feat(library): descriptive metadata on every entry — platform, year, genres, and friends

Emulation-and-beyond libraries need more than a title and a poster. Every
library shape (GameEntry, CustomEntry, CustomInput, ProviderEntryInput)
now carries a shared, flattened GameMeta: platform, description,
developer, publisher, release_year, genres, tags, region, players. All
fields are optional and flat on the wire, so existing library.json files,
provider plugins, and clients keep working unchanged.

- Installed-store scanners (Steam, Lutris, Heroic, Epic, GOG, Xbox) stamp
  platform=PC; custom/provider entries carry whatever was authored.
- GET /library grows a ?platform= filter (case-insensitive) beside
  ?provider=.
- Console: the add/edit form gets a Details section (round-tripping every
  field, since update replaces the entry), the poster tile a platform
  badge (non-PC only — the store badge already implies PC) and the year.
- plugin-kit: ProviderEntry accepts the same fields (new GameMeta schema,
  spread flat); SDK + OpenAPI spec regenerated.
- pf-client-core decodes platform for future client badges.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

crates/punktfunk-host/src/library.rs

@@ -85,6 +85,57 @@ pub struct LaunchSpec {
     pub value: String,
 }
 
+/// Descriptive metadata for a title — everything a richer library UI (details pane, platform
+/// filter, couch-pick badges) renders beyond the poster. Every field is optional and defaults to
+/// absent, so pre-metadata catalogs, providers, and clients keep working unchanged. The struct is
+/// `#[serde(flatten)]`-ed into [`GameEntry`] / the custom-store shapes: one definition, a flat
+/// wire shape everywhere.
+///
+/// Values are free-form display strings, not enums — emulation sources (RomM, EmuDeck, Playnite)
+/// each have their own vocabulary and the host has no business normalizing it.
+#[derive(Clone, Debug, Default, Serialize, Deserialize, ToSchema)]
+pub struct GameMeta {
+    /// The system the title runs on — `"PS2"`, `"Xbox 360"`, `"SNES"`, … Installed-store
+    /// scanners stamp `"PC"`; `GET /library?platform=` filters on it (case-insensitive).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schema(example = "PS2")]
+    pub platform: Option<String>,
+    /// Short blurb for a details pane.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub developer: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub publisher: Option<String>,
+    /// Year of first release — the granularity metadata sources reliably agree on.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schema(example = 2001)]
+    pub release_year: Option<u16>,
+    /// Genre taxonomy from the metadata source (`"RPG"`, `"Platformer"`, …).
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub genres: Vec<String>,
+    /// Free-form organizational labels (`"co-op"`, `"kids"`, `"finished"`, …).
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub tags: Vec<String>,
+    /// Release region — emulation-relevant (`"NTSC-U"`, `"PAL"`, `"NTSC-J"`).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub region: Option<String>,
+    /// Maximum simultaneous (local) players.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub players: Option<u8>,
+}
+
+impl GameMeta {
+    /// The one field an installed-store scanner can assert about its own titles: they run on this
+    /// host, i.e. on a PC. Everything else stays absent (the launchers' local files don't carry it).
+    pub(crate) fn pc() -> Self {
+        GameMeta {
+            platform: Some("PC".into()),
+            ..Default::default()
+        }
+    }
+}
+
 /// One title in the unified library, regardless of which store it came from.
 #[derive(Clone, Debug, Serialize, ToSchema)]
 pub struct GameEntry {
@@ -113,6 +164,9 @@ pub struct GameEntry {
     #[serde(skip)]
     #[schema(ignore)]
     pub detect: DetectSpec,
+    /// Descriptive metadata, flattened — see [`GameMeta`].
+    #[serde(flatten)]
+    pub meta: GameMeta,
 }
 
 /// A store that contributes titles to the library. The trait is the extension point for future

crates/punktfunk-host/src/library/custom.rs

@@ -37,6 +37,9 @@ pub struct CustomEntry {
     /// the host would otherwise lose the game the moment the shim returns.
     #[serde(default, skip_serializing_if = "DetectHint::is_empty")]
     pub detect: DetectHint,
+    /// Descriptive metadata (platform, description, …), flattened — see [`GameMeta`].
+    #[serde(flatten)]
+    pub meta: GameMeta,
 }
 
 /// Request body to create or replace a custom entry (no `id` — the host owns it).
@@ -53,6 +56,10 @@ pub struct CustomInput {
     /// How to recognize this title's process — see [`CustomEntry::detect`].
     #[serde(default)]
     pub detect: DetectHint,
+    /// Descriptive metadata (platform, description, …), flattened — see [`GameMeta`]. Replaced
+    /// wholesale on update, like `art`: an edit must round-trip every field it wants kept.
+    #[serde(flatten)]
+    pub meta: GameMeta,
 }
 
 /// One title in a provider's declarative reconcile payload (RFC §8): [`CustomInput`] plus the
@@ -74,6 +81,9 @@ pub struct ProviderEntryInput {
     /// through the provider's own client still end its session when the player quits.
     #[serde(default)]
     pub detect: DetectHint,
+    /// Descriptive metadata (platform, description, …), flattened — see [`GameMeta`].
+    #[serde(flatten)]
+    pub meta: GameMeta,
 }
 
 impl From<CustomEntry> for GameEntry {
@@ -98,6 +108,7 @@ impl From<CustomEntry> for GameEntry {
             launch: c.launch,
             provider: c.provider,
             detect,
+            meta: c.meta,
         }
     }
 }
