Skip to main content

Settings row grid

Settings sections and detail rows share SettingsRowLayout. Muted captions sit 4px inside a rounded (24px) grouped card. Rows use a 16px inset, a 24px slot for a thin Lucide line icon, a 14px gap before a medium-weight (w500) title and a 44px trailing action column with a 17px Lucide chevron. Settings and Appearance use Lucide icons only. Inset dividers start at the title column (54px), not under the icon. Rows have a 56px minimum height and expand for translated or enlarged text. A row shows its current value as a muted summary under the title, or as a short trailing value before the chevron (for example, the Appearance theme name). It does not show both, except the Time zone rows below. A trailing value keeps its natural width, flush right, while the title still fits on one line; otherwise it moves under the title, so titles never break mid-word at enlarged text. Full-size controls such as switches widen the trailing column and centre vertically instead of scaling down. Multiple timezone actions stack in the trailing column, keeping the text width and action centers consistent with chevrons. Existing English and Vietnamese labels and tooltips remain unchanged. Settings scroll lists use the design foundation’s tokens (AppLayout): content starts 8px below the shell header (pageTop) and ends with the shell-provided dock clearance plus a 24px end gap (scrollEndGap). Row height (56px), row inset (16px) and the gap between groups (24px) are the foundation’s row and section tokens. They inherit the shell surface and keep Back in its floating dock. These presentation defaults do not change timezone reads, writes, retries or permissions. settings_design_checks.dart covers row geometry, action touch targets and the final control clearing the dock; the compact navigation suite also exercises enlarged text in both languages and themes.

Time zone rows

Each Time zone row shows one value line: the zone as a city with its current GMT offset, for example “Ho Chi Minh City (GMT+7)”. Offsets follow daylight saving time, and the offset stays attached to its city. Raw identifiers such as Asia/Saigon are never shown, so they can’t break mid-word. Legacy device ids map to their current city, and Vietnamese shows “TP. Hồ Chí Minh”. When the personal choice is Automatic, the row shows “Auto” on its title line and names the zone that applies. An explicit choice shows only that zone. The workspace row shows only the workspace choice, so the effective zone is never repeated. Loading and account states replace the value rather than adding lines. Errors and rate limits keep their wrapped explanation and Retry action. These rows are the one place a row shows both a value line and a short trailing value. When a row has a value line, its trailing value sits on the title line, so the value keeps the full text width; at enlarged text it moves under the title. The explanation of Automatic and the zone list stay in the picker opened from the row. Offsets resolve through core/utils/timezone_location.dart, which loads the full tz data when a native alias such as Asia/Saigon is missing. timezone_label_test.dart checks every supported zone, settings_timezone_rows_checks.dart checks the one-line rows in both languages, and timezone_resolution_scope_test.dart checks the scoped states.

Settings detail shell and profile settings

All mobile Settings children use the same shell background and one shell top navbar with the destination title and actions. In-app Back appears only in the floating bottom navbar, never in the top navbar. Android system Back remains available. Offline is /settings/offline; its Finance, Inventory, Tasks and Calendar details are /settings/offline/<module>. They do not add body title/back bars, nested AppBars or another top safe area. Their scroll content reserves the shell-provided bottom padding, so the floating dock clears the last actionable row. Pushed destinations return to the screen that opened them; direct links fall back to their Settings parent. Settings → Edit profile, opened from the Account group’s profile row, is the one place for account and profile settings at /settings/profile: Identity (display name, full name, email with any pending change), Avatar (Photo, Remove avatar and a Cover banner row that adds, changes or removes the banner), Account (Manage accounts at /settings/accounts, Sessions and devices) and Account status, as captioned grouped cards with the shell title “Edit profile”. Its identity card is borderless with a circular avatar, matching the Settings profile row, and an unknown join date is omitted. Manage accounts appears only here; the root has neither a You row nor a Manage accounts row, and its group caption is General. Legacy /profile/edit and /profile/accounts links redirect to those destinations. /profile retains the Overview/Timeline activity surface. Its edit entry is a compact icon with an accessible Identity label and tooltip. Account-switching shortcuts remain available there. These defaults apply in both mobile languages; workspace permissions and queued profile writes retain their existing rules. Profile identity fields use the shared Settings tiles in grouped cards, with read-only values until a field is opened for editing. Manage accounts uses the same grouped Add account row and account panels; its shell title is not repeated in a hero card. The Profile account-management entry has one label, and What’s new keeps its description and installed version without repeating the shell heading. Account removal confirmations and queued profile writes are unchanged. These defaults apply to both languages, light/dark themes and enlarged text. Avatar removal in Settings → Edit profile captures the authenticated account when its confirmation opens. An account switch or logout invalidates that confirmation, even if the original account returns before confirmation. Removal uses the existing avatar DELETE and offline queue contracts, with the original actor bound through queue admission and HTTP dispatch. Denied removals show localized media recovery; only an explicit Remove avatar action retries. A confirmed removal reloads the profile and persists the returned avatar state. Banner upload/removal and storage policy retain their existing contracts. profile_avatar_removal_test.dart covers confirmation lifetime, cleared-avatar reload/persistence, and EN/VI recovery. profile_media_actor_race_test.dart covers queue/cache actor changes and HTTP failures without automatic retry. These tests use synthetic actors and storage; authenticated device and real storage verification remain separate gates. Licenses, onboarding replay and explicit admin edit forms intentionally open above the shell on the root navigator with their own full-screen chrome. Sheet editors retain their existing modal presentation. They never stack a second navbar within a shell body. Home Agenda, Profile Overview/Timeline and Calendar Agenda reclaim the dock’s bottom scroll clearance while it is hidden, retaining the physical safe area. The viewport remains full height; reverse scrolling or idle restores the dock and its clearance. Other screens keep stable clearance by default. Text Assistant publishes a lifecycle-scoped composer/action slot into the same shell-owned floating dock used by every root and detail destination. The material stays mounted as navigation and prompt content change; width and root bodies animate independently, with only the current dock controls interactive. No page mounts a second dock. Reduced motion disables transitions, and a focused composer remains visible above the keyboard. Draft controllers stay with the cached Assistant page, while disposed publishers cannot overwrite a newer registration. Text immersive mode retains the same composer and navigation toggle, including when entered through an Assistant tool. Live keeps normal navigation while idle or connecting; only connected call controls replace it, retaining the navbar width and the same shell material. While no workspace is resolved, shell navigation remains available. Shell profile reads and cache mutations are fenced by current actor and request generation. Account changes, logout and newer edits reject late results; cache writes and clearing remain ordered. Feature-level identity guards also remain. Regression coverage: settings_detail_shell_checks.dart exercises actual Offline registrations, inherited background/header and dock clearance, enlarged text, system/dock back without a top Back button, and unknown module links; profile_overview_shell_test.dart covers the icon edit entry and return path. floating_shell_dock_test.dart verifies hidden clearance and stable viewport; shell_assistant_composer_test.dart verifies one dock, draft/focus and Live transitions, and shell_profile_races_test.dart covers delayed account/cache completion. These widget checks do not establish installed-device or production evidence.

