Skip to content

Play your Steam library's Windows games on a jailbroken PS5.

C++
95.6 KB
Raw Blame
// simulation.hpp - Renderer-neutral deterministic Playden UI simulation.
// Copyright (c) 2026 Playden contributors
// SPDX-License-Identifier: MIT
#pragma once

#include "app/preferences.h"
#include "library/organization.h"
#include "library/update_check.h"
#include "library/model.h"
#include "runtime/game_settings.h"
#include "steam/backend/content_language.h"

#include <algorithm>
#include <array>
#include <cstdint>
#include <filesystem>
#include <map>
#include <optional>
#include <set>
#include <tuple>
#include <string>
#include <vector>

namespace playden::homebrew {

using GameId = playden::GameId;

enum class Route { Startup, SignIn, Home, Library, Downloads, Settings, Details, Session, Saves, SaveDetails, ManageGames };
// Manage installed games: one tab per batch action. Each has its own list and selection.
enum class ManageTab { Updates, Runtimes, Move, Uninstall };
enum class ModelMode { Simulation, Live };
// UsePassword/UseQr switch the sign-in screen's method; BeginPassword and SubmitCode carry the form's
// secrets, which the controller takes with TakeSignInCredentials and TakeGuardCode.
enum class ServiceAction { BeginQr, CancelQr, SignOut, SwitchAccount, RefreshLibrary, Reauthenticate,
                           UsePassword, UseQr, BeginPassword, SubmitCode, StaySignedIn };
// A service action for one store's account. The sign-in actions (QR, password, Steam Guard code) are Steam's.
struct ServiceRequest {
    ServiceAction action = ServiceAction::BeginQr;
    Store store = Store::kSteam;
};
inline bool operator==(const ServiceRequest& request, ServiceAction action) { return request.action == action; }
inline bool operator!=(const ServiceRequest& request, ServiceAction action) { return request.action != action; }
enum class AuthState { SignedOut, Restoring, Waiting, Expired, Failed, Cancelled, Syncing, SigningOut, SignedIn, Offline };
enum class DownloadServerRequest { List, Test, CancelTest };
// The controller projects the download-server service here; no credentials or Steam backend types enter the UI.
struct DownloadServerOption {
    std::string id;
    std::string name;
    bool plain_http = false;
};
struct DownloadServerResult {
    std::string id;
    double mb_per_s = 0;
    bool failed = false;
};
struct LiveDownloadServers {
    std::string phase = "idle";  // idle, listing, listed, list-failed, testing, tested, test-failed
    std::vector<DownloadServerOption> servers;
    std::vector<DownloadServerResult> rates;
    std::size_t testing_index = 0;
    bool needs_sign_in = false;
    bool needs_installed_game = false;
    std::string preferred_name;  // the stored choice's display name, even when absent from this list
    std::string message;  // user-facing explanation, supplied by the controller
};
// Web access as the controller reports it (web::Service): the page's address for the QR, or why it isn't open.
struct LiveWebAccess {
    std::string state = "off";  // off, starting, on, failed
    std::string url;            // on: http://<address>:<port>/, empty when the address is unknown
    std::uint16_t port = 0;
    std::string error;          // failed: why
    std::string pairing_code;   // a browser asked to pair: the code to show now; empty when none
    bool operator==(const LiveWebAccess&) const = default;
};
enum class JobState { Queued, Downloading, Pausing, Paused, Verifying, Downloaded, Failed, Cancelled, Interrupted };
enum class JobStage { Download, Verify, Install, Uninstall };
enum class SessionState { Idle, Preparing, Launching, Running, Stopping, Failed, Crashed };
enum class RuntimeState { Unavailable, Checking, Ready, Failed };
enum class LogState { Loading, Ready, Failed };
// Update: an installed game's update (or DLC bought since), from its details page. Move: an installed game to
// another drive (volume_id).
enum class InstallRequestKind { Install, Pause, Resume, DownloadNow, MoveUp, MoveDown, Cancel, Uninstall, SetDefaultVolume,
                                DismissCompleted, ClearCompleted, Update, Move };
struct InstallRequest {
    InstallRequestKind kind = InstallRequestKind::Install;
    GameId game_id;
    std::string volume_id;  // SetDefaultVolume, Move: the drive; Install: this install's drive (empty: the default)
    bool delete_saves = false;  // Uninstall only: also delete the game's kept saves and settings
    // Install: the content language chosen in the install sheet for this install (empty: the Settings
    // download language), and the branch (empty: public).
    std::string language;
    std::string branch;
    // Install: the install-size estimate of the chosen version (the game's when Steam gives none for it),
    // which the install service reserves on the drive; empty: unknown.
    std::optional<std::uint64_t> install_bytes;
    // Install: the DLC turned off in the install sheet, sorted.
    std::vector<std::uint32_t> excluded_dlc;
};
// Game maintenance the details page offers (simulated in fixture mode).
enum class MaintenanceKind { ApplySettings, ClearShaderCache, Repair, BackupSaves, RecreateBottle, UpdateRuntime };
// Whether a game's PS5 title runs now, as the console last answered.
enum class TitleActivity { Unknown, Stopped, Running };
// Live install state projected from the real install service.
// The stored download server choice that races the servers when a download starts.
inline constexpr const char* kFastestDownloadServer = "fastest";
// "Fastly · 18.2 MB/s · ~3 min left": the server's name comes first when there is a rate.
std::string FormatDownloadRate(std::optional<std::uint64_t> bytes_per_second, std::optional<int> eta_seconds,
                               const std::string& server_name = {});
// The jobs the install service's Queue holds at once (installs::InstallService::kMaxJobs).
inline constexpr std::size_t kQueueJobLimit = 64;
struct LiveInstallJob {
    GameId game_id;
    JobState state = JobState::Queued;
    std::uint64_t done_bytes = 0;
    std::uint64_t total_bytes = 0;
    std::string failure;
    std::string volume_id;
    std::optional<std::uint64_t> bytes_per_second;
    std::optional<int> eta_seconds;
    std::uint64_t held_bytes = 0;  // installed bytes already on the drive
    bool checking_licenses = false;  // a slow Steam license check before the download starts
    std::string server_name;  // while downloading: the download server's display name
    bool update = false;          // an installed game's update, not an install
    bool locked = false;          // the update is putting its files in place: the game can't be played
    bool checking_files = false;  // while running: the update hashes the installed files
    bool applying = false;        // while running: the update puts its files in place
    // A move to another drive (volume_id) from from_volume_id; while running, what it is doing. locked: its
    // title may already use the copy, or it is deleting the old folder, so it can't be paused or canceled.
    bool move = false;
    std::string from_volume_id;
    enum class MoveStep { Copying, Verifying, Switching, DeletingOld } move_step = MoveStep::Copying;
    // While the move checks its copy: the files checked so far, of how many (0 of 0: no count).
    std::uint64_t checked_files = 0;
    std::uint64_t check_files = 0;
    std::optional<std::uint64_t> estimated_bytes;  // what the job was asked with, DLC choice included
};
struct LiveInstalledGame {
    GameId game_id;
    std::uint64_t install_bytes = 0;
    std::string volume_id;
    bool available = true;  // false while the game's drive is absent
    std::int64_t finished_at = 0;  // when it was installed (Unix seconds; a move keeps it), 0 unknown
};
// A recent finished download, listed in Downloads after the queue.
struct LiveCompletedDownload {
    GameId game_id;
    std::uint64_t install_bytes = 0;
    std::string volume_id;
    std::int64_t finished_at = 0;  // Unix seconds
    std::uint64_t update_bytes = 0;  // an update: what it downloaded; 0 for an install
};
// A drive the real install service can use. Space is absent when the platform cannot report it.
struct LiveVolume {
    std::string id;
    std::string label;
    bool available = true;   // the drive is attached
    std::optional<std::uint64_t> total_bytes;
    std::optional<std::uint64_t> free_bytes;
    bool writable = true;    // Playden can make its games folder there
};
// The runtime kit in use, for Settings > About. Every field is empty when no kit is usable.
struct LiveKitInfo {
    std::string kit_id;
    std::string manifest_sha256;
    std::string expected_manifest_sha256;  // the kit this build was tested with
    std::string prospero_win_revision;     // what the kit's PS5 titles were built from
    bool source_dirty = false;             // built from uncommitted changes
    std::string unavailable_reason;        // why no kit is in use
    std::string version;                   // "0.13", from its runtime's artifact name; empty for older kits
};
// Live: Playden's own update (update/update_service.h), projected for Settings, Downloads and prompts.
struct LiveSelfUpdate {
    std::string phase = "idle";  // idle, checking, up-to-date, available, downloading, unpacking, staged, failed
    std::string current;         // "0.2.0"
    std::string commit;          // the commit this build was made from, when known
    std::string available;       // the newer version, when known
    std::string notes;
    std::string part;            // "kit" or "app" while downloading or unpacking
    std::uint64_t done = 0;
    std::uint64_t total = 0;
    std::optional<std::uint64_t> bytes_per_second;
    std::optional<int> eta_seconds;
    std::uint64_t download_bytes = 0;
    bool kit_needed = false;
    bool user_check = false;     // the last check was asked for in Settings
    std::string error;
    std::string previous;        // the version "go back" restores; empty when none is kept
    std::string notes_url;       // the available release's page
    std::string current_notes;   // the running version's release notes, when Playden updated to it
    std::string current_notes_url;
    bool whats_new = false;      // the previous run updated Playden: show its release notes once
    bool quiet = false;          // the available version is one the player went back from: no dialog
    std::string finished_message;  // the previous run's update result, shown once
    bool finished_failed = false;
    // The kit-only install (first run, or a kit that isn't this version's): idle, checking, not-needed,
    // unavailable, available, downloading, unpacking, installed, failed.
    std::string kit_phase = "idle";
    bool kit_replaces = false;   // another kit is installed: this one replaces it
    std::uint64_t kit_download_bytes = 0;
    std::uint64_t kit_done = 0;
    std::uint64_t kit_total = 0;
    std::string kit_error;
};
// Live: what Game settings needs to choose a game's program, projected from the runtime host.
// A program a Steam launch option names, as a path in the game folder.
struct LaunchProgram {
    std::string path;
    bool helper = false;  // an installer or tool (the import rules)
};

struct LiveGameSetup {
    std::vector<playden::runtime::GameProgram> programs;  // the game folder's Windows programs
    bool scanned = false;
    // A game Playden could not prepare: the recipe the sheet starts from, whether a choice in
    // Game settings can get past the refusal, and the refusal itself.
    std::optional<playden::runtime::GameRecipe> draft;
    bool refusal_soft = false;
    std::string refusal;
    // Steam's options are all for other branches and more than one program is in the folder:
    // setting up waits for the player's choice (the Play row and a sheet ask).
    std::vector<LaunchProgram> steam_choices;
};
// Live per-game runtime (private bottle and PS5 title) state, projected from the runtime host.
struct LiveRuntimeGame {
    GameId game_id;
    std::string status;   // short value, e.g. "Not prepared", "Preparing", "Ready"
    std::string detail;   // why, or what happens next
    bool can_prepare = false;
    bool ready = false;
    // Play: whether it can start now, and the current or last launch.
    bool can_play = false;
    std::string play_status;  // e.g. "Starting…", "Playing"; empty when idle
    std::string play_detail;  // the last launch's outcome or refusal
    // Uninstall removes the game's PS5 title first; has_title says there is one.
    bool has_title = false;
    std::string uninstall_status;  // e.g. "Syncing saves…", "Removing PS5 title…"; empty when idle
    // How far the current copy or deletion is (0–1); absent when it cannot be measured.
    std::optional<float> progress;
    std::string play_work;  // Play's own work before the launch, for Setup ("Installing PhysX…")
    std::optional<std::string> physx_needed;  // the PhysX engine the bottle lacks: its version, empty when unknown
    // Prepared and waiting for the PS5 to register its title, which it does once Playden
    // quits: the game is ready to play from Home, and Play quits there.
    bool awaiting_registration = false;
    // The title runs the installed kit's runtime (false while a Ready title waits for Update): settings only the
    // newer runtime takes, such as 120 Hz output, can be chosen before but apply only then.
    bool runtime_current = true;
    // Its setup stopped before Ready and left a PS5 title or bottle made with an earlier kit: Try again
    // can't finish it, Recreate bottle does (RuntimeInstallView::setup_other_kit).
    bool setup_other_kit = false;
    // A move stopped part way: "Needs repair", but only Play finishes it.
    bool moving = false;
    // Has a prepared title (Ready, perhaps with an update or repair to make): its Game
    // settings and maintenance apply to it.
    bool prepared = false;
    // The settings revision its PS5 title publishes and the launch entry it was made for.
    std::uint64_t settings_revision = 0;
    std::string launch_entry_id;
    TitleActivity activity = TitleActivity::Unknown;
    // The newest maintenance request and its outcome.
    std::optional<MaintenanceKind> maintenance;
    bool maintenance_running = false;
    bool maintenance_ok = false;
    std::string maintenance_message;
    // Save backups kept for the game and when the newest was made (Unix time).
    std::size_t save_backups = 0;
    std::int64_t latest_save_backup = 0;
    std::string failure_code;  // Recorded preparation failure; detail remains available in diagnostics.
    // Its setup waits for another game's to finish: Playden sets up one game at a time.
    bool queued = false;
    // Another store's game that uses Steamworks: the Steam app ID it was set up with, and whether that
    // came from the game's own steam_appid.txt (which wins over the one in Game settings).
    std::uint32_t steam_app_id = 0;
    bool steam_app_from_game_file = false;
    // The artwork source of the icon inside the program its title starts (homebrew/program_icon.hpp), shown
    // where the game has no cover art; empty before it is prepared.
    std::string program_icon;
};
// A preparation that ended Ready, listed in Queue after the waiting games.
struct LiveCompletedPreparation {
    GameId game_id;
    std::int64_t finished_at = 0;  // Unix seconds
    bool operator==(const LiveCompletedPreparation&) const = default;
};
// An uninstall that runs or waits its turn, listed in Queue's Preparation section.
struct LiveUninstall {
    GameId game_id;
    std::string step;  // what it does now, e.g. "Removing PS5 title…"; empty while it waits its turn
    bool operator==(const LiveUninstall&) const = default;
};
// An uninstall that ended this session: uninstalled, or stopped with the reason.
struct EndedUninstall {
    GameId game_id;
    std::string title;  // kept: an imported game leaves the library once it is uninstalled
    std::string stopped;  // why it stopped; empty once uninstalled
    std::int64_t finished_at = 0;  // Unix seconds, 0 unknown
    bool operator==(const EndedUninstall&) const = default;
};
// Live: the runtime's preparation queue, for Queue's Preparation section.
struct PreparationQueue {
    std::optional<GameId> active;  // being prepared now
    std::vector<GameId> waiting;   // in the order they start
    std::vector<LiveCompletedPreparation> completed;  // newest first
    // Why the latest preparation of a game that is neither prepared nor waiting was refused.
    std::map<GameId, std::string> refused;
    std::vector<LiveUninstall> uninstalls;  // in the order they were asked for
    bool operator==(const PreparationQueue&) const = default;
};
// Saves and settings kept from an uninstalled game (its private bottle).
struct LiveKeptBottle {
    GameId game_id;
    std::string name;
    std::int64_t kept_at = 0;
    std::uint64_t bytes = 0;
    bool operator==(const LiveKeptBottle&) const = default;
};
// A PS5 title folder no install record owns; only its title is removed.
struct LiveLeftoverTitle {
    std::string title_id;
    std::string name;
    std::uint64_t bytes = 0;
    bool operator==(const LiveLeftoverTitle&) const = default;
};
struct LiveLeftoverDelete {
    std::string title_id;
    std::string name;
    std::string step;  // empty while queued
    std::string failure;
    bool operator==(const LiveLeftoverDelete&) const = default;
};
// A game that plays in place from a folder Playden doesn't manage (an imported game on a drive):
// never in Installed games, its files never deleted.
struct LiveExternalGame {
    GameId game_id;
    std::string volume_id;
    bool available = true;  // its drive and folder are there and the PS5 can play from them
    std::string reason;     // why a folder that is there can't be played from; empty otherwise
    bool operator==(const LiveExternalGame&) const = default;
};
// A folder in an import folder that could be added to the library (stores/local/library_source.h).
struct LiveImportProgram {
    std::string path;  // inside the game folder, '/' separators
    std::uint64_t bytes = 0;
    bool helper = false;  // an installer or tool, ranked last
    bool operator==(const LiveImportProgram&) const = default;
};
struct LiveImportCandidate {
    std::string volume_id;
    std::string folder;  // relative to the volume's mount
    std::string path;    // console path
    std::string title;
    std::vector<LiveImportProgram> programs;  // ranked: the likely game first
    std::uint64_t total_bytes = 0;  // estimate
    bool ascii_ok = false;  // can play in place
    bool partial = false;   // the scan stopped at a limit or depth
    GameId imported;        // already in the library as this game; invalid when not
    std::uint64_t file_count = 0;  // files in the folder (0 when unknown)
    bool operator==(const LiveImportCandidate&) const = default;
};
// Requests for the Local store: look for games, add a candidate (in place), remove an imported game.
// A game moved into Playden is prepared once it is there, as a finished copy is.
// CopyIntoPlayden: copy an imported game playing in place into Playden's own storage (volume_id:
// an install volume, empty for the default one). MoveIntoPlayden: rename a drop-folder game into
// Playden's games folder on the console storage (instant; its PS5 title, if any, follows).
enum class ImportRequestKind { LookForGames, Add, Remove, CopyIntoPlayden, MoveIntoPlayden };
struct ImportRequest {
    ImportRequestKind kind = ImportRequestKind::LookForGames;
    GameId game_id;          // Remove, CopyIntoPlayden, MoveIntoPlayden
    std::string volume_id;   // Add, CopyIntoPlayden
    std::string folder;      // Add: relative to the volume's mount
    std::string program;     // Add: relative to the folder
    bool prepare = false;    // Add: prepare the game once it is in the library (it plays in place)
};
// Live Steam Cloud save state for one game, projected from the cloud service.
// Waiting: transfers that need no choice wait for the player (an uninstalled game's saves, or
// saves deleted here that Cloud still has).
enum class CloudStatus { None, Checking, Syncing, Synced, UpToDate, Conflict, NeedsAccount, Unsupported, Failed, Waiting };
struct LiveCloudGame {
    GameId game_id;
    CloudStatus status = CloudStatus::None;
    std::string message;
    std::size_t local_files = 0;
    std::size_t remote_files = 0;
    std::uint64_t local_bytes = 0;
    std::uint64_t remote_bytes = 0;
    std::int64_t local_latest = 0;
    std::int64_t remote_latest = 0;
    bool first_sync = false;      // a conflict before any sync on this console: both sides already had saves
    bool first_overwrite = false; // a conflict because this console's first upload would replace Cloud saves
    std::int64_t last_sync = 0;   // Unix time saves were last in step
    bool queued = false;          // waiting in the running check or Sync all
    std::uint64_t moved_bytes = 0, total_bytes = 0;  // the transfer in progress
    std::size_t downloads = 0, uploads = 0;          // what the transfer moves
    bool after_play = false;      // the game may be running: its saves sync once it stops
    bool background = false;      // the result of a check the player did not start: no dialogs
};
// The Saves tab's check or Sync all, projected from the cloud service.
enum class SavesJobKind { None, QuickCheck, SyncAll };
struct LiveSavesJob {
    SavesJobKind kind = SavesJobKind::None;
    std::size_t done = 0, total = 0;
    GameId current;
    bool stopping = false;
};
// RemoveLocal deletes a game's saves on this console (backed up first); RemoveLeftover deletes an
// uninstalled game's kept data with its sync state. QuickCheck, SyncAll and StopJob are the Saves
// tab's (game_id 0).
enum class CloudRequestKind { Sync, UseLocal, UseCloud, ConfirmAccount, RemoveLocal, RemoveLeftover, QuickCheck, SyncAll, StopJob };
struct CloudRequest {
    CloudRequestKind kind = CloudRequestKind::Sync;
    GameId game_id;
};
enum class Compatibility { Untested, Works, Playable, Broken };
enum class RowKind { Heading, Action, Toggle, Choice, Text, Game, Job, Volume, Profile, Status, Separator };

// The sign-in screen: the QR code, or the account name and password form and its Steam Guard steps.
enum class SignInStep { Qr, Password, Submitting, Approval, EmailCode, AuthenticatorCode };
struct SignInForm {
    SignInStep step = SignInStep::Qr;
    std::string account_name;
    std::string password;        // never saved, shown or snapshotted; cleared after submit, cancel or leaving
    std::string code;            // the Steam Guard code being typed
    std::string email_domain;    // where Steam sent the email code or approval
    bool code_allowed = false;   // Approval: a typed code works too
    bool code_is_email = false;  // the code Steam takes is the emailed one
    bool code_entry = false;     // Approval: the player chose to type a code
    bool code_rejected = false;  // the last code was wrong
    bool code_sent = false;      // waiting for Steam to check the code
    std::string error;           // why the last password sign-in failed
};
// A password as the screen shows it: one dot per character.
std::string mask_secret(std::string_view value);
struct SignInCredentials {
    std::string account_name;
    std::string password;
};

struct Account {
    std::string id;
    std::string display_name;
    std::string challenge_url;
    AuthState authentication = AuthState::SignedOut;
    std::int64_t challenge_expiry = 0;
    std::int64_t last_sync = 0;
    bool cache_available = false;
    std::string error;
    bool storage_full = false;  // Failed: the sign-in can't be saved until console storage has room
};

struct AccountUpdate {
    AuthState authentication = AuthState::SignedOut;
    std::string id;
    std::string display_name;
    std::string challenge_url;
    std::string error;
    bool clear_library = false;
    // Waiting and Failed: the sign-in screen's step and its Steam Guard prompt.
    SignInStep sign_in = SignInStep::Qr;
    std::string email_domain;
    bool code_allowed = false;
    bool code_is_email = false;
    bool code_rejected = false;
    // Authenticated by a sign-in (not a restore): whether it used the password, remembered for next time.
    std::optional<bool> signed_in_with_password;
    bool storage_full = false;  // Failed: console storage is full
    // Failed or SignedOut: the saved sign-in could not be restored (Steam out of reach, storage busy or
    // full, the session revoked), not a sign-in the player started. With another store's games, Playden
    // stays on (or goes to) Home and a notification gives the error.
    bool restoring = false;
};

struct LibraryUpdate {
    std::vector<playden::GameSummary> games;
    bool loading = false;
    std::string error;
    bool stale = false;
    bool cache_available = false;
    std::optional<std::int64_t> retrieved_at;
    Store source = Store::kSteam;  // the store whose games these are; other stores' games stay
};

struct PersistenceLoadToken {
    std::uint64_t id = 0;
    std::uint64_t baseline_revision = 0;
};

inline bool operator==(PersistenceLoadToken left, PersistenceLoadToken right) {
    return left.id == right.id && left.baseline_revision == right.baseline_revision;
}

// A version of a game (a Steam branch) an install can choose, from Steam app info.
struct GameVersion {
    std::string name;  // as Steam names the branch; "public" is the default
    std::string description;
    std::int64_t time_updated = 0;  // unix seconds; 0 = unknown
    std::uint64_t build_id = 0;
    std::optional<std::uint64_t> download_bytes;
    std::optional<std::uint64_t> install_bytes;
    // The same per content language ("german"), for an install in another language than Settings'.
    struct LanguageSize {
        std::string language;
        std::uint64_t download_bytes = 0;
        std::uint64_t install_bytes = 0;
    };
    std::vector<LanguageSize> languages;
};

struct InstallAssessment;  // storage_sim.hpp

// One install choice's size measured from its manifests: Steam's figures add up each depot, so depots holding the
// same files count them twice.
struct MeasuredInstallSize {
    std::uint64_t install_bytes = 0;
    std::uint64_t download_bytes = 0;
};

// A size check the install sheet asks for: a version (Steam branch), a content language, and the owned DLC turned off.
struct SizeCheckRequest {
    GameId id;
    std::string branch;
    std::string language;
    std::vector<std::uint32_t> excluded_dlc;
};

// A DLC with files that an install can leave out.
struct GameDlc {
    std::uint32_t app_id = 0;
    std::string name;  // empty: Steam doesn't describe it
    std::uint64_t download_bytes = 0;
    std::uint64_t install_bytes = 0;
    bool free = false;  // not owned yet: the install claims it
    // Where another version or language differs from the sizes above (public, the Settings language). No install
    // bytes: that choice doesn't have the DLC.
    struct OtherSize {
        std::string branch;
        std::string language;
        std::uint64_t download_bytes = 0;
        std::uint64_t install_bytes = 0;
        bool optional = false;
    };
    std::vector<OtherSize> other_sizes;
    bool optional = false;  // Steam doesn't download it by itself
};

// What the DLC choice does to an install's size. Off: owned DLC turned off, which Steam's figures for the game count.
// Free: free DLC left on, which they don't count, as the account doesn't own it yet.
struct InstallDlcSizes {
    std::uint64_t off_install_bytes = 0;
    std::uint64_t off_download_bytes = 0;
    std::uint64_t free_install_bytes = 0;
    std::uint64_t free_download_bytes = 0;
};

// An installed game's update, from Steam app info compared with its install record.
struct GameUpdate {
    bool newer = false;    // a newer version of the game's content
    bool new_dlc = false;  // DLC the account owns that the install doesn't hold
    // Measured from the manifests against the install's files (`sized`): what the update downloads, and the
    // changed files' bytes staged beside the game until they go in place.
    std::uint64_t download_bytes = 0;
    std::uint64_t staged_bytes = 0;
    std::uint64_t target = 0;  // the depots and manifests updated to (0 unknown): sizes hold for this one only
    bool sized = false;
    [[nodiscard]] bool available() const noexcept { return newer || new_dlc; }
    bool operator==(const GameUpdate&) const = default;
};

// Live: the check of the Steam account's installed games for updates (Manage installed games). It runs at
// most once a day when the screen opens, or when the player asks; the result is saved per account.
struct UpdateCheckState {
    bool loaded = false;          // the account's saved check has been read (or there was none)
    std::int64_t checked_at = 0;  // the last check that finished for every game, unix seconds; 0: never
    bool checking = false;
    std::size_t asked = 0;     // games sent to Steam so far
    std::size_t answered = 0;  // games Steam answered (or failed to)
    std::size_t total = 0;     // games the running check covers; 0 until the controller starts it
    bool failed = false;       // the last check couldn't reach Steam: the saved results stand ("Couldn't check")
    std::map<GameId, GameUpdate> games;  // installed games with an update or new DLC, from checks and game pages
};

struct Game {
    GameId id;
    std::string title;
    std::string description;
    std::string source;
    std::string artwork_source;
    std::string folded_title; // Derived once for production query/sort; never persisted.
    std::string cover_key;
    std::string hero_key;
    std::string logo_key;
    std::vector<std::string> genres;
    std::string controller_support;
    std::optional<std::uint64_t> download_bytes;
    std::optional<std::uint64_t> install_bytes;
    std::optional<std::int64_t> added_at;
    std::optional<std::int64_t> last_played;
    std::optional<std::uint64_t> playtime_minutes;
    std::optional<bool> windows_installable;  // from Steam app info; absent until fetched
    std::vector<std::string> content_languages;  // from Steam app info: the languages an install can choose
    std::vector<GameDlc> dlc;  // from Steam app info: what an install's DLC list offers
    std::vector<GameVersion> versions;  // from Steam app info: public first; two or more offer a choice
    GameUpdate update;  // from Steam app info, for an installed game
    bool demo = false;  // a Steam demo; Sort and filters › Demos hides it
    bool family_shared = false;  // shared by a Steam family member; the tile says "Family"
    bool art_pending = false;
    bool art_failed = false;
};

// What a game that isn't installed takes with the install sheet's defaults: Steam's figures count the owned DLC, so
// optional DLC (which starts off) comes off them and free DLC (which starts on, not owned yet) goes on. Nothing when
// Steam gave no figure.
[[nodiscard]] inline std::optional<std::uint64_t> default_install_bytes(const Game& game) {
    if (!game.install_bytes) return std::nullopt;
    std::uint64_t off = 0, free = 0;
    for (const auto& choice : game.dlc) {
        if (choice.free) free += choice.install_bytes;
        else if (choice.optional) off += choice.install_bytes;
    }
    return *game.install_bytes - std::min(*game.install_bytes, off) + free;
}
[[nodiscard]] inline std::optional<std::uint64_t> default_download_bytes(const Game& game) {
    if (!game.download_bytes) return std::nullopt;
    std::uint64_t off = 0, free = 0;
    for (const auto& choice : game.dlc) {
        if (choice.free) free += choice.download_bytes;
        else if (choice.optional) off += choice.download_bytes;
    }
    return *game.download_bytes - std::min(*game.download_bytes, off) + free;
}

struct Collection {
    std::string id;
    std::string name;
    bool pinned = false;
    std::set<GameId> members;
};

struct UserLibrary {
    std::set<GameId> favorites;
    std::set<GameId> hidden;
    std::vector<Collection> collections;
    std::map<GameId, Compatibility> ratings;
    std::map<GameId, std::string> notes;
    std::string query;
    std::string scope = "all";
    std::string sort = "name";
    // The order "More" on Continue playing shows (most recently played first) while the Library,
    // or a game opened from it, is on screen. Never saved: `sort` stays the player's own choice.
    std::string view_sort;
    std::set<std::string> filters;
};

struct Installation {
    GameId game_id;
    std::string volume_id;
    std::uint64_t installed_bytes = 0;
    bool available = true;
    bool runtime_ready = true;
    bool saves_present = true;
    std::int64_t installed_at = 0;  // live: when it was installed (Unix seconds), 0 unknown; Home's Recently installed
};

struct Job {
    std::string id;
    GameId game_id;
    std::string kind = "install";
    int queue_order = 0;
    JobStage stage = JobStage::Download;
    JobState state = JobState::Queued;
    std::uint64_t completed_bytes = 0;
    std::uint64_t total_bytes = 0;
    std::optional<std::uint64_t> bytes_per_second;
    std::optional<int> eta_seconds;
    std::string failure;
    JobStage retry_stage = JobStage::Download;
    std::string volume_id;
    int stage_ticks = 0;
    std::uint64_t reserved_bytes = 0;
    bool reservation_held = false;
    bool completion_applied = false;
    std::uint64_t held_bytes = 0;  // live: installed bytes already on the drive
    std::optional<std::uint64_t> estimated_bytes;  // live: what the job was asked with
    std::int64_t finished_at = 0;  // live: when a Downloaded job finished (Unix seconds), 0 unknown
    bool checking_licenses = false;  // live: a slow Steam license check before the download starts
    std::string server_name;  // live, while downloading: the download server's display name
    bool update = false;  // an installed game's update (kind stays "install": a game's download)
    bool locked = false;  // the update is putting its files in place, or the move must finish: Play waits for it
    bool move = false;    // an installed game moving to volume_id from from_volume_id: Play waits while it runs
    std::string from_volume_id;
    // A job that is not a game's (the Playden update): its title and the words for its stage and state.
    std::string title;
    std::string stage_text;
    std::string state_text;
};

// The size to show for a game that isn't installed: what its running install was asked with, else the sheet's defaults.
[[nodiscard]] inline std::optional<std::uint64_t> uninstalled_size(const Game& game, const std::vector<Job>& jobs) {
    for (const auto& job : jobs)
        if (job.game_id == game.id && job.estimated_bytes && job.state != JobState::Failed && job.state != JobState::Cancelled)
            return job.estimated_bytes;
    return default_install_bytes(game);
}

struct Volume {
    std::string id;
    std::string label;
    std::uint64_t capacity_bytes = 0;
    std::uint64_t used_bytes = 0;
    std::uint64_t reserved_bytes = 0;
    bool available = true;
    bool writable = true;
    std::uint64_t base_used_bytes = 0;
    std::uint64_t base_reserved_bytes = 0;
    bool capacity_known = true;    // false when the storage query did not return capacity and free space
    std::uint64_t games_bytes = 0; // live: bytes of finished installs on this volume
};

struct ModalEntry {
    std::string id;
    std::string title;
    std::string opener_focus_key;
    std::vector<std::string> action_keys;
    int focused_action = 0;
    bool destructive = false;
    std::string body;  // explanatory text; empty uses the simulation's default wording
    std::string setting_id;  // Game settings picker: the catalogue setting being chosen
    std::string link;  // a web page the dialog shows as a QR code with its address (release notes)
};

struct Navigation {
    Route route = Route::Startup;
    Route detail_origin = Route::Library;
    std::optional<GameId> detail_id;
    std::vector<ModalEntry> modals;
    std::string focus_key = "startup-connect";
    std::map<std::string, int> scroll_offsets;
    GameId selected_game_id;
    int selected_index = 0;
    int home_shelf = 0;
    std::map<std::string, int> home_shelf_focus;
    bool library_rail_focused = false;
    bool settings_rail_focused = false;
    int library_grid_column = 0;
    // The Home/Library/Downloads/Saves/Settings bar has focus (Up from the top of a page), and
    // which tab is focused there: 0 Home, 1 Library, 2 Downloads, 3 Saves, 4 Settings.
    bool tabs_focused = false;
    int tab_focus = 0;
    // Saves tab: the filter (0 All, 1 Needs you, 2 In sync, 3 This console only, 4 Not installed)
    // and the game its details page shows.
    int saves_filter = 0;
    GameId save_id;
    ManageTab manage_tab = ManageTab::Uninstall;  // Manage installed games: the open tab
};

struct EditorState {
    bool active = false;
    std::string purpose;
    std::string value;
    std::string original;
    std::string opener_focus_key;
    std::size_t caret = 0;
    bool shifted = false;
    bool symbols = false;
    bool secret = false;    // a password: shown as dots, never snapshotted
    bool revealed = false;  // the keyboard's Show key; reset each time the editor opens
    std::uint64_t serial = 0;  // tells each opened editor apart (the PS5 offers each one to its system keyboard)
    bool system_keyboard = false;  // the PS5's keyboard is (about to be) open for it: Playden's own is not drawn
    int focus_row = 0;
    int focus_key = 0;
};

struct Notice {
    std::string id;
    std::string message;
    std::string action;
    bool persistent = false;
    int remaining_ticks = 0;  // simulation ticks; live mode counts wall-clock seconds while visible
    bool failure = false;     // drawn with the failure tone
    std::string detail;       // second line; when empty the action key is shown, as fixtures expect
    bool alert = true;        // a live failure waits in a dialog for OK; false keeps it a corner notification
    float progress = -1.0F;   // 0 to 1: a corner notification draws a bar; below 0 it has none
};

struct ControllerState {
    float left_x = 0.0F;
    float left_y = 0.0F;
    float right_x = 0.0F;
    float right_y = 0.0F;
    float l2 = 0.0F;
    float r2 = 0.0F;
    bool cross = false;
    bool circle = false;
    bool square = false;
    bool triangle = false;
    bool l1 = false;
    bool r1 = false;
    bool options = false;
};

struct State {
    // Each store's account. Steam's has its own sign-in screens (sign_in, sign_in_password below).
    std::map<Store, Account> accounts;
    Account& account(Store store = Store::kSteam) { return accounts[store]; }
    const Account& account(Store store = Store::kSteam) const {
        static const Account none;
        const auto found = accounts.find(store);
        return found == accounts.end() ? none : found->second;
    }
    std::uint64_t account_generation = 1; // Invalidates account-scoped presentation resources.
    std::vector<Game> games;
    UserLibrary library;
    std::vector<Installation> installations;
    std::vector<Job> jobs;
    std::vector<Volume> volumes;
    std::string default_volume_id;  // live: where new installs go
    std::map<GameId, LiveCloudGame> cloud;  // live: Steam Cloud save state by game
    std::map<GameId, LiveRuntimeGame> runtime_games;  // live: per-game runtime state
    PreparationQueue preparation_queue;                 // live: games being prepared, waiting and done
    std::vector<EndedUninstall> ended_uninstalls;       // live: this session's, newest first; one stop per game
    // Queue: the section the player expanded ("downloads", "preparation"), "none" once they closed it;
    // empty until they choose.
    std::string queue_expanded;
    std::size_t runtime_leftover_requests = 0;          // live: unused settings requests to clean up
    LiveKitInfo kit;                                    // live: the runtime kit in use
    LiveSelfUpdate self_update;                         // live: Playden's own update
    std::vector<LiveLeftoverTitle> leftover_titles;
    std::vector<LiveLeftoverDelete> leftover_deletions;
    std::vector<LiveKeptBottle> kept_bottles;           // live: saves kept from uninstalled games
    std::vector<LiveExternalGame> external_games;       // live: games playing in place (imported)
    std::map<GameId, std::string> also_on_drives;       // live: a game's folder is on this USB volume too
    std::vector<LiveImportCandidate> import_candidates; // live: folders on the drives that could be imported
    bool import_scanning = false;                       // live: Playden is looking for games to import
    LiveSavesJob saves_job;                             // live: the Saves tab's running check or Sync all
    UpdateCheckState update_check;                      // live: installed games' updates, the signed-in account's
    std::map<GameId, std::uint64_t> save_sizes;         // live: Windows user folders of games without Steam Cloud
    Navigation navigation;
    EditorState editor;
    // The Steam account's sign-in screen and its preference: the last sign-in used the account name and password.
    SignInForm sign_in;
    bool sign_in_password = false;
    bool stay_signed_in = true;       // preference: keep Steam's sign-in token on the PS5 (else memory only)
    std::vector<Notice> notices;
    // Per-game settings: preset and player overrides (see runtime/game_settings.h).
    std::map<GameId, playden::runtime::GameSettingsRecord> game_settings;
    SessionState session = SessionState::Idle;
    RuntimeState runtime = RuntimeState::Unavailable;
    std::string runtime_problem;  // why games can't be prepared or played, in words a person can act on
    // Live: started without the root grant, so only the "Root access is missing" screen shows.
    bool root_access_missing = false;
    std::string root_access_detail;  // the startup error, shortened
    bool root_access_granted = false;  // the grant succeeded; its data in /data/playden failed
    LogState log_state = LogState::Ready;
    std::vector<std::string> log_lines;
    int log_offset = 0;
    std::string log_context;
    GameId session_game_id;
    std::string session_error;
    bool reduced_motion = false;
    bool title_store_suffix = false;  // PS5 titles named "<game> (Steam)"
    bool cloud_saves_auto = false;    // Cloud saves move before Play, after sessions and at startup (opt-in)
    bool beta_updates = false;
    // The language games are downloaded in, as Steam names its depot languages ("german").
    std::string content_language{playden::steam::kDefaultContentLanguage};
    bool downloads_slow_network = false;  // 8 download pieces at a time instead of 4 (Settings › Storage)
    // Empty: Steam default (Steam's order); kFastestDownloadServer: Fastest (raced at each download); otherwise
    // the chosen provider's stable identifier.
    std::string download_server;
    bool hide_run_once_help = false;  // "Don't show again" on Run launcher or setup's dialog
    std::string runtime_prompt_kit;  // the kit whose runtime kit prompt was answered (its manifest SHA-256)
    bool hide_launcher_help = false;  // ...and on the one for turning on Start through a launcher
    bool web_access = true;  // Settings › Web access: the logs and game files page on the local network (on by default)
    std::string web_pairing_code;  // live: a browser asked to pair; shown in a corner over every screen
    bool controller_connected = true;
    ControllerState controller;
    bool persistence_available = true;
    bool library_syncing = false;
    bool startup_loading = false;
    bool library_loading = false;
    bool library_offline = false;
    bool screenshot_mode = false;
    bool quit_requested = false;
    bool quit_waiting = false;  // a quit to Home waits for a preparation; no new one starts meanwhile
    bool simulation_mode = true;
    std::int64_t clock_ticks = 0;
};

struct ViewRow {
    std::string key;
    RowKind kind = RowKind::Action;
    std::string title;
    std::string subtitle;
    std::string value;
    std::string badge;
    std::string action;
    GameId game_id;
    float progress = 0.0F;
    bool enabled = true;
    bool selected = false;
    bool dangerous = false;
    bool modified = false;  // Game settings: the player changed this value
    bool checked = false;   // a sheet's pick-one row (the sort): the current choice, an accent tick
    std::string section;  // Settings: the rail section the row belongs to
    std::string tone;     // Saves: the status colour (good, busy, attention, problem, quiet)
    std::string aside;    // Saves: the right-hand note (size, last sync)
    bool rail_only = false;  // Settings: the section's rail entry is the action (Quit Playden), no card
    std::string qr;          // Settings: a link drawn as a QR code beside the row's text (Web access)
};

// A read-only label and value above a sheet's rows; the focus never goes there.
struct ViewFact {
    std::string label;
    std::string value;
    bool warn = false;
    bool operator==(const ViewFact& other) const { return label == other.label && value == other.value && warn == other.warn; }
};

struct ViewData {
    std::vector<ViewFact> facts;
    std::string surface;
    std::string title;
    std::string subtitle;
    std::string eyebrow;  // a sheet's label above its title; empty: the sheet's place (view.cpp)
    std::vector<ViewRow> rows;
    // Manage installed games: its tabs (selected: the open one; value: the count badge) and each drive's free space.
    std::vector<ViewRow> tabs;
    std::string aside;
    std::vector<ViewRow> actions;
    struct Shelf {
        std::string key;
        std::string title;
        std::vector<ViewRow> items;
        int focused_item = -1;
    };
    std::vector<Shelf> shelves;
    std::vector<std::string> legends;
    std::string footer;  // a sheet's pinned footer note (Installed games: the selection or the batch)
    int focused_row = 0;
    int focused_action = 0;
    std::size_t total_count = 0;
    std::size_t first_index = 0;
    bool show_simulation_label = true;
    std::string tone;  // Saves details: the status colour
    // Preset chooser: the focused preset's name and hint, each setting it changes as
    // {setting, current value, value with the preset}, and a closing line.
    struct Comparison {
        std::string title;
        std::string hint;
        std::vector<std::array<std::string, 3>> rows;
        std::string note;
    };
    std::optional<Comparison> comparison;
};

// Characters a Details description page holds: live pages have status lines above it.
inline std::size_t DetailsDescriptionPage(bool simulation_mode) { return simulation_mode ? 300 : 200; }

// Player words for a preparation journal step ("copy-template" → "Copying the Windows environment").
std::string PreparationStepWords(const std::string& step);
// Where a preparation stands, for the player: "Step 3 of 6 · Copying the Windows environment".
// No record yet (the PS5 title is being reserved) is step 1.
inline constexpr int kPreparationSteps = 6;
int PreparationStepNumber(const std::string& step);
std::string PreparationProgressWords(bool has_record, const std::string& step);

// A job's state for the player ("Downloading", "Paused", "Complete"…): its own words when it has them
// (the Playden update), and "Copying" while an imported game is copied into Playden.
std::string JobStateText(const Job& job);

class Simulation {
public:
    Simulation(std::filesystem::path fixture_directory, std::filesystem::path profile_path,
               ModelMode mode = ModelMode::Simulation);

