# WM Keyboard feature inventory

Built for a comparison table. Three levels: family, feature, capability. A rival
keyboard can match a family and miss every capability under it, which is the whole
point of the nesting.

`RARE` marks something few or no mainstream keyboards ship. `uncommon` marks
something only some of them do. Unmarked means Gboard or SwiftKey has it too.

## Size of the surface

| Area | Families | Features | Capabilities |
|---|---|---|---|
| Typing core: prediction, autocorrect, learning, spell check | 9 | 50 | 205 |
| Input behaviour: glide, gestures, cursor, editing, keys | 11 | 80 | 219 |
| Languages, scripts, layouts, transliteration | 11 | 64 | 213 |
| Themes and appearance | 14 | 73 | 183 |
| Emoji, GIFs, stickers, kaomoji | 16 | 88 | 94 |
| Toolbar and the tool set | 10 | 85 | 311 |
| Clipboard, snippets, text expansion | 7 | 37 | 191 |
| AI, voice, handwriting, scanning | 11 | 70 | 162 |
| Privacy, backup, storage, statistics | 14 | 69 | 173 |
| Accessibility, form factors, platform integration | 13 | 61 | 111 |
| Extensibility: addons, plugins, imports, formats | 5 | 35 | 164 |
| Modes, rows, field adaptation, runtime | 12 | 97 | 203 |
| **Total** | **133** | **807** | **2229** |

## Typing core: prediction, autocorrect, learning, spell check

- **Suggestion engine** — One SuggestionEngine merges completions, corrections, splits, contacts and predictions per keystroke
  - Trie-guided fuzzy beam search `RARE` — Corrections and completions from one best-first walk, not generate-and-test
    - Admissible best-first bound — State bound = sourceWeight + ln(1+maxSubtree) - cost; pruning never loses a top-K word
    - Walks the trie, not the alphabet — Substitution/insertion candidates come from real edge labels, so any script works
    - Log-space scoring — score = sourceLogWeight + ln(1+frequency) - editCost; max-merge across sources
    - Ranks 32 deep for the strip, 8 for autocorrect — Deep ranks feed context boosts; silent replacement still judges only the top 8
    - Heaviest source first — Sources sorted by root bound so early emissions raise the floor and cut later walks
    - Pooled per-thread workspace — Parallel primitive arrays plus index heap; no per-keystroke allocation beyond emitted words
    - Cached ranked walk — Keyed on word, generation, lexicon mutations, K and tap list; strip and commit share one walk
    - Runaway backstop — 4096 expansions per source maximum
  - Weighted candidate sources `uncommon` — Seven merged sources with explicit multipliers over dictionary frequency
    - Personal lexicon x500
    - Contact names x3,000, contact emails flat 4,000 — Emails need a 2-character prefix so one letter doesn't dump the address book
    - App-label names x400 — Below contacts because app labels contain ordinary words like Files and Clock
    - Imported custom list x100, secondary language x40 — Secondary weight further scaled 0.5x-2x by measured use
    - Bundled English as a secondary at half frequency — Covers the native-language plus English pairing
  - Next-word prediction — Empty composing buffer predicts followers from five ordered stores
    - Trigram context beats bigram — Learned (prev2, prev1) followers consulted before followers of prev1 alone
    - Contact name chaining — "Wasi" offers "Mollik" from the indexed name
    - Corpus pack then bundled seed pairs — 827 bundled English pairs cold-start a fresh install
    - Learned skip-gram followers (#195) — What has followed the word two back one word later, then the word three back two words later; personal, so above the corpus, gappy, so below every direct follower
    - Skip-gram rescue on an unknown previous word — Treats an OOV prev as transparent and backfills from the word before it
    - Sentence-start sentinel — U+0001 pseudo-word learned as context only; never offered, never a follower
  - Numbers from the letter keys `RARE` — A word typed entirely on digit-hinted keys also offers the number those hints spell (#181); off by default
    - Read off the pressed keys, not the letters — AZERTY's 1 is on a, Dvorak's on the apostrophe, German has none; a number row that is showing has already stripped the hints, so it is quiet then
    - Last slot, never the primary — Never what a space commits and never autocorrected to; two letters at least, so a lone I is not an 8
    - Grouped like the number chip — Five to fifteen digits, no leading zero, under the chip's grouping style, when that chip is on
  - Next-letter distribution `uncommon` — nextLetterWeights feeds autopilot
    - Weighted across three sources — Dictionary x1, lexicon x500, custom list x100; 24 completions scanned per source
    - Boundary-tap remap at pointer-down — Distance divided by (1 + strength x bias); capped reach; the touch is never consumed
    - Letters layer only, off by default — Skipped for transliterating composers where a Latin nudge is wrong
  - Case matching — Typed capitalization applied to the suggestion
    - All-caps typed gives an all-caps suggestion
    - Leading capital preserved
    - Emails committed verbatim — A candidate containing @ skips case matching so the address isn't corrupted
- **Autocorrect** — Silent replacement on space/enter, gated by a likelihood ratio
  - Confidence gate `uncommon` — Top candidate must outscore the runner-up by a user-set factor
    - Slider 1.5-10, default 4 — Reads directly as a likelihood ratio between the top two candidates
    - Two-source agreement bypasses the gate — Dictionary and personal lexicon independently naming the same word is confidence enough
    - Synthetic solo runner-up floor — An unopposed weak candidate must clear a fixed floor rather than fire for lack of rivals
  - Adaptive confidence `RARE` — Gate scaled by the measured fired/reverted ratio
    - Target revert rate 3%, multiplier clamped 0.85x-2.5x
    - Needs 20 fired corrections before it says anything
    - Halving counters at 200 — An exponential moving window with no timestamps
  - Typing-rhythm gating `RARE` — Mean inter-key gap of the word scales the gate
    - 150ms burst corrects eagerly, 450ms deliberate demands near-certainty
    - Gaps over 2s are thought, not rhythm, and are dropped
    - Needs 2 gaps; strength slider 0 (default) to 1, plus or minus 50% at full
  - Words it never rewrites — Six hard exclusions before any candidate is considered
    - Anything known — Bundled, downloaded, imported, secondary-language or learned
    - Contact names and app names
    - Under 3 characters
    - All-caps words — Acronyms and shouting; user toggle, on by default
    - Anything with two or more digits
    - Blacklisted or offensive words as targets
  - Edit model `uncommon` — Six edit types priced as negative logs of multiplicative weights
    - Substitution, insertion, deletion, transposition — Adjacent and far variants for substitution and insertion
    - Doubled-character deletion is the cheapest edit — "helllo" from key auto-repeat costs the same as a transposition
    - Missed-doubling insertion priced as adjacent — "aple" to "apple"; self-adjacency isn't in the proximity maps
    - Two edits allowed at length 5+ — Budget cap 2.0 nats plus a 2.0 surcharge so a 2-edit fix never outbids a 1-edit one
    - Completion after an edit costs per character — Stops "skiml" resolving to "skills" over "skill"
    - Only classic one-edit shapes may fire silently — Edited-then-completed words are neither a target nor a blocking runner-up
  - Layout-aware key proximity `uncommon` — Adjacency derived from the grid the layout actually draws
    - Derived, not hand-tabled — A custom or rearranged layout gets correct neighbours for free
    - Row-above and row-below straddle — i-1 to i+1 in adjacent rows covers a half-key-staggered phone grid
    - Number row stitched on when shown — Prices a number-row slip as an adjacent substitution
    - proximityRows override — For split or staggered grids whose rows share no column origin
  - Continuous touch model `RARE` — Where the finger landed, not just which key won the hit test
    - Per-key 2D Gaussian in key-width units — Sigma 0.5 key widths; independent of density, size and orientation
    - Off-center taps make even an exact match cost something — Capped at 1.0 nat, which is what lets a neighbour's word win
    - Falls back to discrete adjacency — Hardware keys, pasted text and re-armed words carry no tap positions
  - Missing-space correction `uncommon` — Splits a run into two known words when no single word explains it
    - "kortehobe" becomes "korte hobe" — Scored by the rarer half; halves at least 2 letters, typed run at least 5
    - Fat-fingered spacebar reading — A stray spacebar-adjacent letter between two words is dropped, at a discount
    - Spacebar-adjacent set follows the layout — Defaults to the QWERTY family's cvbnm
  - Digit-slip correction `RARE` — One digit inside a word read as a number-row miss
    - Same-length single-digit swap only — "as3" becomes "ase"; "room3" is never shortened to "room"
    - Only on the path that buffers number-row digits — The standalone spell checker never rewrites genuine alphanumerics
  - Learns from your own fixes `RARE` — A typo you repair by hand teaches the pair and the slip behind it
    - Taught pairs — Fixed twice, autocorrect makes the fix for you; fixed once, it offers it and never applies a different guess over it
    - A real word swapped for another — "form" for "from" needs three fixes and the bigram context on its side
    - Slip habits per layout — Each fix aligned letter by letter (3 for e, b for space, a doubled letter missed) discounts that edit in the fuzzy walk, floored at the adjacent-slip tier, one-sided, after eight sightings
    - Tap model — Where your finger lands per key, learned from every settled word and every kept correction; the glide hand model's class with its own file
    - Three ways a fix is seen — Backspace-and-retype, tapping into a word and editing in place, selecting a word and typing over it; only the keyboard's own edits are followed and the word is checked against the field once, on leaving it
    - Autocorrect's wrong fix, fixed by hand — The pair starts from the original typo and the wrong correction is graded as rejected
    - Learned corrections screen — Every taught pair with its count, the slips noticed, per-pair delete, forget all; both stores ride the Dictionary export section
  - Undo chip `uncommon` — The word you typed, offered back on the strip after autocorrect rewrote it
    - Outlives backspace — Backspace reaches a correction for one keystroke; the chip stands until the sentence ends, and finds the word behind the caret rather than assuming it is still there
    - Gated on how obvious the correction was — Certainty (margin over the confidence gate, or two-source agreement) times how little it moved the word (edit cost and word length); a split correction always qualifies
    - Configurable bar — Toggle plus a 0–100% slider; 50% ships
    - Between words only — The tap edits committed text behind the caret, so it waits for an empty composing buffer
    - Counts as a full rejection — Same path as a backspace revert: the pair is retired and the typed word is noted towards the lexicon
    - Refuses an ambiguous target — The corrected word must stand as a whole word exactly once in the 96-character lookbehind, and the caret must not have gone back through it
  - Revert memory `uncommon` — Autocorrect remembers its own mistakes, per pair and in aggregate
    - Backspace restores the typed word — Also counts double towards learning it, immediately: the user said so directly, so there is nothing left to settle
    - Exact pair blocked for the run of typing — 20 further verdicts or the next field, whichever comes first; other corrections of the same typed word stay live
    - Second persisted revert blocks the pair outright — One revert costs a x0.25 handicap and loses shortcut privileges
    - Deliberate and indirect undos weigh differently — Only a backspace on the correction earns the in-process block; a verdict read back off the settled field does not
    - An indirect undo of a non-word is discarded — The reproduced-typo case: the user fixes a typo by hand, never having seen it was already fixed, and slips again. A personal word reaches the lexicon after its three sightings and its undos then count in full
    - Retired pairs come back on probation — 40 quiet saves and the pair reaches the offer chip again, never the silent rewrite; 3 accepts make it ordinary
    - Four memory levels `RARE` — Off keeps no pair memory, Light never retires a pair, Normal is the shipped balance, Strict retires on the first undo however it was read
    - Penalties age out — A pair untouched for 180 saves loses a count; 500-pair cap
    - Stored outside the lexicon — A rejection persists even with learning off or in incognito
- **Personal learning** — On-device lexicon of words, bigrams, trigrams and 1-skip and 2-skip bigrams (named by words skipped); nothing leaves the device
  - Graded reinforcement `RARE` — How deliberately a word was typed decides how hard it teaches
    - Tapped suggestion counts double
    - Typed and committed counts once
    - Autocorrected word earns nothing — Only the word pair around it is learned
    - Manually added word starts at one use — Marked as added by hand instead of boosted (#164): shielded from autocorrect at any learn-after threshold, evicted last, and it earns weight by being typed like any other word; the row reads "You added this word · Seen N times" (#165)
  - Store shape and bounds `uncommon` — JSON snapshot in app-private storage
    - 10,000 words, evicting to 9,000 — 10% hysteresis so compaction doesn't churn on every save
    - 5,000 bigram heads, 2,000 trigram contexts, 2,000 1-skip and 1,000 2-skip bigram heads, 32 followers each
    - Exponential decay at compaction — count x 2^(-age/64 save-generations); user-added words evicted last
    - Dirty-flag save on dismissal — A dismissal with nothing new re-encodes nothing
    - Word length 32, count capped at 1,000,000
  - Word-key normalization `RARE` — One spelling per word across every store
    - Lowercase plus NFC — Bengali precomposed U+09DF vs decomposed nukta form would otherwise be two words
    - Applied at the store boundary, not the producer — Also covers pasted text and text typed on another keyboard
  - Per-word language tag `RARE` — A learned word remembers the language it was typed under
    - Cross-language damp x3 — A learned-only word tagged for another language is handicapped, never banned
    - Damp is relative to the detected field language — In a Banglish field the English-tagged habits get damped instead
    - Untagged words belong to every language — Legacy files and settings-app additions
  - Personal dictionary screen — Learned words listed with seen-counts
    - Delete a word, or add one by hand
    - Version bump makes the IME reload — Stops the in-memory copy clobbering an edit made in settings
  - Android personal dictionary interop `uncommon` — Two independent opt-ins against the platform UserDictionary provider
    - Mirror learned words out — So other keyboards and spell checkers know them; a session dedupe set avoids duplicate rows
    - Expand shortcuts stored there — An entry with a shortcut ("omw" to "on my way") offers the phrase as the top chip
    - Import from Android's dictionary — Personal dictionary screen lists the platform words missing here as a checklist; added by hand, capitals kept, multi-word rows split (#174)
    - Export to Android's dictionary — Checklist of personal-dictionary words the platform lacks, most used first; counts only rows the provider accepted; needs WM Keyboard to be the current keyboard (#174)
  - Learning gates — Three conditions must all hold before anything is remembered
    - Learn-from-typing setting
    - Not incognito, when incognito is set to pause learning
    - Field allows typing intelligence — Password and secure fields never teach
  - Only a word is learned unasked `RARE` — WordContext.isLearnableWord gates learnWord, PendingLearn.sight, the add chip and the held-menu Add (#185): letters and digits with at least one letter, single interior apostrophe/hyphen/ZWJ/ZWNJ, nothing else; `manager"` never reaches the store or the mirror. addWord (dialog, card, chip yes) is not gated, and UserLexicon.load drops pre-gate junk once, keeping hand-added words
  - Settle before learning — Nothing reaches the dictionary while the text is still moving
    - Every committed word queues — 500-word buffer, one field, memory only, never written out
    - Counted at the flush points — Keyboard closed, message sent, field cleared, another field, buffer full
    - What the keyboard deletes or writes over is dropped — Backspacing over the word, a delete swipe through it, re-picking a swipe, a fix typed on top of it; a glide that read the wrong word never counts (#160)
    - The caret alone decides nothing — A caret parked on a word, or walked through it by a spacebar swipe, leaves it waiting; it settles with the rest if nothing is done to it (#159)
    - The words it jumped over settle instead — Going back to fix one line says nothing about the rest, so a proofreading pass counts the text it left alone rather than discarding the session
    - A dropped word is remembered for pairing — The word committed in its place, within a slip's distance, carries it as a suspected fix; confirmed against the field at the flush before anything is taught
    - Known words need one settled use, unknown ones three — The unknown count is the "Remember a new word after" setting
    - Deleting a word drops its queued copy — Otherwise the flush writes back what the user just removed
    - Add-by-hand and the Add chip skip the queue — The user answered directly instead of by leaving text alone
    - An added word is not counted twice — The commit that finishes the word just added by hand adds nothing on top of it
    - One count per word per place — The same word rewritten in place is one use, not one per pass
  - Per-app recent-word overlay `uncommon` — Words recently typed in this app get a ln(1.3) ranking edge
- **Context ranking** `uncommon` — Layered n-gram evidence over the walk's frequency order
  - In-strip context boost `uncommon` — Bounded log-space bonus on candidates the context knows
    - Capped at ln(4) — A habit may re-rank the strip, never bury a frequent exact match
    - Trigram counts weighted double over bigrams
    - Corpus pack counts divided by 50 — One personal use is worth about 50 corpus sightings
    - Bundled seed pairs at ln(1.5) — English modes only
  - NgramReranker `RARE` — Interpolated rescorer over the top 8 candidates, on-device only
    - Base is the engine's rank, not raw frequency — Preserves edit costs and touch likelihood already encoded in the incoming order
    - Nine weighted, capped terms — User trigram/bigram/two skip-grams, pack trigram/bigram, seed bigram, two OOV backoff terms, plus recency
    - Stored 1-skip bigram, always consulted (#195) — The word two back vouches across any middle word; pools what the trigram splits, still speaks when the middle word is unknown; lifts one rank alone, never two
    - Stored 2-skip bigram (#195) — The word three back vouches across two middle words ("gotten so that you've"); weaker, lifts one rank alone only once seen a dozen times
    - Returns null with no evidence — A reorder can only ever be evidence-driven
    - Skip-gram backoff behind an OOV previous word — Weaker than the direct bigram it stands in for
    - Never read by autocorrect — shouldAutocorrect reads the raw walk ranking, so a rerank can't become a silent replacement
  - Register priors `RARE` — Chat-speak ranked by where you're typing
    - 147-word informal set — Initialisms, contracted spellings, interjections
    - Casual +ln(1.5), formal -ln(2.5) — Misranking "lol" up in an email costs more than missing it in a chat
    - Ranking only, off by default — Never gates what commits; the next-word path reorders instead of scoring
  - Revision advisor `RARE` — The word after sometimes proves the word before wrong
    - 8 confusable sets — their/there/they're, your/you're, its/it's, whose/who's, were/we're/where, then/than, lose/loose, affect/effect
    - Chip only, never rewrites committed text
    - 8x dominance within a single source — User and corpus counts never mixed; minimum 3 personal or 25 corpus sightings
  - Join chip `uncommon` — "some" plus "thing" offers "something" when the joined word clearly wins
    - Chip only — It would rewrite text already committed to the field
    - Joined word needs frequency 50 and a 1.25x lead over the rarer part
    - Max joined length 24, letters only
  - Sentence-aware context extraction `uncommon` — WordContext derives prev1 and prev2 from the field text itself
    - Sentence enders break the chain — "Hello. " yields a sentence-start sentinel, not "hello"
    - Combining marks count as word characters — Otherwise Bengali words ending in a vowel sign read as ending early
    - Trigram context degrades to bigram silently — prev2 is null across any boundary rather than guessed
- **Dictionaries and binary formats** `uncommon` — Two custom on-disk formats, both memory-mapped and read zero-copy
  - .wmdict v3 packed trie `RARE` — 5.9 bytes per node, down from 18.1 in v1
    - Memory-mapped, never parsed — Load time is one mmap call; resident memory is evictable page cache
    - Edge-child array eliminated — Breadth-first numbering makes the child of edge e always node e+1
    - Symbol-table byte labels — 1-byte labels at up to 256 distinct code units; u16 otherwise, for Hangul and Japanese
    - Child counts plus checkpoints every 32 nodes — childStart reconstructed by adding bytes already in the cache line
    - 16-bit minifloat frequencies — Exact below 2048 and monotone, so subtree bounds stay exact and pruning is unchanged
    - Header-only word count read — UI can show a word count without mapping the file
  - .wmng v1 n-gram pack `RARE` — Corpus bigrams and trigrams in one file, 1.7MB where the old shape was 17.4MB
    - Followers are u24 word ids into a shared vocabulary
    - Ids are ranks in UTF-8 byte order — A follower run sorted by id is also alphabetical, so lookups binary-search by string
    - Nine 4-byte-aligned sections with padded tails — u24 reads as one getInt shift, u48 as one getLong shift
    - Three cached head slots per instance — Two bigram heads and one trigram context is exactly what a keystroke needs
  - Bundled lists — Compiled at build time by the :tools:dictc host tool
    - English 17,217 words, Bengali 20,645 words
    - Compiler shares the app's own trie and codec sources — The format cannot drift between writer and reader
    - Extracted to device-protected storage — One copy serves a normal run and direct boot; re-inflated on app update
    - Bengali list loads only when Bengali is enabled
  - Downloadable wordlists `RARE` — 333 catalog entries covering 331 languages
    - Four size tiers — 50k, 150k, 300k or all most-frequent words
    - Transfer aborts at the cap — Lists are count-descending, so Thai's 41MB file costs a few MB
    - 14 romanized transliteration lists — Banglish, Hinglish, romanized Tamil, Telugu, Urdu and others as first-class languages
    - Compiled to .wmdict on device — The gz never touches disk; .part plus atomic rename means presence equals valid
    - Frequency floor 2, word length cap 48 — Below the floor is subtitle-scrape noise
    - Free-space check before starting — About 64 bytes per word plus an 8MB margin
    - Per-variant source tracking — Portuguese Europe vs Brazil: only the matching row reads as downloaded
    - Stale-format sweep at startup — An unreadable .wmdict is deleted and offered for download again
  - Downloadable n-gram packs `RARE` — 3 catalogued languages: English, Bengali, romanized Bengali
    - Caps of 150,000 bigrams and 75,000 trigrams
    - Silent automatic fetch plus an explicit retry — A failure is remembered for the process rather than retried each settings emission
    - Legacy two-file packs deleted eagerly — About 17MB per language of a format nothing reads
  - User-imported word lists `uncommon` — Any language, several lists stacking per language
    - word<space>frequency, comments and junk lines skipped — Most lists found in the wild import as-is
    - Imported from a file picker or a URL — 32MB ceiling either way
    - Additive to the bundled list, not a replacement
    - A file that parses to zero words is deleted again — Picking a PDF fails visibly instead of contributing nothing
    - Legacy folder migration — ENGLISH, BANGLA, FRENCH folders renamed to language ids, merging without clobbering
  - Three trie implementations behind one interface `uncommon` — Mutable node trie, heap-packed CSR trie, mapped trie
    - WordSource and TrieWalker split — The walker gives node-level access so fuzzy search steers its own traversal
    - One shared branch-and-bound completer — TrieCompleter replaces three parallel copies of the same loop
    - CompositeWordSource union — Downloaded plus imported lists merged, keeping the highest frequency per word
- **Multi-language ranking** `RARE` — Bilingual typing without switching layouts
  - Secondary suggestion dictionaries `RARE` — Per primary language, consulted alongside it
    - A word valid in a secondary is never autocorrected away
    - Tagged with a language id so its share adapts to real use
    - English as a secondary rides at half its real frequency — It carries real frequencies unlike the freq-1 imported lists
  - Language mix confidence `RARE` — Learns which language of the mix you actually lean on
    - Per-commit geometric decay of 0.999 — Roughly the last thousand words stay in play
    - Square-root share curve, 0.5x to 2.0x — Moderate use isn't punished as hard as the raw share would
    - Neutral 1.0 until trained — An untrained keyboard behaves exactly as flat weighting did
    - Languages faded to noise are pruned from the tally
  - Per-field language detection `RARE` — Which language this particular field is being written in
    - Starts from the app's habit — A per-app tally of which language the words typed there belong to seeds each field at up to one and a half words of evidence, so a chat app leans Banglish and mail leans English before a word is typed; one real word outweighs it, and a toggle turns it off
    - Per-word decay of 0.7 — The last three words are in charge; code-switching swings it back in two or three
    - Seeded from the words already in the field on focus — Oldest first, so the words nearest the caret dominate
    - Three calibrated strengths — Gentle 1.4, balanced 2.6, aggressive 4.0 nats of maximum swing per language
    - Ambiguous words move the mix nowhere — A word valid in several languages credits all of them at once
    - Evidence ramp — One classified word moves it halfway, three make it certain; unclassified words only decay
    - Never persisted — Thrown away when the field is left
- **Suggestion filtering** `uncommon` — Two independent suppression lists over every suggest path
  - User blacklist `uncommon` — Words never offered and never used as an autocorrect target
    - Case-insensitive, stored lowercased
    - Suppresses suggesting, not typing — The word can still be typed and committed verbatim
    - Applies to strip, next-word, glide results and split halves
    - Added by hand in a settings dialog, or by holding a chip on the strip — "Never suggest", with "Suggest again" to undo
    - Per-language lists (#136) — blacklistByLanguage, one string-set pref per language id; the engine sees global + the language being typed, re-pointed on every layout switch
    - "Blocked from the keyboard" scope — blacklistScope decides where the hold menu's Never suggest lands (all languages by default, or the current one); the editor asks per word; Suggest again clears every list
- **Held-word menu and word card** `uncommon` — Press and hold a suggestion for a menu about it (#99)
  - Contextual items with icons — Never suggest / Suggest again; Add "typed" while the word being typed is unlearned; Delete for a word the keyboard can forget; Edit always
  - Add pins the capitals — The typed spelling goes in at full strength and no later vote changes it (#100)
  - Delete reaches every mutable store — Personal dictionary, waiting room, rank adjustments, Android's dictionary, and the user's imported word lists, whose files are rewritten without the word (#190); a word still in a downloaded list is blacklisted instead
    - "Delete edits imported lists" switch — Off leaves imported lists as imported and blacklists the word the old way
  - Word card — In-window modal over the keyboard: every source the word was found in, its "#N of M" place in each list, the word's spelling, its rank controls, and the same actions (#138)
  - Respell from the card — "Change" hands the keys to a bar in the strip's row (the card covers the board, and an IME cannot raise a field for itself); the draft starts from the word, Enter or ✓ applies it, back or ✕ leaves it, and nothing typed there reaches the app behind (#138)
    - The draft edits like a field (#204) — its own caret and selection: tap/drag/hold on the bar, spacebar scrub (shift or selection mode extends), hardware arrows/Home/End, shift re-cases a selection, forward delete, and a glide types at the caret with no space and nothing learned; the scrub used to walk the app's caret behind the keyboard
    - A respelling carries the count, language tag and word pairs across, moves the rank adjustment, and drops the swipe shapes, waiting-room sightings and Android's copy of the old spelling; a case-only respelling pins the spelling instead; a word the lexicon does not have is added at the new spelling
  - Keep these capitals — The dictionary screen's pin switch, on the card, for a word the keyboard has learned (#138)
  - Two rank mechanisms, both shown by default and chosen in settings — Learned weight (the lexicon count, decade stepper) or a per-word −10..+10 offset applied in the engine to every source, glide and next-word included; never to autocorrect
  - Which menu items show is a chip setting — Edit cannot be hidden, since the card carries the rest
  - Synonyms (#321) — "Synonyms for "word"" on English Latin-letter words opens a sheet of synonyms grouped by part of speech and meaning; a tap goes through the strip's own pick path (replaces the typed word, the caret word or a swipe's word, wears its capitals, is learned like a pick); stored menu sets from before it read it as on (`~synonyms` marker)
    - Ordered, switchable sources, first with synonyms wins, a source that is down or empty falls through — Vocabulary packs (offline), Datamuse `ml=` filtered to `syn` tags, Wiktionary via kaikki, Free Dictionary API, Datamuse similar words (flagged as such); `SynonymLookup` in `:core:tools` `core.thesaurus`, 32-word answer cache, bypasses data saver, own `NetSource.SYNONYMS`, Datamuse overridable on F-Droid
  - Pinned capitals — A word added or respelled by hand keeps its case against the vote; "Keep these capitals" switch on the dictionary screen; a tapped chip no longer teaches an auto-capital (#100)
  - Offensive-word filter — 60-word bundled English list, on by default
    - Never suggested, never an autocorrect target — So a neutral typo is never corrected into a slur
- **Word-boundary fixes** — Commit-time rewrites that sit outside the correction engine
  - Apostrophe restoration — 67-entry contraction table applied before autocorrect
    - Outranks autocorrect — "dont" is a known contraction slip, not a typo for "font"
    - Excludes forms that are real words — its, were, well, ill, shed and lets are left alone
    - Typed capitalization preserved — Dont to Don't, ARENT to AREN'T; im to I'm stays capitalized
    - English modes only, never on a fragment glued to an existing word
  - Bengali fixed-spelling map `RARE` — 14,283 mapped spellings across two bundled TSVs
    - 2,369 English loanwords — Convention-spelled forms the phonetic rules would never produce
    - 11,914 romanized chat spellings — Vowel-dropped chat forms; no fold recovers a vowel that was never typed
    - Curated list outranks the generated one — Load order decides which form leads when the two disagree
    - Shows in the composing preview, not just at commit — So what the preview shows is what a space would commit
    - Per-language opt-out — For someone who wants the letter-for-letter reading instead
  - Bengali phonetic sibling ranking `RARE` — Dictionary siblings outrank the literal transliteration only at 2x frequency
    - A near-tie sibling never silently replaces what the preview showed
    - A literal that isn't a dictionary word always yields to siblings
- **System spell checker** `RARE` — Keyboard-independent SpellCheckerService backed by the bundled Harper engine
  - Sentence-level checking `RARE` — Lints carry offsets and lengths so hosts underline the exact span
    - Spans can cover several words — A their/they're fix is a sentence-level lint, not a word-level one
    - Per-word API implemented as a fallback — Only lints spanning the whole handed-over word are meaningful there
    - Insertions rewritten as whole-span replacements — Deletions return nothing: an empty correction row can't be read or chosen
  - Contact awareness `RARE` — Loads contacts in its own process, independent of the active IME
    - A contact name or known address is never flagged
    - Close contact names lead the correction menu — Prefix completions plus one Norvig edit, kept in source capitalization
  - Squiggle-only mode `RARE` — Flags the typo but suppresses the correction popup
    - Uses the DONT_SHOW_UI_FOR_SUGGESTIONS result attribute — Android 12+ only; the flag is meaningless below that
  - Warm-up on the first settings value `uncommon` — Harper's rule set takes about 100ms to build, so the first underline isn't late
  - Dialect mirrored through a collected flow `uncommon` — A DataStore read per binder call would cost more than the check itself

**Conditions and gating**

| Feature | Needs |
|---|---|
| System spell checker (HarperSpellCheckerService) | full flavour only — lite ships no libharper_jni.so, and the service plus its manifest and spellchecker.xml live in src/full |
| Contact names and contact-email completion in the strip | needs the READ_CONTACTS grant plus the per-feature setting; both off by default |
| Contact-aware spell checking (names never flagged, name corrections lead the menu) | full flavour plus READ_CONTACTS grant plus the contactSuggestions setting |
| Downloadable wordlists (333 entries, 331 languages) | needs network; fetched from the public wmkeyboard-data GitHub repo, no API key |
| Downloadable n-gram packs (English, Bengali, romanized Bengali) | needs network; fetched silently from the same repo |
| Importing a custom word list from a URL | needs network; the file-picker import path does not |
| Mirroring learned words into Android's personal dictionary | writes the platform UserDictionary provider, which only permits the current IME or a spell checker to write |
| Personal-dictionary shortcut expansion | reads the platform UserDictionary SHORTCUT column; off by default, silently empty on OEM builds that hide the provider |
| Squiggle-only spell-check mode | Android 12+ (API 31); the flag is ignored below that |
| App-name suggestions | no permission needed — reads installed app labels; off by default |
| Personal stores under direct boot | UserLexicon, CorrectionStats and LanguageMixConfidence take a nullable file and run memory-only when credential-encrypted storage is unavailable |

## Input behaviour: glide, gestures, cursor, editing, keys

- **Glide typing** — Trie-lattice beam decoder; works in any language whose word list covers the layout, not just English
  - Best-first lattice decoder over the dictionary trie `RARE` — GlideBeam: no flat word-list scan, candidates come from whatever tries are loaded (bundled, imported, personal, any script)
    - Arc-length resampling — Stroke resampled to equally-spaced samples so travel between letters is measured in steps, not pixels
    - Two-term placement cost — Distance-to-key plus disagreement between finger travel and key distance — stops 'hello' decoding as 'ho'
    - Shape channel rescore — Top candidates re-scored on stroke shape with size and position normalised out; weight 45.0
    - Loop-only double letters — 'good' vs 'god': an unlooped doubling pays a charge; a pause or a wiggle says a letter is in the word, never that it is there twice (#337)
    - Loop-aware double letters — A small circle drawn on a key is Swype's mark for the letter twice: found on a fine resample by path-to-extent ratio and enclosed-area roundness, its arc collapsed out of the travel term, the doubling's charge waived, and every word that leaves it undoubled charged for it
    - Unclaimed pauses charged — A finished word pays, once per pause, for each pause none of its letters sits on; only the key the pause happened on claims it, never its neighbour, which is what separates 'write' from 'wrote' on one row. A wiggle, when on, files the same event
    - Exclusive loops — A loop credits only the key nearest its centre, and the samples inside it belong to that key alone, so the keys its edge passes over cannot enter the word
    - Admissible bound pruning — logWeight + ln(1+maxSubtree) - shapeWeight*minCol; anchor radius 1.6 and near radius 1.5 key widths
    - 17 injectable tuning weights — sigma, maxPointCost, gapWeight, gapWindow, shapeWeight, repeatCost, unloopedRepeat, unclaimedDwell, loopExtent, loopMinArc, wiggleExtent, wiggleWeight, unclaimedLoop, shapeChannel, anchorRadius, nearRadius, vocabularyRank — swept by a test harness
  - Per-language glide readiness gate `RARE` — Glide enables itself only where it can decode honestly; measured, not flagged
    - Coverage measurement — Top 1500 words per word source; grid must be able to spell 90% of them
    - Converting-layout block — Off on Avro, Hangul, Vietnamese and every CJK conversion layout — a stroke there spells a reading, not a word
    - Re-checked on dictionary download — Source epoch bumps re-ask the coverage question
  - Bengali phonetic glide `RARE` — Swipe roman letters on the Avro grid, get Bengali words back via RomanizedIndex
  - Multi-word glide across the spacebar `uncommon` — One unbroken stroke crossing space commits several words; spacebar points anchor no letter and are dropped
    - Sequential context — Each segment decoded after the previous one is committed and learned, so word 2 sees word 1 as context
    - Toggleable — Off makes a spacebar-crossing stroke decode as one word
  - Capitalize by gliding over Shift `uncommon` — Drawing through the Shift key mid-stroke capitalizes the word, twice shouts it; the key's points are dropped from the word the way the spacebar's are, so the detour spells nothing
    - The one capital a swipe can teach — A capital the decoder chose is never case evidence; a capital the finger drew is
  - Readings kept for proofreading — The last 500 swiped words in the field keep their stroke's other readings; putting the caret back on one puts them in front of the strip, and taking one counts as a correction of that stroke
  - Manual full search — The newest 24 of those also keep the stroke itself, so "Search all words" on a held strip word decodes it again against every list, past the sandbox and the vocabulary cap; a pick teaches the hand model, the shape and the pair, and an optional strip button — a bare search icon, so the candidates it offers to improve on keep the room — offers it without the hold (#135, #264)
  - Swipe style learning `RARE` — Everything a kept swipe teaches apart from the word itself, behind one switch and one Forget; off freezes it, Forget deletes it without touching learned words
    - Hand adaptation — Kept swipes teach where the finger really lands on each key; later swipes decode against a grid moved to match (KeyOffsets)
    - Keyed by position, not letter — Half-key cells, so layouts with the same geometry share what either learned; a barely-swiped key follows the whole hand's mean
    - Reads a small or large hand as a trend — The slope of the cells' misses against their positions, so a thumb that draws at 85% of the keyboard is followed to the far keys the per-key means alone could not reach; fitted across cells, where each word's own corner cutting cancels
    - Undo un-teaches — Backspacing a swiped word, or replacing it off the strip, retracts exactly what it taught; the replacement teaches instead
    - Learned shapes — A few of the user's own shapes per word, from the glides they keep, for the shape channel to compare a stroke against beside the word's ideal path (GlideShapeStore)
    - Graduated, never taken at commit — The shape rides the word through the learning buffer and lands only when the word settles as a learned word; an undone or replaced glide marks the shape that read it, and a shape rejected more than accepted goes
    - Bounded benefit — A word's learned shape can shorten its shape distance by at most a fixed gain, so a word swiped before gets the benefit of how it is drawn and never a free pass over words that were not
    - Outcome memory — A word taken off the strip over the one a stroke was read as, a picker word that was not the leader, a pick off the deep-retry strip, or a swiped word backspaced straight away, nudges the next decode of that pair (GlideOutcomes)
    - Pairs, not words — "nor over not" says nothing about "nor" against "now"; a pick the other way is counter-evidence, and a pick repays an undo strike
    - Bounded and fading — At most one close-call margin up and under half of one down, so three consistent picks flip a close call and no habit overturns a clear reading; strength fades with use, not time
    - Nothing readable on disk — Salted fingerprints, strengths and logical ages; the salt rotates on Forget; not in the backup
  - Apostrophe in a glide `RARE` — One chosen key (comma, full stop, spacebar or a real apostrophe key) stands for `'` on the glide grid, so "it's" is drawn as i-t-'-s instead of guessed from "its"; off by default
    - Exactly one key — Emitted before every other pass so it takes the claim on `'` off the long-press alternate a layout may hide one behind; two apostrophe keys measurably blur both
    - Spacebar is exclusive — Picking it stands down the multi-word split, since one crossing cannot mean both "word ends" and "apostrophe"
    - Declared spelling when the list has no entry — A stroke through the key rewrites the top reading through the ambiguous contraction table (its → it's, were → we're, lets → let's) that the automatic fix refuses to guess at, keeping the plain spelling next on the strip
    - Never required — The same word drawn straight still decodes, and both `'` and `’` land on the chosen key
  - Possessive flick `RARE` — A short straight swipe from the apostrophe key to `s`, drawn straight after a glide, appends `'s` to that word; on by default once an apostrophe key is chosen (never the spacebar)
    - Detour test — Travel must stay within 1.6× the direct key-to-key distance, so a real word drawn between the same two keys still decodes as the word
    - Takes the glide's own space back — The possessive lands inside it, and backspace still removes stem and ending in one press
    - Learned — The possessive enters the personal dictionary, so the next one is glidable in a single stroke
  - Mid-stroke ambiguity picker `RARE` — Hold still (350 ms by default, 150–1000) while the decode is a close call and the top 2–5 words appear above the fingertip; slide onto one and lift
    - Frozen stroke — The picker's words are the words that commit: nothing after the open feeds the decoder, so a pick is never dropped (#96)
    - Timer-driven — The dwell fires from a timer, not the next touch report, so a finger held genuinely still (which sends no events) still opens it
    - Drift-proof stillness — Measured against where the finger stopped, not the last sample, so slow drift never counts as a hold
    - Sensitivity tiers — Near ties (0.4 nats), Close calls (1.1, default), Any doubt (2.5), Every pause
    - Hold to ask — A confident stroke asks after twice the dwell, so any swipe can be second-guessed without lifting
    - Free to ignore — Lifting off a target commits the decoder's own first choice, outlined so it can be told apart
    - Drag down to cancel — More than a key below the anchor the targets dim and a lift types nothing
    - Chained strokes — A pause on the last word of a spacebar-crossing stroke asks for that word
  - Live preview while swiping — Decoded word drawn over the keys and pushed to the strip at a 40 ms wall-clock cadence (rate-independent of digitizer Hz)
  - Auto-space after a glided word `uncommon` — Keyboard's own space: punctuation typed after takes it back, a space press is spent confirming it
  - One-backspace glide undo — Backspace straight after a swipe removes the whole word plus its auto-space, then re-derives bigram context
  - Shift and caps applied to swipes — CAPS_LOCK uppercases, one-shot shift title-cases the glided word
  - Apostrophe restoration `uncommon` — 'dont' swiped commits as "don't" (English, gated on the auto-apostrophe setting)
  - Customisable comet trail `uncommon` — Head width dp, point lifetime ms, peak opacity — all user sliders
  - Start-sensitivity controls `RARE` — Threshold as a multiple of system touch slop (default 2x)
    - Post-typing cooldown — For 160 ms after a keypress a glide needs up to 2.5x the travel, fading to none across the window; 0 disables
    - Must start near a letter key — A drag beginning off the letter grid is never read as a glide
  - Handwriting instead of glide `RARE` — letterSwipeAction=HANDWRITE turns the same swipe into an ink stroke recognised on the keys
    - Dot window — For 700 ms after a drawn stroke a tap over the letters is captured as another ink mark (i/j dot, t cross) instead of typing
    - Backspace discards ink — Backspace with strokes pending throws the ink away rather than deleting committed text
- **Spacebar gestures** `uncommon` — Two independently-assignable swipe slots plus hold behaviours
  - Short-swipe and long-swipe slots `RARE` — 4 actions each (none / language / cursor / numpad); default Language and Cursor
    - Resolved by hold time, not distance — A drag crossing slop before the long-press delay is 'short'; after it is 'long' — a fast flick travels further than a careful drag
    - Numpad is one-shot — Crossing slop opens the numeric panel once and the rest of the drag goes inert
  - Language ring on the spacebar `uncommon` — 44 dp per layout step, live 5-chip tooltip window centred on the selection
    - Wrap detent — Wrapping past either end costs 2.5x a normal step, so the list parks on the boundary first
    - Two-language toggle rule — With exactly two layouts one run of travel toggles once; only reversing direction switches back
    - Flick counts immediately — The movement that crossed the slop already advances one language
    - A flick moves one language — Further same-way steps wait 200 ms after the last, with banked travel capped at one step, so a fast swipe cannot skip the middle of a 3+ ring; a reversal is ungated
    - Switch echo — The preview lingers 700 ms after a swipe commits, held above the key grid so it survives the layout swap; a flick used to end before the popup drew
  - Hold-to-open language picker `RARE` — 250 ms hold (or the long-press delay, whichever is shorter) opens a chooser without any swipe
    - Only when the hold is free — Skipped when the long-swipe slot names cursor or numpad, since that slot is the setting for what a hold does
    - Two shapes — Inline preview for up to 4 layouts, scrollable tappable list beyond that
    - Hold-drag walk — Vertical drag steps the highlighted row; release commits, a still hold leaves it up for tapping
    - Carousel picker `RARE` — Language picker shape turns the list sideways: a chip strip centred on the current layout, the hold-drag walking it left and right by the swipe's own 44 dp step, the strip re-centring on the highlight; chips tappable, Other keyboards… a glyph past the divider (#150)
    - Never types a space — Release with the picker or preview up commits a layout instead
  - Spacebar long-press keys `RARE` — Characters typed into one setting become the spacebar's own alternates popup, on every layer
    - Claims the hold outright — Authored keys beat the language picker and the space repeat, because a hold cannot mean two things
    - Editor path too — The layout editor now offers the alternates fields on a space key, so a layout can carry its own set
    - Corner hint says so — The first key is drawn in the spacebar's corner, which is what tells you the picker moved
  - Cursor slide — 16 dp of horizontal drag per character; commits the composing buffer first and marks a scrub window
  - 2-D cursor touchpad `uncommon` — Vertical drag also steps the caret by lines; claims the down direction from swipe-to-hide
  - Swipe down to hide `uncommon` — Downward drag past 40 dp, steeper than wide, dismisses the keyboard; separate from the toolbar's own swipe-down
  - Key flicks `RARE` — Short (0.5–2 key heights), straight (detour ≤1.4×), quick (≤250 ms) flicks inside a 30° cone, judged at the lift by keyFlick in two places (inside the glide lift, and a loop of its own on the Initial pass for strokes glide never claimed). Down types the corner hint (layoutBehavior.hintFlick, #178); up types the shifted form, shiftLabel or the letter's capital, without touching shift (layoutBehavior.capitalFlick). Both off by default. An up-flick off a key carrying an octopus word is left to the octopus
  - 🌐 typing guard `RARE` — layoutBehavior.globeTypingGuardMs, 0–1000 ms in 50 ms steps, default 0 (off): a 🌐 tap within the window after a key that typed into the field (Text, Keyman, Space, Delete, ⌦, Enter, Newline) is dropped at the top of dispatchKey; 🌐 bursts, shift and mode keys do not arm it, and the hold picker is untouched
  - Spacebar label control `uncommon` — Language / layout / both, or a custom string where %s is the live language name
    - Direction arrows — ◀ ▶ drawn around the label only when a slot is set to Language and more than one mode is enabled
- **Backspace behaviour** — Tap, hold-repeat and word-swipe are one state machine on the key
  - Grapheme-correct deletion — 64-character lookback so multi-codepoint emoji go in one press
    - ZWJ and tag sequences — 👨‍👩‍👧, 👍🏽, ☠️ delete whole rather than shedding a piece per press
    - Surrogate pairs — Falls back to a 2-unit delete when no emoji cluster matched
    - Per-language conjunct deletion — Opt-in per language id: Bengali/Devanagari clusters delete as one unit instead of code point by code point
  - Word-swipe delete with acceleration `uncommon` — Drag left past slop: 72 dp for the first word, 56 dp for the next, -6 dp each after, floor 28 dp
    - Reversal re-anchors — Dragging right stops the run and resets the acceleration; it never un-deletes
    - Own haptic toggle — Per-word buzz can be silenced separately from the plain backspace
    - Trailing whitespace goes with the word — Repeated steps chew back like desktop ctrl+backspace
  - Hold-to-repeat — Starts after the long-press delay at its own interval (20–200 ms, default 50)
    - Stops at an empty field — The repeat loop polls canDelete() rather than buzzing against nothing
    - Bypasses the tremor debounce — Repeat ticks go through an un-debounced sink so the rate is not silently capped
    - Separate repeat-buzz toggle — Only the first press buzzes when off; the key sound still plays
  - Revert-on-backspace `uncommon` — One press takes back what the keyboard put in the field
    - Autocorrect — Restores the typed word and counts double towards learning it; the pair that fired is blocked on the spot either way; toggleable
    - Pattern snippet — Always revertible; reads one character past the commit and puts it back verbatim
    - Join and revision chips — Tapped word-join and revision suggestions are undone the same way
  - Context-aware targets `uncommon` — Backspace edits whatever is actually taking keystrokes
    - Panel search queries — Emoji, dictionary, clipboard, media, plugin, AI-instruction, calculator, converter and typing-test boxes each get the press
    - Pending morse sequence — Edits the dot/dash sequence and only falls through to a real delete when empty
    - Composing buffer — Shortens the buffer with the same cluster length the field would have used
    - Dedicated field backspace in emoji search — A second backspace in the search pill edits the real field with its own hold-to-repeat
  - Forward delete key `uncommon` — ⌦ deletes after the caret through the InputConnection (works in WebViews), with its own repeat and its own end-of-text predicate
- **Cursor control and text editing** — Panel, toolbar tools, volume keys and spacebar all reach the caret
  - Text-editing panel — Gboard-style d-pad cluster with a Select toggle; 16 actions
    - Action set — UP/DOWN/LEFT/RIGHT, HOME/END, PAGE_UP/PAGE_DOWN, WORD_LEFT/WORD_RIGHT, SELECT, SELECT_ALL, SELECT_WORD, SELECT_LINE, COPY, PASTE, BACKSPACE
    - Selection mode — With Select on, every move carries shift and extends the selection; word moves become Ctrl+Shift+Arrow
    - Own repeat interval — Arrow and backspace auto-repeat, default 60 ms, user-adjustable
    - Panel layout `RARE` — The pad is a PanelLayoutSpec (issue #63): a grid of Keys with KeyAction.Edit, edited in the key layout editor with its row tools, key sheet and undo; the shipped cluster is BuiltInPanelLayouts.TEXT_EDIT
    - Same geometry as a key layout — Drawn by PanelLayoutGrid with real KeyButtons, so the tall left/right arrows are just a key three rows deep and the middle rows flow around them
    - Alternates on press and hold — Edit keys whose operation does not repeat open the alternates popup; Home and End ship holding to the start and end of the text
    - Repair on read, never reject — The panel repair drops components, shift and chorded keys, clamps widths and spans, and falls back to the shipped grid; an old TextEditLayout preference migrates key for key
  - 14 one-tap cursor tools `RARE` — CursorTools list: left/right, word left/right, up/down, home/end, page up/down, select word, select line, select all, selection mode — placeable on the toolbar
    - Shift extends the selection `RARE` — A shift the user pressed turns every toolbar cursor move into shift+arrow; auto-capitalise's own shift is excluded, and is held off the state while the selection is live
    - Hold to repeat `RARE` — The eight non-idempotent moves repeat on hold at the text-edit interval; one switch for the toolbar, defaulted on
    - Per-tool toolbox opt-in — A second switch, one tool at a time and off by default, since a repeating tool spends the toolbox hold that opens its settings page
    - Drag survives the repeat — Travel past the drag slop stops the repeat and picks the tool up, on either surface
  - Selection mode tool `RARE` — One tap arms it, the next disarms it; while it is on every caret move extends the selection instead of collapsing it
    - Every caret path obeys it — KeyboardUiState.selectingText is read by the panel's arrows, the toolbar's cursor tools, the spacebar cursor swipe, the volume keys and a layout's own arrow keys
    - Press and hold for a temporary mode — Selection mode lasts as long as the finger stays on the tool; the release stops the extending and leaves the selection intact, and drag-to-reorder still wins on travel
    - Double and triple press — Two quick presses select the word at the cursor, three the line, both leaving the mode on; the shift key's own double-tap window, and switchable off
    - Shared with the panel's Select key — Either surface arms it, either one turns it off, and both light up while it is on; the toolbar's mode outlives a panel opening, the panel's does not
  - Trackpad tool (issue #39) — The key area as a relative pointing surface: one finger drags the caret a character per stepXDp sideways and a line per stepYDp vertically, sub-step travel carried between frames (TrackpadAxis), every move a real arrow key through onTextEdit
    - Hold, then drag selects — The long press arms selectionHold through the Selection mode tool's own callback and the release disarms it; the selection stays in the editor
    - The selection-actions bar waits for the lift (#136) — selectionMacroBarVisible is false while selectionHold is on, so the bar never pushes or swaps the toolbar out from under the held finger; it appears once the finger comes up
    - Two and three taps — Select word and select line at the caret (TrackpadTapCounter: window plus a distance test, since a surface is wide); switchable off
    - Two fingers — Drag moves by words (Ctrl+Arrow) at twice the character step; a two-finger tap types a space; a finger arriving or leaving re-anchors the centroid rather than counting as travel
    - Tap and hold modes — Tap toggles the panel; a press and hold on the toolbar tool opens it only while the finger stays (onTrackpadHold, paired like onSelectionHold, released on drag pick-up and on onFinishInputView); a hold over a tapped-open panel is a no-op; not while the toolbox is open (#320), where the panel swap took the grid away and the tool could not be dragged back into it
    - Visual feedback — Tool lit while open; finger trail and crosshair drawn from a plain-array ring buffer the draw lambda alone observes; the idle hint fades through a graphicsLayer read
    - Its own panel layout — BuiltInPanelLayouts.TRACKPAD: the TRACKPAD field over the abc / space / backspace row, editable like the other panels; never full-bleed so the toolbar survives the hold
    - Caret magnifier (discussion #303) — While a drag or a hold-select moves the caret, a bubble over the text shows the caret's line enlarged, caret centred, selection highlighted, edges faded. Keyboard-drawn (an IME cannot read the app's pixels): CaretMagnifierController reads 64 chars each side off the main thread after every onUpdateSelection and cuts to the line (magnifierLine); requestCursorUpdates(IMMEDIATE | MONITOR) only for the drag's length places it over the insertion marker (screen coords via CursorAnchorInfo.matrix), above the line or below near the top of the screen, else just above the keyboard. FLAG_NOT_TOUCHABLE Popup composed only while up. Paired onCaretDrag per CaretDragSource (TRACKPAD, SPACEBAR), stopped on onFinishInputView, released in a finally on both surfaces, rebound to the new connection when the field restarts mid-drag; skipped for keyboard-owned fields. Every field call on one serial background lane, reads coalesced to one in flight plus one pending; one getSurroundingText call on API 31+ (three calls below); a selection over 1,024 chars is never read back (only the free side, selected side tinted); cursor updates filtered to the insertion marker on API 33+, an invisible-region marker ignored, bubble clamped above the keys; password fields drawn as bullets per code point. trackpad.magnifier and textEditing.spaceCursorMagnifier, both default on
    - Nested TrackpadSettings — stepXDp 12, stepYDp 28, holdToOpen, multiTap, haptics, trail, magnifier; one KeyboardSettings slot, flat DataStore keys `trackpad_*`
    - Direct-boot safe, no focus ring, no default leader letter — Only touches the input connection; pointer-only so panelFocusRegions is empty; every letter was taken, T is the toolbox
    - Survives navigation, not a new field — A caret move never cancels it; a genuinely new editor does, while a restart of the same field keeps it
  - Volume keys as cursor `RARE` — Volume down/up move the caret left/right while the keyboard is showing; off by default
    - Media-aware release — Re-checks isMusicActive on every press and hands the keys back to the system while audio plays
    - Free auto-repeat — Holding repeats via Android's own hardware key repeat; both DOWN and UP are swallowed
  - Undo / redo `uncommon` — Sent as Ctrl+Z and Ctrl+Shift+Z, with a Ctrl+Y option for apps that want it; commits the buffer first
  - Composing resume at the caret `uncommon` — Tapping into a finished word re-arms it as the composing region so typing extends it and backspace shortens it
    - Combining-mark aware — Word boundaries account for Bengali/Devanagari/Tamil/Thai vowel signs, Arabic harakat, Hebrew niqqud — not just isLetter()
    - Stale-caret guard — Verifies the reported selection is still live before setComposingRegion, and only mirrors into the buffer if the editor accepted the region
    - Blocked while a panel owns the screen — No resume behind Grammar/AI/Translate, on-keys handwriting, or an in-flight dictation
    - Caret-scrub window — A spacebar cursor drag suppresses resume mid-drag so the caret's landing spot does not churn
  - Auto-close brackets `RARE` — Off by default; an opening bracket types its closer behind the caret and leaves the caret between the two
    - 18 pairs — ( [ { （ ［ ｛ 〈 《 ⟨ ⟦ 「 『 ｢ 【 〔 〖 〘 〚 — brackets only; quotes and < are left alone, an apostrophe and a less-than sign being the commoner reading of those keys
    - Types over its own closer — Pressing the closer when it is already the next character steps the caret past it instead of doubling it
    - Backspace takes the pair — One press on an empty pair removes both halves; a pair with text in it deletes a character at a time
    - Stands down in front of a word — A bracket typed immediately before a letter or digit is being put around it by hand; structured and secure fields are excluded like every other typing rule
  - Selection-aware key behaviour `RARE` — What a key does changes when text is selected
    - Shift re-cases the selection — lower → Title → UPPER → lower, keeping the text selected so presses walk the cycle; mixed case normalises to lower
    - Brackets and quotes wrap — 11 pairs — ( [ { < " ' ` “ ‘ « ｢ — wrap the selection and leave the inner text selected for another pass
    - Space and backspace replace — Both drop the composing region first and commit over the selection
  - Selection macros `RARE` — With text selected, the keyboard offers what that shape of text is for and what any text is for: Undo, Select all, then Call | Message | WhatsApp | Contact on a number, Email first on an address, Open, Remove trackers and QR on a link, and the edits, a find and replace, line tools, case and chat formatting, conversions, grammar, AI, both Bengali directions, speech, maps and calendars on prose. Off by default
    - Reads the selection whole — A sentence with a number in it is a sentence, and two lines are never one thing; its own pass over the selection rather than the clipboard's fragment scan, which is the surface that has room to show what it found and where
    - Four readings — Phone, address, link, plain text; bare domains need an ending off a short allow list so a selected filename is not a link, and phone shapes reuse the clipboard's own PhoneFormats masks
    - Format is entity-aware — A number is re-rendered into the user's own mask separators and all (01712345678 to +880 1712-345678), a link loses utm_*/fbclid/gclid and about twenty more while its path and fragment survive, an address is lower-cased; the chip is dropped when the rewrite would change nothing
    - Case ladder behind Format on prose — lower / Title / UPPER / Sentence in place of the row, each chip written in the case it applies; acronyms survive Title and Sentence unless the whole selection is capitals, and the result stays selected so the chips chain
    - Two placements — Its own BarRow.MACROS, animated in and out and reorderable with every other row, or over the suggestion strip at no height cost, since nothing is being typed while text is selected
    - Forty-nine actions in seven groups behind one allow list — Editing, Lines, Format, Convert, Language, Look up, Open in; twenty-eight shipped on, the chat markers, programmer's cases, decoders, speech, zones, maps, calendars, Search and Translate off because each is a taste or a round trip
    - One flat row in the user's own order — A reorderable list in settings decides the sequence; the row is filtered to what the selection allows and Undo is pinned first, so the row seen is shorter than the list
    - Ladders only where an action is a pick — Format's case options, the Fancy styles, a colour's other spellings and the time zones replace the row with choices; every pick converts from the selection as it stood when the ladder opened, so picking again replaces the last choice
    - Undo per selection session — Every rewrite is stacked (twenty deep) while the selection stays live; the chip checks the field still reads as the last rewrite before putting the original back, and the stack ends with the selection, a new field or a move onto other text
    - Find and Replace — Find jumps to the next occurrence and wraps; Replace opens a panel with two buffers of the keyboard's own, Aa/whole word/regex toggles, previous/next, replace one and replace all as one undo entry, a count, and a matcher under a time budget enforced through a clock-watching CharSequence
    - Line tools — Sort (natural order, digits as numbers, again for descending), Unique, Number and Bullets as toggles that convert into each other
    - Programmer's cases — camelCase, snake_case, kebab-case and CONSTANT_CASE inside the Format ladder, each reading any convention in
    - Chat markup per app — Bold, italic, strike and mono in the host app's own markers from a package table (WhatsApp, Telegram, Discord, Slack, Messenger, Google Chat and more), toggling off on a second tap, hidden in any app not in the table
    - Converters — Any numeral system's digits to ASCII, a colour code's other spellings with a swatch on the chip, JSON pretty or minified with key order kept, Base64 and percent decoding behind gates strict enough that a word never qualifies
    - Content detectors behind switches — Dates and times (numeric in either order, month names in English and Bengali, DateSuggest phrases, zone abbreviations) and places (coordinates read exactly, addresses guessed conservatively) only run while a macro that needs them is on
    - Banglish both ways — To Bangla through the spelling map, then the phonetic index under the strip's own confidence rule, then literal Avro, letter runs only; to Banglish through the inverted map and a rule romaniser with the inherent vowel dropped where speech drops it
    - Hinglish both ways — To Hindi and To Hinglish, the same converter over the Hindi scheme; back to Latin through a schwa-deleting romaniser (करना to karna, नमस्ते to namaste), offered only while the Hindi phonetic layout is enabled
    - Grammar, AI and speech — Harper over the selection alone with every fix committed at once; AI buttons that run a chosen action on the selection and land in the AI panel, whose Replace now swaps the selection rather than the field; reading aloud through the vocabulary speaker with a chip that reads Stop
    - Intents with fallbacks — Contacts, Maps and Calendar each try two intents and toast when no app takes them
    - One-time list reset — The on-list and the order carry a list version; a list stored under an older one reads as the shipped list, so every existing user gets the new actions once
    - Select all leads every row — A long-pressed word widens to the whole field in one tap; the chip is dropped once the selection already spans the field, which costs a one-character read only when the selection starts at offset 0
    - Only offers what can work — WhatsApp hidden without WhatsApp installed, Search/Translate/QR hidden when their tools are off, which the power-saving and direct-boot settings views have already decided
    - Never over a password field — isSecureField is asked before the read, so a password never reaches a Share chooser
    - Free while idle — Feature switch, secure field, collapsed caret and a span over 4,000 characters are all answered from the offsets onUpdateSelection reports, before the getSelectedText IPC that would otherwise run on every caret move
    - Acts on the text the chips were drawn for — The offer carries its own text, so a tap runs against what was read, not whatever the field holds by the time the finger lands
    - Direct-boot aware — Every macro that would start an activity is dropped before the first unlock, leaving select all, copy and the case ladder, which only touch the field the user is already in
    - Toolbar switch — The Selection actions tool flips the feature from the keyboard, so the bar can be on only for the stretch it is wanted
  - Long-press letter shortcuts `uncommon` — A/C/V/X/Z/Y carry select-all, copy, paste, cut, undo and redo as entries in their own alternates popup, after the accents the key already has; all six on by default, and each key stays on any layout by naming its own letter
    - Slide from 🌐 `RARE` — longPressLetterActions.globeDrag, off by default: a drag off 🌐 rides the #67 chord-drag loop (first on the Initial pass, trail line from the key) and the key it lifts on runs its shortcut through the same six letters (letters rebinding included), independent of the six popup switches; a drag that starts after the long-press delay is left to the language picker; glide, octopus and handwriting refuse strokes that start on 🌐 while it is on
    - Raw-keystroke mode — Optional Ctrl+A/C/V/X as real key events instead of performContextMenuAction, for terminals
- **Key press behaviour** — Long press, popups, repeat, chording and press feedback
  - Long-press alternates — Delay 150–700 ms (default 300); popup radius, shape and font scale all themed or user-set
    - All-accents mode — Merges the full Latin accent set into every letter popup — 16 base letters with 2–10 variants each; off by default
    - Corner hint character — First long-press alternate drawn small on the key, with its own size multiplier; drawn by every key that opens a popup, action keys included
    - Multi-row popups — A popup with more entries than fit across the display wraps onto further rows rather than running off the edge
    - Alternates sized apart from the bubble — Own text multiplier reaching ×3.20 (the bubble stops at ×1.60, having a fixed box to stay inside) and own 0–32 dp spacing per entry, which is both the gap and the touch target
    - Fixed column grid `uncommon` — Auto wraps on measured width; 3–11 lays every row on one column grid, so a long list reads as a block and each entry keeps its place between holds
    - Per-key column count `RARE` — `Key.alternateColumns` overrides the global for one key, set in the editor's key sheet: a fractions key wants a six-wide grid where a letter's four accents want the one row they already get
    - Fill from the key outward `uncommon` — Optional AOSP row order: the first alternate lands on the row nearest the finger and the overflow climbs away, instead of the popup filling top-down like lines of text
    - Choose without lifting — The first alternate is highlighted as the popup opens, a slide moves the highlight and the lift commits it, so a hold and a straight release types the first alternate; sliding clear of the popup types nothing. On by default; off restores the popup that stays up for a second tap
    - Action alternates `RARE` — A popup entry that runs an action instead of typing: Tab, a layer switch, or any tool. Available on every key whose hold is free, which is all of them bar backspace, forward delete, space and the braille dots
    - Custom currency popup — The $ key's popup list is user-ordered; built-in set is ৳ € £ ¥ ₹ ₿
    - No-alternates fallback — A long press on a key with no popup behaves like a tap rather than doing nothing
  - Key preview bubble `uncommon` — On-key or floating style, each with its own remembered height
    - Minimum linger 140 ms — A fast tap still leaves a readable bubble instead of a one-frame flash
    - Stuck-bubble ceiling 750 ms — Hard cap from press, above the long-press timeout, so a dropped release cannot strand a bubble
    - Off in numeric fields by default — A floating character over a PIN pad is shoulder-surfable
  - Per-pointer press lifecycle `RARE` — Raw pointer tracking instead of detectTapGestures, so a second finger landing on the same key before the first lifts counts as two keystrokes
    - Forgiving release bounds — A drift up to half a key beyond the edge still commits; a deliberate slide further cancels
    - Stolen-pointer handling — When glide consumes the pointer the press is cancelled without committing
    - Separate key-up event — Fires per finger, for sound packs that recorded a release sample
  - Tremor debounce `RARE` — Ignores a repeat press of the same key within N ms (0 = off); scoped per key so alternating keys are unaffected
  - Flick keys — 4-direction flick arms with a live cross popup; ships on the Japanese 12-key layout (ja_flick)
    - Dominant-axis resolution — 22 dp slop; a flick toward an undefined arm falls back to the centre tap
    - Long press still works — Committing to an arm cancels the pending alternates timer
    - Kana variant key — 小゛゜ cycles the last kana through dakuten/handakuten/small forms
  - Chorded and timed input modes `RARE` — Braille and morse ride the same key dispatch as every other press
    - 6-dot braille — Perkins contract: dots gather on the way down, the cell commits when the last finger lifts; stolen pointers still count as lifts
    - Morse — Dot/dash keys with a commit timer; backspace edits the pending sequence
  - Dead keys `uncommon` — Any key emitting a U+0300–U+036F combining mark is a dead key; fuses via NFC so every precomposed pair Unicode defines is reachable
    - Spacing fallback — 13 spacing accents for a lone press; no-precomposed-pair falls back to accent-then-letter
  - Modifier latch keys `uncommon` — Ctrl/Alt/Meta keys: tap arms, double-tap locks, third tap clears
    - Modifiers sent as real key events — KEYCODE_CTRL_LEFT down/up pairs, because TextView reads modifier state off the key events not getMetaState()
    - Armed latches consumed, locked ones kept — So Ctrl+Shift+Arrow selection sequences work
  - Fn layer key `RARE` — One-shot shift into the layout's Fn key map, springing back after one key; a quick second tap sticks
  - Broadcast key `RARE` — A user-authored key that fires an Android intent action — a macro key for Tasker and friends; types nothing
  - Tool key `RARE` — A key bound to any of the keyboard's tools: voice typing, the editing pad, the clipboard, a scanner. Runs whether or not the tool is on the toolbar, and wears the tool's own icon
  - 24 key actions total `uncommon` — text, shift, caps_lock, delete, forward_delete, space, enter, symbols, letters, language_switch, input_method_picker, emoji, numpad, mod, send_key, fn, kana_variant, tool, broadcast, braille_dot, morse_dot, morse_dash, none, unknown
  - Press feedback gating `uncommon` — Fine-grained beyond a master haptics switch
    - Per-event vibrate toggles — Space, delete-swipe steps and auto-repeat ticks each have their own switch
    - Haptic coalescing — A minimum gap defers the second buzz of a fast burst so two presses are felt as two clicks
    - DND respect — Optionally suppress all keyboard haptics while Do Not Disturb is on
- **Shift, caps and auto-capitalise**
  - Shift state machine — OFF → one-shot ON → OFF, with a double-tap to caps lock
    - Tunable caps-lock window — 150–600 ms, default 350 (separate from the fixed modifier double-tap window)
    - Dedicated ⇪ key — Its own action that toggles caps lock outright, for grids wide enough to carry both keys
  - Auto-capitalise — Driven by getCursorCapsMode, so it follows the app's own sentence rules
    - Skipped on caseless scripts — Bengali and other scripts with no letter case never arm shift
    - CAP_CHARACTERS fields — A field asking for all-caps arms caps lock, not a one-shot
    - Text-class only — Never fires in number, phone, date or time fields
  - Shift cancels an auto-inserted space `RARE` — One shift press after a double-space '. ' or an auto-space-after-punctuation removes the space and cancels the armed capital
  - User-shift vs auto-shift distinction `RARE` — shiftPressedByUser is tracked separately so Shift+Enter's newline override never fires on an auto-capitalised empty chat box
    - Shift+Enter newline — Opt-in: types a real newline instead of firing the field's declared Send action
- **Space and punctuation behaviour**
  - Double-space period — Inserts '. ' within 400 ms, plain text fields only so email/URI/number boxes keep two spaces
  - Double-space tab `RARE` — Second space inserts a tab instead; wins over the period rule and works even at a line start
  - Auto-space after punctuation `uncommon` — 'hello,world' becomes 'hello, world'; plain-text fields only, and typing a space yourself right after does not double it
  - Space hold-to-repeat `uncommon` — Its own interval, separate from delete's, because a runaway spacebar costs more than a runaway backspace
  - Symbols layer springs back `uncommon` — Typing one of a configurable char set (default !?.,;:) on ?123 returns to the letters; digits deliberately excluded
  - Long-press ?123 for the numpad `uncommon` — Opens the numeric keypad panel on any field instead of the long press acting as a tap
  - Long-press enter for emoji `uncommon` — Opt-in; prepends an emoji entry to the enter key's popup, so hold-and-release opens the panel; a Send/Search field's newline alternate stays behind it. Toggle lives in Key press and Bottom row keys
  - Number row behaviours `uncommon`
    - Shift swaps digits for symbols — Holding shift on the letters layer turns the digit row into the =\<>[]{}|~ fill row
    - In-symbols toggle — The digit row can be kept on letters but dropped from ?123
    - Untouched-default tracking — Derived from DataStore key presence so tablet defaults can apply without breaking a user's explicit off
- **Words on the keys** `RARE` — A predicted word floats over the key that would reach it, taken by a flick up or a tap; the BlackBerry Z10's in-letter prediction (discussion #102)
  - One placement rule — The word hangs off the first character where the candidate stops agreeing with the buffer, which covers completions, corrections and next-word predictions alike; that index is also the two-tone split
  - Never relocated — A candidate whose key is already claimed is dropped rather than moved, because a word over a key that would not type it is a lie about the affordance
  - The strip's own words — the pool is `suggest`'s finished list, so the keys and the strip never disagree; the engine's raw walk only fills keys the strip had no room for, and past a density of 9 the tries are fanned for the rest
  - Three placements — Floating in the gap above the key (no height change), a reserved lane per row, or inside the key; top-row words straddle the grid and are tapped on the half still over it
  - Words per key (#136) — wordsPerKey 1–3, default 1; a key honours that many claims in rank order (OctopusWord.tier), stacked away from the key; the flick takes the nearest, a tap the one touched, density still caps the board
  - Flick or tap `uncommon` — Both switchable; the flick is judged at the lift against a sensitivity tier whose cone matches the glide picker's, so a glide that opens upward stays a glide
  - Live during a glide — Mid-stroke each alternate hangs off the key where it leaves the decoder's leader, which no other surface can show; one decode, one state write
  - Hints step aside — A key carrying a word drops its corner hint, read at draw time so the board keeps its per-keystroke recomposition skip; the transliteration hint is never hidden
  - Off on phonetic layouts — Avro's candidates are readings of the buffer rather than words longer than it, so there is no next key to derive; needs a roman-side completion source
- **Autopilot** `uncommon` — Two independent touch-position systems: a visible target nudge and an always-on typo model feed
  - Next-letter target nudge `uncommon` — Touch target of each letter biased toward the letters most likely to come next; opt-in, letters layer only
    - Bias source — Dictionary completions from the active, user and custom lexicons, frequency-weighted and normalised to the max
    - Decided at pointer-down — Recorded on the Initial pass before keys see the touch, consumed by the owning key on release; never consumes the event
    - Bounded reach — Strength 1-10 (5 by default), and never remaps to a key more than 1.3 key widths from the finger, or when the plain-nearest key already wins
    - Invalidated on layout change — An in-flight remap is dropped so a release cannot apply a decision made against the old grid
    - Visible touch areas `RARE` — Optional overlay draws the three likeliest letters at the size their areas have grown to, and outlines the same edge; both off by default, clamped to the board, and gated on recent typing so a glide or a caret move never raises them
    - Adjustable exaggeration — The drawn face multiplies each side's growth by ×1.0-×3.0 for readability; the outline and the hit test itself ignore it
  - Touch positions fed to the typo model `RARE` — Every letter-key down position is normalised by key width and paired with the character it committed
    - Live key-centre publication — Layout letter centres pushed to the engine as a KeyTouchModel, coalesced through snapshotFlow
    - Per-character tap frame — The composing buffer carries a touch point per character so autocorrect scores against where fingers actually landed
  - Full-cell touch targets — Keys have no layout spacing — each touch target fills its whole grid cell including the visual gap
- **Hardware keyboard** `uncommon` — Physical keys as a first-class input source plus a full shortcut layer
  - Typed characters through the IME pipeline `RARE` — Transliteration, composing buffer, suggestions and autocorrect all apply to physical keystrokes; toggleable
    - Interception gate — Mirrors the soft keyboard's composing gate, plus every open panel search / typing test that eats keystrokes
    - AltGr passthrough — Ctrl+Alt together is treated as character production, not a shortcut, so German AltGr+Q types @
    - Space, backspace and enter reuse the soft handlers — So double-space period, glide undo and panel-search Enter all behave identically
    - Half-press safety — Every consumed DOWN is recorded so the matching UP is swallowed and the app never sees half a keypress
  - Leader key and tool letters `RARE` — Double-tap Ctrl (default) or a chord arms a picker; a letter then opens a tool
    - 25 default letter bindings — E emoji, C clipboard, X text edit, V voice, A AI … fully remappable as a complete map
    - Cheat sheet on ? — Stays armed while the legend is read
    - Armed timeout 1–30 s — Also how long the on-screen badges stay up; default 8 s
    - Chord validation — Warns on reserved chords (Ctrl+A/C/V/X/Z/Y/S/F, Ctrl+Space, Ctrl/Alt+Tab), bare leaders, disabled tools and duplicate bindings
  - Direct chords `RARE`
    - Ctrl+1…9 toolbar digits — Opens the tool drawn under that digit, no leader first; exact-modifier match so Ctrl+Alt and Ctrl+Shift stay with the app
    - Alt+1…9 suggestions — Picks the nth suggestion; alternative leader-then-digit mode avoids the collision entirely
    - Always-on suggestion digit badges — Digits drawn under the strip whenever a physical keyboard is attached
  - Panel navigation without touching the screen `RARE` — A drawn focus ring moved by the keyboard
    - Arrow, Tab and Shift+Tab — Tab only claimed once the ring exists — before that it is still field navigation or terminal completion
    - Home/End and PageUp/PageDown — Jump to the ring region's first/last item or page through it
    - Escape closes a panel — Only consumed when the keyboard actually has something open
    - Auto-show and restore — A shortcut that opens a tool forces the input view up and puts it back when the tool closes
  - Mac shortcut mode `RARE` — 14 actions on Cmd and Option: copy/cut/paste/select-all, undo/redo, line and document ends, word moves, word delete, delete-to-line-start
    - Ctrl is a disqualifier — Not an alias — an app that handles Ctrl+C keeps getting it
    - No implicit select-all — Cmd+C with nothing selected is a no-op, unlike the long-press C path
  - Ctrl+Space language cycling `uncommon` — Forward, Ctrl+Shift+Space backward; holding Ctrl browses an overlay list and releasing commits
    - Tappable overlay — Rows are tappable with a close button, so unplugging the keyboard mid-browse still has a way out
- **Keyboard geometry and reach** — One-handed, split, floating and an inline resize mode
  - One-handed mode — Docks left or right with an in-keyboard rail
    - Per-orientation profiles — Width percent, height scale and dock side stored separately for portrait and landscape (landscape defaults to 55% vs 78%)
    - Rail controls — Flip side and exit buttons; the flip also rewrites that orientation's remembered side
    - Height compression — Key and number-row heights scale down together to bring the top rows into thumb reach
  - Split keyboard — Configurable gap percent between halves
  - Rounded board corners `uncommon` — layoutBehavior.boardCornerTopDp / boardCornerBottomDp (0–40 dp, default 0) and boardCorners (any of the four, default all): the docked frame's board box is clipped to an AbsoluteRoundedCornerShape so the app shows through; no clip at all while square, none on the television card, the floating panel or in resize mode
    - Midpoint cut — Rows split by accumulated width, ties go right; a straddling spacebar is divided in half with the left half's label blanked
    - Empty-row safety — A custom layout with a deleted row splits without throwing
  - Floating keyboard — Draggable panel with a resize grip
    - Drag handle bar — Position stored as x/y fractions of the available slack so it re-anchors on rotation
    - Resize grip — Width 240 dp to screen width, height scale 0.6–1.6, both quantised so a drag costs a handful of recompositions
    - Touchable-region insets — Content insets say the keyboard occupies nothing and the touchable region shrinks to the panel, so the app behind neither resizes nor loses touches
  - Keep the keyboard on screen `uncommon` — The keyboard stays up after its field is gone and over windows with no field (issue #58); docked or floating
    - Hacker's Keyboard mechanism, no overlay permission — onEvaluateInputViewShown says yes while pinned; a posted requestShowSelf puts it back after any hide the user did not ask for
    - User hides suspend it — The hide tool, toolbar swipe and Back all go through requestHideSelf, which parks the pin until the system next shows the keyboard on its own
    - Bounded re-shows — At most 4 per field, 250 ms apart, so an app that force-hides on every show gets a few flashes and then wins; never re-shown over the lock screen
    - Fieldless windows get key events — Letters commit through the framework's fallback connection as key events; backspace sends KEYCODE_DEL on TYPE_NULL, Enter and modifier chords already did
  - Inline resize tool `uncommon` — Gboard-style drag mode over the docked keyboard
    - Three drags — Top handle scales key heights (keeping the number-row ratio), bottom handle and a centre move button ride the bottom padding
    - Nothing persists until Done — All changes preview through session state; Reset returns to entry values, Cancel writes nothing
    - Unchanged fields written as null — A padding-only session does not freeze the key height and lose device-form defaults
    - Limit feedback — Handles turn red and buzz when pinned at a bound; the scrim eats every touch so resize mode can never type
    - Per screen variant — Commits against the current variant (portrait / landscape / unfolded)
  - Docked width and padding `uncommon`
    - Width percent and alignment — Shrink the board and park it left, centre or right
    - Symmetric side padding — 0–30% shaved off each edge, narrowing keys toward the centre without docking
    - Independent bottom-row height — Space/enter row can be made taller than the rest; 0 means follow the key height
- **Accessibility-facing input behaviour** `RARE`
  - TalkBack gesture pass-through `RARE` — An accessibility service hands the key grid's rectangle back to the keyboard so spacebar slide, backspace swipe, glide and handwriting survive touch exploration
    - Grid only — Strip, toolbar and panels stay outside the carve-out so TalkBack keeps exploring those normally
    - Retracted automatically — A panel replacing the keys removes the region
  - Tremor and timing knobs `uncommon` — Long-press delay, key debounce and both repeat intervals are exposed on the Accessibility screen as well as Key press

**Conditions and gating**

| Feature | Needs |
|---|---|
| Handwriting instead of glide (letter-area swipe drawing) | full flavour only (BuildConfig.ENABLE_ML_KIT_HANDWRITING); also needs a downloaded ML Kit digital-ink model, so a network fetch on first use |
| TalkBack gesture pass-through for spacebar slide / backspace swipe / glide / handwriting | needs the 'WM Keyboard gestures' accessibility service granted by the user |
| Glide typing in a non-bundled language | needs that language's word list present — a downloaded dictionary is a network fetch; coverage below 90% keeps glide off |
| Auto-download of language data that unlocks glide readiness | network |
| Volume keys as cursor control | no permission, but only active while the input view is shown |

## Languages, scripts, layouts, transliteration

- **Language registry** — 845 languages, each with script, locale tag and its own layout list
  - Catalogue size and shape — 845 LanguageDef entries across two Kotlin files, 361 hand-written and 484 generated from the Keyman corpus; unknown ids fall back to a generic Latin language
    - Endonym · English naming — Every row reads "বাংলা · Bangla", native name first
    - Script distribution — 234 Latin, 38 Cyrillic, 16 Arabic, 14 Devanagari, 5 Myanmar, 4 Bengali, plus 32 more scripts
    - Bundled dictionaries only for English and Bengali — bundledDictionary flag is true for 2 of 352; the rest download or learn
    - Never-throwing lookups — byId/byLocale/languageOf degrade to a generic Latin language rather than crashing
  - Language search `uncommon` — Matches endonym, English name, id, locale tag, and layout name/id
    - Layout names are searchable — "avro" or "bepo" finds the language that ships that layout
    - Prebuilt lowercase index — Memoised on AssetLayouts.generation so asset names join once parsing finishes
  - Device-derived language suggestions — Ranked from the phone's own signals; no permission, nothing leaves the device
    - Signal order — System language list first, then one region; SIM country > network country > time zone > locale region
    - Only the first useful region is read — Stops en-GB ROM regions burying Bengali under Welsh/Irish/Gaelic
    - 164-country region-to-language table — e.g. IN lists 22 languages, RU 26, ZA 10; English deliberately omitted throughout
    - Reason shown per row — SYSTEM_LANGUAGE / REGION (with country code) / FALLBACK
    - Romanized variant offered beside its parent — Adding Bengali also surfaces Banglish, even when Bengali is already on
  - Fresh-install seeding — Up to 4 layouts, one per recognised system language, English always included
    - Region is not used to seed — Being in a country offers a language; only the phone's language list enables one
    - Default enabled set — QWERTY + Avro + Probhat + Jatiya when nothing else matches
  - Romanized (transliterated-suggestion) languages — 14 `*_rom` entries: ar, bn, gu, hi, kn, ml, mr, ne, pa, ru, si, ta, te, ur
    - Plain Latin QWERTY, dictionary-only distinction — Stays in Latin script; suggestions come from a transliterated word list
    - Automatic two-way pairing — RomanizedPairing cross-wires every (romanized, same-script) pair among enabled languages in both directions
    - Paired words are exempt from autocorrect — Banglish words stop being "corrected" on the English keyboard
  - Constructed languages `RARE` — 12: Esperanto, Interlingua, Ido, Interlingue, Novial, Lingua Franca Nova, Kotava, Volapük, Lojban, Klingon, Quenya, Toki Pona
  - Per-language settings screen `uncommon` — Up to eight groups, only the ones that language supports
    - Layouts toggles — One switch per layout; the last enabled layout across the whole set cannot be turned off
    - Numerals — Two buttons - the language's own digits or 0-9 - hidden for languages already on Latin digits
    - Also suggest from — Blend other enabled languages' words into this language's suggestions
    - Clusters — Conjunct-aware backspace, with a real sample cluster per script (ক্ষ, क्ष, ක්ෂ)
    - Spellings — Use-known-spellings toggle, shown only for languages with a spelling map (currently bn)
    - Dictionary / Emoji / CJK conversion groups — Word list, emoji keyword pack, n-gram pack downloads with a combined size prompt
- **Scripts and script behaviours** `uncommon` — 37 scripts, each a data row rather than a branch in the service
  - ScriptDef attributes `uncommon` — Direction, letter case, default composer, font hint, Unicode range, sentence-final mark
    - 37 registered scripts — Latin, Cyrillic, Greek, Armenian, Georgian, Arabic, Hebrew, Syriac, 11 Brahmic, Thai, Lao, Khmer, Myanmar, Hangul, Ethiopic, Thaana, Japanese, Han, IPA, Tifinagh, Cherokee, N'Ko, Canadian Syllabics, Tibetan, Ol Chiki, Meetei Mayek, Music, Braille
    - RTL scripts — Arabic, Hebrew, Syriac, Thaana, N'Ko drive the suggestion strip's layout direction
    - Uncased scripts disable shift semantics — hasLetterCase gates auto-capitalisation and shift-uppercasing rather than an is-Bengali boolean
  - Script-specific sentence mark `RARE` — ScriptDef.fullStop; Bengali types দাঁড়ি (।) from the key beside the spacebar
    - ASCII period demoted, not lost — "." moves to that key's long-press for numbers, filenames and URLs
    - Skipped when the layout already types the mark — Only rewrites a Period-role key whose output is literally "."
  - Grapheme-cluster (conjunct-aware) backspace `uncommon` — One press deletes a whole cluster; per-language toggle, off by default
    - Virama table for 13 scripts — Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Sinhala, Myanmar, Khmer, Meetei Mayek (Apun Iyek)
    - Bengali has its own tested path — Walks consonant+hasant[+ZWJ][+nukta] pairs; a bare trailing hasant still deletes alone
    - Generic walk for the rest — Driven by the script's unicodeRange plus its virama, with a guard against a dangling virama over-deleting
  - Contextual vowel forms `RARE` — A Bengali vowel key types kar, য়-glide, or the independent letter depending on the character before the cursor
    - Glide only where a bare vowel is invalid — কা + আ gives কায়া, দি + এ gives দিয়ে; ই/উ/ও stay independent (খাই, বউ, খাও)
  - Per-script pinned fonts `uncommon` — 25 scripts map to a specific Google font; Music to Noto Music, Braille to Noto Sans Symbols 2
    - Per-script font pickers — Curated alternative families per script, shown only while a language on that script is enabled
    - Per-glyph fallback — A glyph the pinned face lacks falls back to the system font rather than blanking
- **Keyboard layouts** — 1,599 shipped layouts: 22 compiled built-ins + 1,577 JSON assets (862 of them converted Keyman keyboards)
  - Shipped catalogue — 20 Kotlin LayoutSpecs (boot-critical) plus 354 .wmlayout.json assets parsed off the main thread
    - Latin ergonomic alternates — QWERTY, AZERTY, Dvorak, Colemak, Workman, Halmak built in; BÉPO, Swiss German, LatAm Spanish, Turkish-Q as assets
    - Ambiguous boards — T9 and Compact QWERTY built in; keys twice to four times the usual size, decoded rather than multi-tapped (#103); T9 keypads for 309 more languages as assets (#332)
    - Indic InScript family — InScript for Marathi, Nepali, Sanskrit, Telugu, Kannada, Malayalam, Gujarati, Punjabi, Odia, Konkani, Maithili, Bodo, Dogri, Bhojpuri; plus Tamil99 and Sinhala Wijesekara
    - Minority Cyrillic alphabets — Tatar, Bashkir, Chuvash, Chechen, Ossetian, Yakut, Udmurt, Komi, Kalmyk, Tuvan, Buryat, Erzya, Mari, Adyghe, Kabardian, Abkhaz, Avar, Lezgian and more
    - A failed asset costs one language, not the build — Each file is decoded in runCatching; a malformed one is skipped
    - Generation counter guards cold-start caches — Anything derived from the shipped set is discarded when the 354 assets finish parsing
  - Layout model `uncommon` — 9 layers with inheritance; a layer left undefined falls back to the shipped grid
    - Nine layers — letters, symbols, symbols2, number, phone, date, time, datetime, fn
    - Key fields — label, output, shiftLabel, action, width, rowSpan, longPress, actionAlternates, clipboardAction, role, icon, iconHint, hideHint, forceHint, flick map
    - Per-key hint override — hideHint drops the corner hint on one key, icon hint and first alternate alike, while press and hold keeps working; forceHint draws it on one key while the global hints switch is off, and hideHint wins if a file sets both
    - 24 key actions — text, shift, caps lock, delete, forward delete, space, enter, symbols, letters, language switch, input method picker, emoji, numpad, mod, send_key, fn, kana_variant, tool, broadcast, braille_dot, morse_dot, morse_dash, none, unknown
    - Broadcast-intent key — Fires an Android broadcast so a key can drive Tasker or any receiver; user-authored only
    - Per-row height multipliers — rowHeights, index-aligned with rows; short or over-long lists tolerated
    - Explicit typo-proximity rows — proximityRows lets a staggered/split grid state its own key neighbourhoods
    - Field-adaptation roles — KeyRole.Comma/Period tag the slots that become @ in email fields and gain / on hold in URI fields, with a legacy label-match fallback
    - Unknown actions survive decoding — A key written by a newer build decodes to Unknown(tag), is reported, and is dropped by repair instead of failing the file
  - Tablet auto-expansion `RARE` — Render-time transform widens an eligible grid by one column each side and mints Tab, backslash, caps lock, a mirrored shift and arrows
    - Row count never changes — The IME window is sized from layer row counts, so the transform only moves and widens keys
    - Backspace can never go missing — Delete only relocates to the number row when that row is actually drawn
    - All-or-nothing eligibility — Declines 322 shipped layouts - the 310 T9 keypads, kana flick pads, braille, morse, the Chinese shape/phonetic pads, and grids with no shift key
    - Per-layout opt-out — tabletExpand flag, default true, for grids already laid out wide by hand
  - More than one letter per key `RARE` — Key.letters lets a grid put a set of letters on one key and leave the language model to say which was meant (#103); AOSP-derived keyboards cannot, because their decoders are one keystroke to one letter
    - Two shipped boards — T9 on the ITU E.161 keypad (8 letter keys, digit hints, 4 columns) and Compact QWERTY (QWERTY's own rows folded two to a key, 5 columns)
    - T9 in 310 languages (#332) — Every keypad follows ETSI ES 202 130's table for its language, or the table the standard names for it (Catalan → Spanish, Faroese → Danish, Rusyn → Ukrainian); languages the standard does not cover start from the table their phones used (German, Russian, Persian, Urdu, or plain E.161) with their own letters on the key ETSI's language-independent table gives them. Indic scripts use the Indian-market plan of ETSI Annex A (signs on 1, vowels with their signs on 2 and 3, consonant rows from 4, punctuation in the shift slot), which Burmese, Khmer, Ol Chiki and Syloti Nagri follow too; Thai and Lao use the Thai phone keypad; Vietnamese's toned vowels ride with their vowel; standalone tone marks take fixed keys. Armenian keeps 9 for punctuation as the standard does; caseless scripts trade the shift key for a comma. Every keypad is checked against its language's 30,000 commonest words
    - Letter sets hold combining marks — Key.withLetters keeps matras, viramas, nuktas and tone marks, and the decoder walks a key's composition-excluded letters (क़, ড়, אַ) along the decomposed spelling the NFC word lists use, as one keystroke
    - The buffer stays one character per keystroke — A tap commits the key's anchor letter, so backspace, the caret, word boundaries and every consumer of the composing buffer are untouched
    - Key sets ride beside the buffer — A per-keystroke frame, the twin of the tap-position frame, snapshotted with the word and size-checked against it
    - Free unedited matches — Every letter of the pressed key matches at zero cost and zero edits, so readings are not corrections and survive the "a known word suppresses corrections" gate
    - Ranked by the language model alone — Frequency, n-gram context, the personal lexicon and the register prior order the readings, exactly as a T9 phone ordered them
    - Honest readings beat commoner edited ones — Edits cost an extra ln(400) here, so throwing a keystroke away needs overwhelming evidence; edits also cap at one, which keeps the frontier from exploding
    - Long press spells a letter outright — Every letter of a key is in its popup; a picked letter pins that position and decodes as itself, which is how names and unknown words are typed
    - Commits the reading, not the buffer — No confidence gate: the anchors are not a word, so "leave it as typed" would be the wrong answer rather than the safe one
    - Glide came free — GlideKeyMap has resolved several characters to one key since Probhat's ক/খ, so a swipe across T9 or the compact grid decodes with no decoder change at all
    - Proximity and the touch model follow — Neighbours derive between keys rather than letters, and every letter of a key reports that key's measured centre
  - Secondary layouts `RARE` — Grids of your own reached by a key or the Secondary layout tool, never by picking a language (#62)
    - LayoutSpec.secondary — Stored beside the other custom layouts; excluded from the language cycle, the OS subtype list and the Languages screen
    - KeyAction.Layout(id) — Shows the named layout over the letters; a second press, ABC, or ?123 leaves it; also works as a press-and-hold alternate
    - Secondary layout tool — Toolbar toggle lit while any secondary layout is up; which one it shows is a setting on its page, the first by default
    - From scratch — A new one is three rows of blank keys plus an ABC key; validate and repair skip the delete/space/enter guarantees for it
  - Persistent layers `RARE` — LayerSpec.persistent keeps a symbols, Fn or secondary grid up across a close and reopen of the keyboard and across fields (#60)
    - One switch per layer — No global "persist if…" settings; the editor's toggle carries the "make sure you have a way to exit" warning and the Problems list repeats it
    - Panels too — The same LayerSpec.persistent on a panel layout's grid keeps the text-edit, emoji, clipboard or trackpad panel open across fields
  - Panels as tabs of every layout `RARE` — The four panel grids are tabs beside Letters…Fn in each layout's editor (#63, per-layout half); a layout's own copy under `panel_<kind>` in `layers` beats the shared panel layout, which beats the shipped grid
    - Routed repair — `LayoutSpec.repair`/`validateLayout` send `panel_*` layers through the panel rules, so component cells survive and panel problems reach the layout's list
    - One editor body — `PanelEditorBody` + `panelPreview` shared by the panel's own screen and the layout editor's tabs
    - A theme per panel — `LayerSpec.themeId` on the panel grid; `screenThemeId` reads the open panel's own theme first, then the typing grid's
    - Numpad is a panel too — `PanelKind.NUMPAD`, keys only; the tool's pad resolves layout tab → shared pad → the layout's Number layer (#55) → shipped pad in the calculator/dialer order
  - A theme per layout and per layer `RARE` — LayoutSpec.themeId / LayerSpec.themeId, picked from every built-in and custom theme in the editor; layer beats layout beats mode beats settings (#61)
    - A view, not a write — applyLayoutTheme overlays keyboardThemeId and switches the auto pair off for as long as the grid shows; the user's own choice is untouched
    - Missing theme is ignored — A layout shared with a theme this device lacks keeps the pairing and draws normally
  - Authored Number layer reaches the Numpad tool — The panel and the ?123 long press draw the layout's own Number layer when it has one (#55)
  - Repair versus validate `RARE` — Two separate passes: one that only reports while editing, one that rewrites on import and activation
    - Repair guarantees delete, space and enter — Runs on import and when a layout becomes active, so you can never type on a layout you cannot backspace in
    - Caps enforced — MaxKeyWidth 12, MaxRowWidth 40, MaxKeysPerRow 24, MaxRowsPerLayer 8
    - Findings are severity-tagged — BLOCKING vs WARNING; a missing shift key is the one warning
    - Notes are resource ids, not strings — LayoutMessage resolves at draw time so the report follows the current device language
  - Selection and migration — Active layout, enabled ids and enabled languages all derive from stored ids
    - Pre-registry InputMode names translate at read time — Nothing is rewritten, so a downgrade still finds input_mode where it left it
    - Retired ids fold onto replacements — The 22 per-style asset_fancy_* ids canonicalise to one asset_fancy
    - Spec version migration — v1 to v2 turns baseMode into langId + composer, moving Avro onto ComposerType.TRANSLITERATE
- **Layout editor and sharing** `RARE` — Every shipped layout is editable visually or as raw JSON
  - Visual grid editor `RARE` — Renders with the user's real theme, key shape and font
    - Nine layer tabs with inheritance markers — A pencil marks an authored layer; an unauthored tab shows the built-in grid live and forks on edit
    - Shift-plane preview — Redraws every key with its shiftLabel (or uppercased label) without switching layers
    - Action picker — 26 options in 6 groups: typing, layers, modifiers, keys apps understand, chorded input, other
    - Icon catalog on text keys — 46 named vectors plus 24 case-insensitive aliases (delete to backspace, globe to language); unknown names fall back to the label
    - Width controls — Quarter-step slider, presets 1 / 1.25 / 1.5 / 2 / 4, and a fill-the-row button
    - Row operations — Add/duplicate/delete row, drag-reorder rows and keys, row-height slider x0.5-x2, reset a layer
    - 30-step undo/redo with coalescing — Whole-layout snapshots; typing inside one key sheet is a single undo step
    - Autosave with live problem list — No save button; validation findings update as you edit
  - Raw JSON editor `RARE` — Draft with an explicit Apply, theme-coloured syntax highlighting, no reformatting
    - Defaults omitted for humans — encodeDefaults off shrinks a QWERTY from ~33 kB to about a tenth
    - The edited id always wins — Pasting another layout's id is ignored so you cannot overwrite a different layout
    - Reaches fields the grid editor has no control for — Clipboard long-press actions and per-direction flick maps
  - Layout files `RARE` — .wmlayout.json versioned envelope tagged "wmkeyboard-layout"
    - Format tag is the only strict check — Everything else is repaired and reported rather than rejected
    - Export, duplicate, import — Filename derived from the layout name; import registered as a system file handler
    - Editing a shipped layout is an override, not a fork — Stored under the same id; the button reads Reset rather than Delete
    - Content-sniffed import — A renamed settings backup inside a .wmlayout.json imports as a backup
    - Imported layouts are never auto-enabled — Added to the list; you turn them on under Languages
  - Community layouts from addon repositories `RARE` — "layout" is one of the addon types a repo URL can serve, capped at 4 MB
- **Importing layouts from other keyboards** `RARE` — Reads FlorisBoard/HeliBoard JSON and HeliBoard's plain-text layout format
  - Two formats, one parser `RARE` — Format guessed from the first non-comment character, so a commented JSON file is not read as text
    - Lenient JSON — Comments and trailing commas allowed; rows accepted bare or under arrangement/rows/keys/layout
    - HeliBoard text — `label popup1 popup2` per line, blank line ends a row
    - Written from published formats, not upstream source — Deliberate, because Floris is Apache-2.0 and HeliBoard GPL-3.0 while this app is MIT
  - Key-code translation `RARE` — ~50 foreign codes mapped to native actions, including F1-F12 from the -10039..-10028 range
    - Space/enter/tab rescued from code points — 0x20 and 0x0A become real actions so auto-space and the field's enter action survive
    - Unmapped codes are dropped and reported — Never turned into Unknown, which would break the save path
    - Approximations counted — delete-word to delete, symbols2 to symbols and friends are tallied so the report cannot claim a clean import
  - Geometry fix-ups `RARE` — Foreign fractional widths scaled x10 onto this app's grid unit; -1 "fill the row" distributed first
    - Rows already in grid units pass through — Detected by a row total above 2.0
  - Character normalisation `RARE` — NFC plus manual nukta recomposition for 22 Devanagari/Bengali/Gurmukhi/Oriya pairs NFC refuses to join
    - ASCII returned untouched — Nothing below U+0080 can carry a combining mark
  - Language is asked, never guessed silently `RARE` — A script histogram over the keys seeds the picker; a blank langId would otherwise migrate to English
  - Repaired once, in front of the user `RARE` — So the grid approved in the dialog is the grid that gets typed on
- **Transliteration and composers** `uncommon` — 16 ComposerType values chosen from a layout's script plus optional override
  - Bengali Avro phonetic `RARE` — Rule-based greedy longest-match transliteration with ~90 rules bucketed by first character
    - Context-sensitive vowels — Independent letter at word start or after a vowel, kar after a consonant
    - Inherent vowel handling — lowercase o is silent after a consonant but breaks the cluster: kolokata gives কলকাতা, kolkata conjuncts
    - Reph, jofola and ba-fola — rr gives র্, y after a consonant gives ্য, w after a consonant gives ্ব (swasthyo to স্বাস্থ্য), w elsewhere gives ও
    - Khanda-ta three ways — TH, a trailing backquote, or a word-final hasant all collapse ত্ to ৎ
    - Cluster breaker — Backquote writes nothing and breaks the join: k`s stays কস where kos conjuncts to ক্স
    - Signs join nothing — ং/ঃ/ঁ hang off the previous syllable; ng before a vowel becomes ঙ (bangla to বাংলা, bangali to বাঙালি)
    - Ridmik spellings accepted alongside Avro's — qq/cb for ঁ, HH for ঃ, hs for hasant (only after a consonant, so "ahsan" is safe)
    - Stray capitals read as lowercase — "Bangla" still types বাংলা instead of dropping a Latin B into the buffer
    - Digits and currency — 0-9 map to ০-৯, $ to ৳, single dot to ।, double dot to a literal period
  - Bengali Khipro `RARE` — Compositional ক্ষিপ্র layout (#400): the Khipro team's own m17n spec (v36.5.0, MIT) run by a small interpreter, passing their conformance cases
    - Deterministic — space commits exactly the composed text; no spelling map, no phonetic fold, no autocorrect
    - Completion strip — composed word first, then bundled/downloaded Bangla words and learned words that start with it
    - Touch grid per the Khipro guideline — / slicer where shift sits, ; separator beside the spacebar, danda key kept
    - Hardware keyboard uses the desktop spec — digits to ০-৯, . to ।, $ to ৳, chosen per word by the key that starts it
  - Lenient Banglish matching `RARE` — Both input and every dictionary word fold to a phonetic key where confusable sounds collapse
    - Aspiration kept as a parallel mask — Typing the h and not getting it is penalised 20x; leaving it out is penalised 2x; only ক/খ, গ/ঘ, ত/থ, ট/ঠ, দ/ধ, ড/ঢ count
    - ch and ph excluded on purpose — They are ordinary English-influenced spellings, not aspiration claims
    - Final ও kept apart — kotha gives কথা and only kothao gives কথাও, despite the fold dropping a trailing o
    - Nukta normalisation and corpus repair — Decomposed ড়/ঢ়/য় recomposed; the scraped-corpus অ+া pair folded back to আ
  - Bengali spelling map `RARE` — 11,914 Banglish chat spellings plus 2,369 English loanwords, consulted before the transliterator
    - Vowel-dropped chat spelling — tmr to তোমার, amk to আমাকে, trpr to তারপর - unreachable by any fold
    - Loanword conventions — table to টেবিল, keyboard to কিবোর্ড rather than the phonetic তাবলে
    - Curated list outranks the generated one — Duplicate keys accumulate in stream order, hand-written file first
    - Per-language off switch — Turning it off is the only way to reach the letter-for-letter reading
  - Hindi phonetic `RARE` — Latin keys in, Devanagari out (kaise ho gives कैसे हो); its own layout under Hindi, InScript still the default (#239)
    - Schwa-aware rules — clusters split unless they open or close the word, double a consonant, precede y, or sit in a short join table; a grammatical ending (na ta ka ko se me kar wala) never joins its stem, so karna gives करना and namaste gives नमस्ते
    - Long finals and anusvara — a word-final a/i/u is long (mera, bhi, tu), a before o/u is long (jao), a nasal before its stop is ं (hindi, lamba)
    - Other readings on the strip — last a long (pyar, sarkar), all clusters joined, none joined, final left short; what fills the strip when no word list is installed
    - Lenient Hinglish matching — a fold that forgets aspiration, dental/retroflex, virama, every inner a and vowel length; ड़ filed under d and r, unwritten nasalisation forgiven (nahi/nahin/nhi); typed details (aa, kh, a doubled consonant, ai) handicap siblings that contradict them
    - Download-only vocabulary — index built over the downloaded and imported Hindi lists, only while the phonetic layout is enabled; a one-time strip chip points at the download when there is none
    - Hindi spelling map — hand-written everyday words, chat shorthand (h, nhi, kr, bhut) and English loanwords, consulted first; per-language off switch
    - Glide — strokes decoded against the spelling map and the downloaded Hinglish list, resolved through the same index
  - Vietnamese Telex and VNI — Two shared-engine transliterators; letters spell the marks in Telex, digits in VNI
    - Standard tone placement — A marked vowel wins; else single vowel, else last vowel of a closed cluster, else first of an open one (oa/oe/uy take the second)
    - qu/gi onsets excluded from the nucleus — The u or i is a glide unless it is the syllable's only vowel
    - VNI buffers digits — bufferDigits on, digitsStartBuffer off, so a plain number on an empty buffer still types
  - Korean Hangul — Compatibility jamo (two-set) and conjoining jamo (three-set) composed into syllable blocks
    - 19 initials, 21 medials, 28 finals — Plus 7 compound medials and 11 compound finals
    - Re-split — 간+ㅏ gives 가나, 갉+ㅣ gives 갈기; two-set only, a three-set final stays where it was typed
    - Three-set layouts — 세벌식 390 and 세벌식 최종 ship beside the two-set grid; a plain initial typed twice doubles (ᄀᄀ → 까)
    - 천지인 (Cheonjiin) pad — Samsung-style 12-key grid; vowels folded from the strokes ㅣ ㆍ ㅡ by CheonjiinComposer, consonants picked by multi-tap; space or a 1 s pause ends a consonant's cycle (#372)
    - No candidate step — Korean gets the ordinary suggestion/autocorrect strip, not a conversion bar
  - Dead keys — Any key emitting a combining mark U+0300-U+036F arms a dead key
    - NFC composition, not a table — Every precomposed pair Unicode defines is reachable, including ǹ, ẍ, ṽ
    - Spacing accents stay literal — Typing ´ ^ ~ ¨ on their own gives ordinary characters so a^2 and backticks still work
    - Visible fallback — A pair Unicode has no character for emits the spacing accent, or the mark on a dotted circle
- **CJK conversion input** — 6 Chinese schemes, Cantonese Jyutping, 3 Japanese layouts, all through one Composer interface
  - Chinese input schemes — Pinyin, T9 Pinyin, Zhuyin, Cangjie, Cangjie Quick, Stroke - six layouts on one language
    - Prefix commit — Pinyin/T9/Zhuyin/Jyutping/Japanese: tapping 你 for `nihao` consumes only `ni` and re-converts the tail
    - Lattice decoding — Viterbi over syllable boundaries with n-gram scoring, capped at 24 units before falling back to prefix lookup
    - Zhuyin and T9 need no dictionary of their own — Both derive their tables from the pinyin inventory and translate each segment to pinyin for lookup
    - Cangjie radical glyphs on the keys — a-y printed as 日月金木水...; the composing region shows glyphs, and hardware letters are accepted too
    - Stroke with a wildcard — Five stroke classes 一丨丿丶乙 (also h/s/p/n/z or 1-5) plus * ? ＊ as an uncertain stroke
    - Code-table methods cap at 24 candidates — Cangjie and Stroke look up a fixed table rather than ranking a lattice
  - Double Pinyin — 5 schemes: Microsoft, Sogou, Xiaohe (小鹤), Ziranma, Pinyin++
    - Validity-filtered translation — An ambiguous final key resolves to whichever combination forms a real syllable
    - Apostrophes skipped, not paired — Otherwise one stray apostrophe desyncs the parity of every syllable after it
  - Jianpin 简拼 — a bare initial is a syllable unit: `wm` → 我们, `zgrm` → 中国人民, mixed `haod` → 好的; z/c/s cover zh/ch/sh, a typed digraph reads both as one initial and as two (`sh` → 是 and 上海)
    - No second index — Initials are per-unit option lists resolved against the sorted pinyin table by prefix range, the same path T9 and fuzzy use
    - Exact over abbreviated — A syllable typed in full is never widened; a/e/o rank their exact reading first; a phrase covering the buffer beats a stitch
  - Fuzzy Pinyin — zh/z, ch/c, sh/s, n/l, r/l, f/h initials and an/ang, en/eng, in/ing, ian/iang, uan/uang finals
    - Ranking signal, not a filter — Two variants per syllable behind an ln(0.15) penalty, so an exact match only loses to a much likelier fuzzy word
    - Validity-filtered expansion — Only real syllables are ever generated
  - Cantonese Jyutping with lazy pronunciation `RARE` — Own 163k-entry pack; tone digits 1-6 buffer without being able to start a buffer
    - Bidirectional mergers — n/l, ng/none, z/j, c/ch - hypercorrection is as common as the merger itself
    - Conditional labial mergers — gw to g and kw to k only before a rounded final, so 誇 kwaa1 never becomes kaa1
    - Coda mergers — -ng to -n, -m to -n, -k to -t, -p to -t
  - Japanese — Romaji, 12-key Flick, and Kana JIS layouts all feeding one composer
    - Romaji to kana transduction — Tracks the romaji span behind every kana unit so consumed lengths report keystrokes, not morae
    - Flick pad — Per-key four-direction flick map in the layout data (あ flicks to い/う/え/お)
    - Kana without marks — かつこう finds 学校 (がっこう): a plain kana typed on Flick or Kana JIS also reads as its small, dakuten or handakuten form behind a small per-mark penalty tuned against the real pack; marks are only ever added, and romaji is never widened
    - Kana-variant key — 小゛゜ cycles the last kana through dakuten/handakuten/small forms (か to が, は to ば to ぱ, つ to っ to づ)
    - Always usable as a bare kana keyboard — With no pack downloaded the reading still commits as hiragana, katakana or half-width katakana
    - Tap resolved by index, not text — ja_kana lists 行 under い, いき, ゆき and こう, so matching by string would eat a mora the user never chose
  - Simplified to Traditional with regional wording `RARE` — Character map plus Taiwan phrase table and TW/HK character preferences
    - Applied inside each composer — Converting a finished candidate list would break prefix-commit's string matching
    - Three regions — Standard, Taiwan (出租車 to 計程車), Hong Kong (character preferences only)
    - Order is load-bearing — Regional tables are keyed to Traditional text, so the character pass must run first
  - Learning from candidate picks `uncommon` — Per-reading history reorders candidates; namespaced by reading space, not by language
    - Five reading spaces — pinyin, pinyin_t9, zhuyin, jyutping, ja_kana each keep their own history; Cangjie and Stroke deliberately do not learn
    - Separate from the Latin user lexicon — That store drops one-character keys, is keyed by surface word, and feeds the gesture decoder where Hanzi is pollution
    - Governed by the on-device learning setting — Incognito and no-learning fields stop new picks being recorded
  - Conversion dictionary packs `uncommon` — 5 downloadable packs, none bundled: pinyin 2.5 MB, ja_kana 41.5 MB, jyutping 3.4 MB, stroke 446 KB, cangjie 351 KB
    - SHA-256 verified before going live — A corrupt conversion table would silently mistranslate
    - Resumable — .part file plus HTTP Range, with a preflight free-space check
    - Presence means valid — Atomic rename after verification, so a final file only exists if the download completed
    - Hot-swap token — A state token summarising which packs are on disk makes a finished download go live on the next field focus
  - Candidate surface — The suggestion strip is replaced by ranked candidates while a buffer is composing
    - Expanded grid — Ranked to depth 128 for lattice methods so a tap in the wrapping grid still resolves
    - Prefix-consistency contract — candidates(b,100).take(12) must equal candidates(b,12) or strip and grid would disagree
    - Raw reading always commits — No dictionary match never traps the user in an empty buffer
- **Numeral systems** `RARE` — Per-language digit glyphs applied at draw time and commit time, layouts stay ASCII
  - Four non-Latin digit sets `uncommon` — Arabic-Indic ٠-٩, Persian ۰-۹, Bengali ০-৯, Devanagari ०-९, plus AUTO and LATIN
    - Per language, not global — Arabic shows ٠-٩ while the English beside it stays 0-9
    - Only two choices offered per language — Its own digits or Latin - nobody writes Bengali with Persian numerals
  - Commit scope `RARE` — TEXT_ONLY (default), EVERYWHERE, DISPLAY_ONLY
    - Numeric fields stay machine-parseable by default — Number/phone/date/time keypads commit ASCII unless EVERYWHERE is chosen
    - DISPLAY_ONLY is purely cosmetic — Native glyphs on the keys, ASCII in the field
  - Late application `uncommon` — Layout data, number-row auto-detection and digit long-press data all keep seeing plain ASCII
- **Multilingual typing and switching** — Enabled layouts form one ordered switch ring reached four ways
  - Spacebar gestures `uncommon` — Two independent slots: quick swipe (default Language) and hold+swipe (default Cursor)
    - Slot chosen by timing, not distance — Crossing touch slop before the long-press delay uses the quick slot
    - 44dp per step, 2.5x wrap resistance — The boundary layout parks before a deliberate extra pull cycles round
    - Two layouts toggle instead of cycling — Extra drag in the same direction will not toggle twice
    - Live preview chips — Every enabled layout as a chip, windowed to five centred on the selection past that count
    - Spacebar label modes — Language / Layout / Both, auto-falling back to both when two enabled layouts share a language
  - Hold-drag picker `RARE` — Hold the spacebar and walk a scrollable list without lifting
    - Threshold at four layouts — Inline preview at four or fewer, scrollable list above that
    - Threshold can be switched off — Picker for more than four layouts (default on); off keeps the windowed, scrolling inline preview at every ring length. The quick-swipe rule and the 🌐 long press still open the picker
    - List or carousel — Language picker shape (default List) picks the vertical list or the sideways strip; the threshold and the swipe slots are untouched by it (#150)
    - First movement absorbed as calibration — Drift from before the hold fired cannot select a neighbour
    - Held-but-unmoved leaves the list open — So it can be tapped directly
  - Language-switch key — Tap cycles layouts (not languages); long-press opens the picker
    - Replaced by an emoji key on a fresh install — globeAsEmoji ships on; switching lives on the spacebar until it is turned off
    - Hidden altogether — showGlobeKey off takes it, or the emoji key in its slot, off every layout's bottom row; the spacebar takes its width (#139)
    - Recently-used order `uncommon` — globeRecentOrder (off by default): a tap goes back to the previous layout, taps within 800ms walk further back through a snapshot of the recent list like Alt+Tab, and only where the run ends is recorded; the physical language key follows it too (#311)
    - Hardware-keyboard overlay — A floated list with tappable rows and a close button, so unplugging the keyboard still leaves a way out
  - Android input-method subtypes `uncommon` — Every enabled layout registered as a subtype, mirrored both ways
    - Stable 31-bit id from the layout id — Android persists the user's enabled-subtype choice by this int, so it must not shift when a name changes
    - Layout id carried in the extra value — layoutId=<id>, so a system-sheet selection maps back to a layout
    - Both locale spellings set — Legacy underscore subtypeLocale plus modern languageTag, because some OEM switchers still read the former
    - ASCII-capable flag from the script — True only for Latin-script layouts
    - Explicit enabling on Android 14+ — setExplicitlyEnabledInputMethodSubtypes; below that the user must tick them in system settings
    - App-name-first label option — A %s string resource formats "WM Keyboard - <language>"
  - Per-app language memory `uncommon` — Remembers the layout you explicitly switched to in each package and restores it
    - Only explicit picks are stored — Apps with no stored pick follow the last-used layout globally
    - Stale ids self-heal — A remembered layout that no longer resolves to itself is ignored
  - Field-driven language overrides `uncommon` — The focused field can outrank both the active layout and per-app memory
    - IME_FLAG_FORCE_ASCII is a hard constraint — Outranks a hintLocales preference, which is only ever a hint
    - hintLocales picks the first layout of the matching enabled language — The field names a language, not a layout
    - Field-scoped, never persisted — The override dies with the field
  - Secondary-language suggestions `uncommon` — "Also suggest from" blends other enabled languages' words in without switching to them
    - Blended words are exempt from autocorrect — A borrowed word is not corrected back
    - Long-term mix confidence — Persisted decaying per-language usage weights the secondary tier, so a daily second language outranks a monthly one
    - Fast per-field language mix — Seeded from text already in the field, updated per commit, decayed per word, never persisted - swings back within two or three words on a code switch
- **Notation pseudo-languages** `RARE` — Four non-language entries that behave like languages: IPA, music, braille, Morse
  - IPA `RARE` — Four layers: pulmonic consonants, vowels, clicks/implosives/ejectives, diacritics and suprasegmentals
    - Long-press variants — p long-presses to pʰ, ⁱp, p̚
    - Rides Latin fonts — No pinned face needed - Latin faces carry IPA Extensions and the modifier letters
  - Musical notation `RARE` — Two layers over the Musical Symbols block plus BMP ♩♪♫♬; Fn layer holds dynamics, ornaments, repeats
    - Exists as its own script mainly to pin a font — Noto Music, because device fonts rarely carry the SMP block
  - Chorded braille `RARE` — Six-key Perkins chord; the cell commits when the last finger lifts
    - Dot keys fire on press, not release — No long-press timer, unlike every other key
    - Grade-1 English decoding — a-z, 8 punctuation cells, dot 6 as capital indicator, dots 3456 as number mode until a non-digit cell
    - Unknown chords commit the raw cell — U+2800 + mask, which doubles as a way to type the Braille Patterns block
    - Half-chords never survive a context change — Field switch, layout switch or panel open resets it; a pointer stolen by the glide handler still counts as lifted
  - Morse code `uncommon` — Two big keys; ITU-R M.1677-1 table covering 26 letters, 10 digits and 20 punctuation marks
    - Fixed 750 ms commit pause — Each signal restarts the timer; no setting to change it
    - Backspace edits the sequence — Drops the last signal, only falling through to a real delete once nothing is pending
    - Live readout in the suggestion strip — Sequence in dot/dash glyphs plus the letter it currently spells
    - Rides Latin script — Autocapitalise and shift still apply to the decoded letters
    - Rolling SOS window — An 8-character buffer watches for "sos" to fire an easter egg
- **Fancy text** `uncommon` — 22 Unicode styles applied at draw and commit time over one plain QWERTY grid
  - 22 styles `uncommon` — Bold, Italic, Bold Italic, Script, Bold Script, Fraktur, Bold Fraktur, Double-struck, Sans, Sans Bold, Sans Italic, Sans Bold Italic, Monospace, Fullwidth, Circled, Circled Filled, Squared, Squared Filled, Small Caps, Superscript, Strikethrough, Underline
    - WYSIWYG keys — The style substitutes on the key labels and on what a tap commits; the stored layout stays plain a-z
    - Style strip with plain-name dropdown — Each chip written in its own style, with a text list for glyphs the device cannot render
    - Two Unicode techniques — Precomposed Mathematical Alphanumerics for most, combining marks over ASCII for Strikethrough and Underline
    - Case coverage varies — Small caps, superscript, squared and circled-filled have no capitals; superscript has no q
  - One layout, not 22 `RARE` — The 22 old per-style asset ids canonicalise onto asset_fancy at read time
    - Editing applies across every style — Because the base grid is a single ordinary layout
  - Fancy-text toolbar tool `uncommon` — Turns the fancy keyboard on and off from the keyboard, adding and removing the language as needed
    - Three settings — Style to start with (or last used), keep the language after turning off, turn off when the keyboard closes
    - Return-layout tracking — layoutAfterFancy returns to where you came from, or the first remaining stop, or the built-in default
    - Hardware leader key then F — Reachable from a physical keyboard

**Conditions and gating**

| Feature | Needs |
|---|---|
| CJK conversion dictionary packs (pinyin, ja_kana, jyutping, stroke, cangjie) | network download required - none are bundled; until downloaded the composer shows the buffer but no candidates. Both flavours. |
| Downloadable word lists, emoji keyword packs and n-gram packs per language | network download; prompted once when adding a language |
| Region-based language suggestions | reads TelephonyManager SIM/network country - no permission needed, but absent on Wi-Fi-only devices (falls back to time zone, then locale) |
| Per-script pinned fonts and per-script font pickers (Noto Music, Noto Sans Symbols 2, Noto Sans <script>) | fetched through the Google Play Services downloadable-fonts provider; on a GMS-free or offline device the async font falls back to the platform default |
| Android subtype auto-enabling for every layout | needs API 34+ (setExplicitlyEnabledInputMethodSubtypes); on Android 13 and below the user must tick languages in system settings |
| Layout import from FlorisBoard/HeliBoard files, and addon-repo layout installs | file picker / repository URL; foreign files capped at 4 MB |
| Everything else in this area (845-language registry, 1,274 layouts, all composers, Avro, Bengali spelling maps, fancy text, notation layouts, layout editor) | no flavour gate - :core:language and :core:input have no full/lite source sets, so all of it ships in Lite too |

## Themes and appearance

- **Built-in theme gallery** — 28 shipped looks in 12 gallery entries, plus a Default (system) card
  - Original themes — 18 in-house looks across 8 gallery entries
    - Ocean family — 9 looks: Ocean, Forest, Sunset, Berry, Crimson, Slate, Deep sea, Sunset drift, Aurora
    - Snow family — 5 light looks: Snow, Mint, Rose, Sand, Glacier
    - Pitch black — AMOLED-friendly true-black board with near-black keys
    - Nebula — 3-stop linear board gradient, translucent keys
    - Shape showcases — Bubble (pill keys, radial glow) and Facet (cut corners, 1dp border, key sheen)
    - Animated built-ins — Sunset drift (FLOW), Aurora (HUE_CYCLE at 0.6x), Cyberpunk (FLOW at 0.7x)
  - Editor colour-scheme ports `RARE` — 11 palette themes in 6 entries, hexes copied verbatim from upstream specs
    - Catppuccin family — All 4 upstream flavours: Mocha, Latte, Frappé, Macchiato
    - Solarized family — Dark + Light; both draw a base01/base1 outline because the spec's tones are 1.2:1
    - Dracula family — Dracula plus Alucard, its upstream light half; Alucard presses to a Selection/Comment blend because Comment alone leaves the label at 2.8:1
    - Nord, Tokyo Night — Surface ramps mapped to board/key/modifier/pressed roles
    - Cyberpunk — Original neon palette; cut keys, translucent faces, neon outline, animated gradient
    - Per-theme WCAG check — Contrast checked per element; deviations from upstream documented in code comments
    - MIT notices shipped — assets/licenses/mit-color-themes.txt listed in the About screen
  - Default (system) theme — Not a stored spec; derived live from the Material scheme
    - Material You dynamic colour — Wallpaper palette on Android 12+; also recolours the settings app
    - Mode switch — System / Light / Dark / Amoled; Amoled forces a pure-black board
    - Dark-blend surfaces — Keys are onSurface blended over a darkened board, not surfaceContainer roles
    - Neutral pressed state — Press shifts toward the text colour, never flashes the accent
  - Gallery presentation
    - Grouped or flat — ThemeGalleryStyle AUTO/GROUPED/FLAT; AUTO follows the onboarding persona depth
    - Two-column cards — Default card, then customs, then built-ins, each with a live mini-preview
    - Per-card actions — Apply, edit (duplicates a built-in), export, delete, pin to keyboard panel
  - Keyboard-side Appearance tool `uncommon` — Full-bleed panel with live mini-previews over the keys
    - Shortlist, not gallery — All custom/downloaded themes plus user-pinned built-ins; 6 pinned by default
    - Icons tab — Same panel switches to icon-pack selection
    - Emoji tab — System, Google, every installed emoji face and an imported file, each card drawn in that font
    - Fonts tab — Key label fonts per script, opening on the script being typed
    - Store link — Every grid ends on the add-on repository filtered to that kind
    - Read-only while locked — Auto theme or a mode-carried theme makes taps preview-only
- **Variant families** `RARE` — One theme carries up to 12 alternate looks (MAX_THEME_VARIANTS)
  - Family model `RARE`
    - One level deep — Variants-of-variants are stripped on every write and import path
    - Globally unique variant ids — Selection, pins and auto-theme slots address a variant directly
    - Family label — familyName on custom families; built-in families use a translatable string resource
    - Representative look — The parent spec is itself the first look, not an empty container
  - Variant swatch dots `RARE` — One coloured dot per look on the card; tapping previews and applies
  - Editing a family `RARE`
    - Chip row per look — Editor opens on the routed look; every write goes through replacingMember
    - Add look — Duplicates the open look; image paths are shared, not copied
    - Delete one look — Files stay for the 24h sweep because siblings may point at them
  - Import becomes a family `RARE` — A multi-theme FlorisBoard extension is grouped under the extension title
  - Id reminting on import `RARE` — withFreshIds rewrites parent and every variant so extracted image filenames stay unique
- **Automatic light/dark pairing** `uncommon` — Two chosen theme ids swap on their own; overrides manual selection entirely
  - Triggers `uncommon` — 3 options
    - System light/dark — Recomposes on the OS setting with no clock at all
    - Time of day — Two clock times; the window wraps correctly across midnight for night shifts
    - Sunrise & sunset — Computed on device from the weather tool's saved location, no network call
  - Fallbacks `uncommon`
    - No location or polar day — Sun trigger falls back to the system light/dark setting
  - Live re-evaluation `RARE` — Clock/sun triggers re-check on the minute boundary while the keyboard is on screen
  - Single resolution point `uncommon` — effectiveThemeId/activeThemeSpec so the painting spec and the override spec cannot disagree
  - Any id in either slot `uncommon` — Default, built-in, variant or custom id in the light and dark slots
- **Theme editor — colour** `uncommon` — 24 colour rows across 6 sections, live mini-keyboard preview pinned on top
  - Colour slots `uncommon` — 24 editable colours
    - Keys — Letter, key text, modifier, modifier text, enter, enter icon, pressed, border
    - Accent & popups — Accent, glide-trail colour, popup fill, popup text, popup border
    - Toolbar — Tool icons, tool circle, active tool circle, tool border
    - Panels & chips — Card fill, suggestion text, chip text, active chip, active chip text, chip border
    - Alpha is first-class — Board, keys, modifiers, gradient stops and trail take ARGB with real alpha
  - Auto-derived nullable slots `uncommon` — Unset colours derive a legible value; the picker's Auto button clears back to derived
    - Contrast-guarded fallbacks — legibleOn picks the first candidate at 3:1 or better, else black/white
    - Board-vs-key inversion handled — Suggestion text falls back to key text only if legible on the board
  - Colour picker
    - HSVA sliders — Hue, saturation, brightness, and opacity when the slot supports alpha
    - Hex field — Accepts 6- or 8-digit hex, echoes the current ARGB
    - 21 preset swatches — 15 seed swatches plus 6 neutrals; presets keep the current alpha
  - Start from a colour (seed) — 15 seed swatches rebuild the whole palette
    - Reseed keeps non-generated fields — Gradients, image, credit, shape, border, radii and animation survive a reseed
    - Alpha preserved over photos — Regenerated opaque colours re-take the previous alpha when a background image exists
    - Dark switch reseeds — Flipping light/dark rebuilds the palette from the current enter-key colour
  - Gradient editor `RARE` — Separate gradients for board and letter keys
    - 3 gradient types — Linear, radial and sweep; angle slider on linear and sweep
    - 2–4 colour stops — Add/remove stops, each with its own alpha
    - Live strip preview — The row draws the actual shader brush the keyboard will use
  - Per-key style overrides `RARE` — A named key gets its own colours, image, press burst and label weight
    - Letter keys by label — Override follows the lowercase letter across layouts and languages
    - 7 special keys — Enter, Space, Shift, Delete, Symbols, Emoji, Language switch
    - 6 colours each — Background, text, hint, border, popup background, popup text — all nullable
    - Per-key image — One key's own texture, drawn at the board's texture fit and opacity; beats the class texture, works with no class texture at all
    - Per-key press burst — Stars, hearts, sparkle, confetti or the key's own emoji; the board's intensity and physics still shape it, and one key's burst is enough to give a board with no effect a particle field
    - Per-key label weight and size — Bold as a three-way answer (follow the board, on, off), and a label size that replaces the automatic rule; a size the layout authored wins over the theme's
- **Key shapes and geometry** `RARE` — 12 shapes, applied independently to 6 surfaces
  - 12 key shapes `RARE` — Picker draws each one rather than naming it
    - No shape — Keys only: labels on the bare board, a rounded flash on press, latched modifiers and single-key faces still lit
    - Radius-following — Rounded, sharp, cut and ticket honour the corner-radius slider
    - Proportional shapes — Pill, squircle, arch, leaf, slant, hexagon, scallop, circle size corners from the key
    - Squircle — n=4 superellipse sampled as a 64-gon
    - Scallop — Bump count derived per side so a spacebar gets more bumps, not longer ones
    - Ticket — Rectangle minus a circle at each corner, built as a path difference
    - Slant bleed — Parallelogram spills half its lean into the key gap so keys keep full width
    - Circle degrades to stadium — Boxes over 1.6:1 from square draw a stadium so labels are not clipped
  - Per-surface shapes `RARE` — 6 independently themeable outlines
    - Key, popup, tool, chip — Each has its own shape field and its own radius
    - Menu and card shapes — List popups and panel cards; auto-derive safely from popup/chip shape
    - Safe container rule — Decorative shapes fall back to rounded on text surfaces unless explicitly set
  - Corner radii overrides — Key, popup and tool radii; null follows the global appearance sliders
    - Chip radius — Own override, defaults to a 12dp soft rectangle
    - Zero tool radius — A 0 tool radius means no tool background at all
  - Key borders — Colour plus 0–3dp width, separately for keys, popups, chips and tools
- **Image backgrounds** — Local image behind the board, with the board colour acting as scrim
  - Two orientation slots `RARE` — Portrait and landscape images; landscape falls back to portrait
    - Independent credits — Each slot carries its own PhotoAttribution
    - Separate crop per slot — Both slots get their own cropper entry
  - Adjustments
    - Opacity — 0–100% alpha on the image itself, shared by both orientations
    - Blur 0–25 — GPU RenderEffect on API 31+, downscale/upscale below it
    - Board scrim — Picking an image zeroes the board alpha and softens key fills automatically
  - Animated backgrounds `RARE` — GIF / animated WebP played through Coil while the keyboard is on screen
    - Mutually exclusive with blur — Enforced in the editor and re-checked in the resolver
    - Degrades to first frame — Reduce motion, power saving or an older build draws the still frame
  - Built-in cropper `uncommon` — Pinch/drag over a fixed frame, cover-scaled
    - 3 aspect presets — 2.4:1 keyboard band, 1.7:1 wide, 1:1 square
    - Zoom 1–6x — Pan clamped so the frame is always filled
    - Writes a new JPEG — Quality 92 into the theme-images folder; source downsampled to ~2048px first
  - Decode cache `uncommon` — Shared by the keyboard and the settings previews
    - Size-bucketed LRU — 128px buckets, budget maxMemory/16 clamped to 4–24MB
    - EXIF-correct sampling — ImageDecoder one-pass target sizing on API 28+
    - Trim callbacks — Halves or empties on the IME's memory-trim levels
    - mtime in the cache key — A re-cropped file at the same path never serves a stale bitmap
  - Orphan sweep `uncommon` — Unreferenced background/texture/decal/effect images deleted after 24h unreferenced
    - Walks whole families — Variants' images and rotation states are counted as references
    - Age guard — Nothing is deleted inside the window where the picker writes before the theme saves
- **Online photo backgrounds** `RARE` — Two stock-photo services searched from inside settings
  - Providers `RARE` — Unsplash and Pexels, interleaved round-robin in one grid
    - API keys — Build-baked key or a user-supplied key per provider; provider absent when blank
    - Rate-limit tracking — Budget parsed from response headers; quota-spent state shown in the grid
    - Provider-aware sizing — imgix params with entropy crop for Unsplash, smallest covering variant for Pexels
  - Search filters `RARE`
    - 12 curated topics — Wallpapers, nature, textures, minimal, architecture, space, animals, travel, food, street, colour, dark
    - 14 colour swatches — Colour-only searches fall back to searching the colour's English name
    - Landscape-only toggle — On by default — a board is a wide, short strip
    - Safe search — Unsplash content_filter=high; Pexels has no equivalent
  - Keyboard-band guide `RARE` — Grid tiles dim the strips the crop throws away, matching the cropper's 2.4:1 default
  - Attribution handling `RARE`
    - Credit stored on the theme — Photographer, links and photo id survive export, import and going offline
    - Referral tagging at use — utm_source/utm_medium added when the link is opened, so the slug is never stale
    - Unsplash download tracking — One authorized GET per real download, deduped in a 60s window, failure ignored
    - Credit travels with the image — Export drops the attribution when the image bytes could not be embedded
    - Thumbnails hotlinked — Grid loads from the provider CDN so view counts reach the photographer
  - Photo collection `RARE` — Saved service photos and copies of device photos, reusable across themes
    - Auto-collect — Any photo made into a background is copied into the collection
    - Keyed by photo id — The same service photo used on two themes is stored once
- **Rotating background** `RARE` — A pool of photos rotated behind the board on a schedule
  - 6 intervals `RARE` — Every open, hourly, 6-hourly, daily, weekly, manual (Shuffle only)
  - 3 scopes `RARE` — Current theme, all themes, or a chosen set of theme ids
  - Applied at draw time `RARE` — Rotation never rewrites the stored theme, so built-ins can rotate too
  - Pool management `RARE`
    - Target 3–20 photos — Default 8; kept ready so a change is never a wait
    - Unseen-first picking — Never-shown photos first by age, then least-recently-shown with random tie-break
    - Eviction rules — Never drops unseen or user-saved photos; 24MB budget, 3x-target headroom
    - Eviction memory — Last 64 evicted photo keys remembered so a top-up doesn't refetch them
    - Feed paging — Top-ups walk up to 20 pages deep instead of re-reading page 1
  - Network gating `RARE` — Rotation itself never needs network; only refills stop
    - Metered opt-in — Off by default
    - Blocked while locked — Pool lives in credential-encrypted storage
    - Power saving and high-contrast — Both stop top-ups entirely
    - One-per-hour floor — MIN_FETCH_PERIOD_MS caps requests whatever the interval says
  - Palette seeding from photo `RARE` — Optional: each new photo reseeds the theme's colours
    - Deterministic histogram — 5-bit-per-channel buckets, saturation-weighted, near-greys set aside unless nothing else
    - Spread-out swatches — Candidates closer than an L1 distance of 90 are dropped
    - Measured at download — Seed and scrim computed once, not on the keyboard-open path
  - Readability guard `RARE` — Adds only as much board scrim as the keys need
    - WCAG contrast model — Composites photo, image opacity, board alpha and key alpha to find luminance behind labels
    - Scrim search — Alpha walked in 0.02 steps to hit 4.5:1, capped at 0.65 so the photo survives
    - Busy-photo detection — Brightness variation over the key band, damped by blur radius
    - Verdict bands — poor <2.0, marginal <3.0, busy >0.22 variation, else good
- **Decorations** `RARE` — Textures, stickers, particles, animation, fonts and sounds carried by the theme
  - Key textures `RARE` — 6 image slots drawn over the key colour, clipped to the key shape
    - Slots — Letter, modifier, enter, space, pressed, popup bubble
    - Fallback chain — Enter falls to modifier falls to normal; space falls to normal
    - 3 fit modes — Crop (centre-crop, default), stretch, tile
    - Opacity 10–100% — Applied over the key colour
    - Draw-cache only — Textures resolve inside drawWithCache, so they cost nothing per keystroke
  - Decals (stickers) `RARE` — Up to 6 images laid over the key grid, touch-transparent
    - Normalized placement — x/y as fractions of the grid so a decal keeps its place across widths and orientations
    - 5 sliders each — X, Y, size 5–80%, rotation -180..180°, opacity 10–100%
    - Adjusted over live preview — The dialog draws the same DecalsCanvas the keyboard uses
  - Key-press particle effects `RARE` — 6 kinds of burst on every key press
    - Built-in kinds — Stars, hearts, sparkle, confetti — 3–5 pre-rasterized glyphs each
    - Custom emoji — Up to 8 typed emoji, each glyph its own particle kind
    - Custom images — Up to 6 user PNGs as particle kinds
    - Intensity 0.4–2.4x — Base burst of 5 particles, clamped 1–12
    - Allocation-free field — Preallocated arrays, stateless physics, loop exits when the last particle dies
    - Motion gating — Never plays under reduce motion, power saving or high contrast
  - Board animation `RARE` — 2 live animations plus a 0.25–3x speed multiplier
    - FLOW — Slides a linear gradient (mirror-tiled), orbits a radial centre, spins a sweep
    - HUE_CYCLE — Rotates every stop's hue, or the solid board colour
    - On-screen only — One ~16s cycle at 1x; no infinite transition runs under reduce motion
  - Theme-carried font `RARE` — fontId in the same namespace the font system uses
    - Precedence — Sits under the user's own pick and under each script's automatic Noto face
    - Missing font degrades — An uninstalled id resolves to null and falls through to the global setting
  - Per-script theme fonts `RARE` — scriptFontIds map keyed by script name; 22 scripts have curated pickers
    - Beats the automatic Noto face — So a pixel theme with a pixel Bengali font keeps its look on a Bengali board
    - Still loses to the user's pick — A deliberately chosen per-script font is never overruled by a theme
    - Unknown script key costs its entry — String keys, not the enum, so one bad entry never drops the theme
  - Theme-carried key sound `RARE` — soundStyle name plus an installed-sound id
    - 6 built-in styles — Click, standard, pop, thock, chime, pack; plus any installed sound
    - Preview on tap — Picker plays each row as it is selected
    - Missing sound falls back — An unknown id or style name reverts to the global sound setting
- **Theme-carried layout overrides** `RARE` — 11 sizing/type fields a theme may set; null follows the user's globals
  - Fields `RARE`
    - Sizing — Key height, toolbar height, tool width, popup height, key gap scale, side padding scale
    - Type — Font scale, bold key labels, hint font scale
    - Glide trail — Trail width and trail opacity
  - Strict precedence `RARE` — Device form, then mode overlays, then theme, then per-screen sizing wins last
  - Instance-stable no-op `RARE` — A theme with no overrides returns the same settings object so callers' remembers hold
  - Never touches theme selection `RARE` — Refuses to write themeId, autoTheme or customThemes back, which would loop
- **Fonts** `uncommon` — Key-label typeface system the theme plugs into
  - 20 curated Google Fonts `uncommon` — Sans, serif, mono and display faces for Latin
  - 27 automatic script faces `RARE` — A Noto face per non-Latin script so a display font never blanks a board
    - Notation scripts included — Noto Music and Noto Sans Symbols 2 for the music and braille pseudo-layouts
  - 22 per-script pickers `RARE` — Curated alternatives per script, e.g. 9 for Thai, 9 for Korean, 9 for Chinese
  - Imported font files `uncommon` — Installed fonts addressed as installed:<id>; Bengali also takes a direct file import
  - Separate emoji font `RARE` — Own family and its own glyph-coverage shaper, kept apart from the text font
    - Per-emoji fallback — An emoji the chosen font half-covers is drawn in the system font instead
- **Icon packs** `RARE` — 97 replaceable icon slots across the keyboard chrome
  - Slot inventory `RARE` — 64 tool icons + 14 key icons + 6 chrome icons + 13 emoji tabs
    - Tool slots derived — One per ToolbarTool entry, so a new tool becomes customisable automatically
    - Key slots — Shift/shift-on/caps, backspace, forward delete, globe, emoji, 7 enter actions
    - Chrome slots — Toolbox, panel back, suggestions expand, emoji shortcut, search close, incognito
    - Layout glyphs excluded — Per-key icons chosen by a layout author are deliberately not overridable
  - .wmicons pack format `RARE` — ZIP with pack.json plus icons/<slotId>.svg
    - Entry names never used as paths — Files written to a name derived from the matched slot id
    - Repair-and-report import — Bad SVGs and unknown slots are dropped with a per-line explanation, not a refusal
    - Zip-bomb caps — 400 entries, 8MB total
    - Up to 20 installed packs — Plus a built-as-you-go 'mine' pack for single-slot imports
  - Per-slot overrides `RARE` — A slot can take one of 181 bundled Material glyphs or an icon from any installed pack
    - CSV storage — slot=b:<name> or slot=p:<packId>; unknown slots dropped, missing packs kept
  - Per-tool icon colours `RARE` — Default accent per tool, user override, and an optional two-colour gradient
    - Derived gradient end — Far end follows the near end until the user pins it down
- **Import, export and sharing** `uncommon` — .wmtheme.json plus a FlorisBoard converter and repo installs
  - Export `uncommon` — Plain JSON so file managers and chat apps will carry it
    - Images embedded — Backgrounds, textures, decals and effect images travel as base64, local paths nulled
    - Whole family or one look — A grouped card exports the family; a flat card exports the shown look alone
  - Import `uncommon`
    - Permissive MIME — json, text/plain and octet-stream all accepted; content is the real check
    - File-open intent — Opening a .wmtheme.json from any app lands in the importer (4 dot-depth patterns)
    - Images extracted to disk — withExtractedImages writes files keyed off freshly minted ids
    - Forward-compatible fields — Shapes, placement, provider and script keys travel as strings so unknown values cost one field
  - FlorisBoard .flex import `RARE` — Reads the snygg v2 stylesheet inside a theme extension
    - Honest lossiness — Reports rules read vs rules mapped, and names what was dropped
    - 7 unsupported categories — Elevation, per-corner radius, per-element spacing, font, dynamic colour, unknown element, low contrast
    - Refuses snygg v1 — FlorisBoard 0.4 dialect rejected outright rather than half-converted
    - No guessing — A field is written only when the sheet says something unambiguous about the same surface
    - Licence and authors carried — Extension metadata kept so it can be shown, not dropped
    - Written from the published format — No FlorisBoard source used — Apache-2.0 upstream vs MIT here
    - Zip guards — 256 entries, 16MB total, 256KB manifest, 4MB per image
  - Addon repository themes `RARE` — Themes installed from a user-added repo URL become ordinary custom themes
    - Dependency prompt — A theme's requires list can pull in the font and sound addons it names
    - Use button lands on the card — A family card answers for every id it holds
    - Uninstall reconciles — Removing the addon deletes the custom theme it created
- **Accessibility and adaptation** `RARE` — Applied after theme resolution so it works on built-in, custom and dynamic themes alike
  - Colour-vision correction `RARE` — Daltonization, not simulation — 4 filters plus grayscale
    - Pipeline — sRGB → LMS, collapse the missing cone, back to RGB, redistribute the error into green/blue
    - Protan/deutan/tritan — Viénot/Brettel-derived matrices
    - Grayscale mode — Rec.709 perceptual luminance, so equal-luminance hues collapse and failures show
    - Alpha untouched — Scrims and ghosted keys keep their translucency
    - Runs before contrast — So the forced-contrast pass gets the last word after hues shift
  - High-contrast keys `uncommon` — Forces a black/white board, fixed key tones and max-contrast text
    - Strips decoration — Gradients, images, textures, decals, per-key overrides, particles and animation all dropped
    - Also pushes the board — Key shapes stay visible, not just labels
  - Key outlines — 1.5dp outline at 45% (90% under high contrast), only where the theme drew none
    - Tools too — Applied to tool backgrounds separately, and only when the tool radius is non-zero
  - Theme crossfade `RARE` — 320ms ease across every colour, gradient, radius and width on a theme switch
    - Interruptible — A second tap restarts from the currently blended colours, not the stale endpoint
    - Discrete fields snap — Shape kind, image path, blur radius and tool width flip at the midpoint
    - Solid⇄gradient blends — A missing gradient is promoted to a flat gradient of its side's solid colour
    - Skipped for reduce motion — And on first composition, so opening the keyboard never fades
  - Direct boot `RARE` — Custom themes render before first unlock with their image paths stripped
    - Recurses into variants — Variant images live in the same credential-encrypted directory
  - Per-mode theme `RARE` — A keyboard mode can carry its own theme id, which locks the Themes panel read-only

**Conditions and gating**

| Feature | Needs |
|---|---|
| Material You / dynamic colour | Android 12+ (Build.VERSION_CODES.S); the switch shows but does nothing below |
| Google Fonts (key font, per-script fonts, theme font picker) | needs the Play Services downloadable-font provider; the list is empty without it |
| Online photo search (Unsplash / Pexels) | needs network plus an API key — a build-baked key or one the user supplies per provider |
| Unsplash download tracking and credit links | needs network; link opening leaves the app |
| Rotating background top-ups | needs network, an unlocked device, and is blocked on metered data by default, under power saving, and under high-contrast keys |
| Auto theme: sunrise & sunset trigger | needs a location saved by the weather tool; falls back to the system setting without one |
| Picking a background, texture, decal or particle image | uses the system photo picker (PickVisualMedia) — no storage permission, but a user pick each time |
| Rotating background pool and theme background images | credential-encrypted storage — unavailable before first unlock; direct boot strips image paths |
| GPU background blur | API 31+ RenderEffect; below that the blur is baked into the decode |
| Animated GIF/WebP backgrounds | played via Coil; falls back to the still first frame under reduce motion or power saving |
| Theme / icon-pack / font / sound addon installs | needs network and a user-added addon repository URL |
| Theme-carried fonts and sounds | ship as separate addons listed in the theme's requires; a missing one silently falls back |

## Emoji, GIFs, stickers, kaomoji

- **Emoji catalogue & bundled data** `uncommon` — Five generated asset files under app/src/main/assets/emoji/, ~550 KB total, all from Unicode/CLDR/gemoji.
  - Full Emoji 17.0 catalogue `uncommon` — catalog.tsv: 1,914 rows — 1,717 base grid entries plus 197 gender/role variants.
    - 10 categories — people 388, flags 270, objects 266, symbols 223, travel 172, smileys 171, animals 131, food 131, activities 85, nature 76
    - Gender/role variants collapse under a parent — woman-running → runner, man-health-worker → person-health-worker; variants stay searchable, grid shows only the base
    - Unicode short name per entry — Sixth TSV column; shown at the top of the long-press popup
    - Sky & weather remapped — Unicode's sky/weather group is folded into the app's nature tab
  - Bilingual keywords shipped in the catalogue `RARE` — English + Bengali CLDR annotations merged into one index, plus hand-curated additions.
    - One language-agnostic index — বিড়াল and "cat" hit the same rows; no language selector anywhere in search
  - RGI skin-tone table `RARE` — variants.tsv: 2,030 exact fully-qualified sequences over 330 base emoji.
    - 19 dual-tone bases — 380 rows carry two independent Fitzpatrick indices (handshake, couples, holding hands)
    - No runtime composition — Only sequences Unicode lists as RGI are offered, so no unsupported combination can be built
  - Shortcode table `uncommon` — shortcodes.tsv: 1,936 :tada:-style GitHub/Discord/Slack names.
  - gemoji trigger table `RARE` — triggers.tsv: 2,121 word→emoji rows; names under 3 chars dropped so flag codes never fire.
  - Animated-emoji index `RARE` — animated.txt: 881 code-point spellings that have a Noto Animated Emoji asset.
  - Regeneration pipeline in-repo `uncommon` — tools/emoji/: generate_catalog, generate_gemoji, generate_animated, generate_dict_catalog, export_keyword_pack, add_names.
- **Emoji search** `uncommon` — Semantic, multilingual, typo-tolerant search over the merged catalogue.
  - Six scoring layers that stack `RARE` — Exact shortcode 1000 > shortcode prefix 500 > exact keyword 100 > synonym 60 > keyword prefix 40 > fuzzy 30.
    - One-typo fuzzy matching — Damerau-Levenshtein distance exactly 1, for query tokens of 4+ characters
    - Curated synonym expansion — 43 concept keys (7 Bengali): party→celebration/confetti, fire→flame/comet
    - Underscore-as-space normalisation — face_with_monocle reaches the catalogue directly, so the shortcode table only carries names that differ
    - Multi-token accumulation — Scores from several query words add up before ranking
  - Downloadable keyword packs `RARE` — 125 languages from the app's data repo (gzipped CLDR-derived JSON, 148 B–112 KB each).
    - Auto-download per enabled language — On by default; gated behind the global "download language data" switch too
    - Declined marker — Deleting a pack writes a marker so auto-download does not re-fetch it
    - Queued, not raced — Requests queue one at a time so an all-languages pass loses nothing
    - Converted at download time — Repo JSON is decoded to TSV once rather than parsed on every keyboard start
  - Hand-imported keyword packs `RARE` — filesDir/emoji_keywords/<lang>/*.tsv, several per language, additive.
    - Format sniffing — A leading [ is read as the data repo's JSON; anything else as TSV
    - Import from file or URL — SAF picker or an http(s) URL; 8 MB cap enforced on the stream, not the reported size
    - Filename sanitised — Path segments stripped, non-alphanumerics replaced, collisions get a numeric suffix
    - Zero-emoji imports deleted — A file that parses to nothing is removed and reported as 0 rather than sitting inert
  - Per-language emoji names `RARE` — Keywords stack across packs; names resolve per typed language, never last-pack-wins.
    - Falls back to the Unicode name — A Spanish pack never renames emoji while Bengali is the language being typed
  - Search examples in the user's own languages `RARE` — Settings copy picks money/birthday words from 29 languages by enabled-language order.
- **Emoji panel** — Tabbed pager over the catalogue with its own search mode and key row.
  - Category pager — One category composed at a time; horizontal swipe crosses tabs, per-tab scroll offset kept.
    - Stable per-tab keys — A tab keeps its scroll and its open popup as history appears and shifts indices
    - Cells keyed by emoji — Favouriting reorders the history grid without a popup jumping to another emoji
  - In-panel search driven by the real keys `RARE` — Tapping the search pill turns the letter keys into a query editor; text never reaches the document.
    - Separate field backspace — An icon beside the pill deletes from the actual text field without leaving search
    - Script-aware typing — Fixed-layout contextual vowel rules apply to the query, so Bengali types correctly into it
    - Search pill sits below the grid — Emoji stay at the top of the panel near the thumb, field next to the keys typing into it
  - Full-bleed mode `uncommon` — On by default: toolbar, emoji row and symbol row hide, tabs move up beside a back button.
    - Height accounting — The panel absorbs every reclaimed row so the keyboard never resizes on a panel switch
  - Bottom control bar `uncommon` — abc / spacebar / hold-to-repeat backspace on the real 10-unit key grid.
    - Repeat stops at an empty field — Backspace repeat honours the same canDelete gate and repeat cadence as the real key
    - Language-agnostic spacebar label — Shows "Space" rather than the language name; a custom label still applies via %s
  - Three ways in `uncommon` — Toolbar tool, globe key replaced by emoji (on by default), or comma key replaced (off).
  - Tab icons are icon-pack slots `RARE` — emoji_tab.search / .recent / .most_used plus one slot per catalogue category.
  - Hardware-keyboard navigation `RARE` — Focus regions for chips, search and the grid, with a drawn focus ring and scroll-into-view.
  - Return to keys after inserting `uncommon` — Optional; closes the panel after a single emoji, kaomoji or paste.
  - Hide emoji this phone cannot draw `RARE` — Off by default; hides only what neither the chosen font nor the system font can render.
    - Two different probes — Paint.hasGlyph for the system chain, font-table reading for the chosen file
- **Skin tones & variants** `uncommon` — Fitzpatrick tones, dual-tone pairs and gender/role members, all from the RGI table.
  - Global default tone — 6 options (neutral + 5); applied in the grid, search results and the suggestion strip.
  - Per-emoji last-used tone `uncommon` — Persisted per base emoji; "override with last used" (on by default) puts it ahead of the default.
  - Long-press variant popup — Neutral base plus five tones, six per row, over the favourite/remove rows.
    - Name header — Unicode short name (or the typed language's name) at the top, toggleable
    - Gender/role members listed first — Runner → woman/man runner; each member then offers its own tone row
  - Two-slot dual-tone picker `RARE` — Independent tone per person for 19 bases; live preview commits the exact RGI sequence.
    - Non-RGI combinations avoided — Picking a tone on one side seeds the other, since toned+neutral has no RGI form
- **Favourites, recents & most used** `uncommon` — JSON usage file holding recents, counts, favourites and per-emoji variant picks.
  - History tab — Recents (32 max) or Most used, chosen by setting; favourites pinned to the front of both.
  - Favourites `uncommon` — 64 max, toggled from any long-press popup, pinned ahead of usage everywhere.
  - Drag-to-reorder favourites inside the keyboard `RARE` — Modal reorder list over the IME window, reached from a starred emoji's popup.
    - Only offered at 2+ favourites — The row is absent until there is something to shuffle
    - Never silently drops a favourite — A partial order is repaired by appending the missing ones at the tail
  - Remove one emoji from history `uncommon` — Popup row on history cells; clears recents, counts and the pin at once.
  - Optional clear-recents button `uncommon` — Off by default, and only on the Recent view — not on the frequency ranking.
  - Dirty-flag persistence `uncommon` — Saved on keyboard dismissal only when something changed; reload path for a restored backup.
- **Emoji prediction & inline entry** `uncommon` — Emoji in the suggestion strip while typing, plus colon-driven inline search.
  - Word→emoji suggestions, four stacked layers `uncommon` — Curated table (78 words, 25 Bengali) → gemoji triggers → exact shortcode → catalogue keywords.
    - Curated ordering — "birthday" leads with 🎂 rather than 🥳; the Bengali triggers live here too
    - Two-word phrase hits — The previous word is passed in, so "alarm clock" → ⏰ and "crossed fingers" → 🤞
    - Trailing plural stripped — A 4+ letter word ending in s retries without it when results are thin
    - Shortcodes only at 3+ chars — Two-letter codes are flags and enclosed letters, so :it:/:us: never fire on ordinary words
  - Learned bigrams that end in an emoji `RARE` — A next-word prediction that is emoji-only is routed to the emoji slot of the strip.
  - Replace vs append on tap — REPLACE (default, Gboard style) swaps the typed word; APPEND keeps it and adds the emoji.
    - Long press runs the other mode — A held suggestion inverts the setting for that one insert; the TalkBack long-click label names the action it will take
  - Inline :colon search `uncommon` — A colon at a word boundary turns the whole strip into emoji search; backspacing the colon ends it.
    - Mode is the buffer — "composing starts with a colon" is the entire state; nothing else tracks it
    - Closing colon auto-commits — Exact shortcodes only — :tada: becomes 🎉, an unknown name stays literal text
  - Suggestions honour the tone settings `uncommon` — Default tone and last-used override applied after the unrenderable filter.
  - Dropped under power saving `RARE` — Power Saving mode's dropEmojiPrediction forces emojiPrediction off while active.
- **Emoji fonts & rendering** `RARE` — The app ships no emoji font; it reads whichever font's own tables and respells per glyph.
  - Four font sources `uncommon` — System, Google Noto via the font provider, an installed addon face, or an imported file.
    - Installed faces come from the addon library — emoji_font addon type; listed separately from text fonts, falls back to System when deleted
    - Direct Noto download — Fetches the current build from the addon repo, since the font provider serves whatever it has
    - Provider-aware option list — The Google choice is hidden on phones with no Play services font provider unless already selected
  - Font-table coverage reader `RARE` — Parses cmap formats 0/4/6/12/13/14 and GSUB ligature lookups straight out of the sfnt.
    - Written because hasGlyph lies — Typeface.createFromFile appends the system fallback chain, so hasGlyph answers for the phone
    - Ligature check for ZWJ sequences — Knows before drawing whether 😶‍🌫️ collapses to one glyph or splits into its parts
    - Hardening — Bounds-checked reads, ttcf handling, sanity ceilings, 64 MB file cap; corrupt fonts yield empty coverage
  - Per-emoji spelling decision `RARE` — Undeclared U+FE0F is stripped so the chosen font wins the run instead of the system font.
    - Declared selectors kept — A font with a format-14 subtable has said which sequences it draws; stripping would ask for the wrong one
    - Per-glyph system-font fallback — When no spelling draws as one glyph, that single emoji is drawn in the system font
    - Cached and warmed off the main thread — Coverage keyed on path + mtime + length so a replaced font invalidates
  - Live font preview in settings `RARE` — Eight-emoji row rendered through the real shaping pipeline, not a mockup.
- **Animated emoji** `RARE` — Long-press any of 881 emoji to loop Google's Noto Animated Emoji and send it as a GIF.
  - Preview and send use different files `RARE` — WebP (~350 KB) loops in the popup; the button fetches the 512×512 GIF (~800 KB) to send.
    - Why the GIF — Apps that accept image/webp often draw only its first frame, which would make the button a liar
    - Button appears only after the preview — No control offering to send an animation nobody has seen
    - Download progress in the row — The spinner fills as a fraction while the GIF comes down
  - Bundled availability index `RARE` — Coverage is partial, so the set ships rather than being probed — no 404 round trip per long press.
    - Four spelling attempts — As authored, selectors stripped, selector added, then skin tones dropped last
  - Attribution shown in the popup `RARE` — CC BY 4.0 credit line under the send row wherever an animation is offered.
  - Counts as usage `uncommon` — Sending an animation records the emoji, so it lands in recents like a tap.
- **Emoji sent as a picture** `RARE` — Draws the emoji itself at 512×512 in the keyboard's font and sends it as a WebP sticker.
  - Offered on every emoji `RARE` — Nothing is downloaded — the glyph is on the device — so it works offline.
    - Solves the other phone's font — The receiver sees the face the sender saw, not a tofu box or a different vendor's art
  - Measured glyph fitting `RARE` — Drawn once at a nominal size, then scaled by the measured bounds so every sticker fills its frame.
  - Encoded by the sticker encoder `RARE` — Same 512 canvas, same lossy WebP, same 100 KB ceiling as a sticker from a pack.
  - Digest-keyed render cache `RARE` — Keyed on spelling + font choice + installed id; a 32-bit hash collided (😘 vs 🧹) so it uses a digest.
  - Follows the sticker send mode `uncommon` — One preference governs every sticker the keyboard sends, including this one.
- **Dedicated emoji row** `uncommon` — Gboard-style row of your own emoji between the toolbar and the keys.
  - Three modes `uncommon` — Off (default), Button (toolbar toggle swaps the strip), or its own permanent row.
  - Content choice `uncommon` — Most used, Recent or Favourites; favourites always sort to the front.
  - Density slider `RARE` — 3–16 slots (default 8); glyphs shrink into their slot, capped at 24sp against font scale.
  - Scrolling `RARE` — On by default so the seeded set past the visible slots is reachable; off pins the row so a sideways swipe cannot slide it out from under a tap.
  - Seeded before any history exists `uncommon` — 24 default emoji, more than fit across a phone, drawn with the user's default skin tone.
  - Row order configurable `RARE` — Emoji row, toolbar and symbol row can be arranged in any order via barOrder.
  - Hardware hotkey badges `RARE` — Row cells can carry hint badges from the hardware-keyboard hint plan.
- **Kaomoji & ASCII emoticons** `uncommon` — Two optional panel tabs, off by default, compiled in as plain data.
  - 201 kaomoji in 15 mood groups `uncommon` — Happy, Love, Sad, Angry, Table flip, Confused, Surprised, Cool, Cute, Animals, Actions, Sleepy, Greetings, Party, Apologies.
  - 111 ASCII emoticons in 8 groups `uncommon` — Happy, Sad, Playful, Love, Surprised, Neutral, Cool, Figures.
  - Auto-shrinking cells `RARE` — Font size steps down 12% at a time until the face fits one line; hidden until it settles.
    - Different column widths per tab — 132dp minimum for kaomoji, 64dp for emoticons
    - Never wraps or ellipsises — Half a kaomoji is unrecognisable, so it shrinks instead
  - Atomic plain-text insert `uncommon` — Composing flushed with autocorrect off, then committed in one step; skips history and prediction.
  - Restricted to fonts Android ships `RARE` — Glyphs limited to Noto Sans CJK / Symbols coverage so nothing renders as tofu.
- **GIF tool** — In-keyboard GIF search over Klipy and GIPHY with direct insert.
  - Two providers `uncommon` — Klipy (Tenor's replacement after Google retired that API) and GIPHY; 24 results per fetch.
    - Trending on open — An empty query returns each provider's trending feed rather than a blank grid
    - Tabs or mixed — A chip per provider, or a round-robin interleave so no source dominates the top
  - Category chips `uncommon` — Provider categories when published, else 16 bundled GIF terms; capped at 24 chips.
    - Term and label are separate — Bundled chips translate with the app while the term sent to the provider stays English
    - Hidden on short keyboards — Below a 190dp panel the row would cost the last grid row, so it steps aside
  - Justified result rows `RARE` — Rows of up to 3 sharing one height, widths by aspect ratio, nothing cropped.
    - Ratio clamping — Cells clamped to 0.5–2.6 so one banner cannot flatten its row
  - Long-press menu `RARE` — Copy to clipboard, or Report — which opens a mail draft naming provider, query, id and URL.
    - Nothing sent from the keyboard — The report lands in the mail app as an editable draft
  - Content filter `uncommon` — Off/Low/Medium/High mapped onto each provider's own rating; Medium default. Shared with stickers.
  - 30-file media cache `uncommon` — Re-picking the same GIF skips the download; older files pruned on every write.
- **Sticker tool** — Same two providers plus a local tab for the user's own packs.
  - My stickers tab `uncommon` — Local packs are never interleaved with providers, in tabs or mixed mode.
    - Per-pack filter chips — All plus one chip per pack, shown once there is more than one pack
    - Local search — Matches a sticker's search words and its pack name together
  - Save a searched sticker into a pack `RARE` — Long-press offers "Save to <pack>" per pack, or "Save to a new pack".
    - Local items get a different menu — Manage packs and Copy only — nothing to save, nobody to report to
  - Pre-send field check `RARE` — A field taking no images shows a standing notice; results stay visible at 45% for long-press.
  - 14 bundled sticker categories `uncommon` — Used when a provider publishes none; GIPHY stickers borrow trending searches instead.
- **Custom sticker packs** `RARE` — .wmstickers packs built from photos, managed in the app, sent from the keyboard.
  - Store limits and layout `RARE` — 50 packs, 200 stickers each, under filesDir/stickers with a packs.json manifest.
    - Self-reconciling — Manifest rows whose file vanished are dropped; unreferenced files and dirs are deleted
    - Cheap staleness signal — The IME checks a size-and-timestamp token and reloads only when the manifest changed
    - Derived file names — Every file name comes from a fresh sticker id, so nothing from a pack is ever used as a path
  - .wmstickers format `RARE` — ZIP with pack.json plus stickers/<file>; versioned envelope, format tag is the one strict check.
    - Forgiving of hand-written manifests — Accepts stickers[] beside pack, "file" instead of "fileName", and paths instead of bare names
    - Repairs are reported — Each dropped entry produces a message; a manifest that yields nothing is a distinct result, not an empty pack
    - Zip-bomb guards — 500 entries and 64 MB per archive; staging dir deleted on any failure path
    - Also an addon type — "stickers" is one of the addon-repository types, installable from a repo URL
  - WhatsApp-spec encoding `RARE` — Stills become 512×512 WebP under 100 KB via a 90/80/70/60/50 quality ladder.
    - Conforming files left alone — An already-spec 512 WebP is stored as-is rather than losing a lossy generation
  - Signal pack import `RARE` — A signal.art / sgnl:// pack link fetches the manifest and stickers from Signal's CDN, decrypts them under the pack key, previews, then adopts them as a pack (#291).
    - No directory of packs — signalstickers.org opens in the browser; its "Add to Signal" comes back through the chooser
    - APNG becomes animated WebP — Frame for frame, with the emoji per sticker kept as a keyword
  - WhatsApp sticker import `RARE` — Three ways in, none of them WhatsApp's own API, which no other app may read (#368).
    - .wastickers files — The Sticker Maker export (title.txt, author.txt, tray PNG, WebP stickers): opened from a file manager, the share sheet or the Import row; the tray is dropped by name or as the lone PNG among WebPs
    - WhatsApp's saved-sticker folder — Android/media/com.whatsapp/WhatsApp/Media/WhatsApp Stickers picked with the folder picker (it carries a .nomedia, so the photo picker never sees it); every WebP becomes one pack, newest 200
    - Hand-picked files — The document picker opened in that folder, multi-select, into an existing or new pack
    - No emoji arrive — Neither source carries any; the packs read no network and keep no folder access
    - Animated sources stored byte-for-byte — Android has no animated-WebP encoder; those are capped at 2 MB instead of 100 KB
    - 12 MB source ceiling — Anything larger is refused before decoding starts
  - Pack management `RARE` — Create, rename, delete, export, reorder packs; per sticker: search words, reorder, move, delete.
    - Photo picker up to 30 at once — A single still image routes into the editor instead; a batch is added directly
    - Search words are one field — First word is the name (read out by screen readers), the rest are tags; round-trips idempotently
    - Export via SAF — Writes the manifest and the present files only; export warned about before a delete
  - Originals kept for re-editing `RARE` — .originals/<id>.webp at 1536px plus the mask PNG and the edit state JSON.
    - Never leaves the device — Excluded from pack export, the settings backup's sticker section, and cloud backup
    - Its own storage row — Listed separately under About › Storage so it can be deleted without losing stickers
  - New file name on every edit `RARE` — s1a2b3c4.webp → _1 → _2, because the shared image loader caches on path.
- **Sticker editor** `RARE` — Crop, background removal and border for one sticker, all on the 512×512 canvas.
  - Four modes `RARE` — Crop (drag/pinch, 6× max zoom), Erase, Restore, Border.
    - Brush 8–96px with a preview ring — A ring the brush's size appears on mode switch or slider move and fades after 1.1s
    - Undo 12 strokes deep — One alpha snapshot per step; raster work only
    - Border 0–24px, white or black — Stamped from the subject's own alpha in a ring of up to 104 offsets behind it
    - Letterboxed, never stretched — A non-square crop gets transparent bars inside the square canvas
  - One-tap background removal `RARE` — ML Kit subject segmentation where there are Play services (module on demand), the app's own U²-Net-P on LiteRT where there are none (#278); either way the model arrives on the first tap with a progress bar.
    - Own model — 4.6 MB `u2netp.tflite` from wmkeyboard-data `models/cutout/`, SHA-256 pinned, resumable, kept in `files/cutout`, listed under Stickers on the storage screen, excluded from Android backup
    - Refuses degenerate masks — Under 1% or over 99% coverage reports "no subject" rather than erasing the picture
    - Brushes still work without it — Lite builds and un-fetchable models just lose the button
  - Edits resume across sessions `RARE` — Reopens the source photo with the crop, mask, border and brush size still applied.
    - Crop stored as fractions — Survives a different screen, window size or decode scale — not the editor's own pan/zoom
    - Opens on Erase when resuming — A stray pan in Crop is the one gesture that would throw the erasing away
    - Re-cropping warns first — Within a session the edit is destructive, so a new crop asks before discarding the mask
    - Stickers with no original reopen as themselves — The version being replaced is kept as the original from then on
  - Animated stickers skip the editor `uncommon` — No still to edit and no encoder to reassemble an animation.
- **Sending mechanics** `uncommon` — MIME negotiation over commitContent, with fallbacks rather than silent failure.
  - WhatsApp sticker MIME offered first `RARE` — image/webp.wasticker before plain image/webp when send mode is Sticker.
    - Only for real WebP bytes — A GIF can never carry the sticker MIME, so animated results always send as images
    - Separate defaults — Stickers default to Sticker mode, GIFs to Image
  - WebP→PNG re-encode fallback `RARE` — When the field rejects WebP but advertises PNG; skipped for animated sources.
  - Clipboard fallback with a toast `uncommon` — If no candidate MIME matches, the file goes to the clipboard via FileProvider and says so.
  - Pre-send acceptsRichMedia gate `uncommon` — Fields taking no images never start a download; a vibration and a standing notice instead.
  - Debug line per commit `RARE` — Logs the chosen MIME, the mode and everything the field advertised.
  - Whole-emoji backspace `uncommon` — One press deletes a full cluster: VS16, tones, ZWJ chains, flag pairs, keycaps, tag sequences.
    - Narrow by design — Returns 0 for non-emoji text so Bengali ZWJ conjuncts fall through to normal rules

**Conditions and gating**

| Feature | Needs |
|---|---|
| Sticker editor: one-tap background removal | full flavour only (ML Kit subject segmentation, or U²-Net-P on the LiteRT interpreter without Play services); lite ships a stub reporting supported=false |
| Sticker editor: segmentation model | needs a one-time download (network): the Play services on-demand module, or without Play services (or when they lack the module) the app's own 4.6 MB model from the data repository (on Play the LiteRT interpreter that runs it is the on-demand :feature:litert split, fetched first under the same bar); button offers the download and falls back to brushes if neither can be fetched |
| GIF search and send (Klipy, GIPHY) | needs a user-supplied API key for at least one provider, plus network |
| Sticker search and send (Klipy, GIPHY) | needs a user-supplied API key for at least one provider, plus network; keys shared with the GIF tool |
| Animated emoji preview and send | network fetch from fonts.gstatic.com on long press (no key, no query, no identifier) |
| Emoji keyword dictionaries (125 languages) | network download from the app's GitHub data repo; auto-download also gated by the global language-data switch |
| Emoji keyword pack import from URL | network; http/https only, 8 MB cap |
| Emoji font: Google (Noto Color Emoji) | needs the Play services downloadable-font provider; option hidden on GMS-free devices unless already selected |
| Direct Noto Color Emoji download, addon emoji fonts, addon sticker packs, addon keyword packs | network (addon repository) |
| Custom sticker packs (panel tab, pack manager, editor) | needs the device unlocked — pack storage is not available during direct boot |
| Sending GIFs, stickers, animated emoji or emoji-as-image | needs a field that advertises image MIME types via commitContent; otherwise clipboard fallback only |
| Sticker pack import and export | needs the SAF document picker (an activity), so it is app-side only, not reachable from the keyboard |
| Adding stickers from photos | uses the Android photo picker (no storage permission), up to 30 images per trip |

## Toolbar and the tool set

- **Toolbar & toolbox mechanics** `uncommon` — 77 tools in ToolbarTool enum; 3 pinned by default (Emoji, Clipboard, Settings)
  - Pinned bar vs toolbox — A tool is on the bar or in the toolbox grid, never both
    - Default pinned row — Emoji, Clipboard, Settings (DefaultToolbarTools)
    - Tablet-aware default pin set — 5 pinned on small tablets, 7 on large, applied only if user never rearranged
    - Ranked default toolbox order — DefaultToolOrder built from the onboarding starter sets, then the rest
    - Unranked new tool still shows — Any enum entry missing from the ranked list is appended, never hidden
  - Drag to pin / unpin / reorder `uncommon` — Hold-and-drag between bar and grid, Gboard style
    - Live drop preview — Bar slot and grid slot render a ghost stand-in so icons make room
    - Haptic tick on slot change — onSnap fires whenever the drop target moves
    - Hold-without-drag opens that tool's settings — Same gesture, 24dp slop decides: tap, settings, or drag; a cursor tool set to repeat on that surface spends it on the repeat instead
    - Hidden pinned tools keep their slot — Slots counted against visible list, translated back to stored list on drop
    - Drag hint on first open — toolboxHintDismissed; resurfaces occasionally after dismissal
  - Two toolbox layouts `RARE` — ToolboxLayout.ICONS (default) or PILLS
    - Icon grid — 3–6 tools per row, toolboxColumns default 4
    - Pill rows — 1–3 pills per row, name at full size, accent icon on the left
    - Chevron marks tools that open something — toolOpensScreen deny-list separates toggles from panels
    - Colour-filled pills — Fills the pill with the tool accent, flipping label to white or near-black
  - Paged toolbox `RARE` — Optional swipe-in-pages mode instead of one scrolling grid
    - Page size 4–40 — ToolboxPageSizeRange, default 12, with page dots
    - Empty toolbox is still one page — toolboxPageCount floors at 1; out-of-range pages return empty, not a crash
    - Drag reorders within the held page — Pages don't flip under the finger
  - Tools on their own row `uncommon` — ToolbarPlacement: STRIP (default, shares the suggestion strip), ON_DEMAND_ROW (the chevron opens a tools row above it, FUTO-style), ALWAYS_ROW (that row stays open, LeanType-style)
    - Strip stops flipping — With a row of their own the strip is only ever candidates, so the surface swap, the emoji handoff and the settle beat all rest
    - Chevron changes job — Opens and closes the row on ON_DEMAND_ROW, and disappears on ALWAYS_ROW where it would do nothing
    - Same row, one renderer — The standalone row wraps the same ToolbarRow the strip hosts, so widths, labels, drag and RTL mirroring are identical
    - Strip can go (#302) — showStrip off under ALWAYS_ROW drops the suggestion strip and its height, leaving only the tools row; compact dictation still takes the row, and full-bleed panels stop counting it
  - Press-and-hold actions on the toolbar `RARE` — Per-tool holdActions map: a hold runs another tool's tap instead of opening that tool's settings page
    - Any tool is a target — "Holding this does what tapping that does" needs no second action vocabulary; the bound tool goes through the same dispatcher a tap uses
    - Toolbar only — The toolbox hold keeps opening settings pages, so no page loses its way in
    - Repeat tools excluded — A caret tool's hold is already spent repeating the move; its row says so rather than hiding
    - Self-binding refused — Encoder drops tool=itself, which is a tap done slowly
    - "Does nothing" is a third answer (#136) — ToolHoldAction.None, stored as `TOOL=NONE`; the hold buzzes and nothing opens or runs
    - Voice hold picks a mode `uncommon` — voiceBar.holdPicksTypingMode (default on, #173): a hold on the pinned Voice tool opens a menu of the three typing modes; a pick persists the mode and starts dictation at once (onVoiceModePick, optimistic state update ahead of the DataStore write). Its own flag, like trackpad.holdToOpen, since holdActions can only name a tool; off hands the hold back to the map
  - Toolbar chrome options `uncommon` — ToolbarBehavior + height/label/shape fields
    - Master strip switch — toolbarBehavior.enabled off reclaims the height for keys
    - Swipe down on the bar to hide keyboard — swipeDownHide, off by default
    - Rearrange by dragging can be turned off (#136) — dragToRearrange, on by default; off, a hold that travels stays a hold and the toolbox is where the bar is rearranged
    - The drag-scope pill never covers the bar — parked below the toolbar, or above it when the row order puts the bar under the keys; the finger dodge goes to whichever end is not the toolbar's
    - Toolbar-only with a hardware keyboard — onlyWithHardwareKeyboard drops the key rows, keeps the strip
    - RTL mirroring of pinned order — reverseForRtl on by default; toolbox grid unaffected
    - Spread vs packed vs scrollable bar — greedy on by default; scrollable forces packed
    - Hide toolbar & clipboard on lock screen — hideWhenLocked, distinct from direct-boot filtering
    - Toolbar top/bottom padding 0–24dp — toolbarBehavior.paddingTopDp default 4, paddingBottomDp default 0, added around the 44dp toolbarHeightDp (#208); the height itself is only a theme override now
    - Tool labels under icons — toolbarLabels off; toolbarLabelSize default 10sp
    - Tool background radius and shape — toolCircleRadiusDp default 20, toolShape shares the key shapes; 0 removes it
    - Tool button width 38dp default — toolWidthDp stretches the circle into a pill
    - Tool icon size 22dp default (14–30) — toolbarBehavior.iconSizeDp, glyph only, button stays 38dp; toolbar + toolbox grid
  - Per-tool settings screen `RARE` — Every one of the 71 tools has its own screen under Settings → Tools
    - Eight groups plus an Other catch-all — Panels, Scanners, Online, Create & convert, Modes, Cursor, Quick actions, Utilities
    - Tune icon marks tools with real options — toolHasOptions; toggle-only tools show just the switch
    - One switch controls bar, toolbox and leader key — setToolEnabled hides the tool everywhere at once
    - Unusable tools grey out with a reason — Search tools show 'Needs an API key' instead of the description
  - Colourful tool icons `uncommon` — coloredToolIcons on by default, per-tool accent
    - Per-tool colour override — toolColorOverrides map, reset-all button when any override exists
    - Two-colour gradient icons — toolIconGradients off by default, with its own end-colour override map
    - Icon-pack glyph substitution — IconSlots.forTool resolves an installed icon pack's glyph
  - Direct-boot tool filter `RARE` — 47 of 77 tools work before the first unlock after reboot
    - Rule is what the tool reads — Arithmetic, sensors and keyboard-own state stay; disk, credentials, providers, activities go
    - All 14 cursor tools stay usable — They only touch the input connection
    - Not a user toggle — isDirectBootSafeTool is automatic and only applies pre-first-unlock
  - Hardware leader-key tool access `RARE` — Double-tap Ctrl (default) then a letter
    - 25 default tool letters — DefaultToolLetters maps E/C/S/X/G/K/V/R/D/W/I/A/N/Y/L/U/M/P/Q/H/O/Z/B/J/F
    - Toolbox and cheat-sheet letters — T opens the toolbox; ? expands a two-column legend of every binding
    - Badges drawn on the tools themselves — HintPlan badges replaced the old floating legend line
    - Disabled tools lose their letter too — usableTools filters the shortcut map
  - Type-a-word tool access `RARE` — 36 tools have default suggestion-strip keywords
    - Editable per tool — Keyword shortcut field on each tool's settings screen; clearable
    - Chip replaces the typed word — replaceSpan drops the keyword when the tool opens
  - Mode-scoped toolbars `RARE` — A keyboard mode can carry its own pinned row and toolbox order
    - Reset pinned tools always resets the global row — Mode overrides are edited on the mode itself
  - Availability gating `uncommon` — isSupportedTool (build) vs isUsableTool (runtime)
    - Lite ships 66 of 71 — Handwriting, OCR, QR scan, Doc scan, Grammar are compiled out
    - Doc scan also needs Play services — PlayServices.available gate, since the scanner UI lives in Play services
    - Search tools appear only with a Brave key — hasSearchKey: user key or the build's baked-in key
  - Panel back-out paths — Back arrow replaces the toolbox button; system Back; Esc on hardware
  - Panel key capture `uncommon` — Input-taking panels reroute keystrokes into their own field
    - Backspace routed into the panel — Stops word-delete editing text you can't see behind the panel
    - Focus-ring navigation inside panels — PanelFocusTarget regions: SEARCH, CHIPS, CATEGORIES, RESULTS, ACTIONS
- **Panel tools** `uncommon` — 12 tools in the Panels group
  - Emoji — Emoji picker panel; also the toolbar's shared strip shortcut
    - Emoji key on the toolbar — emojiToolbar toggle on the tool's own settings screen
    - Shared placement between strip and bar — SharedPlacement animates the icon between its two homes
  - Clipboard — History panel, one of the three pinned by default
    - Five clip kinds — Text/rich text, links, images, files & videos, folders
    - Staggered two-column card grid — Short text clip isn't stretched to match a tall image
    - Files kept by reference, not bytes — URI, name, MIME and size only; up to 20 items per multi-file copy
    - Video frame thumbnail — Grabbed from the start of the clip instead of a blank icon
    - Entity chips — OTP codes, phone numbers and links pulled out as dashed chips
    - G- prefix stripped from OTP — Google's G-123456 pastes as the code alone
    - Learned phone-number formats — Turn a copied number into +880 1XXX-XXXXXX and match only that shape
    - Sensitive-clip handling — Keep / hide-and-forget (default) / never save, with its own 1–120 min timer
    - Forget after pasting into a password field — Purges history and the system clipboard, covering card, chip and Ctrl+V
    - In-panel search — Reroutes keystrokes; indexes file name, format and link-preview title
    - Link previews — Fetches title and description direct from the copied site; off by default
    - Source-app attribution — Long-press info popup; needs Usage Access
    - Expiry and cap — 0–168h expiry (default 24), 5–500 unpinned entries (default 100); pins exempt
    - Swipe a card to delete — No confirmation, no undo
  - Snippets `uncommon` — Text expansion with variables and regex triggers
    - 18 template variables — date, time, isodate, weekday, clip, selection, app, package, uuid, cursor and more
    - {date:pattern} custom formats — Checked before plain {date}; malformed patterns expand to nothing
    - Word triggers — Case-insensitive exact match, fires on space/punctuation/Enter
    - Regex pattern triggers — $1–$9 captures, $0 whole match, ${1:upper|lower|title|trim} transforms
    - Words-to-match cap — 3 by default, up to 8; never crosses a line break
    - Shortest match wins — Word trigger always beats a pattern
    - Ask-before-expanding chips — Offer on the suggestion bar instead of rewriting, updating as you type
    - Backspace undoes an expansion — Restores exactly what you typed, and the trigger won't refire
    - ReDoS step budget — A pathologically slow pattern is stopped rather than stalling typing
    - Skipped mid-transliteration — Composing buffer holds an input spelling, so expansion would misfire
    - Import/export .wmsnippets.json — Repairs rather than rejects rows; 500-snippet and 20k-char import caps
  - Text editing — D-pad cursor panel with selection mode; twenty-one operations including Cut, the start and end of the whole text (#59) and a forward delete that swipes like the key on the letters row (#226)
    - Real key events, not computed moves — Arrows, Home, End, Backspace sent as the events a hardware key would send
    - Select mode wraps moves in a real Shift press — Some editors only read Shift from the key events themselves
    - Select all / Copy / Paste column — Select all turns selection mode on; Copy turns it off
    - Auto-repeat on hold — Fixed 400ms delay, then a 30–200ms interval (default 60ms)
  - Numpad — 4×4 numeric keypad panel over any field
    - Phone or calculator digit order — 1 2 3 top by default; calculator style puts 7 8 9 on top
    - Backspace repeats on hold — Enter sends a normal Enter key
  - Handwriting `uncommon` — Full-width ink canvas, ML Kit digital-ink recognition
    - Per-language model manager — Catalog read from ML Kit itself, filtered to enabled languages; 8-26MB each, sized from ML Kit's own shipped manifest
    - Measured download progress — Bytes counted off disk against the manifest size; stall notice at 20s, gives up and cleans up at 90s; panel download button doubles as cancel
    - Language chip on the canvas — Only shown when two or more enabled languages have a model
    - Undo last stroke vs Delete — Delete throws away all pending ink; undo removes one stroke and re-recognises
    - Stylus-only mode and palm rejection — Finger ignored for 800ms after a stylus point, always on
    - Recognition pause 300–2000ms — Default 700ms; Bengali floored at 1200ms for multi-stroke conjuncts
    - Auto space between written words — Never before punctuation
    - Handwrite-with-swipes alternative — Draw on the key grid instead of gliding; 0–1500ms dot leeway
  - Voice typing — Device speech recognizer, panel or compact bar
    - Full panel or compact bar — Bar replaces the suggestion strip so keys stay usable while dictating
    - Hold-to-talk — Long-press past ~600ms dictates only while held (full panel only)
    - Continuous mode — Next session starts automatically; two silent retries then idle
    - Spoken punctuation — English and Bengali phrase tables, including দাঁড়ি to ।
    - Undo the last dictated phrase — Only while it still sits immediately before the cursor
    - Offline model download chip — Android 13+, named for the language actually being dictated
    - Spacing worked out from surrounding characters — No double or missing space when dictating mid-sentence
    - Dictated words feed the learned dictionary — Same path as typed words
    - No mic in password fields — Inline message in the panel, toast on the bar
  - Camera `uncommon` — In-keyboard CameraX viewfinder
    - Window-clamped crop — Capture sliced to exactly the region visible in the panel at shutter time
    - Send-the-whole-photo option — Keeps the full 4:3 frame instead
    - Self-timer 3s/10s with countdown — Feedback tick each second
    - Flash cycle and lens switch — Only drawn when the device reports a flash unit / both lenses
    - Tap to focus, pinch to zoom — Zoom pill appears above ~1.05x
    - Selfie mirroring — On by default, flips the saved file to match the live preview
    - 1600×1600 cap — JPEG to private storage; only 4 most recent scratch files kept
    - commitContent send with clipboard fallback — Toast explains when the field accepts no image type
  - Dictionary `uncommon` — English definitions from dictionaryapi.dev, keyless
    - Auto-lookup of selection or word at cursor — Latin-script only, ≤40 chars, quotes and hyphens trimmed
    - IPA and pronunciation audio — Play button when the API has a recording
    - Synonym/antonym chips — Up to 12 per row; tapping one looks it up in turn
    - Serif headword font — Lora, deliberately distinct from keyboard typography
    - Power saving forces auto-lookup off — Background-network toggle overrides the setting
  - Vocabulary tool — GRE-level word cards, nudges and flashcards from downloadable vocabulary packs (`vocab/<lang>/<id>.wmvocab.json.gz` in wmkeyboard-data, built from the wordcheck lists with Wiktionary via kaikki.org, WordNet, CMUdict and wordfreq)
    - "hate → abhor" nudges — A new SmartSuggest.Kind.VOCAB narrow chip, last in the detect ladder; the last whole word (plus up to two trailing separators) is looked up in the merged VocabIndex's trigger map; tap opens the card, hold swaps the word (setting flips them); scope, sensitivity (Zipf gap stored per trigger) and cooldown (every time / per field / per day via VocabPrefs) are settings
    - The card — Lora headword, POS pills, IPA and respelling per accent (US/UK), Wiktionary recording with TextToSpeech fallback (first TTS in the codebase; `<queries>` for TTS_SERVICE), source badges, senses with register tags, examples and dated quotations, synonyms/antonyms/word family chips (tap follows the relatedTap setting, hold inserts), origin chain, etymology, mnemonic, translations from per-language sidecars; every section a `VocabCardFields` visibility (Off / app only / keyboard and app)
    - Flashcards — Leitner (5 boxes) and SM-2 schedulers over one `vocab/progress.json` record shared by the keyboard panel and the settings Review screen; word of the day drawn by `WordOfDay`: the lemmas in a fixed hash order, slot `s` takes `s mod n` (the same word for everyone with the same packs, every word once before a repeat), a learnt word skipped by walking on; slots are a day or a fraction of one (`VocabWordInterval`, hourly to daily), pinned per slot in the record; offered as a strip chip that comes back up to `chipTimesPerWord` times across the slot (`VocabPrefs`) until tapped or dismissed, and as a settings home card (dismissable per slot, held in the record beside the pin; the draw is cached per slot and pack state token so it paints on the first frame, with a placeholder holding its height on a cold start)
    - Packs — VocabPacks store under `filesDir/vocab/<lang>/`, `.off` to disable, catalogue downloads of all eleven data-repo lists (VocabDownloadManager; translation sidecars per language, the keyboard's languages fetched on their own via `VocabLanguages.wantedCodes`/`codesToFetch` — `bn_rom`→`bn`, `zh`→`cmn`, `hr`→`sh` fallback — when data saving allows), addon type `vocabulary` (gzipped payloads accepted; the addon repo points at the data repo's Magoosh 1000), `.wmvocab.json(.gz)` file association and export, user-made lists with autofill from installed packs → kaikki.org (`KaikkiClient`, the packs' own source, translations included) → dictionaryapi.dev → Wiktionary REST (`VocabAutofill.Source` chain; manual look-ups bypass data saver); "My words" list fed by the card and by the Dictionary panel's Add to vocab chip
    - Index — `VocabIndexCache` is the process's one merged index (settings screens and the IME share it, token- and language-keyed); glosses in the wanted languages and their romanisations are triggers (`TRANSLATION_GAP`, `foldKey` strips Latin accents but keeps Indic marks, phrases up to `MAX_TRIGGER_WORDS` matched longest-first by SmartSuggest); `VocabLanguages.displayName` names codes the registry lacks (cmn, no, ota, sh)
    - App screens — packs screen cached per pack-state (`InstalledPacksCache`) with translations folded under a summary row; browse filters scroll sideways; the add-word sheet is full-height, scrolling, sectioned, Save in the header; bulk add keeps its text as a `TextFieldValue` (hoisted String doubled words); the word card is sectioned (hero with full list names, Meaning grouped by POS with quotations as year badge + rule + `VocabQuotation.citation`, Related — every chip tappable, a word in no pack opens `VocabLookupSheet` (kaikki → Wiktionary REST → dictionaryapi) with Add to My words, Remember it, In your languages one line per `VocabTranslation.glosses()` pair with romanisation-first for `_rom` layouts, Where it comes from folded, More folded); installed packs listed above the catalogue
    - Backup and storage — ConfigBackup.Section.VOCAB (user packs, imported packs and progress; catalogue packs re-download), Storage category `vocab`
    - Nested VocabularySettings — one KeyboardSettings slot, flat `vocab_*` keys; enums live in core.vocab because SmartSuggest reads them; no default hotkey letter (every letter is taken)
  - Grammar `RARE` — Harper linter over the field, Rust JNI
    - Four English dialects — American (default), British, Canadian, Australian
    - Fix all — Applies each lint's top suggestion in one action
    - Per-lint dismiss — Cards can be dismissed instead of fixed
    - Card jumps the caret when it has no suggestion — Focus-ring seeded only from the leader key
  - App launcher `RARE` — App drawer inside the keyboard
    - Live search over names and packages — Keys return under a shortened panel while searching
    - Pinned and recent row — Last 10 opened, stored as package names only
    - Hold to open a screen inside an app — Lists the app's declared activities; exported ones tappable
    - Show private screens — Non-exported activities listed dimmed with a lock
    - No QUERY_ALL_PACKAGES — Reads the same launcher list the home screen sees
    - Sort A–Z or most recent — Labels under icons can be hidden
- **Scanners** `uncommon` — 3 camera-driven tools, all ML Kit, full edition only
  - Text scan (OCR) `uncommon` — Full-bleed viewfinder, on-device recognition: ML Kit for Latin script, Tesseract (per-language download) for 100+ languages in most other scripts
    - Words as tappable chips grouped by line — Trim the capture down before inserting
    - Start with everything selected — On by default; off makes chips opt-in instead
    - Select-all/deselect-all toggle — Copy and Insert act on the current selection
    - Covers the toolbar row too — Viewfinder is full-bleed, not just the key area
  - QR & barcode scanner `uncommon` — Continuous decode, no shutter tap
    - 13 formats — QR, Aztec, Codabar, Code 39/93/128, Data Matrix, EAN-8/13, ITF, PDF417, UPC-A/E
    - Open button for URL payloads — https/http/www only; anything else inserts as raw text
    - Insert automatically — Off by default; types the value the instant it's spotted
    - Link details preview — Off by default; force-disabled by power saving's background-network toggle
    - Pinch to zoom with a percentage pill — Pill shows above roughly 1.05x
  - Document scanner `uncommon` — Hands off to Google's scanner UI
    - Pages inserted one at a time — JPEG, same path as a camera-tool photo
    - Gallery import allowed — Alongside the camera capture
    - Save to gallery — Off by default; writes to Pictures/WM Keyboard
- **Online tools** `uncommon` — 8 tools in the Online group
  - Translate — Type-and-translate panel with its own search bar
    - 63 languages — TranslateClient.languages; source is detected, or picked from the source chip for the visit
    - Swap — Result becomes the text, its language the source, the detected language the new target
    - Two online providers behind one switch — Google's free public endpoint, or Cloud Translation v2 with your key
    - On-demand on Play — The translator's ~16 MB/ABI lives in the :feature:translate split, fetched through SplitInstall when an on-device engine is first picked; sideload builds compile the same bridge into :core:intelligence
    - On-device engine (full) — ML Kit Translate, 59 languages, one ~30 MB model each, pivots through English; Online / On device / Automatic from the panel's engine chip or the tool page
    - Automatic falls back — On device when both models are here, online for a missing model, an online-only language or romanised text; the chip's icon says which one answered
    - Download offer in the panel — A query that needs a model turns the result area into the offer and the action row into Download/Cancel; retranslates the moment the models land
    - One model store for keyboard and settings — OnDeviceTranslator.models; progress read off the system DownloadManager row ML Kit enqueues, shade notification, data-saver ask
    - Source detection on device — Bundled ML Kit language-id; a weak answer falls back on the typed languages and shows as a guess ("French?")
    - Line structure survives — Each line translated on its own, blank lines and indentation put back
    - Translators released with the panel — And on memory pressure; a loaded pair is tens of MB
    - Insert vs Replace text — Replace swaps the whole field's contents
    - Debounced re-translate — ~400ms after typing stops; immediate on return or target change
    - 2500-character cap — Silently truncated before sending
    - Never reads the field — Only what you type into the panel is sent
  - GIF — Multi-provider animated GIF picker
    - Two remote providers plus local packs — KLIPY, GIPHY, and the user's own .wmstickers packs
    - Tabs or interleaved mix — Round-robin merge so no source dominates the top
    - Justified rows, nothing cropped — Aspect ratios clamped 0.5–2.6 so one banner can't flatten a row
    - 16 bundled browse categories — Floor when a provider offers none; provider categories capped at 24
    - Search-as-you-type — Keystrokes rerouted into the panel's own query
    - Content filter — Off/low/medium/high provider rating levels
  - Sticker — Same panel as GIF in sticker mode
    - Local sticker packs get their own tab — Never interleaved with provider results
    - Image vs sticker MIME negotiation — MediaSendMode prefers a sticker MIME where the field advertises one
  - Web search `uncommon` — Brave Search results in a panel
    - Tap inserts the URL, icon opens the browser — Two distinct actions per row
    - Title, host and HTML-stripped snippet — Per result row
    - Results per search 1–10 — Default 8; one API request either way
    - SafeSearch maps to Brave's moderate — Image search maps the same toggle to strict
    - Invisible without a key — Off the bar, toolbox, chips and hardware shortcut entirely
  - Image search `uncommon` — Brave image grid
    - Tap inserts the image itself — Downloads the full image and commits it
    - Long-press inserts the URL — Plain text instead of the image
    - Dedupes by full-size image URL — Brave returns one image for many reposted results
  - Wikipedia `RARE` — Three-tab in-keyboard article reader
    - Summary / Links / Full article tabs — Links and Full article load lazily on first visit
    - Outgoing links capped at 200 — Namespace 0 only, so no Talk:/File: noise
    - Tap a paragraph to insert just it — Full-article extract split into paragraphs
    - Per-language subdomain — Free-text code, default en; drives search, summary, links and article
    - Markdown link insertion — Off by default; [Title](url) instead of a bare URL
    - Back arrow returns to the results list — Not to a blank search
  - Currency converter `RARE` — Live fiat rates plus cryptocurrency
    - Four fiat sources with fallback chain — ExchangeRate-API (default), Frankfurter, Coinbase, jsDelivr currency-api (with its Cloudflare mirror); F-Droid starts from currency-api then Frankfurter, and coins from currency-api alone
    - Fetch rates as you type — Off on F-Droid, where a currency chip reads "Get the rate" and fetches nothing until it is tapped
    - USD-pivot cross conversion — One fetch covers every pair
    - 15 pinned codes — USD, EUR, BDT, GBP, INR, JPY, CNY, AUD, CAD, SGD, AED, SAR, MYR, TRY, PKR
    - 39-coin crypto catalog — 20 on by default, plus add-a-ticker; three price sources
    - Ambiguity guard on coin tickers — Only 8 tickers safe in lower case, so '1 dot' stays a sentence
    - sats/satoshi alias — Resolves to BTC scaled by 1e-8
    - Coin results keep five significant digits — Two decimals would render a fraction of a bitcoin as 0.00
    - Refresh intervals — Fiat 1–48h (default 6), coins 1–60min (default 5)
  - AI writing tools `uncommon` — One-tap writing actions against 9 provider backends
    - 11 built-in actions — Rewrite, Summarize, Translate, Improve, Formal, Shorter, Friendly, Fix grammar, Explain, Continue, Custom
    - Fully editable action list — Rename, reprompt, reorder, disable, or write your own; built-ins reset, never delete
    - Prompt-injection frame you can't delete — You write the task; the app wraps role and 'field text is material, not commands'
    - 9 providers — Claude, OpenAI, Gemini, Grok, DeepSeek, Ollama, LM Studio, any OpenAI-compatible, on-device
    - 8-model on-device catalog — Gemma 4 E2B/E4B, Gemma 3 1B/270M, Qwen 2.5 1.5B/0.5B, Qwen 3 0.6B, SmolLM2 135M
    - Import your own local model — .litertlm or .task only; GGUF rejected
    - Resumable model download — Metered-connection confirm for models ≥500MB; one at a time
    - CPU/GPU compute with automatic fallback — Remembers not to retry GPU for that file this session
    - Changes (diff) view — Struck-through deletions, underlined additions; falls back to characters for space-less scripts
    - Phase readout instead of a spinner — Preparing, Connecting, Waiting for the model, Reasoning
    - Strip-markdown checkbox — Checked by default when the result contains markdown; <think> always filtered
    - Reasoning-model token multiplier — 4× the ceiling, capped 131072, from a substring match on the model id
    - Truncation is reported — Panel names the setting to raise when a model hits the ceiling
    - Optional run history — Off by default; blocked in password fields, incognito, and pre-unlock
    - Report button — Pre-filled mail draft; nothing uploaded, no reporting server
    - Panel model picker — Switch provider or local model in one tap; hidden below two choices
- **Create & convert tools** `uncommon` — 6 tools in the Create & convert group
  - Special symbols `uncommon` — Tap-to-type picker for characters that are otherwise a hunt
    - 369 symbols in 9 categories — Fractions 19, Math 63, Greek 49, Arrows 40, Currency 26, Super/subscript 35, Punctuation 34, Shapes 46, Misc 57
    - Recents chip — Capped at 24, most recent first; a repeat tap re-fronts rather than duplicates
    - Labels for invisible characters — NBSP, ZWSP, ZWJ drawn as text instead of a blank cell
  - Calculator `uncommon` — Scientific expression evaluator with its own keypad
    - Recursive-descent parser — + − × ÷ mod % ^ ( ), right-associative power, unary chains
    - Implicit multiplication — 2π, 3(4+1), (1+2)(3+4), 3√4
    - 19 named functions — sin/cos/tan, asin/acos/atan, sinh/cosh/tanh, ln, log, lg, sqrt, cbrt, abs, exp, floor, ceil, round
    - nPr and nCr keypad shorthand — 5p3 and 4c2, built as running products so 60P3 doesn't overflow
    - Percent is context-sensitive — Trailing % divides by 100; % followed by a value is modulo
    - deg/rad chip — Remembers the choice; inverse trig returns in the same unit
    - = collapses in place — 12*4= becomes 12*4=48 rather than clearing
    - Insert chip — Types the formatted result at the cursor
    - Precision 0–12 decimals — Default 8, trailing zeros stripped, scientific fallback past 1e15/1e-9
    - Localised error messages — Errors carry a string res plus one detail argument, not English strings
  - Unit converter `uncommon` — 14 categories, 118 units, all local
    - Categories — Length, mass, temperature, area, volume, speed, time, data, energy, power, pressure, angle, frequency, fuel economy
    - Reciprocal units — Fuel economy handled as base = factor / value, so mpg↔L/100km is right
    - Regional area units — Katha and bigha alongside acre and hectare
    - Per-category unit-pair memory — Volume and Length each remember their own last pair
    - Feet-and-inches output — 1 m reads 3 ft 3.37 in rather than 3.2808399 ft
    - Convert-as-you-type chip — Typing '1 ft' offers the conversion inline
  - QR code generator `RARE` — Encodes typed text and sends it as an image
    - Keeps the letter rows on screen — Its own editable buffer, seeded from the field but never writing back until send
    - Live preview to 2000 characters — Past that it shows the character count instead of a code
    - Error correction L/M/Q/H — Default M
    - Output size 256–2048px — Default 1024; preview stays a fixed small size
    - commitContent send with clipboard fallback — Optional Save to gallery
  - Password generator `RARE` — SecureRandom passwords and passphrases, nothing stored
    - Guaranteed class coverage then Fisher-Yates shuffle — One character per enabled class, not front-loaded
    - Length 4–64 — Default 16; uppercase, digits, symbols each toggleable
    - Exclude look-alikes — Strips Il1O0o5S8B and a few punctuation marks from the pool
    - Passphrases from the bundled English dictionary — 4–8 letter lowercase distinct words; no separate wordlist download
    - Passphrase options — 2–10 words, free-text separator, capitalise, append a digit
    - Entropy estimate in bits — Shown for both modes
  - Learn from text `RARE` — Lists the words in the field or selection the keyboard does not know, to add to the personal dictionary in one go (#174)
    - Selection, else the whole field — Password fields refused; a partial read or a list past 2,000 words says so
    - Unknown means every source the engine asks — Active language mix, imported lists, personal and Android dictionaries, contacts, apps; blacklisted words, numbers, links and spaceless scripts skipped
    - All rows checked, sortable — Select all/none; Most used, Text order or A to Z, remembered
    - Per-row Edit, Show in text, Never suggest, Ignore — Edit types into the panel's own buffer with glide blocked; Ignore lasts one scan
    - Add as by hand — Same path as Add word: out of the waiting room, off the blacklist, mirrored to Android when that is on
    - Word pairs chip — Teaches the text's pairs, triples and skip-grams once each, only between known words, never across a sentence end or line break, not while learning is off or paused
  - Typing speed test `RARE` — Scored typing test on the real keys
    - Three modes — Timed (15/30/60/120s), word count (10/25/50/100), quote
    - 200 most common English words — Plus 14 public-domain quotations for quote mode
    - Optional punctuation and numbers — Sentence shape, quoted words, and short numerals sprinkled in
    - Clock starts on the first keystroke — Reading the prompt doesn't count against you
    - Shift forced off at start — Auto-capitalisation can't turn the first keystroke into a false miss
    - Per-character verdicts — Correct, wrong, extra, missing, pending
    - WPM, raw, keystroke accuracy, consistency — Consistency is the coefficient of variation over per-second samples
    - Personal best per configuration — time30 and quote are separate records
    - 24-run rolling history — Feeds the trend bar on the results screen
    - Four achievement badges — 100 WPM, flawless run ≥30 chars, pangram quote, 50 tests
    - Insert score chip — Types '83 WPM · 96% accuracy (30s)' into the field
- **Keyboard mode & geometry tools** `uncommon` — 6 tools in the Modes group
  - Modes `RARE` — Panel to switch keyboard modes
    - Empty state links to settings — Chip straight to the modes settings screen when none exist
    - A mode can carry its own toolbar — Switching modes swaps the whole pinned row
  - One-handed — Shrinks and sides the keyboard, no panel
  - Split — Toggles the split layout, no panel
  - Floating — Toggles the floating window, no panel
    - Drag pill and corner resize grip — Handle bar with dock button, drag pill and grip
  - Keep on screen — Toggles the persistent keyboard (issue #58), no panel; same setting as the Layout row
  - Resize `RARE` — Inline drag-resize of the docked keyboard
    - Three drags — Top handle scales key heights; bottom handle and centre move button ride bottom padding
    - Nothing persists until Done — Everything previews through the session; Reset returns to the entry values
    - Only changed fields written — Unchanged values go as null, so a padding-only session keeps tablet height defaults
    - Handles turn red at a limit — Both heights keep their ratio from one clean drag-start baseline
    - Scrim eats every touch — Accent outline hugs the keyboard rectangle while resizing
- **Cursor & selection tools** `RARE` — 14 one-tap toolbar tools; all direct-boot safe
  - Cursor left `uncommon` — Moves the caret one character left
  - Cursor right `uncommon` — Moves the caret one character right
  - Word left `uncommon` — Ctrl+Arrow word jump backwards
  - Word right `uncommon` — Ctrl+Arrow word jump forwards
  - Cursor up `uncommon` — Moves the caret one line up
  - Cursor down `uncommon` — Moves the caret one line down
  - Line start `uncommon` — Home
  - Line end `uncommon` — End
  - Page up `RARE` — Scrolls the caret a page up
  - Page down `RARE` — Scrolls the caret a page down
  - Select word `RARE` — Selects the word at the cursor
    - Boundaries computed, not Ctrl+Shift+Arrow — Sets the selection directly; no-ops on whitespace or punctuation
  - Select line `RARE` — Selects the whole line at the cursor
    - Turns selection mode on afterwards — No-op on an empty line
  - Select all `RARE` — Selects the whole field in one tap (issue #228)
    - Same action as the panel's key — performContextMenuAction(selectAll); leaves selection mode where it found it
  - Selection mode `RARE` — Every caret move extends the selection while it is on
    - Three gestures on one button — Tap to toggle, press and hold for a temporary mode, two or three quick presses to select the word or the line
  - Hide keyboard `uncommon` — One tap dismisses the keyboard
- **Quick-action tools** `uncommon` — 14 tools in the Quick actions group
  - Undo — Sends the field's own Ctrl+Z
    - Commits the composing word first — Then sends a real key event; not a keyboard-side history
  - Redo — Ctrl+Shift+Z, or Ctrl+Y if flipped
    - Shared toggle on both tool screens — redoUsesCtrlY appears under Undo and Redo alike
  - Autocorrect `uncommon` — One-tap autocorrect on/off, no panel
  - Selection actions `RARE` — One-tap switch for the selection actions bar (#177), no panel; same setting as Advanced → Selection actions
    - Reaches a bar already on screen — Every flip re-reads the selection: off clears a live bar, on offers one for text already selected, without waiting for the caret to move
  - Fancy text `RARE` — Switches to the fancy-text layout and back
    - 22 Unicode styles — Bold, italic, script, fraktur, double-struck, monospace, fullwidth, circled, squared, small caps and more
    - Enables the fancy layout on demand — Adds AssetLayouts.FANCY_ID to enabled layouts and remembers the return layout
    - Pinned style applies to the session only — Never overwrites the style the strip last chose
  - Secondary layout `RARE` — Shows one of your secondary layouts over the letters and takes it off again
    - Picker when there are several — PanelMode.CUSTOM_LAYOUTS lists them by name; "Layout to show" pins one to skip it; the tool is hidden until one exists
  - Incognito `uncommon` — Pauses learning and clipboard capture with one tap
    - Field-requested incognito is explained — Toast instead of a switch that looks stuck on
  - Sound & haptics `RARE` — Panel of key-feedback switches and style chips
    - Ringer-mode awareness — Live broadcast receiver, so 'sound on but silent' isn't read as broken
    - Haptic and sound style chips — Custom and installed pack styles only appear when already selected
  - Themes `uncommon` — Mid-typing theme quick-switch panel
    - Curated built-in shortlist — themesPanelBuiltIns; the Settings gallery edits it per card
    - Custom and downloaded themes always show — Plus an auto light/dark preview card
    - Icon packs tab — Switch installed icon packs from the same panel
    - Variant style chips — Pick a theme's variant without leaving the keyboard
  - Power saving `RARE` — One-tap battery saver for the keyboard
    - Manual switch coexists with the automatic trigger — Says which one is in charge instead of reading as a dead button
    - Warns when nothing is configured to drop — Separate toast when the profile drops nothing
  - Settings — Opens the settings app from the keyboard
- **Utilities & instruments** `RARE` — 6 tools in the Utilities group
  - Flashlight `RARE` — Torch toggle with no panel
    - No CAMERA permission needed — Torch mode only
    - Tile mirrors real torch state — Flipping it from quick settings lights the toolbox tile
    - Auto-off with the keyboard — On by default, so it's never left burning
    - Waits on the flash-camera probe — At most one tap queues, so a double tap can't leave it on
  - Compass `RARE` — Rotation-vector rose with optional qibla
    - Qibla marker — Computed on-device from the Weather tool's saved coordinates
    - 16-point cardinal readout — Reads 'Calibrating…' until the sensor reports
    - Smoothed heading — Glides rather than jumping per sample
  - Bubble level `RARE` — Bullseye plus two tube vials
    - Three gauges at once — Combined pitch+roll bullseye, vertical vial, horizontal vial
    - Independent flat thresholds — A vial can read level a moment before the bullseye agrees
    - Gravity sensor preferred — Falls back to the accelerometer
  - Calendar `RARE` — Month grid with alternate calendar systems
    - 8 non-Gregorian systems, two at a time — Bengali, Hijri, Chinese, Hebrew, Hindu (Saka), Persian, Buddhist, Japanese era
    - Alternate day number inside the cell — Bengali digits ০–৯; a Chinese lunar month's first day shows the month name
    - Region-guessed defaults — From SIM, then network, then locale; only until the user picks
    - Device calendar events per selected day — Colour stripe, time or All day, location; recurrences expanded per occurrence
    - Read-only — No insert, edit or delete path against the provider
    - Weekend presets — Seven options including Fri&Sat, Thu&Fri, and none
    - Hijri day adjustment −2..+2 — Tabular calendar can miss local sighting by a day or two
    - Chinese computed astronomically — Real new-moon and solar-longitude calculations
  - Weather `RARE` — Open-Meteo current conditions, no key
    - Fetch the forecast as you type — Off on F-Droid, where a weather chip reads "Get the forecast" and fetches nothing until it is tapped
    - Location typed or searched, never GPS — Open-Meteo geocoding, or manual latitude/longitude
    - 15-minute cache with manual refresh — Reopening the panel is usually instant
    - Conditional stat grid — Feels-like, humidity, wind always; rain chance, cloud, pressure, UV, sunrise, sunset when present
    - 8-point wind direction — Plus emoji and short description for current conditions
    - Shares its location with the compass — Qibla reads the same saved coordinates
  - Moon phase `RARE` — Computed, not fetched
    - Eight phase names — Plus percent illuminated and days into the cycle
    - Next full and new moon dates — From a synodic-month constant and a reference new moon
    - Southern-hemisphere mirroring — Changes only the drawing, not the name or dates
- **Other tools** `uncommon` — 3 tools the group list doesn't claim, caught by the Other section
  - Media controls `uncommon` — Transport for the active media session
    - Album art, title, artist, album — Music-note placeholder when the app publishes none
    - Seek bar when the session reports duration — Disabled the same way skip buttons are when unsupported
    - Skip buttons dim on unsupported actions — Reflects what the session actually advertises
    - Empty listener service — MediaNotificationListener exists only to satisfy the access check; reads no notifications
  - KDE Connect tool (issue #285) `RARE` — A paired computer from the keyboard, and the computer typing back: a from-scratch client for the KDE Connect LAN protocol (version 8) in `:core:kdeconnect`, owned per process by KdeConnectHub. Works with kdeconnect-kde, GSConnect and Valent; the KDE Connect Android app is not needed
    - Own protocol engine, no GPL code — UDP discovery on 1716 plus mDNS (`_kdeconnect._udp` through NsdManager), the inverted-role TLS handshake with the encrypted identity re-exchange, trust-on-first-use then an exact certificate pin, pairing with the shared 8-character verification code (KdeVerificationKey), payload sockets on 1739–1764. The certificate is DER written by hand (DerCertificate), so there is no BouncyCastle
    - Nothing under `:core:kdeconnect` names an Android class — two whole engines pair and exchange files over localhost in plain JUnit (LoopbackTest), and InteropTest drives a real kdeconnect-kde daemon through its own CLI (`-Pkde.interop=1`)
    - Off until Turn on is pressed — KdeConnectSettings.enabled defaults false; the hub opens no socket before it, and none without a paired device unless a device list is on screen
    - Link lifetime — KdeLinkLifetime PANEL / KEYBOARD (default, 60 s linger) / ALWAYS, decided by KdeConnectHub from the reasons held (SERVICE, KEYBOARD, PANEL, SETTINGS, SHARE); no foreground service; power saving's background-network switch turns ALWAYS into KEYBOARD
    - Strangers only while browsing — an unpaired device is linked only while a device list is up (engine.setDiscovering), in the panel or on the settings screen
    - Input tab — KdeRemotePad: drag moves, tap clicks, two and three finger taps are right and middle click, two fingers scroll (ScrollAccumulator releases a step at a time, since X11 reads every packet as a wheel click), hold-then-drag and tap-then-drag hold the button; PointerAcceleration is ours, nothing about feel is on the wire; queued pure moves are summed by the link's writer rather than replayed
    - Type on computer — CaptureTarget.KDE_REMOTE: the whole keyboard types there, glide and strip picks included, because every buffer change is replayed as backspaces plus text (RemoteTextDiff, counted in code points); arrows, Home/End and page keys go to the computer as special keys; Ctrl/Alt/Super armed on the panel's strip or the board turn the next key into a chord. KDE_COMPOSE edits a line locally and sends it on Enter
    - The computer types here — `mousepad.request` with `key`/`specialKey` lands in the field through commitToField (literal) or the hardware-keyboard path (remoteTypingPipeline); only while the keyboard view is shown and the device is unlocked, which is also when `keyboardstate: true` is sent, without which Plasma's remote-keyboard box never appears; echoes always carry `key` and `isAck` or kdeconnect-kde drops them
    - Clipboard both ways — hooked ahead of the clipboard history's own gate so sync works with history off; sensitive clips (EXTRA_IS_SENSITIVE or ClipSensitivity) are never auto-sent, nothing from a secure field or while incognito pauses the clipboard; the engine records received text before the system clipboard is written, which is what stops the echo
    - Media, volume, run, slides, device tabs — MPRIS players with partial-packet merge and art over payload or HTTP, the computer's sinks in raw units against maxVolume, run commands with live output (`commandList` is JSON inside JSON), presenter pointer in screen fractions kept alive every 250 ms, ping, ring, lock
    - Files — sent from the panel's picker (KdeFilePickerActivity) or another app's share sheet (KdeShareAlias, an activity-alias enabled only once something is paired); received into Downloads/WM Keyboard through MediaStore (app files behind the clipboard FileProvider below API 29) and added to the clipboard history; file names from the peer are reduced to a bare name
    - Phone side — battery report, and the phone's media as an MPRIS player for the computer (a second MediaControlManager; needs the notification-listener grant)
    - Not built, on purpose — SMS and telephony, notification mirroring, SFTP, contacts, find-my-phone, mouse receiver
    - Identity out of every backup — `filesDir/kdeconnect` (key.pk8, cert.der, devices.json) is excluded in backup_rules and data_extraction_rules: a restored key would clone the device id onto a second phone
    - Nested KdeConnectSettings — one KeyboardSettings slot, flat `kde_*` keys; hidden in direct boot (restrictedToDirectBoot turns it off); NotificationKind.CONNECT for a pair request, file or ping that arrives while the keyboard is hidden
  - Plugins `RARE` — Runs installed .wmplugin Lua plugins in a panel
    - List then running view — Cards for installed plugins, Manage row at the end
    - Plugin-owned input field — Panel takes keystrokes; copy/paste/insert callbacks are host-mediated
    - No text, clipboard or network API for plugins — Deliberate Play-policy limit on what a plugin can reach

**Conditions and gating**

| Feature | Needs |
|---|---|
| Handwriting tool and handwrite-with-swipes | full flavour only (ML Kit digital ink); each language model is an 8-26MB download |
| Text scan (OCR) | full flavour only (ML Kit text recognition + bundled Tesseract library); needs CAMERA permission |
| QR & barcode scanner | full flavour only (ML Kit barcode); needs CAMERA permission; link details need network |
| Document scanner | full flavour only, and hidden entirely when Google Play services is unavailable |
| Grammar tool | full flavour only (BuildConfig.ENABLE_GRAMMAR, Harper Rust JNI) |
| AI On-device provider and its 8-model catalog | full flavour only; 2 of the 8 models need a Hugging Face token and licence acceptance |
| AI cloud providers (Claude, OpenAI, Gemini, Grok, DeepSeek) | needs the user's own API key — no built-in or proxied key for any of them |
| AI self-hosted providers (Ollama, LM Studio, Other service) | needs a reachable server address; plain-HTTP traffic on the local network |
| Web search and Image search | needs a Brave API key (user's or the build's); with none the tools vanish from bar, toolbox, chips and hardware shortcuts |
| Translate | network; optional Google Cloud Translation key, otherwise the free public endpoint |
| Currency converter (fiat and crypto) | network; four keyless fiat sources and three keyless coin sources |
| Weather and its place search | network (Open-Meteo, keyless); location typed or searched, never read from GPS |
| Compass qibla marker | needs a location saved in the Weather tool's settings |
| Wikipedia and Dictionary | network; keyless public APIs |
| GIF and Sticker | network for the KLIPY/GIPHY providers; local packs work offline |
| Camera tool | needs CAMERA permission, granted through a trampoline activity; shared with OCR and QR scan |
| Calendar events | needs calendar read permission, requested from the panel's Allow button |
| Media controls | needs the notification-listener grant, awarded in system Settings |
| Clipboard user screenshots | needs the photos/storage permission |
| Clipboard source-app attribution | needs Usage Access; best-effort foreground-app guess |
| Voice typing | needs microphone permission; audio may reach the OS recognizer service unless the on-device language model is installed |
| Clipboard link previews and QR link details and dictionary auto-lookup | network, and force-disabled by power saving's background-network toggle |
| 30 tools of 77 are unavailable before the first unlock after reboot | direct-boot filter; the other 47 (arithmetic, sensors, keyboard-own state, all 14 cursor tools) stay usable |
| Lite edition tool count | 72 of 77 tools; the 5 ML Kit / Harper tools are compiled out, not just hidden |

## Clipboard, snippets, text expansion

- **Clipboard history** — Persistent clipboard manager, JSON-backed, 7 clip kinds, 18 settings
  - Clip kinds stored `uncommon` — 7 kinds: TEXT, HTML, LINK, IMAGE, FILE, FOLDER, VIDEO
    - Rich text keeps the HTML markup — htmlText holds the markup, text the plain rendering; card tagged "rich text"
    - Bare URLs promoted to link clips — Regex on the whole trimmed clip, ≤2048 chars; bare www. gets https:// added
    - Image clips copied into app-private storage — Store owns the file and deletes it on expiry, cap, delete or clear
    - Files, folders and videos stored by URI reference only — Bytes stay with the copying app, so a multi-GB video costs nothing
    - Video card shows a frame grabbed at t=0 — MediaMetadataRetriever on the source URI; falls back to a file row
    - Folder tap types the folder name and hands the URI back — A folder cannot be attached, so it goes to the system clipboard instead
    - Device screenshots captured into history — MediaStore observer, 15s freshness window, path must contain "Screenshot"
    - Up to 20 items recorded from one multi-file copy
    - Orphaned image files swept at load — Files in the images dir with no matching item are deleted on restore
  - History bounds `uncommon`
    - Expiry in hours — 0–168, default 24; 0 disables expiry
    - Unpinned entry cap — stops 5–5,000 or Unlimited (0), default 100; oldest unpinned drops as new ones arrive
    - Pinning exempts a clip from expiry, the cap and the sensitive timer
    - Pinned-first or pinned-last ordering — Toggle; newest-first within each group either way
    - Per-clip text limit — clipboard.maxTextChars, default 0 (no limit), stops 1k–100k: capClipText at add and edit, surrogate-safe; markup dropped when the cut makes it lie; the system clipboard is untouched
    - Re-copying an existing clip moves it to the top instead of duplicating — Matches on text for textual clips, on URI for file clips
  - Panel `uncommon`
    - Staggered grid, 1–4 columns (clipboard.gridColumns, default 2) — Columns pack independently so a tall image leaves no hole beside it
    - Lines per clip — clipboard.previewLines, 0 = auto (6 on a card, 3 in a row), up to 20; every preview (cards, rows, the strip chip) cut by clipPreviewText before layout: one line past the last shown, 4,000 chars at most, so a document-sized clip lays out like a short one
    - Time on each clip — clipboard.timeLabel NONE / COPIED (relative, abbreviated) / EXPIRES (countdown from ClipItem.expiresAt, the same rule prune uses), refreshed every 30 s only while shown
    - Swipe a card off to delete — Card follows the finger and fades; release past 40% of its width deletes
    - Press-and-hold info popup — Relative + exact copy time, source app, type, and size/duration/char count
    - View full text — hold popup turns into the clip's whole text, scrolling in 2,000-char lazy chunks, with Paste and Close; not for hidden clips (#414)
    - Per-card pin and delete buttons — clipboard.cardButtons, default on; off moves Pin/Delete into the hold popup and drops a card's bottom row when it has no number, time or rich-text tag (#414)
    - Height bar on top of the panel — drag up to grow the panel over the app (clipboard.panelExtraHeightDp, 0–600 dp, fitted to 80% of the screen); the window is held at full height through the drag so it resizes twice, not per frame (#414)
    - Full-bleed panel — Panel takes the toolbar's row for more cards; on by default
    - Panel layout (issue #63) — search box, fragment strip and history are field cells of a PanelLayoutSpec; an abc/space/backspace row is a row of keys the user adds (the old bottom-row switch seeds it)
    - Send an image clip as a sticker — Info-popup action converts it to the 512px transparent WebP sticker format
    - Store re-read from disk on every panel open — Settings can delete history while the IME holds the same list
    - Close-after-insert option shared with the emoji panel
  - Search inside the panel `uncommon`
    - Search pill captures keystrokes instead of typing into the field — Panel shrinks to 132dp while searching; same trick as emoji search
    - Searchable text beyond the clip's own — File name, link-preview title/description/site, source app and MIME subtype
    - Clips with no text findable by what they are — Kind words "image picture screenshot", "folder directory", "video movie" indexed
    - One matchesQuery predicate shared by the panel filter and store.search
  - Link previews `uncommon` — Off by default; makes a direct request to the copied site
    - Title, description and site name fetched on panel open — Max 8 pending links per pass
    - A failed fetch is recorded so it is not retried on every open
    - Turning the setting off drops every fetched preview
  - Recent-copy paste chip on the suggestion strip
    - Takes the idle strip only — Word candidates always win the row; auto-hides on a timer
    - Narrow form when sharing the strip with candidates or smart replies — Capped at 160dp instead of stretching
    - Image chip shows a downsampled thumbnail; screenshots labelled separately
    - Chip can offer the code inside the clip rather than the whole clip — Dashed outline plus a CODE badge when the clip merely contains an OTP
    - Dismissing the chip remembers that clip so it is not re-offered
  - System clipboard integration
    - OnPrimaryClipChangedListener capture, skipping the app's own clips — Clips from our FileProvider authority are ignored to avoid duplicates
    - commitContent MIME negotiation on paste — Tries the field's accepted types in order; static WebP converted to PNG if needed
    - Falls back to the system clipboard with a toast when the field refuses
    - Ctrl+A/C/V/X hardware shortcuts, plus Mac-style equivalents
    - Long-press clipboard actions on A/C/V/X/Z/Y — 6 actions (select all, copy, paste, cut, undo, redo) in each key's alternates popup, each on by default
    - Optional toast confirming a copy
  - Storage and backup `uncommon`
    - Own Storage-screen category with its own delete — files/clipboard, marked personal-danger
    - Config-backup Clipboard section — Only TEXT/HTML/LINK travel; images, files, folders and videos are dropped
    - Sensitive clips excluded from an export regardless of the toggle
  - Capture gating `uncommon`
    - Blocked before first unlock and while the device is locked — History lives in credential-encrypted storage
    - Incognito pauses capture — Separate incognitoPausesClipboard setting, on by default
    - Incognito private clipboard (#392) — incognitoPrivateClipboard, off by default; keyboard copy/cut kept in memory (KeyboardClipboard), keyboard paste pastes it, forgotten when incognito ends
    - Copies made from a password field never reach history
- **Sensitive clips and password hygiene** `RARE` — Two independent passes: at copy time and at paste time
  - Copy-time classification `RARE`
    - Android 13 EXTRA_IS_SENSITIVE honoured — Constant spelled out literally so it is read on every API level
    - Three-way handling — Keep / short-lived (default) / never save
    - Own heuristic detector for apps that do not set the flag — On by default; only fires when handling is not "keep"
    - Bare-code shape — 4–8 chars of A–Z0–9, at least one digit, whole clip only
    - Generated-secret shape — 8–128 chars, no whitespace, 3 of 4 character classes
    - URLs, email addresses and 1900–2099 years explicitly excluded
    - Sensitivity only ever tightens on a re-copy, never clears
  - Sensitive clip lifetime `RARE`
    - Separate expiry timer — 1–120 minutes, default 5, never capped by the history expiry
    - Pinning still overrides the short leash
  - Sensitive clip presentation `RARE`
    - Card masked as bullets plus a character count — 6–16 bullets and a lock icon; the real text is never on screen
    - Deliberately not revealable in place — A peek button would expose the secret without adding a way to use it
    - Excluded from the strip paste chip and from entity-chip scanning
    - Info popup carries a "private" row explaining the short timer
  - Paste-time purge in password fields `RARE` — On by default
    - Clip deleted from history the moment it is pasted into a secure field
    - System clipboard cleared too, but only if it still holds what was pasted — clearPrimaryClip on API 28+, empty ClipData below
    - Covers every paste path — Card tap, strip chip, entity chip, Ctrl+V, and the text-editing panel
    - Pasting a fragment still purges its parent clip — A code pasted out of an SMS would otherwise leave the whole SMS readable
  - Bare-code clips typed character by character `RARE` — A code-shaped clip goes in one char at a time for row-of-boxes code fields
- **Entity detection in clipped text** `RARE` — 3 kinds pulled out of clips as their own chips: OTP, phone, URL
  - Scan bounds
    - 40 newest clips scanned, 4000 chars per clip, 12 chips shown
    - Detection order URL → code → phone, overlapping spans lose — A URL's digits would otherwise read as a phone number
    - A fragment that is the whole clip is dropped — That clip's own card already pastes it
    - Clips masked as sensitive are never scanned
  - One-time-code extraction `RARE`
    - Keyword-anchored only — Token must sit within 40 chars of otp/passcode/verification/2fa/pin/code…
    - 17-word deny list on the word before the keyword — zip, postal, area, country, dial, hex, sort, swift, ifsc, iban, bar, qr, colour…
    - Google's G- branding prefix stripped from the pasted value — Pasting "G-123456" into a six-box OTP field would be wrong
    - Shape rules — Digits required; alphanumeric codes need ≥2 digits; 4-digit years 1900–2099 rejected
  - Phone-number extraction `RARE`
    - 7–15 digits by shape, 4–15 once masks are set
    - Date shapes rejected as whole matches — yyyy-m-d and d-m-yy only, so 555-12-3456 still counts as a number
    - Runs after #, $, £ or € rejected — Order numbers and totals share the shape
    - Unpunctuated, unprefixed runs over 11 digits rejected
    - Word-character guards — emoji_864356927 is a filename tail, not a number to dial
  - URL extraction
    - Trailing sentence punctuation trimmed
    - Balanced-bracket handling — /wiki/Foo_(bar) survives; an unmatched closer is dropped
  - Phone-number format masks `RARE` — User-declared number shapes that narrow the phone pass
    - Mask built from an example number — Dial code stays literal, every other digit becomes X, separators kept
    - X, x and # accepted as wildcards and folded to X on save
    - Separators ignored on both sides — 01712-345678, 01712 345678 and (01712) 345678 are one number to a mask
    - One mask covers four spellings — +880…, 880…, 0171…, and 171… all match a country-code mask
    - A clip with an explicit + or 00 must match a country code — That is what keeps a foreign number out
    - Dial-code length derived from E.164 zones — Zones 1 and 7 = 1 digit, a 44-entry two-digit set, everything else 3
    - Live test field in settings — Paste a number and see match / no match / "all numbers pass" before trusting it
    - Masks can only remove numbers, never add one back — Every impostor guard still applies on top
  - Fragment chips in the panel `RARE`
    - Dashed cut-out styling, deliberately unlike a filled history card
    - Kind tag printed above the value — CODE / PHONE / LINK plus a per-kind icon
    - Long-press shows the fragment highlighted inside its source clip — ±60 chars of surrounding text, ellipsised
    - De-duplicated across clips by kind+value
- **One-time codes from notifications** `RARE` — Verification code lifted off the shade onto the suggestion strip; off by default
  - Capture path `RARE`
    - Single notification-listener component shared with the media tool — Renaming it would silently revoke the grant existing users gave
    - Per-notification gate read from device-protected prefs — The listener module cannot see the settings repository and must answer pre-unlock
    - Own package, ongoing notifications and group summaries skipped
    - 64-entry dedupe on key+postTime — An app updating the same notification does not re-raise a dismissed chip
    - Six text surfaces harvested, visible-first — Title, text, big text, text lines, sub text, summary; 1000 chars scanned
  - Code extraction `RARE`
    - Four anchored patterns in precision order — "482913 is your OTP", "code: 482913", keyword…is…code, "use 4829 to sign in"
    - No "any six digits" tier — Delivery slots, order numbers and flight times arrive as notifications too
    - Split codes rejoined — 123 456 and 123-456 are cleaned to 123456
    - Falls back to the clipboard detector's proximity pass — Also picks up alphanumeric codes the anchored digit patterns skip
    - Shares the clipboard detector's deny list and year guard
  - Offer and lifetime `RARE`
    - Code never persisted anywhere — Single-slot in-memory bus, newest wins, same process as the IME
    - Expiry measured from the notification's post time — 1–10 minutes, default 3
    - Number-fields-only by default — Failing the field gate hides the chip but keeps the code for the next field
    - Suppressed in incognito
    - Optional: cancel the source notification once the code is used
    - Per-digit entry for row-of-boxes code fields — Digits sent as key events with a gap so each box's focus handler can run
    - Turning the feature off drops any code already captured
- **Snippets and text expansion** `uncommon` — 18 template variables plus {date:pattern}; word and regex triggers
  - Snippet panel
    - Two-column cards showing the raw template, not the expanded preview
    - File re-read on panel open and on field entry — Settings app and IME share snippets/snippets.json
    - Tapping a pattern snippet inserts the blank template — Captures left empty and the caret parked in the first gap
    - Snippet order is set by a pencil on each list's heading — One order per list: inside a folder, and outside every folder
    - Folder drill-in — Folder tiles first, then the ungrouped snippets; back climbs out of the folder before it closes the panel
    - Long-press a folder tile to arm or disarm it — Persisted straight to the shared file
  - Folders `uncommon` — One level of named groups; a snippet is in at most one
    - Per-folder switch disarms triggers only — The snippets stay in the panel and still insert on a tap
    - A disarmed folder is left out of the trigger index — Every gate the index answers (hasPatterns, couldStartPattern, the confirm-chip checks) answers no for free
    - Deleting a folder keeps its snippets by default — A switch in the same question deletes them with it
    - Settings drills in too — A folder row opens the folder's own page: name, icon, switch, and the snippets inside it
    - Per-folder icon from the keyboard-mode catalogue — Shown on the Settings row and on the panel tile; falls back to a plain folder
    - Pencil on the Folders heading swaps each switch for a drag handle and a bin — Order and delete live behind it
    - Installed packs get a folder named after the pack — Uninstalling takes the folder too unless something else was moved into it
    - Packs installed before folders existed are adopted on the next addon-screen sweep — Skipped for a pack whose snippets the user has already filed by hand
  - Word triggers
    - Exact, case-insensitive match, fired by space/punctuation/Enter
    - Looked up through a prebuilt index, not a linear scan
    - Skipped for transliterating and conversion composers — Their buffer holds an input spelling, not the word the user meant
    - A word trigger always beats a pattern on the same snippet
  - Pattern (regex) triggers `RARE` — Regex over the words behind the cursor, captures spliced into the text
    - Words-to-match window — 1–8 words, default 3; never reaches across a line break
    - Capture references $0–$9 with four transforms — ${1:upper}, ${1:lower}, ${1:title}, ${1:trim}; $$ is a literal dollar
    - Shortest match wins — Spans tried nearest-cursor-first so a tie consumes less of the user's text
    - Window never anchored when it was cut mid-word — Matching half a word would delete text the user cannot see the start of
    - Surrogate-safe window — An orphan low surrogate at the cut is dropped
    - ReDoS step budget — 40,000 char reads per matcher run, counted through a wrapping CharSequence
    - 40 matcher runs per commit across every snippet
    - A runaway pattern is stopped permanently by id
    - Backreferences and nested quantifiers refused at validation — \1/\k and the (a+)+ shape are rejected before compiling
    - 200-character cap on pattern source
    - Literal-head prefilter bucketed by first character — A pattern starting with a plain word is skipped unless that word is behind the cursor
    - Editor warns when a pattern has no literal start
    - Capture text spliced raw, never re-expanded — A {clip} typed into a captured group cannot pull the clipboard into the field
  - Ask-before-it-expands mode `RARE` — Per-snippet switch turning a trigger into a suggestion-strip offer
    - Offer derived fresh from the field, never remembered — An edit, caret jump or outside change simply stops it matching
    - Word triggers offer mid-word, before the space
    - Patterns re-derive on every keystroke, debounced and off the typing path
    - The offer survives the space that ends the word — Up to 2 trailing non-alphanumeric characters are tolerated
    - Asking and auto patterns are searched separately — Each side checks whether the other kind exists before doing any work
  - Template variables `uncommon` — 18 tokens plus the parameterised {date:pattern}
    - Date and time tokens — {date} {time} {time12} {datetime} {isodate} {isotime} {weekday} {day} {month} {year} {timezone} {timestamp}
    - Context tokens — {clip}, {selection}, {app}, {package}
    - {uuid} generates a fresh value on every insertion
    - {cursor} marks where the caret lands — Private-use code point so snippet text can never collide with it
    - {date:pattern} takes any SimpleDateFormat pattern — Resolved before plain {date}; a malformed pattern expands to nothing
    - Settings screen shows every variable with a live example
  - Expansion behaviour `uncommon`
    - One backspace reverts an expansion — Restores exactly what was typed, up to 256 characters
    - Reverted text muted so the pattern does not re-fire on it
    - Snippet text is never learned into the lexicon
    - The key that fired a caret-parked snippet is swallowed — A space would otherwise land in the middle of the inserted text
    - Composing region finished before the delete — deleteSurroundingText behaves differently in EditText and BasicTextField otherwise
    - Never runs in password fields or no-suggestion fields
  - Import, export and packs `uncommon`
    - .wmsnippets.json versioned envelope — format tag is the only strict check; permissive import MIME list
    - Repair-not-reject import — 500-snippet cap, 20,000-char text cap, blank label filled from the first line
    - A pattern that will not compile is dropped and the snippet kept
    - Import always adds alongside with fresh ids — Importing twice yields two sets rather than overwriting
    - Folders travel in the file and are recreated under fresh ids — Empty folders are not exported; a nameless, repeated or id-0 folder is dropped on import
    - Installable snippet add-on packs, 4 MB, previewable before install
    - Uninstalling a pack removes exactly the ids it added
    - Own config-backup section
- **Contact-aware completion** `uncommon` — Names, emails and app labels held in memory only, never written to disk
  - Contact name suggestions — Off by default; needs the Contacts permission
    - Display names split into component words and indexed
    - Next part of the same contact's name offered as the following word — "Wasi" chains to "Mollik" the way a learned bigram would
    - Contact and app words are never autocorrected away
    - Index dropped the instant the setting is turned off
  - Contact email completion `RARE` — Whole addresses completed from their local part
    - Addresses kept as single tokens, not split on @ . -
    - Minimum 2-character prefix before addresses are offered
    - Only plausible addresses indexed — One @ with content either side and no whitespace
    - Ranked above dictionary and learned words in the strip
  - Email-field force path `RARE` — Completion inside fields that suppress the ordinary strip
    - Deliberately ignores the field's no-suggestions request — Email fields ask for a silent strip, which is where addresses are wanted most
    - Token read straight from the input connection — 96-char lookbehind; email fields keep no composing buffer
    - Token characters include . _ % + - @
    - Up to 5 addresses offered
    - Committed with no trailing space and not learned as a word
  - Contacts in the system spell checker `RARE` — Full flavour only; separate Android spell-checker component
    - Known contact names and emails are not underlined
    - Matching contact name ranked first in the correction menu
    - Reads the same contact-names setting, with no toggle of its own
- **Inline autofill and platform chips** `uncommon` — Android 11+ inline suggestions, split into two independently toggled lanes
  - Two lanes from one API `RARE`
    - Split by InlineSuggestionInfo source — Autofill service chips vs Android System Intelligence chips
    - Separate chip budgets — 6 credential chips, 3 platform chips
    - Separate toggles — Password-manager chips on by default; system smart replies on by default
    - A lane that is off requests 0 chips rather than discarding them later
    - Password-manager chips off closes *both* lanes — one request per field serves both, so asking for replies also diverts credentials out of the manager's dropdown and into a lane that would drop them; the boolean `onInlineSuggestionsResponse` returns is wired to a Consumer and discarded, so they cannot be handed back (#250)
    - Reply chips ranked ahead of action chips within the platform lane
    - Autofill order left exactly as the manager sent it
  - Rendering and safety `uncommon`
    - Declared with `supportsInlineSuggestions` in method.xml — without it the platform never calls onCreateInlineSuggestionsRequest and the manager draws its own dropdown (#250)
    - Per-chip width capped at half the screen — the spec max is what the sender lays out against, so an uncapped one fills the strip and hides the rest
    - Hosted in an Android HorizontalScrollView, not a Compose one — chips are remote surfaces that ignore a Compose clip and keep their full width off screen, so they painted over the chevron, emoji key and dismiss cross and stole their touches
    - Each chip clipped to its visible slice on every scroll and layout (View.setClipBounds)
    - Not on every draw, and not via offsetRectIntoDescendantCoords — AOSP's InlineContentClipView does both and both put chip text over the chevron here; the arithmetic matches AOSP's, so the difference is elsewhere (likely its transparent z-ordered SurfaceView). A translation that moves the row without a scroll or a layout is the known gap
    - Inflated at WRAP_CONTENT in both axes — chips size to their own content, and an exact height outside the spec's range would make inflate throw into a swallowed catch, vanishing every chip silently
    - Measured and inflated against the display context on Android 11–12, where the service's own resources still describe the built-in panel
    - Chips are remote-rendered; the keyboard never sees their contents
    - Chip taps buzz and click like a key — the tap never reaches the keyboard (the renderer sends it straight to the autofill system), so it is read from the empty response that withdraws the row just before the fill, unless a keypress, a field edit or a new field in the last 400 ms explains it; a focus change up to 60 ms later cancels it. A locked vault's tap sends no withdrawal and stays silent (#250)
    - Chip background and text colours follow the theme — the strip's own chip colours, reported out of the composition because the request is built on the service; the first request after process start carries none, since nothing has resolved a theme yet
    - Renderer version read off the request's uiExtras, not echoed back into the request's own extras — an undeclared renderer is taken at v1, since the bundle is empty on every device tested and v1 is the only version there is
    - Both lanes inflated and delivered in one callback — Stops a reply landing a frame before a credential chip and moving the row
    - A chip that fails to inflate is dropped, not fatal
    - Both lanes closed in incognito

**Conditions and gating**

| Feature | Needs |
|---|---|
| Clipboard tool (history, panel, entity chips, phone masks) | ships identically in full and lite; no edition gating |
| Snippets and text expansion | ships identically in full and lite; no edition gating |
| Clipboard link previews | network — direct unauthenticated request to the copied site, off by default |
| Screenshots in clipboard history | needs READ_MEDIA_IMAGES / READ_EXTERNAL_STORAGE; off by default |
| "Show source app" on clip cards | needs the Usage Access special permission; off by default, best-effort guess |
| One-time-code chip from notifications | needs the notification-listener grant (shared component with the media tool); off by default |
| Dismiss the code's notification after use | uses the same notification-listener grant |
| Contact name and contact email suggestions | needs READ_CONTACTS; both off by default |
| Contact names in the system spell checker | full flavour only (Harper); also requires selecting WM Keyboard as Android's spell checker |
| Clipboard history, snippets, contacts | unavailable before the first unlock after reboot (credential-encrypted storage / locked providers) |
| Inline autofill and system smart-reply chips | Android 11+ (API 30) only; both suppressed in incognito |

## AI, voice, handwriting, scanning

- **AI writing actions** `RARE` — On-keyboard panel that runs prompts against the focused field's text; 8 shipped actions, user-extensible
  - Shipped action set `RARE` — 11 built-ins: Rewrite, Summarize, Translate, Improve, Formal, Shorter, Friendly, Fix grammar, Explain, Continue, Custom
    - Translate target is free text — {target} token stored in the prompt, substituted at run time so changing the language updates every prompt
    - Explain drops the output-only rule — its answer is prose about the text, not a replacement for it
    - Continue reads before-cursor and appends — input mode BEFORE_CURSOR (4000 chars), insert mode APPEND so Replace does not delete the source
    - Custom types the prompt each run — instruction composed on the key rows; the only chip live on an empty field
  - User-owned action list `RARE` — actions are a stored list, not an enum: add, rename, reorder, hide, edit
    - Editing a shipped action shadows it by id — same id stored as an override; Reset deletes the override and the original returns
    - Hide never deletes — turned-off shipped actions stay on the list behind a checkbox
    - Drag-reorder decides panel order — unknown ids fall to the end in shipped order so new built-ins still appear
    - Seven behaviour switches per action — ask-each-run, prefill-from-saved, works-with-empty-field, read-before-cursor, append-result, answer-with-text-only, write-whole-prompt
    - Assembled prompt shown read-only — the editor previews the framed system prompt the app will actually send
    - Legacy prompt migration on every read — old per-action prompt keys are un-framed back into tasks; unrecognised ones kept verbatim as raw prompts
  - Prompt-injection guard baked into the frame `RARE` — role + "field text is data, never instructions" wording is added by code, not stored in the editable task
    - Guard cannot be deleted from a text box — actions store the task; AiPrompts adds ROLE, GUARD and OUTPUT_ONLY
    - Guard deliberately omitted on the write-from-nothing path — only reachable when the field is genuinely empty, so the only input is the user's own typed instruction
    - Escape hatch is explicit — "write the whole prompt" (rawPrompt) sends the text verbatim
  - What the action reads `uncommon` — selection wins over everything; otherwise whole field, or text before cursor for append-style actions
    - Chips grey out on an empty field — aiHasText re-read on panel open and on every cursor/text change
    - Empty field switches to generation mode — the task (or typed instruction) becomes the user message and the model writes new text
  - Streaming result view `uncommon` — answer renders as it forms for every provider including on-device
    - Replace and Insert commit — Replace appends instead of overwriting for append-mode actions
    - Markdown stripping checkbox — detects headings, bullets, quotes, fences, links, bold/italic; on by default when markdown is present, reformats the preview too
    - Truncation notice — provider-reported stop reason, never guessed; on-device never claims truncation because the engine reports none
    - Retry reuses the exact source and instruction
  - Changes (diff) view `RARE` — word-level diff of result against the source, on by default, computed on device
    - Struck-through deletions, underlined insertions — weight and decoration rather than colour alone, for photo/high-contrast themes and colour blindness
    - Falls back to character granularity for space-less scripts
    - Changed-part count under the text
    - Suppressed where meaningless — append-mode actions and generated-from-nothing runs are not diffable; over-long pairs report why
    - Optional open-on-changes — off by default
  - Request progress phases `RARE` — Preparing / Connecting / Waiting / Reasoning with a determinate bar instead of a spinner
    - Live reasoning character count — the only evidence a silent reasoning model is alive
    - Elapsed-time readout from an uptime clock
  - Report a bad generation `RARE` — builds a pre-filled mail draft with action, provider, model, instruction and both texts trimmed to 4000 chars
    - Nothing is uploaded — no reporting server; the draft opens in the user's mail app
    - API keys never included
  - Model picker on the panel `RARE` — scrolling chip row of configured providers plus downloaded local models; auto-hidden below two choices
    - Selected chip animates to the front
  - Hardware-keyboard focus ring over the panel `RARE` — chips, results and controls are focus targets (FocusRegion CHIPS/RESULTS)
- **AI providers and connectivity** `RARE` — 9 selectable backends, bring-your-own-key only — no bundled or proxied key for any cloud provider
  - Cloud providers with fixed endpoints `RARE` — 5: Anthropic, OpenAI, Gemini, xAI (Grok), DeepSeek
    - Per-provider default model — claude-sonnet-5, gpt-5.6-luna, gemini-3.5-flash, grok-4.5, deepseek-v4-flash; shown as the field hint
    - Model field is free text — blank falls back to the default above
  - Self-hosted servers `RARE` — Ollama and LM Studio by LAN address, no key required
    - Ollama speaks NDJSON on /api/chat — num_predict under options; thinking on message.thinking
    - LM Studio uses the OpenAI shape at /v1/chat/completions — no default model — uses whatever the server has loaded
    - Cleartext HTTP allowed app-wide for this
  - Generic OpenAI-compatible endpoint `RARE` — user supplies base URL up to the version segment, model and optional key; covers OpenRouter, Groq, Together, Mistral, vLLM
    - App appends /chat/completions only — because services disagree on /v1, /openai/v1, /api/v1
    - Key optional — a gateway on the user's own network often wants none
  - Streaming implemented per provider wire format `RARE` — Anthropic SSE, Gemini streamGenerateContent?alt=sse, OpenAI-shaped SSE, Ollama newline JSON
    - Non-streamed fallback parse — a proxy that ignores stream:true is parsed from the collected body rather than costing a second request
    - Mid-stream error events raised as failures — an error arriving inside the stream would otherwise silently truncate the answer
  - Reasoning channels folded into one shape `RARE` — Anthropic thinking_delta, OpenAI reasoning_content/reasoning, Gemini thought parts, Ollama thinking all wrapped as <think>…</think>
    - Show-model-reasoning toggle — off by default; hidden reasoning is stripped from the result and from what gets committed
    - Implicit-think handling — models whose template opens the think block in the prompt emit bare reasoning ended by </think>
  - Truncation detected per provider `RARE` — stop_reason=max_tokens, finish_reason=length, finishReason=MAX_TOKENS, done_reason=length
  - Response-length control `uncommon` — 8 presets 1024–131072 plus "Provider maximum"; default 8192
    - Provider maximum omits the field entirely — so the service applies its own default
    - Reasoning models get 4x the ceiling — capped at 131072; guessed from 13 model-id substrings (thinking, reason, -r1, qwq, magistral, gpt-5, o1-, o3, o4-, qwen3, grok-4, deepseek-v4)
    - Anthropic over-ceiling auto-retry — Anthropic requires max_tokens and hard-rejects an oversize value; the app reads the real limit out of the error and retries once
  - Conversation normalisation before send `RARE` — blank turns dropped, leading/trailing assistant turns removed, same-role runs merged — Anthropic rejects all three
- **On-device LLM (LiteRT-LM)** `RARE` — A full LLM running locally with no network; 8-model curated catalog
  - Curated model catalog `RARE` — 8 models, quality-ordered: Gemma 4 E2B/E4B, Gemma 3 1B, Qwen 2.5 1.5B, Qwen 3 0.6B, Qwen 2.5 0.5B, Gemma 3 270M, SmolLM2 135M
    - Tier badges — Recommended / Standard / Untested / Experimental
    - Advisory RAM floor per model — 2–8 GB; warns "may be too large" but never blocks the download
    - Two gated models need a Hugging Face token — Gemma 3 1B and Gemma 3 270M; token field plus a link to the licence page
    - Reasoning models flagged in the catalog — Qwen 3 0.6B declares reasoning=true
  - Download manager `uncommon` — process-level singleton, one download at a time, survives navigation and process death
    - Resumable via .part file plus HTTP Range — a server that ignores Range restarts cleanly
    - Free-space preflight with margin — reports roughly how many GB to free
    - Metered-connection confirmation above 500 MB
    - Orphan cleanup — directories left by models dropped from the catalog are reported with a one-tap Free up
  - Import your own model file `RARE` — any .litertlm or .task; GGUF rejected on extension
  - Compute backend choice `RARE` — CPU (default) or GPU
    - GPU failure falls back to CPU and is remembered per model file
  - Context-window setting `RARE` — 5 presets 1024–16384 plus the model's own default; changing it reloads the model
    - No per-response ceiling on-device — the window bounds prompt and answer together
  - Engine lifecycle `RARE` — one cached engine rebuilt only when model file or backend changes
    - Retired conversations closed lazily — closing the native conversation the instant generation finished raced the runtime and crashed the IME
    - Sampler fixed at topK 40 / topP 0.95 / temperature 0.7
    - Streaming through the raw MessageCallback — litertlm's Flow bridge throws NoSuchMethodError on this project's coroutines, on a native thread where nothing can catch it
- **AI chat screen** `RARE` — Multi-turn conversations in the settings app, against the same provider set
  - Saved conversations `uncommon` — 50 conversations, 200 messages each, 20000 chars per message, oldest fall off
    - Auto title from the first user message — cut to 48 chars on a word boundary
    - Per-conversation model memory — last provider and local model id stored with the conversation
    - Kept out of settings backups — same reasoning as the AI history and the learned dictionary
  - Real multi-turn on-device `RARE` — a LiteRT-LM ChatSession keeps context on the conversation's KV cache instead of re-sending the transcript
    - Transcript replay after engine eviction — the IME releases the shared engine on trim-memory; the session rebuilds and replays up to 12000 chars of transcript
    - Session seeded from disk when a chat is resumed
    - Session keyed on conversation + model file + backend + context size
  - Generation controls `uncommon` — streams into the bubble; survives navigation because a static controller owns the run
    - Stop keeps the partial, marked stopped — the full native answer is still mirrored into the session so a later replay matches what the model remembers
    - Retry drops the failed bubble and re-answers the same user message
    - Failed turns excluded from the context sent to the model
  - Launcher shortcut straight into chat `RARE` — wmkeyboard://settings/ai_chat, one of 7 allowlisted shortcut routes
- **AI history and privacy guards** `RARE` — Optional on-device log of every AI run
  - Four-condition write guard `RARE` — a pure, separately tested function: enabled AND device unlocked since boot AND not a password field AND not incognito
  - What a record holds `RARE` — action id and name-at-the-time, provider, model, input, output, duration, instruction, reasoning chars, streamed flag, error, truncated flag
    - Whether the answer was actually used — NONE / REPLACE / INSERT, written back when the user commits
    - Failed runs recorded with the message the panel showed
    - Connection details and API keys never stored
  - History screen `RARE` — search across input, output and model name; filter by action; expand to copy either side or delete
    - Cap 100 by default, ceiling 500; 4000 chars per side
    - Turning the setting off deletes the file
    - Excluded from settings backup
  - API keys excluded from settings backup `uncommon` — ai_anthropic_key, ai_openai_key, ai_gemini_key and friends are on the never-export list
- **Voice dictation (system recognizer)** — Platform SpeechRecognizer wrapper, fresh recognizer per session
  - On-device recognition preferred — API 31+ createOnDeviceSpeechRecognizer: faster, offline, no per-utterance beep
    - Transparent one-time fallback to the network recognizer — a language the on-device model rejects is remembered and skipped from then on
    - Recognizer-side punctuation/casing requested on API 33+ — EXTRA_ENABLE_FORMATTING = FORMATTING_OPTIMIZE_QUALITY
  - Offline language-model management `uncommon` — checks installed / downloadable / pending per language and offers the system download
    - In-panel download chip named for the dictation language — "Get Spanish for offline dictation"; falls back to generic wording for an unknown language
    - Progress callback on API 34+, fire-and-forget on 33
    - Region-tolerant tag matching — bn matches bn-BD
  - Continuous dictation — on by default; chains straight into the next utterance
    - Silence restarts quietly, twice — after 2 silent retries the mic winds down instead of listening forever
    - Next session deferred to the next looper tick — starting synchronously inside onResults raced teardown and spuriously errored on some OEM builds
  - Spoken punctuation — on by default; 10 English phrases and 10 Bengali phrases, longest-match first
    - Bengali dictates the danda — "দাঁড়ি" types ।, not .
    - Applied to final results only — partials stay raw
    - Mark attaches with no leading space
  - Context-aware spacing `uncommon` — reads the characters either side of the cursor to decide on a leading and/or trailing space
    - Re-measured after a rail keystroke — so a space typed on the panel does not become two
  - Undo the last dictated phrase `uncommon` — one-tap removal while the committed text is still immediately before the cursor
  - Dictated words are learned `uncommon` — same learning path as typed words, so dictated vocabulary reaches suggestions and autocorrect
  - Language follows the active layout — BCP-47 tag from the layout's locale; no separate voice language picker
    - EN / non-English switch chip in the panel — only when both an English and a non-English language are enabled
  - Failure handling — 6 error kinds mapped to specific messages: no speech, network, busy, permission, language, other
    - Network drop mid-utterance keeps what was heard
    - Mic never opens in a password field
    - Permission requested through a trampoline activity — IMEs cannot show runtime permission dialogs; the panel rechecks on resume
  - Dictation stops on manual input `uncommon` — a key, swipe or suggestion tap ends the utterance because cumulative partials would be corrupted
- **Voice surfaces** `RARE` — Three dictation UIs from one session: full panel, over-the-keys strip, floating collapsed bar
  - Full panel — large mic with a level-driven pulse ring, plus a 4-key action rail
    - Rail keys are Delete, Space, context-aware Enter, back-to-keys
    - Hold-to-talk — past 600 ms the mic is walkie-talkie: listens while held, stops on release; a tap still toggles
    - Rail keys do not end the recording — except when a system partial is sitting in the editor as composing text
    - Stop anywhere while listening (#283) — the whole side left of the rail takes the stop press, tinted while it does; chips and the mic keep their own presses, pointerInput so TalkBack still has one mic node
  - Compact strip over the keys `uncommon` — replaces the suggestion strip, keys stay usable underneath
    - Stop anywhere while listening (#283) — everywhere on the bar that is not another button finishes the phrase; listening only, an idle bar never opens the mic for a stray touch
  - Voice tool is the stop button (#283) — pressed over a dictation running on the strip or panel it finishes the phrase (endVoiceFromTool) and the surface closes once the words land (settleVoiceToolEnding); it used to cancel, which threw a Whisper or server clip away. The strip's close button (VoiceBarAction.CloseStrip) and the panel's keyboard key still abandon; an error keeps the surface up
  - Floating collapsed bar `RARE` — Gboard-style voice toolbar: the keyboard gives its whole window to a draggable pill so the app behind is visible
    - Touchable region shrunk to the pill — everything around it falls through to the app
    - Horizontal pill snaps to 3 rests and keeps its height
    - Vertical pill docks to either screen edge and keeps its position along it
    - Rest position persisted, local-first — deriving it from settings made the pill spring back while the DataStore write was in flight
    - Hamburger menu page — back, undo, language, upright toggle, settings
    - Exit control depends on how the bar was entered — an inline collapse shows Expand back to the surface it replaced; a settings choice shows the keyboard button
    - Survives the IME process being killed between fields
  - Surface switching mid-session `RARE` — collapse from panel or strip into the bar and expand back to whichever it was
- **Offline Whisper dictation** `RARE` — Second dictation engine that transcribes entirely on device; 29-model catalog
  - Model catalog `RARE` — 29 graphs: 10 multilingual (7 auto-detect, 3 language-selectable) plus 19 single-language covering 13 languages
    - Sizes Tiny through Large, plus Turbo as its own class — large-v3-turbo downloads at Medium size but transcribes near Large accuracy
    - Grouped graphs take a language token — TOP_WORLD covers 40 languages, EUROPEAN_UNION 26; the keyboard forces the language being typed in
    - Single-language graphs only appear once that language is enabled — en, de, es, fr, hi, it, ja, pt, ru, ta, te, ur, zh
    - Two mel bandwidths handled — large-v3 and turbo need a 128-band filterbank; every older graph needs 80, and the band count is read from the downloaded file
    - Deliberate exclusions documented — duplicate and timestamp-emitting graphs are left out
  - Per-language model routing `RARE` — 5-step fallback rather than one global model
    - Order: pinned model, largest single-language, global fallback, best-ranked covering, then anything downloaded
    - Last resort is deliberate — wrong words beat a dead microphone; the row is flagged in the error colour
    - Sole downloaded model adopted as the fallback automatically
    - Recommendation shortlist from enabled languages — capped at 4, spanning the accuracy/size trade-off
  - Wrong-script rescue `RARE` — a Bangla clip auto-detected as Hindi is mapped from Devanagari back to Bengali by codepoint offset
    - Only runs when the transcript's script disagrees with the layout's script
    - Explicit exception tables for characters with no counterpart
    - Never runs on a language-forced or single-language graph
    - Settings flags languages nothing can be told about — and points at the models whose detection is best
  - Capture model `RARE` — 16 kHz mono into a fixed 30-second float buffer, VOICE_RECOGNITION source
    - Buffer full auto-transcribes — continuous mode then starts the next clip
    - No live partials — the whole clip is transcribed after you stop; the panel says "tap when you're done"
    - Keystrokes during transcription never cost a recording — the audio is already in the recorder, not the editor
  - Speech translation to English `RARE` — where the graph was actually trained for it — 9 of the 10 multilingual models
    - Turbo excluded on purpose — it carries the translate signature but was trained for transcription only, so running it returns confident nonsense
  - Whisper downloads `uncommon` — two files per model into one directory, both required
    - Small vocab file fetched first so a broken connection fails fast
    - Resumable .part plus Range, one at a time
    - Metered confirmation above ~150 MB
    - Storage total and orphan cleanup on the same screen
  - No prompt or arbitrary language forcing `RARE` — the published .tflite conversions traced generate() inside the graph, so only the spectrogram and a lang_token are reachable
  - Missing-model state offers both ways out `uncommon` — download a model, or switch back to the system recognizer and start listening immediately
- **Handwriting** — ML Kit digital-ink recognition on a full-width canvas, or drawn straight on the letter keys
  - Model catalog read from the library, not hardcoded `RARE` — ML Kit's own identifier table minus autodraw/emoji/shape/gesture models, filtered to enabled languages
    - 32 script codes mapped for variant selection — keeps Sanskrit on sa-Deva-IN rather than the romanised sa-Latn
    - Subtag aliases — nb→no, tl→fil
    - Languages with no ink model are called out and fall back to the nearest that has one
  - Per-language model manager `uncommon` — one row per enabled language: download, downloading, downloaded, delete, failed
  - Recognition context `uncommon` — 20 chars of pre-context (ML Kit's own cap) plus the writing-area size, up to 4 candidates
    - Top candidate commits, alternates go to the suggestion strip — tapping one replaces the committed word, same mechanics as glide typing
    - One recognizer cached; switching language closes the old one
  - Ink controls — canvas plus a 4-key rail (Delete, Space, Enter, back to keys)
    - Undo-last-stroke re-runs recognition on what remains
    - Delete discards all pending ink while ink is unrecognised — and reverts to deleting committed characters once the strokes have become text
    - A single tap counts as a stroke — so a full stop or the dot of an i is not lost
    - In-panel language chip when two or more languages have models
  - Commit timing `uncommon` — recognition pause default 700 ms, adjustable 300–2000 ms
    - Bengali floor of 1200 ms — conjuncts, matra and vowel signs are separate strokes, so a natural pause would commit half a glyph
  - Stylus handling `uncommon` — stylus-only toggle plus automatic palm rejection
    - Finger touches ignored for 800 ms after a stylus point
    - Only the first pointer draws, so a resting palm never adds ink
  - Handwrite with swipes on the letter keys `RARE` — LetterSwipeAction.HANDWRITE turns a glide across the keys into ink instead of a word
    - Dot leeway after a stroke — default 700 ms, 0–1500 ms: a tap over the letters becomes the dot on i/j/t instead of typing the key
    - Ink commit waits out the leeway — otherwise the dot would have no character to join
    - Taps still type normally
  - Text conventions `uncommon` — auto-space between consecutively written words, never before punctuation
    - Sentence-start capitalisation only for en-US, never in a secure field
- **Scanners** `uncommon` — Three camera tools: text OCR, QR/barcode, and document scan
  - Text scan (OCR) `RARE` — ML Kit Latin text recognition inside the keyboard, full-bleed over the toolbar
    - Tesseract for other scripts (#306) `RARE` — engine setting Automatic / ML Kit / Tesseract; language chip on the viewfinder; tessdata_fast packs downloaded per enabled language from the panel or the tool page; slim 1.7 MB native library (native/tesseract-jni); reads twice (Sauvola local threshold, then Otsu) and keeps the read with more text, since global Otsu blacked out unevenly lit photos; a failed read or a pack that won't load shows as an error, not as "no text"
    - Recognised words become tappable chips grouped by line
    - Start-with-everything-selected toggle — on by default: tap to deselect and trim the capture down
    - Select-all / deselect-all toggle, Copy and Insert act on the selection
    - WYSIWYG capture — shared CameraX ViewPort crops the capture to exactly what the viewfinder framed
    - Capture targets 2048x2048 — more pixels than a chat photo needs for small print, less than the full sensor
    - Torch toggle when the lens has a flash unit
    - Camera released while the frozen result is on screen
  - QR and barcode scanner `RARE` — continuous decode with no shutter tap; 13 formats labelled in the result
    - Formats: QR, Aztec, Codabar, Code 39/93/128, Data Matrix, EAN-8/13, ITF, PDF417, UPC-A/E
    - Frame skipping instead of queueing — a busy flag drops frames while the previous one decodes
    - Auto-insert option — off by default; types the value the instant it is spotted
    - Haptic on detection — on by default
    - Link preview for URL payloads — off by default; fetches page title and description, and an Open button appears
    - Pinch to zoom with a percentage pill above 1.05x
    - Rescan re-arms the decoder
  - Document scanner `RARE` — hands off to Play services' GmsDocumentScanner (edge detection, crop, cleanup) through an invisible trampoline activity
    - Gallery import allowed alongside the camera
    - Pages come back as JPEGs and are committed one at a time when the IME regains the field
    - Pending-page directory trimmed to the 8 newest
    - Optional copy into Pictures/WM Keyboard
    - Tool hidden entirely on a device without Play services
  - Shared camera permission gate `uncommon` — one trampoline activity for OCR, QR and the camera tool; the panel rechecks on resume
- **Camera tool** `uncommon` — Live viewfinder inside the keyboard that sends a photo into the field, both editions
  - Viewfinder controls `uncommon` — tap to focus, pinch to zoom, flash cycle, self-timer, lens switch
    - Flash cycles Off → Auto → On, shown only when the lens has a flash unit
    - Self-timer cycles Off → 3s → 10s with a large countdown digit and a tick per second
    - Zoom pill appears above 1.05x, clamped to the lens range
    - Front/back switch only when the device has both
  - Window-clamped crop `RARE` — the preview overflows the panel, so the capture is sliced to exactly the on-screen region at shutter time
    - Send-the-whole-photo option keeps the full 4:3 frame
    - Confirm step redraws the photo at the exact spot the viewfinder had it
    - Captures capped at 1600x1600
    - Selfie mirroring option, on by default
  - Sending `uncommon` — commitContent against the field's accepted MIME types, clipboard fallback with a toast
    - Optional copy into Pictures/WM Keyboard
    - Scratch captures pruned to the 4 newest on each panel open
  - Per-tool feedback settings — shutter sound and in-panel haptics are separate toggles

**Conditions and gating**

| Feature | Needs |
|---|---|
| On-device LLM provider and its whole model catalog | full flavour only (BuildConfig.ENABLE_LOCAL_LLM; LiteRT-LM) — the provider chip is absent in lite |
| Offline Whisper dictation and the Recognition-engine picker | full flavour only (BuildConfig.ENABLE_WHISPER); the section does not render in lite |
| Handwriting panel and handwrite-with-swipes | full flavour only (BuildConfig.ENABLE_ML_KIT_HANDWRITING; ML Kit digital ink) |
| Text scan (OCR) and QR/barcode scanner | full flavour only (BuildConfig.ENABLE_ML_KIT_SCANNERS; ML Kit text + barcode) |
| Document scanner | full flavour only, and additionally requires Google Play services — the tool is hidden when Play services is absent |
| Every cloud AI provider (Anthropic, OpenAI, Gemini, xAI, DeepSeek) | needs a user-supplied API key and network; no bundled or proxied key exists |
| Ollama and LM Studio providers | needs a reachable server address on the user's network; traffic is plain HTTP (cleartext allowed app-wide) |
| On-device LLM model downloads | network (Hugging Face); the 2 gated Gemma models additionally need a Hugging Face token and an accepted licence |
| Whisper model downloads | network (Hugging Face); ~40 MB to 1.5 GB per model, metered confirmation above ~150 MB |
| Handwriting language models | one-time network download per language through ML Kit |
| Voice dictation (any engine) | needs the RECORD_AUDIO runtime permission, requested through a trampoline activity |
| System speech recognition without the on-device language pack | sends audio to the OS recognizer service; the on-device model download itself needs network |
| Camera tool, OCR and QR scanner | need the CAMERA runtime permission (shared trampoline) |
| QR scanner link previews | network; force-disabled by Power Saving's background-network option |
| Whisper engine and handwrite-with-swipes | silently downgraded by Power Saving's "drop on-device models" option (Whisper → system recognizer, handwrite → glide typing) |
| AI tool, handwriting, all three scanners and the camera tool | not direct-boot safe — unavailable until the device has been unlocked once after a restart |
| AI history and AI chat transcripts | stored only on device, deliberately excluded from settings backup; history additionally requires the user to enable it and is never written from a password field or in incognito |
| Report a bad AI generation | opens a draft in the user's own mail app; there is no reporting server and nothing is uploaded |
| Save-to-gallery for camera captures and scanned pages | writes into shared storage (Pictures/WM Keyboard); off by default |

## Privacy, backup, storage, statistics

- **Fingerprint lock** — Optional BiometricPrompt in front of the settings screens and destructive buttons the user picks.
  - Curated target registry — 17 lockable items (9 screens, 8 actions) in one file; a screen costs one entry, an action that entry plus a `lock =` argument.
    - Labels borrow the guarded row's own string — Configurator reads in the same words as the thing it protects and inherits its glyph.
    - Source-reading drift test — AppLockTargetsTest fails on a route with no destination or an action with no call site.
  - Self-locking configurator — The `applock` route resolves to AppLockTargets.SELF, so the screen holding the off switch is behind the prompt.
    - Both toggle directions authenticate — Controlled switch; the value is written only after a passed check.
    - First enable seeds the defaults — Eight targets ticked once, on an empty selection; turning the feature off keeps the picks.
  - One gate for every screen — SettingsScreen already carries the route, so the check covers deep links and EXTRA_OPEN_ROUTE with no per-screen wiring.
    - Body-only replacement — Top bar, title and shared-element flight survive, so a locked screen still says where you are.
    - Cancel pops, lockout explains — A cancel leaves the screen; ERROR_LOCKOUT keeps the panel and its reason with a Retry.
  - Configurable re-lock — Immediately / 1 min / 5 min / on leaving / until the app closes, on elapsedRealtime so a clock change cannot extend a window.
    - Screens share one grant, actions never do — An irreversible write asks every time, however recently the user answered.
    - Session is memory only — Never written to disk, a Bundle or savedInstanceState; a rotation keeps it, a kill does not.
  - Fails open when unanswerable — No enrolled biometric and no screen lock means the gates stand aside rather than shutting the owner out.
    - BIOMETRIC_WEAK plus DEVICE_CREDENTIAL — The one combination legal on every API level, so there is no SDK fork; nothing here is encrypted, so weak is the honest class.
    - PIN fallback on by default — The only route back after a sensor lockout, and the only thing that works with no reader.
- **Servers (F-Droid)** — Every address the app calls is a setting on the F-Droid build, so no service is tethered.
  - Advanced › Servers — One screen listing every API and download repository; the same rows sit on each tool's own page.
    - 28 API base addresses — Wikipedia/any MediaWiki, dictionary, Wiktionary, kaikki, Open-Meteo, currency sources, Keyman, Noto animations, F-Droid repository, and the keyed ones (Brave, KLIPY, GIPHY, Unsplash, Pexels, Google Translate, cloud AI) for proxies or clones
    - Blank means the default — Nothing moves until a field is edited; a half-typed address is ignored and the field says which server is used
  - Git mirrors on any forge — Language data, add-on and key-sound repositories and the Espanso Hub on GitHub, Forgejo/Gitea (Codeberg), GitLab, SourceHut, Bitbucket or a plain HTTPS folder
    - Paste a repository link — Any forge's page address fills in host, owner, repository and branch
    - Add-on repository links learn the same forges — A pasted Codeberg or GitLab page resolves to its raw wmkeyboard-repo.json
  - Update check on any F-Droid repository — IzzyOnDroid's string version codes read the same as f-droid.org's numbers
- **Incognito mode** — One boolean, toggled from a toolbar tool or Privacy settings; five defined effects.
  - Manual incognito toggle — Toolbox tool + Privacy switch drive the same setting; toast and haptic on toggle.
    - Toolbar badge while active — Badge next to the toolbar and the tool renders in its active state.
    - Toast when field is already incognito — Tapping the tool in an auto-incognito field says the switch has nothing to turn off.
  - Auto incognito per field — Reads IME_FLAG_NO_PERSONALIZED_LEARNING; on by default, scoped to that field only.
    - privateImeOptions fallback — Also accepts the pre-Oreo `...noPersonalizedLearning` string some apps still send.
    - Never touches the manual switch — Leaving a private tab restores the global setting instead of leaving incognito on.
  - Per-effect incognito sub-switches `uncommon` — Pause learning and pause clipboard capture are independently toggleable, both on by default.
    - Learning pause covers Latin lexicon and CJK history — One shared `learningAllowed` gate so both stores go quiet together.
    - System-dictionary writes follow the same gate — "Add words to system dictionary" pauses with the lexicon, no separate check.
    - Typing statistics follow the learning pause — recordStat re-derives the gate per event; paused stretches never enter active time.
  - Inline chip block (ungated) `uncommon` — Autofill credential chips and platform smart replies both return a zero budget in incognito.
    - Read off EditorInfo, not cached state — Autofill request is built in onStartInput, before UI state exists, so the flag is re-read.
  - AI history pause `RARE` — AiHistoryGuard requires enabled AND unlocked AND not-secure-field AND not-incognito.
    - No switch of its own — Deliberately not user-overridable; the four noes are a pure, unit-tested function.
- **Secure-field handling** — Password/PIN input types detected off inputType; independent of incognito.
  - Secure-field detection — TEXT password, visible-password, web-password variations plus NUMBER password variation.
    - Strip suppression cannot be overridden — "Suggestions in every field" never re-enables the strip in a password variation.
  - Password-paste purge `RARE` — Pasting into a password field deletes the clip and clears the system clipboard; on by default.
    - Covers every keyboard paste path — Clipboard panel, paste chip, hold-V and Ctrl+V; not the field's own long-press menu.
  - Sensitive-clip policy `uncommon` — Three-way choice: keep, hide-and-expire (default 5 min), never save.
    - On-device shape recogniser — Extends Android 13's app-set sensitive flag; whole-token check so quoted codes are ignored.
    - Masked render, no reveal-in-place — Lock icon and character count; tapping pastes straight into the field.
    - Code fields are the one exception — A copied OTP is still offered as a chip, only in digit-asking fields.
  - Hide toolbar & clipboard on lock screen `uncommon` — Drops the whole top strip and blocks the clipboard panel while the keyguard shows; off by default.
- **On-device learning controls** — Privacy screen group governing what the keyboard is allowed to remember.
  - Learn from typing — Master switch for the personal lexicon, bigrams, trigrams and skip-grams; on by default.
  - Add words to system dictionary `uncommon` — Mirrors typed words into Android's shared personal dictionary; off by default.
    - Only genuinely typed words — Reinforcement 0 (autocorrect targets) is skipped; they are already dictionary words.
  - Expand dictionary shortcuts `RARE` — Reads shortcuts back out of Android's system dictionary and offers the expansion.
  - Clear learned words — One button deleting four learning files plus the in-memory CJK store.
    - Files removed — user_lexicon.json, emoji_usage.json, correction_stats.json, cjk_history.json.
    - CjkLearning store cleared in memory — Otherwise the process-wide object would write the picks straight back.
- **Direct boot / locked device** `RARE` — The keyboard runs before first unlock with a deliberately narrowed feature set.
  - LockedSettings mirror `RARE` — Settings mirrored as one typed-JSON blob in device-protected SharedPreferences.
    - Credentials filtered on the way in — SettingsBackup.SECRET_KEYS dropped by both write() and locked-mode edit().
    - Locked edits are transient — First write after unlock overwrites them with the credential-encrypted truth.
    - SharedPreferences, not a second DataStore — A synchronous read so the locked keyboard can draw its first frame.
  - restrictedToDirectBoot settings view `RARE` — ~15 settings forced off because their files live in credential-encrypted storage.
    - Tools filtered three ways — enabledTools, toolbarTools and toolboxOrder all pass isDirectBootSafeTool.
    - Theme image paths stripped, recursively — Theme and its variants lose backgroundImage/Photo; photo rotation disabled.
    - Fonts and sounds fall back — keyFontId, scriptFontIds, emojiFont reset; CUSTOM/PACK key sounds drop to CLICK.
    - Provider-backed suggestions off — Contacts, contact emails, app names and system-dictionary writes disabled.
    - Clipboard fully off — history, suggestRecent and userScreenshots all false while locked.
    - Handwriting swipe reverts to word typing — The ML Kit model lives in filesDir and could only reach a download prompt.
    - Offline dictation forced to system engine — Whisper weights are in filesDir; the OS recognizer still works.
    - OTP chip disabled — The lock screen redacts notification content; a chip would print it anyway.
  - Personal stores never mirrored `RARE` — Learned words, clipboard, snippets and emoji history stay behind entirely.
  - Device-protected crash log and dictionary `RARE` — debug/ and a bundled dict copy live in DE storage so a locked boot still works.
- **Config backup file** `uncommon` — One `.wmconfig.json` bundle of 11 independently toggleable sections.
  - 11 backup sections `RARE` — settings, themes, dictionary, clipboard, snippets, stickers, icons, wordlists, emoji, addons, statistics.
    - Emoji history section — Recents, use counts, favourites and the per-emoji skin tone.
    - Statistics section — Daily typing counts and lifetime totals; counts only, never text.
    - Addons section is the repo list — Repository addresses only; installed addons ride in Themes/Icons.
    - Theme backgrounds embedded as base64 — Re-extracted to files/theme_images on import so a device-local path is not restored.
    - Sticker and icon packs embed image bytes — Manifest plus base64 files, so a restore gets working packs not empty shells.
    - Sticker originals excluded — Only stickers the manifest names travel; stickers/.originals photos stay on device.
  - Generic settings codec `uncommon` — Walks the raw DataStore preference map, so a new setting is backed up the day it lands.
    - Type tag per value — boolean/int/long/float/double/string/stringSet, since JSON numbers are untyped.
    - Unreadable entries counted, not fatal — One bad line costs that setting, not the other two hundred.
  - Secrets excluded by default `RARE` — 19 named SECRET_KEYS held out of every export unless "Include API keys" is on.
    - Covers backup credentials too — Passphrase, WebDAV password, S3 secret, FTP, SFTP, SMB and IMAP passwords, SFTP keys, Git tokens, Dropbox and OneDrive refresh tokens.
    - Covers 13 service keys — Translate, Klipy, Brave, Giphy, five AI providers plus compatible, HF, Unsplash, Pexels.
    - Warning after export and before import — "Treat that file as a password"; the import dialog warns keys will overwrite existing ones.
    - Same set LockedSettings refuses — One list drives both export redaction and device-protected-storage filtering.
  - Install-local keys never travel `RARE` — 5 TRANSIENT_KEYS held back so a restore cannot arm a backup pointing at another device.
    - Keys held back — auto_backup enabled, folder URI, KDF salt, last-run time, last error.
  - Import confirmation before writing `uncommon` — File is parsed and itemised ("Themes: 3 custom themes") before anything is applied.
    - Per-section merge vs replace — Settings and addon repos merge; themes, dictionary, clipboard, stickers, icons, wordlists replace.
    - Rollback-safe settings import — Re-reads settings after writing; an unparseable result restores the snapshot wholesale.
    - Empty-decode guard — decodedList refuses to treat a failed decode of a non-empty section as "user has none".
    - Newer bundle version refused outright — Most sections replace, so a half-applied unknown format is not recoverable.
    - Path-traversal guard on pack restore — Name regex plus canonical-path comparison for every sticker and icon file.
    - Clipboard export is text-only — portableClipboard drops image/file clips and anything flagged sensitive.
    - Opening from a file manager uses the same dialog — No silent import path exists.
  - Legacy settings-only format `uncommon` — `.wmsettings.json` still accepted on import; nothing writes one anymore.
- **Automatic backup** `RARE` — Scheduled unattended export of the same bundle to a destination the user owns.
  - 11 destinations `RARE` — SAF folder, WebDAV, Google Drive (appdata or a visible folder), S3, Dropbox, OneDrive, FTP, SFTP, SMB, Git, IMAP. No first-party server.
    - SAF folder — Persisted tree URI; reaches any DocumentsProvider, needs no account, works without Play services.
    - WebDAV — Nextcloud/ownCloud and friends; plain http refused because the password crosses the wire.
      - Service presets — Nextcloud, ownCloud, Seafile, Koofr, pCloud, Yandex, kDrive, Storage Box, 4shared build the URL; missing folder made by MKCOL.
      - Nextcloud Login Flow v2 — Browser sign-in hands back an app password; the account password never reaches the app.
    - S3-compatible — AWS, MinIO, R2, B2, Wasabi, Garage; own SigV4 signer, path-style toggle.
      - Service presets — 14 providers fill endpoint, region examples and addressing from a region or account field.
    - Google Drive — appDataFolder with drive.appdata, or a visible My Drive folder with drive.file; gms source set only.
    - SFTP `RARE` — JSch for SSH only, own SFTP v3 client (JSch's ChannelSftp dies on API 24); ML-KEM, curve25519, ed25519 and chacha20 via Bouncy Castle; trust-on-first-use host key pinning.
    - SMB 2/3 `RARE` — Hand-written client: NTLMv2 in SPNEGO with MIC, signing, 3.1.1 preauth integrity, AES-GCM/CCM encryption on by default; guest fallback refused.
    - Git repository `RARE` — GitHub, GitLab, Gitea/Forgejo REST contents APIs; every backup a commit; public repos refused; message template, author, branch, [skip ci].
    - IMAP `uncommon` — One message per backup in a dedicated folder; APPENDUID, UID EXPUNGE, hostname-verified TLS.
    - Dropbox and OneDrive — App-folder scopes via PKCE in a real browser, no SDK and no client secret.
    - FTP — Hand-rolled socket client, AUTH TLS on by default; plain FTP allowed with a stated cost.
    - Five-verb sink interface — readiness, write, list, read, delete; every method returns Result, never throws.
    - Typed failure reasons — NOT_CONFIGURED, PERMISSION_LOST, TARGET_MISSING, OUT_OF_SPACE, UNSAFE, IO; only IO is retried.
  - Scheduling `uncommon` — JobScheduler periodic job, charging-required, 6/12/24/168-hour intervals.
    - Idempotent sync — An already-correct job is left alone, so process start does not restart its period.
    - Not setPersisted — Avoids RECEIVE_BOOT_COMPLETED; the keyboard re-establishes it seconds after a reboot.
    - Clock-skew tolerant due check — A last-run time in the future triggers a run rather than a weeks-long wait.
    - Runs in :app job service, not the IME — A hidden IME is the most killable process on the device.
  - Never-lose-a-generation ordering `RARE` — Stage locally, rename, read back and parse, upload, then rotate.
    - Verify by full decode — Encrypted staging files are decrypted and ConfigBackup.decode'd before upload.
    - Rotation is the last step — Nothing older is deleted until the new file is confirmed at the destination.
    - Keep 3/5/10, newest never deleted — keep is floored at 1; sorted by modified time with filename as tiebreaker.
    - Strict ownership check — Only `wmkeyboard-auto-*.wmconfig.json/.enc` is rotatable; hand exports use a different prefix.
    - .part files swept separately — Half-written files are recognised and cleaned without counting as a generation.
    - Locked device is skipped, not failed — A backup taken before first unlock would be nearly empty and would evict good ones.
    - Process-wide mutex — "Back up now" and the scheduled job cannot fight over the staging file.
  - Heap guard on bulky sections `RARE` — Above a 16 MB embedded estimate, stickers/icons/wordlists are dropped and named in the result.
  - Failure visibility `uncommon` — Last-run time or the last SinkError is shown as a caption under the group.
    - Personal-sections warning — Including dictionary or clipboard without encryption prints an explicit warning.
- **Backup encryption** `RARE` — Optional passphrase encryption of the bundle, own container format.
  - AES-256-GCM container `RARE` — `WMKB` magic + `ENC`, 44-byte header, 12-byte nonce, 128-bit tag.
    - Whole header is AEAD associated data — Stops an attacker rewriting the iteration count down to 1 for cheap offline cracking.
    - Fresh nonce per file, per-install salt — SecureRandom nonce each write; one 16-byte salt stored once per install.
    - Header carries its own iteration count — Raising the default later does not invalidate existing files.
    - Separate .wmconfig.enc extension and octet-stream MIME — Providers append .json to a JSON-typed file, so the type is deliberately not JSON.
  - Hand-rolled PBKDF2-HMAC-SHA256 `RARE` — 120 000 rounds default, 2 000 000 ceiling, built on HmacSHA256 for API 24 support.
    - Iteration ceiling stops a hostile file — The count is read before authentication, so an unbounded value would hang a restore.
    - Passphrase kept as CharArray — UTF-8 encoded without ever materialising a String on the heap.
  - Non-streaming decrypt `RARE` — Buffered into one doFinal because Android's CipherInputStream swallows AEADBadTagException.
    - Four decrypt outcomes — Ok, BadPassphraseOrCorrupt, NotEncrypted, UnsupportedVersion.
    - Wrong passphrase and tampering are not distinguished — The UI states both possibilities rather than guessing.
  - Stated threat model `RARE` — Passphrase is stored in the clear because an unattended backup has nobody to type it.
    - Protects the file where it lands — Cloud folder or shared drive; not against someone holding an unlocked phone.
    - Secrets only ride along when encrypted — includeSecrets is ANDed with encrypt in the automatic path.
  - Encrypted import flow `RARE` — Magic-byte sniff on import, then a passphrase prompt before the usual confirmation.
- **Android system backup** `RARE` — Platform Auto Backup folded in behind a runtime opt-in switch, off by default.
  - Runtime opt-in via BackupAgent `RARE` — allowBackup is build-time, so the agent writes nothing unless the setting is on.
    - Flag read from device-protected storage — Backup runs when idle and charging, possibly before unlock, so LockedSettings holds it.
    - Restore deliberately not gated — A restore can only replay data an earlier install was allowed to make.
  - Extraction rules `uncommon` — Everything included by default; 9 exclusions, all size rather than secrecy.
    - Excluded — models, whisper, dict, cjk_dicts, emoji_dict, emoji_keywords, camera, docscan.
    - Clipboard images out, clip text in — files/clipboard/images excluded; history.json travels.
    - Sticker originals out, stickers in — stickers/.originals is the largest thing there and only buys a future edit.
    - Same list for device-transfer — A separate <device-transfer> block mirrors the cloud-backup exclusions.
  - Client-side encryption required `uncommon` — disableIfNoEncryptionCapabilities: no backup on a device that cannot encrypt under the screen lock.
- **Storage manager** `RARE` — In-app breakdown of every byte the app uses, with per-item deletion.
  - 28 categories in 6 groups `RARE` — App, Downloads, Looks, Personal, Cache, System; 25 walked plus 3 synthetic.
    - 8 personal categories — learned words, typing stats, clipboard, snippets, AI history, custom word lists, captures, settings store.
    - 5 cache categories — image cache, media cache, addon downloads/previews, temp files, and the cache residual.
    - Two residual rows — "Other cache" and "Other data" so the bars always add up to the system figure.
    - Residuals are itemised, not opaque — Unclaimed directories are listed by name (read-only) instead of shown as a number.
    - Adding a directory means adding a row — Otherwise its bytes land silently in the residual.
  - System-authoritative totals `RARE` — StorageStatsManager.queryStatsForPackage, so the screen agrees with Settings → Apps.
    - No permission needed — PACKAGE_USAGE_STATS is only for querying other packages.
    - Pre-API-26 fallback marked as an estimate — The screen says the figure is approximate rather than silently disagreeing.
    - du-style block accounting — Every file rounded up to the filesystem block; symlinks measured as nothing, never followed.
    - Device-protected tree counted — A filesDir-only walk would under-report and inflate the residual.
    - Marketing-capacity snapping — 256 GiB reported by the vendor is shown as the 256 GB on the box.
  - Deletion routed through owning stores `RARE` — deletePack, FontStore.delete, repository.clearAllPreferences rather than raw file removal.
    - Four danger levels — NONE, REDOWNLOAD, PERSONAL, RESET; each gets its own confirmation wording.
    - Settings reset confirmed twice — The only action here that is both irreversible and impossible to preview.
    - Version counters bumped after clears — bumpLexiconVersion / bumpStatsVersion / bumpCustomDictVersion stop the IME writing old data back.
    - Coil disk cache cleared through Coil — Emptying it behind the loader's back leaves its index pointing at gone files.
    - emptyOut keeps the directory — Anything holding the directory open keeps a valid handle.
  - Progressive scan and snapshot cache `uncommon` — Categories stream in as measured; the last complete report is held 30 s per process.
    - Re-sort only when a scan finishes — Rows do not leapfrog under a finger already reaching for one.
    - Invalidated on any deletion — Going back never shows the size of something just deleted.
  - Free-up-cache button `uncommon` — Appears above 512 KB of clearable cache and states how much it frees.
  - Ring and per-group bars `uncommon` — Three-arc ring (app/user data/cache) inside a hairline device-fullness ring.
    - Charts hidden from screen readers — One summary sentence on the ring; the rows restate every number.
  - Cross-links to real management screens `uncommon` — manageRoute sends a category to the screen that owns it (languages, plugins, AI history).
- **Typing statistics** `uncommon` — Aggregate-only counters with charts; on by default, deletable.
  - What is counted `uncommon` — Characters, words, backspaces and burst-measured active time, per local calendar day.
    - Aggregates only, by design — No text, no per-app split, no timestamp finer than the day bucket.
    - Burst-gated active time — Gaps over 5 s are pauses and add no active time, so averages are not diluted.
    - Keystroke-stream word boundary detection — Works for composing and direct-commit scripts without a hook in the commit path.
    - Suggestion picks and glides count as words — onWordsCommitted adds words but no characters or active time.
    - Voice, handwriting and panel inserts excluded — They are insertions, not typing, and would make speed figures meaningless.
    - Backspaces never decrement — The statistic is work done, not text surviving.
  - Statistics screen `uncommon` — 5 lifetime tiles, a day/week/month history and a 24-hour histogram.
    - 5 tiles — Characters, words, WPM, active time, backspaces.
    - 3 periods x 3 metrics — 14 days / 12 weeks / 12 months; words, characters, or a WPM line chart.
    - Busiest hour named in words — Lifetime hour histogram with the peak hour formatted in the device time format.
    - WPM suppressed below 30 s active — Under that the figure is noise and a placeholder is shown.
    - Reader-only screen — The settings screen never calls save, so it cannot race the keyboard into losing counts.
  - Retention and deletion `uncommon` — 370 day buckets kept, pruned relative to the newest recorded day; lifetime totals survive pruning.
    - Delete with confirmation, then version bump — statsVersion tells the running IME to re-read instead of writing old numbers back.
    - Stored in stats/, not learning/ — "Delete learned words" must not take the statistics with it.
    - Direct boot means memory-only — A null storage file: counters run but nothing is written.
  - Levels `uncommon` — XP from the lifetime counts; each level costs 500 XP more than the last; ten names from Beginner to Legend (#390).
    - XP rule — 1 per word, 1 more per predicted, completed or glided word, 100 per achievement step.
    - Computed, never stored — TypingProgress derives it on open, so a delete resets it and a backup restores it.
  - Achievements `uncommon` — Six SwiftKey-style tiered counters with a progress ring each (#390).
    - The six — Words typed, keystrokes saved, words predicted, words completed, glided words, glide distance (metres, last step 42,195).
    - Pick classification — Nothing typed is a prediction, longer than typed is a completion; a pick over a glide or the caret word is a word only.
    - Keystrokes saved — A pick saves its letters plus the auto space, less what was typed and the chip tap; a glide saves all letters but one.
    - Glide distance in physical millimetres — Stroke length over xdpi/ydpi, so a bigger screen does not count faster.
  - Tap heatmap `RARE` — Per layout, key downs counted per quarter-key cell and drawn over that layout's letter keys (#390).
    - Rows down, not key widths — Portrait and landscape taps share cells.
    - Letters layer only — Symbols, secondary layouts and open panels are left out; space and backspace count.
    - Eight boards kept — The least tapped makes room; chips pick among the four most tapped.
    - Most tapped letters in words — The screen-reader version of the hidden map.
  - Statistics tool `uncommon` — ToolbarTool.STATISTICS opens the screen from the keyboard; not direct-boot safe (#390).
  - Typing-test achievements `RARE` — 4 badges stored as one comma-list preference; unlocks only accumulate.
    - The four — 100 WPM, a flawless run of 30+ chars, a pangram quote, 50 completed tests.
    - Unknown ids dropped on decode — Encoding is order-stable against the ALL list.
- **Network activity log** `RARE` — Settings › Privacy › Network activity: every request the keyboard's own code makes, on the device only.
  - Every network path recorded `RARE` — ToolHttp, the download managers, OkHttp (backup sinks, media loader), FTP and KDE Connect sockets all go through NetLog.
    - Build-time guard — NetworkCallSitesTest fails when a file opens a connection, client or socket without the log.
    - Honest about the gaps — ML Kit, Play services fonts, Play Store libraries and the system speech recognizer are named as outside it.
  - Address without what was typed `RARE` — Host plus a route the call site names; no query strings, headers, bodies or error messages.
    - Placeholders for secrets in paths — KLIPY's key and Signal's pack id show as {key} and {pack}; dictionary and Wikipedia routes stop before the word.
    - Real byte counts — Counted off the streams, not Content-Length.
  - Burst merging `RARE` — Identical requests within 60 s become one row with a count, summed bytes and a mean duration.
  - Totals kept apart from rows `uncommon` — 2,000 rows or 30 days; per-day totals by feature, server and hour survive the row cap.
    - Direct boot — Rows held in memory until the first unlock, then written.
  - Screen `RARE` — Live "contacting…" line, Today / 7 days / 30 days card with a stacked, scrubbable chart in each tool's own colour, By feature and Servers contacted cards, filtered timeline, per-request sheet.
    - Server badges — New (after the log is 7 days old), Your server (self-hosted and backup addresses), Local network (decided from the name, never resolved).
    - Request sheet — Why it happened, result in words, data each way, time taken, what that feature sends, links to its settings and Data saver.
    - Incognito marked, not paused — Rows made while incognito are badged and filterable.
    - CSV export, clear with undo — Also listed on the Storage screen.
  - Keyboard activity dot `RARE` — Off by default; a dot on the toolbar in the requesting tool's colour, hold to read the server.
- **Permissions & disclosures** `uncommon` — Prominent-disclosure layer plus an in-app permission inventory screen.
  - Prominent disclosure before every prompt `uncommon` — 7 disclosure definitions covering 6 runtime permissions; refusable without granting.
    - Three sanctioned request paths only — IME trampoline activity, settings-side composable helper, special-access helper; no bare launch().
    - Contacts gets two texts — Separate wording for name suggestions and for email suggestions.
    - Photos disclosure admits the wide grant — Android has no screenshots-only permission, so the copy says the whole library opens.
    - Scrollable dialog body — A clipped disclosure is not a disclosure.
  - Blocked-permission detection `RARE` — Tracks first ask in device-protected prefs to tell "never asked" from "permanently denied".
    - Button becomes Open settings — Avoids a button that fires a prompt Android will never draw.
    - Errs toward Settings — A re-grantable permission may route to Settings rather than risk a silent no-op.
  - Permissions inventory screen `RARE` — Privacy → Permissions: runtime, special-access and install-time rows with live state.
    - 5–6 runtime rows — Mic, camera, contacts, calendar, photos, plus storage only on API ≤ 28.
    - 3 special accesses — Notification listener, usage access, accessibility service, each with live grant state.
    - 3 install-time rows — Internet, network state, vibrate — listed for completeness, no action.
    - Grant-ahead-of-feature — The one place a permission can be granted before the feature that wants it.
    - State re-read on foreground return — Both directions of a change happen on system screens the row links to.
  - No analytics or telemetry SDK `RARE` — No Firebase/Crashlytics/Sentry/Mixpanel dependency anywhere in the build files.
    - No update check either — Updates come from wherever the app was installed.
- **Diagnostics & crash log** `uncommon` — Always-on in-memory ring plus an on-disk crash record, shareable from About.
  - 500-entry in-memory ring `uncommon` — Shared by the IME and settings when co-resident; always on, no switch to forget.
    - Nothing typed is ever logged — Call sites pass what happened, never what the user wrote.
  - Crash record in device-protected storage `RARE` — Last 10 crashes, so a crash on the lock screen is still recorded.
    - Record carries the last 40 ring entries — The ring dies with the process, so the run-up is inlined.
    - Default handler chained — Android's handler is what actually ends the process; skipping it leaves a dead app on screen.
    - Crash screen in its own process — Diagnostic builds only; the crashing process is about to be killed.
  - Diagnostics export `uncommon` — Build, flavour, channel, device, crashes and session log as one shareable text blob.
    - Own logcat included — Reading the app's own entries needs no permission since Android 4.1.
    - Clearable from Storage — The "Logs" category clears crash records through DebugLog rather than deleting files.

**Conditions and gating**

| Feature | Needs |
|---|---|
| Google Drive backup destination | gms source set only (Play services); F-Droid/nogms builds get a no-op authorizer and the destination is unreachable |
| Google Drive backup destination | needs the user to grant the drive.appdata scope through Google's consent screen; there is deliberately no in-app revoke |
| Dropbox and OneDrive destinations | need a build-time OAuth client id compiled in (local.properties/env); absent id means the destination does not exist. Also need a browser sign-in and network |
| Servers screen and server overrides | F-Droid builds only (wmkb.enableFdroid); other builds show a note on the screen and always call each service's default |
| SAF folder destination | needs a persisted tree-URI grant taken via OpenDocumentTree; a lost grant reports PERMISSION_LOST and stops backups |
| WebDAV / S3 / FTP destinations | need network plus user-supplied server credentials (WebDAV and S3 refuse plain http; FTP allows plain with a stated warning) |
| Automatic backup job | requires the device to be charging, and skips entirely until the user has unlocked once since boot |
| Android system backup | needs the opt-in switch plus a device capable of encrypting the backup under the user's screen lock (disableIfNoEncryptionCapabilities) |
| Backup exclusion of Whisper / on-device AI models | full flavour only — those directories exist only where the models can be downloaded |
| Exact storage totals | API 26+ StorageStatsManager; below that the screen falls back to its own walk and labels the figure an estimate |
| Clipboard screenshot capture (storage category, backup content) | needs the photos grant (READ_MEDIA_IMAGES / READ_EXTERNAL_STORAGE) |
| OTP notification chip (disabled during direct boot) | needs the notification-listener grant, which is a system settings screen rather than a prompt |
| "Show source app" on clipboard entries | needs usage access, a system settings screen |
| Keyboard gesture pass-through under TalkBack | needs the accessibility service enabled from system settings |
| Diagnostics crash screen | diagnostic builds only (BuildConfig.ENABLE_CRASH_SCREEN); otherwise the record is written and Android's handler runs |

## Accessibility, form factors, platform integration

- **Screen reader support** `RARE` — Four TalkBack modes plus the app's own pass-through accessibility service.
  - Four screen-reader modes `RARE` — Off / Labels / Explore / Gestures; default is Labels, so keys speak from first launch.
    - Labels: spoken names with direct typing kept — Aimed at switch access and low-vision users who still touch-type.
    - 32 punctuation and symbol keys get spoken names — TalkBack otherwise reads '.' or '@' as silence, making a symbol layer unusable by ear.
    - 6 named send-keys spoken — Tab, Escape and the four arrows, whose labels are bare glyphs.
    - Enter key named for the field's own action — 8 variants: search, send, go, next, previous, done, the app's custom label, default.
    - Shift, caps lock and Ctrl/Alt/Meta announce their live state — Separate strings for armed vs locked modifiers.
    - Explore: semantics-driven keys with a typed activation action — Custom onClick labelled 'Type <key>'; the pointer detector is switched off entirely.
    - Gestures: keyboard keeps its own touch handling under a screen reader — Announces on press, commits on release.
  - Touch-exploration pass-through service `RARE` — Own AccessibilityService whose only job is setTouchExplorationPassthroughRegion + setGestureDetectionPassthroughRegion (API 30+) for the key grid.
    - Zero event types, cannot retrieve window content — accessibilityEventTypes omitted, canRetrieveWindowContent=false, isAccessibilityTool=true.
    - Carve-out covers the key grid only — Suggestion strip, toolbar and panels stay explorable; region republished on every layout.
    - Touch-exploration flag added at runtime only while another service explores by touch — Enabling it alone can never switch explore-by-touch on.
    - Region retracted on dispose, unbind and panel open — A stale rectangle would bypass touch exploration with no keyboard under it.
    - Silently degrades to Explore when the service is not granted — Keys that neither announce nor honour explore-by-touch would be worse than either mode.
    - Runs in the IME's process, rectangle passed in-memory — No IPC; a shared StateFlow object.
  - Live touch-exploration detection `uncommon` — TouchExplorationStateChangeListener at the compose root, so toggling TalkBack mid-task swaps key handling.
  - Prominent disclosure before the accessibility grant `RARE` — Dialog naming what the service reads (nothing) before opening system Accessibility settings.
- **Vision accommodations** `uncommon` — Vision group on the Accessibility screen: 7 controls.
  - Colour-vision correction `RARE` — 5 choices: off, deutan, protan, tritan, greyscale.
    - Daltonization, not simulation — sRGB→LMS, collapse the missing cone, back to RGB, redistribute the error into green/blue.
    - Greyscale uses perceptual luminance — Equal-luminance hues collapse, exposing contrast failures in a theme.
    - Applied after the theme resolves — Identical for built-in, custom and dynamic-colour themes; alpha untouched.
  - High contrast keys `uncommon` — Flat black or white board with a separate key/modifier tone, labels forced to maximum contrast.
    - Strips everything that fights legibility — Board and key gradients, background images, animated backgrounds, key textures, decals, key effects, per-key overrides.
    - Recolours the whole surface, not just labels — Suggestions, toolbar icons, popups, chips and dividers all re-derive against the flat board.
    - Blocks photo-background rotation — The rotation pool declines while high contrast is on.
  - Key outlines `uncommon` — 1.5dp border at 0.45 alpha (0.9 with high contrast) on keys and on toolbar tool circles.
    - Skipped where the theme already draws its own border — Keys and tool circles are judged separately.
  - Bold key labels — FontWeight.Bold instead of Medium; also settable per theme.
  - Readable-font one-tap toggle `RARE` — Switches the keyboard face to Atkinson Hyperlegible (Braille Institute) via the downloadable-fonts path.
    - Chosen over OpenDyslexic because it is on Google Fonts — Rides the existing font provider with no bundled asset.
  - Key label text scale — 70%–150%, default 100%; independent of the key-preview popup's own scale.
  - Keyboard font row — Opens the full font browser from inside the accessibility screen.
- **Reduce motion** `uncommon` — One switch read by the keyboard and the settings app.
  - Carried on the resolved theme object `uncommon` — Every drawing composable reaches it through LocalKbTheme, including carets four panels deep.
  - What it removes `uncommon` — Toolbar slide/scale, strip reveals, panel pager scroll, settings shared-element and nav transitions, onboarding animations, anniversary confetti, voice mic pulse rings, chip appear animations.
    - Caret blink is held solid, not snapped — The loop is skipped rather than the spec zeroed, so the caret stays drawn.
  - Deliberately keeps meaning-carrying feedback `uncommon` — Key preview bubble, pressed-key colour and the glide trail stay.
  - Power saving can force it on `uncommon` — underPowerSaving() ORs its 'drop animations' switch into the same flag.
- **Screen transitions** `RARE` — Settings-app switch for slower phones: off drops the row-to-heading flights and the SharedTransitionLayout behind them.
  - Removes the lookahead pass, not just the motion — The layout lays the whole settings tree out twice on every pass whether anything flies or not.
  - Screens survive the flip — A flip recreates the activity, the rotation path, so back stack, scroll and fields come back (moving composed nodes out of a lookahead scope crashes Compose); the plain nav slide stays.
  - Two panes only mute the flights — The layout stays, so a fold or rotation never rebuilds the screens.
- **Touch and motor accommodations** `RARE` — Touch group on the Accessibility screen.
  - Ignore repeated presses (tremor filter) `RARE` — 0–500 ms, default off; drops a second contact on the same key inside the window.
    - Scoped per key — Alternating keys are never filtered — only a bouncing repeat of one key.
    - Dropped contacts are silent — Press haptic, press sound and the release sound are all gated on the same window.
  - Long-press delay — 150–800 ms, default 300 ms, for the alternate-character popup.
  - Cross-links to key size and haptics — Rows that jump to the layout and key-press screens rather than duplicating the sliders.
- **Power saving mode** `RARE` — A settings view applied on the way out of the repository; never persisted, so nothing is lost when it lifts.
  - Four triggers `uncommon` — Off, system battery saver (default), low battery, either.
    - Battery threshold 5–50%, default 20%
    - Ignored while charging (default on) — The manual switch is unaffected.
    - Manual switch persists like incognito — Survives the keyboard being torn down between fields.
  - 12 independent 'what to drop' switches `RARE` — Haptics, key sound, animations, glide trail, key popup, gesture typing, emoji prediction, smart chips, background network, screenshot watching, on-device models, typing stats.
    - On-device models fall back rather than break — Whisper dictation goes to the system recognizer; the handwriting swipe reverts to typing words.
    - Glide trail dropped by zeroing opacity — The gesture keeps decoding while the per-frame overlay stops.
    - Background network means unrequested fetches only — Link previews, QR link previews, dictionary look-up-on-selection; hand-opened tools still work.
  - Coarse power-state watching `uncommon` — Subscribes to battery low/okay, charger in/out and the system saver toggle; the exact level is read from the sticky broadcast on demand.
    - Never registers for ACTION_BATTERY_CHANGED — A null receiver returns the last sticky intent instead.
    - Battery-full counts as charging
  - Toolbar tool and a settings screen `uncommon` — Also bound to hardware-shortcut letter B.
- **Data saver** `RARE` — The same settings-view trick as power saving, keyed to what the connection costs instead of the battery.
  - Five triggers `uncommon` — Off, metered (default), roaming only, Android's own Data Saver, any of these; plus a manual switch that holds on any connection.
  - Three answers per feature `RARE` — Allow, ask each time, turn off. "Ask" shows the panel a notice with a "Use mobile data" action that grants that one feature for the session.
    - Background rows get two of the three — Link previews, word look-ups, photo backgrounds, weather chip, exchange rates (allowed by default) and add-on refresh happen with no panel open, so there is nobody to ask.
    - On-demand rows default to asking — GIF/sticker search, web and image search, animated emoji, downloads, cloud AI. Local sticker packs and on-device AI are never held.
    - Grants are session state — Dropped whenever the network changes; the settings app asks separately from the keyboard.
  - Default-network callback rather than polling `uncommon` — Metered, temporarily-not-metered and roaming come off NetworkCapabilities; Android's Data Saver has no capability bit, so it arrives as ACTION_RESTRICT_BACKGROUND_CHANGED and is re-read when the keyboard opens.
  - Absorbed two older switches — "Ask before downloading on mobile data" (Languages) and "Only download over Wi-Fi" (AI models) migrate into the Downloads row on first read; their DataStore keys are still read once for the migration.
- **Notifications** `uncommon` — Four kinds, four switches, and nothing else: the app posts no tips, suggestions or advertising.
  - Downloads report themselves `uncommon` — Dictionaries, emoji names, voice and AI models, CJK packs and the emoji font each get a progress row, a "ready to use" line, and the failure sentence the settings row would have shown.
    - Progress notifications expire by themselves — The app does no background work, so a download whose process is killed takes its notification with it rather than freezing at 43%.
  - Update notifications `uncommon` — Downloading, ready to install, and "Updated to 0.5.8" after the fact, the last of which fires on every channel through MY_PACKAGE_REPLACED.
    - No Install button in the shade `RARE` — Installing restarts the process the keyboard runs in, so the shade tap opens the app where the warning is; only Cancel is safe to press from a notification.
  - Automatic backup failures `RARE` — The one failure with nowhere else to appear: the job runs with no screen, and a revoked folder grant otherwise stops every backup silently.
  - Keyboard controls in the shade `RARE` — Hacker's Keyboard's answer to a pinned keyboard that has gone down over a window with no text field: Show, Unpin and Switch keyboard, off by default.
  - Quick Settings tile `RARE` — "Keep keyboard on screen", the same setting as the pin tool, needing no permission at all.
  - Asked for at the first useful moment `uncommon` — The permission request comes with the first download or the first shade control, never on launch, and never twice.
- **Form factors: tablets and foldables** `RARE` — Two independent screen questions — device form (size) and screen variant (posture).
  - DeviceForm buckets `uncommon` — PHONE / SMALL_TABLET / LARGE_TABLET at AOSP's 600dp and 768dp smallest-width thresholds.
    - Read from smallestScreenWidthDp — A phone in landscape is still a phone; a tablet is a tablet either way up.
    - Multi-window correctly drops to PHONE — The platform reports the app's own window.
    - Re-evaluated on every configuration change — Fold, unfold or a move to another display; the layout cache is keyed on the form.
  - Tablet key-grid expansion `RARE` — A render-time transform over the compiled grid rather than hand-authored tablet layouts; most shipped layouts get it, and the ones that decline are pinned by TabletExpansionCorpusTest.
    - One column of keys added each side — The centring spacers become Tab, backslash, caps lock and Enter.
    - Backspace moves to the number row, mirrored Shift takes its place — Only when that row is actually drawn, so backspace can never go missing.
    - Backtick prepended to the digit row — Idempotent — a layout that already has one gets no second.
    - Large tablet adds arrows, a second ?123 and moves the period up — A small tablet is still thumb-typed, so its period stays on the bottom row.
    - Dedicated emoji key minted beside ?123 — The comma-as-emoji and globe-as-emoji workarounds switch off on that grid.
    - Row count never changes — The IME window height is computed from layer row counts.
    - 14 shipped layouts decline, pinned by a corpus test — Kana flick pads, braille, morse, four Chinese pads, IPA, syllabics, music, N'Ko, Syriac.
    - Per-layout author override — LayoutSpec.tabletExpand, true by default, exposed in the layout editor.
    - Grid width pinned across layers — Symbols and Fn draw on the letters layer's pitch so ?123 does not resize every key.
  - Tablet defaults, applied only while untouched `RARE` — Gated on the DataStore key's absence, not its value, so a tablet user can still turn the number row off.
    - Key height 44dp (large) / 46dp (small) vs a phone's 48dp
    - Number row height 38dp / 40dp vs 42dp, and the row on by default
    - 7 pinned tools on a large tablet, 5 on a small one, vs the shipped 3
    - Runs first in the overlay chain — Before mode, theme overrides, screen variant and the direct-boot restriction.
  - Per-screen-shape sizing (ScreenVariant) `RARE` — Portrait is the base; landscape, portrait-unfolded and landscape-unfolded are optional override sets.
    - 7 overridable values per shape — Key height, number-row height, bottom padding, width percent, font scale, alignment, keyboard scale.
    - Whole-keyboard scale multiplier — Exists only on the three override shapes; folds into the resolved heights so no render code learns about it.
    - 'Unfolded' is a 600dp smallest-width check, not a hinge sensor — Deliberately separate constant from DeviceForm's own 600dp line.
    - Unset values fall back to portrait — A user who only cares about landscape height sets one number.
  - Other reach adaptations `uncommon` — One-handed, split and floating keyboards; all direct-boot safe and bindable as toolbar tools.
    - One-handed keeps a separate profile per orientation — Portrait 78% width, landscape 55%, each with its own height scale and docked side.
    - Split keyboard with a 5–40% gap, default 12%
    - Floating keyboard: draggable, resizable, 320dp default, fullscreen extract mode disabled
    - Keep the keyboard on screen: pinned over fieldless windows until hidden by hand (issue #58); direct-boot safe, bindable as a toolbar tool
  - Toolbar-only view with a physical keyboard `RARE` — Optional: drop the key grid and keep the tool strip; the IME forces the input view shown so the platform cannot hide it.
    - Presence read from Configuration.keyboard + hardKeyboardHidden
    - Also force-shown when a hardware shortcut opens a tool — Restored as soon as the tool closes.
  - Edge-to-edge window handling `uncommon` — Bottom padding defaults to 32dp on API 35+ where IME windows draw behind the gesture bar, 8dp below.
- **Hardware keyboard hint badges and dispatch** `RARE` — One plan built from the visible state, read by both the renderer and the dispatcher, so a badge can never disagree with what the key does.
  - Leader key arms an on-screen picker `RARE` — Default is a double-tapped Ctrl; Alt and Shift also offered, or capture an arbitrary chord.
    - Fires on the second tap's release — So the following letter arrives bare instead of looking like a Ctrl chord.
    - Any key in between resets the chain — Ctrl-tap, Ctrl+C, Ctrl-tap never arms; an auto-repeating held modifier is not a tap.
    - Picker timeout 1–30 s, default 8 s
  - Badges drawn under the button they operate `RARE` — Toolbar digits 1–0 counting from the toolbox launcher, tool letters, Shift+key on toolbox tiles, symbol and emoji row cells, suggestion slots.
    - 25 default tool letters, T and ? reserved — Each tool's own initial where it was free.
    - Second tier of 36 Shift+keys — 26 letters in keyboard order for the symbol row, 10 digits for the emoji row; the toolbox drains both.
    - An open toolbox claims the whole Shift tier — The rows drop their badges rather than being renumbered under the user.
    - Modifier spelled as words by default — Ctrl+ / Shift+ / Alt+; the Mac keycap glyphs are opt-in.
    - Suggestion badges count display slots, not engine ranks — With the best suggestion centred, badge 1 still commits the leftmost word.
  - Keycap-character decoding for the picker letter `RARE` — getUnicodeChar with no meta state, so Shift and AltGr cannot change which tool a letter opens; falls back to the QWERTY position for Cyrillic- or Greek-only keymaps.
    - ? and / normalise to the same key — Asking for help must not depend on Shift.
  - Cheat sheet `RARE` — Full legend on ?, covering the tools no on-screen badge can reach.
  - Chord validation `RARE` — Warns on 11 chords the focused app is entitled to, on a bare (modifier-less) leader, on letters bound to disabled tools and on duplicates.
  - macOS shortcut mode `RARE` — Off by default; 14 actions routed from Cmd/Option chords into the IME's existing editing operations.
    - Ctrl is a disqualifier, not an alias — Apps keep Ctrl+C; unclaimed Cmd chords fall straight through.
    - Shift with a move makes it a selection
  - Suggestion hotkeys `RARE` — Three modes: off, Alt+1–9 (default), or the leader then a digit.
  - Ctrl+digit toolbar chord `uncommon` — On by default and switchable off, since browsers use it for tabs.
- **Direct boot** `RARE` — The IME is directBootAware, so it is the keyboard that types the first PIN after a reboot.
  - Device-protected mirror of the settings `RARE` — Republished on every change while unlocked; read synchronously for the locked keyboard's first frame.
    - Credentials dropped on the way in — API keys and tokens are stripped; learned words, clipboard, snippets and emoji history are never mirrored at all.
    - Locked edits go to the mirror and are transient — The first write after unlock overwrites them, so in-keyboard toggles still respond on a lock screen.
    - Stored as one typed-JSON blob — SharedPreferences would lose the DataStore key types.
  - A restricted settings view for the locked session `RARE` — Applied on the way out of the repository, so the renderer, engine and tool handlers all agree without knowing direct boot exists.
    - 39 of 64 tools survive — Everything backed by filesDir, a locked provider, a credential or an activity is filtered out of the toolbar, toolbox and enabled set.
    - Fonts, emoji font and sound packs fall back to system
    - Custom theme background image paths stripped, recursing into variants — The photographer credit goes with the photo.
    - Contacts, contact e-mails, app-name suggestions and system-dictionary writing off
    - Clipboard history, recent-clip chip and screenshot watching off
    - OTP notification chips off — The lock screen is already redacting that content.
    - Whisper falls back to the system recognizer; handwriting swipe reverts to typing words
  - Live unlock recovery `RARE` — ACTION_USER_UNLOCKED flips the repository back to the real store and re-establishes everything in place.
    - Duplicate filtering deliberately sits inside each branch — So the switch always delivers a first value and the keyboard cannot stay in its reduced shape.
    - OS subtypes re-registered after unlock — Writes made before the first unlock are volatile.
  - Keyguard treated separately from direct boot `uncommon` — deviceLocked is the lock screen being up, where storage works; it drives an optional hide-the-toolbar setting and withholds clipboard entries.
- **Launcher and deep-link integration** `uncommon` — Custom wmkeyboard:// scheme, no domain to verify and no assetlinks.json.
  - 4 static launcher shortcuts `uncommon` — Tools, Languages, AI chat, Themes — published at install time with no ShortcutManager code.
    - Order is reversed on purpose — Launchers draw bottom-up, so the most-wanted screen is last in the XML.
    - Explicit intents, so no browsable filter is needed — Nothing off-device can send one.
  - wmkeyboard://settings/<route> `uncommon` — 7-route allowlist parsed back to a NavHost destination; unknown routes navigate nowhere.
    - Both the authority and opaque URI forms accepted
    - A test reads the NavHost and fails if a shortcut names a screen that does not exist
    - One keyboard mode's row, by the mode's id — settings/mode_edit/mode_browser?setting=modes_symbol_sets_title (#323); the editor's rows are indexed on `modes` for search and carry `screenPattern` mode_edit/{modeId} for links, and the docs dump lists them once per built-in mode
  - Addon store deep links `RARE` — 3 targets: wmkeyboard://addons, ://repo?url=, ://addon?repo=&id= — browsable, so a README or a message can open one.
    - A link never installs anything and never adds a repository — It only navigates; the resulting screen shows the address and author and the user taps Install.
  - OAuth redirect activity `uncommon` — wmkeyboard://oauth catches the Dropbox and OneDrive sign-in codes; PKCE verifier never leaves the device.
  - File associations for the app's own export formats `RARE` — 10 compound extensions matched by pathPattern (never by MIME type, which would claim every .json), landing in a one-shot import activity rather than the settings app.
    - Extra .* variants per dot — pathPattern has no backtracking, so 'my.theme.wmtheme.json' needs its own alternative.
- **Play Store and GMS-free builds** `uncommon` — Store channel and Play services are separate build flags, each selecting a source directory.
  - Play In-App Updates `RARE` — Flexible and immediate flows behind a policy object turning Play's priority and staleness numbers into one decision.
    - Priority ≥4 or 90 days behind takes the blocking flow
    - Priority ≥2 or 7 days behind earns a Play dialog, otherwise a quiet card
    - 'Not now' snoozes one version code for 7 days — Keyed by version so it expires by itself at the next release.
    - install() is never called on the app's own initiative — Finishing an update restarts the process the keyboard lives in.
    - Auto-prompt is a user setting, stored outside KeyboardSettings — Not a keyboard setting, so it stays out of exports and backups.
  - Non-Play builds compile no Play Core code `uncommon` — src/noplay supplies a no-op updater sitting on Unsupported forever, so every update surface draws nothing.
  - Play services probe with narrow package visibility `RARE` — Two <queries> entries — the GMS package and the fonts provider authority — and no broad package-query permission.
    - Document scanner tool hidden without Play services — It is a Play services activity; OCR and QR stay, their models are in the APK.
    - Google Fonts lists hidden without the font provider — Every entry would silently resolve to the system face.
    - microG answers both probes the same way, by design — The feature is offered and its own failure path takes over per module.
    - Probed answers cached for the process, primed in both onCreate paths — Defaults to 'available' before priming so a tool never disappears on a device that supports it.
  - Drive backup destination behind a gms/nogms source seam `uncommon` — Only the OAuth token provider is gated; the Drive REST calls are ordinary HTTP and compile everywhere.
  - full / lite build flavours `uncommon` — lite drops ~100 MB of ML Kit and native Harper: handwriting, OCR, QR scan, doc scan, grammar, local LLM and Whisper.
- **Notification listener and special access** `RARE` — One prominent-disclosure layer for the three grants Android hands out on a system Settings screen rather than a permission dialog.
  - One notification-listener component worn by two features `RARE` — Media control needs only the grant; the OTP chip reads notification text, gated per notification.
    - Renaming the class would silently revoke existing users' grant — Android grants notification access per component.
    - Notification text is not read at all while the code chip is off — The gate sits in onNotificationPosted, before the monitor.
    - Keeps a live instance so a used code's notification can be cancelled
  - 4 disclosure kinds `RARE` — Notifications (media), notification codes, usage access, accessibility service — each with its own copy naming what it reads.
    - Wording states the narrow truth without contradicting the system's alarming warning
    - Per-listener deep link on API 30+, with a fallback to the list page — Some OEMs ship neither.
  - Invisible trampoline activity for the IME `RARE` — An input method cannot host a dialog outside its own window, so the disclosure runs in a translucent activity that then opens Settings.
    - Every IME-launched activity carries taskAffinity="" — Otherwise NEW_TASK fronts the settings task and strands the user out of their text field.
- **OS input-method integration** `uncommon` — How the keyboard presents itself to the platform's own switcher.
  - Runtime subtypes, no static ones `RARE` — One subtype per enabled layout, registered only while the 'list languages in the Android switcher' setting is on.
    - A static bootstrap subtype was removed on purpose — With the setting off the picker labelled the keyboard 'English' instead of by name.
    - setExplicitlyEnabledInputMethodSubtypes on API 34+ — Registering is not enabling; below 34 the languages must be ticked by hand in the system enabler, which settings links to.
    - In-app language switch mirrored back to the OS switcher on API 28+
    - Diffed against a signature so nothing is rewritten per settings emission
  - Switch-to-next-input-method supported — Declared in method.xml; the settings app can also open the system IME picker.

**Conditions and gating**

| Feature | Needs |
|---|---|
| Readable font (Atkinson Hyperlegible) and every google:<Name> keyboard font | needs the Play services downloadable-fonts provider plus a network fetch; the option is hidden on devices without it |
| TalkBack Gestures mode (keyboard gestures under a screen reader) | needs the WM Keyboard pass-through accessibility service enabled in system Settings; falls back to Explore without it |
| Media control tool and OTP notification chips | needs the notification-listener grant (Settings > Notification access); Play Console declaration still outstanding per project notes |
| Clipboard 'show source app' | needs the usage-access grant |
| Play In-App Updates (card, About rows, flexible/immediate flows) | play-channel builds only (wmkb.enablePlayStore); also requires the install to have come from Play and a network call |
| Document scanner tool | full flavour only (ML Kit) and hidden entirely on devices without Google Play services |
| Handwriting, OCR, QR scan, grammar check, offline Whisper dictation, local LLM | full flavour only (ML Kit / LiteRT / Harper native) — power saving's 'drop on-device models' and the direct-boot restriction both fall back to system alternatives |
| Offline Whisper dictation, the sticker editor's own background remover, handwriting recognition | on Play, each runtime is an on-demand split fetched on first use (:feature:litert for the LiteRT interpreter the first two share, :feature:handwriting for ML Kit's ink recogniser); the language-to-model mapping for handwriting is compiled in (InkModelTags) so the tool knows what it is offering before the split arrives; sideload builds compile the same bridges into :core:voice, :core:content and :core:intelligence |
| Google Drive backup destination | GMS-enabled builds only (wmkb.enableGms); reports unavailable in F-Droid builds |
| Servers screen (Advanced) and per-tool server fields | F-Droid builds only (wmkb.enableFdroid) |
| Launcher shortcuts | API 25+; ignored on the minSdk 24 floor |
| Touch-exploration pass-through region | API 30+ (setTouchExplorationPassthroughRegion); the mode is inert below that |
| Explicitly enabled OS subtypes for the system language switcher | API 34+; on 24–33 the user must tick languages in the system subtype enabler |
| Addon deep links and the addon store | network; a link only ever navigates, installs are explicit taps |

## Extensibility: addons, plugins, imports, formats

- **Add-on repositories** `RARE` — User-added HTTPS repos serving 12 add-on types from a wmkeyboard-repo.json index; 30 repos max, 2 shipped pre-added
  - Repository manifest format `RARE` — wmkeyboard-repo.json: repo metadata + addons[] entries
    - 12 installable add-on types — theme, layout, dictionary, emoji_keywords, snippets, stickers, icon_pack, font, emoji_font, sound, sound_pack, plugin
    - Index only, no packaging step — Payloads are the app's own export files; installing = hand the file to the existing importer
    - Forward-compatible decode — Unknown type coerces to Unknown and disables one row; unknown JSON keys ignored; whole repo never fails
    - Per-entry metadata — version, author, tags, previews[], sizeBytes, minAppVersion, langId/langIds, license/licenseText/licenseFile, requires[]
    - Soft dependencies — requires[] names sibling entries (a theme's font and sound); skipping them still installs a working add-on
    - 1 MB manifest cap — Sanity bound on the fetch, enforced during download
  - URL resolution and trust boundary `RARE` — Pasted string -> manifest URL, HTTPS only
    - GitHub shorthand — github.com/USER/REPO -> raw.githubusercontent.com/USER/REPO/HEAD/wmkeyboard-repo.json; /tree/ or /blob/ pins a branch
    - Plain http rejected, not upgraded — Whole scheme compared so "http" can't slip past a "https" prefix test; opaque schemes (javascript:, content:) rejected
    - Relative assets can't escape the repo — resolveAsset() requires same host, path under the manifest directory; //-relative and /-relative refused
    - Bare host or user/repo assumed HTTPS — Scheme-less input is prefixed rather than refused
  - Install pipeline `RARE` — Download -> verify -> hand to importer -> record what it created
    - Resumable transfer — HTTP Range into a .part file; a 200 instead of 206 discards the partial and restarts
    - Per-type size caps — layout/snippets 4 MB, theme/sound_pack 16 MB, emoji_keywords/icon_pack 8 MB, dictionary/font 32 MB, stickers 64 MB, plugin 1 MB
    - SHA-256 verification — Optional per entry, verified when declared; mandatory for plugins — a plugin with no checksum is refused
    - minAppVersion floor — Older builds show the add-on but report APP_TOO_OLD instead of installing
    - Free-space guard — Requires payload size + 32 MB headroom before starting
    - One install at a time — StateFlow of per-addon status survives rotation and navigating away mid-download
    - Dependency batch install — requires[] entries install first under the same lock; a failed dependency doesn't abort the main install
    - Update = re-install — Old copy removed only after the new payload verifies, so a failed update leaves the working version
    - Lenient semver compare — 1.2, v1.2.3, 2026.07 all compare; missing components read as 0; prereleases sort before releases
  - Install and apply are separate `RARE` — Browsing a repo is never destructive
    - Post-install "use it?" prompt — Asked for 7 types with a single obvious slot: theme, icon pack, emoji font, sound, sound pack, layout, plugin
    - Prompt outlives the screen — Held on the download manager, so whichever add-on screen is on top when the install lands asks
    - Updates re-select themselves — An update of the theme you were wearing reapplies under its new id instead of asking again
    - Plugins install disabled — A plugin from a repo lands switched off even though a hand-opened .wmplugin lands on
  - Uninstall and reconciliation
    - Per-type reversal — Recorded localRef is the theme id, layout id, pack id, font/sound id, dictionary path or snippet id list
    - Selection cleanup — Uninstall also clears the icon-pack/font/sound settings pointing at it and purges the SoundPool copy
    - Sweep on screen entry — AddonReconciler drops records whose local object was deleted from its own settings screen
    - Installs survive repo removal — Removing a repository only stops update checks
  - Catalogue browsing
    - Two-column grid with screenshots — previews[] images, aspect clamped 0.62–2.2 so a phone screenshot doesn't eat the screen
    - Search and type-filter chips — Search matches name, description, author and tags; chips only show types the repo actually has; both survive back-navigation
    - Pre-install content previews — 7 previewable types: snippet list, up to 10k dictionary words, 24 keyword rows, playable sound, every sound-pack variant, 24 stickers, plugin permissions
    - Preview downloads capped and cached — 12 MB ceiling under every install cap; re-opening the same preview doesn't refetch
    - Licence surfacing — SPDX id, inline text, or a licence file fetched on demand (256 KB cap)
    - "Get more" rows — 12 settings screens link into the catalogue pre-filtered to their own add-on type
    - Offline browsing — Last manifest cached verbatim per repo; a fetch failure keeps showing what it had
  - Deep links `RARE` — wmkeyboard:// scheme, three targets
    - Three routes — wmkeyboard://addons, //repo?url=<repo>, //addon?repo=<repo>&id=<addonId>
    - A link can only navigate — Never installs and never adds a repository; the add dialog is pre-filled and the user still confirms
    - URL revalidated — The carried repo URL goes through the same HTTPS-only resolver before any route is produced
  - Seeded repositories
    - Two shipped defaults — The sample add-on repository and the monkeytype sound-pack repository
    - Removal sticks — A per-URL marker file records what has been offered, so a removed default never comes back
    - New defaults reach old installs — Appending to the seed list offers it once on existing devices too
- **Lua plugins** `RARE` — .wmplugin tool panels running in a locked-down luaj sandbox; 50 installs max, subsystem off until enabled
  - .wmplugin package `RARE` — ZIP with plugin.json + a Lua source file
    - Source only — Precompiled Lua rejected at import by its 0x1B signature, and no undumper is installed anywhere
    - Zip-bomb caps — 16 entries, 1 MB archive, 256 KB script, 64 KB manifest; sizes counted from bytes actually read
    - Entry names never used as paths — manifest entry field is a map key; ../ in an entry name or the manifest has nowhere to go
    - Manifest-only read for disclosure — Showing what a plugin may do never touches the code that would do it
  - Manifest validation is total `RARE` — Any problem is a refusal with a reason; nothing about a plugin is repaired
    - Id must be a safe path segment — ^[a-z0-9][a-z0-9._-]{2,63}$, re-checked by the store because the id becomes a directory
    - Display strings sanitised — Control, format (bidi overrides), surrogate and private-use code points stripped; name capped at 40 chars
    - API level gate — apiVersion above the host's (currently 1) is refused rather than run
    - Unknown permission = refused install — Forward-compat guard: an old build declines rather than running with a capability it can't describe
  - Permission model `RARE` — Exactly one permission exists: storage
    - No API for typed text — No wm.text, no keystroke feed — a plugin only ever sees the contents of its own visible input box
    - No clipboard API — Not behind a prompt, not behind a grant — the function does not exist
    - No network API — Deliberate: a plugin that could read text and open a socket is keyboard malware, and consent doesn't change that
    - Storage isn't prompted at use — Disclosed before install; with no egress anywhere it is app-local scratch space
  - Host API surface `RARE` — wm.log, wm.json, wm.ui.set_input, wm.storage — the whole of it, pinned by a test
    - wm.json — decode/encode with 24-level depth cap and 256 KB text cap; whole numbers round-trip as integers
    - wm.storage quotas — 128 keys, 64-char keys, 8 KB per value, 64 KB per plugin; enforced before every write
    - wm.ui.set_input — Writes into one of the plugin's own text boxes, 8 KB cap; applied after the handler returns
    - Revocation — Once a session is abandoned every wm.* call throws instead of doing anything
  - Sandbox `RARE` — 5 stdlib modules in, 6 kept out, each for a stated reason
    - Installed — BaseLib, Bit32Lib, TableLib, StringLib, JseMathLib and the LuaC compiler
    - PackageLib omitted — require resolves through Class.forName — the single most important omission; a decoy package table absorbs the libs' own writes
    - CoroutineLib omitted — luaj coroutines are real non-daemon threads that leak past the keyboard if they never yield
    - io/os/luajava omitted — os replaced with time/clock/date only, over a small fixed strftime subset
    - Every string-to-code route nulled — load, loadstring, loadfile, dofile, require, package, io, luajava, coroutine, debug
    - Frozen string metatable — LuaString.s_metatable is a process-global static; replaced with a sealed table hidden behind __metatable so one plugin can't rewrite ('x'):rep for every other
    - Amplifier guards — string.rep capped at 256 KB, pattern subject/pattern bounded (256 KB / 256 B), table.concat at 1 MB
    - No stdout, no resource finder — STDOUT/STDERR sink to nowhere, STDIN null, finder returns null; collectgarbage is a stub
  - Runaway containment
    - Per-instruction budget — Load 30M instructions/3 s, event 20M/2 s, render 4M/0.5 s; clock read every 1024 instructions via a bitmask
    - Abort can't be caught — PluginAbort extends Error, so luaj's pcall/xpcall and the interpreter loop pass it straight through
    - Hook is unreachable from Lua — Lives on DebugLib, which is loaded then removed from globals; no debug.sethook to unset
    - Watchdog abandons stuck threads — Covers time spent inside luaj's Java pattern matcher where the hook never fires: session revoked, executor shut down, priority dropped
    - Two strikes — A plugin abandoned twice is disabled until the user turns it back on; re-enabling forgives the strikes
    - Host-call time isn't charged — enterHostCall/exitHostCall push the deadline out so a slow disk write can't kill a well-behaved script
  - Plugin UI vocabulary `RARE` — 11 widget kinds, drawn by the keyboard in its own theme
    - Widgets — tabs, column, row, label, output, button, toggle, input, spacer, divider, progress
    - Insert button is the only text route — An output widget gets the host's own Insert/Copy buttons; no API types for the user
    - Inputs are host-owned — No Compose TextField in the IME — a tap re-routes keystrokes into the panel's buffer and the script is told the new contents as an event
    - 4 event kinds — Click, ToggleChanged, InputChanged, TabSelected — all user-initiated
    - UI is repaired, not refused — 256 nodes, depth 12 (also breaks cycles), 2 KB per string, 64 KB per tree, 8 tabs; drops are reported as captions
    - Pure-Lua prelude — ui.* helpers just build plain tables, so the widget format is data an author could write by hand
  - Install and lifecycle
    - Master switch, off by default — Gates installing as well as running; kept out of KeyboardSettings so it never rides the keyboard's hot path
    - On-disk layout — filesDir/plugins/<id>/ holds plugin.json, main.lua, storage.json and log.txt; delete removes all four
    - Updates keep user data — storage.json survives an upgrade; enabled state and abandon strikes reset
    - Ring-buffer log — print() and script errors, 200 lines x 512 chars, flushed at session end and shown in settings
    - Index reconcile — Records whose script file vanished are dropped on load
    - Capability disclosure screen — Settings lists what plugins cannot do (typing, text field, clipboard, internet) beside what they can
- **Native file formats** `RARE` — 10 file-associated extensions plus 4 import-only/internal ones; every one is plain JSON or a ZIP
  - Theme .wmtheme.json `uncommon` — Bare ThemeSpec object, ARGB colours as 0xAARRGGBB longs
    - No format tag — Every field defaults, so any JSON decodes; the extension is the only evidence a file was meant to be a theme, checked last
    - Self-contained images — Local paths stripped, bytes embedded base64 — two dedicated background fields plus a generic assets map (keyTexture, popupTexture, decal:<id>, effectImage:<n>)
    - Fonts and sounds by id only — Never embedded, so they stay reusable as their own add-ons; a missing one falls back to the global choice
    - Import can't point outside app storage — withExtractedImages writes the bytes out and rewrites the path, which also drops any absolute path the file arrived with
    - Photo credit travels with its image — Attribution dropped if the image it belongs to didn't resolve
  - Layout .wmlayout.json `uncommon` — Envelope {format, version, appVersion, layout}
    - Tag is the one strict check — Chosen over a bare object precisely because a bare theme-style object would "import" a shopping list
    - Repair-and-report — A hand-edited grid with a typo is fixed and every change listed under "Changed on the way in"
  - Snippets .wmsnippets.json `uncommon`
    - Ids never trusted — Fresh ids assigned on import, so importing twice gives two independent sets
    - Pattern triggers travel — trigger, triggerPattern + triggerWords, and confirm are written only when set; an uncompilable pattern is dropped and its snippet kept
    - 500-snippet cap — Past it the rest is dropped with a note
  - Sticker pack .wmstickers `uncommon` — ZIP: pack.json + stickers/; 500 entries / 64 MB, 50 packs installed
    - Entry names never used as paths — Every image is written under a freshly minted sticker id
    - Source photos stay behind — The archive carries the finished sticker only, not the original it was cut from
  - WhatsApp pack .wastickers `RARE` — Foreign format, read only: flat ZIP with title.txt / author.txt beside the pictures; recognised by those two names since it has no manifest; same 500-entry / 64 MB guards and staging as .wmstickers
  - Icon pack .wmicons `RARE` — ZIP: pack.json + icons/<slotId>.svg; 400 entries / 8 MB, 20 packs installed
    - 97 replaceable icon slots — 64 tool icons (derived from the toolbar enum), 14 key icons, 6 toolbar-chrome, 13 emoji-tab
    - Slot ids are the file names — manifest slots[] is advisory; the importer keeps every entry whose name matches a known slot and drops the rest
    - Own SVG reader — path, g transform nesting, rect/circle/ellipse/line/polyline/polygon, presentation attrs, inline style, #rgb/#rrggbb/#rrggbbaa/rgb()/none/currentColor
    - XXE hardened — Any DOCTYPE anywhere rejects the file outright — Android's SAX throws on Apache's disallow-doctype-decl, so it's done by inspection
    - Monochrome detection — An icon declaring no colours tracks the keyboard theme and the per-tool accent; a coloured one is drawn as authored
    - Parser caps — 256 KB source, 400 paths, 64 KB path data, depth 32, viewport clamp against width="1e999"
  - Sound pack .wmsoundpack `RARE` — ZIP: pack.json + sounds/; 16 MB, 64 samples, 32 variants per list, 20 packs installed
    - 5 key roles — default, space, enter, delete, modifier — each may carry its own samples and gain, falling back per field
    - Key-down and key-up sets — Separate press/release lists so holding a key really holds the sound open; empty release means silence, not a fallback
    - Variant randomisation — Many recordings of one keyboard, one picked per press
    - Gain is a cut — Clamped to 0..1 because SoundPool can't amplify; a pack asking for 2.0 gets 1.0
    - Broken entries dropped, not fatal — A press entry naming a missing file is dropped; a pack with nothing left is refused
    - Paths rewritten on install — Manifest paths resolve to bytes, then to generated s000.snd names; shared samples stored once
    - Header sniff — ID3/MPEG sync/OggS/RIFF-WAVE accepted; anything else isn't stored
  - Single key sound — .mp3 published; .ogg and .wav also accepted on import. 4 MB, 30 sounds
    - Magic-byte validation — Catches the obvious mistake — an HTML error page, a zip, a video — rather than decoding
  - Fonts .ttf / .otf `uncommon` — 32 MB, 50 fonts installed
    - Two-stage validation — sfnt magic (0x00010000, OTTO, true, ttcf) then an actual Typeface.createFromFile
    - Emoji fonts are a separate add-on type — Chosen in Emoji settings rather than the key-label pickers; colour COLR/CBDT builds draw in colour
    - Language claims — langIds on the repo entry stop a Latin-only face being offered for Bengali
  - Word lists .txt (optionally .gz) `uncommon` — Import-only; 32 MB per file, additive per language
    - Permissive parse — word<space>frequency, frequency optional and defaulting to 1; # comments; junk lines skipped so wild lists import as-is
    - Stacks on the bundled lists — Several lists per language, layered over the built-in English and Bengali dictionaries
    - Import from a URL — http/https only, size-capped download, name taken from the last path segment
    - Empty imports self-delete — A file that parses to zero words is removed and reported, so picking a PDF fails visibly
    - Legacy folder migration — Old ENGLISH/BANGLA/FRENCH/GERMAN/SPANISH folders renamed to language ids once, merging rather than clobbering
  - Emoji keyword packs .tsv (optionally .gz) `RARE` — Import-only; 8 MB, one folder per language
    - Row shape — emoji TAB keywords,comma,separated TAB optional display name
    - "# " comments, bare # does not — Because #⃣ is an emoji and starts a real data row
    - JSON sniff — A file starting with [ is read as the data repo's JSON dictionary instead, so a raw .json URL imports unconverted
    - Keywords stack, names don't — Search finds an emoji under every installed language; the long-press name is resolved per typed language
  - Config backup .wmconfig.json / .wmconfig.enc `uncommon` — 11 opt-in sections, each embedded as the JSON its own store already writes
    - Sections — settings, themes, dictionary, clipboard, snippets, stickers, icons, wordlists, emoji, addons, statistics
    - Add-on repo list is backed up — The bookmark list, which a restore would otherwise silently lose
    - Encrypted variant — Separate .wmconfig.enc extension and octet-stream MIME, since a provider handed a .enc name with a JSON type appends .json
    - Secrets excluded by default — API keys and tokens only travel when "Include API keys" is on
    - Legacy .wmsettings.json — Read on import, never written; rollback-safe restore re-reads what it wrote
  - Internal binary formats — No file association and no export path
    - .wmdict — WMDC-magic packed-trie dictionary (codec version 3), memory-mapped for zero-parse loads
    - .wmng — Memory-mapped corpus n-gram pack (version 1)
- **Importing from other keyboards** `RARE` — FlorisBoard and HeliBoard layouts and themes, Gboard and Rboard themes, written from the published formats — no upstream code (MIT app vs Apache-2.0 / GPL-3.0 sources)
  - Foreign layouts `RARE` — Two formats, one parser: FlorisBoard/HeliBoard KeyData JSON and HeliBoard's plain-text layout
    - Format sniff skips comments — First non-blank, non-// character decides JSON vs text, so a commented JSON grid isn't read one key per line
    - Lenient JSON — Comments and trailing commas allowed (HeliBoard's own reader allows both); rows accepted bare or under arrangement/rows/keys/layout
    - Key-code table — Floris constants plus HeliBoard's -10000 range: modifiers, layer keys, editing, cursor moves and Ctrl shortcuts as raw key events
    - Unmappable keys dropped and named — Codes for things this keyboard reaches another way (settings, clipboard, voice, smartbar toggles) are removed and the dialog lists them, rather than becoming dead keys
    - Approximations counted — delete-word becomes plain delete; the second symbols page folds onto the symbols key; the dialog says how many
    - Space/enter promoted to actions — Code points 32/10/13 become real keys, or auto-space, double-space full stop and the field's enter action would all be lost
    - Language must be chosen — Neither format records one; the app guesses from the script on the keys and seeds a picker — a blank id would silently become English
    - Width renormalisation — Foreign fractional widths (0.1 = a normal key) scaled onto this app's grid weights; HeliBoard's -1 "fill the row" resolved first
    - Nukta normalisation — NFC leaves Bengali/Devanagari/Gurmukhi/Oriya composition exclusions decomposed; those are recomposed or keys shape and backspace wrongly while looking right
    - Letters layer only — Symbols, numbers and the bottom row come from this app's own grids, added by the repair pass
    - Size cap — Foreign files are read capped, unlike the native import, because they were picked by extension
  - FlorisBoard .flex themes `RARE` — ZIP of extension.json + snygg stylesheets, converted to ThemeSpec
    - Honest conversion count — The dialog reports mapped rules out of rules read, e.g. "34 of the 52 style rules"
    - What maps — Board, key, pressed key, modifier and enter keys, borders, popups, glide trail, candidate text/chip, accent
    - Per-key overrides — snygg key[code=…] selectors become per-key colour overrides instead of collapsing onto one modifier colour
    - 8 named losses — snygg v1, elevation, per-corner radius, per-element spacing, font, dynamic colour, unknown element, low-contrast fallback
    - Unreadable text is dropped — A scraped foreground below the contrast floor is replaced with a derived colour and reported
    - Fields left null, never guessed — A derived default beats a colour scraped from a selector that meant a different surface
    - FlorisBoard 0.4 refused outright — snygg v1 is a different dialect; half a theme is worse than a clear no
    - Day+night becomes one theme family — Two stylesheets in one extension are grouped as variants of a single entry named after the extension
    - Saved, not activated — A converted theme goes into the gallery to be looked at first; licence and maintainers from the manifest are shown
    - Zip caps — 256 entries / 16 MB, 256 KB manifest, 4 MB per image; entry names only ever map keys
  - .flex file association `RARE` — The app claims FlorisBoard's extension so a file already on the phone opens; with both installed Android asks which
  - Gboard theme ZIPs and Rboard packs `RARE` — metadata.json + Gboard's CSS dialect (@def variables, RRGGBBAA colours) converted to ThemeSpec; a pack (ZIP of theme ZIPs + previews) lists its themes, pick one or Add all
    - Key borders become two looks — Gboard's BORDER flavour sheet is a second look of one theme family, the theme's preferred one first; a no-op flavour collapses to one look
    - Fallback base sheet — Gboard's standard variables (color_state_key, color_label, color_header…) restated as lowest-priority rules, so variable-only themes convert
    - What maps — Board (key area over base area), photo + landscape photo, keys, pressed, function, enter (incl. the borderless round badge), space as a per-key style, outlines, corner size/pill/no face, lift, text, hint, strip, popups, glide trail, accent, light/dark
    - 8 named losses — compiled .binarypb sheets, key icon pictures, per-key padding, fonts, shadow colour, per-corner radius, pictures on other parts, low-contrast fallback; the rest is the "N of M style rules" count, computed from what the mapper read
    - Tolerant reader — Stray semicolons, 9-digit hex typos, unclosed comments, forward-referenced variables, junk after metadata.json; zip-slip names dropped, 48 MB / 4 MB per image / 128 themes caps
    - Compiled themes refused by name — A theme that is .binarypb through and through (Gboard's stock ones) says so instead of failing as junk
    - Opens from a file manager — Recognised inside any ZIP by a root metadata.json or pack.meta; a pack opened that way imports every theme
  - Rboard collection browser `RARE` — Themes › Gboard › Browse Rboard lists the packs in GboardThemes/PackRepoBeta's list.json; nothing fetched until that screen opens; left out of the Play build (ENABLE_PLAY_STORE: route not registered, the Gboard button opens the file picker)
    - SHA-256 checked — Each pack is verified against the list's hash before it is read, then cached; the list is capped at 2 MB, a pack at 32 MB
    - Data saver and network log — Asks once before the first request under Ask each time; every request is logged as "Rboard themes"
    - Clear error state — A list that is not the expected shape shows an error and Retry, never a half list
- **Opening files from outside the app** `uncommon` — 10 recognised extensions routed to a dedicated one-dialog activity
  - File associations
    - Name matching, not MIME — Every format is JSON or ZIP, so a MIME filter would claim every .json and archive on the device
    - Compound extensions — .wmtheme.json rather than .wmtheme, so plain .json stays unclaimed
    - Four patterns per extension — Android pathPattern can't backtrack, so my.theme.wmtheme.json needs its own variant; content:// only, via host="*"
  - Content-based identification — The extension gets the file in; reading it decides what to do
    - ZIP branch — Scans up to 400 entries for pack.json / plugin.json / extension.json / Gboard's metadata.json / Rboard's pack.meta, capped at 64 KB, then matches the format tag
    - Stickers vs icons vs plugins — Sticker and icon packs share pack.json and can only be told apart by the tag inside
    - Text branch order — Config backup, legacy settings, layout, snippets — first matching format tag wins; theme by file name last, and nothing untagged may be added after it
    - Encrypted header detected first — Before the text read, so a large .wmconfig.enc isn't decoded as UTF-8
    - A renamed file is judged by content — A layout renamed .wmtheme.json is refused rather than imported as an empty theme
  - Import dialog behaviour
    - Read, then ask, then write — One confirm dialog listing what the file holds; nothing is written until accepted
    - Repairs listed — "Changed on the way in" bullets for layouts, snippets, sticker and icon packs
    - Plugin disclosure — Name, version, author, description and permission list shown before install; blocked with an explanation when plugins are off
    - Passphrase prompt — Encrypted backups ask in a password field so this keyboard doesn't learn the passphrase
    - Never opens settings — Separate ImportFileActivity, excluded from recents
  - Export — System Save-As picker for themes, layouts, snippet packs, sticker packs, icon packs and config backups
    - Plain MIME types — application/json or application/zip, since a vendor MIME would stop file managers and chat apps offering the file
    - Suggested names — Derived from the object's own name, punctuation-stripped; backups get a timestamp
    - Exports are repo payloads — The same file an export button writes is what an add-on repository serves — no packaging step to publish

**Conditions and gating**

| Feature | Needs |
|---|---|
| Add-on repository browsing, install, update and preview | needs network (HTTPS only; plain http is refused, not upgraded) |
| Add-on store and installed-add-on list | unavailable during direct boot — filesDir/addons is credential-encrypted, so the store is empty and addRepo refuses before first unlock |
| Lua plugins (install and run) | needs the plugin subsystem master switch turned on by the user; off by default, and it gates installing as well as running |
| Lua plugins | unavailable during direct boot; scripts and their storage live in credential-encrypted storage |
| Word list and emoji keyword pack import from a URL | needs network; http/https only |
| Installing a plugin from a repository | requires a sha256 in the manifest — the install is refused without one (opening a .wmplugin file directly skips that check) |
| Plugin runtime (luaj) | no flavour gate — core:plugins has no src/full or src/lite sources and luaj-jse ships in both full and lite builds |
| Font import validation | the second validation stage calls android.graphics.Typeface, so it only runs on device (injected as a lambda for JVM tests) |

## Modes, rows, field adaptation, runtime

- **Keyboard modes (per-app / per-field profiles)** `RARE` — 6 seeded modes; a named override bundle applied while active, resolved on every field focus
  - What a mode can override `RARE` — Null fields inherit the global setting
    - Emoji row presentation — Inherit / Off / Button / Always-on row
    - Symbol row on/off and which symbol sets it offers — First set in the list becomes the active one
    - Keyboard theme — Hard override: beats the hand-picked theme and disables auto light/dark for the mode's lifetime
    - Pinned toolbar tools, replace or append — Append keeps the user's own pins first and drops duplicates
    - Toolbox ordering — Partial list floats named tools to the front; unnamed tools keep their global rank
    - A tool a mode pins is force-enabled — Added to enabledTools so pinning can never silently do nothing
    - Typing switches — Autocorrect, automatic capitals, suggestions and automatic spaces, each Inherit / On / Off
    - Automatic spaces is one switch over three settings — The space after punctuation, after a strip suggestion and before and after a glided word (the leading one is `autoSpaceBeforeGlide`, an applied-view flag with no key or row, #184); off means every space in the field is one the user typed
  - The six seeded modes `RARE` — Stored copies on first run; user can edit or delete any of them
    - Passwords — Emoji off, symbol row off, toolbar replaced with password generator + clipboard + settings
    - Email — Symbol row on with Email and Punctuation sets; bound to email fields only
    - Browser — Symbol row on with the Web set; bound to URL fields only, no app list
    - Chat — Emoji row always on; emoji/GIF/sticker/voice appended; 15 messaging apps plus text fields
    - Writing — Toolbar replaced with AI/text-edit/voice/clipboard/emoji; 14 note and mail apps, bodies only
    - Coding — Coding + Math symbol sets; Termux, Acode, RK Editor, Spck
  - Automatic activation bindings `RARE` — 7 ModeField kinds: PASSWORD, EMAIL, URL, NUMBER, PHONE, TEXT, NOTIFICATION_REPLY
    - Apps AND field kinds when both are set — Chat bound to WhatsApp plus TEXT fires on the composer, not the contact search
    - TEXT deliberately excludes password boxes — A masked field reports TEXT at the OS level; filtered out so chat modes can't take a login form
    - NOTIFICATION_REPLY ignores the app binding — Inline reply is hosted by com.android.systemui, never the app being replied to
    - Field-kind match beats an app-only match — A password box inside a code editor still resolves to Passwords, not Coding
    - Neither set = manual only — Listed as "Manual only (Modes tool)" in the settings subtitle
  - Manual override from the Modes tool `RARE` — On-keyboard panel listing Automatic plus one row per mode
    - A manual pick lasts until the focused app's package changes — Never persisted; lives only in the running service
  - Mode editor
    - 36-icon catalog stored by id — Ids survive the catalog being reshuffled; unknown ids fall back to a generic icon
    - Reorderable chip lists for pinned tools, toolbox order and symbol sets
    - Edits save immediately; a new mode is not written until its first edit
    - Only the six built-ins have a Reset
  - Drags edit the active mode `RARE` — On by default; on-keyboard tool drags write into the mode that owns the order
    - Only when the mode prescribes toolbarTools or toolboxOrder — ownsToolOrder gate; otherwise a drag goes to the global order
    - One-off toast naming the mode the drag was saved to
  - Seed versioning for upgrades — CurrentModeSeedVersion = 3
    - New default modes appended on upgrade — Chat and Writing added in seed v2
    - App and field top-ups skip anything already bound — A package already routed by any stored mode is never re-added
    - A mode the user deleted stays deleted
    - Legacy app lists dropped when they exactly match the old shipped list — Browser and Email became field-bound only
- **Rows above the key grid** `RARE` — 7 stackable rows (BarRow: TOPBAR, EMOJI, SYMBOL, FANCY, TOOLS, DICTIONARY, MACROS) in a user-chosen order
  - Row order `RARE` — Default emoji, toolbar, symbol row; reordered with up/down arrows
    - A hidden row keeps its slot empty rather than collapsing the stack
    - Stored order sanitized on read — Duplicates dropped, missing rows appended, unknown enum names ignored
    - One row is state-driven, not setting-driven — MACROS (selection macros) draws only while text is selected and takes no height otherwise; it still holds its slot in the order, and a stored order that predates it gets it just above the suggestion strip
    - Global only — a keyboard mode cannot reorder the stack
    - Migrated from the old emoji-row-above-toolbar boolean
  - Symbol row `RARE` — One-tap characters and snippets above the keys, off by default
    - A page of its own (#136) — route `rows/symbol`: the Rows & bars row is a switch and a door (ToggleNavRow), the page repeats the switch and holds height, lines, scrolling and the symbol sets
    - 5 built-in sets, all enabled by default — Email (11 entries), Web (15), Coding (32), Math (22), Punctuation (20)
    - Left-edge picker chip, shown only when more than one set is enabled
    - Entries can be whole snippets, not just characters — @gmail.com, https://, ->, => and a literal tab
    - Invisible characters get a display label — Tab shows ⇥, space ␣, NBSP/ZWSP/ZWJ named
    - Editing a built-in stores an override under the same id — Modes referencing that id keep working; deleting the override restores the shipped set
    - Custom sets creatable from scratch; at least one set must stay enabled
    - Row picks persist unless a mode prescribes its own sets — With a mode's list in force the pick is session-only and clears on field switch
    - Hardware-hotkey badges render on the row's chips
    - Hold an entry with no popup for a menu (#323) — Remove it (a built-in set gets an override, so Reset undoes it; the last entry stays), Hide the row in <mode> (while a mode turns the row on or names its own sets; sets that mode's Symbol row to Off), Delete the set (own sets only, asks first), Symbol row settings (the mode's editor when the mode is why the row shows, else rows/symbol)
  - Emoji row — Three presentations: Off, Button (a toolbar toggle swaps the strip), Always-on row
    - Folds away automatically while the emoji panel is open
  - Fancy Text style strip — Rides with its layout rather than with barOrder, drawn closest to the keys
    - Deliberately not a BarRow — the enum is serialized and older builds must decode it
  - Automatic row suppression
    - Full-bleed panels swallow every row and take their height
    - Symbol row yields to the special-characters panel; emoji row yields to the emoji panel
    - Lock-screen privacy drops the whole top strip while the keyguard is up
    - Emoji search and clipboard search hide the toolbar to buy result rows
- **Number row** — Dedicated digit row above the letters, on by default
  - Independent height `uncommon` — 32–100 dp slider, separate from the letter key height; 42 dp default
    - Per-screen-variant overrides — Own value for landscape / unfolded / tablet
    - Tablet defaults 40 dp (small) / 38 dp (large) until the user touches it
  - Per-layer digit-row content `RARE` — The row keeps one slot on every layer so switching layers never moves it
    - Letters and symbols-1 show digits borrowed from the symbol layer, keeping fraction and superscript long-presses
    - Symbols-2 swaps in an arrow/comparison fill row — ← → ↑ ↓ ± ∞ ≈ ≠ with their own long-press alternates
    - Symbols-1 body loses its own duplicate digit row — Replaced by the =\<>[]{}|~ fill row, only when that row really is digits
    - Numeric keypads get operators instead of a second set of digits — Phone field: + * # , ; ( ) - / . ; other keypads: + - * / = ( ) % : .
  - Symbols on shift `RARE` — Holding shift on letters turns the digits into =\<>[]{}|~; off by default
  - Number row in symbols `uncommon` — On by default; off drops the digit row from the ?123 layer and shrinks the board there
  - Layout-authored number row `RARE` — A layout file can supply its own numberRow, per layer
    - Authored rows resolved for LETTERS, SYMBOLS, SYMBOLS_SHIFTED and FN independently
  - Tablet digit row carries backspace `RARE` — The body row gave it up for the mirrored shift, so both answers come from one condition
    - Never over a numeric field, where the 4-column pad is kept intact
  - Digit long-presses stripped when the row is on — Top-row letters go straight to their accents instead of duplicating the digits
  - Number-row typo correction `RARE` — A lone digit inside a word joins the composing word and may swap to the letter below it
    - Only same-length single-digit swaps; two or more digits are left alone
  - Native numeral systems on the row and keypads `RARE` — 6 systems: Auto, Latin, Arabic-Indic, Persian, Bengali, Devanagari — chosen per language
    - Layout data always stores ASCII; glyphs applied at draw and commit time
    - Commit scope: text fields only (default), everywhere, or display only — Text-only keeps ASCII in numeric/phone/date/time fields so they stay machine-parseable
- **Symbol layers and layer cycling** — 4 cycled layers: letters, symbols, symbols-2, Fn
  - Two-stop cycle
    - ?123 opens symbols; the key relabels to =\< at 1.5x width and opens symbols-2
    - Symbols-2's corner reads ?123 again and bounces back — there is no page 3
    - ABC jumps to letters from anywhere, including out of a locked Fn layer
  - Hold ?123 for the numpad panel `uncommon` — On by default; long-press opens the keypad tool from any field
  - Go back to the letters after punctuation `uncommon` — Off by default; character list defaults to !?.,;: and is user-editable
    - Only single-character keys count, so a .com key never triggers it
    - Digits deliberately absent from the default list
  - Fixed row span so cycling never resizes the board — Height is the tallest of letters/symbols/symbols-2/Fn; shorter pages pad at the top
  - A layer with no way back gets an ABC key appended `RARE` — Repair pass, applied to any cycled layer of a custom or imported layout
  - Leaving letters drops in-progress handwriting ink
- **Input-field adaptation** — 8 FieldKind values read from EditorInfo on every field focus; no setting to turn off
  - Field-kind detection — TEXT, EMAIL, URI, NUMBER, PHONE, DATE, TIME, DATETIME
    - Both web and plain email variations map to EMAIL
    - DATETIME class split three ways by variation
  - Five dedicated numeric keypads `RARE` — 4-column phone-pad order (1-2-3 on top), delete and enter anchoring the right column
    - Number pad: - with + % * / on hold, space, . with : on hold, comma; backspace moved to the low-right slot
    - Phone pad: dial pad with pause (,) and wait (;) on long press, + on the zero key
    - Date pad: / with : on hold, -, ., , — covers 20/07/2026, 2026-07-20, 20.7.26
    - Time pad: colon-led with . on hold, space for AM/PM suffixes
    - Date-and-time pad: / with . on hold, :, -, space
    - Shared across every shipped layout; a custom layout can override any of the five
    - Key-preview bubble suppressed on keypads by default — Echoing a PIN digit large enough to read is a shoulder-surfing risk
  - Email and URL bottom-row key swaps — Letters layer only, so a Dvorak layout's real . and , keys elsewhere stay untouched
    - Email: comma becomes @, period long-press gains .com .net .org .edu .co
    - URL: comma stays (address bar is a search box too), / ? # & = on its hold; period long-press gains .com .org .net www. https:// /
    - Field adaptation outranks the comma-as-emoji preference
  - secureField as a separate flag from FieldKind `uncommon` — A masked box reports TEXT; a PIN box is NUMBER and secure at once
    - Covers text, visible-password, web-password and numeric-PIN variations
    - Password variations force the strip off unconditionally — the one case the override can't beat
    - Clipboard history stops recording while a secure field has focus
    - Voice typing refuses to start, with a toast on the toolbar and an inline notice in the panel
  - Suggestion-strip suppression, gated separately from typing intelligence `uncommon` — NO_SUGGESTIONS flag plus email/URI/filter/password variations
    - "Suggestions in every field" override, on by default — Ignores the app's plea for a silent strip; never overrides passwords or non-text classes
    - Hiding the strip never disables autocorrect, glide, phonetic composing or learning
  - Typing-intelligence gate `uncommon` — Full engine only on plain, non-secure TEXT — email and URL fields are excluded too
    - Phonetic (Avro) composing is the one thing that keeps running everywhere
  - Enter key follows the field — 8 EnterAction values: default, search, send, go, next, previous, done, custom
    - IME_FLAG_NO_ENTER_ACTION wins outright, so multi-line fields always get a newline
    - A non-null actionLabel draws the app's own wording and fires its actionId
    - Shift+Enter newline escape hatch, off by default — Only a user-armed one-shot shift counts; caps lock and auto-capitalize are excluded
  - FORCE_ASCII switches to a Latin layout `RARE` — Prefers one the user has enabled over hard-coding English
    - Avro's roman keys still commit Bengali, so a Latin layout is the only safe answer
  - hintLocales honoured advisorily `RARE` — Only when the user already has that language enabled; never overrides field-kind detection
  - Auto-incognito from the field `uncommon` — IME_FLAG_NO_PERSONALIZED_LEARNING, plus the pre-Oreo privateImeOptions string
    - Session-scoped: follows the field, never the persisted incognito switch
  - Register from field and app `RARE` — Messaging packages read CASUAL, mail clients and email fields FORMAL, everything else NEUTRAL
    - 18-package messaging allowlist and 10-package mail allowlist
  - Editor's advertised content MIME types read once on focus `uncommon` — Media panels say up front that a GIF has nowhere to land instead of dead-ending on send
  - Numeric pad suppressed while a keyboard-owned search box is typing `RARE` — Emoji, dictionary, clipboard, media, plugin and typing-test buffers get the letters back
  - Per-field state reset on focus — Panels close, symbol and fancy picks clear, layer returns to letters unless the field is merely restarting
- **Suggestion strip layout and lane arbitration** `uncommon` — One row shared by candidates, chips and the toolbar, with an explicit priority order
  - Lane priority, top to bottom `RARE` — Each lane either claims the whole row or shares it and falls through
    - Autofill (password-manager) chips claim the row and carry a dismiss cross
    - Armed dead-key accent hint
    - Live morse sequence readout with the letter it spells so far
    - OTP-from-notification chip — outranks everything below because it expires
    - Snippet offer chip (shares the row)
    - Smart calc/currency/unit chip claims the row; a tool-keyword chip takes only what it needs
    - Recently-copied paste chip, narrowed to 160dp when it has to share
    - Platform smart replies — whole row when nothing is typed, 180dp tail otherwise
    - Word candidates, conversion candidates, or inline emoji chips
    - Up to 4 emoji predictions after the words
    - Quick-punctuation chips on the tail behind a divider
  - Candidate presentation splits by composer — Latin gets 3 wide chips, a conversion IME gets a scrolling strip with an expand chevron
  - Primary candidate in the middle slot (Gboard style), on by default
  - Rewrite chip leads the row — Join or revision suggestion, visually apart from the three word slots
  - Quick punctuation row beside the candidates — Off by default; yields the tail to an emoji prediction when one is present
  - Strip / toolbar swap
    - Chevron toggles by hand; the override resets when candidates come and go
    - Suggestions-first keeps the empty strip as the resting surface
    - Toolbar only takes over after the strip has stayed empty for a debounce plus a fade
    - Cross-dissolve with the emoji icon sliding its position between the two surfaces
  - RTL layout flip for the strip only `uncommon` — Arabic, Hebrew, Persian, Urdu, Thaana put the best candidate on the right; the key grid stays LTR
  - Downward flick anywhere on the strip dismisses the keyboard — Opt-in; a tool's hold-then-drag reorder fires its long-press first and never collides
  - Reduce-motion honoured — Fades snap, but the hide still debounces so a typing-burst gap can't blink the strip
- **InputConnection handling** `RARE` — Composing-region and selection bookkeeping shared by every panel and tool
  - Panel inserts flush the composing word first `RARE` — A bare commitText would replace the active region and eat the word
    - Skipping the flush leaves a stale buffer the next setComposingText re-inserts elsewhere
  - Digits typed as real key events, not commits `RARE` — keyCode 229 commits are dropped by one-character-per-box verification forms
  - Per-digit OTP entry `RARE` — Codes typed one character at a time with a delay so each box hands focus to the next
    - Input connection re-read per character, because the focus moving is what replaces it
  - Expected-selection cache — Kept from initialSelStart/End and every onUpdateSelection, so the keyboard tells its own echoes apart
  - Composing region re-attached after an input-connection restart `RARE` — Only over text that reads back as the buffer's own output, else the buffer is dropped
    - Transliterating composers re-attach over the composed form, not the roman source
  - Silent region loss re-armed `RARE` — A TextWatcher restyling text drops the composing span without telling the IME; the region is re-set
    - Without it, the commit on space inserts the word instead of replacing it and it doubles
  - Caret-left-composing-region predicate — Only a caret strictly outside the reported range counts, so a commit echo isn't read as a jump
  - Mid-word caret tap drops the composition — Otherwise the next keystroke's setComposingText snaps the cursor back to the word's end
  - Context re-read on entry, not only on selection updates — A field returning with unchanged text and caret never fires onUpdateSelection
  - Composing resume gated on language and composer `RARE` — A word the caret lands on is re-armed only where the buffer is the field's text
    - Transliterating and conversion composers excluded — their buffer is input spelling, not output
    - Word-character test includes combining marks, so Bengali/Devanagari/Tamil/Thai/Arabic words qualify
  - Batch edits around multi-step rewrites — Translate, grammar, text-edit and select-all replacements wrap their operations
- **Easter eggs** `RARE` — 6 hidden surprises; none ever touches the text being typed, none phones home
  - Install-anniversary card and confetti `RARE` — Settings home grows a birthday card on the install date's month and day
    - Year-number marker in its own prefs file, so it re-arms every January by itself
    - Leap-day installs celebrate on the 28th in common years
    - Confetti and toast fire once per calendar year; reduce motion keeps the card, drops the motion
    - Install moment read from the package manager, so a reinstall restarts the count
  - Keycap catcher mini game `RARE` — Seven taps on the About version row, with a countdown toast from the fourth
    - Falling keycaps, a spacebar-shaped paddle on a horizontal drag, three misses ends the round
    - Fall speed rises with the score; high score kept in the eggs prefs file only
  - xkcd 936 caption in the password generator `RARE` — Roughly one generation in 500 adds a second caption under the entropy estimate
    - Quoted words are never part of the generated output; the generator is untouched
  - Rickroll detection in the QR scanner `RARE` — Matches the video id across watch?v=, youtu.be, /embed/, /shorts/, /live/ and 7 YouTube hosts
    - Scheme-optional, host case-insensitive, id exact, payloads over 500 characters skipped
    - Adds a line above the payload; the code still scans, copies and opens normally
  - Typing-test achievement badges `RARE` — 4 badges: 100 wpm club, flawless run, quick brown fox, 50 runs
    - Flawless requires at least 30 correct characters, so a short run can't luck into it
    - Pangram badge only from quote mode, checked a-z against the prompt
    - Unlocks only accumulate; stored as one comma-list preference
  - Morse SOS note on the suggestion strip `RARE` — Keying S, O, S as three consecutive letters; once per keyboard session, about 5 seconds
    - Drawn below the live sequence readout so it only shows in the pauses
- **First-run onboarding wizard** `uncommon` — 11 pages, gated per device, per persona and per run; every page writes straight to DataStore
  - Persona quiz `RARE` — 3 questions whose answers both trim the wizard and apply a batch of defaults
    - How many languages: one / two or more — One sets both spacebar swipes to cursor and the globe key to emoji; many sets both to language
    - How deep: keep it simple / a good middle / show me everything — Picks the starter tool set and unlocks the emoji, feedback, gestures, tools and tool-setup pages
    - Privacy: standard / extra strict — Strict turns off learn-from-typing, clipboard history and typing stats, and adds the incognito tool
    - Every option's subtitle states its consequences, so picking blind is impossible
    - A replay changes only the stored answers — it never silently rewrites settings
    - Answers recomputed as a whole, so the depth/privacy pair is order-independent
  - Starter tool sets `RARE` — 3 ordered sets: Minimal 8 tools, Recommended 21, Power 35, out of 64
    - Set order is load-bearing — the default toolbox ranking is built from it
    - Unsupported tools filtered out, then topped up with Wikipedia and Power saving — Covers the lite build and Play-less devices losing handwriting, OCR and doc scan
    - Finishing from any page lands the persona's set — Only when the enabled set is still the untouched everything-on default; unanswered gets the middle set
  - Page gating — OnboardingPage enum of 11; the unanswered short path is deliberate
    - Languages page appears for "two or more" or when a second language is already enabled
    - Emoji page only for "a good middle" and "show me everything"; its emoji-font half only when the phone's own font is missing catalog emoji, or on Samsung
    - Welcome page skipped on a replay where the keyboard is already enabled and selected
    - Tool-setup page only for Power and only if Calendar, Weather or Compass is on
    - A page vanishing under the user falls back to the nearest earlier surviving page
  - Discover feature tour `RARE` — 12 cards; capped at 5 for Minimal, 7 for Balanced, all for Power
    - Cards are toggles or explore-only pointers — Toggle cards flip the feature on the spot; explore cards say where it lives
    - Catalog skips table stakes on purpose — No glide, plain voice input or one-handed mode — a tour of those teaches nobody anything
    - Each card carries an animated staged scene of the feature working — Answer chip over keys, a code arriving, a clipboard stack, a snippet arrow
    - Strict privacy reorders the list — Quick toggles card pushed to the front, the network-adjacent AI card pushed last
    - OTP card asks for the notification grant with a disclosure as its switch goes on
    - Whisper card only in builds that ship it
  - Spacebar-gesture question — 5 combined choices, one badged as recommended from the language answer
    - Cursor-then-language, language-then-cursor, language only, cursor only, off
  - Per-tool first-run setup page
    - Calendar: Gregorian shown as always-on, two alternate calendars, weekend days
    - Weather: the same location search-or-coordinates editor as settings, plus Fahrenheit
    - Compass: Qibla direction, borrowing the weather location editor when weather is off
  - Try page — A real text field so the just-configured keyboard appears in its chosen theme
    - Hints point at what the wizard just enabled, not at things the keys already show
    - Nothing typed there is stored; focus requested only after the page finishes sliding in
    - Falls back to the enable-keyboard card if the IME still isn't set up
  - Wizard chrome
    - Tappable progress row that animates pages in as the persona answers unlock them
    - Per-page accent colour matching the settings route colours
    - Skip on every page but the last; a replay has no Skip
    - Miniature keyboard previews for the layout, digit-row and globe-key choices
    - Languages and haptic style seeded from the device on a fresh run only
- **Settings search** `RARE` — About 500 hand-written index entries plus one per supported toolbar tool
  - Index structure
    - Every entry carries title, subtitle, breadcrumb, route and the title's string resource
    - Breadcrumbs up to three levels deep, e.g. "Tools › Camera"
    - Tool rows derived from the enum, so a new tool is searchable the moment it has a title
    - Unsupported tools' rows filtered out because their screens are unreachable
    - Hidden keywords on destination screens only — "dark mode" for themes, "new phone" for backup
  - Ranking `RARE` — 8 scoring tiers from whole-field exact down to fuzzy, weighted per field
    - 3 entry weights: destination screen 200%, ordinary row 100%, mirror row 40% — Mirrors are the backup screen's per-feature toggles and the "All ... settings" shortcuts
    - Plural and -ies stemming, so "themes" finds Theme and "dictionaries" finds Dictionary
    - Punctuation-stripped compact match for queries of 3 or more characters
    - Ties break on title length, so the plainest matching row floats up
  - Vocabulary `RARE` — 58 synonym groups plus a stop-word list, read from resources so they follow the UI language
    - Bridges the screens' glossary to what people type — "vibration" finds haptics, "long press" finds press-and-hold, "enable" finds turn-on
    - Synonym hits keep only 45% of their score, so a literal title match always wins
    - Stop words dropped unless the whole query is stop words
  - Typo tolerance `RARE` — Damerau-Levenshtein, 1 edit from 5 letters, 2 from 8
    - Only short fields spell-correct — in a twenty-word subtitle something is always one edit away
    - Words under 5 letters are never corrected: mode/more, dark/mark
  - Partial-query fallback — When no row carries every word, the rows carrying the most answer — if that is over half the query
  - Result navigation `RARE` — Opens the owning screen, scrolls to the exact row and flashes it
    - Matched by string resource, not drawn words, so it survives translation
    - User-owned list entries matched by their own local handle (theme id, pack id, file path)
    - Only the topmost matching row claims the scroll
    - Separate return-anchor mechanism restores list position without flashing
  - Full-screen search field that grabs focus on open, with a per-route icon on each result
- **Storage screen** `RARE` — 28 named categories in 6 groups, sized from Android's own StorageStatsManager
  - Headline figures match the system's App info page — Three-arc ring split App / Data / Cache, with the device's free space underneath
    - Block-rounded sizes, so a thousand tiny files cost what they really occupy
    - Pre-API-26 devices fall back to a walked estimate and say so
    - Direct-boot (device-protected) storage counted as real storage
  - Six groups — The app itself, Downloads, Looks and add-ons, Your data, Caches, The rest
    - Group headers carry their own total, so "which is the big one" is answered before the row level
    - Empty rows hidden behind a Show all toggle
  - Per-category drill-down — Own route per category; lists each item with its size and a delete button
    - Word lists labelled by language name rather than directory id
    - Sticker packs list "Images you made stickers from" separately from the packs
    - Deletes go through the owning store, not raw file removal — Stores keep an in-memory manifest shared with the running keyboard
  - Four danger tiers govern the confirmation wording `RARE` — Cache (free), re-downloadable, personal/unrecoverable, and full settings reset
    - Settings reset confirms twice — the one action a user can neither undo nor see the shape of
  - Free up button clears every cache at once — Never touches anything the user made; hidden below 512 KB of reclaimable space
  - Two residual rows so nothing is invisible `RARE` — Other cache and Other data list whatever no named category claims
    - Split along the same line the system splits its own figures
    - Descends one level into files/ rather than reporting the whole tree as one row
    - Residual items are listed but not deletable
  - Staging and .part leftovers swept without touching tracked files
  - Manage routes link a category to the screen that owns it properly
- **Typing speed test tool** `RARE` — An in-keyboard typing test panel, keystrokes routed away from the field
  - Three modes — Time (15/30/60/120 s), Words (10/25/50/100), Quote
    - 200 most common English words, kept short so it measures typing not vocabulary
    - 14 public-domain or original quotes, nothing under copyright
    - Time runs generate a surplus prompt so nobody runs dry mid-test
  - Difficulty options
    - Punctuation adds sentence shape — capitals after a stop, commas, the odd quoted word
    - Numbers turns roughly one word in eight into a numeral
  - Live run view
    - Per-character verdicts: correct, wrong, extra, missing, pending — The live word's untyped tail stays pending rather than counting as a mistake
    - Caret parked mid-box so the line ahead stays readable; blink held solid under reduce motion
    - Headline counts seconds left on a timed run, words left on a counted one
    - Settings strip drops out once typing starts, handing its height to the prompt
  - Scoring `RARE` — Standard 5-characters-per-word; keystroke-level accuracy so corrected mistakes still cost
    - Net wpm from matched characters, raw wpm from everything typed
    - Consistency as coefficient of variation over the per-second samples
    - The space that closed a word counts as a keystroke only if the word was right
  - Results screen
    - WPM graph from once-a-second samples, with error markers on the seconds a mistake landed
    - Personal bests kept per configuration, not one all-time number
    - Trend bar from the last 24 runs
    - New-best accent, and a New accent on badges the run just unlocked
    - Insert result writes the score into the field the user came from
  - A run belongs to the field it started in — Moving to another field abandons it rather than resuming half-typed
  - Achievements list and Clear records on the tool's settings screen — Clear wipes badges along with bests and history

**Conditions and gating**

| Feature | Needs |
|---|---|
| Rickroll detection in the QR scanner | full flavour only (ML Kit barcode scanning); the matcher itself lives in :core:tools and compiles in both |
| Whisper card on the onboarding Discover page | full flavour only (BuildConfig.ENABLE_WHISPER) |
| OTP discover card and the OTP chip on the suggestion strip | needs the notification-listener grant; the wizard asks with a prominent disclosure as the switch goes on |
| Handwriting and text-scanning tools in the Recommended/Power starter sets | full flavour only; the sets top up with Wikipedia and Power saving when they drop out |
| Document scanner in the Power starter set | needs Google Play services; absent otherwise, triggering the same top-up |
| Weather section of the onboarding tool-setup page | needs a location (search or coordinates) and a network call to be useful |
| Autofill chips and platform smart replies in the suggestion strip | needs Android 11+ and a system autofill service; suppressed while incognito |
| Storage screen exact figures | needs API 26+ StorageStatsManager; older devices get a walked estimate labelled as such |
| AI tools pinned by the Writing mode and the AI discover card | drop out on their own in a build without AI (isSupportedTool), leaving the rest of the bar untouched |
| Anniversary egg install date | read from the package manager, so a full uninstall and reinstall restarts the count |

## Coverage notes

- **Typing core: prediction, autocorrect, learning, spell check**: Read in full: all 33 files under core/prediction/src/main/.../core/prediction (SuggestionEngine, FuzzyBeamSearch, UserLexicon, CorrectionStats, KeystrokeTiming, Register, RevisionAdvisor, NgramReranker, CandidateReranker, LanguageMixConfidence, FieldLanguageMix, WordContext, WordKey, Apostrophes, SeedBigrams, SpellingMap, NameIndex, ContactEmails, SystemUserDictionary, CustomDictionaries, DictionaryLoader, CompositeWordSource, NgramPack, NgramPackCodec, PackedTrieCodec and FrequencyCodec, PackedTrie, MappedTrie, MappedNgramPack, Trie and WordSource, TrieWalker, TrieCompleter, KeyProximity, TouchModel) and all 5 under core/prediction/.../core/dictionaries (DictionaryCatalog, NgramPackCatalog, DictionaryStore, WordlistDownloadManager, NgramPackDownloadManager). Also read core/intelligence/src/full/.../HarperSpellCheckerService.kt with its manifest and spellchecker.xml registration; the prediction wiring, learning, revert and commit paths in feature/ime/.../WMKeyboardService.kt; the smart-hit-detection code in feature/ime/.../ui/KeyboardScreen.kt; the typing, suggestion-strip and autocorrect settings blocks in core/settings/.../SettingsRepository.kt; the personal-dictionary, blacklist and custom-dictionary screens in app/.../MainActivity.kt plus the wordlist download UI in LanguageSettingsScreens.kt; and docs/src/content/docs/smart/suggestions.mdx plus the headings of the other eight smart docs. Every count is from code or assets (catalog entries and asset lines counted with grep, excluding comments), not from docs. NOT covered, deliberately: glide/gesture decoding in core/prediction/.../core/gesture (GlideBeam, GlideWorkspace, GlideKeyMap, GlideCoverage, RomanizedIndex, GestureGeometry) — it shares the engine's walk sources and reranker but belongs to the gestures area; the Harper grammar engine internals in core/grammar and the grammar panel; emoji prediction and inline emoji search; smart chips (calculator, currency, unit); autofill chips and system smart replies; CJK composers and conversion dictionaries in core/input; suggestion-strip rendering, sizing and shift re-casing; pattern snippets; typing stats; and all test sources and the prediction eval/latency harnesses.
- **Input behaviour: glide, gestures, cursor, editing, keys**: Read in full or in the relevant sections: core/input (DeadKeys, BrailleChord, MorseCode), core/prediction/gesture (GlideBeam, GlideCoverage, GlideKeyMap, GlideWorkspace, RomanizedIndex, GestureGeometry), core/language KeyActions.kt, core/tools/HardwareShortcuts.kt, core/settings/SettingsRepository.kt (KeyPopupSettings, KeyRepeatSettings, OneHandedSettings, HardwareKeyboardSettings, FeedbackSettings, LongPressLetterActions, GestureSettings, LayoutBehaviorSettings, TextEditingSettings, SpaceSwipeAction/LetterSwipeAction/SpacebarDisplay, and the input-related fields of KeyboardSettings), core/common ToolbarTool.kt. In feature/ime: KeyboardScreen.kt gesture detectors, pointerInputKey (spacebar / backspace / flick / generic branches), smart-hit observers, popups, one-handed rail, docked and floating frames; ResizeOverlay.kt; TextEditPanel.kt; ComposingResume.kt; LanguageSwitchOverlay.kt; and WMKeyboardService.kt onKey/onShift/onCapsLock/onDelete/deleteFromField/onDeleteWord/onSpace/onCursorMove(+Vertical)/onUndoRedo/onTextEdit/glide decode+commit paths/hardware key dispatch/autoCapitalizeShift/onModifier/onSizingAction/onComputeInsets. Selection macros were added later and read from core/content/.../core/selection/SelectionMacros.kt, the SelectionMacroSettings/SelectionMacroPlacement block and DirectBootSettings entry in core/settings, feature/ime/.../ui/SelectionMacroBar.kt, and WMKeyboardService's refreshSelectionMacros/onSelectionMacro/replaceSelection paths. Cross-checked against docs/src/content/docs/reference/gestures.mdx but every entry is grounded in code. Not covered (other areas): the suggestion strip and autocorrect scoring itself, prediction engine internals, emoji/GIF/sticker panel gestures, clipboard panel swipes, toolbar drag-to-pin, voice bar dragging, theme/appearance, layout editor, per-app language, and the CJK/Avro composers beyond how they gate glide and hardware interception. I did not count shipped layouts or languages (another area's job) — the only layout count here is the single shipped flick layout (app/src/main/assets/layouts/ja_flick.wmlayout.json). Nothing was run or device-verified; this is a static read.
- **Languages, scripts, layouts, transliteration**: Read in full: core/language (Script.kt, Language.kt, Numerals.kt, FancyStyles.kt, LanguageSuggestions.kt, DeviceLocales.kt, RomanizedPairing.kt; core/layout's LayoutSpec, BuiltInLayouts, AssetLayouts, KeyActions, KeyboardLayout, LayoutFile, LayoutSelection, ForeignLayout end to end, LayoutRepair head, TabletExpansion head; transliteration/AvroPhonetic, BengaliGraphemes, BengaliPhoneticIndex). Read in core/input: Composer.kt, PinyinComposer, DoublePinyin, CjkConfig, CjkDictCatalog, CjkDictDownloadManager head, HanVariant, PinyinFuzzy, JyutpingFuzzy, CjkUserHistory, CjkNgrams, StrokeComposer, CangjieComposer, T9/Zhuyin/Japanese/Jyutping heads, HangulComposer, VietnameseComposer head, IndicClusterComposer, DeadKeys, MorseCode, BrailleChord. Also Subtypes.kt, the per-app-language and fullStop/emoji-key rewrite paths in WMKeyboardService and KeyboardScreen, KeyIcons, KeyboardFonts, LanguageSettingsScreens, LayoutEditorScreens (action catalog + foreign import), SpellingMap, FieldLanguageMix, LanguageMixConfidence, and all 8 docs/src/content/docs/languages/*.mdx.

Counts come from code and assets and are pinned by `ShippedCountsTest`: 845 languages (361 hand-written + 484 generated from the Keyman corpus) and 1,274 layouts (18 built-in + 1,256 .wmlayout.json assets, 862 of them converted Keyman keyboards). Run that test rather than recounting by hand; it also lists every file that quotes these figures. Spelling-map figures are data lines excluding comments (11,914 bn_rom + 2,369 en_bn); the docs round these to 12,000 and 2,300. The editor's action picker has 28 entries in 6 groups, which the docs now match.

Not covered (other areas or not read): the suggestion/prediction engine itself, glide typing, autocorrect, the downloadable word-list catalogue and its per-language sizes, emoji keyword packs, handwriting, voice/dictation languages, theme-side script font storage (ThemeSpec.scriptFontIds), and the addon repository format beyond noting "layout" is one of its types. I did not read Lattice.kt, ConversionDictionary.kt, CodeTableDictionary.kt or SyllableSegmenter.kt in full (headers and call sites only), nor LayoutRepair.kt past its rule constants, TabletExpansion.kt past its eligibility contract, or the 354 asset layout files individually - those I analysed programmatically for composer/layer/flick distribution. IPA and music layer contents come from the asset JSON structure plus the docs, not a key-by-key read.
- **Themes and appearance**: Read in full: core/theme (ThemeSpec.kt, PaletteThemes.kt, ThemeRendering.kt, ColorVision.kt, PhotoPalette.kt, BackgroundBitmaps.kt, FlexTheme.kt, SnyggMapper.kt head), core/settings (ThemeOverrides.kt, RotationPool.kt, PhotoBackgroundSettings.kt, ThemePhotoSweep.kt, RotatingBackground.kt, DirectBootSettings.kt theme half, AutoThemeSettings + ThemeMode + KeySoundStyle + ThemeGalleryStyle in SettingsRepository.kt), feature/ime/ui/KbTheme.kt, feature/tools/PhotoBackgroundManager.kt, core/tools/PhotoSources.kt, app/PhotoBackgroundUi.kt. Read in full or by section: app/ThemeScreens.kt (4180 lines — gallery, editor, all pickers, gradient editor, cropper, colour picker), core/icons (IconSlots.kt, IconOverrides.kt, IconPacks.kt, IconPackFile.kt head, IconPackStore constants), feature/ime/ui/KeyboardFonts.kt, KeyTextures.kt, KeyPressEffects.kt, BoardDecals.kt, BuiltinIcons.kt catalog. Counts verified from code/assets: 28 built-in looks in 12 entries (4 families), 10 palette ports, 12 key shapes, 24 editor colour rows, 15 seed swatches, 6 texture slots, 6 decals, 12 variants, 6 effect kinds, 6 effect images, 97 icon slots, 181 bundled glyphs, 20 Latin Google Fonts, 27 automatic script faces, 22 script pickers, 12 photo topics, 14 photo colours, 6 rotation intervals, 3 scopes. Skipped or only skimmed: Snygg.kt stylesheet parser internals, SvgParser.kt, IconPackStore.kt beyond its constants, PhotoDetailScreens.kt and the photo library/rotation settings screens (read only their entry points and the shared UI in PhotoBackgroundUi.kt), UnsplashClient/PexelsClient request building, AddonScreens/AddonInstaller theme-install UI beyond the theme branches, MainActivity route plumbing, onboarding theme picks (OnboardingPages.kt), and the docs prose (used only to cross-check — note docs/themes/overview.mdx says 26 built-ins, which is stale against the 28 in code). Did not run the app or verify anything on a device.
- **Emoji, GIFs, stickers, kaomoji**: Read in full: all 19 files of :core:emoji (catalogue, search, shortcodes, triggers, suggester, usage, variant index, names, keyword packs, dict catalogue/store/codec/download manager, font coverage/shaping/render check, animated, text art); the sticker half of :core:content (StickerPackFile, StickerPackStore, StickerPacks, StickerImage, StickerOutline, StickerEditState, StickerSearchWords, SubjectCutout in both full and lite source sets), plus MediaMime, EmojiFontDownload, EmojiGraphemes; app/StickerPackScreens.kt and app/StickerEditorScreen.kt; the EmojiPanel/EmojiCell/EmojiVariantPopup/DualTonePicker/TextArtGrid/EmojiBottomBar/FavouritesReorderPopup/EmojiBarStrip block of feature/ime KeyboardScreen.kt and MediaToolPanels.kt (GifPanel, MediaActionSheet, source chips); the emoji, animated-emoji, emoji-sticker, inline-colon-search, suggestion and commitImageFile paths in WMKeyboardService.kt; the emoji settings, emoji-keyword settings and emoji-font sections of MainActivity.kt; core/tools GifSources.kt and MediaCategories.kt, feature/tools KlipyClient/GiphyClient heads; all five docs/emoji pages. Counts taken from the asset TSVs and the source lists themselves (catalog 1,914 rows; variants 2,030; shortcodes 1,936; triggers 2,121; animated 881; dict catalogue 125; kaomoji 201/15 groups; emoticons 111/8 groups; curated triggers 78; synonyms 43). Skipped or only skimmed: the GIF/sticker settings screens in MainActivity (behaviour taken from the settings data classes and docs rather than the composables), the unit tests beyond EmojiCatalogTest and EmojiDictCatalogTest, the addon-install plumbing for emoji_font/emoji_keywords/stickers types, the backup and storage-category code paths for sticker packs, image-loader/Coil configuration, and the emoji-related onboarding presets. Rarity marks are my judgement, not verified against rival keyboards.
- **Toolbar and the tool set**: Read in full: core/common/.../core/settings/ToolbarTool.kt (the 64-entry enum, direct-boot set, starter sets, default orders, page maths), core/settings/.../ToolAvailability.kt, core/tools UnitConvert.kt, SymbolCatalog.kt, CryptoCatalog.kt, TypingTest.kt, CalcEngine.kt, PasswordGen.kt, GifSources.kt, AiActions.kt, plus targeted reads of CurrencyClient.kt, TranslateClient.kt, WeatherClient.kt, MediaCategories.kt, SmartSuggest.kt (keyword map), HardwareShortcuts.kt (leader letters). In :feature:ime read WMKeyboardService.kt's tool-tap dispatcher and the flashlight/undo/incognito/power-saving/fancy/resize handlers, KeyboardScreen.kt's ToolDragController + DraggableTool + ModesPanel, ResizeOverlay.kt, ToolPickerOverlay.kt, and headers of ToolPanels.kt/UtilityToolPanels.kt/MediaToolPanels.kt/GeneratorPanels.kt/GrammarPanel.kt/PluginPanel.kt. In :app read ToolsSettings, ToolGroups and the head of ToolDetailSettings in MainActivity.kt. In core/settings read the ToolbarBehavior/ToolboxSettings/tool-icon/enabled-tools blocks of SettingsRepository.kt, plus AiProvider and GrammarDialect. Read all 17 docs/src/content/docs/tools/*.mdx and cross-checked their numbers against code — where they disagreed I used the code: the docs say 62 tools and 37 direct-boot-safe (pre-RESIZE), the enum has 64 and 39; docs say 33 translate languages, TranslateClient.languages has 32. Counted rather than guessed: 64 tools, 39 direct-boot safe, 59 in lite, 25 default leader letters, 36 keyword-chip tools, 369 symbols in 9 categories, 14 unit categories / 118 units, 39 coins (20 default) / 15 pinned fiat codes, 32 translate languages, 8 AI actions, 9 AI providers, 8 local models, 22 fancy styles, 16 bundled GIF categories, 14 typing-test quotes / 200 prompt words / 4 badges. NOT covered in depth (belongs to other areas, only touched where the toolbar owns it): the emoji panel's internals, the clipboard's storage layer, the GIF/sticker provider clients' request shapes, Whisper offline voice, the smart-chip engine itself, keyboard modes' own settings, theme internals, and the plugin runtime's Lua API. I did not read the full 14k-line KeyboardScreen.kt or the full 13.7k-line MainActivity.kt, so a minor per-tool setting or panel affordance may be missing; every entry above came from a file I actually opened.
- **Clipboard, snippets, text expansion**: Read in full: core/content clipboard (ClipboardStore, ClipEntities, ClipSensitivity, PhoneFormats), core/content snippets (SnippetStore, SnippetMatcher/SnippetIndex, SnippetFile), core/content otp (NotificationOtp, NotificationOtpMonitor), core/content/media/MediaNotificationListener, core/prediction/ContactEmails, feature/ime/InlineAutofill. Read the clipboard/snippet/OTP/contact-email sections of WMKeyboardService.kt (~1000 of its 15.7k lines) and the clipboard panel, entity strip, info popups and paste chip in KeyboardScreen.kt. Read ClipboardSettings/OtpSettings/contact settings and the config-backup clipboard filter in SettingsRepository.kt, the clipboard tool-detail, phone-format and snippet settings screens in MainActivity.kt, StorageCategories.kt, SpecialAccess.kt, AddonRepo/AddonInstaller snippet-pack paths, plus docs/tools/clipboard.mdx, docs/tools/snippets.mdx, docs/smart/contacts.mdx. Skipped: the unit tests under app/src/test/.../clipboard and .../snippets (used only as cross-checks, not as feature sources); NameIndex/ContactNames internals and the wider SuggestionEngine ranking (another agent's area beyond the contact hooks); the Harper spell-checker service body; the text-editing panel beyond its copy/paste actions; smart-chip \"keyword shortcut\" wiring that opens the clipboard/snippets panels (belongs to the smart-chips area); addon install/preview UI beyond the snippet-pack paths. Counts (7 clip kinds, 3 entity kinds, 18 clipboard settings, 5 OTP settings, 18 snippet variables, 4 capture transforms, 4 anchored OTP patterns, 17-word deny list, 44 two-digit dial codes, 6 clipboard key actions) were taken from the enum/field declarations, not estimated.
- **AI, voice, handwriting, scanning**: Read in full or in the relevant part: core/intelligence (LocalLlmCatalog, LocalLlmEngine full+lite, LocalLlmDownloadManager, LocalLlmStore, ChatReplay, Handwriting.kt, MlKitInit); core/voice (VoiceInputEngine, VoicePunctuation, VoiceSpacing, WhisperRecorder, and whisper/ Catalog, Store, DownloadManager, Languages, Script, Engine full); core/tools AiActions.kt, AiPrompts.kt, AiThinking.kt, AiPhase.kt, AiMarkdown.kt; feature/tools AiClient.kt (all 4 wire formats); core/content aichat/AiChatStore.kt and aihistory/ (Store + Guard); core/settings AiProvider/AiSettings/WhisperSettings/VoiceBarSettings/CameraSettings/handwriting keys plus PowerSavingSettings.underPowerSaving; feature/ime AiPanel.kt, VoicePanel.kt, VoiceToolbar.kt, HandwritingPanel.kt, CameraToolPanel.kt, ScannerToolPanels.kt (full), DocScanActivity.kt, and the voice/handwriting/AI sections of WMKeyboardService.kt; app/ LocalLlmSettings.kt, WhisperSettings.kt, AiChatScreens.kt, AiChatController.kt, AiHistoryScreen.kt and the AiToolSettings / AiActionEditor / HandwritingModelManager / tool-detail sections of MainActivity.kt; core/common ToolbarTool.kt; core/config build.gradle.kts flavour flags; docs tools/ai.mdx, voice.mdx, whisper.mdx, handwriting.mdx, scanner.mdx, camera.mdx. Counts (9 providers, 8 AI actions, 8 local models, 29 Whisper models = 10 multilingual + 19 single-language over 13 languages, 99 Whisper languages, 40/26-language grouped graphs, 13 barcode formats, 10+10 spoken-punctuation phrases, 13 reasoning-model hints, 8 max-token presets, 5 local-context presets, 32 handwriting script codes) were taken from the source, not the docs. Deliberately NOT covered, as they belong to other areas: the Harper grammar checker and spell-checker service (they live in :core:intelligence but are prediction/smart-typing features), the network Translate/GIF/search tools, smart-suggestion chips beyond noting the tool keywords (ai, dictate, ocr, scan, docscan, handwrite, camera), the toolbar/toolbox plumbing, theming of these panels, hardware-keyboard leader-key routing, string resources, and unit tests. I did not run a build or exercise anything on a device — everything here is read from source.
- **Privacy, backup, storage, statistics**: Read in full: core/settings BackupCrypto.kt, ConfigBackup.kt, SettingsBackup.kt, LockedSettings.kt, DirectBootSettings.kt, CloudBackup.kt, AutoBackupRunner.kt, AutoBackupScheduler.kt, sink/BackupSink.kt, sink/AutoBackupNaming.kt, sink/BackupClients.kt; core/common DirectBoot.kt, PermissionDisclosure.kt, DebugLog.kt; core/content AiHistoryGuard.kt; core/tools TypingStats.kt and TypingAchievements (in TypingTest.kt); app AutoBackupJobService.kt, WMBackupAgent.kt, oauth/BackupOAuth.kt, PermissionsScreen.kt, statistics/StatisticsScreen.kt, storage/StorageScreen.kt, storage/StorageScan.kt, storage/StorageCategoryScreen.kt, storage/StorageCategories.kt (skimmed the middle third), res/xml/data_extraction_rules.xml; MainActivity PrivacySettings, AutoBackupGroup and BackupSettings; FileImport.kt config/encrypted-config branches; SettingsRepository AutoBackupSettings/BackupDestination/S3Config/FtpConfig, exportConfig/importConfig/describeConfig, portableClipboard, restoreStickers, and the incognito/cloudBackup/typingStats fields; WMKeyboardService incognito, learning-gate, recordStat, autofill-budget and secure-field code; docs/src/content/docs/privacy/{overview,data,incognito,backup,permissions}.mdx. Skipped or only grepped: the individual sink implementations (SafFolderSink, WebDavSink, S3Sink/AwsSigV4, FtpSink/FtpListing, DriveAppDataSink, DropboxSink, OneDriveSink, OAuthTokens) beyond their TLS/permission/error handling and folder scopes; privacy/network.mdx (network policy is another area's ground); the clipboard store internals, personal-dictionary screen and AI-history screen, which belong to the clipboard/prediction/AI areas — I covered only their privacy-facing gates. Counts (7 destinations, 11 sections, 19 secret keys, 5 transient keys, 28 storage categories in 6 groups, 4 achievements, 5 stat tiles, 500-entry ring, 10 crash records, 370-day retention, 120k PBKDF2 rounds) are read off the code, not estimated. I did not build or run the app, so nothing here is device-verified.
- **Accessibility, form factors, platform integration**: Read in full: app/src/main/java/com/wasimaster/wmkeyboard/app/AccessibilityScreens.kt, core/common/.../core/accessibility/{KeyboardPassthrough,TouchPassthroughService}.kt, app/src/main/res/xml/passthrough_service.xml, core/theme/.../ColorVision.kt, core/settings/.../{PowerSavingSettings,ScreenVariant,DeviceFormDefaults,DirectBootSettings,LockedSettings(partial)}.kt, core/settings/.../core/power/PowerSaver.kt, core/common/.../core/settings/DeviceForm.kt, core/common/.../core/directboot/DirectBoot.kt, core/language/.../core/layout/TabletExpansion.kt, core/tools/.../{HardwareShortcuts,HardwareHints}.kt, app/.../{SettingsDeepLink,SettingsRoutes,AddonDeepLink}.kt, app/src/main/res/xml/shortcuts.xml, app/.../updates/{AppUpdater,UpdatePolicy,UpdatePrefs,UpdateState}.kt, core/common/.../app/SpecialAccess.kt, core/content/.../media/MediaNotificationListener.kt, core/common/.../core/util/PlayServices.kt, app/src/nogms/.../NoGmsDrive.kt, app/src/main/AndroidManifest.xml, app/src/main/res/xml/method.xml, app/build.gradle.kts (flavour/channel block), docs accessibility/overview.mdx and reference/shortcuts.mdx. Read in part (targeted regions): feature/ime/.../ui/KeyboardScreen.kt (touch-exploration locals, spoken labels, key semantics, debounce, pass-through region, screen-variant resolve), feature/ime/.../WMKeyboardService.kt (hardware-keyboard detection, onConfigurationChanged, resolveLayoutSet, subtype registration, direct-boot/unlock paths, lock state), feature/ime/.../ui/KbTheme.kt (accessibilityAdjusted), core/settings/.../SettingsRepository.kt (accessibility fields, HardwareKeyboardSettings, one-handed/split/floating, direct-boot flow), core/common/.../ToolbarTool.kt (direct-boot-safe list, tablet toolbar defaults, GMS gating), TabletExpansionCorpusTest.kt for the declined-layout count. Not covered: the settings-app UI implementation of the hardware-shortcut and power-saving screens beyond the setting list (MainActivity.kt is 13.7k lines and I only read the relevant regions); PlayAppUpdater.kt and UpdateUi.kt were skimmed by signature rather than read line by line; the settings app's own TalkBack semantics (as opposed to the keyboard's); backup/restore, RTL layout mirroring, per-app modes, and the panel focus-ring implementation, which belong to other areas; docs/reference/settings/accessibility.mdx and docs/typing/size-position.mdx were read only via targeted greps. No numbers here are estimates — every count came from the enum, map, asset list or test it is stated against.
- **Extensibility: addons, plugins, imports, formats**: Read in full or in substantial part: core/addons (AddonRepo, AddonRepoCodec, AddonStore, Semver), feature/addons (AddonInstaller, AddonDownloadManager, AddonApply, AddonReconciler, AddonPreviewContent), all 13 files of core/plugins, app/FileImport.kt, app/AddonDeepLink.kt, app/AddonScreens.kt (skimmed for UI capabilities), app/PluginScreens.kt (outline), core/theme/FlexTheme.kt + SnyggMapper.kt + ThemeCodec, core/language/layout/ForeignLayout.kt + LayoutFile.kt, core/feedback/SoundPack.kt + SoundFile.kt, core/icons/IconPackFile.kt + IconSlots.kt + SvgParser.kt (header), core/content SnippetFile/StickerPackFile/FontFile, core/prediction/CustomDictionaries.kt, core/emoji/EmojiKeywordPack.kt, core/settings/ConfigBackup.kt, app/src/main/AndroidManifest.xml intent filters, and docs/reference/file-formats.mdx, docs/reference/importing-other-keyboards.mdx, docs/development/addon-repos/*. Counts verified against code: 12 installable add-on types, 97 icon slots (64 toolbar tools + 14 key + 6 chrome + 13 emoji-tab), 11 backup sections, 10 file-associated extensions, 11 plugin widget kinds, 1 plugin permission, 5 sound roles, 8 flex loss reasons, store caps (30 repos, 50 plugins, 50 sticker packs, 50 fonts, 30 sounds, 20 sound packs, 20 icon packs). Not covered (other areas or out of scope): the auto-backup SAF sink and BackupCrypto internals, the downloadable-dictionary catalog and download pipeline, .wmdict/.wmng codec internals and the :tools:dictc compiler, ThemeSpec's own field set and theme variant/decoration system, the addon repository's external publishing scripts (build_index.py / validate.py / build_plugins.py live in the separate wmkeyboard-addon-repository repo, not here), and the full body of AddonScreens.kt UI code past what was needed to name capabilities. I did not build or run anything, so nothing here is device-verified.
- **Modes, rows, field adaptation, runtime**: Read in full: core/settings/.../KeyboardModes.kt, core/tools/.../SymbolSets.kt, SymbolCatalog.kt, TypingTest.kt, EggLinks.kt, core/language/.../Numerals.kt, feature/ime/.../FieldRegister.kt, app/.../EggPrefs.kt, AnniversaryEgg.kt, OnboardingGraph.kt, OnboardingPersona.kt. Read the relevant regions of the large files: WMKeyboardService.kt (onStartInput field adaptation ~2800-3040, onUpdateSelection, commitToField/reattachComposing ~5780-5900, resolveLayoutSet ~5525-5600, EditorInfo helpers ~15690-15860), KeyboardScreen.kt (TopBar and strip lanes 1910-2800, SymbolRowStrip 3680-3800, bar order 6340-6470, KeyRows and number row 8700-8850, currentLayout field swaps 9270-9420, row-visibility helpers 9670-9720), KeyboardState.kt (FieldKind, PanelMode, TypingTestUi, KeyboardUiState gates), MainActivity.kt (RowsSettings 12734-12900, ModesSettings 13570-13620, TypingTestToolSettings 10751-10870), SettingsSearch.kt, SettingsSearchMatch.kt, SettingsSearchScreen.kt, storage/StorageCategories.kt + StorageScan.kt + StorageScreen.kt + StorageChart.kt, ToolbarTool.kt starter sets, LayoutSpec.kt / LayoutCompiler.kt / LayoutRepair.kt number-row and ABC-key parts, BuiltInLayouts numpad definitions, OnboardingDiscover.kt, OnboardingPages.kt (tool-setup section), OnboardingTry.kt, Onboarding.kt (wizard shell), ModeIcons.kt, ComposingResume.kt. Docs read: typing/field-adaptation.mdx, typing/modes.mdx, reference/easter-eggs.md, reference/settings/layout.mdx (number row), reference/settings/index.mdx (search), reference/settings/about.mdx (storage).

Counts taken from source, not docs: 6 seeded modes, 36 mode icons, 7 ModeField kinds, 7 BarRow slots, 5 built-in symbol sets (11/15/32/22/20 entries), 8 FieldKind values with 5 numeric-pad kinds, 8 EnterAction values, 6 numeral systems, 6 easter eggs, 4 typing achievements, 200 test words and 14 quotes with a 24-run history, 11 onboarding pages / 12 discover cards / 5 spacebar choices, starter sets of 8/21/35 out of 64 tools, 58 search synonym groups, ~500 hand-written search entries (counted by call site) plus one per supported tool, 28 storage categories in 6 groups of which 3 are synthetic.

Two places where the shipped docs are stale and I followed the code: the number row now defaults ON (KeyboardSettings.numberRow = true, matching commit c547947c) where reference/settings/layout.mdx still says Off, and "Hold ?123 for numpad" defaults ON (LayoutBehaviorSettings.symbolsLongPressNumpad = true) where typing/modes.mdx says Off.

Deliberately skipped as other agents' areas: the emoji panel and emoji fonts, the toolbar/toolbox and the 63 individual tools (only starter-set membership and mode-owned tool ordering are covered here), the prediction engine itself (only the strip's layout and the field gates that switch it on), themes, layouts and the layout editor beyond the number-row and ABC-key repair hooks, clipboard/OTP/snippet chip internals (only their slot in the strip's lane order), voice, plugins, addons, backup, and the per-row restore-to-default button in the settings UI. I did not run the app or any tests; everything above is read off source.