Floating dock layout

Back is a 52dp button at the leading edge of the floating navbar, inside its shared material. The frame fills the phone width within safe-area margins and centres at up to 480dp on portrait tablets. The page action moves to the top bar when its dock slot would reduce the number of visible destinations. Expanded windows keep Back and section destinations in the leading rail. Root destinations have no Back unless the page registers an in-place Back handler. System Back and deep-link fallbacks use the same route handling. Five destinations show icons only, with localized accessibility names and tooltips on touch and hover. A sub-shell with more than five sections shows Back, four sections and More, which opens a bottom sheet with the remaining sections in order. Back and the trailing page action each have their own space outside the destination count. Narrow windows can fold extra destinations into More sooner to preserve 44dp targets. The More slot is selected when its sheet contains the active destination. Shorter docks show labels where space permits. The rule also applies to page action groups, such as the Mail reader. The selection pill, Back, and each slot’s ink and focus outline share the dock’s outer radius minus its inner padding. The More sheet uses its own inset radius for rows and clips its handle to fit its height. Both appearances use the same geometry. Navigation and the Assistant composer share one dock material that stays the same element as their content swaps, so the dock never flashes; the composer takes the full row while the zones step aside. While a sheet or dialog on the shell navigator is open, the dock slides and fades away and the overlay pads only for the system safe area; it returns as the overlay starts closing. An overlay that places its own action in the dock, such as an in-sheet search, keeps the dock. Reduced motion settles every dock transition immediately; pushes and pops cross-fade (see Push and pop). Switching root destinations retains one dock while bodies ease between tabs. Only the active body receives pointer input or semantics. Visited tabs remain mounted, preserving drafts and scroll positions. Every other newly opened route starts at the top, including a page the router reuses for another location of the same path (another wallet or board). The top bar’s scrolled-under separator follows the visible page: hidden at the top, restored with a revisited tab’s retained position, and never carried over from the previous route (shell_route_scroll_test.dart). Content scrolling under the top bar shows one hairline and no shadow. When page chrome such as the Calendar week strip or the Tasks timeline range sits between the bar and the scrolling content, that hairline marks the bottom of the whole composite header, never the edge between the bar and the strip. Ambient appearances keep their clear or frosted header without it (floating_shell_dock_separator_test.dart). Coverage: shell_dock_bar_test.dart (in-bar Back, overflow, sliding highlight timing), dock_action_choreography_test.dart, persistent_shell_dock_test.dart, floating_dock_rail_test.dart, shell_dock_modal_visibility_test.dart, shared_navbar_large_text_test.dart, shell_back_navigation_test.dart and shell_assistant_composer_test.dart.

Push and pop

Opening a page inside the shell, by push or by go, slides only its body; the shell’s chrome stays in place and changes on the same 220ms timeline.
  • The new body slides in from the end edge with the emphasized curve Cubic(0.2, 0, 0, 1). The covered body moves a quarter of the width towards the start edge and dims slightly.
  • The top bar title fades out over the first 90ms with a 12dp slide towards the start edge. The next title fades in from 70ms, arriving 16dp from the end edge.
  • Destination and action-group contents fade out over 0-90ms, then the next contents fade in over 90-220ms. Back keeps its position and touch target. When both pages have a dock action, the circle keeps its material and only the icon changes. A circle entering or leaving changes the width available to the navigation slots.
  • A pop runs the same timeline in reverse. Back from the dock or the system button usually replaces the page rather than popping it; that arrival still plays as a pop, with the leaving page sliding off towards the end edge.
  • The iOS edge swipe scrubs the body with the finger and settles from the release point. The title and dock contents scrub with it only when the page below is the one the shell showed before this page; otherwise they keep this page’s chrome during the swipe and change at once when the pop commits. The swipe is off while Back at that page runs the shell’s own handling: a page’s registered Back, an open sheet or dialog, or a deep link’s Back route.
  • Root destinations, sibling destinations of one mini app, and a change of location within one route pattern (another board or wallet) swap in place without this transition.
  • When both pages have the same dock action, the circle does not change. A dock action that is not an icon button changes through the circle’s own hide and reveal.
  • Reduced motion (the system setting or Appearance) slides nothing: body, title and dock contents cross-fade together in 100ms, linearly.
  • Every pushed page paints a backdrop beneath its content, so the page it covers never shows through while it slides. Solid appearances paint the page color. Ambient appearances paint their gradient or blobs only while the page moves, fixed to the screen so they meet the app-wide layer under the header and beside a rail without a seam; at rest the app-wide layer shows.
  • A page a mini app pushes inside its own navigator without changing the location (the Mail reader, a Drive file preview) registers its own Back: the dock, system Back and the iOS edge swipe close it to the list beneath, which keeps its scroll position. Only the current page closes; a second Back while it closes does nothing, and its Back retires with it (mail_shell_back_test.dart). Such a page draws no bar of its own: the shell’s top bar shows its title, such as a Drive file’s name, and the list beneath retires its own dock actions and chips while it shows.
  • Back from a page opened from Notifications returns to Notifications, ahead of the page’s own list. A shell root (Home, Assistant, Apps, Notifications, You) keeps its own Back; any other page does not, a mini app’s sections and an app pinned as a tab included. A Mail message opened from Notifications returns there in one Back. A page’s own layer still closes first: a task opened from Notifications closes its sheet on the first Back, and the next returns to Notifications. The edge swipe is off while Back returns to Notifications. A cold-start deep link, which has no history, returns to the item’s list (Mail: the inbox) (shell_route_transition_shell_test.dart, mail_shell_back_test.dart).
