ci: cache embedded mpv runtime

.github/workflows/build-and-make.yaml

@@ -88,10 +88,64 @@ jobs:
             - name: Build frontend
               run: pnpm nx build web --skip-nx-cache
 
+            - name: Resolve embedded MPV runtime cache key
+              # TEMPORARY ARTIFACT TEST: remove `|| github.event_name == 'pull_request' || github.ref == 'refs/heads/master'`
+              # after the macOS Embedded MPV artifacts are built and manually tested.
+              if: matrix.os == 'macos' && !startsWith(github.ref, 'refs/tags/v') && (github.event_name == 'pull_request' || github.ref == 'refs/heads/master')
+              id: embedded-mpv-runtime-cache-key
+              shell: bash
+              run: |
+                  set -euo pipefail
+
+                  deployment_target="${MACOSX_DEPLOYMENT_TARGET:-11.0}"
+                  safe_deployment_target="$(printf '%s' "${deployment_target}" | tr -c 'A-Za-z0-9_.-' '-')"
+                  xcode_version="$(xcodebuild -version | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
+                  xcode_hash="$(printf '%s' "${xcode_version}" | shasum -a 256 | awk '{print $1}')"
+                  source_hash="$(
+                      shasum -a 256 \
+                          tools/embedded-mpv/build-macos-runtime.mjs \
+                          tools/embedded-mpv/stage-macos-runtime.mjs |
+                          shasum -a 256 |
+                          awk '{print $1}'
+                  )"
+                  cache_key="embedded-mpv-runtime-v1-${RUNNER_OS}-${{ matrix.arch }}-macos${safe_deployment_target}-xcode${xcode_hash}-${source_hash}"
+
+                  echo "deployment-target=${deployment_target}" >> "${GITHUB_OUTPUT}"
+                  echo "xcode-version=${xcode_version}" >> "${GITHUB_OUTPUT}"
+                  echo "key=${cache_key}" >> "${GITHUB_OUTPUT}"
+                  echo "Embedded MPV runtime cache key: ${cache_key}"
+                  echo "Xcode version: ${xcode_version}"
+
+            - name: Restore embedded MPV runtime cache
+              # TEMPORARY ARTIFACT TEST: remove `|| github.event_name == 'pull_request' || github.ref == 'refs/heads/master'`
+              # after the macOS Embedded MPV artifacts are built and manually tested.
+              if: matrix.os == 'macos' && !startsWith(github.ref, 'refs/tags/v') && (github.event_name == 'pull_request' || github.ref == 'refs/heads/master')
+              id: embedded-mpv-runtime-cache
+              uses: actions/cache/restore@v4
+              with:
+                  path: |
+                      vendor/embedded-mpv/darwin-${{ matrix.arch }}/include
+                      vendor/embedded-mpv/darwin-${{ matrix.arch }}/lib
+                      vendor/embedded-mpv/darwin-${{ matrix.arch }}/runtime-manifest.json
+                  key: ${{ steps.embedded-mpv-runtime-cache-key.outputs.key }}
+
+            - name: Clear non-exact embedded MPV runtime cache restore
+              # TEMPORARY ARTIFACT TEST: remove `|| github.event_name == 'pull_request' || github.ref == 'refs/heads/master'`
+              # after the macOS Embedded MPV artifacts are built and manually tested.
+              if: matrix.os == 'macos' && !startsWith(github.ref, 'refs/tags/v') && (github.event_name == 'pull_request' || github.ref == 'refs/heads/master') && steps.embedded-mpv-runtime-cache.outputs.cache-hit != 'true'
+              shell: bash
+              run: |
+                  set -euo pipefail
+
+                  rm -rf \
+                      "vendor/embedded-mpv/darwin-${{ matrix.arch }}/include" \
+                      "vendor/embedded-mpv/darwin-${{ matrix.arch }}/lib" \
+                      "vendor/embedded-mpv/darwin-${{ matrix.arch }}/runtime-manifest.json"
+
             - name: Build embedded MPV runtime (macOS release)
               # TEMPORARY ARTIFACT TEST: remove `|| github.event_name == 'pull_request' || github.ref == 'refs/heads/master'`
               # after the macOS Embedded MPV artifacts are built and manually tested.
-              if: matrix.os == 'macos' && (startsWith(github.ref, 'refs/tags/v') || github.event_name == 'pull_request' || github.ref == 'refs/heads/master')
+              if: matrix.os == 'macos' && (startsWith(github.ref, 'refs/tags/v') || github.event_name == 'pull_request' || github.ref == 'refs/heads/master') && steps.embedded-mpv-runtime-cache.outputs.cache-hit != 'true'
               shell: bash
               run: |
                   set -euo pipefail
