feat(ui): show Space Required size on uninstalled games before download (#1395) (#1526)

Uninstalled games now show a "Space Required" cell in the play section
next to the download button, so the download footprint is visible before
deciding to download — matching Steam's native game detail.

The size comes from RomM's per-ROM `fs_size_bytes`, persisted locally so
it is available offline: it rides the library sync UPSERT like the other
server-derived facts, a completed download or a version switch tops it
up between syncs, and it is surfaced in the cached game-detail payload.
The cell shows only while the ROM is uninstalled and its size is known,
and it leads the info row so it is never clipped.

Closes #1395

Author: danielcopper

.size-limit.json

@@ -3,6 +3,6 @@
     "name": "dist/index.js (raw)",
     "path": "dist/index.js",
     "brotli": false,
-    "limit": "775 KB"
+    "limit": "800 KB"
   }
 ]

docs/architecture/database-design.md

@@ -15,6 +15,9 @@ shows:
 - **Region / Languages** — attributes of the active version, shown in the Game Info tab when RomM has them (see below)
 - **BIOS status** — whether required BIOS files are present (see [BIOS Management](bios-management.md))
 - **Save sync status** — last sync time, conflict count, and playtime (see [Save Sync](save-sync.md))
+- **Space required** — for a game that isn't downloaded yet, a "Space Required" cell next to the Play button shows how
+  much disk space the download needs. It disappears once the game is installed (mirroring how Steam hides it for
+  installed games); it's also omitted when RomM doesn't report the size.
 - **Action buttons** — Download, Pause/Resume, Uninstall, Cancel, or Refresh Metadata depending on state
 
 ![Game detail page showing the RomM Sync panel for an installed game](../assets/screenshot-game-detail.jpg)
@@ -84,7 +87,8 @@ versions, and a version with no region/language detail simply omits the rows. Th
 
 ## Downloading ROMs
 
-Games appear as shortcuts in your library even before the ROM file is downloaded. To download:
+Games appear as shortcuts in your library even before the ROM file is downloaded. Before downloading, the panel shows a
+**Space Required** cell next to the Play button so you know how much disk space the ROM needs. To download:
 
 1. Open the game's detail page in the Steam Library
 2. In the RomM Sync panel, tap **Download**

docs/user-guide/managing-games.md

@@ -42,6 +42,11 @@
     "revision",
     "tags",
     "is_main_sibling",
+    # The server-reported ROM size in bytes (#1395). Like the version dimensions
+    # above (and unlike the user pins), it is a server-derived fact that rides
+    # the UPSERT and refreshes every sync — set directly from the fetched dict,
+    # no confirmed-else-preserved merge. NULL = unknown.
+    "fs_size_bytes",
     # The fetch generation that last saw this row (#1504). Server-independent
     # like the pins, but it rides the UPSERT: the reporter merges it
     # confirmed-else-preserved before save(), so a platform apply advances it
@@ -84,6 +89,7 @@ def _row_to_rom(row: sqlite3.Row) -> Rom:
         revision=row["revision"],
         tags=tuple(json.loads(row["tags"])),
         is_main_sibling=bool(row["is_main_sibling"]),
+        fs_size_bytes=row["fs_size_bytes"],
         last_fetch_id=row["last_fetch_id"],
     )
 
@@ -155,6 +161,7 @@ def save(self, rom: Rom) -> None:
                 rom.revision,
                 json.dumps(list(rom.tags)),
                 int(rom.is_main_sibling),
+                rom.fs_size_bytes,
                 rom.last_fetch_id,
             ),
         )