@@ -188,6 +199,7 @@ pub fn add_custom(input: CustomInput) -> Result<CustomEntry> {
         provider: None,
         external_id: None,
         detect: input.detect,
+        meta: input.meta,
     };
     entries.push(entry.clone());
     save_custom(&entries)?;
@@ -210,6 +222,7 @@ pub fn update_custom(id: &str, input: CustomInput) -> Result<MutateOutcome<Custo
     slot.launch = input.launch;
     slot.prep = input.prep;
     slot.detect = input.detect;
+    slot.meta = input.meta;
     let updated = slot.clone();
     save_custom(&entries)?;
     emit_changed("manual");
@@ -305,6 +318,7 @@ fn reconcile_entries(
             provider: Some(provider.to_string()),
             external_id: Some(input.external_id),
             detect: input.detect,
+            meta: input.meta,
         });
     }
     // `existing`'s leftovers are the orphans — deliberately dropped (declarative reconcile).
@@ -383,6 +397,7 @@ mod tests {
             provider: None,
             external_id: None,
             detect: DetectHint::default(),
+            meta: GameMeta::default(),
         }
     }
 
@@ -394,6 +409,7 @@ mod tests {
             launch: None,
             prep: Vec::new(),
             detect: DetectHint::default(),
+            meta: GameMeta::default(),
         }
     }
 
@@ -407,8 +423,43 @@ mod tests {
         let mut e = manual("def456", "Synced");
         e.provider = Some("romm".into());
         e.external_id = Some("rom-1".into());
+        e.meta.platform = Some("PS2".into());
         let g: GameEntry = e.into();
         assert_eq!(g.provider.as_deref(), Some("romm"));
+        assert_eq!(g.meta.platform.as_deref(), Some("PS2"));
+    }
+
+    /// The metadata contract on the wire and on disk: fields serialize FLAT (no `meta` nesting —
+    /// clients and plugins see `platform` beside `title`), absent fields vanish entirely, and a
+    /// pre-metadata `library.json` / payload still parses (all-optional).
+    #[test]
+    fn meta_is_flat_and_optional_on_the_wire() {
+        let mut e = manual("abc123", "Shadow of the Colossus");
+        e.meta = GameMeta {
+            platform: Some("PS2".into()),
+            release_year: Some(2005),
+            genres: vec!["Adventure".into()],
+            ..Default::default()
+        };
+        let v = serde_json::to_value(&e).unwrap();
+        assert_eq!(v["platform"], "PS2");
+        assert_eq!(v["release_year"], 2005);
+        assert_eq!(v["genres"][0], "Adventure");
+        assert!(v.get("meta").is_none(), "flattened, not nested");
+        assert!(v.get("description").is_none(), "absent fields are omitted");
+        assert!(v.get("tags").is_none(), "empty lists are omitted");
+
+        // A pre-metadata entry (what an existing library.json holds) still deserializes.
+        let old = r#"{"id":"abc","title":"Old"}"#;
+        let e: CustomEntry = serde_json::from_str(old).unwrap();
+        assert!(e.meta.platform.is_none());
+
+        // And a provider payload can carry the fields flat, next to `title` (RFC §8 shape).
+        let payload = r#"{"external_id":"rom-1","title":"OoT","platform":"N64",
+                          "region":"NTSC-U","players":1,"tags":["kids"]}"#;
+        let p: ProviderEntryInput = serde_json::from_str(payload).unwrap();
+        assert_eq!(p.meta.platform.as_deref(), Some("N64"));
+        assert_eq!(p.meta.players, Some(1));
     }
 
     /// The RFC §8 contract in one walk: add keeps ids stable across re-syncs, updates flow,

crates/punktfunk-host/src/library/epic.rs

