Merge branch 'docs/mediacenter-videos-app': Videos group app

Poster grid / flat list browsing, TMDB metadata enrichment, thumbnail
generation and caching, season-specific overviews, manual match
correction, and the create-group wizard's app-selection step.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LAmyXtc6dAADsH23ydXQpY

3 files changed, 68 insertions, 1 deletions

diff --git a/packages/meshbay-common/src/meshbay_common/__init__.py b/packages/meshbay-common/src/meshbay_common/__init__.py
index a622623..938f5d4 100644
--- a/packages/meshbay-common/src/meshbay_common/__init__.py
+++ b/packages/meshbay-common/src/meshbay_common/__init__.py
@@ -8,5 +8,15 @@ __version__ = "0.6.0"
 # handshake ack, for the group-applications registry. Additive — a node that
 # predates it is never sent the op, and a client that predates it never looks
 # for the field — so this is a MINOR bump too.
-MNP_VERSION = "0.4"
+# 0.5: added `width`/`height`/`display_title`/`season`/`episode` to
+# `IndexEntry`, started populating the already-declared `duration`/
+# `thumb_hash`, and added `media_meta_req`/`media_meta_resp`, for the Videos
+# group app. Additive — an older client simply doesn't render the new
+# fields — so this is a MINOR bump too.
+# 0.6: added `season_meta_req`/`season_meta_resp` (per-season TMDB overview,
+# rather than one static show-level summary applied to every season alike)
+# and `tmdb_search_req`/`tmdb_search_resp` + `tmdb_override`/`tmdb_override_ack`
+# (an operator correcting a wrong automatic TMDB match, found live against a
+# real show fragmented across TMDB entries per season). All additive.
+MNP_VERSION = "0.6"
 MHP_VERSION = "0.1"
diff --git a/packages/meshbay-common/src/meshbay_common/adminop.py b/packages/meshbay-common/src/meshbay_common/adminop.py
index c48f011..51396c7 100644
--- a/packages/meshbay-common/src/meshbay_common/adminop.py
+++ b/packages/meshbay-common/src/meshbay_common/adminop.py
@@ -61,6 +61,21 @@ OP_APPS_ENABLED = "apps_enabled"
 # security property in itself, but the pattern (every operator setting is
 # signed) is what keeps the authorization model simple to reason about.
 OP_SET_SCAN_SETTINGS = "set_scan_settings"
+# Whether the node calls TMDB at all, and whether it uses the operator's own
+# API token instead of the shipped default. Signed like the rest: it turns
+# on outbound third-party network traffic that did not exist before the
+# Videos app (docs/mediacenter.md §5.5, §8) — an unsigned toggle would let
+# any member turn on egress the operator never agreed to.
+OP_TMDB_CONFIG = "tmdb_config"
+# Which folder (possibly a subfolder of a shared root) is the Videos app's
+# entry point for this group — per-group, unlike tmdb_config. Signed like
+# the rest: it decides what every member's Videos tab shows.
+OP_VIDEO_ROOT = "video_root"
+# Correcting a wrong automatic TMDB match — signed for the same reason as
+# tmdb_config: it changes what every member sees for a show/movie, node-wide
+# (media_cache is shared, not per-viewer), so an unsigned override would let
+# any member vandalize another show's metadata.
+OP_TMDB_OVERRIDE = "tmdb_override"
 OP_ROOT_ADD = "root_add"
 OP_ROOT_REMOVE = "root_remove"
 OP_GROUP_ATTACH = "group_attach"
diff --git a/packages/meshbay-common/src/meshbay_common/protocol.py b/packages/meshbay-common/src/meshbay_common/protocol.py
index e1bfb8e..900acc2 100644
--- a/packages/meshbay-common/src/meshbay_common/protocol.py
+++ b/packages/meshbay-common/src/meshbay_common/protocol.py
@@ -90,6 +90,18 @@ class MNP:
     APPS_ENABLED_ACK     = "apps_enabled_ack"
     SET_SCAN_SETTINGS     = "set_scan_settings"     # operator → node: reconcile/debounce timing
     SET_SCAN_SETTINGS_ACK = "set_scan_settings_ack"
+    MEDIA_META_REQ        = "media_meta_req"        # client → node: TMDB metadata for a path
+    MEDIA_META_RESP       = "media_meta_resp"       # node → client: TMDB metadata (or none)
+    VIDEO_ROOT            = "video_root"             # operator → node: which folder is the Videos entry point
+    VIDEO_ROOT_ACK        = "video_root_ack"
+    TMDB_CONFIG           = "tmdb_config"            # operator → node: enable/disable TMDB, set token
+    TMDB_CONFIG_ACK       = "tmdb_config_ack"        # node → everyone: new TMDB config (never the token)
+    SEASON_META_REQ       = "season_meta_req"        # client → node: TMDB overview/poster for one season
+    SEASON_META_RESP      = "season_meta_resp"       # node → client: season-level TMDB fields (or none)
+    TMDB_SEARCH_REQ       = "tmdb_search_req"        # client → node: candidate TMDB matches for a query
+    TMDB_SEARCH_RESP      = "tmdb_search_resp"       # node → client: candidate list (id, title, year, poster)
+    TMDB_OVERRIDE         = "tmdb_override"          # operator → node: replace a show/movie's TMDB match
+    TMDB_OVERRIDE_ACK     = "tmdb_override_ack"
     # Device linking. A new device files a request bound to a code it displays;
     # an already-pinned device of the same account approves it. Neither the hub
     # nor the node can produce the countersignature.
@@ -141,6 +153,30 @@ class IndexEntry:
     thumb_hash: str | None = None  # blake3 of thumbnail
     uploader_id: str | None = None  # user_id of who uploaded (None = pre-existing on disk)
     uploader_pk: str | None = None  # Ed25519 public key of uploader (base64 raw 32 bytes)
+    width:      int | None = None  # pixels, video only
+    height:     int | None = None  # pixels, video only
+    display_title: str | None = None  # parsed or cleaned-filename title, Videos app
+    season:     int | None = None  # parsed season number, Videos app
+    episode:    int | None = None  # parsed episode number, Videos app
+
+
+def index_entry_wire(e: IndexEntry) -> dict:
+    """
+    The wire-dict shape used by INDEX_SYNC/INDEX_DELTA hand-built messages
+    (as opposed to GroupIndex.serialize()'s asdict() encoding of the whole
+    index). Centralized so the three call sites that build these
+    (webrtc_server._do_index_sync, daemon._broadcast_index_change's two
+    branches) can't drift from each other as fields are added.
+    """
+    return {
+        "id": e.id, "name": e.name, "path": e.path,
+        "size": e.size, "type": e.type, "added_at": e.added_at,
+        "uploader_id": e.uploader_id,
+        "duration": e.duration, "thumb_hash": e.thumb_hash,
+        "width": e.width, "height": e.height,
+        "display_title": e.display_title,
+        "season": e.season, "episode": e.episode,
+    }
 
 
 @dataclass
@@ -149,6 +185,12 @@ class IndexDelta:
     version:      int
     additions:    list[IndexEntry] = field(default_factory=list)
     deletions:    list[str] = field(default_factory=list)  # list of ids
+    # Same id as before (same file, same content hash), different field
+    # values — e.g. the Videos app's async enrichment filling in duration/
+    # thumb_hash/etc. after the file was already indexed with hash+size only.
+    # A distinct list from `additions`: `GroupIndex.diff()` only ever adds an
+    # id here once it has already appeared unchanged in a prior snapshot.
+    updates:      list[IndexEntry] = field(default_factory=list)
 
 
 # ── Chunk request/response ────────────────────────────────────────────────────