native/docs/widgets-verification.md

Android widgets: verification checklist

Every tap target of the 32 Android home-screen widgets (src/widgets/), how it was tested on the emulator, and what happened. Started for the report "widget actions sometimes don't work" (#52 follow-up).

Rig

• Emulator Bulwark_Pixel7_API35 (Pixel 7, Android 15, x86_64), Pixel launcher, release APK built with -PreactNativeArchitectures=x86_64.
• Servers: the standing test servers, Stalwart 0.16 (stalwart-test) and 1.0 (stalwart-test-v1), reached through a logging reverse proxy that records every JMAP method, notUpdated/notCreated and errors, and can delay or fail chosen methods on request.
• Accounts: usera@example.org (password) and userb@example.org (OAuth through Stalwart's own authorization server) signed in at once. Both are members of the team@ group; usera's calendar is shared with userb. Extra test data: tasks for both, invitations each way through server-side scheduling.
• Placed: Triage, Tasks, Invitations (others in phase 3).

States

Code	State	How
FG	App on screen when the link arrives	am start of the link while the app is in front
BG	App backgrounded, JS runtime alive	Home after using the app
COLD	Process dead	adb root, kill -9 <pid> (not am kill, not force-stop)
OFF	Offline	cmd connectivity airplane-mode enable
ACC2	Item belongs to the non-active account	the other account active in the app
SHARED	Item in a shared or group account	usera's calendar seen by userb
DBL	Two taps in quick succession	input tap twice, 150 ms and 1–1.5 s apart
UPD	Tap while a refresh is running	proxy delays Email/set by 4 s, second tap meanwhile

A widget tap cannot happen with the app in front, so FG applies to deep links only. Links were opened with am start -a VIEW -f 0x10000000, which is exactly what the widget provider does (RNWidgetProvider.openUri); the widget's own Reply, card and event taps were also tapped on the launcher.

Phase 1 results (before fixes, Stalwart 0.16)

Background actions

Action	Widgets	BG	COLD	OFF	ACC2	DBL	UPD	Notes
archive	Triage	pass	pass	fail	n/a	fail	fail	see A1, A2, A3
trash	Triage	pass	pass	fail	n/a	fail	fail	same code path as archive
triageNext	Triage	pass	pass	pass	n/a	pass	pass	local only
rsvp	Invitations	pass	pass	fail	fail	fail	fail	A1, A3, A4, A5
toggleTask	Tasks, Today overview	pass	pass	fail	fail	fail	fail	A1, A3, A4, A5, A6
markRead	(no button uses it)	–	–	–	–	–	–	kept for the API
any button	all	pass*	pass*	–	–	–	–	*on this emulator; A0

Deep links (links.* in src/widgets/clicks.ts)

Link	Used by	FG	BG	COLD	OFF	ACC2	Notes
inbox	Inbox, Unread count, Folder counts, Tag, Attachments, Mail and next, Today overview	pass	pass	pass	pass	n/a
message	Inbox/Starred/All accounts rows, Latest message, Triage card, Mail and next, Attachments	pass	pass	pass	fail	pass online	L4
reply	Triage	fail	fail	fail	fail	fail	L1
draft	Last draft	pass	pass	pass	fail	pass online	L4
unified (all / starred / role)	All accounts, Starred, Folder counts, Last draft	pass	pass	pass	not run	n/a
scheduled	Outbox, Folder counts	pass	pass	pass	not run	n/a
search (empty / query)	Inbox, Search mail, Favourite people	pass	pass	pass	not run	n/a	empty search opens the list without focusing the field
compose (plain)	Inbox, Last draft	pass	pass	pass	pass	n/a
compose with to + subject	Birthdays "Send wishes", Up next "Running late"	fail	fail	fail	fail	n/a	L2
calendar	all calendar and plans widgets	pass	pass	pass	crash	n/a	L3
event	Week, Month, Today, Next event, Up next, Countdown, Invitations, Mail and next	fail	pass	pass	crash	fail	L3, L5
contacts	Shortcuts, Favourite people, Birthdays	pass	pass	pass	not run	n/a
files	Shortcuts, Recent files	pass	pass	pass	not run	n/a
settings/vacation, /account, /calendar	Vacation, Storage, Free time, Tasks (off)	pass	pass	pass	not run	n/a
video URL	Up next "Join"	–	–	–	–	–	external https link, opens the browser

Refresh

Case	Result	Notes
App goes to the background	fail (sometimes)	R1
Account switched in the app	fail	R1: widgets kept the previous account until the next app start
Cold periodic update	pass for mail	R2: calendar, tasks, files, scheduled stay as last loaded by the app
Back online after an offline tap	fail	A1: nothing brings the change back until the app or a 30-minute update runs

Causes found

• A0. Buttons silently dead on fast phones. The widget library registers every button's PendingIntent with requestCode = (int) System.currentTimeMillis() and FLAG_CANCEL_CURRENT. All buttons of one widget share the same action and component, so two buttons registered in the same millisecond get the same identity and the second registration cancels the first: that button then does nothing at all. On the emulator each registration takes 3–10 ms (measured from the request codes in dumpsys activity intents), so every button survived; a current phone makes the binder call in well under a millisecond, which makes the dead button depend on timing — "sometimes". The cancelled-then-recreated records also pile up (227 for three widgets after an hour of testing).
• A1. Offline or failed calls look like they worked. The action edits the stored snapshot first and relies on the next refresh to undo a failed call. Offline that refresh fails too and returns the edited snapshot, so an archive that never reached the server shows as done; a cold refresh never reloads calendar or tasks, so a refused RSVP or task change is never undone either. Failures are only console.warned.
• A2. A fast second tap repeats the first. Two taps 150 ms apart both archived d2aaaaa3: the second tap hits the buttons of the old drawing, which still name the first message. Harmless for archive; for task ticks the code would flip the task back, because toggleTask inverts whatever the stored snapshot says instead of carrying the state the user saw.
• A3. A refresh brings back a message just archived. Each tap is its own headless task in the same runtime; they interleave at every await. With Email/set delayed 4 s, tap 1's refresh read the server before tap 2's archive landed, was stored anyway (it started after tap 2's local edit, so noteLocalChange did not catch it) and redrew the archived message (baaaaaai, log 08:44:19), until tap 2's own refresh removed it again. Separately, load–edit–save of the snapshot is not serialized, so two concurrent edits can drop one, and redraws of different snapshots can land out of order. In one run the second tap archived a message the card was not showing.
• A4. RSVP and task ticks go to the wrong account after a switch. They pick the client from snapshot.activeAccountId and look the item up by id in the current snapshot, not from the tap's own data. JMAP ids are small per-account sequences (e, f, h1kbleaaaaaj), so a tap on a drawing made before an account switch can match another account's task or event with the same id. Not reproduced on the device (the window between the stored refresh and the redraw is short); follows from the code.
• A5. Nothing tells the user. See A1.
• A6. The task tick target is 22 dp. A tap on the task's title or a few dp beside the circle does nothing.
• Lead 2 (target lacks widgetId) is ruled out: the logged click data of Archive/Delete is {"id":…,"widgetId":3,"accountId":…}.
• Lead 4 (credentials in a cold runtime): the password account restores and acts from a cold start (archive, task tick). The OAuth account with an access token that expired while the app was dead is checked in phase 2.
• Lead 5 (progressUpdated) is ruled out: the widget's task update has carried no progressUpdated since the B12 fix, and both 0.16 and 1.0 accept it (updated, no notUpdated).
• R1. The refresh on going to the background often never runs. With an account switched in the app and Home pressed, no refresh request reached the proxy and the widgets kept the old account's mail.
• R2. Cold refreshes skip calendar and tasks. Only mail has JMAP code of its own; the rest needs the app's stores, which only run with the UI.
• L1. Widget Reply never opens the composer. The reader opens on the message but the composer does not follow, in every state.
• L2. "Send wishes" loses its subject. parseDeepLink takes the subject from the mailto parser, which returns an empty string rather than nothing, so the link's own subject is never used.
• L3. Calendar links crash the app offline. On an offline cold start the Calendar tab mounts CalendarShareSheet, whose list of people to share with calls ownPrincipalId() while rendering; with no session that throws "Not authenticated - call connect() first" and the app closes.
• L4. Message links for the other account fail offline. The link switches accounts first, which needs the server; offline the switch fails and the app shows "Couldn't open this".
• L5. Event links carry no account. With the other account active, an event link opens the Calendar tab and nothing else (or, with an id that exists in both accounts, the wrong event). In the foreground the event link landed on the Inbox.

Corrections to phase 1

• L1 and L2 were faults of the test rig, not of the app. adb shell am start -d <url> handed the URL to the device shell unquoted, and the shell cut it at the first &: Reply lost &action=reply (and &thread=), and "Send wishes" lost &subject=. Quoted, Reply opens the composer over the message and the subject arrives, cold, backgrounded and in the foreground, on 0.16 and 1.0.
• L4 is two app limits, not a widget fault. A message link offline needs the message on the device: with the offline mail cache off (the default) a message is not kept across app starts and the reader says "Failed to load email". A link for the other account needs the server for the account switch, so offline it says "Couldn't open this".
• R1 had a second half. Starting the background refresh directly (no timer) was not enough: fetch resolves every response through a zero-delay timer, and with the activity paused the first request went out and its answer was never read. The refresh now runs in a headless task of its own.

After the fixes (phase 2)

Same rig. 1.0 was reached as http://127.0.0.1:18191 through adb reverse, so its accounts (usera@127.0.0.1) sit next to the 0.16 ones; that path does not go through the emulator's network, so "offline" on 1.0 was simulated with the proxy refusing Email/set (503) instead of airplane mode.

Background actions

Action	BG	COLD	OFF	ACC2	DBL	UPD	1.0	Notes
archive	pass	pass	pass	n/a	pass	pass	pass	offline: the message comes back on the card with "Couldn't archive. Tap to try again."; the tap archives it once online
trash	pass	pass	pass	n/a	pass	pass	pass	offline: "Couldn't delete. Tap to try again."; the tap moves it to Trash once online
triageNext	pass	pass	pass	n/a	pass	pass	pass	local only, no server call
rsvp	pass	pass	pass	pass (unit test)	not run	not run	call passes, see 1.0 below	offline: the invitation stays with "Couldn't send your answer"; the retry accepts it. DBL and UPD not run on the device: they go through the same serial lane and pending overlay as archive and the tick, and actions.test.ts covers both
toggleTask	pass	pass	pass	pass (unit test)	pass	not run	call passes, see 1.0 below	two taps 150 ms apart send completed twice; offline the tick reverts with a notice naming the task, and tapping the notice once online sends one CalendarEvent/set and the task shows done. UPD not run on the device (see rsvp)
any button	pass	pass	–	–	–	–	–	request codes unique (107 click intents, 107 codes)

DBL for archive: two taps 150 ms apart still both name the message the drawing showed (the second is a harmless repeat); taps a second apart act on consecutive messages. UPD: with Email/set delayed 4 s, two archives 1.5 s apart leave the card on "5 of 5" for the whole run and nothing comes back (before: the first archive's refresh brought the second message back). Trash behaves the same: a double tap names the shown message twice, and two deletes 1.5 s apart with Email/set delayed move two different messages and nothing comes back.

Deep links

Link	FG	BG	COLD	OFF	ACC2	1.0
inbox, unified, scheduled, search, compose	pass	pass	pass	pass	n/a	pass
message	pass	pass	pass	pass with the offline cache (L4)	pass	pass
reply	pass	pass	pass	pass with the offline cache (L4)	pass	pass
draft	pass	pass	pass	only if opened before (L4)	pass	not run (same route as message)
compose with to + subject	pass	pass	pass	not run (no server involved)	n/a	pass
calendar	pass	pass	pass	pass (no crash)	n/a	opens; see 1.0 below
event	pass	pass	pass	opens the Calendar tab; the event needs the server	pass (switches account)	see 1.0 below
contacts, settings	pass	pass	pass	pass (Vacation settings say the server does not support it while offline)	n/a	pass
files	pass	pass	pass	pass (no crash; the screen shows the raw network error)	n/a	pass

Refresh

Case	Result
Account switched in the app, then Home	pass: the widgets show the new account within a second, both directions
App goes to the background	pass
Cold periodic update	pass: mail, calendar, tasks, files and scheduled (appDataAt set)
OAuth account with an expired access token, cold	pass: userb's token had expired an hour after sign-in; the cold refresh renewed it and loaded userb's inbox preview

Stalwart 1.0

• Mail actions and links pass: the archive race, a refused write with its notice and retry, trash, triage next, message and reply links cold and backgrounded, and the inbox, unified, scheduled, search, compose, calendar, contacts, files and settings links.
• The app on main does not load calendar events or tasks from 1.0: its CalendarEvent/get asks for recurrenceOverrides together with utcStart/utcEnd, which 1.0 refuses as a whole (invalidArguments). The unmerged feat/stalwart-1.0 branch fixes that. Until it is merged the calendar and task widgets are empty against 1.0. The widgets' own calls were sent to 1.0 directly: the task update (progress, percentComplete) and the RSVP patch both come back updated.

Causes and their fixes

Cause	Commit
A0 dead buttons (shared request codes)	fix: stop widget buttons from going dead when two are drawn in the same millisecond
A3 refresh brings an archived message back, lost concurrent edits, out-of-order redraws	fix: keep a widget archive when a second tap's refresh lands before it
A1, A5 failures looked like success, no feedback	the commit above (a failed op is dropped) and feat: show on the widget when an action could not reach the server
A2, A4 tick flips back, item of another account	fix: send widget RSVPs and task ticks to the item the tap was made on
A6 22dp tick	fix: make widget task ticks easy to hit
R1 no refresh on leaving the app	fix: refresh the widgets when the app goes to the background, fix: finish the widget refresh after leaving the app
R2 cold refresh skipped calendar and tasks	fix: load calendar and tasks into the widgets when the app is not running
L3 offline crash from calendar and files widgets	fix: keep the app from closing when a calendar widget opens it offline, fix: keep the app from closing when a files widget opens it offline
L5 event links without account	fix: open a widget's event in the account it belongs to

Phase 3: layout review

All 32 widgets were drawn through a temporary in-app gallery (WidgetPreview, removed again) at their smallest, default and largest (4x5) size with sample data, light and dark, German, very long names and counts (five-digit counts, 50-character names and subjects), empty data, and the loading, signed-out, not-yet-loaded and unsupported states, and with the tap areas highlighted. Fixed:

• The Inbox header at two cells pushed the compose button off; header titles now give way to the buttons, and the search icon goes at that width.
• A long sender pushed the triage card's time and position out.
• German labels were cut on the triage buttons ("Archivie", "Lösc"); they drop to icons when they do not fit.
• Five-digit counts overflowed Unread count, Tag and Mail and next, and the total wrapped a character per line; counts from 10,000 are shortened.
• "ungelesen" was cut in Mail and next; it moves under the number.
• Buttons under 48dp (32–36dp) get a transparent 48dp tap area.
• The Month arrows and the Vacation switch looked like controls but only opened the app.
• Folder counts with no folders showed a bare heading.
• A finished task past its due date read "Overdue".
• The triage card and Latest message did not use their height for the preview.
• A failure notice about a long task title cut off "Tap to try again".
• Widget strings were English in every language; German added.
• Avatars showed initials only, worked out differently from the webmail. Initials now follow the webmail everywhere in the app (first letters of the first and last name, leading punctuation and emoji skipped), and the widget avatars show the contact photo or the sender's logo first, as the app's list does. Logos come from the same favicon service, are fetched when the snapshot is built and are cached for offline drawing; a logo over 40 KB, or one Android cannot decode, leaves the initials.
• The corners were rounder (22dp) than the launcher's own widgets; they are 16dp now, previews included.

Checked and left as they are:

• Dark theme: no white fallbacks; the primary is white as in the webmail.
• Large sizes of the 2x2 widgets are mostly empty space. A resize limit (maxResizeWidth) is given in dp, and on launchers with large cells it would pin a widget below two cells, so there is none.
• RTL is not supported: the widget library does not mirror layouts, and there are no right-to-left widget strings.
• Mail and next's chip for the following event is 24dp tall; the whole column also opens the calendar.

Open

• A0 cannot be shown on this emulator, where each registration takes 3–10 ms; the fix is checked by the request codes being unique.
• Calendar and task widgets against Stalwart 1.0 wait for feat/stalwart-1.0 (see above).
• Offline message links need the offline cache; links for the other account need the server for the switch (L4).
• Widget strings exist in English and German only.
• RSVP double tap and update race, and the tick's update race, were not run on the device; unit tests cover them.
• The Files screen opened offline shows the raw network error instead of an offline message (app screen, not a widget).