feat(compositor): CPU backend — WARP render + software decode, surfaced to the user

.claude/launch.json

@@ -0,0 +1,31 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "vite-dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev", "--", "--port", "5199", "--strictPort"],
+      "port": 5199,
+      "env": { "NO_ELECTRON": "1" }
+    },
+    {
+      "name": "desktop-dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev", "--", "--port", "5201", "--strictPort"],
+      "port": 5201,
+      "env": { "NO_ELECTRON": "1" }
+    },
+    {
+      "name": "v4preview",
+      "runtimeExecutable": "node",
+      "runtimeArgs": ["node_modules/vite/bin/vite.js", "--config", "vite.v4preview.config.ts"],
+      "port": 5207
+    },
+    {
+      "name": "docs",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "website", "run", "serve", "--", "--port", "3111"],
+      "port": 3111
+    }
+  ]
+}

.github/workflows/build-whisper-stt.yml

@@ -0,0 +1,202 @@
+name: Build whisper-stt binaries
+
+# Builds the whisper.cpp-based `whisper-stt-server` helper for each desktop
+# platform and uploads the binary + ggml backend sidecars as GitHub artifacts
+# so `build.yml` can bundle them into installers.
+#
+# Triggered:
+#   * manually via workflow_dispatch (release-blocking binary refresh)
+#   * automatically when the helper, build script, or this workflow changes
+#
+# ponytail: one binary per platform is enough because whisper.cpp selects the
+# right backend at runtime (Metal on Apple Silicon, Vulkan on Windows/Linux,
+# CPU fallback when no GPU/driver is available). A CUDA variant is supported
+# by the build script but is not built by default; Vulkan already accelerates
+# NVIDIA cards.
+
+on:
+  workflow_dispatch:
+    inputs:
+      enable_cuda:
+        description: "Also build a CUDA variant when the host has an nvcc toolchain"
+        required: false
+        default: "false"
+        type: choice
+        options:
+          - "true"
+          - "false"
+  push:
+    paths:
+      - "scripts/build-whisper-stt.sh"
+      - "electron/native/whisper-stt/**"
+      - ".github/workflows/build-whisper-stt.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: ${{ matrix.label }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-latest
+            arch: arm64
+            # Matches `os_arch_tag()` in scripts/build-whisper-stt.sh — this is
+            # the directory name the build script actually stages into
+            # (electron/native/bin/<tag>/), NOT `${{ matrix.os }}-${{ matrix.arch }}`.
+            tag: darwin-arm64
+            label: macOS arm64 (Metal)
+            vulkan: false
+          - os: macos-15-intel
+            arch: x64
+            tag: darwin-x64
+            label: macOS x64 (CPU)
+            vulkan: false
+          - os: ubuntu-latest
+            arch: x64
+            tag: linux-x64
+            label: Linux x64 (Vulkan + CPU fallback)
+            vulkan: true
+          - os: windows-latest
+            arch: x64
+            tag: win32-x64
+            label: Windows x64 (Vulkan + CPU fallback)
+            vulkan: true
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: ./.github/actions/setup
+
+      - name: Install Ninja (Linux)
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ninja-build build-essential
+
+      - name: Install Ninja (macOS)
+        if: startsWith(matrix.os, 'macos')
+        run: brew install ninja
+
+      - name: Setup MSVC (Windows)
+        if: matrix.os == 'windows-latest'
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: x64
+
+      - name: Install Vulkan SDK
+        if: matrix.vulkan
+        # ponytail: humbletim/setup-vulkan-sdk builds Glslang from source via
+        # CMake ExternalProject, which fails ("ENABLE_OPT set but SPIR-V
+        # tools not found") because Glslang's build needs a sibling
+        # SPIRV-Tools checkout it doesn't fetch on its own — reproduced on
+        # both the Linux and Windows legs. jakoch/install-vulkan-sdk-action
+        # downloads LunarG's official prebuilt SDK (glslc included, no
+        # compilation), which is both more reliable and much faster.
+        uses: jakoch/install-vulkan-sdk-action@v1
+        with:
+          vulkan_version: 1.4.304.1
+          install_runtime: false
+          cache: true
+
+      - name: Put glslc on PATH
+        if: matrix.vulkan
+        shell: bash
+        # Belt-and-braces: the action exports VULKAN_SDK but its own PATH
+        # handling isn't documented in enough detail to rely on for a tool
+        # (glslc) the ggml Vulkan backend's CMake configure step needs to find.
+        run: |
+          set -euo pipefail
+          for cand in "${VULKAN_SDK}/Bin" "${VULKAN_SDK}/bin"; do
+            if [[ -d "${cand}" ]]; then
+              echo "${cand}" >> "$GITHUB_PATH"
+            fi
+          done
+
+      - name: Install SPIRV-Headers (Windows only)
+        if: matrix.os == 'windows-latest'
+        shell: bash
+        # ponytail: ggml-vulkan's CMakeLists does
+        # `find_package(SPIRV-Headers CONFIG REQUIRED)`. The Linux LunarG SDK
+        # tarball bundles that CMake config alongside the SDK, so the Linux
+        # leg resolves it for free; the Windows installer .exe (as fetched by
+        # jakoch/install-vulkan-sdk-action) does not ship it at all, so
+        # find_package fails with "Could not find a package configuration
+        # file". vcpkg (preinstalled on GitHub's windows-latest image) ships
+        # a spirv-headers port that provides the missing config; point
+        # CMAKE_PREFIX_PATH at its install dir so ggml's own
+        # `if (DEFINED ENV{VULKAN_SDK}) list(APPEND CMAKE_PREFIX_PATH ...)`
+        # logic has a second, working prefix to fall back to.
+        run: |
+          set -euo pipefail
+          VCPKG_ROOT_DIR="$(dirname "$(command -v vcpkg)")"
+          "${VCPKG_ROOT_DIR}/vcpkg" install spirv-headers:x64-windows
+          echo "CMAKE_PREFIX_PATH=${VCPKG_ROOT_DIR}/installed/x64-windows" >> "$GITHUB_ENV"
+
+      - name: Cache whisper.cpp build tree
+        uses: actions/cache@v4
+        with:
+          # Matches scripts/build-whisper-stt.sh's own BUILD_ROOT default for
+          # each OS (short `C:/wstbuild` on Windows to dodge the vulkan-shaders-gen
+          # MAX_PATH issue; `.cache/whisper-stt-build` elsewhere) — cache the
+          # FetchContent checkout + object files directly, no env override needed.
+          path: ${{ runner.os == 'Windows' && 'C:/wstbuild' || '.cache/whisper-stt-build' }}
+          # Keyed on the pinned WHISPER_REF/backend flags in CMakeLists.txt so a
+          # bump there invalidates the cache instead of silently reusing a stale
+          # FetchContent checkout; falls back to the newest cache for the same
+          # platform + runner image on a miss so incremental compilation still
+          # helps. The runner image version ($ImageOS/$ImageVersion) is part of
+          # the key AND the restore-keys prefix because CMake bakes absolute
+          # toolchain paths (e.g. the Xcode SDK's libz.tbd) into the cached build
+          # tree — when GitHub rolls the image's Xcode/SDK, those paths vanish and
+          # a restored tree fails with "No rule to make target …libz.tbd". Scoping
+          # the cache to the image version auto-busts it on every toolchain roll.
+          key: whisper-stt-build-${{ matrix.tag }}-${{ env.ImageOS }}-${{ env.ImageVersion }}-${{ hashFiles('electron/native/whisper-stt/CMakeLists.txt') }}
+          restore-keys: |
+            whisper-stt-build-${{ matrix.tag }}-${{ env.ImageOS }}-${{ env.ImageVersion }}-
+
+      - name: Run whisper-stt build script
+        env:
+          ENABLE_CUDA: ${{ github.event.inputs.enable_cuda || 'false' }}
+        run: bash scripts/build-whisper-stt.sh
+
+      - name: Stage binaries for upload
+        shell: bash
+        run: |
+          set -euo pipefail
+          BAG="whisper-stt-${{ matrix.tag }}"
+          mkdir -p "$BAG"
+          # Copy the whole per-platform directory: the helper executable plus
+          # every ggml backend sidecar/library it needs at runtime.
+          cp -v "electron/native/bin/${{ matrix.tag }}"/* "$BAG/"
+          tar -czf "${BAG}.tar.gz" "$BAG"
+          echo "Staged ${BAG}.tar.gz"
+
+      - name: Upload binaries
+        uses: actions/upload-artifact@v4
+        with:
+          name: whisper-stt-${{ matrix.tag }}
+          path: whisper-stt-${{ matrix.tag }}.tar.gz
+          if-no-files-found: error
+          # build.yml now stages these into the installers
+          # (scripts/stage-whisper-stt.sh), so an expired artifact fails a
+          # release build. 90 days instead of 30 to make that rarer.
+          retention-days: 90
+
+      - name: Workflow summary
+        if: always()
+        # Explicit shell: the bash `{ ... } >> file` grouping syntax below is
+        # not valid PowerShell, which is the default `run:` shell on Windows
+        # runners — this step silently failed on Windows without this.
+        shell: bash
+        run: |
+          {
+            echo "## whisper-stt build"
+            echo ""
+            echo "- Matrix: \`${{ matrix.label }}\`"
+            echo "- Result: ${{ job.status }}"
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/build.yml

@@ -38,11 +38,16 @@ jobs:
       - name: Setup Node.js
         uses: ./.github/actions/setup
 
-      - name: Cache caption assets
-        uses: actions/cache@v4
-        with:
-          path: caption-assets
-          key: caption-assets-${{ runner.os }}-${{ hashFiles('scripts/fetch-caption-model.mjs') }}
+      # STT is the bundled whisper-stt-server (whisper.cpp with native DTW token
+      # timestamps); no VAD model is fetched here. The binary is built by
+      # build-whisper-stt.yml and staged below — without that step the installer
+      # ships without speech-to-text. See
+      # technical-documentation/architecture/transcription-and-captions.md.
+      - name: Stage whisper-stt binaries
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: bash scripts/stage-whisper-stt.sh win32-x64
 
       - name: Build Windows app
         run: npm run build:win -- --publish never
@@ -65,11 +70,11 @@ jobs:
       - name: Setup Node.js
         uses: ./.github/actions/setup
 
-      - name: Cache caption assets
-        uses: actions/cache@v4
-        with:
-          path: caption-assets
-          key: caption-assets-${{ runner.os }}-${{ hashFiles('scripts/fetch-caption-model.mjs') }}
+      - name: Stage whisper-stt binaries
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: bash scripts/stage-whisper-stt.sh win32-x64
 
       - name: Build Windows Store package
         run: npm run build:win:store -- --publish never
@@ -84,6 +89,9 @@ jobs:
 
   build-macos:
     name: macOS ${{ matrix.arch }} DMG
+    # RELEASE-BRANCH-ONLY: 1.8.0 ships Windows-only. Do NOT let this `if: false`
+    # reach main when promoting, or every later release becomes Windows-only too.
+    if: false
     runs-on: macos-latest
     strategy:
       fail-fast: false
@@ -106,11 +114,11 @@ jobs:
         env:
           npm_config_build_from_source: "false"
 
-      - name: Cache caption assets
-        uses: actions/cache@v4
-        with:
-          path: caption-assets
-          key: caption-assets-${{ runner.os }}-${{ hashFiles('scripts/fetch-caption-model.mjs') }}
+      - name: Stage whisper-stt binaries
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: bash scripts/stage-whisper-stt.sh darwin-${{ matrix.arch }}
 
       - name: Resolve macOS signing
         id: signing
@@ -258,6 +266,8 @@ jobs:
 
   build-linux:
     name: Linux packages
+    # RELEASE-BRANCH-ONLY: see the note on build-macos above.
+    if: false
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
@@ -269,11 +279,11 @@ jobs:
       - name: Install pacman build dependencies
         run: sudo apt-get update && sudo apt-get install -y libarchive-tools
 
-      - name: Cache caption assets
-        uses: actions/cache@v4
-        with:
-          path: caption-assets
-          key: caption-assets-${{ runner.os }}-${{ hashFiles('scripts/fetch-caption-model.mjs') }}
+      - name: Stage whisper-stt binaries
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: bash scripts/stage-whisper-stt.sh linux-x64
 
       - name: Build Linux app
         run: npm run build:linux -- --publish never
@@ -293,10 +303,11 @@ jobs:
   publish-release:
     name: Publish GitHub release
     runs-on: ubuntu-latest
+    # RELEASE-BRANCH-ONLY: build-macos / build-linux are disabled for this
+    # Windows-only release. A skipped job in `needs` skips this one too, so they
+    # must come out of the list, not just be gated. Restore all three on main.
     needs:
       - build-windows
-      - build-macos
-      - build-linux
     if: ${{ (github.event_name == 'push' && github.ref_type == 'tag') || (github.event_name == 'workflow_dispatch' && github.event.inputs.release_tag != '') }}
     steps:
       - name: Checkout code
@@ -378,6 +389,9 @@ jobs:
           path: artifacts/mac-x64
 
       - name: Download Linux packages
+        # RELEASE-BRANCH-ONLY: tolerate the missing artifact from the disabled
+        # Linux job (the macOS downloads below already do). Drop with the rest.
+        continue-on-error: true
         uses: actions/download-artifact@v4
         with:
           name: openscreen-linux