    bool scenario(const std::string& name);
    // repeat: the step comes from a held direction, not a new press (a side menu stops at its ends).
    bool action(const std::string& logical_action, bool repeat = false);
    void controller_sample(ControllerState sample);
    void text(const std::string& utf8);
    // The PS5 system keyboard's accepted text replaces the open editor's value and commits it, as Done does.
    void SubmitEditorText(std::string utf8);
    void SetSystemKeyboardOpen(bool open) { state_.editor.system_keyboard = open && state_.editor.active; }
    // The PS5 offers every field to its system keyboard: fields open with Playden's keyboard hidden
    // until that one is refused (SetSystemKeyboardOpen(false)).
    void SetSystemKeyboardAvailable(bool available) { system_keyboard_available_ = available; }
    void tick(int ticks = 1);
    void SetControllerConnected(bool connected);
    void SetWallClock(std::int64_t unix_seconds);
    void UpdateAccount(AccountUpdate update);
    // Another store has a signed-in account or games: Steam's sign-in screen need not take over.
    [[nodiscard]] bool HasGamesBeyondSteam() const { return beyond_steam(); }
    bool UpdateLibrary(LibraryUpdate update);
    // Live mode: requests for the real install service, and its state for display.
    [[nodiscard]] std::vector<InstallRequest> TakeInstallRequests();
    // Live mode: the exact sizes the install sheet asks for, and the answers. `measured` false: Steam's figures
    // stand (nothing to check, or the check failed; `failed` lets the sheet ask again when it opens next).
    [[nodiscard]] std::vector<SizeCheckRequest> TakeSizeChecks();
    void UpdateMeasuredSize(const SizeCheckRequest& request, bool measured, bool failed, MeasuredInstallSize size);
    // Live mode: installed games whose update has no measured size yet, each asked once for what it updates to;
    // and the answers. `target` is the selection measured: a size for another one than the saved update's is
    // dropped. Not measured (the network, a full queue): the size stays unknown until Steam answers for the
    // game again. True when Steam should be asked about the game again (a size for a newer update than the
    // one listed), once per update measured.
    [[nodiscard]] std::vector<GameId> TakeUpdateSizeChecks();
    bool UpdateMeasuredUpdate(GameId id, bool measured, std::uint64_t target, std::uint64_t download_bytes,
                              std::uint64_t staged_bytes);
    // The details service dropped what it was asked (another account, or the language changed): checks
    // still waiting for an answer are asked again.
    void ResetSizeChecks();
    void UpdateInstalls(const std::vector<LiveInstallJob>& jobs, const std::vector<LiveInstalledGame>& installed,
                        const std::vector<LiveCompletedDownload>& completed = {});
    // Live mode: Steam Cloud save requests for the cloud service, and its state for display.
    [[nodiscard]] std::vector<CloudRequest> TakeCloudRequests();
    void UpdateCloud(const std::vector<LiveCloudGame>& games);
    // Live mode: the Saves tab's running job, and the size of saves of games without Steam Cloud.
    void UpdateSavesJob(LiveSavesJob job);
    void UpdateSaveSizes(std::map<GameId, std::uint64_t> sizes);
    // Live mode: the answer to a Cloud request the player made (its settled result), or its refusal
    // (the game's title may run). Play waiting to quit to Home goes on from these.
    void NotifyCloudAnswered(GameId id, CloudStatus status);
    void NotifyCloudRefused(GameId id);
    // Live mode: games to prepare (bottle + PS5 title), and the runtime state for display.
    [[nodiscard]] std::vector<GameId> TakeRuntimePrepareRequests();
    // Queues Prepare without a button press: after a download, or before Play.
    void RequestRuntimePrepare(GameId id);
    [[nodiscard]] std::vector<GameId> TakeRuntimePlayRequests();
    // Verbose or input logging lasts one session: back to Normal for the game's next start, as this one starts.
    void EndOneSessionLogging(GameId id);
    // The Play requests above that run a program from the game folder once instead of the game (Run a program
    // once…): the program, relative to the game folder. A plain Play request of the same game replaces its entry.
    [[nodiscard]] std::map<GameId, std::string> TakeRuntimeSetupPrograms();
    [[nodiscard]] bool TakeRuntimeCleanupRequest();
    // Live mode: kept game data, deletions the player confirmed, and why an uninstall stopped.
    void UpdateKeptBottles(std::vector<LiveKeptBottle> kept);
    void UpdateLeftoverTitles(std::vector<LiveLeftoverTitle> titles);
    void UpdateLeftoverDeletions(std::vector<LiveLeftoverDelete> deletions);
    [[nodiscard]] std::vector<std::string> TakeLeftoverDeleteRequests();
    // Live mode: games playing in place, and what the drives offer to import.
    void UpdateExternalGames(std::vector<LiveExternalGame> games);
    void UpdateAlsoOnDrives(std::map<GameId, std::string> drives);
    // Games being published again in the background after a USB drive changed places.
    void UpdateDriveUpdates(std::size_t done, std::size_t total, std::size_t failed = 0);
    void UpdateImportCandidates(std::vector<LiveImportCandidate> candidates, bool scanning);
    // Live mode: requests for the Local store (the Import sheet, the dev request file).
    void RequestImport(ImportRequest request);
    [[nodiscard]] std::vector<ImportRequest> TakeImportRequests();
    // Live mode: a request from TakeImportRequests that the Local store refused (an add, copy, move
    // or removal), with its sentence for the player: shown as a notice, and what waited on it dropped.
    void NotifyImportFailed(const ImportRequest& request, const std::string& message);
    // Writes the program an imported game starts with into its Game settings when the game has no
    // saved settings yet (just added); never over anything the player changed, a reset Program
    // included. Saved at once so the next preparation reads it. True when it was written.
    bool SeedGameProgram(GameId id, const std::string& program);
    [[nodiscard]] std::vector<GameId> TakeKeptDeleteRequests();
    // Live mode: maintenance the player confirmed (and settings to apply when the sheet
    // closes), and games whose title activity the sheet needs to know.
    [[nodiscard]] std::vector<std::pair<GameId, MaintenanceKind>> TakeMaintenanceRequests();
    [[nodiscard]] std::vector<GameId> TakeActivityRequests();
    void NotifyUninstallStopped(GameId id, const std::string& reason);
    // A move or an update the install service refused when it was asked (InstallRequestKind::Move, ::Update).
    void NotifyMoveRefused(GameId id, const std::string& reason);
    void NotifyUpdateRefused(GameId id, const std::string& reason);
    // The uninstall is over: the game's PS5 title and files are gone. Queue lists it as done.
    void NotifyUninstallFinished(GameId id);
    // Play prepared the game first and that ended without a playable title.
    void NotifyPlayStopped(GameId id, const std::string& reason);
    // Play updated the game's title to the installed kit's runtime and left it there: asks whether to start it.
    void NotifyRuntimeUpdated(GameId id);
    // The game's last run tried to start this program and couldn't: offers launcher mode.
    // False until the game is known, so the caller tells it again.
    bool NotifyLauncherHint(GameId id, const std::string& program);
    // A preparation the player started left the game waiting for the PS5: ask, when
    // nothing else is open, whether to quit to the PS5 Home screen to play it.
    void NotifyReadyToPlay(GameId id);
    void SetRuntimeLeftovers(std::size_t count);
    void SetKitInfo(LiveKitInfo kit);
    void UpdateRuntime(RuntimeState runtime, const std::vector<LiveRuntimeGame>& games);
    // Live mode: the preparation queue for Queue, and what the player asked of it there: games to
    // prepare next, finished preparations dismissed, and Clear completed.
    void UpdatePreparationQueue(PreparationQueue queue);
    [[nodiscard]] std::vector<GameId> TakePrepareNextRequests();
    [[nodiscard]] std::vector<LiveCompletedPreparation> TakePreparedDismissals();
    [[nodiscard]] bool TakePreparedClear();
    // The game runtime could not start (raw: its log reason; empty: it runs). Shown on every screen
    // until it is fixed, with the reason under Settings › Runtime status (#64).
    void UpdateRuntimeProblem(const std::string& raw);
    // Live mode: a one-line note from startup's data layout move (a step held back this start).
    void ShowLayoutNotice(const std::string& text);
    // Live mode: startup got no root grant (raw: NativeAccessResult::error). Shows only the
    // "Root access is missing" screen; its one action quits to Home (quit_requested).
    // granted: the grant succeeded but Playden can't use /data/playden (other words, same screen).
    void ShowRootAccessMissing(const std::string& raw, bool granted = false);
    // Live mode: Playden's own update, and what the player asked of it: "check" (from Settings),
    // "install", "cancel", "restart" (apply at quit; quit follows), "rollback" (put the previous
    // version back at quit; quit follows) and "acknowledge" (a finished update's message was shown).
    void UpdateSelfUpdate(const LiveSelfUpdate& update);
    [[nodiscard]] std::vector<std::string> TakeSelfUpdateRequests();
    void ApplyLiveDownloadServers(const LiveDownloadServers& snapshot);
    void ApplyLiveWebAccess(const LiveWebAccess& snapshot);
    // Quit Playden from outside the UI (web access). A game being prepared or queued is waited for, with the
    // dialog the TV shows then, since nobody may be in front of the TV to see a half-made title.
    void RequestQuit();
    [[nodiscard]] std::vector<DownloadServerRequest> TakeDownloadServerRequests();
    // Live mode: the folder holding install.log, auth.log and launch.log for the log viewer.
    void SetLogDirectory(std::filesystem::path directory);
    // Live mode: the drives installs can use and the one new installs go to.
    // default_volume_saved false: the drive choice couldn't be written and lasts until Playden closes.
    void UpdateVolumes(const std::vector<LiveVolume>& volumes, const std::string& default_volume_id,
                       bool default_volume_saved = true);
    // False on a console that cannot read free space at all: installs are then allowed without it.
    void SetFreeSpaceSupported(bool supported) noexcept { free_space_supported_ = supported; }
    // Live mode: Steam app-info estimates for one game (download/install size, installability).
    // `languages`: the content languages the game carries, as Steam names them. `dlc`: the DLC with
    // files an install can leave out, which the install sheet lists. `versions`: the versions an
    // install can choose, public first. `update`: an installed game's update or new DLC, which the account's
    // saved update list takes only when `updates_known` (the library refresh has read the licenses).
    bool UpdateAppDetails(GameId id, std::optional<std::uint64_t> download_bytes,
                          std::optional<std::uint64_t> install_bytes, std::optional<bool> windows_installable,
                          std::vector<std::string> languages = {}, std::vector<GameDlc> dlc = {},
                          std::vector<GameVersion> versions = {}, GameUpdate update = {}, bool updates_known = true);
    // Live mode: the Steam store's description, genres and controller support for one game;
    // kept across library refreshes.
    void UpdateStoreDetails(GameId id, std::string description, std::vector<std::string> genres,
                            std::string controller_support);
    PersistenceLoadToken BeginOrganizationLoad(std::uint64_t account);
    bool ApplyOrganization(std::uint64_t account, PersistenceLoadToken token,
                           std::optional<playden::OrganizationSnapshot> loaded);
    bool FailOrganizationLoad(std::uint64_t account, PersistenceLoadToken token,
                              playden::StorageError error);
    void OrganizationCleared(std::uint64_t account);
    PersistenceLoadToken BeginPreferencesLoad();
    // Live mode: the update check of installed games, saved per Steam account. BeginUpdateCheckLoad: that
    // account's saved check is read next (ApplyUpdateCheck; nothing saved: an empty optional). Reset: no account.
    void BeginUpdateCheckLoad(std::uint64_t account);
    void ApplyUpdateCheck(std::uint64_t account, std::optional<playden::SavedUpdateCheck> saved);
    void ResetUpdateCheck();
    [[nodiscard]] std::uint64_t UpdateCheckAccount() const noexcept { return update_check_account_; }
    [[nodiscard]] std::uint64_t UpdateCheckRevision() const noexcept { return update_check_revision_; }
    // Loaded, and changed since the last save that worked.
    [[nodiscard]] bool UpdateCheckDirty() const noexcept;
    [[nodiscard]] playden::SavedUpdateCheck ExportUpdateCheck() const;
    void UpdateCheckSaveResult(std::uint64_t account, std::uint64_t revision, playden::StorageError error);
    // A check the controller should start: the player asked, or the screen opened a day after the last one.
    [[nodiscard]] bool TakeUpdateCheckRequest();
    // The running check's progress, in games; Finish ends it. `failed`: Steam gave no answer for some games,
    // so the time of the last full check stays and their saved results stand.
    void UpdateCheckProgress(std::size_t asked, std::size_t answered, std::size_t total);
    void FinishUpdateCheck(bool failed);
    bool ApplyPreferences(PersistenceLoadToken token,
                          const playden::PreferencesLoadResult& loaded);
    [[nodiscard]] playden::OrganizationSnapshot ExportOrganization() const;
    [[nodiscard]] playden::Preferences ExportPreferences() const;
    [[nodiscard]] std::uint64_t OrganizationAccount() const noexcept { return organization_account_; }
    [[nodiscard]] std::uint64_t OrganizationRevision() const noexcept { return organization_revision_; }
    [[nodiscard]] std::uint64_t PreferencesRevision() const noexcept { return preferences_revision_; }
    [[nodiscard]] bool OrganizationDirty() const noexcept;
    [[nodiscard]] bool PreferencesDirty() const noexcept;
    // The saved preferences have been read (or found missing), so a setting such as web access is the player's.
    [[nodiscard]] bool PreferencesLoaded() const noexcept { return preferences_loaded_; }
    [[nodiscard]] bool OrganizationReadyForSave() const noexcept;
    void OrganizationSaveResult(std::uint64_t account, std::uint64_t revision,
                                playden::StorageError error);
    void PreferencesSaveResult(std::uint64_t revision, playden::StorageError error);
    bool TakePersistenceRetryRequest();
    [[nodiscard]] std::vector<ServiceRequest> TakeServiceActions();
    // The password sign-in's secrets, handed over once; the form keeps no copy of the password.
    [[nodiscard]] std::optional<SignInCredentials> TakeSignInCredentials();
    [[nodiscard]] std::optional<std::string> TakeGuardCode();
    // Presets and recipes for the Game settings sheet (runtime/presets.json, runtime/recipes/).
    void SetSettingsData(std::vector<playden::runtime::SettingsPreset> presets,
                         std::vector<playden::runtime::GameRecipe> recipes);
    void SetKitCapabilities(playden::runtime::KitCapabilities kit);
    // Live mode: where per-game settings are kept (loaded now, saved on every change).
    void SetGameSettingsFile(std::filesystem::path path);
    // The recipe and effective settings the sheet shows for a game.
    // Recipes the runtime generated from Steam launch options; a shipped recipe wins.
    void SetGeneratedRecipes(const std::vector<playden::runtime::GameRecipe>& recipes);
    // Live: each game's programs and, for a refused game, its draft recipe (RecipeFor uses it).
    void SetGameSetups(std::map<GameId, LiveGameSetup> setups);
    // Live: games whose folder the Program picker needs scanned.
    [[nodiscard]] std::vector<GameId> TakeProgramScanRequests();
    // Where "Export as recipe" writes recipe-<app id>.json, and the console's firmware for its metadata.
    void SetRecipeExportTarget(std::filesystem::path directory, std::string firmware);
    [[nodiscard]] const playden::runtime::GameRecipe& RecipeFor(GameId id) const;
    [[nodiscard]] bool EffectiveSettingsFor(GameId id, playden::runtime::EffectiveSettings* settings) const;
    // Whether Game settings lists "Known problems" (Try anyway) for a game.
    [[nodiscard]] bool known_problem(GameId id) const;
    void follow_refresh_rate(GameId game);
    [[nodiscard]] bool game_settings_row_shown(const playden::runtime::SettingDefinition& definition, GameId game) const;
    // The overrides a preset change or a reset keeps: the program choices (simulation.cpp).
    [[nodiscard]] std::map<std::string, std::string> kept_start_choices(GameId id) const;
    // Opens the picker, editor or "Change anyway" for one Game settings row.
    void open_setting(const std::string& id);
    // The actions of a row whose value the recipe starts (edit, reset, library override entries).
    [[nodiscard]] std::vector<std::string> setting_value_actions(const std::string& id) const;
    // "Export as recipe": the game's effective settings as recipe-<app id>.json for a pull request.
    void export_recipe(GameId id);

