merge: provider API

feat: provider platform with multiple accounts and a provider store

Author: sachk

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,5 +1,5 @@
 name: Bug report
-description: Report a reproducible Spool for Jellyfin defect
+description: Report a reproducible Spool defect
 title: "[Bug]: "
 labels: [bug]
 body:

.github/workflows/build-artifacts.yml

@@ -37,7 +37,7 @@ jobs:
       - name: Upload corresponding source
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.0
         with:
-          name: spool-for-jellyfin-corresponding-source
+          name: spool-corresponding-source
           path: release-source/*
           retention-days: 1
 
@@ -137,6 +137,7 @@ jobs:
           }
           add_row 'macOS — Apple Silicon' '*-macOS-arm64.dmg'
           add_row 'macOS — Intel' '*-macOS-x86_64.dmg'
+          add_row 'Apple TV — unsigned (re-sign required)' '*-tvOS-arm64.ipa'
           add_row 'Windows — installer' '*-Windows-x64-Setup.exe'
           add_row 'Windows — portable' '*-Windows-x64-Portable.exe'
           add_row 'Linux — AppImage' '*-x86_64.AppImage'
@@ -167,6 +168,11 @@ jobs:
             if [[ "$MACOS_SIGNED" != true ]]; then
               echo 'The macOS DMG is **not Developer ID signed or notarized**.'
             fi
+            echo
+            echo 'Release CI requires the complete Linux traditional and real OpenGL/Vulkan GUI suites, Windows OpenGL tests, and the Android phone journey. Full macOS, tvOS simulator, and Android TV native suites remain available manually but do not gate this release; their platform builds and package audits are retained.'
+            echo
+            echo 'The Apple TV IPA is **unsigned**: it has no Apple signing identity or provisioning profile, and tvOS will not install it as downloaded. It is not distributed through the App Store or TestFlight and has not been reviewed by Apple.'
+            echo "Build and sign from source with your own Apple Account, or use your own tvOS re-signing setup. See [Apple TV build and signing directions](https://github.com/$REPO/tree/$TAG#apple-tv)."
           } >release-notes.md
       - name: Publish GitHub prerelease
         env:
@@ -280,7 +286,7 @@ jobs:
           fi
           gh release download "$TAG" --repo "$GITHUB_REPOSITORY" \
             --pattern SHA256SUMS.txt --dir "$RUNNER_TEMP"
-          bundle="Spool-for-Jellyfin-$version-linux-x86_64.tar.zst"
+          bundle="Spool-$version-linux-x86_64.tar.zst"
           checksum="$(awk -v want="$bundle" \
             '{ sub(/^\*/, "", $2); if ($2 == want) print $1 }' \
             "$RUNNER_TEMP/SHA256SUMS.txt")"

.github/workflows/release.yml

@@ -24,11 +24,11 @@ jobs:
           mkdir sboms
           tag="$(gh release list --exclude-drafts --limit 1 --json tagName --jq '.[0].tagName')"
           test -n "$tag"
-          gh release download "$tag" --pattern '*.cdx.json' --dir sboms
-          test -n "$(find sboms -type f -name '*.cdx.json' -print -quit)"
+          gh release download "$tag" --pattern '*.syft.json' --pattern 'ffmpeg-vex.json' --dir sboms
+          test -n "$(find sboms -type f -name '*.syft.json' -print -quit)"
       - name: Enforce vulnerability policy
         run: |
           set -euo pipefail
-          for sbom in sboms/*.cdx.json; do
-            "$RUNNER_TEMP/release-tools/grype" "sbom:$sbom" --fail-on high --only-fixed
+          for sbom in sboms/*.syft.json; do
+            "$RUNNER_TEMP/release-tools/grype" "sbom:$sbom" --vex sboms/ffmpeg-vex.json --fail-on high --only-fixed
           done

.github/workflows/rescan-release-sboms.yml

@@ -0,0 +1,69 @@
+name: tvOS source build
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [feature/tvos]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tvos-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  simulator:
+    name: Qt mpv tvOS ${{ matrix.sdk }} build (simulator tests; device artifact audit only)
+    runs-on: macos-15
+    timeout-minutes: 180
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [appletvsimulator, appletvos]
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+        with:
+          submodules: recursive
+          persist-credentials: false
+      - name: Install native build tools
+        run: brew install cmake ninja meson pkg-config bash python imagemagick gpatch
+      - name: Install pinned macOS Qt host tools
+        run: |
+          python3 -m venv "$RUNNER_TEMP/aqt"
+          "$RUNNER_TEMP/aqt/bin/pip" install aqtinstall
+          version="$(python3 -c 'import json;print(json.load(open("tools/manifests/toolchain.json"))["qt"]["version"])')"
+          "$RUNNER_TEMP/aqt/bin/aqt" install-qt mac desktop "$version" clang_64 \
+            -O "$RUNNER_TEMP/Qt" -m qtshadertools qtwebsockets qtimageformats qttasktree
+          echo "QT_HOST_PATH=$RUNNER_TEMP/Qt/$version/macos" >> "$GITHUB_ENV"
+      - name: Build Qt and media libraries for Apple TV
+        env:
+          APPLE_SDK: ${{ matrix.sdk }}
+          APPLE_ARCH: arm64
+          JOBS: 3
+          BUILD_JOBS: 3
+        run: bash tools/build-tvos.sh
+      - uses: ./.github/actions/install-nix
+        if: matrix.sdk == 'appletvsimulator'
+        with:
+          nix_conf: |
+            experimental-features = nix-command flakes
+      - uses: cachix/cachix-action@3ba601ff5bbb07c7220846facfa2cd81eeee15a1
+        if: matrix.sdk == 'appletvsimulator'
+        with:
+          name: spool
+          skipPush: true
+      - name: Build same-binary host controller for the actual mobile app journey
+        if: matrix.sdk == 'appletvsimulator'
+        run: nix develop .#native -c env DEPLOY_APP=0 bash tools/build-macos.sh
+      - name: Run traditional then real GPU GUI tests in isolated Apple TV simulator
+        if: matrix.sdk == 'appletvsimulator'
+        run: bash tools/apple/smoke-tvos.sh build/tvos/appletvsimulator-arm64/install/Spool.app
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        if: always()
+        with:
+          name: internal-tvos-${{ matrix.sdk }}-arm64
+          path: |
+            build/tvos/${{ matrix.sdk }}-arm64/install
+            build/tvos/smoke/*.png
+            build/tvos/smoke/*.json

.github/workflows/tvos.yml

@@ -1,5 +1,6 @@
 /build/
 /build-linux-dev/
+/test-artifacts/
 /build-arm/
 /app/bin/
 /app/lib/

.gitignore

@@ -1,4 +1,4 @@
 [General]
-; QML files live at qml/ and qml/*/, so include both relative depths.
-buildDir=../build/linux-dev/app:../../build/linux-dev/app
+; QML files live at qml/, qml/*/ and qml/providers/*/, so include every relative depth.
+buildDir=../build/linux-dev/app:../../build/linux-dev/app:../../../build/linux-dev/app
 no-cmake-calls=true

.qmlls.ini

@@ -2,7 +2,7 @@
 
 ## Project
 
-- Spool for Jellyfin client for webOS and desktop.
+- Spool: a media player for webOS, desktop and Android.
 - Prefer a smaller, faster, easier-to-extend codebase over compatibility scaffolding or speculative abstractions.
 - The app is prerelease software: bump/reset caches on schema changes instead of adding migrations or fallback readers.
 - `mpv/` is a submodule. Commit mpv changes inside `mpv/`, then commit its pointer here.
@@ -29,18 +29,33 @@
 
 ## Module Seam
 
-The goal is one core that several backends can sit on (spool-jellyfin,
-spool-plex, spool-stremio). `CMakeLists.txt` groups sources into
-`SPOOL_PLATFORM_SOURCES`, `SPOOL_PLAYER_SOURCES`, `SPOOL_SHELL_SOURCES` and
-`SPOOL_JELLYFIN_SOURCES` to mark where that cut goes. They still build as one
-library; the grouping exists so the split stays mechanical.
+The app knows no media backend. Every source is a provider package (JS logic
+and QML screens) run by `src/provider/`; `docs/providers.md` describes the
+pieces and `sdk/` is the current format-3 provider contract. Jellyfin, Emby, Plex and
+Stremio live in their `spool-player/spool-*` repositories; Open Movies lives in
+`spool-player/spool-provider-example`. All five are bundled from digest-pinned
+archives in `providers/lock.json`. Providers and host cut over together; do not add
+compatibility shims for older provider/host builds.
 
-- Do not add a `src/api/` or `src/discovery/` include to the platform, player
-  or shell groups. Four such dependencies already exist and are the work a
-  split has to undo first: `PlayerController`, `PlaybackReporter`,
-  `PlayQueueController` and `SettingsController` each take a
-  `JellyfinApiFacade`, and `configurePlatformPlaybackCapabilities()` is
-  handed one.
+- Core is everything under `src/` except `src/providers/` (native providers;
+  only `LocalProvider` today) and `src/main.cpp`, the composition root. Core
+  never includes `src/providers/`; `tools/check-module-seam.sh` is the
+  `module-seam` ctest.
+- The app sees one `Provider`, `SourceHub`, which routes to every enabled
+  account. IDs leaving it are scoped (`<8 hex>:<id>`) and stay opaque to
+  routes, caches and QML. Pages reach media through `Catalog`,
+  `SearchSource`, `UserItemStateSink`, `ArtworkSource`, `PlaybackSource` and
+  `StreamQualityControl`, never a provider type.
+- Shared QML gates optional controls on the `ProviderCapabilities` singleton
+  (search, userItemState, playbackReporting, segments, groupPlayback,
+  remoteControl, streamQuality, trickplay): what the enabled accounts can do
+  between them. Provider-specific UI is the provider's own QML, mounted by
+  `shell/ProviderSurface` with a `ProviderUiContext`; item-menu entries come
+  from the manifest's `actions`.
+- Group playback and remote control are generic (`GroupPlaybackController`,
+  `AppControllerRemote.cpp`); providers translate their protocol into
+  `group` and `remote` events. Do not touch `src/player` or
+  `qml/pages/Player*` for provider work beyond renames.
 - `qml/primitives` and `qml/theme` reach exactly two singletons, `Art.url` and
   `Settings.uiScalePercent`. Keep it that way; page- and shell-level QML is
   where backend-shaped data belongs.
@@ -52,6 +67,12 @@ library; the grouping exists so the split stays mechanical.
 - `tools/manifests/toolchain.json` sets the Qt and FFmpeg versions for every
   platform. Nothing else may name one; `tools/toolchain-versions.sh --check`
   is what CI runs to keep the Qt module manifests honest.
+- Qt source manifests use the official-listed FAU archive mirror rather than a
+  geo-selected redirect. Mirror changes must preserve version/module SHA-256 pins;
+  verify the full archive digest before changing a source URL.
+- webOS GCC coroutine calls use named argument maps before `co_await`; nesting
+  a member expression inside a temporary argument aggregate triggered a compiler
+  internal error. Keep the wire arguments unchanged when restructuring such calls.
 - The launch screen carries the version, so it is rendered per build by
   `tools/generate-splash.sh` from `tools/manifests/splash.json` and is not
   committed. Configuring the app is enough to get it on every platform.
@@ -61,12 +82,30 @@ library; the grouping exists so the split stays mechanical.
 - Launch the native release app with `nix run`. Clean Git revisions substitute the immutable package from Cachix; dirty tracked changes use the incremental checkout build.
 - Launch the already-built native release app without rebuilding with `nix run .#run`. It fails with a build-command hint when the binary is missing.
 - Build without launching with `nix run .#build`.
-- Run the test suite the way CI does with `nix run .#tests` (release build, then the same ctest invocation and exclusions as the workflow).
+- Run the test suite the way CI does with `nix run .#tests` (release build, then `python tools/run-tests.py --build-dir <dir> --workers N`: traditional selectors finish before real GUI e2e; failures aggregate without GPU exclusions).
 - Leave interactive UI testing to the user. Do not drive their desktop with xdotool/xdgtool or similar input automation, or launch visible smoke tests unless explicitly requested. Use builds and isolated/offscreen checks for verification.
-- Use `nix develop .#native -c ...` for targeted development commands (e.g. `cmake --preset linux-dev`, then `cmake --build build/linux-dev/app --target jellyfin-native`).
+- Use `nix develop .#native -c ...` for targeted development commands (e.g. `cmake --preset linux-dev`, then `cmake --build build/linux-dev/app --target spool`).
 - The image-diagnostics equivalents remain `nix run .#image-debug-build` followed by `nix run .#image-debug`.
 - Batch coherent edits, then run one build and one `qmlformat`/`clang-format` invocation over all touched files; don't build or format file-by-file.
 
+### Filtered preview diagnostics
+
+- Trace is opt-in: `QT_LOGGING_RULES='spool.provider.trace.debug=true'`.
+  Enable it only for the shortest necessary inspection, then unset it.
+- Never print or share unfiltered app logs, diagnostics JSON, provider responses,
+  credential stores, URLs, request headers, or account configuration. Restoration
+  must use the real app's existing credential path, never pasted tokens.
+- Always filter trace output before displaying it: select only `preview metadata`,
+  `preview session`, `preview fetch failed`, and `preview load failed` messages
+  from `spool.provider.trace`. Prefer an explicit field allowlist (item ID,
+  enabled, availability, format, dimensions/count, numeric network/status codes,
+  frame/speculative). Redact authentication, URL/query, user/account and path
+  values even if upstream logging is already sanitized.
+- `spoolet` may inspect restored-account library rows and drive an explicitly
+  requested offscreen preview smoke. Filter JSON to the required titles, IDs,
+  player/preview state and dimensions. Never dump raw provider payloads or
+  support reports to discover preview availability.
+
 ## webOS
 
 - Do not build, install, launch, deploy, or test on a TV unless the user explicitly requests it. "Deploy" means install-only; never launch unless separately asked.