Shell routes are ShellTransitionPages (shellTransitionRoutes). The route reports its animation to the shell’s ShellRouteTransitionController, and ShellRouteFade points opacity and paint-offset layers at it. Frames retarget those layers only; neither the title nor the dock contents rebuild per frame. Coverage: shell_route_transition_test.dart (unchanged dock geometry at 0, 70, 140 and 220ms on push, pop and Back arrival; title and contents opacity windows; reduced motion; a half back-swipe; no per-frame dock rebuilds) and shell_route_transition_shell_test.dart (the real shell: chrome timing on a go between flat pages, swipe-pop history, instant root, sibling and same-pattern moves, a navigation during a pop, and no swipe over a registered Back).

Dock action groups

A page whose own actions lead the screen, such as the Mail reader, registers a dock action group (ShellDockActionGroup through ShellChromeActions .actionGroup). While the page is shown, the group takes the dock’s pill and its action circle; Back keeps its position and the shell navigation returns as soon as the page leaves.
  • The pill holds the group’s actions in order as momentary buttons, with the same label rules as destination slots. The shell appends More whenever the group has More sections.
  • At most five slots show, none narrower than 44px; actions that do not fit fold, in order, into the first More section.
  • The circle holds the group’s primary. Any pill or More entry with the primary’s id is left out, so nothing appears twice.
  • More opens the shared sheet with the group’s sections, separated by a hairline. Rows are actions or a choice row with a segmented control, which applies at once and keeps the sheet open. Destructive rows use the destructive token. An action row closes the sheet before it runs.
  • The dock hides while the sheet is open and returns as it closes.
  • Disabled entries show but do not act, and announce as disabled.
  • An overlay that places its own action in the dock takes the dock over the group. The newest registration for a location wins, so a pushed page’s group replaces the one beneath until it pops.
Coverage: shell_dock_action_group_test.dart.

Root destinations

The root dock and tablet rail use Home, Apps, Mira, Alerts and Profile in that order. The root dock has five icons. The legacy shell-dock-root-tabs-v1 pin preference stays on the device so older app installs can restore the layout on downgrade. Apps contains Tasks, Calendar, Mail, Finance, Drive and Timer when those modules are available. Profile contains Settings and account switching and management. Opening a module retains the launching tab as its Back destination. shell_root_tabs_test.dart covers the fixed order, accessible icon names, legacy preferences, workspace trigger placement and Back geometry at 390dp and 834dp. shell_dock_bar_test.dart covers choosing an overflow destination.

Workspace picker

Home and Profile provide the active-workspace picker in their top bars. The 44dp control shows the current workspace avatar and announces its name. When no workspace is selected it shows a workspace icon and opens the same picker. Settings retains the separate default-workspace and hidden-workspace controls.
  • The selected workspace (the current one, or the default in the default workspace picker) is the checked first row. The rest follow in one list by recent use, then in the listed order.
  • Recent use is kept per account and per device under workspace-recent-ids-v1:<account id>: up to 12 workspace ids, updated on every switch. Nothing else is stored, and another account never sees it. Signing an account out or removing it from the device deletes its list, and signing out of every account deletes all of them. Switching accounts keeps each list.
  • Paid tiers carry a small outlined marker (Pro, Plus, Enterprise); Free has none.
  • Create workspace and Manage workspaces are plain rows after the list. Create is disabled with the limit message when the workspace limit is reached; Manage opens the visibility sheet and is not shown in the default workspace picker.
  • A filter field appears only above 8 workspaces, and then the sheet opens tall; otherwise it fits its rows. Tapping a row switches and closes the sheet.
  • The hidden-workspaces list (Settings > Hidden workspaces) uses the same sheet with restore actions and no Create or Manage rows. The normal picker never exposes hide buttons.
Coverage: workspace_picker_sheet_test.dart (checked first row, recent-use order, tier marker, filter threshold, switching, default mode, Create and Manage rows, limit, loading and preference failure, hidden restore, long lists, large text) and workspace_recents_test.dart (ordering, the per-account store and recording on switch). Leaving Apps or launching a module clears Apps search so returning starts in navigation mode. Native dark launch backgrounds match the actual app theme, checked by native_splash_theme_test.dart; the locked screen shows only the lock status and unlock action. Device visual, transition, and keyboard checks on the exact CI-built artifact remain required.

Notification navigation and refresh