    [[nodiscard]] const State& state() const noexcept { return state_; }
    [[nodiscard]] const ViewData& view() const noexcept { return view_; }
    [[nodiscard]] const ViewData& route_view() const noexcept { return route_view_; }
    [[nodiscard]] std::vector<const Game*> visible_games() const;
    [[nodiscard]] std::string snapshot() const;
    [[nodiscard]] const std::string& last_error() const noexcept { return last_error_; }

private:
    std::filesystem::path fixture_directory_;
    std::filesystem::path profile_path_;
    ModelMode mode_ = ModelMode::Simulation;
    State state_;
    ViewData view_;
    ViewData route_view_;
    std::string last_error_;
    std::string pending_destructive_action_;
    // The game a live Uninstall or Remove from library confirmation acts on, fixed when it opens.
    std::optional<GameId> destructive_target_;
    std::vector<std::string> self_update_requests_;
    LiveDownloadServers download_servers_;
    std::vector<DownloadServerRequest> download_server_requests_;
    bool download_server_focus_choice_ = false;
    bool download_server_cancel_pending_ = false;
    bool download_server_test_requested_ = false;
    bool download_server_fixture_ = false;
    std::size_t drive_updates_done_ = 0, drive_updates_total_ = 0;  // what the corner notification last said
    bool manage_fixture_ = false;  // a Manage installed games scenario: Settings shows its rows in the fixture
    void refresh_download_servers(const std::string& focus = {});
    [[nodiscard]] std::string best_tested_download_server() const;
    [[nodiscard]] std::string download_server_choice_key() const;
    [[nodiscard]] bool download_server_test_allowed() const;
    std::string self_update_prompted_;   // "available 0.3.0" or "staged 0.3.0": each prompt shows once
    std::string pending_update_prompt_;  // a prompt waiting for the open dialog to close
    bool kit_prompted_ = false;          // the kit was offered since its last check (a cancel doesn't offer it again)
    void show_update_prompt();
    void sync_self_update_job();
    void request_self_update_restart(const std::string& request = "restart");
    void close_game_modals();
    void open_release_notes(bool after_update);
    std::string selected_volume_id_;
    bool default_volume_saved_ = true;  // last install-service report, so a failed save is said once
    // Live: the drive chosen in the install sheet for this one install (empty: the default drive),
    // and whether the open storage picker chooses it rather than the default.
    std::string install_volume_id_;
    bool picking_install_volume_ = false;
    // Live: the content language chosen in the install sheet for this one install (empty: the one the
    // Settings download language resolves to for the game).
    std::string install_language_;
    std::map<std::uint32_t, bool> install_dlc_choice_;  // what the install sheet's player changed (on?), for this install only
    bool page_under_install_sheet_ = false;  // while the page behind the install sheet is built
    // Live: the version (branch) chosen in the install sheet for this one install (empty: public).
    std::string install_version_;
    bool free_space_supported_ = true;
    std::vector<playden::runtime::SettingsPreset> settings_presets_;
    // Shipped and generated recipes by game (runtime::RecipeGame).
    std::map<GameId, playden::runtime::GameRecipe> recipes_;
    std::map<GameId, playden::runtime::GameRecipe> generated_recipes_;
    mutable std::map<GameId, playden::runtime::GameRecipe> simulated_recipes_;
    playden::runtime::KitCapabilities kit_;
    std::set<std::string> expanded_settings_sections_;
    std::string editing_setting_id_;
    bool editing_append_ = false;  // the editor adds one library override to the list
    std::map<GameId, LiveGameSetup> game_setups_;
    std::vector<GameId> pending_program_scans_;
    std::set<GameId> requested_program_scans_;
    std::filesystem::path recipe_export_directory_;
    std::string console_firmware_;
    std::filesystem::path game_settings_file_;
    std::map<GameId, playden::runtime::GameSettingsRecord> saved_game_settings_;
    bool settings_save_failed_ = false;
    bool settings_load_failed_ = false;
    std::optional<playden::runtime::GameSettingsRecord> settings_opened_record_;  // for the close toast
    std::string editing_target_id_;
    std::uint64_t challenge_generation_ = 0;
    std::uint64_t cancelled_challenge_generation_ = 0;
    std::uint64_t next_collection_serial_ = 1;
    std::uint64_t next_job_serial_ = 1;
    bool controller_seen_ = false;  // a connected controller has been reported this run
    std::vector<ServiceRequest> pending_service_actions_;
    std::optional<SignInCredentials> pending_credentials_;
    std::optional<std::string> pending_guard_code_;
    std::uint64_t editor_serial_ = 0;
    bool system_keyboard_available_ = false;
    std::vector<InstallRequest> pending_install_requests_;
    std::vector<ImportRequest> pending_import_requests_;
    std::vector<GameId> pending_runtime_prepare_requests_;
    std::vector<GameId> pending_prepare_next_requests_;
    std::vector<LiveCompletedPreparation> pending_prepared_dismissals_;
    bool pending_prepared_clear_ = false;
    // Asked of the runtime and not carried out yet: finished preparations dismissed, a game moved first.
    std::vector<LiveCompletedPreparation> prepared_dismissed_;
    std::optional<GameId> prepare_next_asked_;
    std::vector<GameId> pending_runtime_play_requests_;
    std::map<GameId, std::string> pending_runtime_setup_programs_;
    std::string setup_program_choice_;  // Run launcher or setup: the program the confirmation names
    bool pending_runtime_cleanup_ = false;
    bool library_catalog_received_ = false;
    std::set<Store> catalog_sources_;  // stores whose library arrived at least once
    // The sign-in screen shows because Steam's saved sign-in failed to restore, not for a sign-in the player started.
    bool restore_failed_sign_in_ = false;
    std::set<Store> loading_sources_;  // stores whose library is loading now
    // Live install events become notifications; the first snapshot is restored history, not an event.
    bool live_installs_seen_ = false;
    std::map<GameId, JobState> live_job_states_;
    std::set<GameId> live_update_jobs_;  // the live jobs that are updates, as last projected
    std::set<GameId> live_move_jobs_;    // the live jobs that are moves, as last projected
    std::set<GameId> canceled_updates_;  // updates the player canceled, until their job ends
    std::set<GameId> live_installed_ids_;
    std::set<GameId> pending_uninstalls_;
    std::vector<GameId> pending_kept_delete_requests_;
    std::vector<std::string> pending_leftover_delete_requests_;
    int leftover_delete_ticks_ = 0;
    std::vector<std::pair<GameId, MaintenanceKind>> pending_maintenance_requests_;
    std::vector<GameId> pending_activity_requests_;
    bool uninstall_delete_saves_ = false;  // the uninstall dialog's choice
    std::set<GameId> kept_selected_;  // the kept game data manager's checked games
    std::set<std::string> leftover_selected_;  // the leftover titles manager's checked title IDs
    // Manage installed games: each tab's checked games, order and focus, kept while the screen is open.
    struct ManageTabState {
        std::set<GameId> selected;
        std::set<GameId> listed;  // Updates: games listed so far; each is checked when it first shows up
        bool by_played = false;   // false: largest first (download size on Updates); true: never played, then the oldest
        std::string focus;        // the row focused when the player switched away
        std::string list_focus;   // the game row the focus left for the footer
    };
    std::map<ManageTab, ManageTabState> manage_tabs_;
    Route manage_return_route_ = Route::Settings;  // where Circle returns: Settings, or the storage-full sign-in
    std::string manage_return_focus_;              // the row that opened the screen
    int manage_focus_index_ = 0;       // the focused row's place, to stay near it when that game goes
    // Games uninstalled together from the Installed games list: Queue follows them, so they post
    // no notice of their own when they finish, and a stop is a corner notice, not a dialog.
    std::set<GameId> batch_uninstalls_;
    std::map<GameId, std::string> uninstall_titles_;  // names of games being uninstalled, for once they are gone
    // Steam games still being uninstalled when their account signed out: how they end is not listed.
    std::set<GameId> previous_account_uninstalls_;
    std::string manage_message_;  // the Uninstall tab's note when a confirmed uninstall could not start
    // Move: the drive the checked games go to (each moves from where it is), and the game a drive is being
    // chosen for from its page's Maintenance (none: the Move tab's Move to).
    std::string manage_move_volume_id_;
    GameId move_picker_game_;
    std::string manage_move_from_id_;  // Move: only the games on this drive are listed; empty lists every drive
    std::string manage_uninstall_from_id_;  // Uninstall: only the games on this drive are listed; empty lists every drive
    bool rebuilding_overlay_ = false;  // rebuild_view is building the screen under an open sheet
    struct StoreFacts { std::string description; std::vector<std::string> genres; std::string controller_support; };
    std::map<GameId, StoreFacts> store_facts_;  // live: from the Steam store, applied over library refreshes
    std::vector<GameId> ready_prompts_;  // games to announce as ready to play, oldest first
    // settings_game: a game whose refusal Game settings can get past; the dialog offers it.
    struct AlertPrompt { std::string title; std::string body; GameId settings_game; bool launcher_hint = false; };
    GameId alert_settings_game_;  // the game the open failure dialog's "Game settings" opens
    // Games refused at Prepare whose program or "Try anyway" the player changed since: their page
    // no longer shows the old refusal.
    std::set<GameId> rechosen_after_refusal_;
    // Launches that stopped before their store's library arrived (a start from Home reported when Playden
    // starts): told once the game's name is known.
    std::map<GameId, std::string> pending_play_stops_;
    void tell_play_stopped(GameId id, const std::string& reason);
    // Game settings asked for on a game not set up yet: it opens once preparing makes a draft or a title.
    std::set<GameId> settings_after_prepare_;
    void open_settings_after_prepare();
    std::vector<AlertPrompt> alert_prompts_;  // failures waiting for an OK, oldest first
    std::filesystem::path log_directory_;
    std::vector<CloudRequest> pending_cloud_requests_;
    std::map<GameId, CloudStatus> settled_cloud_;  // each game's last settled Cloud state, for notices
    // The Runtimes tab's batch: the games still to send, in order, and the one at work. One at a time, so free space
    // is checked before each. Not kept across runs: what didn't finish stays listed on the tab.
    std::vector<std::pair<GameId, MaintenanceKind>> runtime_batch_;
    std::optional<std::pair<GameId, MaintenanceKind>> runtime_batch_current_;
    std::int64_t runtime_batch_sent_at_ = 0;
    std::size_t runtime_batch_total_ = 0;
    std::size_t runtime_batch_failed_ = 0;
    PreparationQueue runtime_queue_;  // the runtime's own queue, before the batch's waiting games are added to it
    GameId ready_prompt_game_;  // the game the "ready to play" dialog is about
    std::vector<GameId> update_ready_prompts_;  // games Play updated, whose "is ready" dialog hasn't opened yet
    GameId update_ready_game_;  // the game the open "is ready" dialog is about
    GameId quit_sync_game_;     // Play quits to Home once this game's saves are in step
    std::string quit_wait_title_;   // the dialog a quit to Home waits in while a game is prepared
    std::string live_log_topic_;
    GameId live_log_game_;
    bool details_primary_pending_ = false;  // live Details: move focus to the first action once known
    // Settings: the last focused row, so focus stays nearby when that row goes away.
    int settings_focus_index_ = 0;
    int queue_focus_index_ = 0;  // Queue: the focused row's place, for when that row goes away
    bool queue_shown_ = false;   // Queue was on screen at the last rebuild
    std::string queue_return_focus_;  // Queue: the row a game page was opened from, focused again on Back
    // Install sheet size checks by (game, branch, language): asked and not answered, and the answers.
    using SizeCheckKey = std::tuple<GameId, std::string, std::string, std::vector<std::uint32_t>>;
    std::vector<SizeCheckRequest> size_checks_;
    std::set<SizeCheckKey> size_checks_running_;
    std::set<SizeCheckKey> size_checks_answered_;
    std::set<SizeCheckKey> size_checks_failed_;  // not asked again until the sheet reopens
    std::map<SizeCheckKey, MeasuredInstallSize> measured_sizes_;
    std::string settings_focus_section_;

