apps/mobile) brings eligible Tuturuuu workspace tools into a
native shell. Its launcher, module availability, background behavior, and device
permissions are separate from the web app’s browser runtime.
Learn by surface
Tasks, Calendar, and Finance are default launcher modules. Meet, Mail, Chat,
and Notes are opt-in experiments documented in the workspace-tools guide.
Turning a module on exposes its eligible launch surfaces; it does not grant
workspace or account privileges. Mail keeps its exact-domain eligibility rule.
Modes (General and Education)
A mode is a display preference for one account in one workspace. It changes what the app puts first and never grants anything: every surface keeps its own permission check, workspace-hidden modules stay hidden, and guests see only what they could already open.- Default: General. Home is unchanged in General mode.
- Resolution, first stored value wins:
- the member’s own choice for this workspace (
user_workspace_configsMOBILE_AUDIENCE_MODE); - the workspace default an admin with
manage_workspace_settingssets (workspace_configsMOBILE_DEFAULT_AUDIENCE_MODE), so a centre can open every member’s phone in Education while members can still opt out; - the account preference chosen in onboarding (
user_configsMOBILE_AUDIENCE_MODE).
- the member’s own choice for this workspace (
- Where to change it: Settings → Workspace → Mode. Admins also see “Default for members”; personal workspaces have no member default.
- Education Home: a “Today’s classes” card leads Home (hideable and
reorderable like other Home widgets). The server decides access: the card is
offered on Home and in the customization sheet only after the sessions read
succeeds, which requires
view_user_groups. A denial removes the card and its stored copy; any other failure keeps the last classes with an inline notice. In General mode the card’s data is never requested. Finished sessions sink below current and upcoming ones, phases update at each start and end, the list reloads after midnight, and states are words, never count chips. - Teacher scope: teachers see only the classes they teach by default, with a “Show all” switch. This is a presentation filter, not a security boundary. Until the consolidated Today endpoint can tell which classes a teacher teaches, the card lists all of the day’s classes and says so (“All classes today”) instead of claiming a filter.
- Offline: the last resolved mode is cached per account and workspace, so the first frame is correct offline. A member’s own choice is queued and replayed (the config write is idempotent); the admin default is online only.
test/features/audience_mode/, test/features/classes/,
test/features/dashboard/view/home_mode_gate_test.dart (General never fetches;
no access means absent from Home and the customization sheet),
test/features/settings/view/settings_audience_mode_section_test.dart, the
onboarding mode-slide cases in test/features/onboarding/onboarding_page_test.dart,
and the Home order case in dashboard_layout_cubit_test.dart.
Offline rollout flags
Mobile rollout flags default to false and are cached per account and workspace. The app refreshes/api/v1/mobile/feature-flags?wsId=<workspace> at startup,
on login, account/workspace changes, resume, network reconnect, and every server
ttlSeconds while foregrounded, clamped to 15–3600 seconds with a 30-second
fallback when no payload is known. The boundary cases are covered by
mobile_flags_test.dart. Backgrounding cancels
polling; resume requests fresh flags. Requests use Bearer authentication
and the cached version as If-None-Match; HTTP 304 retains the payload.
An unreachable server keeps the last known cached values without time expiry;
a cold cache enables nothing. Logout clears all flag snapshots for that account
and fences late responses. Workspace snapshots remain isolated. A server kill
applies on the next successful refresh; losing connectivity does not disable flags.
Unknown keys are ignored. mobile_offline is the master switch: when false,
every offline_* flag is false, including test overrides.
There is zero behaviour change while flags are off for the existing explicit
Finance, Tasks, Calendar, and Inventory downloads. These register with a null
flag. New app preparers register once through
OfflinePreparationCoordinator.instance.registry.register(appKey, flagKey, preparer).
The coordinator requires both the registered flag and master switch before
running a flagged preparer. Existing permission and retention checks still apply.
The web app owns config/feature-flags.json. From apps/mobile, run
dart tool/generate_mobile_flags.dart when that manifest changes, then format
the generated Dart file. The mobile manifest parity test skips explicitly while
the manifest is absent. Reader regression coverage lives in
test/core/feature_flags/mobile_flags_test.dart; registry/coordinator gating
coverage lives in test/core/cache/offline_preparer_registry_test.dart.
Shell and offline expectations
Screens inherit the app shell’s background and single top title/actions bar. On phones and portrait tablets the floating bottom navbar owns in-app Back navigation and scroll clearance. On landscape tablets, laptops, and desktops (width >= 840dp, shortest side >= 600dp) the same destinations, including Back, move to a leading rail and the dock keeps only composers and page actions. Full-screen/system forms have their own shell rules. These conventions keep controls reachable and avoid duplicate headers. Every screen uses the same page gutters, section spacing, and wide-screen max widths. Only calendar, board, conversation, call, and media/map canvases run full-bleed. See the mobile design system. Offline availability is product-specific. Cached data is not proof that an edit reached the server. Review queued/sync states and recover through the owning product’s documented flow. Optional products should not warm private endpoints until access is known to be enabled. Offline status UI is default OFF behindoffline_status_ui; the existing
mobile_offline kill switch remains authoritative for offline capability.
The settings preparation section accepts offlineStatusUiEnabled until the
MobileFlags reader is integrated. With the flag off, its existing UI and behavior
remain unchanged. With it on, app rows show readiness, indeterminate preparation
progress (the coordinator has no per-app percentage), Wi-Fi/retry waits, failure,
unavailability and last sync. Retry and sync timestamps use the device locale and
local time zone. The compact ready count appears only in the existing offline
settings section. These labels describe downloaded snapshots, not server
acknowledgement of queued edits. Regression coverage:
apps/mobile/test/features/settings/view/offline_status_ui_test.dart.
Versions and privacy
The toolchain reference reads the Flutter and Dart constraints and mobile package version frompubspec.yaml. Distribution
artifacts and build metadata establish what a device is running. The browser
bootstrap for Flutter is noindex; it is not a duplicate public marketing site.
The standalone API migration uses a build-number gate at
/api/v1/mobile/version for iOS and Android. The configured minimum supported
build is inclusive; older builds require an update. Missing policy fails closed
with 503. Mobile switches to consolidated contracts during this migration; the
program accepts a temporary compatibility break followed by a forced update.
External non-mobile consumers retain compatibility. The old semantic-version
endpoint remains on the retained Next origin until separately reviewed. See the
API contract and regression coverage.
The API foundation does not itself activate the client screen or production gate.
Developers changing translations regenerate localization before analysis/tests.
Native app work does not require the paused Rust/TanStack Start runtime or the
retired Docker cron runner. Database-dependent test fixtures still need an
appropriate isolated environment; see Without Docker.
Private product feedback
Settings → Send feedback opens an account-scoped form inside the existing shell; the shell keeps its single title and dock navigation. The active platform Web/api/v1/product-feedback route owns submission, not the workspace CRM feedback
store. Native calls use the current Supabase Bearer identity and never send an
authoritative actor id. English and Vietnamese copy ship together.
Ingress retains the shared 512 KiB request limit for every other route/method;
only exact POST /api/v1/product-feedback gets the 2,850,000-byte envelope needed
for base64 image plus bounded text. Both declared and actual streamed bytes are
checked at the proxy and again in the owning route. The regression includes an
old-limit negative control and adjacent-path/method denials.
The default is off: PRODUCT_FEEDBACK_SUBMISSION_ENABLED=true enables text
intake and requires a real Turnstile configuration even in development. Each
explicit dispatch obtains a fresh token. The existing SQL intake owns atomic
actor/network/global quota charges and the content-free idempotent receipt;
unverified forwarded headers do not select a quota bucket. No automatic offline,
Auth-response or challenge-response replay is allowed. HTTP 429 retains
Retry-After; 409 retains the original reference.
One optional PNG/JPEG/WebP screenshot is bounded at 2 MiB of source bytes. The
server validates the actual format, rejects animation and more than ten million
pixels, strips metadata, fits within 1920×1920, and stores at most 512 KiB of WebP.
PRODUCT_FEEDBACK_MEDIA_ENABLED=true additionally requires the additive private
media migration. The wrapper reuses the existing intake transaction and advisory
lock: screenshot and receipt commit together, identical retries do not charge
again, and adding, changing or removing media conflicts. Every Web submission,
including a screenshot-free replay, uses this wrapper. Omitting a previous
screenshot still conflicts when media intake is disabled; missing media schema
fails closed. Small normalized screenshots live in the RLS-protected private media table, one per report; originals, filenames, public
URLs and general-purpose attachments are not stored. This bounded design does
not create a public Storage bucket.
The app freezes an attempted draft and retains its original UUID. Only that
reference is saved in account-scoped preferences; text, images and Turnstile
tokens stay in memory. After restart, recovery is receipt observation only. The
owner-only /receipts/{key} route remains available with submission disabled,
so stopping intake does not prevent recovery. A missing receipt remains unknown
and never starts another POST. An explicit in-session retry uses the same
immutable draft/key with a fresh token. Initial definitive pre-acceptance
400/401/403/413/429 responses allow editing only if no earlier attempt has an
unknown outcome. After a 503/transport uncertainty, a later retry rejection cannot
erase the original key or unlock editing. Only a confirmed receipt resolves that
uncertainty. There is no automatic polling or write replay.
Staff can explicitly open a private screenshot from the Web inbox when both
staff and media gates are enabled. The media route rechecks the current Auth
identity and the existing SQL activated exact-domain staff assertion on each read.
It returns a bounded uncached image projection, with no reporter identity,
storage path or bearer URL. Staff status/archive/revision metadata stays read only.
Regression coverage is in product-feedback-{handlers,service}.test.ts,
product-feedback-private-media.sql, the internal-api feedback tests and
product_feedback_{page,repository}_test.dart. The page tests exercise both
503 and transport uncertainty followed by each supported retry rejection. The
privacy fixture first verifies synthetic camera/GPS EXIF on the input, then
requires the stored WebP to omit metadata. Web replay tests exercise the real
dispatcher against modeled RPC contracts; they do not replace SQL qualification.
The disposable database runner applies the full current migration history before the 17-assertion media packet and type
generation. Run it with
bun run --cwd apps/database sb:validate:isolated --test supabase/tests/product-feedback-private-media.sql --typegen packages/types/src/supabase.ts
through ttr resources run; it owns and cleans a separate temporary Supabase
project. Before activation, require exact-head Web/mobile CI, hosted Auth and
registry checks, real Turnstile acceptance, and device tests for image picking,
account changes, pending recovery, keyboard/dock clearance and enlarged text.
Desktop beta downloads
The same Flutter app ships through the desktop beta channel for Windows x64, macOS, and Linux. The 2026-10-22 policy permits unsigned Windows direct-download installers when both signing secrets are absent. The download page and release notes disclose SmartScreen warnings and checksum verification. Configured signing failures block the Windows package. macOS still requires Developer ID signing and notarization; the Microsoft Store channel is separate. Windows in-app updates retain their publisher-signature checks, so unsigned betas use manual verified-installer updates. Packaging and receipt regressions are covered byscripts/desktop-deployment/windows-signing.test.mjs and
verify-publication.test.mjs; native Windows acceptance remains a release gate.
Windows x64 uses a per-user .exe installer from the official download page or
GitHub desktop release. Unsigned builds may show SmartScreen Windows protected
your PC or Unknown publisher. Verify the release SHA-256 checksum before
using More info → Run anyway, if Windows offers it. Use the web app when
organization policy blocks unsigned installers. See the
desktop installation and signing plan.
Startup recovery and performance inspection
On Android and iOS, optional public model-download recovery starts after the first painted Flutter frame. This moves native transfer restoration and model file checks out of first-frame contention. The owning Settings flow retains initialization failures and retry behavior; other platforms do not schedule this recovery. Required authentication, appearance, encrypted cache and pending mutation restoration still finish beforerunApp.
Regression coverage: test/core/startup/optional_startup_test.dart verifies
paint-before-recovery ordering, one invocation, subsequent frame progress while
recovery is pending, and synchronous/asynchronous failure containment.
For a build-free performance pass, follow bootstrap.dart and
app/view/app.dart separately: unawaited work can still compete with painting,
and provider construction/locale loading happens when the root mounts. Record
asset byte sizes and dependency/native plugin candidates as source measurements,
not installed bundle sizes. Dynamic server icon selection references many
constant glyphs in core/icons/platform_icon_data.dart; retain that contract
when evaluating font subsets. Measure release size and startup timing separately
in admitted CI/device workflows before claiming a numeric improvement.
First-frame critical path
BeforerunApp, bootstrap reads the local preferences (haptics, theme mode,
system chrome, last routes) together with the consent read and gated admission
in TelemetryPreference.instance.initialize, via initializeBootstrapServices.
Both settle before Supabase starts. The overlap never moves Firebase earlier:
Firebase is initialized only through FirebaseAdmission (signed in, and push or
telemetry allowed), so a signed-out launch initializes no Firebase and no FCM.
Consent is read before collection is enabled, and unsent Crashlytics reports are
deleted before it is, in MobileObservability.initialize; only the package
metadata read overlaps the collection switches.
Local-notification setup (PushNotificationService.initialize) and the
signed-in session (startSession, which is where FCM and Firebase admission
happen) start after the first painted frame through scheduleOptionalStartup.
startPushForCurrentAccount reads the signed-in account when it runs and skips
a session an auth change already started before the first frame. Failures are
logged by type only. A notification that launched the app is delivered once the
session starts.
Regression coverage: startup_state_test.dart and
cold_start_firebase_contract_test.dart (no Firebase/FCM before sign-in, slow
or failing Firebase, cold-start notification tap). These are orchestration
fixtures; no device timing is claimed.
Independent startup state restoration
After Firebase/observability handlers and Supabase have settled, bootstrap usesinitializeStartupState to overlap account appearance reads with offline state
restoration via Future.wait. Keep the identity/MFA boundary before appearance,
and keep CacheStore before OfflineMutationQueue in a single branch: a cache
failure must skip queue restoration. Each branch retains its original fallback
or error log with the original error/stack; both finish before routes, builder
and runApp. Firebase and Supabase remain sequential to preserve platform-error
handler coverage during session restoration.
test/core/startup/startup_state_test.dart uses completion barriers to prove
concurrency, both completion orders, queue ordering, sync/async cache and queue
failure reporting, appearance fallback and unexpected-error propagation. These
are orchestration fixtures, not native-plugin or device latency measurements.
Pull to refresh
Remote list surfaces support pulling down from the top, including lists shorter than the viewport and actionable empty/error states. Refresh awaits the existing cubit or repository owner, retains its account/workspace fences and does not start a second data layer. The Nova refresh affordance adds clearance for scrollable floating headers; fixed headers already pad the body. Only the owning vertical scroll view opts into always-scrollable physics, preserving nested horizontal row swipes. Calendar refresh completes only when its event reload completes. The audit below covers routed lists and remote list overlays. Cold loaders already have a request in flight. Editable forms and composers, authentication/MFA forms, QR/media viewers, active calls, local preference/static navigation screens, and reverse realtime chat/Assistant message timelines retain their existing gestures. Apps reads its registry and local preferences; it has no remote feed.
Regression evidence: notifications_pull_to_refresh_test.dart exercises Inbox and
Archive with empty, short and initial-error data, checks the selected cubit tab and refresh flag,
holds the request to verify the refresh lifetime and then asserts new visible
content. nova_refresh_indicator_test.dart covers short page physics, error
viewports, canceled/upward gestures and actual floating-header geometry.
The habit tracker detail Entries and Leaderboard tabs and the note-link picker
also refresh through their existing owners. Explicit refresh retains empty/error
presentation instead of restarting a full-page cold loader. Regression coverage
includes both task-board row-action suites and exact indicator offsets for fixed
and scrollable headers.
Pull gestures retain the current error message while refreshing. Explicit Retry
returns to loading feedback. Compact sheet empty/error states use a plain
indicator with a shrink-wrapped scroll view. Regression coverage includes
calendar_cubit_test.dart and nova_refresh_indicator_test.dart.