Mobile Notifications keeps its scoped snapshot visible while revalidating on entry. Concurrent unread badge refreshes share one awaitable request; the visible feed owns its push listener, and count-only changes do not rebuild page rows. Unchanged counts do not serialize the retained feed again. Workspace switches clear the visible feed and reload the selected tab; responses from an older workspace or actor cannot replace current reads. Pagination and offline pending read overlays retain their existing behavior. These defaults apply to the native Inbox and Archive; the sheet also updates its unread header. Empty and error messages use a minimum height rather than a fixed height, so narrow screens and enlarged text can wrap without clipping. The real 320px root transition matrix in shell_assistant_composer_test.dart covers this responsive empty-state path. notifications_cubit_test.dart covers coalescing, retry, delayed scope responses and close safety. Focused tests establish request behavior, not a measured device frame-time improvement. The persistent notifications action button coalesces unread refreshes only for the same signed-in actor and workspace. An account transition clears the badge, retained feeds and pending state before starting a new request, including a switch away and back in the same workspace. Delayed old requests cannot replace the new count or end its loading state. This applies to the native shell action button and shared notifications cubit; delayed-actor and same-workspace ABA regressions are in notifications_cubit_test.dart.

Settings > Apps: one home for app settings

Every native app’s settings live in Settings under a captioned Apps group. Each row shows a summary of current values and opens that app’s settings. This applies to both mobile languages, all themes and enlarged text. Each setting has exactly one editor and keeps its existing storage, scope cancellation and permission gate. Rows appear only when the app is available. Timer appears when its opt-in experiment is enabled. Mail requires mail discovery and a workspace. Assistant requires a signed-in account and a workspace. The registry does not grant permissions or invent settings. Device-wide preferences stay at the root: Appearance and language, Time zone (personal and workspace), and Notifications and interaction (reminders, haptics, link browser). Tasks, Calendar, Finance and Timer render as routed sub-screens in the shell with one top title, dock Back and dock-clearing scroll. Offline module pages link to the app sub-screen instead of repeating its editors. The app sub-screens link back to their offline data. Mail and Assistant keep their account-scoped hubs, which an account or workspace switch cancels.

Appearance follows the account

Appearance (theme, accent, background, surfaces, interface style, density, corners and reduced motion) follows the signed-in account across devices. It is stored in user_configs as MOBILE_APPEARANCE through /api/v1/users/me/configs, and cached per user so it shows at launch and offline. Resolution order: the device override, then the account, then the default. Seeding happens once per device: the first account bound after the upgrade receives the device’s existing look, only when one exists and the override is off (appearance-seed-consumed records it). Later empty accounts show the default and write nothing until the user edits. One switch on the Appearance page, Use different appearance on this device, keeps this device on its own look. Turning it on keeps what is showing, and turning it off shows the account’s values again. Signed out, or while an account still awaits MFA, only the device’s look shows, so a previous account’s look never leaks. Light/dark mode and haptics stay device preferences. Uploads run one at a time per user, and the newest local choice is always sent last. A choice stays pending until the server confirms it with nothing newer queued, and unsent choices retry on the next launch or sign-in. Coverage: test/features/settings/cubit/theme_account_appearance_test.dart and the Appearance checks in settings_compact_navigation_test.dart. Summaries state the current value rather than repeating a title: Tasks reads “Board view” or “Board list”, Finance “Amounts shown” or “Amounts hidden”, and Calendar the effective first day. Each sub-screen group has a footer naming the scope it changes: this device (Tasks board, Finance amounts, Pomodoro, offline data), your account (first day of week) or the whole workspace (approval threshold, calendar accounts). Calendar also links to the shared Time zone group on the Settings root. The approval threshold editor uses grouped rows: a Require approval switch, inline day and minute fields and a footer explaining both. A threshold write is queued when offline and still reports success. The saved threshold and grace period are therefore published into the cached workspace settings that Timer and Requests read. A reload shows the saved value, not the previous one, and live revalidation later replaces it with the server copy. Overlapping saves apply in the order they were made. In-app entry points use the same editor. The Timer gear and the Requests gear deep-link to Apps → Timer. On return, Timer reloads Pomodoro lengths and Requests reloads its threshold and permissions for the same workspace. The Mail gear opens the current mailbox in the shared Mail editor. The Mira menu opens the shared Assistant settings route at /settings/apps/assistant. These stay contextual on purpose:
  • quick toggles that edit the same stored value, such as the Finance eye action;
  • the layout editors of their own surfaces, Home customize and Apps arrange;
  • per-entity settings, such as a Meet room, a chat conversation’s model and a habit tracker.
Routes and redirects:
  • /settings/apps and unknown or hub-only app ids, such as /settings/apps/mail, redirect to /settings.
  • /tasks/settings, /calendar/settings, /finance/settings and /timer/settings redirect to the matching sub-screen. They are registered ahead of the app registry’s parameterised routes, so /calendar/settings is not read as the /calendar/:eventId detail. The app does not register a /tasks/:taskId route.
  • Web and app links of the form <workspace>/settings/apps/<app> and <workspace>/<app>/settings, plus the Tasks host’s <workspace>/settings, resolve to the same locations.
  • /settings/preferences still redirects to /settings, and existing Settings routes are unchanged.
Settings search is the Settings root’s primary floating dock action, not an inline field. Opening it turns the shell’s top navbar into the query field, and results replace the root list, Account group included. Search matches titles, sections and the settings on app sub-screens, ignoring case and Vietnamese diacritics, including decomposed input with combining marks. A result for a routed destination opens it. A result for an inline root row clears and closes the search and scrolls that row’s group into view. Isolated previews without the shell chrome registry keep an inline field as a fallback. Settings and Offline search retain the floating dock above the keyboard; dock and system Back clear and close search before leaving the destination. Coverage:
  • settings_apps_checks.dart covers the Apps rows, sub-screens, renders and search, including the dock search action and its light/dark renders.
  • timer_app_settings_test.dart covers the threshold permission gate, workspace switch, Pomodoro persistence, the cache write-through and focus=threshold.
  • time_tracker_threshold_cache_test.dart covers offline reads of a queued threshold through the same cache keys the repository uses.
  • time_tracker_settings_entrypoint_test.dart covers the Requests gear deep link and reload.
  • app_settings_routes_test.dart covers redirects, deep links and precedence in the real app router.
  • settings_search_test.dart covers folding and matching.
  • profile_page_test.dart and profile_page_render_test.dart cover the Edit profile groups and renders.

