Nightly: bump version and refresh snapshots

.gitignore

@@ -17,3 +17,6 @@
 __pycache__/
 *.pyc
 .coverage
+
+# Plugin runtime caches
+/addon/plugins/*_cache.json

README.md

@@ -14,6 +14,7 @@ ViewIT ist ein Kodi‑Addon zum Durchsuchen und Abspielen von Inhalten der unter
 - Addon‑Ordner bauen: `./scripts/build_install_addon.sh` → `dist/<addon_id>/`
 - Kodi‑ZIP bauen: `./scripts/build_kodi_zip.sh` → `dist/<addon_id>-<version>.zip`
 - Addon‑Version in `addon/addon.xml`
+- Reproduzierbare ZIPs: optional `SOURCE_DATE_EPOCH` setzen
 
 ## Lokales Kodi-Repository
 - Repository bauen (inkl. ZIPs + `addons.xml` + `addons.xml.md5`): `./scripts/build_local_kodi_repo.sh`

addon/addon.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<addon id="plugin.video.viewit" name="ViewIt" version="0.1.50" provider-name="ViewIt">
+<addon id="plugin.video.viewit" name="ViewIt" version="0.1.51" provider-name="ViewIt">
   <requires>
     <import addon="xbmc.python" version="3.0.0" />
     <import addon="script.module.requests" />

addon/default.py

@@ -1230,11 +1230,16 @@ def _discover_plugins() -> dict[str, BasisPlugin]:
         except Exception as exc:
             xbmc.log(f"Plugin-Datei {file_path.name} konnte nicht geladen werden: {exc}", xbmc.LOGWARNING)
             continue
+        preferred = getattr(module, "Plugin", None)
+        if inspect.isclass(preferred) and issubclass(preferred, BasisPlugin) and preferred is not BasisPlugin:
+            plugin_classes = [preferred]
+        else:
             plugin_classes = [
                 obj
                 for obj in module.__dict__.values()
                 if inspect.isclass(obj) and issubclass(obj, BasisPlugin) and obj is not BasisPlugin
             ]
+            plugin_classes.sort(key=lambda cls: cls.__name__.casefold())
         for cls in plugin_classes:
             try:
                 instance = cls()
@@ -1245,7 +1250,21 @@ def _discover_plugins() -> dict[str, BasisPlugin]:
                 reason = getattr(instance, "unavailable_reason", "Nicht verfuegbar.")
                 xbmc.log(f"Plugin {cls.__name__} deaktiviert: {reason}", xbmc.LOGWARNING)
                 continue
-            plugins[instance.name] = instance
+            plugin_name = str(getattr(instance, "name", "") or "").strip()
+            if not plugin_name:
+                xbmc.log(
+                    f"Plugin {cls.__name__} wurde ohne Name registriert und wird uebersprungen.",
+                    xbmc.LOGWARNING,
+                )
+                continue
+            if plugin_name in plugins:
+                xbmc.log(
+                    f"Plugin-Name doppelt ({plugin_name}), {cls.__name__} wird uebersprungen.",
+                    xbmc.LOGWARNING,
+                )
+                continue
+            plugins[plugin_name] = instance
+    plugins = dict(sorted(plugins.items(), key=lambda item: item[0].casefold()))
     _PLUGIN_CACHE = plugins
     return plugins
 

addon/plugin_interface.py

@@ -4,7 +4,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import List, Optional, Set
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 
 class BasisPlugin(ABC):
@@ -12,6 +12,7 @@ class BasisPlugin(ABC):
 
     name: str
     version: str = "0.0.0"
+    prefer_source_metadata: bool = False
 
     @abstractmethod
     async def search_titles(self, query: str) -> List[str]:
@@ -29,6 +30,10 @@ class BasisPlugin(ABC):
         """Optional: Liefert den Stream-Link fuer eine konkrete Folge."""
         return None
 
+    def metadata_for(self, title: str) -> Tuple[Dict[str, str], Dict[str, str], Optional[List[Any]]]:
+        """Optional: Liefert Info-Labels, Art und Cast fuer einen Titel."""
+        return {}, {}, None
+
     def resolve_stream_link(self, link: str) -> Optional[str]:
         """Optional: Folgt einem Stream-Link und liefert die finale URL."""
         return None

addon/plugins/einschalten_plugin.py

@@ -1079,3 +1079,7 @@ class EinschaltenPlugin(BasisPlugin):
             return []
         # Backwards compatible: first page only. UI uses paging via `new_titles_page`.
         return self.new_titles_page(1)
+
+
+# Alias für die automatische Plugin-Erkennung.
+Plugin = EinschaltenPlugin

addon/plugins/filmpalast_plugin.py

@@ -922,3 +922,7 @@ class FilmpalastPlugin(BasisPlugin):
             _log_url_event(redirected, kind="FINAL")
             return redirected
         return None
+
+
+# Alias für die automatische Plugin-Erkennung.
+Plugin = FilmpalastPlugin

addon/plugins/topstreamfilm_plugin.py

@@ -57,7 +57,7 @@ else:  # pragma: no cover
 
 ADDON_ID = "plugin.video.viewit"
 SETTING_BASE_URL = "topstream_base_url"
-DEFAULT_BASE_URL = "https://www.meineseite"
+DEFAULT_BASE_URL = "https://topstreamfilm.live"
 GLOBAL_SETTING_LOG_URLS = "debug_log_urls"
 GLOBAL_SETTING_DUMP_HTML = "debug_dump_html"
 GLOBAL_SETTING_SHOW_URL_INFO = "debug_show_url_info"

docs/DEFAULT_ROUTER.md

@@ -10,7 +10,7 @@ Dieses Dokument beschreibt den Einstiegspunkt des Addons und die zentrale Steuer
 - startet die Wiedergabe und verwaltet Playstate/Resume.
 
 ## Ablauf (high level)
-1. **Plugin‑Discovery**: Lädt alle `addon/plugins/*.py` (ohne `_`‑Prefix) und instanziiert Klassen, die von `BasisPlugin` erben.
+1. **Plugin‑Discovery**: Lädt alle `addon/plugins/*.py` (ohne `_`‑Prefix). Bevorzugt `Plugin = <Klasse>`, sonst werden `BasisPlugin`‑Subklassen deterministisch instanziiert.
 2. **Navigation**: Baut Kodi‑Listen (Serien/Staffeln/Episoden) auf Basis der Plugin‑Antworten.
 3. **Playback**: Holt Stream‑Links aus dem Plugin und startet die Wiedergabe.
 4. **Playstate**: Speichert Resume‑Daten lokal (`playstate.json`) und setzt `playcount`/Resume‑Infos.
@@ -35,6 +35,7 @@ Die genaue Aktion wird aus den Query‑Parametern gelesen und an das entsprechen
 - **Plugin‑Loader**: findet & instanziiert Plugins.
 - **UI‑Helper**: setzt Content‑Type, baut Verzeichnisseinträge.
 - **Playstate‑Helper**: `_load_playstate`, `_save_playstate`, `_apply_playstate_to_info`.
+- **Metadata‑Merge**: Plugin‑Metadaten können TMDB übersteuern, TMDB dient als Fallback.
 
 ## Fehlerbehandlung
 - Plugin‑Importfehler werden isoliert behandelt, damit das Addon nicht komplett ausfällt.

docs/PLUGIN_DEVELOPMENT.md

@@ -6,6 +6,7 @@ Diese Doku beschreibt, wie Plugins im ViewIT‑Addon aufgebaut sind und wie neue
 - Jedes Plugin ist eine einzelne Datei unter `addon/plugins/`.
 - Dateinamen **ohne** `_`‑Prefix werden automatisch geladen.
 - Jede Datei enthält eine Klasse, die von `BasisPlugin` erbt.
+- Optional: `Plugin = <Klasse>` als expliziter Einstiegspunkt (bevorzugt vom Loader).
 
 ## Pflicht‑Methoden (BasisPlugin)
 Jedes Plugin muss diese Methoden implementieren:
@@ -22,6 +23,7 @@ Wesentliche Rückgaben an die Hauptlogik:
 - `episodes_for(...)` → Liste von Episoden-Labels
 - `stream_link_for(...)` → Hoster-/Player-Link (nicht zwingend finale Media-URL)
 - `resolve_stream_link(...)` → finale/spielbare URL nach Redirect/Resolver
+- `metadata_for(...)` → Info-Labels/Art (Plot/Poster) aus der Quelle
 - Optional `available_hosters_for(...)` → auswählbare Hoster-Namen im Dialog
 - Optional `series_url_for_title(...)` → stabile Detail-URL pro Titel für Folgeaufrufe
 - Optional `remember_series_url(...)` → Übernahme einer bereits bekannten Detail-URL
@@ -35,6 +37,9 @@ Standard für Film-Provider (ohne echte Staffeln):
 - `popular_series` → `popular_series()`
 - `genres` → `genres()` + `titles_for_genre(genre)`
 - `latest_episodes` → `latest_episodes(page=1)`
+- `new_titles` → `new_titles_page(page=1)`
+- `alpha` → `alpha_index()` + `titles_for_alpha_page(letter, page)`
+- `series_catalog` → `series_catalog_page(page=1)`
 
 ## Empfohlene Struktur
 - Konstanten für URLs/Endpoints (BASE_URL, Pfade, Templates)
@@ -60,6 +65,7 @@ Standard: `*_base_url` (Domain / BASE_URL)
   - `einschalten_base_url`
   - `topstream_base_url`
   - `filmpalast_base_url`
+  - `doku_streams_base_url`
 
 ## Playback
 - `stream_link_for(...)` implementieren (liefert bevorzugten Hoster-Link).
@@ -75,7 +81,8 @@ Standard: `*_base_url` (Domain / BASE_URL)
 2. **Navigation**: `series_url_for_title`/`remember_series_url` unterstützen, damit URLs zwischen Aufrufen stabil bleiben.
 3. **Auswahl Hoster**: Hoster-Namen aus der Detailseite extrahieren und anbieten.
 4. **Playback**: Hoster-Link liefern, danach konsistent über `resolve_stream_link` finalisieren.
-5. **Fallbacks**: bei Layout-Unterschieden defensiv parsen und Logging aktivierbar halten.
+5. **Metadaten**: `metadata_for` nutzen, Plot/Poster aus der Quelle zurückgeben.
+6. **Fallbacks**: bei Layout-Unterschieden defensiv parsen und Logging aktivierbar halten.
 
 ## Debugging
 Global gesteuert über Settings:
@@ -94,6 +101,8 @@ Plugins sollten die Helper aus `addon/plugin_helpers.py` nutzen:
 ## Build & Test
 - ZIP bauen: `./scripts/build_kodi_zip.sh`
 - Addon‑Ordner: `./scripts/build_install_addon.sh`
+- Plugin‑Manifest aktualisieren: `python3 scripts/generate_plugin_manifest.py`
+- Live-Snapshot-Checks: `python3 qa/run_plugin_snapshots.py` (aktualisieren mit `--update`)
 
 ## Beispiel‑Checkliste
 - [ ] `name` korrekt gesetzt

docs/PLUGIN_MANIFEST.json

@@ -0,0 +1,104 @@
+{
+  "schema_version": 1,
+  "plugins": [
+    {
+      "file": "addon/plugins/aniworld_plugin.py",
+      "module": "aniworld_plugin",
+      "name": "Aniworld",
+      "class": "AniworldPlugin",
+      "version": "1.0.0",
+      "capabilities": [
+        "genres",
+        "latest_episodes",
+        "popular_series"
+      ],
+      "prefer_source_metadata": false,
+      "base_url_setting": "aniworld_base_url",
+      "available": true,
+      "unavailable_reason": null,
+      "error": null
+    },
+    {
+      "file": "addon/plugins/dokustreams_plugin.py",
+      "module": "dokustreams_plugin",
+      "name": "Doku-Streams",
+      "class": "DokuStreamsPlugin",
+      "version": "1.0.0",
+      "capabilities": [
+        "genres",
+        "popular_series"
+      ],
+      "prefer_source_metadata": true,
+      "base_url_setting": "doku_streams_base_url",
+      "available": true,
+      "unavailable_reason": null,
+      "error": null
+    },
+    {
+      "file": "addon/plugins/einschalten_plugin.py",
+      "module": "einschalten_plugin",
+      "name": "Einschalten",
+      "class": "EinschaltenPlugin",
+      "version": "1.0.0",
+      "capabilities": [
+        "genres",
+        "new_titles"
+      ],
+      "prefer_source_metadata": false,
+      "base_url_setting": "einschalten_base_url",
+      "available": true,
+      "unavailable_reason": null,
+      "error": null
+    },
+    {
+      "file": "addon/plugins/filmpalast_plugin.py",
+      "module": "filmpalast_plugin",
+      "name": "Filmpalast",
+      "class": "FilmpalastPlugin",
+      "version": "1.0.0",
+      "capabilities": [
+        "alpha",
+        "genres",
+        "series_catalog"
+      ],
+      "prefer_source_metadata": false,
+      "base_url_setting": "filmpalast_base_url",
+      "available": true,
+      "unavailable_reason": null,
+      "error": null
+    },
+    {
+      "file": "addon/plugins/serienstream_plugin.py",
+      "module": "serienstream_plugin",
+      "name": "Serienstream",
+      "class": "SerienstreamPlugin",
+      "version": "1.0.0",
+      "capabilities": [
+        "genres",
+        "latest_episodes",
+        "popular_series"
+      ],
+      "prefer_source_metadata": false,
+      "base_url_setting": "serienstream_base_url",
+      "available": true,
+      "unavailable_reason": null,
+      "error": null
+    },
+    {
+      "file": "addon/plugins/topstreamfilm_plugin.py",
+      "module": "topstreamfilm_plugin",
+      "name": "Topstreamfilm",
+      "class": "TopstreamfilmPlugin",
+      "version": "1.0.0",
+      "capabilities": [
+        "genres",
+        "popular_series"
+      ],
+      "prefer_source_metadata": false,
+      "base_url_setting": "topstream_base_url",
+      "available": true,
+      "unavailable_reason": null,
+      "error": null
+    }
+  ]
+}

docs/PLUGIN_SYSTEM.md

@@ -9,6 +9,7 @@ ViewIt lädt Provider-Integrationen dynamisch aus `addon/plugins/*.py`. Jede Dat
 Weitere Details:
 - `docs/DEFAULT_ROUTER.md` (Hauptlogik in `addon/default.py`)
 - `docs/PLUGIN_DEVELOPMENT.md` (Entwicklerdoku für Plugins)
+- `docs/PLUGIN_MANIFEST.json` (zentraler Überblick über Plugins, Versionen, Capabilities)
 
 ### Aktuelle Plugins
 
@@ -17,6 +18,7 @@ Weitere Details:
 - `einschalten_plugin.py` – Einschalten
 - `aniworld_plugin.py` – Aniworld
 - `filmpalast_plugin.py` – Filmpalast
+- `dokustreams_plugin.py` – Doku-Streams
 - `_template_plugin.py` – Vorlage für neue Plugins
 
 ### Plugin-Discovery (Ladeprozess)
@@ -26,11 +28,16 @@ Der Loader in `addon/default.py`:
 1. Sucht alle `*.py` in `addon/plugins/`
 2. Überspringt Dateien, die mit `_` beginnen
 3. Lädt Module dynamisch
-4. Instanziert Klassen, die von `BasisPlugin` erben
-5. Ignoriert Plugins mit `is_available = False`
+4. Nutzt `Plugin = <Klasse>` als bevorzugten Einstiegspunkt (falls vorhanden)
+5. Fallback: instanziert Klassen, die von `BasisPlugin` erben (deterministisch sortiert)
+6. Ignoriert Plugins mit `is_available = False`
 
 Damit bleiben fehlerhafte Plugins isoliert und blockieren nicht das gesamte Add-on.
 
+### Plugin-Manifest (Audit & Repro)
+`docs/PLUGIN_MANIFEST.json` listet alle Plugins mit Version, Capabilities und Basis-Settings.
+Erzeugung: `python3 scripts/generate_plugin_manifest.py`
+
 ### BasisPlugin – verpflichtende Methoden
 
 Definiert in `addon/plugin_interface.py`:
@@ -38,19 +45,29 @@ Definiert in `addon/plugin_interface.py`:
 - `async search_titles(query: str) -> list[str]`
 - `seasons_for(title: str) -> list[str]`
 - `episodes_for(title: str, season: str) -> list[str]`
+- optional `metadata_for(title: str) -> (info_labels, art, cast)`
 
 ### Optionale Features (Capabilities)
 
 Plugins können zusätzliche Features anbieten:
 
 - `capabilities() -> set[str]`
-  - `popular_series`: liefert beliebte Serien
-  - `genres`: Genre-Liste verfügbar
-  - `latest_episodes`: neue Episoden verfügbar
+- `popular_series`: liefert beliebte Serien
+- `genres`: Genre-Liste verfügbar
+- `latest_episodes`: neue Episoden verfügbar
+- `new_titles`: neue Titel verfügbar
+- `alpha`: A-Z Index verfügbar
+- `series_catalog`: Serienkatalog verfügbar
 - `popular_series() -> list[str]`
 - `genres() -> list[str]`
 - `titles_for_genre(genre: str) -> list[str]`
 - `latest_episodes(page: int = 1) -> list[LatestEpisode]` (wenn angeboten)
+- `new_titles_page(page: int = 1) -> list[str]` (wenn angeboten)
+- `alpha_index() -> list[str]` (wenn angeboten)
+- `series_catalog_page(page: int = 1) -> list[str]` (wenn angeboten)
+
+Metadaten:
+- `prefer_source_metadata = True` bedeutet: Plugin-Metadaten gehen vor TMDB, TMDB dient nur als Fallback.
 
 ViewIt zeigt im UI nur die Features an, die ein Plugin tatsächlich liefert.
 
@@ -62,6 +79,7 @@ Eine Integration sollte typischerweise bieten:
 - `search_titles()` mit Provider-Suche
 - `seasons_for()` und `episodes_for()` mit HTML-Parsing
 - `stream_link_for()` optional für direkte Playback-Links
+- `metadata_for()` optional für Plot/Poster aus der Quelle
 - Optional: `available_hosters_for()` oder Provider-spezifische Helfer
 
 Als Startpunkt dient `addon/plugins/_template_plugin.py`.
@@ -79,8 +97,9 @@ Als Startpunkt dient `addon/plugins/_template_plugin.py`.
 - Keine Netzwerkzugriffe im Import-Top-Level
 - Netzwerkzugriffe nur in Methoden (z. B. `search_titles`)
 - Fehler sauber abfangen und verständliche Fehlermeldungen liefern
-- Kein globaler Zustand, der across instances überrascht
+- Kein globaler Zustand, der über Instanzen hinweg überrascht
 - Provider-spezifische Parser in Helper-Funktionen kapseln
+- Reproduzierbare Reihenfolge: `Plugin`-Alias nutzen oder Klassenname eindeutig halten
 
 ### Debugging & Logs
 

qa/plugin_snapshots.json

@@ -0,0 +1,52 @@
+{
+  "snapshots": {
+    "Serienstream::search_titles::trek": [
+      "Star Trek: Lower Decks",
+      "Star Trek: Prodigy",
+      "Star Trek: The Animated Series",
+      "Inside Star Trek",
+      "Raumschiff Enterprise - Star Trek: The Original Series",
+      "Star Trek: Deep Space Nine",
+      "Star Trek: Discovery",
+      "Star Trek: Enterprise",
+      "Star Trek: Picard",
+      "Star Trek: Raumschiff Voyager",
+      "Star Trek: Short Treks",
+      "Star Trek: Starfleet Academy",
+      "Star Trek: Strange New Worlds",
+      "Star Trek: The Next Generation"
+    ],
+    "Aniworld::search_titles::naruto": [
+      "Naruto",
+      "Naruto Shippuden",
+      "Boruto: Naruto Next Generations",
+      "Naruto Spin-Off: Rock Lee & His Ninja Pals"
+    ],
+    "Topstreamfilm::search_titles::matrix": [
+      "Darkdrive – Verschollen in der Matrix",
+      "Matrix Reloaded",
+      "Armitage III: Poly Matrix",
+      "Matrix Resurrections",
+      "Matrix",
+      "Matrix Revolutions",
+      "Matrix Fighters"
+    ],
+    "Einschalten::new_titles_page::1": [],
+    "Filmpalast::search_titles::trek": [
+      "Star Trek",
+      "Star Trek - Der Film",
+      "Star Trek 2 - Der Zorn des Khan",
+      "Star Trek 9 Der Aufstand",
+      "Star Trek: Nemesis",
+      "Star Trek: Section 31",
+      "Star Trek: Starfleet Academy",
+      "Star Trek: Strange New Worlds"
+    ],
+    "Doku-Streams::search_titles::japan": [
+      "Deutsche im Knast - Japan und die Disziplin",
+      "Die Meerfrauen von Japan",
+      "Japan - Land der Moderne und Tradition",
+      "Japan im Zweiten Weltkrieg - Der Fall des Kaiserreichs"
+    ]
+  }
+}

qa/run_plugin_snapshots.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Run live snapshot checks for plugins.
+
+Use --update to refresh stored snapshots.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib.util
+import inspect
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+PLUGIN_DIR = ROOT_DIR / "addon" / "plugins"
+SNAPSHOT_PATH = ROOT_DIR / "qa" / "plugin_snapshots.json"
+
+sys.path.insert(0, str(ROOT_DIR / "addon"))
+
+try:
+    from plugin_interface import BasisPlugin  # type: ignore
+except Exception as exc:  # pragma: no cover
+    raise SystemExit(f"Failed to import BasisPlugin: {exc}")
+
+CONFIG = [
+    {"plugin": "Serienstream", "method": "search_titles", "args": ["trek"], "max_items": 20},
+    {"plugin": "Aniworld", "method": "search_titles", "args": ["naruto"], "max_items": 20},
+    {"plugin": "Topstreamfilm", "method": "search_titles", "args": ["matrix"], "max_items": 20},
+    {"plugin": "Einschalten", "method": "new_titles_page", "args": [1], "max_items": 20},
+    {"plugin": "Filmpalast", "method": "search_titles", "args": ["trek"], "max_items": 20},
+    {"plugin": "Doku-Streams", "method": "search_titles", "args": ["japan"], "max_items": 20},
+]
+
+
+def _import_module(path: Path):
+    spec = importlib.util.spec_from_file_location(path.stem, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Missing spec for {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _discover_plugins() -> dict[str, BasisPlugin]:
+    plugins: dict[str, BasisPlugin] = {}
+    for file_path in sorted(PLUGIN_DIR.glob("*.py")):
+        if file_path.name.startswith("_"):
+            continue
+        module = _import_module(file_path)
+        preferred = getattr(module, "Plugin", None)
+        if inspect.isclass(preferred) and issubclass(preferred, BasisPlugin) and preferred is not BasisPlugin:
+            classes = [preferred]
+        else:
+            classes = [
+                obj
+                for obj in module.__dict__.values()
+                if inspect.isclass(obj) and issubclass(obj, BasisPlugin) and obj is not BasisPlugin
+            ]
+            classes.sort(key=lambda cls: cls.__name__.casefold())
+        for cls in classes:
+            instance = cls()
+            name = str(getattr(instance, "name", "") or "").strip()
+            if name and name not in plugins:
+                plugins[name] = instance
+    return plugins
+
+
+def _normalize_titles(value: Any, max_items: int) -> list[str]:
+    if not value:
+        return []
+    titles = [str(item).strip() for item in list(value) if item and str(item).strip()]
+    seen = set()
+    normalized: list[str] = []
+    for title in titles:
+        key = title.casefold()
+        if key in seen:
+            continue
+        seen.add(key)
+        normalized.append(title)
+        if len(normalized) >= max_items:
+            break
+    return normalized
+
+
+def _snapshot_key(entry: dict[str, Any]) -> str:
+    args = entry.get("args", [])
+    return f"{entry['plugin']}::{entry['method']}::{','.join(str(a) for a in args)}"
+
+
+def _call_method(plugin: BasisPlugin, method_name: str, args: list[Any]):
+    method = getattr(plugin, method_name, None)
+    if not callable(method):
+        raise RuntimeError(f"Method missing: {method_name}")
+    result = method(*args)
+    if asyncio.iscoroutine(result):
+        return asyncio.run(result)
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--update", action="store_true")
+    args = parser.parse_args()
+
+    snapshots: dict[str, Any] = {}
+    if SNAPSHOT_PATH.exists():
+        snapshots = json.loads(SNAPSHOT_PATH.read_text(encoding="utf-8"))
+    data = snapshots.get("snapshots", {}) if isinstance(snapshots, dict) else {}
+    if args.update:
+        data = {}
+
+    plugins = _discover_plugins()
+    errors = []
+
+    for entry in CONFIG:
+        plugin_name = entry["plugin"]
+        plugin = plugins.get(plugin_name)
+        if plugin is None:
+            errors.append(f"Plugin missing: {plugin_name}")
+            continue
+        key = _snapshot_key(entry)
+        try:
+            result = _call_method(plugin, entry["method"], entry.get("args", []))
+            normalized = _normalize_titles(result, entry.get("max_items", 20))
+        except Exception as exc:
+            errors.append(f"Snapshot error: {key} ({exc})")
+            if args.update:
+                data[key] = {"error": str(exc)}
+            continue
+        if args.update:
+            data[key] = normalized
+        else:
+            expected = data.get(key)
+            if expected != normalized:
+                errors.append(f"Snapshot mismatch: {key}\nExpected: {expected}\nActual:   {normalized}")
+
+    if args.update:
+        SNAPSHOT_PATH.parent.mkdir(parents=True, exist_ok=True)
+        SNAPSHOT_PATH.write_text(json.dumps({"snapshots": data}, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    if errors:
+        for err in errors:
+            print(err)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/build_kodi_zip.sh

@@ -37,6 +37,6 @@ ZIP_PATH="${INSTALL_DIR}/${ZIP_NAME}"
 ADDON_DIR="$("${ROOT_DIR}/scripts/build_install_addon.sh" >/dev/null; echo "${INSTALL_DIR}/${ADDON_ID}")"
 
 rm -f "${ZIP_PATH}"
-(cd "${INSTALL_DIR}" && zip -r "${ZIP_NAME}" "$(basename "${ADDON_DIR}")" >/dev/null)
+python3 "${ROOT_DIR}/scripts/zip_deterministic.py" "${ZIP_PATH}" "${ADDON_DIR}" >/dev/null
 
 echo "${ZIP_PATH}"

scripts/build_local_kodi_repo.sh

@@ -73,7 +73,7 @@ PY
 REPO_ZIP_NAME="${REPO_ADDON_ID}-${REPO_ADDON_VERSION}.zip"
 REPO_ZIP_PATH="${REPO_DIR}/${REPO_ZIP_NAME}"
 rm -f "${REPO_ZIP_PATH}"
-(cd "${TMP_DIR}" && zip -r "${REPO_ZIP_PATH}" "${REPO_ADDON_ID}" >/dev/null)
+python3 "${ROOT_DIR}/scripts/zip_deterministic.py" "${REPO_ZIP_PATH}" "${TMP_REPO_ADDON_DIR}" >/dev/null
 
 python3 - "${PLUGIN_ADDON_XML}" "${TMP_REPO_ADDON_DIR}/addon.xml" "${REPO_DIR}/addons.xml" <<'PY'
 import sys

scripts/generate_plugin_manifest.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Generate a JSON manifest for addon plugins."""
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import json
+import sys
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+PLUGIN_DIR = ROOT_DIR / "addon" / "plugins"
+OUTPUT_PATH = ROOT_DIR / "docs" / "PLUGIN_MANIFEST.json"
+
+sys.path.insert(0, str(ROOT_DIR / "addon"))
+
+try:
+    from plugin_interface import BasisPlugin  # type: ignore
+except Exception as exc:  # pragma: no cover
+    raise SystemExit(f"Failed to import BasisPlugin: {exc}")
+
+
+def _import_module(path: Path):
+    spec = importlib.util.spec_from_file_location(path.stem, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Missing spec for {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _collect_plugins():
+    plugins = []
+    for file_path in sorted(PLUGIN_DIR.glob("*.py")):
+        if file_path.name.startswith("_"):
+            continue
+        entry = {
+            "file": str(file_path.relative_to(ROOT_DIR)),
+            "module": file_path.stem,
+            "name": None,
+            "class": None,
+            "version": None,
+            "capabilities": [],
+            "prefer_source_metadata": False,
+            "base_url_setting": None,
+            "available": None,
+            "unavailable_reason": None,
+            "error": None,
+        }
+        try:
+            module = _import_module(file_path)
+            preferred = getattr(module, "Plugin", None)
+            if inspect.isclass(preferred) and issubclass(preferred, BasisPlugin) and preferred is not BasisPlugin:
+                classes = [preferred]
+            else:
+                classes = [
+                    obj
+                    for obj in module.__dict__.values()
+                    if inspect.isclass(obj) and issubclass(obj, BasisPlugin) and obj is not BasisPlugin
+                ]
+                classes.sort(key=lambda cls: cls.__name__.casefold())
+
+            if not classes:
+                entry["error"] = "No plugin classes found"
+                plugins.append(entry)
+                continue
+
+            cls = classes[0]
+            instance = cls()
+            entry["class"] = cls.__name__
+            entry["name"] = str(getattr(instance, "name", "") or "") or None
+            entry["version"] = str(getattr(instance, "version", "0.0.0") or "0.0.0")
+            entry["prefer_source_metadata"] = bool(getattr(instance, "prefer_source_metadata", False))
+            entry["available"] = bool(getattr(instance, "is_available", True))
+            entry["unavailable_reason"] = getattr(instance, "unavailable_reason", None)
+            try:
+                caps = instance.capabilities()  # type: ignore[call-arg]
+                entry["capabilities"] = sorted([str(c) for c in caps]) if caps else []
+            except Exception:
+                entry["capabilities"] = []
+
+            entry["base_url_setting"] = getattr(module, "SETTING_BASE_URL", None)
+        except Exception as exc:  # pragma: no cover
+            entry["error"] = str(exc)
+        plugins.append(entry)
+
+    plugins.sort(key=lambda item: (item.get("name") or item["module"]).casefold())
+    return plugins
+
+
+def main() -> int:
+    if not PLUGIN_DIR.exists():
+        raise SystemExit("Plugin directory missing")
+    manifest = {
+        "schema_version": 1,
+        "plugins": _collect_plugins(),
+    }
+    OUTPUT_PATH.parent.mkdir(parents=True, exist_ok=True)
+    OUTPUT_PATH.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(str(OUTPUT_PATH))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/zip_deterministic.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Create deterministic zip archives.
+
+Usage:
+  zip_deterministic.py <zip_path> <root_dir>
+
+The archive will include the root directory itself and all files under it.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+import zipfile
+from pathlib import Path
+
+
+def _timestamp() -> tuple[int, int, int, int, int, int]:
+    epoch = os.environ.get("SOURCE_DATE_EPOCH")
+    if epoch:
+        try:
+            value = int(epoch)
+            return time.gmtime(value)[:6]
+        except Exception:
+            pass
+    return (2000, 1, 1, 0, 0, 0)
+
+
+def _iter_files(root: Path):
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted([d for d in dirnames if d != "__pycache__"])
+        for filename in sorted(filenames):
+            if filename.endswith(".pyc"):
+                continue
+            yield Path(dirpath) / filename
+
+
+def _add_file(zf: zipfile.ZipFile, file_path: Path, arcname: str) -> None:
+    info = zipfile.ZipInfo(arcname, date_time=_timestamp())
+    info.compress_type = zipfile.ZIP_DEFLATED
+    info.external_attr = (0o644 & 0xFFFF) << 16
+    with file_path.open("rb") as handle:
+        data = handle.read()
+    zf.writestr(info, data, compress_type=zipfile.ZIP_DEFLATED)
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("Usage: zip_deterministic.py <zip_path> <root_dir>")
+        return 2
+
+    zip_path = Path(sys.argv[1]).resolve()
+    root = Path(sys.argv[2]).resolve()
+    if not root.exists() or not root.is_dir():
+        print(f"Missing root dir: {root}")
+        return 2
+
+    base = root.parent
+    zip_path.parent.mkdir(parents=True, exist_ok=True)
+    if zip_path.exists():
+        zip_path.unlink()
+
+    with zipfile.ZipFile(zip_path, "w") as zf:
+        for file_path in sorted(_iter_files(root)):
+            arcname = str(file_path.relative_to(base)).replace(os.sep, "/")
+            _add_file(zf, file_path, arcname)
+
+    print(str(zip_path))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())