fix(linux): Hyprland cursor telemetry + anchor recording start to the first real frame

.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": "poc",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["vite", "--config", "poc/vite.config.js"],
+      "port": 5210
+    }
+  ]
+}

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

@@ -0,0 +1,199 @@
+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
+          retention-days: 30
+
+      - 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

@@ -44,6 +44,10 @@ jobs:
           path: caption-assets
           key: caption-assets-${{ runner.os }}-${{ hashFiles('scripts/fetch-caption-model.mjs') }}
 
+      # ponytail: STT is handled by the bundled whisper-stt-server (whisper.cpp
+      # with native DTW token timestamps). No separate VAD model is fetched
+      # here. See docs/engineering/stt-spec.md for the full architecture.
+
       - name: Build Windows app
         run: npm run build:win -- --publish never
 
@@ -71,6 +75,10 @@ jobs:
           path: caption-assets
           key: caption-assets-${{ runner.os }}-${{ hashFiles('scripts/fetch-caption-model.mjs') }}
 
+      # ponytail: STT is handled by the bundled whisper-stt-server (whisper.cpp
+      # with native DTW token timestamps). No separate VAD model is fetched
+      # here. See docs/engineering/stt-spec.md for the full architecture.
+
       - name: Build Windows Store package
         run: npm run build:win:store -- --publish never
 
@@ -112,6 +120,8 @@ jobs:
           path: caption-assets
           key: caption-assets-${{ runner.os }}-${{ hashFiles('scripts/fetch-caption-model.mjs') }}
 
+      # ponytail: STT is handled by the bundled whisper-stt-server (see the
+      # build-windows comment); no VAD model is fetched here.
       - name: Resolve macOS signing
         id: signing
         env:
@@ -275,6 +285,7 @@ jobs:
           path: caption-assets
           key: caption-assets-${{ runner.os }}-${{ hashFiles('scripts/fetch-caption-model.mjs') }}
 
+      # ponytail: no VAD fetch here either (see build-windows comment).
       - name: Build Linux app
         run: npm run build:linux -- --publish never
 

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Docs
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "website/**"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: [main]
+    paths:
+      - "website/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Cancel in-flight runs on the same ref so fast follow-up pushes
+# don't queue stale builds.
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+      - name: Install dependencies
+        working-directory: website
+        run: npm ci
+      - name: Type-check
+        working-directory: website
+        run: npm run typecheck
+      - name: Build
+        working-directory: website
+        run: npm run build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        with:
+          path: website/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -16,6 +16,7 @@ dist-ssr
 
 # Native helper build outputs
 /electron/native/wgc-capture/build/
+/electron/native/compositor-view/build/
 /electron/native/screencapturekit/build/
 /electron/native/screencapturekit/.build/
 /electron/native/screencapturekit/.swiftpm/
@@ -40,6 +41,7 @@ xcuserdata/
 release/**
 *.kiro/
 .claude/
+.worktrees/
 # npx electron-builder --mac --win
 
 # Playwright
@@ -67,3 +69,39 @@ result-*
 
 # Auto-caption model + ORT wasm — regenerated at build by scripts/fetch-caption-model.mjs
 /caption-assets/
+
+# Native STT artifacts — whisper-stt-server binaries + ggml backend sidecars.
+/electron/native/bin/
+/electron/native/models/
+
+# Build cache for the native STT server (FetchContent clones + CMake build).
+/.cache/
+
+# Vite's dependency cache, moved out of node_modules so concurrent dev servers
+# (main checkout + worktrees, which share node_modules via a junction) stop
+# re-optimising into each other's cache. See `cacheDir` in vite.config.ts.
+/.vite-cache/
+
+# whisper.cpp DTW POC (tools/stt-eval/whispercpp-dtw-poc) — vendored engine
+# clone, downloaded GGML models, and generated build/results artifacts.
+# See docs/engineering/stt-whispercpp-dtw-poc-plan.md.
+/tools/stt-eval/whispercpp-dtw-poc/whisper.cpp/
+/tools/stt-eval/whispercpp-dtw-poc/build-cpu/
+/tools/stt-eval/whispercpp-dtw-poc/build-vulkan/
+/tools/stt-eval/whispercpp-dtw-poc/build-cuda/
+/tools/stt-eval/whispercpp-dtw-poc/build-harness/
+/tools/stt-eval/whispercpp-dtw-poc/fixtures/*.wav
+/tools/stt-eval/whispercpp-dtw-poc/results/
+
+opencode.json
+opencode.json
+
+# Frames dumped by `npm run bench:export -- --dumpFrame=N`, for eyes only.
+bench-frame-*.png
+
+# POC inputs (real recordings) and outputs — big, and not source.
+poc/media/
+poc/out/
+
+# cc-delegate worker worktrees/branches + scratch test artifacts.
+.cc-delegate/