Calendar settings offline behavior

Week-start and time-zone preferences restore encrypted account/workspace snapshots, then revalidate in the background even when the snapshot is fresh. Leaving an account or workspace clears its visible preference; reconnect and app resume refresh the active scope. A failed save preserves the last confirmed selection and shows a localized recovery action. These settings do not queue writes: their PATCH contract currently has no operation receipt or revision precondition. Offline editing and cross-device conflict resolution remain pending API work, rather than silently reporting success. Coverage is in calendar_settings_cache_test.dart, calendar_settings_offline_test.dart and timezone_settings_offline_test.dart. Calendar and Timezone refresh on entry, scope changes and app resume rather than every unrelated outbox cycle. Known preferences remain editable during refresh; a save fences the obsolete read. Stored week-start values are validated before restoration. Offline Calendar and Timezone writes remain a follow-up requirement; this cache layer does not claim queued edits.

Mail settings offline behavior

Mail account rows and mailbox settings restore an encrypted account/workspace snapshot before background revalidation. Long addresses wrap within their row. Save belongs to the floating navbar, and unsynchronized changes remain visibly queued or require review until acknowledged by the server. Cached mailbox roles never grant editing. Restored settings open immediately in read-only mode until current-session membership can be verified. A previously verified editor can queue an offline edit; an uncertain send retains its original operation identity for manual review. Before a queued settings PATCH leaves the device, its manual-review state is persisted. An interruption therefore cannot automatically resend it after restart; an interruption before actual transmission also conservatively requires review because the API has no operation receipt. Settings use a separate outbox scope, including legacy retained records, so a held settings write does not hold inbox actions. Saves send changed top-level fields only; nested automation and group policies remain complete objects. A sender-name edit preserves an unrelated web signature change, but concurrent edits to the same field or policy still use the server’s existing last-write-wins contract. No revision precondition is claimed. Server-setting controls stay read-only while that mailbox has an unresolved edit, including when reopened, and until a fresh response installs the next confirmed baseline. Retry after a mailbox denial requires a fresh owner/admin management grant; cached roles never restore editing. Failed edits do not overlay confirmed settings. A mailbox settings 403/404 removes only that mailbox’s snapshot; workspace bootstrap denial still revokes workspace Mail. Authorization denial removes the affected snapshot; a verification challenge retains it without granting new management access. Refreshes preserve dirty form values. This behavior is covered by mail_settings_cache_ui_regression_test.dart and mail_settings_offline_regression_test.dart. Restart and in-flight Retry fencing are covered by mail_settings_dispatch_restart_test.dart.

Assistant settings layout

Mira’s settings action and Settings → Apps → Assistant open the same routed screen at /settings/apps/assistant. The shell keeps its destination title, background and floating bottom navbar; the screen adds no inner navbar. Nested personality and memory editors also stay routed, with Save in the shell dock. Editors explicitly retain the dock above the keyboard, including disabled or pending Save actions, so Back and Save remain reachable while typing. Other destinations retain their keyboard visibility policy. Back closes a custom explanation dialog before returning through the editor history. Standalone previews without shell providers retain fallback chrome. Personality restores only a verified actor-owned snapshot from the existing Assistant cache while revalidation runs. Personality editors remain read-only until fresh settings succeed, including after a failed refresh. An offline snapshot never enables an unknown memory-consent setting; unresolved consent shows progress during loading. Memory items, consent changes and revisioned memory edits remain authoritative network operations; full personality saves are not queued without a matching receipt contract. Cache and generation fences are covered by assistant_personal_settings_cache_test.dart and assistant_personal_settings_cache_first_test.dart. On-device models use compact rows with size and download/selection status. Installed rows expose Remove directly and distinguish Use from selected status. License and source actions live in custom explanation dialogs. Existing preference, memory consent, selection and download semantics remain unchanged. This scope applies to English and Vietnamese, including enlarged text. assistant_settings_dock_route_test.dart covers action lifecycle, blocking repeated or covered saves, and dialog Back. assistant_routed_editors_test.dart verifies Back and Save at 320px, doubled text size and an open keyboard. Compact rows are covered by assistant_compact_settings_models_test.dart; real caller-to-editor paths and EN/VI coverage remain in settings_compact_navigation_test.dart. Native acceptance requires an authenticated device running the exact CI-built artifact.

Native text editing and keyboard dismissal

Across mobile routes and modal forms, editable fields keep their native copy, cut, paste and select-all actions while the keyboard is visible. Tapping a selection toolbar, selection handle or a TextFieldTapRegion accessory keeps editing focus. A genuine outside tap dismisses the visible keyboard through Flutter’s EditableTextTapOutsideIntent. Dialogs that consume the inherited keyboard inset still recognize the visible keyboard from the view. A field’s explicit onTapOutside callback retains control of its behavior. The task interaction dismissal guard still suspends outside dismissal. Without a visible keyboard, the existing focus policy is delegated to Flutter, including mouse and stylus outside dismissal. Shadcn text fields and areas explicitly pair the platform menu builder with native handle-only selection controls. Android and iOS retain draggable selection handles; desktop keeps its platform handle policy. The device-name and QR-link inputs use the same native editing controls. Workspace search already uses a native Material field. This applies to Material fields and shadcn fields and text areas, including the Assistant composer and settings forms. Disabled fields remain disabled, read-only fields allow selection and copying without mutation, and obscured fields retain Flutter’s restrictions on copying and cutting. Input formatters and IME composition remain owned by the field. Regression coverage lives in test/app/view/text_editing_*_test.dart and dismiss_keyboard_on_pointer_down_test.dart. It exercises real clipboard menu press/release gestures with a frame between pointer down and up, Android/iOS, English/Vietnamese, single and multiline inputs, modal and enlarged text, selection replacement, keyboard shortcuts, field policies and composition. Widget evidence does not replace native-device clipboard and IME verification.