    struct OrganizationJournalEntry {
        playden::OrganizationSnapshot before;
        playden::OrganizationSnapshot after;
        bool reset = false;
        bool selected = false;
        std::size_t bytes = 0;
    };
    std::uint64_t next_persistence_load_token_ = 0;
    std::uint64_t organization_account_ = 0;
    std::uint64_t organization_revision_ = 0;
    std::uint64_t organization_saved_revision_ = 0;
    std::uint64_t preferences_revision_ = 0;
    std::uint64_t preferences_saved_revision_ = 0;
    PersistenceLoadToken organization_load_token_;
    PersistenceLoadToken preferences_load_token_;
    bool organization_load_pending_ = false;
    bool organization_load_failed_ = false;
    bool organization_save_failed_ = false;
    bool organization_journal_full_ = false;
    bool organization_save_suppressed_ = false;
    bool preferences_load_pending_ = false;
    bool preferences_loaded_ = false;
    LiveWebAccess web_access_;
    bool preferences_load_may_apply_ = false;
    bool preferences_load_failed_ = false;
    bool preferences_save_failed_ = false;
    bool persistence_retry_requested_ = false;
    bool force_organization_reset_ = false;
    bool force_organization_selection_ = false;
    bool force_preferences_reset_ = false;
    std::size_t organization_journal_bytes_ = 0;
    std::vector<OrganizationJournalEntry> organization_journal_;
    playden::OrganizationSnapshot captured_organization_;
    playden::OrganizationSnapshot persisted_organization_;
    playden::Preferences captured_preferences_;
    std::uint64_t update_check_account_ = 0;
    std::uint64_t update_check_revision_ = 0;
    std::uint64_t update_check_saved_revision_ = 0;
    bool update_check_requested_ = false;
    std::optional<bool> update_check_waiting_;  // asked (true: by the player) before the saved check was read
    std::map<GameId, GameUpdate> update_check_early_;  // results before the saved check was read
    std::map<GameId, std::uint64_t> update_sizes_running_;          // asked, with the target then saved
    std::set<std::pair<GameId, std::uint64_t>> update_sizes_ended_;  // answered without a size: not asked again
    std::set<std::pair<GameId, std::uint64_t>> update_sizes_newer_;  // measured targets Steam was asked about again
    // An update's size as the screens say it: the download, "Checking size…" while it is measured, else "Size unknown".
    [[nodiscard]] std::string update_size_text(GameId id) const;