@@ -322,6 +376,18 @@ jobs:
                   IPTVNATOR_REQUIRE_EMBEDDED_MPV: ${{ matrix.os == 'macos' && (startsWith(github.ref, 'refs/tags/v') || github.event_name == 'pull_request' || github.ref == 'refs/heads/master') && '1' || '0' }}
               run: pnpm run verify:package-layout -- "$PACKAGE_OS" "$PACKAGE_ARCH"
 
+            - name: Save embedded MPV runtime cache
+              # TEMPORARY ARTIFACT TEST: remove `|| github.ref == 'refs/heads/master'`
+              # after the macOS Embedded MPV artifacts are built and manually tested.
+              if: matrix.os == 'macos' && !startsWith(github.ref, 'refs/tags/v') && github.repository == '4gray/iptvnator' && github.event_name != 'pull_request' && github.ref == 'refs/heads/master' && steps.embedded-mpv-runtime-cache.outputs.cache-hit != 'true'
+              uses: actions/cache/save@v4
+              with:
+                  path: |
+                      vendor/embedded-mpv/darwin-${{ matrix.arch }}/include
+                      vendor/embedded-mpv/darwin-${{ matrix.arch }}/lib
+                      vendor/embedded-mpv/darwin-${{ matrix.arch }}/runtime-manifest.json
+                  key: ${{ steps.embedded-mpv-runtime-cache-key.outputs.key }}
+
             - name: Smoke test packaged Flatpak launcher
               if: matrix.os == 'linux' && matrix.linux_profile == 'flatpak'
               shell: bash

docs/architecture/embedded-mpv-native.md

@@ -192,6 +192,8 @@ pnpm embedded-mpv:build-runtime -- arm64 /tmp/embedded-mpv-prefix
 pnpm embedded-mpv:stage-runtime -- arm64 /tmp/embedded-mpv-prefix
 ```
 
+During temporary PR and `master` artifact testing, CI can restore an exact-keyed GitHub Actions cache for the staged `vendor/embedded-mpv/darwin-<arch>/` runtime and skip the expensive source build. The cache only contains `include/`, `lib/`, and `runtime-manifest.json`; it never contains the compiled `embedded_mpv.node` addon because that target depends on Electron headers, ABI, architecture, and build environment. Runtime cache entries are saved only from trusted repository refs, and tagged public release builds continue to rebuild from pinned sources until a dedicated signed and attested runtime artifact flow exists.
+
 The CI builder pins FFmpeg `8.1`, mpv `0.41.0`, libplacebo `7.360.1`, libass `0.17.3`, FreeType `2.13.3`, FriBidi `1.0.16`, and HarfBuzz `8.5.0`. FFmpeg disables autodetected external libraries so Homebrew libraries cannot silently enter the runtime. Libplacebo is checked out from git with the submodules required by its Meson build because the generated GitHub archive does not include submodule contents. Even with Vulkan disabled, libplacebo still compiles Vulkan stubs and needs `3rdparty/Vulkan-Headers`. The generated manifest records source URLs, archive SHA-256 values where applicable, libplacebo git commit/submodule metadata, FFmpeg configure flags, and mpv Meson flags. The staging step normalizes that manifest to `origin: vendored-lgpl`, which release package validation requires.
 
 The Electron backend build consumes the staged runtime, copies Mach-O runtime files into the native build output, and rewrites Mach-O paths so `embedded_mpv.node` loads `@loader_path/lib/libmpv.2.dylib` instead of a machine-local Homebrew path. After `install_name_tool` rewrites any addon or runtime binary, the build re-signs that binary with an ad-hoc signature for local development. Release packaging still performs the normal app signing and notarization later.

tools/embedded-mpv/README.md

@@ -57,6 +57,8 @@ pnpm embedded-mpv:build-runtime -- arm64 /tmp/embedded-mpv-prefix
 pnpm embedded-mpv:stage-runtime -- arm64 /tmp/embedded-mpv-prefix
 ```
 
+During temporary PR and `master` artifact testing, CI restores an exact-keyed GitHub Actions cache for the staged `vendor/embedded-mpv/darwin-<arch>/` runtime before falling back to the source build. The cache key includes the target architecture, macOS deployment target, Xcode version, and hashes of the runtime build/staging scripts. Cache entries are saved only from trusted repository refs and are treated strictly as a speed optimization; tagged release builds continue to rebuild from pinned sources unless a future signed and attested runtime artifact flow is introduced.
+
 The builder currently pins:
 
 - FFmpeg `8.1`, configured without `--enable-gpl` or `--enable-nonfree`, and with autodetected external libraries disabled