Private error diagnostics

Mobile Mira reply failures and timezone read/write failures offer Copy debug information only to an authenticated account with a confirmed @tuturuuu.com email. External addresses, unconfirmed addresses and MFA-required sessions do not see this control. Email/confirmation changes update auth-state equality; logout and account changes revoke the control and its stale callback. Copying writes a local, fixed-field envelope to the clipboard: operation stage, error category, HTTP status, retry delay and allowlisted rate-limit policy fields. It never includes messages, prompts, response bodies, URLs, email addresses or credentials, and never uploads diagnostics. Retry and cooldown rules are unchanged. Recovery clears old diagnostics; timezone actor/workspace changes discard them. Streamed HTTP errors retain at most 64 KiB before parsing. Error-body reads have a total deadline matching the request timeout (30 seconds by default), even if small chunks keep arriving. Deadline, source failure or overflow requests source cancellation and discards partial payloads while preserving HTTP status and headers for typed errors; transport cleanup cannot delay that result. Logout or actor departure during this read cancels it and rejects publication, including a return to the same actor. Successful streams keep their existing lifetime. Oversized bodies are canceled and become generic status failures; status/retry headers survive. Successful streams remain unread until consumed by the assistant transport. Coverage: safe_error_diagnostics_test.dart, api_client_stream_error_test.dart, bounded_stream_error_test.dart, stream_error_deadline_test.dart, internal_diagnostics_copy_test.dart and timezone_safe_diagnostics_test.dart. These tests establish local capture, clipboard privacy and cooldown behavior; they do not establish the cause of a production 429 or stopped reply.

Component localization fallback

The mobile app supports English and Vietnamese. App and Material strings keep the selected language, including native text actions. The installed Shad component library supplies English resources only, so its built-in control strings use an explicit English fallback in Vietnamese sessions. This does not expand the app’s supported locales or claim those component strings are translated. The shared widget-test app uses the same production delegate. Coverage: shadcn_localizations_fallback_test.dart renders the actual Shad date picker and Material/app strings in both locales without missing delegates.

Compact settings sections

General and product settings share one rounded card per group, with inset separators and unboxed line icons, rather than a separate outlined card for every action. On solid pages, the card is a quiet tonal step from the page background that keeps muted text at WCAG AA. Over a gradient or blob appearance, the card is translucent at the chosen card opacity. Edit profile uses the same captioned groups; its cover banner keeps its preview panel, and explicit destructive confirmations retain their grouping. Preference categories use one consistent gap between groups and no trailing group gap; the parent owns spacing to the next section. Row touch targets remain at least 48 logical pixels, while translated labels and enlarged text may increase height. These defaults apply to mobile English/Vietnamese and light/dark themes; settings permissions, destinations and persistence are unchanged. Assistant settings leaves use the same shell and row vocabulary. settings_design_checks.dart exercises the actual Settings host spacing and 320px enlarged-text navigation in both languages/themes. Its harness uses the production localization fallback and explicit theme/locale. Widget renders are bounded evidence; exact-build device safe-area, keyboard and visual checks remain required. Preferences observes the active workspace id, and Overview observes its displayed name. Workspace loading, module visibility and creation state do not rebuild these sections when those values remain unchanged. Renames update the workspace row; workspace switches retain calendar preference loading and permission revalidation. Other Settings data sources retain their subscriptions, and compact spacing, row alignment, editing and persistence keep their existing behavior. settings_rebuild_test.dart observes real widget rebuilds after synthetic workspace state emissions, with rename and workspace-switch controls. This isolates unnecessary subscription work; it does not measure frame latency or establish a TestFlight performance improvement.

Settings sub-page forms

Settings sub-pages (Mail, Offline modules, Feedback and per-app screens) share one template: the shell navbar carries the title, the dock carries Back, and the body is captioned SettingsCompactSection cards separated by the group gap. Inside a card, on/off settings are SettingsSwitchRow (the whole row toggles), single choices are SettingsChoiceRow (current value at the end; opens the shared option sheet from showAppSelectSheet), and free text is an AppTextField or AppTextFormField padded by SettingsFieldRow. Fields keep their visible label above the outline, a placeholder that gives an example rather than repeating the label, helper text for format or privacy notes, and the counter when a length limit applies. Primary actions use AppButton.primary; there are no underline-style Material fields.
  • Mail groups Reading (remote images, default action, swipe actions), Sender and signature, AI drafts (auto-draft and draft instructions), Delivery and routing, Group permissions and Organize. Field order and saved keys are unchanged.
  • Offline modules show a Stored on this device card: storage used with queued changes, then one row per collection with its item count, a readable size (“870 KB”) and a localized update time. Each row opens the stored item browser. Snapshot counts, payload bytes, server totals and the coverage and measurement caveats stay under a collapsed Technical details section. Collection names are derived from the cache namespace and are not translated.
  • Feedback has Subject and Details fields, a Screenshot (optional) row with the accepted formats and size, and a primary Send button.
Every text input in the mobile app shows a localized placeholder while empty. test/core/ui/input_placeholder_audit_test.dart scans lib/ and fails on an input constructor without placeholder:, hintText: or hint:. A deliberate exception, such as a single OTP digit cell, carries an // input-placeholder: exempt <reason> comment inside the call. Coverage also includes settings_forms_render_test.dart (Feedback and Offline in English and Vietnamese, light and dark), offline_module_page_test.dart and the Mail settings regressions.

Handled timezone operational failures

