feat(collections): add a collection naming mode to keep same-named types separate (#1569)

Now that franchise and IGDB-collection virtual types both sync,
collections of different types that share a name silently merge into one
Steam collection (#1503's by-name union) — two enabled rows collapse
into one Steam collection with no way to tell them apart. This adds a
user setting to opt out of that merge, and fixes a related
case-collision that could drop games.

## `collection_naming_mode`

A new setting in Settings → Library, default `merge` (unchanged
behaviour):

- **`merge`** (default) — same-named collections union into one `RomM:
[<name>] (<host>)`.
- **`by_label`** — each Steam collection name carries its type label so
distinct groupings stay separate: `RomM: [<name> (Franchise)] (<host>)`,
`RomM: [<name> (IGDB Collection)] (<host>)`, `RomM: [<name> (Smart)]
(<host>)`, `RomM: [<name> (Standard)] (<host>)`. Collections that share
both name and type still union.

The label is injected at the reporter's union key, so the frontend
create-name and the stale-collection reconcile stay derived from a
single key. Switching modes renames every collection on the next normal
sync — the existing complete-set reconcile deletes the old-named
collections and recreates them under the new scheme; no Force Full Sync
is needed.

Toggle copy: "Distinguish collection types in Steam names — Adds the
collection type (e.g. Franchise, IGDB Collection) to the Steam
collection name so collections that share a name stay separate instead
of merging into one. Applies on the next sync."

## Case-insensitive name identity

Collections whose names differ only by case previously produced two
separate keys under `merge`, which Steam then collapsed by its own
case-insensitive collection identity — silently overwriting one with the
other and dropping its games. Collection and platform name identity is
now case-insensitive throughout (the reporter union, the frontend
create/find, the stale-collection reconcile, and the cleanup paths), so
case-variants union into a single collection instead of clobbering each
other. First-seen casing is kept for display (Steam uppercases the name
regardless).

## Migrations

- Settings migrate to v13: the `enabled_collections` bucket keyed `user`
is renamed to `standard` (lossless; merged into an existing `standard`
bucket if present).
- A database migration renames the stored kind on existing collection
sync-state rows, so no standard collection is needlessly re-fetched
after the update.

Docs (syncing guide, Steam-shortcuts architecture) and the glossary are
updated in the same change.

Closes #1539.

Author: danielcopper

CONTEXT.md

@@ -294,3 +294,15 @@ The ownership filter over the collection list on a shared RomM server — the `c
 collections). Orthogonal to the collection kind axis: it filters by owner (`is_own` / `user_id` vs `romm_user_id`), not
 by kind, and virtual collections have no owner so they always survive. The stored value stays `own` / `all`; only the
 QAM label is **Mine** / **All** (the value was left `own` to avoid a settings migration, #1539).
+
+### Collection naming mode (merge / by_label)
+
+How the Steam-collection **name** is formed when RomM collections share a display name across kinds — the
+`collection_naming_mode` setting valued `merge` (default) or `by_label`. Under **`merge`**, same-named collections union
+into one `RomM: [<name>] (<host>)` Steam collection (#1503). Under **`by_label`**, each name carries its **fine type
+label** so distinct groupings stay separate: `RomM: [<name> (Franchise)]`, `RomM: [<name> (IGDB Collection)]`,
+`RomM: [<name> (Smart)]`, `RomM: [<name> (Standard)]`. The label is the fine label, not the coarse kind — franchise and
+IGDB-collection are both `kind="virtual"`, distinguished by `virtual_type` (see the **Collection kind** entry above).
+Computed backend-side at the reporter's union key (`domain/collection_label.py`), so the wire payload stays name→appIds
+and the frontend needs no change; the mode flip is applied by the ordinary complete-set reconcile on the next normal
+sync (no Force Full Sync). Same-name-**within-one-label** still unions.

docs/architecture/steam-non-steam-shortcuts.md

@@ -279,6 +279,50 @@ wipe the entire library organization. The additive create/update path stays unga
 still get their collections; only the destructive deletion is skipped on cancel. Steam collections are not backed up, so
 the safe behavior on a partial/cancelled run is to delete nothing.
 
+### Collection naming mode — `merge` vs `by_label` (#1539)
+
+The `romm_collection_app_ids` wire payload is `name → appIds` **only** — kind/virtual_type are collapsed away before the
+frontend sees them, and the frontend simply wraps each key as `RomM: [<key>] (<hostname>)`. So the Steam-collection name
+is decided **entirely by the reporter's dict key**, computed backend-side in
+`SyncReporter._resolve_collection_memberships` (`services/library/reporter.py`) from the `collection_naming_mode`
+setting:
+
+- **`merge`** (default) — the key is the bare collection display name. Same-named RomM collections of any kind union
+  into one `RomM: [<name>]` Steam collection (RomM permits same-named collections across kinds/users, #1503).
+- **`by_label`** (opt-in) — the key is `"<name> (<FineLabel>)"`, where the fine label comes from the pure
+  `domain/collection_label.py` kernel: `Standard` / `Smart` for those kinds, and the virtual sub-type label (`Franchise`
+  / `IGDB Collection`) for `kind == "virtual"`. So a franchise and an IGDB collection that share a name become
+  `RomM: [<name> (Franchise)]` and `RomM: [<name> (IGDB Collection)]` — separate Steam collections. Two collections that
+  share **both** name and label still union.
+
+The label strings **must** match the frontend collection-type vocabulary (`SUB_TAB_LABELS` / `VIRTUAL_TYPE_LABELS` in
+`src/components/LibraryPage.tsx`) so the type a user sees on the Collections page is the type baked into the Steam name.
+The reporter needs the kind/virtual_type at its union key, so `WorkUnit.virtual_type` and `CollectionMembership.kind` +
+`CollectionMembership.virtual_type` thread that identity through the fetcher → orchestrator → reporter.
+
+**Label-format constraint:** the reconcile parses the collection name with `/^RomM: \[([^\]]+)\]/` (`src/index.tsx`), so
+a label must contain **no** `]` character — it sits inside the single existing bracket pair. Parens (`(Franchise)`) are
+safe; a bracket would truncate the parsed name and orphan the collection. Every produced label is bracket-free (asserted
+in `tests/domain/test_collection_label.py`).
+
+**No Force Full Sync on a mode flip.** Because the create-name and the reconcile's `activeNames` both derive from the
+same `romm_collection_app_ids` keys, flipping the mode is applied by the ordinary **complete-set reconcile** on the next
+normal sync: the reporter re-emits the complete set of enabled collections under the new keys, `onSyncComplete` creates
+the new-named collections and deletes any old-named collection absent from the new complete set. No skip-state
+invalidation is involved (same mechanism owner-scope reshaping uses).
+
+**Name identity is case-insensitive (#1569).** Steam collapses collection names by a **case-insensitive** identity — two
+collections whose display names differ only in case (`RomM: [7 up]` vs `RomM: [7 Up]`) are the same Steam collection, so
+creating the second silently overwrites the first and loses its games. To match, collection **and** platform name
+identity is treated case-insensitively **everywhere** the plugin compares names: the reporter groups both
+`romm_collection_app_ids` and `platform_app_ids` by a case-folded key (`str.casefold()`), keeping the first-seen
+original casing for display (which exact casing wins is irrelevant — Steam uppercases collection names anyway); the
+frontend create/find (`createOrUpdateCollections` / `createOrUpdateRomMCollections`), the cleanup matchers
+(`clearPlatformCollection` / `clearAllRomMCollections`), and the `onSyncComplete` stale-delete comparisons all match by
+`toLowerCase()`. This is always safe precisely because Steam's identity is case-insensitive: two collections differing
+only by case can never coexist, so there is never an ambiguous match to disambiguate. The DB is unaffected —
+`collection_sync_state` is keyed by `(collection_id, collection_kind)`, never by name — so there is no migration.
+
 ## App IDs and Artwork
 
 `SteamClient.Apps.AddShortcut()` returns the real `appId`, so the plugin does **not** compute shortcut app IDs itself —

docs/user-guide/syncing-your-library.md

@@ -263,10 +263,24 @@ On a **shared RomM server** the collection list includes every other user's _pub
 first time you sign in (existing sign-ins pick it up on the next connection check). Until then, **Mine** behaves exactly
 like **All** — it never hides a collection it can't yet attribute.
 
+#### Collections that share a name
+
 If two enabled collections share the same name — for example a personal collection and a smart or virtual collection
-called the same thing, or (on a shared server) another account's public collection — they **merge into a single Steam
-collection** carrying the combined set of games. RomM allows collections to share a name, but Steam identifies a
-collection by its name, so the plugin unions their members rather than dropping one.
+called the same thing, or (on a shared server) another account's public collection — what happens depends on the
+**Distinguish collection types in Steam names** setting on the **Settings** page under **Library**:
+
+- **Off** (default) — the same-named collections **merge into a single Steam collection** carrying the combined set of
+  games. RomM allows collections to share a name, but Steam identifies a collection by its name, so the plugin unions
+  their members rather than dropping one. Names that differ only in **capitalisation** ("7 up" vs "7 Up") count as the
+  same name and merge too — Steam itself treats collection names case-insensitively.
+- **On** — the plugin appends the collection **type** to the Steam name, so same-named collections of different types
+  stay **separate**. A franchise and an IGDB collection that share a name become `RomM: [<name> (Franchise)]` and
+  `RomM: [<name> (IGDB Collection)]` — matching the Franchise / IGDB Collection / Smart / Standard labels you see on the
+  Collections page. Collections that share both a name **and** a type still merge.
+
+The setting applies on the **next normal sync** — no Force Full Sync is needed. After flipping it, run a sync and the
+plugin renames the affected Steam collections (and removes the old-named ones) as part of its normal end-of-sync
+housekeeping.
 
 ## Artwork
 

main.py

@@ -346,6 +346,9 @@ async def save_collection_platform_groups(self, enabled):
     async def set_collection_owner_scope(self, scope):
         return self._settings_service.set_collection_owner_scope(scope)
 
+    async def set_collection_naming_mode(self, mode):
+        return self._settings_service.set_collection_naming_mode(mode)
+
     @migration_blocked
     async def start_sync(self):
         return self._sync_service.start_sync()

py_modules/adapters/persistence.py

@@ -54,6 +54,12 @@ def time(self) -> float:
     # server lists) or ``"own"`` (only the signed-in user's own collections;
     # virtual collections have no owner and always survive).
     "collection_owner_scope": "all",
+    # Steam-collection naming mode: ``"merge"`` (default — same-named collections
+    # of any kind union into one ``RomM: [<name>]`` collection) or ``"by_label"``
+    # (the fine type label is appended, ``RomM: [<name> (Franchise)]``, so
+    # same-named collections of different types stay separate). Applies on the
+    # next normal sync via the reporter key + complete-set reconcile.
+    "collection_naming_mode": "merge",
     "preferred_region": "auto",
     "steam_input_mode": "default",
     "steamgriddb_api_key": "",

py_modules/domain/collection_label.py

@@ -0,0 +1,59 @@
+"""Fine display label for a RomM collection, keyed by kind + virtual type.
+
+The pure kernel behind the ``by_label`` Steam-collection naming mode: it maps a
+collection's ``kind`` (``standard`` / ``smart`` / ``virtual``) and, for the
+virtual kind, its ``virtual_type`` (``franchise`` / ``collection``) onto the
+short human label the reporter appends to a collection name so same-named
+collections of different types stay separate Steam collections
+(``RomM: [<name> (Franchise)] (host)``). No I/O, no state.
+
+The label strings MUST match the frontend vocabulary exactly — ``SUB_TAB_LABELS``
+and ``VIRTUAL_TYPE_LABELS`` in ``src/components/LibraryPage.tsx`` — so the type a
+user sees on the Collections page is the type baked into the Steam name. Keep the
+two in sync.
+
+Label-format safety: a label is appended inside the single bracket pair of
+``RomM: [<name> (<label>)]``, and the frontend reconcile parses that name with
+``/^RomM: \\[([^\\]]+)\\]/`` (``src/index.tsx``). So a label must contain **no**
+``]`` character (parens are safe, brackets would truncate the parsed name and
+orphan the collection). Every label below is bracket-free; the fallback
+capitalises a controlled kind literal, which is too.
+"""
+
+from __future__ import annotations
+
+# Coarse kind → label. Mirrors ``SUB_TAB_LABELS`` in LibraryPage.tsx.
+_KIND_LABELS: dict[str, str] = {
+    "standard": "Standard",
+    "smart": "Smart",
+    "virtual": "Virtual",
+}
+
+# Virtual sub-type → label. Mirrors ``VIRTUAL_TYPE_LABELS`` in LibraryPage.tsx:
+# "IGDB Collection" (not "Collection") disambiguates from the Collections page
+# it lives inside.
+_VIRTUAL_TYPE_LABELS: dict[str, str] = {
+    "franchise": "Franchise",
+    "collection": "IGDB Collection",
+}
+
+
+def collection_label(kind: str, virtual_type: str | None) -> str:
+    """Return the fine display label for a collection of ``kind`` / ``virtual_type``.
+
+    ``standard`` → ``"Standard"``, ``smart`` → ``"Smart"``. A ``virtual``
+    collection resolves to its virtual-type label — ``franchise`` →
+    ``"Franchise"``, ``collection`` → ``"IGDB Collection"`` — falling back to
+    ``"Virtual"`` when the type is missing or unrecognised (an older backend, a
+    virtual type the plugin does not sync). An unknown ``kind`` degrades to the
+    capitalised kind string (never expected for the ``standard`` / ``smart`` /
+    ``virtual`` set), and an empty kind to ``"Collection"``. Every branch is
+    free of ``]`` so the reconcile name-parse stays intact.
+    """
+    if kind == "virtual":
+        if virtual_type is not None and virtual_type in _VIRTUAL_TYPE_LABELS:
+            return _VIRTUAL_TYPE_LABELS[virtual_type]
+        return _KIND_LABELS["virtual"]
+    if kind in _KIND_LABELS:
+        return _KIND_LABELS[kind]
+    return kind.capitalize() if kind else "Collection"

py_modules/domain/work_unit.py

@@ -31,6 +31,13 @@ class WorkUnit:
     # Collection-only: dispatches the correct list-roms endpoint at fetch time.
     # ``None`` is only valid when ``type == "platform"``.
     collection_kind: CollectionKind | None = None
+    # Virtual-collection-only: which virtual type this unit is (``"franchise"``
+    # or ``"collection"``), stamped from the query type at fetch time. Threaded
+    # so the reporter can build the fine display label for the ``by_label``
+    # Steam-collection naming mode (a ``kind == "virtual"`` unit needs the
+    # sub-type to distinguish Franchise from IGDB Collection). ``None`` for a
+    # platform or a standard/smart collection (their kind alone names them).
+    virtual_type: str | None = None
     # Collection-only: the collection's server ``updated_at`` from the listing,
     # threaded so the incremental-skip gate can compare it against the stored
     # ``CollectionSyncState`` stamp (#742). RomM bumps this on any membership

py_modules/services/library/_state.py

@@ -54,10 +54,18 @@ class CollectionMembership:
     memberships and UNIONs their resolved appIds into the one
     ``RomM: [<name>] (host)`` Steam collection (RomM permits same-named collections
     across kinds/users, so the plugin merges rather than owner-filters, #1503).
+
+    ``kind`` (``"standard"`` / ``"smart"`` / ``"virtual"``) and — for the virtual
+    kind — ``virtual_type`` (``"franchise"`` / ``"collection"``) ride here too so
+    the reporter can build the fine display label under the ``by_label`` naming
+    mode (``domain.collection_label``); in the default ``merge`` mode they are
+    unused and same-named collections still union by name.
     """
 
     name: str
     rom_ids: list[int]
+    kind: str
+    virtual_type: str | None = None
 
 
 @dataclass(frozen=True)

py_modules/services/library/fetcher.py

@@ -97,6 +97,7 @@ def _collection_units(
     enabled_ids: set[str],
     kind: CollectionKind,
     *,
+    virtual_type: str | None = None,
     own_user_id: int | None = None,
     filter_to_own: bool = False,
 ) -> list[WorkUnit]:
@@ -107,6 +108,12 @@ def _collection_units(
     queue even if it is enabled, so a scope selected over an earlier enable never
     syncs someone else's collection. Virtual collections have no owner and
     always survive (:func:`is_own_collection`).
+
+    *virtual_type* stamps the unit's virtual sub-type (``"franchise"`` /
+    ``"collection"``) for the ``kind == "virtual"`` caller, which fetches one
+    type at a time and so knows it authoritatively — the same source the QAM
+    listing uses. ``None`` for standard/smart callers (their kind alone labels
+    them).
     """
     units: list[WorkUnit] = []
     for c in collections:
@@ -123,6 +130,7 @@ def _collection_units(
                 slug=c.get("slug", ""),
                 rom_count=int(c.get("rom_count", len(c.get("rom_ids", [])))),
                 collection_kind=kind,
+                virtual_type=virtual_type,
                 # RomM bumps the collection's updated_at on any membership change
                 # (#742). Threaded so the skip gate compares it against the stamp;
                 # ``None`` for a listing that omits it (e.g. virtual, never
@@ -610,15 +618,17 @@ async def _build_virtual_collection_units(self, enabled_ids: set[str]) -> list[W
         """
         if not enabled_ids:
             return []
-        collections: list[dict[str, Any]] = []
+        units: list[WorkUnit] = []
         for virtual_type in _SUPPORTED_VIRTUAL_TYPES:
             try:
-                collections.extend(
-                    await self._loop.run_in_executor(None, self._romm_api.list_virtual_collections, virtual_type)
+                collections = await self._loop.run_in_executor(
+                    None, self._romm_api.list_virtual_collections, virtual_type
                 )
             except Exception as e:
                 self._logger.warning(f"Failed to fetch {virtual_type} collections for work queue: {e}")
-        return _collection_units(collections, enabled_ids, "virtual")
+                continue
+            units.extend(_collection_units(collections, enabled_ids, "virtual", virtual_type=virtual_type))
+        return units
 
     async def _attach_plan_estimates(self, platform_units: list[WorkUnit]) -> list[WorkUnit]:
         """Stamp each platform unit with its plan-time estimate riders (#1382).