Settings row grid
Settings sections and detail rows shareSettingsRowLayout. 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 asAsia/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).
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.
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 legacyshell-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.
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 inshell_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 inuser_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.
/settings/appsand unknown or hub-only app ids, such as/settings/apps/mail, redirect to/settings./tasks/settings,/calendar/settings,/finance/settingsand/timer/settingsredirect to the matching sub-screen. They are registered ahead of the app registry’s parameterised routes, so/calendar/settingsis not read as the/calendar/:eventIddetail. The app does not register a/tasks/:taskIdroute.- 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/preferencesstill redirects to/settings, and existing Settings routes are unchanged.
settings_apps_checks.dartcovers the Apps rows, sub-screens, renders and search, including the dock search action and its light/dark renders.timer_app_settings_test.dartcovers the threshold permission gate, workspace switch, Pomodoro persistence, the cache write-through andfocus=threshold.time_tracker_threshold_cache_test.dartcovers offline reads of a queued threshold through the same cache keys the repository uses.time_tracker_settings_entrypoint_test.dartcovers the Requests gear deep link and reload.app_settings_routes_test.dartcovers redirects, deep links and precedence in the real app router.settings_search_test.dartcovers folding and matching.profile_page_test.dartandprofile_page_render_test.dartcover 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 incalendar_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 bymail_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 aTextFieldTapRegion 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 captionedSettingsCompactSection 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.
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.
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.
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 throughGlassEffects 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.