Mobile timezone diagnostics distinguish preference load (timezoneRead), API write (timezoneWrite) and unresolved native timezone after a successful write (timezoneResolve). A genuine handled HTTP 429 records its status and bounded Retry-After bucket once, while preserving the existing cooldown, failed edit and explicit retry. A cooldown-blocked tap, logout, closed cubit or superseded ABA request does not create an incident. Native lookup that is unnecessary for a named preference also creates no incident. The production Crashlytics boundary follows the fixed-field privacy and bounded dedup defaults documented in mobile chat. It excludes timezone values and actor/workspace identifiers. Tests can inject a sink without Firebase. Sink rejection leaves existing UI failure and retry behavior intact. timezone_operational_reporting_test.dart exercises genuine HTTP 429 responses through the authenticated API client and repository with synthetic credentials, separate read/write phases, cooldown/recovery, stale requests and sink failure. Native authenticated provider/device evidence remains pending; this does not identify the cause of any customer’s 429.

Timezone pickers and sheet Back

The Personal timezone and Workspace timezone rows open a large sheet built on the shared sheet host (showAppSheet). It shows every supported zone by city, with its region and current GMT offset (for example, “Ho Chi Minh · Asia · GMT+7”). Zones are sorted west to east. The saved choice is pinned under Current with a check mark. Automatic explains what it means:
  • Personal: it follows the workspace timezone, or this device’s when the workspace has none, and names the zone it resolves to now.
  • Workspace: members without a personal timezone use their own device’s.
Search is the floating dock’s dynamic search action. It turns the shell’s top navbar into the query field, and the sheet has no inline search field. The query matches city, region, IANA id or offset (gmt+7, utc-5, +05:30). System Back, the dock Back and dragging the sheet down all close the picker without saving, and the user stays on Settings. The same rule applies to every sheet or dialog opened through showAppSheet, showAppDialog or showAdaptiveSheet: Back closes the topmost overlay first and never pops the page beneath. Saves, rate-limit cooldowns, permissions and the account/workspace cancellation of an open editor are unchanged. These defaults apply in English and Vietnamese, light and dark, and enlarged text. Coverage: settings_timezone_picker_checks.dart, app_sheet_host_test.dart and timezone_choices_test.dart.

Settings overview and Appearance

The Settings overview opens with an Account group instead of a header. Its rows are the profile (avatar, display name and email; opens /settings/profile), the current Workspace (its name; opens /settings/workspace) and Hidden workspaces. There are no standalone Edit profile or Workspace buttons and no separate workspace counter: every account destination is an ordinary grouped row. The root shows no social counts or invented destinations. The shell keeps the single top-navbar title and the floating dock Back control; the page adds no large in-body title or back chevron. Root preference rows still open nested editors and save only an explicit choice. The no-root-switch decision recorded in apps/mobile/docs/settings-calendar-timezone.md remains, so Settings shows no inline toggles at the root even though the visual reference does. The Appearance row opens /settings/appearance. That is a child page, and its controls apply and persist instantly because choosing there is the explicit action. Visiting the page and returning writes no appearance preference. Until a user first opens Appearance, its root row shows a “New” chip. Opening it from that row features Aurora with a “New” chip in the gallery (/settings/appearance?highlight=aurora). Any visit, including a deep link, retires the chip through the appearance-intro-seen preference. Aurora is listed first in the gallery; whether fresh installs should default to Aurora is an open product decision.

Appearance options and defaults

Classic dark (Neutral accent, Solid background) returns the original shad and Material themes. Classic light uses an iOS-style grouped page: a #F2F2F7 page with white cards and darker muted text (#5E5E66) that stays AA on the tinted page. Gallery swatches always show each theme’s gradient or blobs at full intensity, so dark Classic, Mono and Ember remain distinguishable. Picking a theme in the gallery also applies its recommended background style: Aurora, Forest and Blossom use Blobs; Sunset, Ocean, Ember and Mono use Gradient; Classic uses Solid. Reset to default restores every option, including System mode. Curated colour values live only in lib/core/theme/appearance/appearance_palettes.dart. AppearanceTheme derives the shad colour scheme and the Material bridge theme from them; widgets use theme tokens. Foreground, muted, card and popover text keep WCAG AA (4.5:1) against any blend of each theme’s base, gradient, blob, card and subtle-surface colours, in light and dark. Primary (accent) and destructive colours are derived per theme: each is stepped toward black or white until it reaches 4.5:1 against that worst-case blend. Labels on primary, secondary, accent and muted fills, and Material onError/onPrimary, also reach 4.5:1. Non-neutral accents also drive Material primary/secondary/tertiary containers and surface tint, so chips, FABs and indicators follow the accent. AppearanceBackdrop also installs accessibleDestructiveButtonTheme for every appearance. shad’s built-in destructive button paints a fixed white label on a 50% destructive fill (about 2.5:1 on light pages). The override uses the theme’s solid destructive fill with the labelOn label instead, so it reaches 4.5:1. Hover and press shift the fill slightly toward the label without losing AA, and disabled buttons keep shad’s styling. Default Classic dark uses the base scheme, so its destructive buttons also change from a translucent to a solid fill. Segmented-control labels (Mode, Background) scale down to fit rather than truncate.

Interface style options (planned)

The default interface looks the same on Android and iOS: the Tuturuuu style. A planned Interface group in Appearance lets each user choose: Rules:
  • Stored per device. Choices persist alongside the existing appearance payload and are not synced to the account.
  • Applied through the theme. Choices take effect through theme extensions read via AppTokens; widgets never fork on the platform.
  • Accessibility floors. Compact density never shrinks touch targets below 44pt. Every Style and Radius combination keeps the contrast guarantees above.
  • Reset. Reset to default restores every option.
See the native pass plan.

App-wide application and cost