@@ -100,6 +100,7 @@ fn epic_entry(
     };
     Some(GameEntry {
         provider: None,
+        meta: GameMeta::pc(),
         id: format!("epic:{app_name}"),
         store: "epic".into(),
         title,

crates/punktfunk-host/src/library/gog.rs

@@ -57,6 +57,7 @@ fn gog_games() -> Vec<GameEntry> {
         let detect = DetectSpec::exe(&exe).with_dir(&path);
         out.push(GameEntry {
             provider: None,
+            meta: GameMeta::pc(),
             id,
             store: "gog".into(),
             title,

crates/punktfunk-host/src/library/heroic.rs

@@ -109,6 +109,7 @@ fn heroic_games(path: &Path, runner: &str, key: &str) -> anyhow::Result<Vec<Game
         };
         games.push(GameEntry {
             provider: None,
+            meta: GameMeta::pc(),
             id: format!("heroic:{runner}:{app_name}"),
             store: "heroic".into(),
             title,

crates/punktfunk-host/src/library/lutris.rs

@@ -84,6 +84,7 @@ fn lutris_games(db: &Path) -> rusqlite::Result<Vec<GameEntry>> {
     for (id, slug, name, directory) in rows.flatten() {
         games.push(GameEntry {
             provider: None,
+            meta: GameMeta::pc(),
             id: format!("lutris:{id}"),
             store: "lutris".into(),
             title: name,

crates/punktfunk-host/src/library/steam.rs

@@ -29,6 +29,7 @@ impl LibraryProvider for SteamProvider {
             .filter(|app| !is_steam_tool(app.appid, &app.name))
             .map(|app| GameEntry {
                 provider: None,
+                meta: GameMeta::pc(),
                 id: format!("steam:{}", app.appid),
                 store: "steam".into(),
                 art: steam_art(app.appid),
@@ -382,6 +383,7 @@ fn shortcut_entry(sc: Shortcut) -> Option<GameEntry> {
     }
     Some(GameEntry {
         provider: None,
+        meta: GameMeta::pc(),
         id: format!("steam:{}", sc.appid),
         store: "steam".into(),
         title: sc.name,

crates/punktfunk-host/src/library/xbox.rs

@@ -70,6 +70,7 @@ fn xbox_games() -> Vec<GameEntry> {
             let art = cached_art(&id).unwrap_or_default();
             games.push(GameEntry {
                 provider: None,
+                meta: GameMeta::pc(),
                 id,
                 store: "xbox".into(),
                 title,

crates/punktfunk-host/src/mgmt/library.rs

@@ -8,6 +8,8 @@ use axum::http::header;
 pub(crate) struct LibraryQuery {
     /// Only entries owned by this external provider (RFC §8).
     provider: Option<String>,
+    /// Only entries on this platform (case-insensitive).
+    platform: Option<String>,
 }
 
 /// List the game library
@@ -15,7 +17,8 @@ pub(crate) struct LibraryQuery {
 /// Every installed-store title (Steam, read from the host's local files — no Steam API key)
 /// merged with the user's custom entries, sorted by title. Artwork fields are URLs the client
 /// fetches directly (the public Steam CDN for Steam titles). `?provider=` narrows to the
-/// entries a given external provider owns.
+/// entries a given external provider owns; `?platform=` to one platform (case-insensitive —
+/// installed-store titles are `PC`, custom/provider entries carry whatever was authored).
 #[utoipa::path(
     get,
     path = "/library",
@@ -23,6 +26,7 @@ pub(crate) struct LibraryQuery {
     operation_id = "getLibrary",
     params(
         ("provider" = Option<String>, Query, description = "Only entries owned by this external provider"),
+        ("platform" = Option<String>, Query, description = "Only entries on this platform (case-insensitive, e.g. `PS2`)"),
     ),
     responses(
         (status = OK, description = "Unified library across all stores", body = [crate::library::GameEntry]),
@@ -36,6 +40,14 @@ pub(crate) async fn get_library(
     if let Some(provider) = q.provider.filter(|p| !p.is_empty()) {
         games.retain(|g| g.provider.as_deref() == Some(provider.as_str()));
     }
+    if let Some(platform) = q.platform.filter(|p| !p.is_empty()) {
+        games.retain(|g| {
+            g.meta
+                .platform
+                .as_deref()
+                .is_some_and(|p| p.eq_ignore_ascii_case(&platform))
+        });
+    }
     // Rewrite provider entries' local-file art into host art-proxy URLs so a client fetches covers
     // from the host (a provider like Playnite stores on-host paths; the payload stays tiny at any
     // library size, and the client never sees an unreachable `C:\…`).