UX foundation: universal Options, contextual Select and active-game multitasking #167

Product decision (9 October 2026)

Give TrainerOS one coherent controller-first interaction philosophy, rather than accumulating unrelated small menus.

The existing Home primary page retains its name; Options is the tentative user-facing name for the overlay opened by the physical Home button, not a new sixth primary tab. Keep L1/R1 and L2/R2 routing (#111) and the existing warm material/chassis identity.

Experience

• Options uses most of the viewport (approximately 85–95% of the safe screen area) with the origin dimly visible, not the existing narrow HomeMenuCard list. Real handheld and TV profiles recompose separately (TV UI foundation: introduce a real ten-foot responsive layout system, not 960x540 stretching #156–Acceptance: independent image/software updates and true handheld/TV parity across install modes #160).
• In the shell, the same universal capabilities are reachable regardless of which primary/face is underneath. Context-specific operations belong to Select and other local controls, not a different Options menu per shell page.
• During a game, Game Options shows real title/art/session identity, Continue, Minimize / return to TrainerOS, multiplayer/game-party, supported per-game graphics/actions, Exit game, active communications and notifications.
• A minimized session remains running and can be brought back without relaunch or ordinary-save/savestate substitution. Pausing while minimized is runtime/capability-aware; multiplayer must not be frozen.
• Starting a multiplayer invitation from Home's selected game, a library card, a conversation or the running game reuses the same GameParty/Play Together machinery, prefilled with the already-known game, person/group or actual live session.
• Notifications and confirmed achievement toasts can appear over live play without stealing game input. The notification inbox remains accessible through Options during play as well as in the shell.

Hard constraints

• One implementation of actions/providers/parties/calls/notifications; different entry points only supply context.
• Preserve active-session identity, current Trainer, per-collection selection, focus, B/Home dismissal and protected operations. Async events must not retarget actions or move A onto Exit.
• Opening Options never exits, minimizes or pauses a game on its own. Only explicit Exit uses Launch lifecycle: keep ordinary saves and confirm saving only after explicit Exit game #49's clean screenshot / ordinary-save confirmation / graceful close.
• Minimize is not Power lifecycle: support reliable lid close, sleep and wake on handheld devices #79 lid/system suspend, not killing/hiding the app without a working return path and not restoring persistent emulator savestates.
• A notification is not permission to open a microphone, accept an invite, modify a save or steal game input.
• Preserve UX: reconcile Social, multiplayer, calls and Link into one coherent user journey #127–UX acceptance: validate the complete Social → Together → party → game → return journey #135 Social/Together UX, RetroAchievements: show an in-universe unlock banner and play a short TrainerOS jingle #25 verified achievement notifications, Home button: add an adaptive activity overlay with game appearance presets, without duplicating Start #112's supported game appearance controls and existing runtime/input ownership.

Implementation boundaries and review

Reuse the current ShellController, AdventureExitPresentation, AdventureOverlayService, HomeMenuCard, Main.qml and the live session/launch controllers where appropriate; replace their presentation/dispatch contracts deliberately rather than adding another independent menu. Keep service operations behind controllers, not QML file writes or emulator commands.

Separate issues will cover the shell Options surface, Select grammar, Game Options presentation, safe minimize/resume, Play Together entry contexts and passive notification surfaces. This issue captures the cross-cutting policy and final product review; it does not itself claim delivery.

Related existing work: #25, #49, #79, #88, #101, #111, #112, #127, #130–#135, #156–#160.

Acceptance

• A user can predict A / Select / Home-Options / Start across shell and gameplay.
• Shell Options is universal, rather than quietly varying based on the current TrainerOS screen; local Select is contextual.
• Game Options is a full-featured large session surface with preserved global notifications.
• Live game → Options → minimize → Social/respond → return to same process is proven on supported devices/runtimes without accidental exit/save rewrite.
• Invite and notification actions from multiple entry points resolve to the same authorized identities and existing services.
• Controller, touch, handheld, TV, privacy, DND, reduced motion, loss/recovery and protected-save checks cover the reconciled experience.
• Updated active docs/help distinguish accepted behavior from older compact-menu/historical screenshots and behavior.

Child issue tracker (created 9 October 2026)

• Shell Options: replace the compact Home menu with a large universal activity surface #168 — Large universal shell Options (not per-page context actions)
• Select UX: context actions for the focused object and current TrainerOS screen #169 — Select on the focused shell item/screen
• Game Options: large artwork-led overlay for the actual running game session #170 — Large running-game Game Options with game art, communications and actions
• Game multitasking: minimize a live game, safely pause when supported, and return #171 — Real Minimize / Return to Game with per-runtime safe pause policy
• Play Together context entries: invite from Home game card, library, chat or live game #172 — Shared Play Together across Home game card, library, chat and live session
• Notifications UI: shared passive toasts during gameplay and in shell, with Options inbox #173 — Passive notification toasts in shell and live gameplay, inbox in both Options surfaces

Existing work retained, not duplicated: #25 owns verified achievement popups and jingle; #49 owns explicit safe Exit; #112 owns Home interception and existing game appearance controls; #127–#135 own the party, invitation/consent and incoming-activity semantics; #79 owns system sleep; #156–#160 own TV profile adaptation.

Suggested delivery dependency: #168/#169 and compositor/input contracts → #170/#171 → #172/#173 integration → end-to-end handheld/TV acceptance. The UX can be iterated without waiting on unrelated netplay providers.

Game-specific experience encapsulation (owner decision, 9 October 2026)

Beyond Options/Select, the two existing game-facing shell slots Companions and Trainer are adapter/experience-driven in labels, secondary faces and real contents. Do not bake Pokémon screens/badges into the shell. The current selected Home Adventure chooses the shell experience; a live minimized/running game binds its Game Options extensions to the actual session independently. Persistent local TrainerOS user identity and generic Social, Options and system services remain global.

• Experience architecture: adapter-owned game UI, dynamic Companions/Trainer slots and progression #174 — Experience architecture: one host shell + encapsulated game-specific UI/actions/progress.
• Experience navigation: resolve primary labels, faces and Select actions from selected-game adapters #175 — Dynamic labels/routes/faces and context Select contribution per selected game.
• Pokémon experience extraction: encapsulate Companions, Center and game progress outside the core shell #176 — Move existing Pokémon Companions/Center/Journey/Hall into its own experience, preserving real Emerald functionality.
• Generic game experience: meaningful fallback and cross-adapter UX acceptance #177 — Honest generic-game fallback and cross-family/missing-adapter acceptance.
• Player identity vs game progression: decouple universal Trainer profile from adapter-specific history #178 — Universal player identity separate from Pokémon-only profile decoration/progression.

Reconcile existing #89/#90/#92/#111 rather than building a parallel adapter or save framework. Do not change #168's universal shell Options by current page/game; only Select and in-game Game Options accept game-specific extensions.