AppearanceBackdrop sits in the app builder around the router. For Gradient and Blobs, it paints one ambient layer behind every route and makes shad scaffolds transparent, so the theme shows across Settings, root tabs and detail pages. Its child keeps a stable position, so changing styles never remounts navigation. Imperatively pushed Material/Cupertino pages carry their own copy of the layer beneath their content, so transitions never reveal the page below. The shell header is clear on detail routes, so the gradient reaches the title and status bar. On root tabs, where content scrolls under it, the header is frosted (translucent background with an 18px backdrop blur). Solid themes keep the opaque header. Adaptive sheets, drawers and dialogs restore opaque scaffolds. Solid styles add no layer. The layer uses radial and linear gradients, not image blur, inside a RepaintBoundary, so its picture is recorded once. Impeller has no raster cache: the GPU still redraws it every frame, which is cheap for gradients. Animated blobs are opt-in and drift on a 48-second loop driven by a 15 fps timer. Only the painter repaints; no widget above it rebuilds per tick. Motion stops when the system Reduce Motion setting is on or tickers are disabled. The clock stops immediately when the app leaves the foreground and resumes from the same phase.

Frosted glass on Android

Glass chrome (the dock material, the frosted root-tab header, adaptive sheets and dialog scaffolds) goes through GlassEffects in lib/core/theme/appearance/glass_effects.dart. A live BackdropFilter re-reads and re-blurs the content behind it on every frame that content changes. That is every scroll, sheet and transition frame. Each filter also splits the GPU render pass. Android GPUs are tile-based and pay heavily for that, so on Android (defaultTargetPlatform) the same surfaces draw without the blur. Their fill closes 75% of the remaining gap to opaque: dock 0.72 becomes 0.93, header 0.55 becomes 0.89, and sheets and dialogs 0.88 become 0.97. iOS and desktop keep the live blur. High contrast is always opaque with no blur. Shapes, borders, shadows, colours and the ambient layer are unchanged on every platform. Coverage: glass_effects_test.dart asserts the composited BackdropFilterLayer count and fill per platform, and adaptive_sheet_test.dart checks both platforms. The on-device frame benchmark integration_test/perf/glass_effects_benchmark_test.dart compares blurred and flat glass over Solid, Blobs and animated Blobs (flutter drive --profile; see its header). Persistence uses SharedPreferences: mode keeps the original theme-mode key and customization is stored as versioned JSON under appearance-v1. Installs without that key migrate to the default appearance with their saved mode. Unknown or malformed values fall back field by field. Bootstrap preloads both values, so cold start does not flash the default theme. A newer change or closing the cubit fences older pending writes. Slider drags preview live and persist when released. Coverage: appearance_contrast_test.dart checks every rendered text and role pair (including destructive and Material onError) for every theme, background style, brightness and accent, plus the defaults. appearance_application_test.dart checks app-wide application without remounting, pushed-page layers, pixel output for solid, gradient and blob styles, that reduced motion schedules no frames, and that the blob clock stops in the background and resumes. theme_appearance_test.dart covers migration, restart persistence, preview, write fencing, reset and decoding. settings_appearance_shell_checks.dart runs the real shell for Classic light/dark, Aurora blobs and Sunset gradient. It also covers instant apply/persist/reset, reduced and full motion, the New chip and Aurora highlight, the one-line workspace stat, 320px pages at 2x text in English and Vietnamese, and screen-reader activation of theme tiles and accent swatches. appearance_root_tabs_render_test.dart renders the Home and Apps root tabs in Classic light and dark Aurora blobs. settings_design_checks.dart covers the row grid. These are widget-level checks. Device visual, battery and frame-time acceptance on the exact CI-built artifact remain separate gates.

Interface style, density and corners

Appearance ends with an Interface group. The default look is the same on Android and iOS. Each choice applies instantly through the theme and is stored with the appearance payload on this device only; it is not synced to the account. Colors and layout do not change with these options, so the contrast guarantees above hold for every combination. Reset to default restores the interface options with the rest of Appearance. Haptic feedback keeps its own preference and is not reset. Components read the options through AppTokens.of(context).interface (AppInterfaceTokens, a Material theme extension) instead of checking the platform. Regression coverage: interface_theme_test.dart covers the payload round trip and fallbacks, radii, density floors, transitions per style and Reduce motion layering. settings_appearance_interface_checks.dart covers choosing, persisting and resetting in the real Settings shell, and a stored choice applying through the shell theme. The existing 320px at 2x text checks in English and Vietnamese include the new group.

Custom controls and modal editors

Appearance, Storage and Offline use the shared design-system controls. Appearance sliders preview immediately and persist on release. Storage opens as a large hosted sheet; its clear confirmation remains disabled during an active download and clears data only after explicit confirmation. Back dismisses the current picker or cancels the confirmation before leaving Settings; outside dismissal also cancels the confirmation. Offline module search lives in the floating navbar. Browsing a stored namespace opens a hosted sheet with its own navbar search and lazily rendered record details. Search scans all locally retained records in that namespace, without fetching the network. An open browser refreshes on a content revision; losing its owning actor, workspace or permission dismisses it. Reopening starts a fresh search. The standalone preview uses an inline search field when no shell is present. Assistant quick settings and the central Assistant entry both open the routed Assistant settings screen. Nested personality and memory editors retain account/workspace cancellation and write fences. System-owned license and permission screens keep their framework or operating-system presentation. Regression coverage: settings_appearance_shell_checks.dart, cache_storage_review_test.dart, offline_stored_items_test.dart, offline_module_page_test.dart, offline_search_chrome_test.dart and settings_assistant_entrypoint_checks.dart.

Reminders offline opening

The Reminders settings screen opens from local per-user preferences and the in-memory reminder service status. Opening the screen does not read Tasks or Calendar or request the network; those caches feed reminder planning during service refresh. No additional Reminders cache or flag-dependent behavior is needed. Explicit refresh and OS scheduling remain separate from opening settings. reminder_offline_open_test.dart blocks network access and verifies persisted settings with offline_read_reminders both off and on.