Expo Router + TypeScript baseline for the unified OSHUN shell.
Watch Companions#
- Native Apple Watch and Wear OS companion apps live in
apps/oshun/wearable/(see its README for architecture, tests, and the phone ⇄ watch wire contract). - Phone-side bridge:
src/wearable/—watchBridgeCodec.ts(versioned envelope codec shared with Swift/Kotlin),watchTransport.ts(typednot_configureddegradation when the native module is absent),watchCompanionBridge.ts(stats/preferences push, watch session-control routing into active-companion sessions, completed-session credit), andWatchCompanionBridgeHost.tsx(mounted inapp/_layout.tsx). - Native transport module:
modules/oshun-wearable-connectivity(WCSession on iOS, Wearable Data Layer on Android; autolinked at prebuild). - The watchOS app target is injected into the generated Xcode project at
expo prebuildbyconfig/plugins/withOshunWatchApp.js.
Meditation Audio Engine#
src/audio/meditationPlaybackEngine.tsbinds the shared Tara session state machine (@oshun/domain-tara) to a realexpo-audioplayer: play/pause/ seek, playback status feedback, completion detection, and lock-screen Now Playing metadata (setActiveForLockScreen). Attached per domain-route mount inapp/domain/[domainId].tsx.
Commands#
pnpm nx run @oshun/mobile:startpnpm nx run @oshun/mobile:start:iospnpm nx run @oshun/mobile:start:androidpnpm nx run @oshun/mobile:start:webpnpm nx run @oshun/mobile:typecheckpnpm nx run @oshun/mobile:lint
EAS Build Profiles#
developmentdevelopment client + simulator/debug buildsinternalinternal QA builds for device distributionpreviewrelease-like internal builds for pre-release validationproductionapp store / play store release builds
Examples:
cd apps/oshun/mobile && eas build --profile development --platform ioscd apps/oshun/mobile && eas build --profile preview --platform androidcd apps/oshun/mobile && eas build --profile production --platform allcd apps/oshun/mobile && eas submit --profile production --platform ios
Device Matrix QA#
- Canonical device-matrix contract:
e2e/device-matrix.yaml
- Canonical redesign inventory:
docs/releases/v1/reports/mobile-redesign-inventory.md
- Canonical matrix runner:
pnpm --dir apps/oshun/mobile run e2e:matrixpnpm --dir apps/oshun/mobile run e2e:matrix:drypnpm --dir apps/oshun/mobile run e2e:matrix:nisabapnpm --dir apps/oshun/mobile run e2e:matrix:nisaba:dry
- Matrix targets:
- current iPhone profile:
iPhone 17, with automatic fallback toiPhone 17 Proand theniPhone 16when the preferred simulator is not installed - lower-tier Android profile:
OSHUN Lower Tier Android
- current iPhone profile:
- The matrix always runs the mobile core suite (
e2e:core) so auth, navigation, home, search, library, and assistant coverage are exercised against both device classes before launch signoff. - Nisaba-specific mobile study coverage also has a dedicated matrix path
(
e2e:matrix:nisaba) so daily passage, highlight, and study-reminder regressions can be exercised as one focused mobile contract without running the entire core suite.
Structure#
app/Expo Router routesapp/(tabs)/primary structural tab shell (Home,Explore,Activity,Library,Profile)src/shared local app modules
Shell Relationship Model#
docs/adr/ADR-0056-oshun-mobile-shell-relationship-model.mdis the canonical mobile-shell relationship decision.- Mobile structural tabs:
Home,Explore,Activity,Library,Profile - Mobile assistant behavior: global continuity sheet, not a peer tab route
- Mobile assistant links hydrate into a structural tab anchor plus an assistant route intent so shared links can open the global sheet without inventing a fake sixth tab.
- Mobile domain switching now exposes a lower-zone launcher plus grouped switch sheet so all six domains remain reachable without scrolling back to the top of the active surface.
src/navigation/phoneFirstIA.tsis the measured phone-first IA contract for Home, domain switching, Library, Assistant, and Profile. It keeps the lower domain/assistant launcher pair to44%per side with a shared max width so the pair fits on 320 px small-phone layouts before native E2E runs.src/accessibility/shellNavigationAccessibility.tsis the canonical shell-navigation accessibility contract for:- explicit tab-bar accessibility labels and stable shell tab test IDs
- thumb-reach domain-switcher launcher semantics
app/(tabs)/_layout.tsxnow opts every shell tab into explicit accessibility labels plus tab-bar font scaling.src/components/MobileDomainSwitcherControl.tsxandsrc/components/MobileDomainSwitcherSheet.tsxexpose explicit launcher button semantics and a screen-reader heading for the switcher sheet title.
Thumb-Zone Shell Chrome#
- The structural tab shell now uses a calmer label-led bottom dock with a stronger active-state pill and keyboard-hide behavior so the lower band stays usable during repeated navigation.
- The global domain switcher launcher remains left-anchored in the thumb zone, but now presents itself as the current room affordance instead of a generic utility button.
- The global assistant launcher remains right-anchored above shell chrome, but now reads as a smaller guide-layer affordance instead of a competing primary card.
- The domain switcher and assistant launcher use shared phone-first geometry, so they remain side-by-side on Home, Activity, Library, and Profile and stack only where Explore already has a local thumb-reach search dock.
src/components/ThumbReachActionDock.tsx,src/components/MobileDomainSwitcherControl.tsx, andsrc/components/MobileAssistantLauncher.tsxnow share a tighter lower-band visual grammar so Explore’s local thumb dock and the global shell helpers feel like one system.src/components/AssistantEntryCard.tsxnow supports a compact variant used across Home, Explore, Activity, Library, and Profile so contextual assistant entry preserves prompt seeding without adding another heavy card block to the route.
Grouped Continuity And Library Density#
src/components/QuickActionsTray.tsxnow presents the fixed six quick starts as a grouped core lane plus a lighter utility grid, instead of reading like a stack of independent action cards.src/components/ContinuityCard.tsxnow uses a calmer continuation surface with lighter chrome so Home return journeys and shared domain continuation modules read as reopen cues, not dashboard tiles.src/library/UnifiedLibraryView.tsxnow renders saved material inside a grouped rail with row dividers, lightweight metadata chips, and inline action pills so Library preserves density without becoming another feed of cards.src/library/UnifiedLibraryView.tsxexportsUnifiedLibraryItemsRailso the redesigned library row treatment has direct unit-test coverage without depending on hookful container setup.
Search-First Explore And Domain Entry#
app/(tabs)/explore.tsxnow separates query-present and query-empty states so live results move directly under the search workspace, while empty search state starts with guided domain-entry rows instead of a generic feed.src/components/ExploreDomainLaunchRail.tsxis the grouped mode-first entry rail that lets Explore branch cleanly into Tara, Veritas, Nyx, Arete, or Nisaba without stacking another set of cards.app/domain/[domainId].tsxnow opens every major domain route with a domain-specific entry hero that owns the primary launch decision for listening, reading, observation, check-in, and study.src/components/DomainEntryHero.tsxis the shared launch-hero primitive used to keep the domain entry contract consistent while preserving domain-specific copy, palette, and secondary-action choreography.src/navigation/mobileNisabaReadingQueue.tsnow resolves a dedicated phone reading queue for Nisaba so continuation, daily anchor passages, reminder returns, saved study, and notebook or compare handoffs appear as one ordered mobile lane instead of unrelated cards.
Compact Trust Grammar#
src/components/CompactFactRow.tsxis the shared mobile fact-rail primitive for disclosure, provenance, auth posture, governance summaries, and trust-preserving follow-up states.src/components/AssistantDisclosureStrip.tsx,src/components/AssistantMemoryState.tsx, andsrc/components/MobileAssistantSheet.tsxnow use a calmer disclosure and memory hierarchy that keeps governance visible without dominating the sheet.app/domain/[domainId].tsx,src/components/SourceListItem.tsx,src/components/EvidenceSidebar.tsx,src/components/EvidenceCard.tsx, andsrc/components/ClaimListItem.tsxnow treat Veritas evidence and provenance as scan-first reading support instead of a stack of dashboard cards.- Nisaba’s focused study lane now exposes source/provenance and disclosure facts directly in the main reading lane, while Profile now surfaces compact notification, privacy, auth, and session governance summaries before the deeper controls.
Recovery States#
src/components/MobileRecoveryPanel.tsxis the shared recovery surface for offline continuity, reconnecting work, retry-required sync, and crash-adjacent recovery states.src/offline/shellOfflineExperience.tsis the canonical copy contract for shell-level offline, reconnecting, retry, and queued-sync posture.src/offline/GlobalOfflineBanner.tsxandsrc/offline/ShellOfflineContinuityCard.tsxnow use the same calmer recovery grammar as Activity, domain fallback, Profile offline cache governance, and the rootOshunErrorBoundary.app/(tabs)/activity.tsxnow treats queued sync, retry-required edits, and hydration fallback as local-first recovery states instead of stacked warning cards.app/domain/[domainId].tsxnow opens offline and temporarily unavailable domain routes with one trust-preserving recovery panel before handing off to cached continuation paths.
One-Handed Re-entry Validation#
src/components/NotificationRoutingBridge.tsxnow has direct unit coverage for cold-start notification replay, duplicate-response suppression, and foreground delivery so push re-entry cannot double-route the shell.e2e/flows/shell/one-handed-interruption-and-notification-reentry.yamlis the integrated Maestro validation flow for:- thumb-zone shell launchers on Home
- Home quick resume after returning from an interruption
- Explore thumb-reach search re-entry
- Activity-anchored notification handoff into routed domain surfaces
e2e/flows/shell/notification-route-handoffs.yamlnow also asserts the preservedFrom activityroute context for domain notification launches, not just the deep-link focus payload.e2e/flows/core-experience-suite.yamlande2e/flows/regression-suite.yamlnow include the integrated re-entry audit so it runs in the shared mobile signoff paths.e2e/flows/shell/tara-home-quick-start-completion.yamlnow covers the live Tara quick-start path from Home through session completion, reflection save, and return to Home by using a route-scoped Tara E2E completion/reflection harness instead of a synthetic post-session shortcut.
Startup and Branding#
- Native app icon, adaptive icon, splash image, and web favicon are configured
in
app.jsonand sourced fromassets/. - Brand fonts are bundled in
assets/fonts/and loaded inapp/_layout.tsxbefore initial route render. - Startup flow keeps the native splash visible until:
- initial app bootstrap delay completes
- bundled OSHUN fonts are loaded (or font load fails gracefully)
- App start instrumentation (
shell_opened) records startup latency and font-load health fromapp/_layout.tsx. - Canonical startup budget contract:
src/performance/startupBudgets.ts- cold start targets:
2.2siOS,2.5sAndroid - shared cold-start alert thresholds: warning at
4.0sp95, critical at8.0sp95 - experiment guardrail:
6.0sp95
- cold start targets:
- Canonical animation and battery-impact budget contract:
src/performance/animationBudgets.ts- core action ceiling:
700ms - route transition ceiling:
500ms - reduced-motion continuity cue ceiling:
120ms - stagger ceiling:
8elements across a400msreveal window - every canonical motion recipe is budgeted: tap feedback, card entrance, bottom sheet, route transition, list stagger, shell control, sheet section, and tab-bar visibility
- Android FPS profiling thresholds:
120frames,<= 5%janky,p95 <= 20msorp90 <= 18ms,>= 57estimated FPS - active-session battery budget: max
5%drain per30minutes - long-running decorative loops on interactive shell surfaces:
0
- core action ceiling:
- Canonical offline-asset memory and cache budget contract:
src/performance/offlineAssetBudgets.ts- memory ceilings:
150MBidle,300MBactive,500MBpeak - download-manager storage caps:
free:500MBtotal,25items per domain,50MBper itempro:2GBtotal,100items per domain,200MBper itempremium:10GBtotal,500items per domain,500MBper item
- domain cache windows:
- Tara:
3recent meditations,14day retention - Veritas:
3recent briefings,3day retention - Nisaba:
3recent passages +3recent notes,14day retention
- Tara:
- memory ceilings:
Runtime Env and Feature Flags#
src/config/runtime.tsloads typed runtime config fromEXPO_PUBLIC_*values.src/config/runtime-context.tsxprovides app-wide runtime config anduseFeatureFlag(...)helpers.- Feature flag precedence:
- defaults in
src/config/runtime.ts - JSON overrides via
EXPO_PUBLIC_FEATURE_FLAGS - per-flag env overrides via
EXPO_PUBLIC_FF_*(highest priority)
- defaults in
- Root provider wiring:
app/_layout.tsx. - Example consumed flags:
domainSwitcher(home domain switcher section)quickActionsTray(home and explore quick actions trays)
Error Boundaries and Crash Reporting#
- Root app tree is wrapped by
OshunErrorBoundaryinapp/_layout.tsx. - Boundary fallback UI provides a safe retry action instead of a hard crash screen.
- Crash reporting bootstrap:
src/observability/crash-reporting.ts.- installs React Native global JS error handler (when available)
- installs unhandled-promise capture hook for crash diagnostics
- installs memory diagnostics hooks (startup snapshot, interval sampling, memory warning events)
- captures boundary + global exceptions
- logs local crash payloads and attempts non-blocking POST to:
${EXPO_PUBLIC_OSHUN_BFF_URL}/v1/mobile/crashes
- logs diagnostics payloads and attempts non-blocking POST to:
${EXPO_PUBLIC_OSHUN_BFF_URL}/v1/mobile/diagnostics
src/observability/crash-reporting-screen-context.tsandsrc/observability/MobileCrashReportingScreenBridge.tsxattach active screen metadata to crash and diagnostics payloads for the major shell surfaces: Home, Explore, Activity, Library, Profile, and the shared domain route.- Crash reporting can be toggled with
crashReportingfeature flag.
Network Layer (Retry + Timeout)#
- Shared HTTP client:
src/network/http-client.ts- request timeout via
AbortController - retry policy with exponential backoff + jitter
- retryable status handling (
408,425,429,5xx) - non-retryable
4xxfail-fast behavior
- request timeout via
- BFF adapter client:
src/network/oshun-bff-client.ts- typed
getNotifications(...)wrapper - typed notification write wrappers (
markNotificationRead(...),markNotificationsRead(...)) - notification item payloads now preserve optional
actionPathandactionLabelmetadata for route handoff - optional bearer token injection for protected routes
- typed
- Notifications screen (
app/(tabs)/activity.tsx) now hydrates from BFF whenEXPO_PUBLIC_OSHUN_DEV_AUTH_TOKENis provided, with local fallback + retry CTA. src/notifications/registration.tsinstalls foreground and response listeners plus last-response hydration for notification taps.src/components/NotificationRoutingBridge.tsxmounts inapp/_layout.tsxand routes push responses into Expo Router usingsrc/notifications/notificationRouting.ts.src/notifications/NotificationRoutingPreferences.tsx,src/notifications/NotificationQuietHoursSchedule.tsx, andsrc/notifications/NotificationSensitivityPreferences.tsxprovide the reusable mobile notification policy controls used in Profile and the standalone notification settings screen.src/notifications/NotificationRouteE2EHarness.tsxexposes E2E-only notification response cases from Profile so Maestro can drive the liveNotificationRoutingBridgehandoff path without OS push-delivery dependencies.- Quiet-hours schedule edits patch
/v1/notifications/preferenceswhen an auth token is available and fall back to optimistic local updates for guest and E2E runs. - Sensitivity-aware delivery toggles update the canonical
personalization.notificationTopicssuppression model (daily,events,achievements,research) used by the shared personalization contract.
Global Offline Queue#
- Root offline provider:
src/offline/offline-provider.tsx- native-aware connectivity state (
online/offline/reconnecting) backed by@react-native-community/netinfoon iOS/Android and browser events on web - queued action buffering via
@oshun/offlineOfflineSyncQueue - automatic queue flush on reconnect and manual
sync nowsupport
- native-aware connectivity state (
- Connectivity normalization lives in
src/offline/connectivity.ts. - Global banner:
src/offline/GlobalOfflineBanner.tsx- shown on all app surfaces from
app/_layout.tsx - displays offline/reconnect status, queued action count, and sync controls
- shown on all app surfaces from
- Shared per-surface continuity notice:
src/offline/ShellOfflineContinuityCard.tsx- mounted in Home, Explore, Activity, Library, and Profile
- keeps capability copy consistent with the shell offline contract
- Activity read-state edits now queue while offline, surface queued/retrying/ retry-required state in the timeline, and replay after reconnect.
src/offline/e2eOfflineReplayHarness.tsarms one-shot replay failures in E2E automation so Maestro can exercise the retry-required recovery path without depending on flaky real network faults.e2e/flows/offline-and-retry-suite.yamlgroups shell offline continuity, queued Activity replay, manual retry recovery, and offline cached-domain flows into one dedicated mobile signoff suite.- Device-only dismiss actions stay local and are no longer presented as server-synced work.
Expo Route Map#
src/navigation/routes.tsdefines the typed Expo Router mapping for:- shell tab routes (
home,explore,activity,library,profile) - assistant route intents anchored to a structural tab
- domain launch route (
/domain/[domainId])
- shell tab routes (
- Domain launches in
Home,Explore,Activity,Library, andProfileuse this contract instead of inline path literals. - Domain launch metadata (icon, label, CTA, permissions) is sourced from
@oshun/domain-registry. - Deep/shared URL hydration:
src/navigation/deepLinkHydration.tsresolves canonicaloshun://...and sharedhttps://oshun.app/...links into internal Expo routes.src/navigation/useDeepLinkHydration.tshydrates initial and runtime URLs viaLinkingandrouter.replace(...).
- Route transition instrumentation (
route_transition_completed,tab_viewed) is captured from root layout route-context commits viasrc/analytics/appPerformanceTelemetry.ts.- emits normalized route path
- emits shell-tab context when applicable
- emits six-domain active-domain context for shell routes
- emits explicit route-domain context for
/domain/[domainId]routes - waits for current-domain hydration before emitting shell-route analytics so the first event is not attributed without domain context
app/_layout.tsxmounts the global mobile assistant layer throughsrc/components/MobileDomainSwitcherControl.tsx,src/assistant/MobileAssistantProvider.tsx,src/navigation/MobileAssistantRouteIntentBridge.tsx,src/components/MobileAssistantLauncher.tsx, andsrc/components/MobileAssistantSheet.tsx.src/assistant/disclosure.ts,src/components/AssistantDisclosureStrip.tsx, andsrc/components/AssistantMemoryState.tsxprovide the reusable mobile assistant disclosure and memory-state surfaces used inside the global assistant sheet.- Mobile assistant accessibility audits now cover the live voice/text entry
surface through:
src/components/AssistantDisclosureStrip.test.tsxsrc/components/AssistantMemoryState.test.tsxsrc/components/MobileAssistantSheet.test.tsxe2e/flows/shell/assistant-accessibility-audit.yaml
- The assistant sheet now exposes:
- a screen-reader heading for the assistant title
- explicit disclosure + memory summaries on the live sheet
- quick-prompt button hints
- text-composer label/hint semantics
- a labeled sheet-dismiss action
- synthetic-voice disclosure alongside session-memory disclosure
- Shell-navigation accessibility audits live in:
src/accessibility/shellNavigationAccessibility.test.tsapp/(tabs)/_layout.test.tsxsrc/components/MobileDomainSwitcherSheet.test.tsxe2e/flows/shell/navigation-accessibility-audit.yaml
- Core mobile E2E signoff now has an explicit Maestro suite:
e2e/flows/core-experience-suite.yamlpnpm --dir apps/oshun/mobile run e2e:core
- The core suite is the launch bar for:
- auth session creation and re-entry
- structural tab navigation
- home entry validation
- Tara quick-start launch through completion and reflection return
- explore search execution
- library preservation handoff
- assistant continuation from a saved-item journey
- Device-matrix execution for that suite is handled by
scripts/run-maestro-device-matrix.sh, which resolves the current iPhone simulator automatically and lets QA bind a named lower-tier Android emulator throughANDROID_LOWER_TIER_DEVICE_NAMEorANDROID_LOWER_TIER_DEVICE_ID. - Redesigned shell signoff now has a dedicated Maestro suite:
e2e/flows/shell-redesign-signoff-suite.yamlpnpm --dir apps/oshun/mobile run e2e:signoff
- That suite is the redesign bar for:
- structural tab and launcher navigation posture
- Home hero, return, quick-action, and contextual assistant-entry hierarchy
- continuation states across the six domain entry routes
- contextual assistant entry continuity from Home, Explore, Activity, Profile, and Library
- QA can run the same suite across the existing device matrix through:
pnpm --dir apps/oshun/mobile run e2e:matrix:signoffpnpm --dir apps/oshun/mobile run e2e:matrix:signoff:iospnpm --dir apps/oshun/mobile run e2e:matrix:signoff:android
- Mobile assistant streaming transport has a dedicated lifecycle and device
benchmark contract:
pnpm --dir apps/oshun/mobile run e2e:assistant-transportpnpm --dir apps/oshun/mobile run e2e:matrix:assistant-transportpnpm --dir apps/oshun/mobile run e2e:matrix:assistant-transport:dry- The streaming lifecycle suite requires Metro/the dev client to be built with
EXPO_PUBLIC_OSHUN_MOBILE_ASSISTANT_TRANSPORT=streaming; buffered is the fail-closed default until retained measurements admit a winner. scripts/run-assistant-transport-android-benchmark.shcaptures native PSS, batterystats, TTFT, cancel/background/network outcomes, and raw hashes for either thestreamingorbufferedarm.
- Device-specific redesigned-shell visual capture signoff now has a dedicated
flow and runner:
e2e/flows/shell/redesigned-shell-visual-captures.yamlpnpm --dir apps/oshun/mobile run e2e:captures:shellpnpm --dir apps/oshun/mobile run e2e:captures:shell:iospnpm --dir apps/oshun/mobile run e2e:captures:shell:androidpnpm --dir apps/oshun/mobile run e2e:captures:shell:dry
- The capture runner writes ignored review artifacts into:
apps/oshun/mobile/e2e/artifacts/shell-redesign-signoff/screenshots/iphone-17apps/oshun/mobile/e2e/artifacts/shell-redesign-signoff/screenshots/android-lower-tier
- On Android, the capture runner can be pointed at Expo Go or a dev client with
the existing
APP_ID,DEV_CLIENT_LINK,EXPO_GO_LINK, andVERITAS_ROUTE_LINKoverrides, and it now bootstraps the Maestro Android helper packages automatically when the emulator is missing them.
Home Dashboard#
app/(tabs)/index.tsxnow implements the mobile home workspace around the accepted Tara-first shell sequence instead of a generic dashboard stack:- dynamic daypart-led hero that resolves the canonical OSHUN morning, midday,
and evening journey model through
src/navigation/mobileDaypartJourneys.ts - one dominant current-arc action plus a quieter continuity-review handoff
- explicit three-card daypart rail for morning anchoring, midday reorientation, and evening integration
- one lead return-journey feature plus a calmer stacked continuation lane for alternate reopen points
- companion-domain bridges rebuilt as one grouped support lane rather than a feed of repeated cards
- contextual assistant entry now sits beneath the return/bridge sequence so it supports the current arc without competing with the first-view focal plane
- direct launches rebuilt from a two-column domain card grid into a grouped domain rail with current-focus signaling
- offline continuity and daily-footing surfaces moved beneath the primary ritual and re-entry sequence so Home opens with less density
- quick actions tray now exposes a fixed six-action shell contract
(
meditation,check-in,briefing,tonight,study,assistant-follow-up) plus the existing utility controls underneath - reusable
src/components/ContinuityCard.tsxcontinuity cards for Home and domain detail resume surfaces, with a lead feature treatment used on Home - Home continuity launches mapped through the domain adapter action + deep-link contracts for Tara, Veritas, Nyx, Arete, Nisaba, and Metis
- stable home section, daypart, lead-return, and direct-launch test IDs used by Maestro shell coverage
- dynamic daypart-led hero that resolves the canonical OSHUN morning, midday,
and evening journey model through
src/navigation/mobileDaypartJourneys.tsmaps the shared daypart journey contract into mobile-native route intents:- domain route hydration for Tara, Arete, Veritas, Nyx, Nisaba, and Metis
- assistant-sheet route intent for midday recovery
- shared Library closure handoff for evening integration
src/navigation/mobileQuickActions.tsmaps the fixed quick-action grammar into daypart-aware mobile route intents reused by Home and Explore.
Domain Launch Startup Skeletons#
app/domain/[domainId].tsxnow renders startup skeleton placeholders while domain module metadata/hydration context initializes.- Skeleton phase includes badge/title/body/card placeholders and then transitions to launch contract + permissions content.
- Domain unavailable fallback is handled in the same route with graceful
retry/back/switch-domain actions (
unavailable,reasonquery support). - Domain offline fallback cards are handled in the same route with per-domain
messaging/CTA/cache hints (
offlinequery support plus launch-time device connectivity resolution). - Tara session launch paths (
/meditate/resume/:sessionId,/meditate/session/:sessionId) are hydrated into a concrete shell launch flow with stateful CTA + launch notice. src/offline/taraOfflineCache.tsnow keeps the latest Tara meditations and their audio assets cached through the mobile shell download manager so recent sessions remain launchable offline.- The Tara domain route now exposes a live offline-cache summary while online and cached meditation launch cards while offline when audio is ready.
- Profile settings now bind the existing
Offline downloadspreference to the Tara cache lifecycle and expose Tara cache status plus a clear-cache action. - Reusable
src/components/EvidenceCard.tsxandsrc/components/EvidenceSidebar.tsxprimitives now power the Veritas claim evidence snapshot surface inside domain detail. - Reusable
src/components/ClaimListItem.tsx,src/components/SourceListItem.tsx, andsrc/components/PassageListItem.tsxnow power Veritas claim/source rows and Nisaba study cards inside domain detail. - Reusable
src/components/NotebookCard.tsxandsrc/components/CollectionCard.tsxnow power Nisaba notebook workspaces, Explore curated collections, and type-aware Library notebook/collection rendering. - Entitlement middleware checks now run in the same route using shared profile
state +
@oshun/auth-clientevaluators to block access, expose upgrade navigation context, and filter inaccessible domain shortcuts. - Domain launch telemetry is emitted from
src/analytics/domainLaunchTelemetry.ts(domain_launch_requested,domain_launch_completed, latency + success). - The global lower-zone domain launcher remains available on domain detail routes so cross-domain switching no longer depends only on inline switch rows.
src/navigation/mobileDomainDeepLinkFocus.tsresolves hydrated deep-link paths and query payloads into six-domain mobile focus cards so Tara, Veritas, Nyx, Arete, Nisaba, and Metis expose a visible, testable target contract on the shared domain route.- The shared domain route now exposes first-class continuity cards for Tara, Arete, Veritas, Nyx, and Nisaba so every domain has a stable resume surface before deeper content modules.
- The same shared route now exposes drift-recovery cards for Tara routines, Arete habits, and Nisaba study threads so missed days reopen into a humane next step instead of a raw resume state.
e2e/flows/shell/offline-shell-continuity.yamladds Android-specific Maestro coverage for shell offline banner visibility and offline domain fallback routing, ande2e/flows/regression-suite.yamlnow includes it conditionally on Android.e2e/flows/shell/domain-continuation-cards.yamlverifies that all six domain detail routes expose their expected continuity card and is included in the shared mobile regression suite.e2e/flows/shell/deep-links-six-domains.yamlverifies that high-value object links in all six domains hydrate into visible target focus cards.e2e/flows/shell/domain-drift-recovery.yamlverifies that Tara, Arete, and Nisaba expose their expected drift-recovery card states through the shared domain switcher.e2e/flows/shell/tara-offline-cache.yamladds Android-specific regression coverage that seeds Tara cache online, confirms the Profile cache summary, then validates Tara cached-session affordances after going offline.src/offline/veritasOfflineCache.tsnow keeps recent Veritas briefings in a policy-aware offline cache so only evidence-backed and credibility-eligible briefs are stored locally.e2e/flows/shell/veritas-offline-cache.yamladds Android-specific regression coverage that seeds the Veritas cache online, confirms the Profile summary, and validates cached briefing continuation after going offline.src/offline/nisabaOfflineCache.tsnow keeps recent Nisaba passages and notebook/compare note work cached through the shared download manifest so the Nisaba domain can reopen real study context offline instead of falling back to a generic unavailable screen.e2e/flows/shell/nisaba-offline-cache.yamladds Android-specific regression coverage that seeds Nisaba cache online, confirms the Profile summary, then validates cached passage and note continuation after going offline.
Universal Search UX#
app/(tabs)/explore.tsximplements cross-domain universal search with:- curated cross-domain collections (tap-to-apply themed query sets)
- editorial spotlight cards with curated picks and domain launch/save actions
- explicit domain filter chips and sort controls (
recency,popularity) - Tara quick-resume + result launches routed through canonical Tara deep-link metadata
- per-result save/unsave controls with explicit library handoff behavior
- query input + clear control
- reusable domain switcher entry (
All,Tara,Veritas,Nyx,Arete,Nisaba) + direct domain launch CTA - quick actions tray entry with fixed
meditation,check-in,briefing,tonight,study, andassistant-follow-uplaunches plus the legacy utility actions - contextual assistant entry for branching the current discovery state into the global assistant sheet
- URL hydration support for
q,query,domain, andpathparams - recent searches + trending intents
- result cards with domain/type metadata and one-tap domain launch
Library UX#
app/(tabs)/library.tsximplements the dedicated mobile preserve surface with:- relationship copy clarifying how Library fits with Home, Explore, Activity, Assistant, and Profile
- saved-item, domain, and pending-sync summary cards
- contextual assistant entry seeded with library-triage context
- full
UnifiedLibraryViewbrowsing/filtering behavior usingoriginTab="library"
src/library/LibraryPreviewStrip.tsxreplaces the old full-library embed inside Explore and now hands preserved context into the Library tab.
Assistant Continuity Layer#
Assistantis a global mobile continuity sheet rather than a peer tab.src/assistant/mobile-assistant-model.tsresolves current shell/domain context into prompts, responses, and routing actions, including the Metis learning domain for course, tutoring, and assessment handoffs.src/components/AssistantEntryCard.tsxprovides the reusable contextual assistant-entry surface used across Home, Explore, Activity, Library, and Profile.- The launcher remains available from shell and domain surfaces, and assistant responses route users back into structural tabs or domain launches.
- Every primary tab now also exposes a local assistant entry with a seeded prompt, explicit source tag, and stable test ID so invocation can start from the current screen’s working context instead of only from the floating launcher.
- Learning-oriented assistant prompts route to Metis, while saved-material, settings, and continuity prompts still route to Library, Profile, and Activity respectively.
Activity Timeline UX#
app/(tabs)/activity.tsximplements a unified cross-domain activity timeline with:- unread/priority/domain summary tiles
- streak/progress summary card and milestone progress rows
- cross-domain achievement cards with unlock/progress state
- explicit hydration loading/failure cards with retry actions
- offline-aware queued mutation behavior for timeline actions
- optimistic mutation rollback rules for failed sync writes
- timeline filters (
All,Unread,Priority) - domain filters (
All,Tara,Veritas,Nyx,Arete) - grouped sections (
Now,Today,Earlier) with timeline rail affordance - per-entry actions (
Open,Read/Unread,Dismiss) Opennow routes through the same notification-routing contract used by real push responses, so six-domain activity items hand off into exact domain paths instead of only domain roots- bulk
Mark all seenaction - contextual assistant entry for turning timeline change into a settings or next-surface handoff
Profile and Settings UX#
app/(tabs)/profile.tsximplements a full account and preferences surface with:- identity and plan header
- quick profile stats
- shared profile identity/stats/domain state from
@oshun/auth-client(src/profile/store.ts) - shared preferences model (theme/language/notifications) from
@oshun/auth-client(src/profile/store.ts) - shared privacy + consent model from
@oshun/auth-client(src/profile/store.ts) - shared billing status + recovery model from
@oshun/auth-client(src/profile/store.ts) - general preferences (
theme,language,reduced motion,high contrast,haptics) - notifications controls (
push,email digest,quiet hours) - per-domain push routing so Tara, Veritas, Nyx, Arete, Nisaba, and Metis can each keep or mute push delivery independently without losing in-app or digest settings
- per-persona push routing so OSHUN Navigator, Tara Guide, Zen River Guide, Stoic Research Guide, Nisaba Study Guide, Source Lineage Guide, and Heart Wisdom Guide can each be enabled or muted as notification voices
- privacy/access toggles (
biometric lock,crash reporting,private profile,cross-domain personalization,offline,cellular sync) - consent controls (
legal agreements,analytics,personalization,marketing) - data rights requests UX (
export account data,request/cancel account deletionwith status history) - purchase/upgrade entry points with plan cards and upgrade-intent hydration
(
intent=upgrade,domain,requiredTier) - billing status and recovery actions (
retry payment,schedule retry,update payment method, recovery notice states) - linked devices/session management (
require trusted sessions, per-device revoke, sign out other devices) - support and feedback channels (
help center,contact support,report issue,product feedback) - connected-domain rows with per-domain manage entry
- contextual assistant entry for explaining settings and routing back into the right post-settings shell surface
Gesture Patterns Implemented#
swipe back: enabled on stack routes (seeapp/_layout.tsx) with concrete domain route transitions.cross-domain back stack: domain launches now carryorigin+stackcontext andapp/domain/[domainId].tsxresolves deterministic in-shell back behavior across domain hops.pull-to-refresh: wired on home feed scroll (app/(tabs)/index.tsx)sheet drag: reusable draggable sheet atsrc/components/DraggableBottomSheet.tsx
Haptic Helpers#
src/feedback/haptics.tsmaps OSHUN intents to platform-safe haptic primitives:actionConfirmation-> selection feedbacksuccess-> success notificationwarning-> warning notificationlock-> heavy impact
- Includes priority resolver and throttling controls aligned with
docs/releases/v1/design/haptics-guidelines.md. src/feedback/mobileFlowFeedback.tsis the mobile-shell guidance map for the key launch-critical flows:- assistant open / submit / action handoff
- domain switcher open / select
- quick actions open / launch
- home refresh start / completion
- The shell posture remains one haptic per gesture by default, with selection feedback for launcher/open actions and success reserved for completed refresh outcomes.
src/preferences/mobileExperienceSettings.tsnow makes in-apphapticsandreduced motionpreferences global shell inputs instead of Profile-only local state.
Reduced Motion Support#
src/accessibility/useReducedMotionPreference.tsmerges systemreduceMotionwith the in-app reduced-motion preference fromsrc/preferences/mobileExperienceSettings.ts.src/motion/mobileMotion.tscodifies the canonical duration/easing tokens plus the shared recipes for tap feedback, card entrance, bottom sheet, route transitions, shell controls, sheet sections, and tab-bar visibility.src/motion/MobileMotionSurface.tsxapplies those presets to battery-safe entrance and press feedback across floating shell controls, sheet actions, and tab buttons without introducing continuous or decorative loops.src/components/MobileShellTabBarButton.tsxandapp/(tabs)/_layout.tsxnow give the bottom tabs selected-state emphasis and explicit keyboard hide/show timing that collapse to instant when reduced motion is enabled.app/_layout.tsxnow uses explicit route transition guidance instead of a single hard-coded animation, and still disables transitions when reduced motion is enabled.src/components/DraggableBottomSheet.tsxnow uses shared bottom-sheet motion guidance for open, dismiss, and settle behavior, and collapses those transitions to instant when reduced motion is enabled.- Assistant, quick-actions, domain-switcher, assistant-entry, and thumb-dock surfaces now share the same shell-control and sheet-section motion posture so redesigned mobile entry points feel related rather than independently tuned.
src/recommendations/RecommendationCarousel.tsxsuppresses layout animation when reduced motion is enabled.
Android FPS Validation#
scripts/validate-android-fps.shcapturesadb shell dumpsys gfxinfofor interaction profiling.scripts/parse-gfxinfo.mjsparses captured output using the shared profiling thresholds inconfig/animation-budgets.json.- Validation guide:
docs/releases/v1/runbooks/android-60fps-validation.md
Examples:
cd apps/oshun/mobile && pnpm run perf:fps:android com.oshun.mobile swipe-backcd apps/oshun/mobile && pnpm run perf:fps:android com.oshun.mobile pull-to-refreshcd apps/oshun/mobile && pnpm run perf:fps:android com.oshun.mobile sheet-drag