    // The screen opened (`forced` false: only a day after the last full check) or Check for updates.
    void request_update_check(bool forced);
    // A game's update as Steam answered it: kept when there is one, dropped otherwise.
    void set_saved_update(GameId id, const GameUpdate& update);
    void load_fixtures();
    void load_profile();
    bool save_profile();
    GameId import_page_asked_;  // the imported game whose open page has asked whether it runs
    void reset_default_state();
    void rebuild_view();
    void activate();
    void cancel();
    void move(int delta_x, int delta_y, bool repeat = false);
    void move_content(int delta_x, int delta_y);
    [[nodiscard]] bool tab_bar_shown() const;
    bool move_settings(int delta_x, int delta_y);
    bool move_saves(int delta_x, int delta_y);
    // The Saves tab's games, in name order, after the filter when `filtered`.
    [[nodiscard]] std::vector<GameId> save_games(bool filtered) const;
    [[nodiscard]] std::vector<GameId> saves_awaiting_account() const;
    void ask_upload_all();
    void open_saves();
    void settle_quit_sync(GameId id, std::optional<CloudStatus> status);
    void quit_to_home();
    void change_route(int delta);
    void open_modal(ModalEntry modal);
    void prepare_next(GameId id);
    void close_modal();
    void open_details_from_queue(GameId id);
    void start_editor(std::string purpose, std::string value, bool secret = false);
    // Sign-in screen: opened in the remembered method, its actions, and the form's secrets wiped.
    void open_sign_in(bool reauthenticate = false);
    bool sign_in_action(const std::string& action_name);
    void submit_fixture_sign_in();
    void clear_sign_in_secrets();
    void set_route_focus(std::string key);
    // Steam Guard codes: five characters, uppercase.
    void normalize_editor();
    void commit_editor();
    void advance_jobs();
    [[nodiscard]] std::vector<std::string> game_settings_actions() const;
    [[nodiscard]] std::vector<std::string> kept_manager_actions() const;
    [[nodiscard]] std::vector<std::string> leftover_manager_actions() const;
    [[nodiscard]] bool leftover_queued(const std::string& title_id) const;
    // The Import sheet: Look for games, then the candidates grouped by drive (headings never take
    // the focus), then Close. Opened from Startup, Home's empty state and Settings › Library.
    [[nodiscard]] std::vector<std::string> import_sheet_actions() const;
    [[nodiscard]] const LiveImportCandidate* import_candidate(const std::string& key) const;
    void open_import_sheet();
    void refresh_import_sheet();
    void move_import_sheet(int delta);
    void look_for_games();
    std::string import_programs_key_;  // the candidate whose program list is open
    // The import wizard. Step 1 (surface import-choice), for the program picked in the open program
    // list: play the game from its folder, or Copy to storage. Step 2 (surface import-storage):
    // the drive the game goes to, for that program's folder or for a game already added
    // (import_choice_game_ valid: its page's Copy to storage opens step 2 directly).
    void open_import_choice(std::size_t program);
    void open_import_storage(GameId game = {});
    void choose_import(const std::string& action);
    void choose_import_volume(const std::string& volume_id);
    // Sends the add of the open program list's folder with the transfer to start once it has its
    // game, and returns to the Import sheet.
    void add_import_candidate(const std::string& key, std::optional<ImportRequestKind> then, const std::string& volume_id);
    // What the wizard imports: the candidate (step 1 from the program list) or the game added
    // already, its size and the volume its files are on now.
    struct ImportSubject {
        const LiveImportCandidate* candidate = nullptr;
        std::string title;
        std::string volume;
        std::uint64_t bytes = 0;
        bool ascii_ok = true;
    };
    [[nodiscard]] ImportSubject import_subject() const;
    // Why a drive can't take the game in step 2 (empty: it can), and its words there.
    [[nodiscard]] std::string import_volume_blocker(const ImportSubject& subject, const Volume& volume) const;
    // An add sent to the Local store waits for its game: then the copy or move chosen with it is sent
    // and its page opens.
    struct PendingImport {
        std::optional<ImportRequestKind> then;  // CopyIntoPlayden or MoveIntoPlayden
        std::string volume_id;                  // the copy's install volume
        Route from = Route::Startup;            // where the Import sheet was open
    };
    void settle_pending_imports();
    void start_import_transfer(GameId id, ImportRequestKind kind, const std::string& volume_id);
    void open_game_page(GameId id);
    // Imported games playing in place from their folder (State::external_games), and a copy running.
    [[nodiscard]] const LiveExternalGame* external_game(GameId id) const;
    [[nodiscard]] const Job* import_copy_job(GameId id) const;
    // A game whose setup waits for its program (LiveGameSetup::steam_choices): the sheet that asks,
    // installers and tools last, and the choice, which sets the game up again.
    void open_steam_programs(GameId id);
    // Run launcher or setup: the game folder's programs, then a confirmation.
    void open_setup_programs();
    void choose_steam_launch(GameId id, const std::string& program);
    std::vector<LaunchProgram> steam_programs_shown_;
    std::set<GameId> steam_programs_asked_;  // games whose waiting setup asked once already
    GameId steam_programs_game_;
    std::size_t import_program_index_ = 0;
    bool import_program_chosen_ = false;  // the program was clear (ClearGameProgram): its list was skipped
    GameId import_choice_game_;
    std::map<std::string, PendingImport> pending_imports_;  // by candidate key
    // Live: a copy or move asked for whose job (or finished move) isn't listed yet; its page shows it starting.
    std::map<GameId, ImportRequestKind> import_transfers_starting_;
    // Why the latest add of a folder was refused, by candidate key: its row on the Import sheet says it
    // (a dialog waits until the sheet closes).
    std::map<std::string, std::string> import_failures_;
    // Manage installed games: a tab's games in its order, why a game cannot be picked now (empty when it
    // can), and the screen's refresh when installs, jobs or the runtime change.
    [[nodiscard]] std::vector<GameId> manage_list(ManageTab tab) const;
    [[nodiscard]] std::string installed_blocker(GameId id) const;
    // On Updates also a game whose drive is disconnected or read-only.
    [[nodiscard]] std::string manage_blocker(ManageTab tab, GameId id) const;
    // What the Runtimes tab would do for a game: update its runtime or repair it; nothing when it is current.
    [[nodiscard]] std::optional<MaintenanceKind> runtime_work(GameId id) const;
    void start_runtime_batch();
    // Sends the batch's next game once the last one is done and nothing else is being prepared. Stops first if
    // console storage is too low to go on.
    void runtime_batch_step();
    void stop_runtime_batch();
    void refresh_manage_games();
    void open_manage_games(ManageTab tab);
    void close_manage_games();
    void show_manage_queue(GameId first);
    void switch_manage_tab(int delta);
    void manage_select_all();
    void ask_manage_uninstall();
    // The Updates tab's checked games that can update now, in list order, the download they add up to, and
    // the first drive without room for its share (empty when they all fit or free space can't be read).
    struct ManageUpdates {
        std::vector<GameId> games;
        std::uint64_t bytes = 0;     // the sized games' downloads
        std::size_t unsized = 0;     // games whose size isn't known yet
        std::vector<std::pair<std::string, std::uint64_t>> free;  // each drive's label and free space
        std::string short_drive;
        std::uint64_t short_bytes = 0;
    };
    [[nodiscard]] ManageUpdates manage_updates() const;
    void queue_manage_updates(bool anyway = false);
    // The Move tab's checked games that can move now, in list order, their size, and the destination's free
    // space (none when it can't be read); short when they don't fit there.
    struct ManageMoves {
        std::vector<GameId> games;
        std::uint64_t bytes = 0;
        std::optional<std::uint64_t> free;
        bool short_of_space = false;
    };
    [[nodiscard]] ManageMoves manage_moves() const;
    void queue_manage_moves();
    // Drives a game can move to: available and writable. Moving needs two of them.
    [[nodiscard]] std::vector<const Volume*> move_volumes() const;
    // Live: how many more games the Queue takes (kQueueJobLimit less its jobs and those asked for); false
    // when the batch of `count` doesn't fit, after telling the player.
    [[nodiscard]] std::size_t queue_room() const;
    bool queue_fits(std::size_t count);
    void choose_manage_move_volume();
    // Move from: the drives with games that can move, in the drives' order; Cross on the button goes round
    // them after All drives.
    [[nodiscard]] std::vector<const Volume*> move_from_volumes() const;
    void cycle_manage_move_from();
    [[nodiscard]] std::vector<const Volume*> uninstall_from_volumes() const;
    void cycle_manage_uninstall_from();
    void open_move_picker(GameId game);
    void choose_move_volume(const std::string& volume_id);
    // Why a game can't move to `volume_id` now (empty when it can).
    [[nodiscard]] std::string move_blocker(GameId id, const std::string& volume_id) const;
    void build_manage_games_view();
    [[nodiscard]] std::string manage_default_focus() const;
    bool move_manage(int delta_x, int delta_y);
    // Asks the controller to uninstall a game; batch: from the Installed games list.
    void request_uninstall(GameId id, bool delete_saves, bool batch);
    void start_setup_program();  // Run launcher or setup: the program chosen, when the game is closed
    bool launcher_mode_kit() const { return kit_.launcher_mode || kit_.launcher_mode_needs_update; }
    void end_uninstall(GameId id, const std::string& stopped);
    [[nodiscard]] const EndedUninstall* uninstall_stop(GameId id) const;
    [[nodiscard]] std::vector<std::string> collection_sheet_actions(const std::string& sheet) const;
    void refresh_collection_sheets(const std::string& focus = {});
    void refresh_game_settings();
    bool can_change_game_settings();
    void set_game_setting(const std::string& id, const std::string& value);
    void announce_settings_saved();
    // The game's Game settings and maintenance can change it: in live mode, its title is prepared.
    [[nodiscard]] bool game_prepared(GameId id) const;
    // Whether a setting or action that needs the game closed can run: false while the game
    // runs or the console has not said; reason says why.
    [[nodiscard]] bool game_closed(GameId id, std::string* reason = nullptr) const;
    [[nodiscard]] std::vector<std::string> maintenance_actions() const;
    // The game page's More menu: Game settings and Maintenance first for a prepared game.
    [[nodiscard]] std::vector<std::string> details_context_actions() const;
    void request_maintenance(GameId id, MaintenanceKind kind);
    // Rows the preset chooser compares: Current → This preset for the focused preset.
    void build_preset_comparison(GameId id, const std::string& preset_id);
    [[nodiscard]] const playden::runtime::SettingsPreset* preset_for(GameId id) const;
    // The kit's capabilities as the game's PS5 title can use them: a title still on an earlier kit's runtime (Update
    // pending) gets no 120 Hz output until it is updated (runtime::KitForTitleRuntime); the rows wait for it.
    [[nodiscard]] playden::runtime::KitCapabilities kit_for(GameId id) const;
    void start_logs();
    void finish_logs();
    void queue_service_action(ServiceAction action, Store store = Store::kSteam);
    // Another store has a signed-in account or games: then Playden opens on Home without Steam.
    [[nodiscard]] bool beyond_steam() const;
    // Steam's sign-in ended without an account: Home when another store has games, else Startup.
    void leave_steam_sign_in();
    // A notification for Steam's saved sign-in that failed while another store's games show.
    void steam_restore_notice();
    void clear_account_specific_state();
    void apply_organization_snapshot(const playden::OrganizationSnapshot& snapshot);
    void reconcile_applied_organization_selection(GameId prior_selected_id);
    bool record_live_persistence();
    void update_persistence_notice();
    void apply_live_volume_usage();
    void push_notice(Notice notice);
    void show_ready_prompt();
    void show_update_ready_prompt();
    // The runtime kit prompt: once per kit, when games wait for its runtime, after What's new.
    void show_runtime_prompt();
    std::size_t runtime_prompt_games_ = 0;  // what its button starts: kit updates and repairs
    bool runtime_prompt_open_ = false;
    std::string runtime_prompt_shown_kit_;
    void show_alert(std::string title, std::string body, GameId settings_game = {});
    void open_game_settings();
    void show_alert_prompt();
    void open_live_log(const std::string& topic, GameId game_id);
    void load_live_log();
    [[nodiscard]] bool live_notices_visible() const noexcept;
    [[nodiscard]] bool live() const noexcept { return mode_ == ModelMode::Live; }
    [[nodiscard]] const std::string& install_target() const noexcept {
        return install_volume_id_.empty() ? selected_volume_id_ : install_volume_id_;
    }
    [[nodiscard]] std::string next_job_id();
    // The language the install sheet would install `id` in, and the sheet's rows for it.
    [[nodiscard]] std::string install_language(GameId id) const;
    // Every DLC as the install sheet's version and language have it (no install bytes: that choice doesn't).
    [[nodiscard]] std::vector<GameDlc> install_dlc_for_choice(GameId id) const;
    // The DLC the install sheet's version and language offer, with their sizes for that choice.
    [[nodiscard]] std::vector<GameDlc> install_dlc(GameId id) const;
    // Off when the player turned it off; else optional DLC the account owns starts off and the rest on. Free DLC stays
    // on: some games need it, and the list shows its size.
    [[nodiscard]] bool install_dlc_off(const GameDlc& dlc) const;
    [[nodiscard]] std::vector<std::uint32_t> install_excluded_dlc(GameId id) const;
    // A size check of an install choice, unless it is under way, answered or has failed.
    void request_size_check(const SizeCheckRequest& check);
    // The check of the choice an install sheet opens with, and what that choice takes: a game's page says the same.
    [[nodiscard]] SizeCheckRequest default_size_check(const Game& game) const;
    [[nodiscard]] std::optional<std::uint64_t> default_install_size(const Game& game) const;
    // The install sheet's choice in figures: "About" until its exact size is known.
    [[nodiscard]] std::string install_size_text(GameId id, const std::optional<std::uint64_t>& bytes, const char* unknown) const;
    [[nodiscard]] InstallDlcSizes install_dlc_sizes(GameId id) const;
    [[nodiscard]] std::uint64_t install_dlc_on_bytes(GameId id) const;
    // A sheet's rows depend on the game's details and on the version and language chosen.
    void refresh_install_sheet(GameId id);
    // The version chosen in the install sheet for `id`, when it is not the public one.
    [[nodiscard]] const GameVersion* install_version(GameId id) const;
    [[nodiscard]] const GameVersion* install_sized_version(GameId id) const;
    // The install sheet's choice for `id` as a size check names it, and its measured size once known.
    [[nodiscard]] SizeCheckRequest install_size_check(GameId id) const;
    [[nodiscard]] const MeasuredInstallSize* measured_install_size(GameId id) const;
    [[nodiscard]] bool install_size_checking(GameId id) const;
    // The live install sheet's fit check: the chosen version, language and drive, with the measured size.
    [[nodiscard]] InstallAssessment install_assessment(GameId id) const;
    [[nodiscard]] std::vector<std::string> live_install_sheet_actions(GameId id) const;
    // An installed game's update on its own drive: whether it can start, and the words the sheet shows.
    struct UpdateCheck {
        bool allowed = false;
        std::string volume_label;
        std::optional<std::uint64_t> free_bytes;
        std::optional<std::uint64_t> download_bytes;  // measured; none unknown
        std::string reason;  // short, for the confirm row: why not, or what pressing does
    };
    [[nodiscard]] UpdateCheck update_check(GameId id) const;
    // The game's update is putting its files in place: Play waits.
    [[nodiscard]] bool update_locked(GameId id) const;
};

} // namespace playden::homebrew