feat(library): generalize the franchise collection kind to virtual and sync IGDB collections

Generalizes the internal `franchise` collection kind into a single ownerless `virtual` kind carrying a `virtual_type` sub-field, and syncs the two virtual collection types RomM treats as browsable collections: `franchise` (already supported) and IGDB `collection` (RomM's default virtual type — previously not synced).

**Why one `virtual` kind, not five:** RomM's virtual collections are one ownerless model with a `type` discriminator; every axis that affects sync — ownership (none), id/ROM-fetch, incremental-stampability (none — the view has no stable `updated_at`), membership shape — is identical across types. Only the display label differs, so the label becomes data (`virtual_type`) and the owner-filter, stamp-exclusion, and ROM-fetch dispatch each stay a single branch.

**Scope — `genre`, `company`, `mode` are intentionally excluded.** RomM surfaces `genre`/`company` as ROM filter facets, not browsable collections, and `mode` as neither (its Collections view browses one virtual type at a time, defaulting to IGDB `collection`). The supported set is a single constant, so adding a type later is a one-line change.

**Migration:** the `enabled_collections` `franchise` bucket is renamed to `virtual` (settings v10→v11). Existing franchise enables carry over losslessly — a virtual collection's id already encodes its type — so no re-login and no user action. Non-breaking.

UI: the "Franchise" sub-tab becomes "Virtual" and lists both types, each row tagged with its type label ("Franchise" / "IGDB Collection"). The collection-settings UI redesign for the growing type set is tracked separately (#1539).

Closes #1538.

Author: danielcopper

docs/architecture/backend-architecture.md

@@ -501,7 +501,7 @@ sibling row holding `shortcut_app_id` is the group's **active version**.
   collection.
 
 **Same-named collections union into one Steam collection (#1503).** RomM enforces name uniqueness only per-table and
-per-`(name, user_id)`, so two enabled collections can share a display name — a user collection and a smart/franchise
+per-`(name, user_id)`, so two enabled collections can share a display name — a user collection and a smart/virtual
 collection, or (multi-user) another account's public collection the list endpoints return. Steam's collection namespace
 is **by-name** (`RomM: [<name>] (host)`), so both must resolve to the one Steam collection. The finalize accumulator
 (`_state.py` `pending_collection_memberships`) is therefore keyed by a collision-free `(collection_kind, collection_id)`
@@ -514,17 +514,34 @@ set of one and is byte-for-byte the pre-#1503 output. The union runs **after** t
 foreign collection is dropped from the work queue it never reaches the accumulator, so "Own" narrows what is unioned
 rather than changing how the union works.
 
+**Collection kinds — one `virtual` kind covers RomM's browsable virtual types (#1538).** `get_collections` and
+`build_work_queue` group collections into three internal kinds: `user`, `smart`, and `virtual`. The `virtual` kind is
+RomM's ownerless `VirtualCollection` (base64 id, no `user_id`, no stable `updated_at` — never stamped), and it carries a
+`virtual_type` sub-field on each collection dict/setting so the UI can label the row. RomM's `VirtualCollection` has
+five `type` values, but the plugin syncs only the **two RomM itself surfaces as browsable collections**: IGDB
+`franchise` and the default IGDB `collection` (series). `genre`, `company`, and `mode` are **intentionally excluded** —
+RomM treats `genre`/`company` as ROM _filter facets_ (not collections) and `mode` as neither, so they never appear in
+RomM's Collections view. The supported set is a single constant (`services/library/fetcher._SUPPORTED_VIRTUAL_TYPES`);
+the fetcher fetches each supported type (per-type fail-open) and merges them under the one `virtual` bucket. Because the
+type is baked into the base64 id, ids are globally unique across types, so one enabled-bucket keyed by id cannot
+collide. The owner filter, stamp-exclusion, and per-unit ROM-fetch dispatch all stay a **single `kind == "virtual"`
+branch**, not fanned out per type. On disk the enabled-collections bucket was renamed `franchise → virtual` by the
+lossless `settings.json` migration **v10 → v11** (`domain/state_migrations._migrate_v10_to_v11`): it renames the bucket
+key while preserving every enabled id, so a previously-enabled franchise collection stays enabled and no re-login is
+required. (The historical v2 → v3 split still produces the `franchise` bucket; the v10 → v11 step renames it afterwards,
+so that frozen step is untouched.)
+
 **Collection owner-scope filter — "Own" is a sync scope, not just a display filter (#1532).** RomM's collection list
 endpoints return the signed-in user's own collections plus every other user's _public_ collection. The QAM
 `Show
 collections` control writes `collection_owner_scope` (`"own"` / `"all"`, default `"all"`); `get_collections` also
 tags each row with `is_own` so the frontend can hide foreign ones under "Own". Ownership is a pure predicate
-(`domain/collection_owner.is_own_collection`): a collection is own when it is a **franchise/virtual** collection (RomM's
+(`domain/collection_owner.is_own_collection`): a collection is own when it is a **virtual** collection (RomM's
 `VirtualCollection` model carries no `user_id` column — these are global/derived and belong to no one, so they always
 survive), when the plugin's own identity is unknown (the **degrade-to-"All" fallback**), or when the collection's
 `user_id` equals the stored `romm_user_id`; only user and smart collections carry a `user_id` to compare.
 `build_work_queue` applies the same predicate: under `"own"` **with a known identity** it drops foreign user/smart units
-from the queue — so a foreign collection enabled earlier is never synced — while franchise units and every unit under
+from the queue — so a foreign collection enabled earlier is never synced — while virtual units and every unit under
 `"all"` pass through unchanged. The scope filters **over** the per-kind enable state without mutating it, so switching
 back to `"all"` restores the prior enables. Because an **unknown identity never filters**, the feature is non-breaking:
 it silently no-ops until `romm_user_id` is stamped (see the ConnectionService lazy-identity note), then activates — no
@@ -622,9 +639,9 @@ weights + planned totals, via `sync_plan`) and the applying frames.
   zero persisted rows honestly means "every planned item is a create". On a **collection** it counts the bound members
   of the completion stamp's stored `member_rom_ids` (the same member set the skip replays), in one short read UoW
   covering every collection unit — no ROM fetch. The two sides are deliberately **asymmetric** on the empty case: a
-  platform reports `0`, an unstamped or franchise collection is **omitted**. A collection's membership exists only in
-  its stamp, and franchise collections are never stampable (`CollectionSyncState.stamp` accepts only `user`/`smart`), so
-  `0` there would claim knowledge that does not exist. Absent and `0` price identically today; the distinction keeps the
+  platform reports `0`, an unstamped or virtual collection is **omitted**. A collection's membership exists only in its
+  stamp, and virtual collections are never stampable (`CollectionSyncState.stamp` accepts only `user`/`smart`), so `0`
+  there would claim knowledge that does not exist. Absent and `0` price identically today; the distinction keeps the
   field honest for later consumers, so do not collapse it into consistency. A collection's stored member set may be
   **stale** if membership changed since the stamp — accepted and bounded, since this is estimate-only and a freshness
   probe would mean network I/O at plan time. A fourth rider, `new_shortcut_count` (#1517), is the create-side complement
@@ -686,8 +703,8 @@ weights + planned totals, via `sync_plan`) and the applying frames.
   pricing. Platforms are unaffected — their `bound_count` and `new_shortcut_count` are deliberately not stamp-gated.
   This follows directly from the `None`-not-`0` rule above and errs **long**, the safe direction; correcting it would
   mean asserting membership the plan does not have. A unit whose `bound_count` is absent (older backend, unstamped or
-  franchise collection) prices as all creates, the pre-#1511 behaviour. The live-countdown weights are unaffected and
-  stay `predicted_skip ? 0 : (collapsed_count ?? rom_count)`.
+  virtual collection) prices as all creates, the pre-#1511 behaviour. The live-countdown weights are unaffected and stay
+  `predicted_skip ? 0 : (collapsed_count ?? rom_count)`.
 - **Measured live countdown (takes over within seconds).** Once the apply is underway, `syncEta.ts` measures the
   **real** rate from the applying frames — one throttled sample per second over a ~30 s sliding window — and projects
   `remaining = (planned_total − processed) / rate`, rendered rounded **up** ("9 min left") so it never promises less

docs/user-guide/configuration.md

@@ -95,7 +95,7 @@ it surfaces later as a permissions error on the affected action (save upload, de
 | `platforms.read`   | read      | Listing your platforms                                                                       |
 | `roms.read`        | read      | Listing and reading ROM metadata (the library)                                               |
 | `roms.user.read`   | read      | Your per-user ROM data — native play-session history                                         |
-| `collections.read` | read      | Reading your collections (user, smart, franchise)                                            |
+| `collections.read` | read      | Reading your collections (user, smart, virtual)                                              |
 | `firmware.read`    | read      | Listing and downloading BIOS / firmware                                                      |
 | `assets.read`      | read      | Downloading save files                                                                       |
 | `devices.read`     | read      | Reading your registered devices (device sync)                                                |

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

@@ -222,7 +222,8 @@ The **Collections** page splits collections into three sub-tabs plus a dedicated
 - **My** sub-tab — your other user-created collections
 - **Smart** sub-tab — filter-based collections that resolve membership at query time, so syncing always picks up the
   current matches
-- **Franchise** sub-tab — auto-generated franchise groupings (IGDB)
+- **Virtual** sub-tab — auto-generated groupings RomM derives from IGDB metadata: both IGDB **franchise** groupings and
+  IGDB **collection** (series) groupings. Each row is labelled with its type (Franchise / IGDB Collection).
 
 Each sub-tab shows its visible count in the section header (e.g. `MY COLLECTIONS (4)`) and lets you toggle individual
 collections, or use the paired **Enable All** / **Disable All** buttons to bulk-toggle just that sub-tab. The global
@@ -240,12 +241,12 @@ On a **shared RomM server** the collection list includes every other user's _pub
   sync, even if one was enabled earlier — switching back to **All** brings your earlier choices back, since the scope
   filters over your enable state rather than changing it.
 
-**Franchise collections always sync** under either setting: they are auto-generated groupings that belong to no one, so
+**Virtual collections always sync** under either setting: they are auto-generated groupings that belong to no one, so
 "Own" never hides them. The filter only becomes active once the plugin knows your account identity, which it learns the
 first time you sign in (existing sign-ins pick it up on the next connection check). Until then, **Own** behaves exactly
 like **All** — it never hides a collection it can't yet attribute.
 
-If two enabled collections share the same name — for example a personal collection and a smart or franchise collection
+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.

py_modules/adapters/persistence.py

@@ -16,7 +16,7 @@
 
 from adapters.system_clock import SystemClock
 
-_SETTINGS_VERSION = 10
+_SETTINGS_VERSION = 11
 _LOCK_EXT = ".lock"
 
 
@@ -48,11 +48,11 @@ def time(self) -> float:
     # behave like "All" (the non-breaking fallback).
     "romm_user_id": None,
     "enabled_platforms": {},
-    "enabled_collections": {"user": {}, "smart": {}, "franchise": {}},
+    "enabled_collections": {"user": {}, "smart": {}, "virtual": {}},
     "collection_create_platform_groups": False,
     # QAM collection owner-scope: ``"all"`` (default — every collection the
     # server lists) or ``"own"`` (only the signed-in user's own collections;
-    # franchise/virtual collections have no owner and always survive).
+    # virtual collections have no owner and always survive).
     "collection_owner_scope": "all",
     "preferred_region": "auto",
     "steam_input_mode": "default",

py_modules/adapters/romm/romm_api.py

@@ -211,7 +211,7 @@ def list_collection_roms_updated_after(
         # A smart collection filters on ``smart_collection_id``; a user collection
         # on ``collection_id`` (RomM's /api/roms accepts either alongside
         # ``updated_after`` — 5.0.0 endpoints/roms/__init__.py). Only user/smart
-        # kinds ever reach here; the skip gate never probes a franchise collection.
+        # kinds ever reach here; the skip gate never probes a virtual collection.
         param = "smart_collection_id" if kind == "smart" else "collection_id"
         quoted_after = urllib.parse.quote(updated_after)
         return self._client.request(

py_modules/domain/collection_owner.py

@@ -10,10 +10,10 @@
 
 Two invariants make the filter safe and non-breaking:
 
-* **Franchise/virtual collections have no owner.** They are global/derived —
-  RomM's ``VirtualCollection`` model carries no ``user_id`` column and returns
-  them identically to every user — so they are always own and always survive
-  an "Own" filter.
+* **Virtual collections have no owner.** They are global/derived — RomM's
+  ``VirtualCollection`` model carries no ``user_id`` column and returns them
+  identically to every user — so they are always own and always survive an
+  "Own" filter.
 * **Unknown identity degrades to "All".** When the plugin does not yet know its
   own user id (never fetched / offline), every collection is treated as own, so
   "Own" filters nothing rather than filtering against the wrong identity.
@@ -30,19 +30,19 @@ def is_own_collection(collection_user_id: object, own_user_id: int | None, *, ki
     collection_user_id:
         The collection's owner id (``user_id``) from the RomM listing dict, or
         ``None``/absent. Compared by value against *own_user_id*. Only user and
-        smart collections carry it; franchise/virtual collections never do.
+        smart collections carry it; virtual collections never do.
     own_user_id:
         The signed-in user's own id (``settings["romm_user_id"]``), or ``None``
         when identity is not yet known.
     kind:
-        ``"user"``, ``"smart"`` or ``"franchise"``.
+        ``"user"``, ``"smart"`` or ``"virtual"``.
 
-    Returns ``True`` (own) when the collection is a franchise/virtual collection
-    (no owner), when our own identity is unknown (the non-breaking fallback), or
+    Returns ``True`` (own) when the collection is a virtual collection (no
+    owner), when our own identity is unknown (the non-breaking fallback), or
     when the collection's owner id equals ours. ``False`` (foreign) only when a
     user/smart collection is owned by a different known id.
     """
-    if kind == "franchise":
+    if kind == "virtual":
         return True
     if own_user_id is None:
         return True

py_modules/domain/collection_sync_state.py

@@ -27,9 +27,9 @@
    ``updated_at`` does not move for that).
 3. ``rom_count`` unchanged vs. both the live listing and the stored member set.
 
-Only **user** and **smart** collections carry a stamp — franchise/virtual
-collections are auto-generated groupings with no stable ``updated_at`` and are
-never stamped (they always full-fetch). A thin record built whole and upserted —
+Only **user** and **smart** collections carry a stamp — virtual collections
+are auto-generated groupings with no stable ``updated_at`` and are never
+stamped (they always full-fetch). A thin record built whole and upserted —
 never a partial field mutation — so it carries a single ``stamp`` constructor and
 no verb-named mutators. Cleared on the same events that clear platform stamps:
 the local destructive flows (shortcut removal / live-shortcut reconcile) drop any

py_modules/domain/state_migrations.py

@@ -35,6 +35,8 @@ def migrate_settings(data: dict[str, Any]) -> dict[str, Any]:
         new_data = _migrate_v8_to_v9(new_data)
     if version < 10:
         new_data = _migrate_v9_to_v10(new_data)
+    if version < 11:
+        new_data = _migrate_v10_to_v11(new_data)
     return new_data
 
 
@@ -250,3 +252,36 @@ def _migrate_v9_to_v10(data: dict[str, Any]) -> dict[str, Any]:
     data["romm_api_token_source"] = "minted" if data.get("romm_api_token") else None
     data["version"] = 10
     return data
+
+
+def _migrate_v10_to_v11(data: dict[str, Any]) -> dict[str, Any]:
+    """v<11 → v11: rename the ``enabled_collections`` ``franchise`` bucket to ``virtual``.
+
+    The single ownerless virtual-collection kind is now ``virtual`` (it carries
+    a ``virtual_type`` sub-field distinguishing IGDB ``franchise`` from IGDB
+    ``collection``), so the on-disk enabled bucket keyed ``franchise`` is renamed
+    to ``virtual`` with every enabled id preserved — a previously-enabled
+    franchise collection stays enabled and keeps syncing.
+
+    Value semantics: the nested ``enabled_collections`` dict is rebuilt rather
+    than mutated in place. A file that somehow already carries a ``virtual``
+    bucket has the franchise entries merged into it (franchise ids win on a key
+    clash) rather than dropped — the two buckets cannot legitimately both exist
+    before v11, so the union is the loss-free reconciliation.
+
+    The historical v2→v3 step still produces the ``franchise`` bucket; this step
+    renames it afterwards, so the whole chain (v2→v3 → … → v10→v11) lands a
+    v2-origin install on the ``virtual`` bucket without rewriting frozen history.
+    """
+    collections = data.get("enabled_collections")
+    if isinstance(collections, dict) and "franchise" in collections:
+        rebuilt = {k: v for k, v in collections.items() if k != "franchise"}
+        franchise_bucket = collections["franchise"]
+        existing_virtual = rebuilt.get("virtual", {})
+        merged = dict(existing_virtual) if isinstance(existing_virtual, dict) else {}
+        if isinstance(franchise_bucket, dict):
+            merged.update(franchise_bucket)
+        rebuilt["virtual"] = merged
+        data["enabled_collections"] = rebuilt
+    data["version"] = 11
+    return data

py_modules/domain/work_unit.py

@@ -16,7 +16,7 @@
 from typing import Any, Literal
 
 UnitType = Literal["platform", "collection"]
-CollectionKind = Literal["user", "smart", "franchise"]
+CollectionKind = Literal["user", "smart", "virtual"]
 
 
 @dataclass(frozen=True)
@@ -36,7 +36,7 @@ class WorkUnit:
     # ``CollectionSyncState`` stamp (#742). RomM bumps this on any membership
     # add/remove (and a smart-criteria edit), so an equal value is the
     # membership-stable signal. ``None`` when the listing omits it (e.g. a
-    # franchise collection, which is never stamped) — skip-internal, off the wire.
+    # virtual collection, which is never stamped) — skip-internal, off the wire.
     collection_updated_at: str | None = None
     # Plan-time estimate riders (#1382 / #1511 / #1517). ``predicted_skip`` is
     # the plan's local-conditions guess at the fetch-time wholesale-skip gate's