@@ -218,6 +225,22 @@ def clear_all_applied_launch_options(self) -> None:
         """
         self._conn.execute("UPDATE roms SET applied_launch_options = NULL")
 
+    def set_fs_size_bytes(self, rom_id: int, size: int | None) -> None:
+        """Write the server-reported ROM size for ``rom_id`` — the download write-back (#1395).
+
+        A between-syncs freshness top-up: a completed download stamps the size
+        from the ROM detail it already fetched, so the game-detail UI shows the
+        downloaded ROM's size without waiting for the next sync. Unlike the pin
+        columns (``emulator_override`` / ``selected_disc`` / ``applied_launch_options``),
+        ``fs_size_bytes`` ALSO rides the sync UPSERT in :meth:`save`, so a later
+        re-sync re-writes the same authoritative server value — the two write
+        paths never conflict. ``size`` is the byte count, or ``None`` for SQL NULL.
+        """
+        self._conn.execute(
+            "UPDATE roms SET fs_size_bytes = ? WHERE rom_id = ?",
+            (size, rom_id),
+        )
+
     def delete(self, rom_id: int) -> None:
         self._conn.execute("DELETE FROM roms WHERE rom_id = ?", (rom_id,))
 

py_modules/adapters/repositories/rom.py

@@ -0,0 +1,34 @@
+-- =============================================================================
+-- 021_add_rom_fs_size.sql — persist a ROM's server-reported byte size
+-- #1395 (show download size / space required before a ROM is downloaded)
+-- =============================================================================
+--
+-- RomM returns ``fs_size_bytes`` — the total on-server size of a ROM's file(s)
+-- — on both its list and detail responses, the same value in each. The plugin
+-- needs it at the frontend before a download so the game-detail UI can show how
+-- much space the download will take. This column carries that fact locally.
+--
+--   * roms.fs_size_bytes — the server-reported ROM size in bytes.
+--
+-- Nullable because the value is not always known:
+--
+--   * A pre-migration row has no size until the next sync re-writes it.
+--   * A platform the current session wholesale-skipped is not re-applied, so a
+--     row it never touched keeps whatever it had (NULL for a fresh row).
+--
+-- ``NULL`` = unknown; the frontend treats it as "size unknown, hide it".
+--
+-- Backfill needs no data-migration pass. The size is a server-derived fact, so
+-- it rides the sync UPSERT exactly like the version-metadata columns (regions /
+-- sibling_group_key / …, migration 008) — set directly from the fetched dict,
+-- no confirmed-else-preserved merge — and every applying sync re-writes the
+-- authoritative server value onto each row it touches. Between syncs a completed
+-- download also tops the value up (the download write-back reads the ROM detail
+-- it already fetched), so a freshly downloaded ROM shows its size without waiting
+-- for the next sync. The two paths never conflict: both write the same
+-- server-reported number.
+--
+-- Transaction-safe DDL only — the runner (adapters/sqlite_migrations.py) wraps
+-- BEGIN/COMMIT and stamps PRAGMA user_version = 21.
+-- -----------------------------------------------------------------------------
+ALTER TABLE roms ADD COLUMN fs_size_bytes INTEGER;  -- server-reported ROM size in bytes; NULL = unknown

py_modules/db/migrations/021_add_rom_fs_size.sql

@@ -10,17 +10,23 @@
 from __future__ import annotations
 
 from domain._aggregate import cosmic_aggregate
+from domain.version_metadata import VersionMetadata
+
+# The neutral "no version metadata known" value. Shared as the ``synced`` default
+# because ``VersionMetadata`` is frozen/immutable, so a single instance is safe.
+_EMPTY_VERSION_METADATA = VersionMetadata()
 
 
 @cosmic_aggregate
 class Rom:
     """One ROM as the plugin tracks it locally (identity + shortcut binding).
 
     ``sibling_group_key`` and the version dimensions (``regions`` / ``languages``
-    / ``revision`` / ``tags`` / ``is_main_sibling``) are server-derived facts
-    RomM supplies per ROM — the sibling group this dump belongs to and how it
-    differs from its siblings (region/language/revision variants). They are set
-    at construction from the fetch and refreshed on every sync (they ride the
+    / ``revision`` / ``tags`` / ``is_main_sibling``), plus ``fs_size_bytes`` (the
+    server-reported ROM size, #1395), are server-derived facts RomM supplies per
+    ROM — the sibling group this dump belongs to, how it differs from its
+    siblings (region/language/revision variants), and how large it is. They are
+    set at construction from the fetch and refreshed on every sync (they ride the
     sync UPSERT, unlike the user-pin ``emulator_override`` / ``selected_disc``);
     no mutation verbs, as no local flow changes them independently of a sync.
     """
@@ -46,6 +52,7 @@ class Rom:
     revision: str = ""
     tags: tuple[str, ...] = ()
     is_main_sibling: bool = False
+    fs_size_bytes: int | None = None
 
     @classmethod
     def synced(
@@ -58,18 +65,19 @@ def synced(
         shortcut_app_id: int | None,
         synced_at: str,
         igdb_id: int | None = None,
-        sibling_group_key: str | None = None,
-        regions: tuple[str, ...] = (),
-        languages: tuple[str, ...] = (),
-        revision: str = "",
-        tags: tuple[str, ...] = (),
-        is_main_sibling: bool = False,
+        version: VersionMetadata = _EMPTY_VERSION_METADATA,
+        fs_size_bytes: int | None = None,
     ) -> Rom:
         """Build a Rom synced from RomM at ISO timestamp ``synced_at``.
 
         ``shortcut_app_id`` is ``None`` for a non-representative sibling — every
         fetched ROM is persisted for identity + version metadata (ADR-0021), but
         only the group's representative carries a Steam-shortcut binding.
+
+        ``version`` bundles the ADR-0021 server-derived version facts (sibling
+        group key + region/language/revision/tag dimensions); it is unpacked into
+        the ROM's flat fields here. The default empty instance is the "no version
+        metadata known" state, so a minimal-arg sync omits it.
         """
         if rom_id <= 0:
             raise ValueError("rom_id must be positive")
@@ -83,12 +91,13 @@ def synced(
             shortcut_app_id=shortcut_app_id,
             last_synced_at=synced_at,
             igdb_id=igdb_id,
-            sibling_group_key=sibling_group_key,
-            regions=regions,
-            languages=languages,
-            revision=revision,
-            tags=tags,
-            is_main_sibling=is_main_sibling,
+            sibling_group_key=version.sibling_group_key,
+            regions=version.regions,
+            languages=version.languages,
+            revision=version.revision,
+            tags=version.tags,
+            is_main_sibling=version.is_main_sibling,
+            fs_size_bytes=fs_size_bytes,
         )
 
     def record_fetch_generation(self, fetch_id: str) -> None:

py_modules/domain/rom.py

@@ -230,6 +230,10 @@ def build_shortcuts_data(
             "igdb_id": rom.get("igdb_id"),
             "sgdb_id": rom.get("sgdb_id"),
             "ra_id": rom.get("ra_id"),
+            # Server-reported ROM size in bytes (#1395), carried through so the
+            # commit persists it on the Rom aggregate (it rides the sync UPSERT
+            # like the version dimensions). Absent/None → "size unknown".
+            "fs_size_bytes": rom.get("fs_size_bytes"),
             "cover_path": "",
             # The sibling-group key + version dimensions (ADR-0021), extracted by
             # the shared helper so the sync build and the version-switch persist

py_modules/domain/shortcut_data.py

@@ -0,0 +1,60 @@
+"""VersionMetadata — the ADR-0021 server-derived version facts as one value.
+
+The sibling-group identity and version dimensions RomM supplies per ROM: which
+sibling group a dump belongs to, and how it differs from its siblings
+(region/language/revision/tag variants, and whether it is the group's main
+sibling). Bundled here so the cohesive set travels as a single value object
+across the factory boundary rather than as loose parallel parameters.
+
+Pure value object — no I/O, no service/adapter imports. The ``Rom`` aggregate
+keeps these as flat fields; this type is the parameter object its factory
+accepts, and the shape :func:`domain.shortcut_data.extract_version_metadata`
+already treats as a unit.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class VersionMetadata:
+    """The server-derived version facts for one ROM (ADR-0021).
+
+    ``sibling_group_key`` names the sibling group this dump belongs to;
+    ``regions`` / ``languages`` / ``revision`` / ``tags`` describe how it differs
+    from its siblings; ``is_main_sibling`` marks the group's representative dump.
+    The defaults are the "no version metadata known" state — an empty instance is
+    the neutral value the ROM factory falls back to.
+    """
+
+    sibling_group_key: str | None = None
+    regions: tuple[str, ...] = ()
+    languages: tuple[str, ...] = ()
+    revision: str = ""
+    tags: tuple[str, ...] = ()
+    is_main_sibling: bool = False
+
+    @classmethod
+    def from_mapping(cls, m: Mapping[str, Any], *, sibling_group_key: str | None = None) -> VersionMetadata:
+        """Build a ``VersionMetadata`` from a flat RomM-derived mapping.
+
+        Applies the same safe defaulting the sync and version-switch persist
+        paths use (``.get(...) or default``), so a missing or ``null`` field
+        degrades to its neutral value rather than raising. *sibling_group_key*
+        overrides the mapping's key when truthy (the version-switch case, where
+        the target adopts its bound group's key); a falsy override falls back to
+        the mapping's own key.
+        """
+        return cls(
+            sibling_group_key=sibling_group_key or m.get("sibling_group_key"),
+            regions=tuple(m.get("regions") or ()),
+            languages=tuple(m.get("languages") or ()),
+            revision=m.get("revision") or "",
+            tags=tuple(m.get("tags") or ()),
+            is_main_sibling=bool(m.get("is_main_sibling", False)),
+        )

py_modules/domain/version_metadata.py

@@ -514,6 +514,13 @@ def _record_install_io(self, *, rom_id, rom_detail, file_path, rom_dir, system,
 
         with self._uow_factory() as uow:
             uow.rom_installs.save(install)
+            # Download write-back (#1395): top up the ROM's size from the detail
+            # we already fetched, so the game-detail UI shows it without waiting
+            # for the next sync. Guarded on truthiness — a missing/zero size must
+            # never overwrite a good persisted value.
+            size = rom_detail.get("fs_size_bytes")
+            if size:
+                uow.roms.set_fs_size_bytes(int(rom_id), size)
         return file_path, None
 
     def _resolve_safe_extract_dir_name(self, rom_detail: dict[str, Any]) -> str:

py_modules/services/downloads.py

@@ -280,6 +280,9 @@ def get_cached_game_detail(self, app_id) -> dict[str, Any]:
             "revision": rom.revision,
             "tags": list(rom.tags),
             "is_main_sibling": rom.is_main_sibling,
+            # Server-reported ROM size in bytes (#1395), surfaced read-only so the
+            # frontend can show the space a download needs. NULL = size unknown.
+            "fs_size_bytes": rom.fs_size_bytes,
         }
 
     async def get_bios_status(self, rom_id) -> dict[str, Any]: