Big refactor: provider integration, E2E coverage, profiling and v0.9.1

.github/workflows/build-artifacts.yml

@@ -33,6 +33,11 @@ on:
         required: true
         default: false
         type: boolean
+      build_ios:
+        description: "Build unsigned iOS device IPA and smoke the simulator app"
+        required: true
+        default: true
+        type: boolean
       build_tvos:
         description: "Build unsigned Apple TV device IPA and simulator app"
         required: true
@@ -362,6 +367,29 @@ jobs:
           nix develop .#native -c python tools/run-tests.py \
             --build-dir build/linux-release/app --workers "$(nproc)"
 
+      # The GUI phase measures real cold/prepared controller setup on every
+      # run. Keep its history longer than the large transient test artifacts.
+      - name: Report player setup latency
+        if: ${{ always() }}
+        run: |
+          mkdir -p dist/player-setup-benchmark
+          if [[ -f build/linux-release/app/player-setup-benchmark.json ]]; then
+            cp build/linux-release/app/player-setup-benchmark.json dist/player-setup-benchmark/timings.json
+          fi
+          status=0
+          python3 tools/report-player-setup.py dist/player-setup-benchmark/timings.json \
+            --markdown dist/player-setup-benchmark/summary.md || status=$?
+          cat dist/player-setup-benchmark/summary.md >> "$GITHUB_STEP_SUMMARY"
+          exit "$status"
+
+      - name: Retain player setup history
+        if: ${{ always() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.0
+        with:
+          name: internal-player-setup-benchmark
+          path: dist/player-setup-benchmark
+          retention-days: 90
+
       - name: Retain internal native phase results after failures
         if: always()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.0
@@ -757,6 +785,14 @@ jobs:
             ~/Library/Caches/ccache
           key: ${{ steps.macos-build-cache.outputs.cache-primary-key }}
 
+  ios:
+    name: iOS
+    needs: [lint, toolchain]
+    if: ${{ github.event_name != 'workflow_dispatch' || inputs.build_ios }}
+    uses: ./.github/workflows/ios-review.yml
+    with:
+      release: ${{ inputs.release || false }}
+
   tvos:
     name: tvOS (${{ matrix.sdk }} arm64)
     runs-on: macos-15

.github/workflows/ios-review.yml

@@ -0,0 +1,110 @@
+name: iOS device IPA and simulator smoke
+on:
+  workflow_dispatch:
+    inputs:
+      release:
+        description: "Use release artifact retention; the device IPA remains unsigned"
+        type: boolean
+        default: false
+  workflow_call:
+    inputs:
+      release:
+        description: "Use release artifact retention; the device IPA remains unsigned"
+        type: boolean
+        default: false
+  push:
+    branches: [feature/ios]
+permissions:
+  contents: read
+jobs:
+  native:
+    name: iOS (${{ matrix.sdk }} ${{ matrix.arch }})
+    runs-on: macos-15-intel
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - sdk: iphonesimulator
+            arch: x86_64
+          - sdk: iphoneos
+            arch: arm64
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.0.2
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Validate immutable package version
+        shell: bash
+        run: |
+          source tools/lib/build-common.sh
+          version="$(read_project_version "$GITHUB_WORKSPACE")"
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            [[ "$GITHUB_REF_NAME" == "v$version" ]] || {
+              echo "error: release tag must match VERSION ($version)" >&2
+              exit 1
+            }
+          fi
+          echo "Building source $GITHUB_SHA with bundle/package version $version"
+      - name: Install native build tools
+        run: brew install cmake ninja meson pkg-config bash python imagemagick nasm gpatch
+      - name: Install pinned Qt host and iOS kits
+        shell: bash
+        run: |
+          python3 -m venv "$RUNNER_TEMP/aqt"
+          "$RUNNER_TEMP/aqt/bin/pip" install aqtinstall==3.3.0
+          qt_version="$(python3 -c 'import json; print(json.load(open("tools/manifests/toolchain.json"))["qt"]["version"])')"
+          "$RUNNER_TEMP/aqt/bin/aqt" install-qt mac desktop "$qt_version" clang_64 -O "$RUNNER_TEMP/Qt" -m qtshadertools qtwebsockets qtimageformats qttasktree
+          "$RUNNER_TEMP/aqt/bin/aqt" install-qt mac ios "$qt_version" ios -O "$RUNNER_TEMP/Qt" -m qtshadertools qtwebsockets qtimageformats qttasktree
+          echo "QT_HOST_PATH=$RUNNER_TEMP/Qt/$qt_version/macos" >> "$GITHUB_ENV"
+          echo "QT_TARGET_PREFIX=$RUNNER_TEMP/Qt/$qt_version/ios" >> "$GITHUB_ENV"
+      - name: Build native iOS application
+        shell: bash
+        env:
+          APPLE_SDK: ${{ matrix.sdk }}
+          APPLE_ARCH: ${{ matrix.arch }}
+          APPLE_CODE_SIGNING_ALLOWED: 'NO'
+          BUILD_JOBS: '4'
+        run: bash tools/build-ios.sh
+      - name: Smoke native startup on simulator
+        if: matrix.sdk == 'iphonesimulator'
+        shell: bash
+        run: |
+          device="$(xcrun simctl list devices available --json | python3 -c 'import json,sys; print(next(d["udid"] for ds in json.load(sys.stdin)["devices"].values() for d in ds if d["name"].startswith("iPhone")))')"
+          xcrun simctl boot "$device"
+          xcrun simctl bootstatus "$device" -b
+          bundle="build/apple/iphonesimulator-x86_64/app/Release-iphonesimulator/Spool.app"
+          xcrun simctl install "$device" "$bundle"
+          xcrun simctl launch --console "$device" com.sachk.spool --launch-test
+      - name: Package audited unsigned device IPA
+        if: matrix.sdk == 'iphoneos'
+        shell: bash
+        run: bash tools/package-ios.sh build/apple/iphoneos-arm64/app/Release-iphoneos/Spool.app dist/ios
+      - name: Upload only the unsigned device release package
+        if: matrix.sdk == 'iphoneos'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.0
+        with:
+          name: spool-ios-device-arm64
+          path: dist/ios/Spool-*-iOS-arm64.ipa
+          if-no-files-found: error
+          retention-days: ${{ inputs.release && 1 || 7 }}
+      - name: Archive simulator bundle preserving executable permissions
+        if: matrix.sdk == 'iphonesimulator'
+        shell: bash
+        run: |
+          tar -czf "$RUNNER_TEMP/ios-simulator-x86_64.tar.gz" \
+            -C build/apple/iphonesimulator-x86_64/app/Release-iphonesimulator Spool.app
+      - name: Keep simulator build internal
+        if: matrix.sdk == 'iphonesimulator'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.0
+        with:
+          name: internal-ios-simulator-x86_64
+          path: ${{ runner.temp }}/ios-simulator-x86_64.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+      - name: Document unsigned artifact boundary
+        if: matrix.sdk == 'iphoneos'
+        shell: bash
+        run: |
+          echo '### Unsigned iOS device IPA' >> "$GITHUB_STEP_SUMMARY"
+          echo 'The audited arm64 device bundle has matching VERSION metadata and a closed bundled Mach-O dependency graph. It is unsigned and unprovisioned: re-sign with your own Apple identity and provisioning profile before installation. Device playback, App Store approval and TestFlight distribution are not verified by this build.' >> "$GITHUB_STEP_SUMMARY"

.github/workflows/release.yml

@@ -138,6 +138,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 'iPhone and iPad — unsigned (re-sign required)' '*-iOS-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'
@@ -169,10 +170,14 @@ jobs:
               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 'Release CI requires the complete Linux traditional and real OpenGL/Vulkan GUI suites, ASan/UBSan package consumers, and all platform builds and package audits. Windows, Android phone/TV, macOS native, and tvOS simulator runtime suites remain available manually but do not gate this release. Successful packages do not certify physical-device playback.'
             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)."
+            if compgen -G 'release-assets/*-iOS-arm64.ipa' >/dev/null; then
+              echo
+              echo 'The iPhone/iPad IPA is also **unsigned** and requires your own Apple signing identity and provisioning profile before installation. It is not distributed through the App Store or TestFlight; simulator startup does not certify device playback.'
+            fi
           } >release-notes.md
       - name: Publish GitHub prerelease
         env:

AGENTS.md

@@ -110,7 +110,7 @@ compatibility shims for older provider/host builds.
 
 - 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.
 - For a requested deployment, use this exact build-and-install command from the repository root:
-  `TV_HOST=root@tv.local; ./build-ipk.sh && nix develop -c bash tools/webos/verify-device.sh --no-launch --host "$TV_HOST" ./build/com.sachk.spool_0.3.0_arm.ipk`
+  `TV_HOST=root@tv.local; ./build-ipk.sh && nix develop -c bash tools/webos/verify-device.sh --no-launch --host "$TV_HOST" "./build/com.sachk.spool_$(cat VERSION)_arm.ipk"`
   `build-ipk.sh` defaults to the complete fresh `all` pipeline. Never invoke the `app`, `stage`, or `package` phases separately.
 - The packaged IPK is the only supported way to update the TV app. Never copy binaries or libraries to the TV manually, mutate the installed application tree, or substitute hand-written CMake/staging/install steps.
 - If webOS diagnosis is requested, read current logs first and make one targeted change — no speculative deploy loops.

CMakeLists.txt

@@ -9,7 +9,7 @@ endif()
 project(SpoolWebOS VERSION "${SPOOL_VERSION}" LANGUAGES C CXX)
 
 set(SPOOL_APPLE_MOBILE OFF)
-if(CMAKE_SYSTEM_NAME STREQUAL "tvOS")
+if(IOS OR CMAKE_SYSTEM_NAME STREQUAL "tvOS")
     set(SPOOL_APPLE_MOBILE ON)
 endif()
 
@@ -23,6 +23,9 @@ if(CMAKE_CROSSCOMPILING AND NOT ANDROID AND NOT SPOOL_APPLE_MOBILE)
 endif()
 option(SPOOL_WEBOS "Build the webOS Starfish/native-surface client" ${SPOOL_WEBOS_DEFAULT})
 option(TOUCHSCREEN "Enable mobile touchscreen interactions (runtime-disabled on TVs)" ${ANDROID})
+if(IOS)
+    set(TOUCHSCREEN ON)
+endif()
 option(SPOOL_DEV_BUILD "Favor faster local development builds over smallest release artifacts" OFF)
 option(SPOOL_DIAGNOSTICS "Build debug lifecycle/process/watchdog diagnostics" OFF)
 option(SPOOL_DIAGNOSTICS_STACKDUMP "Allow diagnostics to request gdb stack dumps" OFF)
@@ -264,6 +267,7 @@ set(SPOOL_SHELL_SOURCES
     src/app/LibraryQuery.h
     src/app/MemoryBudget.cpp
     src/app/MemoryBudget.h
+    src/app/PlaybackStopPolicy.h
     src/app/RouterController.cpp
     src/app/RouterController.h
     src/app/SettingsController.cpp
@@ -564,6 +568,7 @@ qt_add_qml_module(spool
         qml/browse/ListBrowseView.qml
         qml/browse/RowStackView.qml
         qml/pages/HomePage.qml
+        qml/pages/HomeProviderPicker.qml
         qml/pages/ItemDetailsPage.qml
         qml/pages/CollectionEditorPage.qml
         qml/pages/LocalFolders.qml
@@ -633,6 +638,7 @@ qt_add_qml_module(spool
         qml/primitives/SettingRow.qml
         qml/primitives/SliderRow.qml
         qml/primitives/Surface.qml
+        qml/primitives/SwitchIndicator.qml
         qml/primitives/TechMetadataLine.qml
         qml/primitives/TechnicalDetailsBar.qml
         qml/primitives/TextFieldRow.qml
@@ -1115,6 +1121,8 @@ if(BUILD_TESTING AND NOT SPOOL_WEBOS)
                 "${CMAKE_CURRENT_SOURCE_DIR}/tests/tools/PackageAuditTest.py"
                 "${CMAKE_CURRENT_SOURCE_DIR}/tools/package-audit.py"
         )
+        add_test(NAME webos-tooling
+            COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tests/tools/WebosToolingTest.py")
     endif()
     add_test(NAME module-seam
         COMMAND bash "${CMAKE_CURRENT_SOURCE_DIR}/tools/check-module-seam.sh"
@@ -1131,14 +1139,18 @@ if(BUILD_TESTING AND NOT SPOOL_WEBOS)
             "${CMAKE_CURRENT_SOURCE_DIR}/tests/tools/RenderBenchmarkReportTest.py"
             "${CMAKE_CURRENT_SOURCE_DIR}/tools/compare-render-benchmark.py"
     )
+    add_test(NAME player-setup-report
+        COMMAND "${Python3_EXECUTABLE}"
+            "${CMAKE_CURRENT_SOURCE_DIR}/tests/tools/PlayerSetupReportTest.py"
+            "${CMAKE_CURRENT_SOURCE_DIR}/tools/report-player-setup.py")
     add_test(NAME test-driver-ordering
         COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tests/tools/TestDriverTest.py")
 
     # URL-only native playlists require real video-surface admission; the
     # desktop controller consumer therefore belongs to the serial GPU phase.
     set(SPOOL_E2E_SOURCES tests/TestRunner.cpp tests/QmlTestRunner.cpp tests/ExtensionIntegration.h
         tests/ArtworkIntegration.h tests/player/MpvVideoItemTest.cpp tests/player/MpvFullscreenTest.cpp
-        tests/player/PlayerControllerTest.cpp
+        tests/player/PlayerControllerTest.cpp tests/player/PlayerSetupBenchmark.cpp
         tests/e2e/AppJourneyTest.cpp tests/e2e/JellyfinFixture.cpp)
     if(APPLE AND NOT SPOOL_APPLE_MOBILE)
         set_source_files_properties(tests/player/MpvFullscreenTest.cpp PROPERTIES LANGUAGE OBJCXX)
@@ -1149,7 +1161,7 @@ if(BUILD_TESTING AND NOT SPOOL_WEBOS)
     file(GENERATE OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/native-spoolet-path.txt"
         CONTENT "$<TARGET_FILE:spoolet>\n")
     target_include_directories(spool-e2e-tests PRIVATE tests src "${CMAKE_CURRENT_BINARY_DIR}/generated")
-    target_compile_definitions(spool-e2e-tests PRIVATE TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}"
+    target_compile_definitions(spool-e2e-tests PRIVATE SPOOL_E2E_BINARY=1 TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}"
         SPOOL_E2E_APP="$<TARGET_FILE:spool>" SPOOL_E2E_SPOOLET="$<TARGET_FILE:spoolet>")
     if(SPOOL_TEST_RENDER_BACKEND STREQUAL "opengl")
         target_compile_definitions(spool-e2e-tests PRIVATE SPOOL_TEST_OPENGL_ONLY=1)
@@ -1169,6 +1181,7 @@ if(BUILD_TESTING AND NOT SPOOL_WEBOS)
         VERBATIM)
         set(SPOOL_QML_TESTS
             route-policy tests/qml/tst_RoutePolicy.qml
+            row-stack-view tests/qml/tst_RowStackView.qml
             key-router tests/qml/tst_KeyRouter.qml
             player-overlay-input tests/qml/tst_PlayerOverlayInput.qml
             popup-menu-input tests/qml/tst_PopupMenuInput.qml
@@ -1253,16 +1266,61 @@ if(BUILD_TESTING AND NOT SPOOL_WEBOS)
         endforeach()
         file(APPEND "${qml_registry}" "}\n")
         target_sources(spool-e2e-tests PRIVATE "${qml_registry}")
-        add_test(NAME gui-e2e-native COMMAND spool-e2e-tests --run-all --workers 1 --timeout-ms 600000 --results "${CMAKE_CURRENT_BINARY_DIR}/e2e-results.json")
+        # On a Linux host the GUI selectors always get the private Weston/Xvfb
+        # session, so a bare `ctest` cannot open windows on the developer's
+        # desktop (or be disturbed by them using it).
+        if(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND NOT ANDROID)
+            set(SPOOL_E2E_SESSION bash "${CMAKE_CURRENT_SOURCE_DIR}/tools/test-gpu-session.sh")
+        else()
+            set(SPOOL_E2E_SESSION "")
+        endif()
+        add_test(NAME gui-e2e-native COMMAND ${SPOOL_E2E_SESSION} $<TARGET_FILE:spool-e2e-tests> --run-all --workers 1 --timeout-ms 600000 --results "${CMAKE_CURRENT_BINARY_DIR}/e2e-results.json")
         set_tests_properties(gui-e2e-native PROPERTIES LABELS e2e ENVIRONMENT "${SPOOL_TEST_ENV}" TIMEOUT 0)
+        add_test(NAME player-setup-performance
+            COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tools/report-player-setup.py"
+                "${CMAKE_CURRENT_BINARY_DIR}/player-setup-benchmark.json")
+        set_tests_properties(player-setup-performance PROPERTIES LABELS e2e DEPENDS gui-e2e-native)
+        # Exercise the event-thread lifecycle with a controllable client API.
+        # Keep this separate from the core targets so the fake symbols cannot
+        # interpose on the real libmpv used by the other player tests.
+        find_package(Threads REQUIRED)
+        add_executable(mpv-lifecycle-tests
+            tests/player/MpvLifecycleTest.cpp
+            src/player/MpvLifecycle.cpp)
+        target_include_directories(mpv-lifecycle-tests PRIVATE
+            "${CMAKE_CURRENT_SOURCE_DIR}/src"
+            "${MPV_ACTIVE_SOURCE_DIR}"
+            "${MPV_ACTIVE_SOURCE_DIR}/include")
+        # Native builds normally obtain installed headers from the libmpv
+        # target. Import those paths without linking its real client symbols.
+        foreach(mpv_headers_target IN ITEMS PkgConfig::MPV MPV::MPV)
+            if(TARGET ${mpv_headers_target})
+                target_include_directories(mpv-lifecycle-tests SYSTEM PRIVATE
+                    "$<TARGET_PROPERTY:${mpv_headers_target},INTERFACE_INCLUDE_DIRECTORIES>")
+            endif()
+        endforeach()
+        target_link_libraries(mpv-lifecycle-tests PRIVATE Qt6::Core Threads::Threads)
+        set_target_properties(mpv-lifecycle-tests PROPERTIES
+            AUTOMOC OFF
+            AUTOUIC OFF
+            AUTORCC OFF)
+        add_test(NAME mpv-lifecycle COMMAND mpv-lifecycle-tests)
+        set_tests_properties(mpv-lifecycle PROPERTIES LABELS e2e ENVIRONMENT "${SPOOL_TEST_ENV}" TIMEOUT 0)
         foreach(test_target IN ITEMS spool-tests spool-e2e-tests)
             set_target_properties(${test_target} PROPERTIES INTERPROCEDURAL_OPTIMIZATION OFF
                 INTERPROCEDURAL_OPTIMIZATION_RELEASE OFF INTERPROCEDURAL_OPTIMIZATION_MINSIZEREL OFF)
         endforeach()
         set_tests_properties(provider-sdk-tool local-provider-overrides ffmpeg-capability-generator module-seam
-            network-shaper render-benchmark-report test-driver-ordering PROPERTIES LABELS traditional)
+            network-shaper render-benchmark-report player-setup-report test-driver-ordering PROPERTIES LABELS traditional)
         if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
-            set_tests_properties(package-audit PROPERTIES LABELS traditional)
+            set_tests_properties(package-audit webos-tooling PROPERTIES LABELS traditional)
+            # Exercise the actual curl scheduler/counters, not just its exposed
+            # option values. Meson tests are disabled in packaged native builds.
+            find_library(SPOOL_CURL_TEST_MPV NAMES mpv HINTS ${MPV_LIBRARY_DIRS} REQUIRED)
+            add_test(NAME curl-transport
+                COMMAND "${Python3_EXECUTABLE}" "${MPV_ACTIVE_SOURCE_DIR}/test/curl_transport.py"
+                    --libmpv "${SPOOL_CURL_TEST_MPV}" -v)
+            set_tests_properties(curl-transport PROPERTIES LABELS traditional TIMEOUT 180)
         endif()
     endif()
     if(SPOOL_SANITIZERS AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")