Address webcam sidecar review feedback

Record browser webcam sidecar when native Windows capture is active.

Add native webcam sidecar output and DirectShow NV12/YUY2 fallback.

Sample exported webcam frames by source timestamp.

.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+indent_style = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.env.example

@@ -0,0 +1,10 @@
+APP_NAME=Openscreen
+BUNDLE_ID=com.siddharthvaddem.openscreen
+
+APPLE_ID=
+TEAM_ID=
+SIGN_IDENTITY="Developer ID Application: Samir Patil ()"
+CSC_NAME="Samir Patil ()"
+
+NOTARY_PROFILE=OpenScreen-notary
+APPLE_APP_SPECIFIC_PASSWORD=

.envrc

@@ -0,0 +1 @@
+use flake

.eslintrc.cjs

@@ -1,18 +0,0 @@
-module.exports = {
-  root: true,
-  env: { browser: true, es2020: true },
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-    'plugin:react-hooks/recommended',
-  ],
-  ignorePatterns: ['dist', '.eslintrc.cjs'],
-  parser: '@typescript-eslint/parser',
-  plugins: ['react-refresh'],
-  rules: {
-    'react-refresh/only-export-components': [
-      'warn',
-      { allowConstantExport: true },
-    ],
-  },
-}

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @siddharthvaddem

.github/FUNDING.yml

@@ -1,15 +0,0 @@
-# These are supported funding model platforms
-
-github: siddharthvaddem
-patreon: # Replace with a single Patreon username
-open_collective: # Replace with a sissgle Open Collective username
-ko_fi: # Replace with a single Ko-fi username
-tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-polar: # Replace with a single Polar username
-buy_me_a_coffee: siddharthvaddem
-thanks_dev: # Replace with a single thanks.dev username
-custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,38 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: ''
-labels: ''
-assignees: ''
-
----
-
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
-
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
-
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
-
-**Additional context**
-Add any other context about the problem here.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,149 @@
+name: Bug Report
+description: Create a report to help us improve
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: checkboxes
+    attributes:
+      label: Search existing issues
+      description: Please search to see if an issue already exists for the bug you encountered.
+      options:
+        - label: I have searched the existing issues
+          required: true
+
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+      placeholder: e.g., When I click submit, nothing happens...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: A clear and concise description of what you expected to happen.
+      placeholder: e.g., The form should submit and show a success message
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: To Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Go to '...'
+        2. Click on '....'
+        3. Scroll down to '....'
+        4. See error
+    validations:
+      required: false
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots
+      description: If applicable, add screenshots to help explain your problem.
+      placeholder: Drag and drop images here or paste them
+    validations:
+      required: false
+
+  - type: dropdown
+    id: os-type
+    attributes:
+      label: OS
+      description: Operating system
+      options:
+        - Windows
+        - macOS
+        - Linux
+        - iOS
+        - Android
+        - Other
+    validations:
+      required: false
+
+  - type: input
+    id: os-version
+    attributes:
+      label: OS Version
+      description: Please specify your OS version
+      placeholder: e.g., Windows 11, macOS Sonoma, Ubuntu 22.04
+    validations:
+      required: false
+
+  - type: input
+    id: os-other
+    attributes:
+      label: Other OS
+      description: If you selected "Other" for OS, please specify your operating system
+      placeholder: e.g., FreeBSD, Solaris
+    validations:
+      required: false
+
+  - type: dropdown
+    id: browser
+    attributes:
+      label: Browser
+      description: What browser are you using?
+      options:
+        - Chrome
+        - Firefox
+        - Safari
+        - Edge
+        - Other
+    validations:
+      required: false
+
+  - type: input
+    id: browser-version
+    attributes:
+      label: Browser Version
+      description: Please specify your browser version
+      placeholder: e.g., 120.0, 121.0.1
+    validations:
+      required: false
+
+  - type: input
+    id: browser-other
+    attributes:
+      label: Other Browser
+      description: If you selected "Other" for Browser, please specify your browser
+      placeholder: e.g., Brave, Vivaldi, Opera
+    validations:
+      required: false
+
+  - type: dropdown
+    id: device-type
+    attributes:
+      label: Device Type
+      description: Device category
+      options:
+        - Desktop
+        - Laptop
+        - Tablet
+        - Mobile
+        - Other
+    validations:
+      required: false
+
+  - type: input
+    id: device-other
+    attributes:
+      label: Other Device
+      description: If you selected "Other" for Device Type, please specify your device
+      placeholder: e.g., Smart TV, IoT device
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add any other context about the problem here.
+      placeholder: Links, references, or any additional information
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,20 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
-
----
-
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
-
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen.
-
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
-**Additional context**
-Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,48 @@
+name: Feature Request
+description: Suggest an idea for this project
+title: "[Feature]: "
+labels: ["enhancement", "feature-request"]
+body:
+  - type: checkboxes
+    attributes:
+      label: Search existing issues
+      description: Please search to see if an issue already exists for this feature request.
+      options:
+        - label: I have searched the existing issues
+          required: true
+
+  - type: textarea
+    id: problem-description
+    attributes:
+      label: Is your feature request related to a problem?
+      description: A clear and concise description of what the problem is.
+      placeholder: e.g., I'm always frustrated when I have to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution-description
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+      placeholder: Describe the feature or change you're proposing
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+      placeholder: Have you considered any workarounds or alternative approaches?
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add any other context or screenshots about the feature request here.
+      placeholder: Links, mockups, or any additional information
+    validations:
+      required: false

.github/workflows/build.yml

@@ -3,6 +3,16 @@ name: Build Electron App
 
 on:
   workflow_dispatch:
+    inputs:
+      arch:
+        description: 'Architecture to build'
+        required: true
+        default: 'both'
+        type: choice
+        options:
+          - arm64
+          - x64
+          - both
 
 jobs:
   build-windows:
@@ -10,18 +20,15 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
-      
+
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
           node-version: '22'
-          
+
       - name: Install dependencies
         run: npm ci
-        
-      - name: Install app dependencies
-        run: npx electron-builder install-app-deps
-        
+
       - name: Build Windows app
         run: npm run build:win
         env:
@@ -36,6 +43,182 @@ jobs:
 
   build-macos:
     runs-on: macos-latest
+    strategy:
+      matrix:
+        arch: ${{ github.event.inputs.arch == 'both' && fromJSON('["arm64", "x64"]') || fromJSON(format('["{0}"]', github.event.inputs.arch)) }}
+    
+    steps:
+      # ─── Checkout ─────────────────────────────────────────────
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # ─── Setup Node.js ────────────────────────────────────────
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      # ─── Setup Python (needed by some native deps) ────────────
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # ─── Install Dependencies ─────────────────────────────────
+      - name: Install dependencies
+        run: npm ci
+
+      # ─── Import Code Signing Certificate ──────────────────────
+      # This is the KEY step that makes CI signing work.
+      # We create a temporary keychain, import the .p12 cert into it,
+      # and set it as the default so codesign can find it.
+      - name: Import code signing certificate
+        env:
+          MAC_CERTIFICATE_P12: ${{ secrets.MAC_CERTIFICATE_P12 }}
+          MAC_CERTIFICATE_PASSWORD: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
+        run: |
+          # Create a temporary keychain
+          KEYCHAIN_PATH=$RUNNER_TEMP/build.keychain-db
+          KEYCHAIN_PASSWORD=$(openssl rand -base64 32)
+
+          # Create and configure keychain
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+
+          # Decode and import certificate
+          echo "$MAC_CERTIFICATE_P12" | base64 --decode > $RUNNER_TEMP/certificate.p12
+          security import $RUNNER_TEMP/certificate.p12 \
+            -k "$KEYCHAIN_PATH" \
+            -P "$MAC_CERTIFICATE_PASSWORD" \
+            -T /usr/bin/codesign \
+            -T /usr/bin/security
+
+          # Allow codesign to access the keychain without UI prompt
+          security set-key-partition-list -S apple-tool:,apple: -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+
+          # Add to keychain search path (makes it the default)
+          security list-keychains -d user -s "$KEYCHAIN_PATH" $(security list-keychains -d user | tr -d '"')
+
+          # Verify the identity is available
+          security find-identity -v -p codesigning "$KEYCHAIN_PATH"
+
+          # Clean up the .p12 file
+          rm -f $RUNNER_TEMP/certificate.p12
+
+      # ─── Build Vite + Electron ────────────────────────────────
+      - name: Build Vite + Electron
+        run: npx tsc && npx vite build
+
+      # ─── Package with electron-builder ────────────────────────
+      # electron-builder handles deep codesigning the .app bundle
+      # "notarize: false" in electron-builder.json5 prevents it from
+      # trying its own notarization flow
+      - name: Package .app bundle
+        run: npx electron-builder --mac --${{ matrix.arch }} --dir
+        env:
+          CSC_NAME: "Samir Patil (N26FZ4GW28)"
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # ─── Read version from package.json ───────────────────────
+      - name: Get version
+        id: version
+        run: echo "version=$(node -p 'require(\"./package.json\").version')" >> $GITHUB_OUTPUT
+
+      # ─── Locate the .app bundle ───────────────────────────────
+      - name: Find .app bundle
+        id: find_app
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          echo "=== Release directory contents ==="
+          ls -laR "release/${VERSION}/" || echo "release/${VERSION}/ not found"
+          echo "=== Searching for .app bundle ==="
+          APP_BUNDLE=$(find "release/${VERSION}" -maxdepth 4 -name "*.app" -type d | head -n1)
+          if [ -z "$APP_BUNDLE" ]; then
+            echo "::error::No .app bundle found in release/${VERSION}/"
+            exit 1
+          fi
+          echo "app_bundle=$APP_BUNDLE" >> $GITHUB_OUTPUT
+          echo "Found: $APP_BUNDLE"
+
+      # ─── Verify .app signature ────────────────────────────────
+      - name: Verify .app code signature
+        run: codesign --verify --deep --strict "${{ steps.find_app.outputs.app_bundle }}"
+
+      # ─── Create DMG ───────────────────────────────────────────
+      - name: Create DMG
+        id: dmg
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          ARCH="${{ matrix.arch }}"
+          DMG_NAME="Openscreen-Mac-${ARCH}-${VERSION}.dmg"
+          RELEASE_DIR="release/${VERSION}"
+          DMG_OUTPUT="${RELEASE_DIR}/${DMG_NAME}"
+          STAGING="${RELEASE_DIR}/dmg-staging"
+
+          mkdir -p "$STAGING"
+          cp -R "${{ steps.find_app.outputs.app_bundle }}" "$STAGING/"
+          ln -s /Applications "$STAGING/Applications"
+
+          hdiutil create \
+            -srcfolder "$STAGING" \
+            -volname "Openscreen" \
+            -fs HFS+ \
+            -fsargs "-c c=64,a=16,e=16" \
+            -format UDBZ \
+            "$DMG_OUTPUT"
+
+          rm -rf "$STAGING"
+
+          echo "dmg_path=$DMG_OUTPUT" >> $GITHUB_OUTPUT
+          echo "dmg_name=$DMG_NAME" >> $GITHUB_OUTPUT
+
+      # ─── Sign DMG ─────────────────────────────────────────────
+      - name: Sign DMG
+        run: |
+          codesign --force \
+            --sign "Developer ID Application: Samir Patil (N26FZ4GW28)" \
+            --timestamp \
+            "${{ steps.dmg.outputs.dmg_path }}"
+
+      # ─── Notarize DMG ────────────────────────────────────────
+      # On CI we can't use keychain profiles for notarytool, so we
+      # pass credentials directly via env vars / flags
+      - name: Notarize DMG
+        run: |
+          xcrun notarytool submit "${{ steps.dmg.outputs.dmg_path }}" \
+            --apple-id "${{ secrets.APPLE_ID }}" \
+            --team-id "${{ secrets.APPLE_TEAM_ID }}" \
+            --password "${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}" \
+            --wait
+        timeout-minutes: 15
+
+      # ─── Staple ───────────────────────────────────────────────
+      - name: Staple notarization ticket
+        run: xcrun stapler staple "${{ steps.dmg.outputs.dmg_path }}"
+
+      # ─── Validate ─────────────────────────────────────────────
+      - name: Validate stapled DMG
+        run: |
+          xcrun stapler validate "${{ steps.dmg.outputs.dmg_path }}"
+          spctl -a -vv -t install "${{ steps.dmg.outputs.dmg_path }}"
+
+      # ─── Upload Artifact ──────────────────────────────────────
+      - name: Upload notarized DMG
+        uses: actions/upload-artifact@v4
+        with:
+          name: openscreen-mac-${{ matrix.arch }}
+          path: ${{ steps.dmg.outputs.dmg_path }}
+          retention-days: 30
+
+      # ─── Cleanup Keychain ─────────────────────────────────────
+      - name: Cleanup keychain
+        if: always()
+        run: security delete-keychain $RUNNER_TEMP/build.keychain-db || true
+
+  build-linux:
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
@@ -45,26 +228,26 @@ jobs:
         with:
           node-version: '22'
 
-      - name: Setup Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.11'
-
       - name: Install dependencies
         run: npm ci
 
-      - name: Install app dependencies
-        run: npx electron-builder install-app-deps
+      # bsdtar (from libarchive-tools) is required by fpm to build pacman
+      # packages. AppImage and deb don't need it; ubuntu-latest doesn't ship it.
+      - name: Install pacman build dependencies
+        run: sudo apt-get update && sudo apt-get install -y libarchive-tools
 
-      - name: Build macOS app
-        run: npm run build:mac
+      - name: Build Linux app
+        run: npm run build:linux
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Upload macOS build
+      - name: Upload Linux build
         uses: actions/upload-artifact@v4
         with:
-          name: macos-installer
-          path: release/**/*.dmg
+          name: linux-installer
+          path: |
+            release/**/*.AppImage
+            release/**/*.zsync
+            release/**/*.deb
+            release/**/*.pacman
           retention-days: 30
-

.github/workflows/bump-nix-package.yml

@@ -0,0 +1,118 @@
+name: Bump Nix package on release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to bump (e.g. v1.5.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || !github.event.release.prerelease
+    steps:
+      - name: Resolve tag and version
+        id: meta
+        env:
+          GH_EVENT_TAG: ${{ github.event.release.tag_name }}
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          TAG="${GH_EVENT_TAG:-$INPUT_TAG}"
+          if [[ -z "$TAG" ]]; then
+            echo "::error::No tag resolved from release event or workflow input"
+            exit 1
+          fi
+          VERSION="${TAG#v}"
+          BRANCH="chore/bump-nix-${VERSION}"
+          echo "tag=$TAG"         >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "branch=$BRANCH"   >> "$GITHUB_OUTPUT"
+
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+
+      - name: Compute npmDepsHash
+        id: hash
+        run: |
+          set -euo pipefail
+          HASH=$(nix run nixpkgs#prefetch-npm-deps -- package-lock.json)
+          if [[ -z "$HASH" ]]; then
+            echo "::error::prefetch-npm-deps returned an empty hash"
+            exit 1
+          fi
+          echo "hash=$HASH" >> "$GITHUB_OUTPUT"
+          echo "Computed npmDepsHash: $HASH"
+
+      - name: Update nix/package.nix
+        env:
+          VERSION: ${{ steps.meta.outputs.version }}
+          HASH: ${{ steps.hash.outputs.hash }}
+        run: |
+          set -euo pipefail
+          # Update version line: `  version = "<anything>";`
+          sed -i -E "s|^([[:space:]]*version[[:space:]]*=[[:space:]]*)\"[^\"]*\";|\1\"${VERSION}\";|" nix/package.nix
+          # Update npmDepsHash line: `  npmDepsHash = "<anything>";`
+          sed -i -E "s|^([[:space:]]*npmDepsHash[[:space:]]*=[[:space:]]*)\"[^\"]*\";|\1\"${HASH}\";|" nix/package.nix
+
+          echo "=== diff ==="
+          git --no-pager diff nix/package.nix || true
+
+      - name: Create PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ steps.meta.outputs.version }}
+          HASH: ${{ steps.hash.outputs.hash }}
+          BRANCH: ${{ steps.meta.outputs.branch }}
+          TAG: ${{ steps.meta.outputs.tag }}
+        run: |
+          set -euo pipefail
+
+          if git diff --quiet -- nix/package.nix; then
+            echo "nix/package.nix already at v${VERSION} with this hash — nothing to do."
+            exit 0
+          fi
+
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # Replace any prior bump branch to keep the workflow idempotent.
+          git push origin --delete "$BRANCH" 2>/dev/null || true
+          git checkout -b "$BRANCH"
+          git add nix/package.nix
+          git commit -m "chore: bump nix package to v${VERSION}"
+          git push -u origin "$BRANCH"
+
+          gh pr create \
+            --title "chore: bump nix package to v${VERSION}" \
+            --base main \
+            --head "$BRANCH" \
+            --body "$(cat <<EOF
+          Automated bump triggered by release \`${TAG}\`.
+
+          - \`version\` → \`${VERSION}\`
+          - \`npmDepsHash\` → \`${HASH}\` (computed via \`prefetch-npm-deps package-lock.json\`)
+
+          Merge this so Nix users (NixOS, Home Manager, \`nix run github:siddharthvaddem/openscreen\`) pick up the new release.
+
+          > Note: PRs opened by \`GITHUB_TOKEN\` don't auto-trigger CI. The diff is two lines — review the change here, then merge. If you want CI to run, push an empty commit to this branch or close-and-reopen the PR.
+          EOF
+          )"

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npx tsc --noEmit
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run test
+      - run: npm run test:browser:install
+      - run: npm run test:browser
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npx vite build

.github/workflows/discord.yaml

@@ -0,0 +1,519 @@
+name: PR to Discord Forum
+
+on:
+  pull_request_target:
+    types: [opened, reopened, ready_for_review, converted_to_draft, synchronize, edited, labeled, unlabeled, closed]
+  pull_request_review:
+    types: [submitted]
+  issue_comment:
+    types: [created]
+  schedule:
+    - cron: "0 12 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: read
+
+jobs:
+  notify:
+    if: github.event_name != 'schedule' && github.actor != 'github-actions[bot]'
+    concurrency:
+      group: discord-pr-sync-${{ github.repository }}-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Sync PR activity to Discord forum thread
+        id: sync
+        uses: actions/github-script@v7
+        env:
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          DISCORD_PR_FORUM_WEBHOOK: ${{ secrets.DISCORD_PR_FORUM_WEBHOOK }}
+          DISCORD_WEBHOOK_USERNAME: ${{ secrets.DISCORD_WEBHOOK_USERNAME }}
+          DISCORD_WEBHOOK_AVATAR_URL: ${{ secrets.DISCORD_WEBHOOK_AVATAR_URL }}
+          DISCORD_BOT_TOKEN: ${{ secrets.DISCORD_BOT_TOKEN }}
+          DISCORD_REVIEWER_ROLE_ID: ${{ secrets.DISCORD_REVIEWER_ROLE_ID }}
+          DISCORD_ALERT_WEBHOOK_URL: ${{ secrets.DISCORD_ALERT_WEBHOOK_URL }}
+        with:
+          script: |
+            const WEBHOOK_USERNAME = (process.env.DISCORD_WEBHOOK_USERNAME || "OpenScreen").trim();
+            const WEBHOOK_AVATAR = (process.env.DISCORD_WEBHOOK_AVATAR_URL || "").trim();
+
+            const THREAD_MARKER_REGEX = /<!--\s*discord-thread-id:(\d+)\s*-->/i;
+            const webhookUrl = (process.env.DISCORD_WEBHOOK_URL || process.env.DISCORD_PR_FORUM_WEBHOOK || "").trim();
+            const botToken = (process.env.DISCORD_BOT_TOKEN || "").trim();
+            const reviewerRoleId = (process.env.DISCORD_REVIEWER_ROLE_ID || "").trim();
+            const alertWebhookUrl = (process.env.DISCORD_ALERT_WEBHOOK_URL || "").trim();
+
+            const TAGS = {
+              open: "1493976692967080096",
+              draft: "1493976782028935279",
+              ready: "1493976833626996756",
+              changes: "1493976909875515564",
+              approved: "1493976951038152764",
+              merged: "1493977049709281320",
+              closed: "1493977108102516786",
+            };
+
+            const labelTagMap = {
+              bug: "1493977562773458975",
+              enhancement: "1493977619216207993",
+              documentation: "1493978565153394830",
+            };
+
+            function cleanDescription(text, maxLen = 3500) {
+              if (!text) return "No description provided.";
+              const normalized = text
+                .replace(/\r\n/g, "\n")
+                .replace(/\n{3,}/g, "\n\n")
+                .trim();
+              if (normalized.length <= maxLen) return normalized;
+              return `${normalized.slice(0, maxLen - 1)}…`;
+            }
+
+            function trimThreadName(name) {
+              return name.length > 95 ? name.slice(0, 95) : name;
+            }
+
+            function extractThreadId(body) {
+              if (!body) return null;
+              const match = body.match(THREAD_MARKER_REGEX);
+              return match ? match[1] : null;
+            }
+
+            function upsertThreadMarker(body, threadId) {
+              const cleaned = (body || "").replace(THREAD_MARKER_REGEX, "").trim();
+              return `${cleaned}\n\n<!-- discord-thread-id:${threadId} -->`.trim();
+            }
+
+            async function discordPost(payload, options = {}) {
+              const endpoint = new URL(webhookUrl);
+              endpoint.searchParams.set("wait", "true");
+              if (options.threadId) endpoint.searchParams.set("thread_id", String(options.threadId));
+
+              const response = await fetch(endpoint.toString(), {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                  username: WEBHOOK_USERNAME,
+                  avatar_url: WEBHOOK_AVATAR,
+                  allowed_mentions: { parse: [] },
+                  ...payload,
+                })
+              });
+
+              const contentType = (response.headers.get("content-type") || "").toLowerCase();
+              const text = await response.text();
+
+              if (!response.ok) {
+                throw new Error(`Discord API error ${response.status}: ${text}`);
+              }
+
+              if (!text) return {};
+              if (contentType.includes("application/json")) return JSON.parse(text);
+
+              // Some proxy/CDN edge responses may return HTML with 2xx; avoid crashing on JSON parse.
+              core.warning(`Discord webhook returned non-JSON response (content-type: ${contentType || "unknown"}).`);
+              return {};
+            }
+
+            async function patchDiscordThread(threadId, patchBody) {
+              if (!botToken || !threadId) return;
+              const response = await fetch(`https://discord.com/api/v10/channels/${threadId}`, {
+                method: "PATCH",
+                headers: {
+                  "Authorization": `Bot ${botToken}`,
+                  "Content-Type": "application/json",
+                },
+                body: JSON.stringify(patchBody),
+              });
+              if (!response.ok) {
+                const text = await response.text();
+                core.warning(`Discord thread patch failed (${response.status}): ${text}`);
+              }
+            }
+
+            function desiredStatusTag(prState) {
+              if (prState.merged && TAGS.merged) return TAGS.merged;
+              if (prState.closed && !prState.merged && TAGS.closed) return TAGS.closed;
+              if (prState.reviewState === "CHANGES_REQUESTED" && TAGS.changes) return TAGS.changes;
+              if (prState.reviewState === "APPROVED" && TAGS.approved) return TAGS.approved;
+              if (prState.draft && TAGS.draft) return TAGS.draft;
+              if (!prState.draft && TAGS.ready) return TAGS.ready;
+              return TAGS.open || null;
+            }
+
+            function tagIdsFromLabels(labels) {
+              const out = [];
+              for (const label of labels) {
+                const mapped = labelTagMap[label.toLowerCase()] || labelTagMap[label];
+                if (mapped) out.push(String(mapped));
+              }
+              return out;
+            }
+
+            async function getPullRequest() {
+              if (context.eventName === "pull_request_target" || context.eventName === "pull_request_review") {
+                return context.payload.pull_request || null;
+              }
+              if (context.eventName === "issue_comment") {
+                const issue = context.payload.issue;
+                if (!issue?.pull_request) return null;
+                const { data } = await github.rest.pulls.get({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: issue.number,
+                });
+                return data;
+              }
+              return null;
+            }
+
+            async function getReviewState(owner, repo, pullNumber) {
+              const { data } = await github.rest.pulls.listReviews({ owner, repo, pull_number: pullNumber, per_page: 100 });
+              let hasChanges = false;
+              let hasApproved = false;
+              for (const r of data) {
+                const s = (r.state || "").toUpperCase();
+                if (s === "CHANGES_REQUESTED") hasChanges = true;
+                if (s === "APPROVED") hasApproved = true;
+              }
+              if (hasChanges) return "CHANGES_REQUESTED";
+              if (hasApproved) return "APPROVED";
+              return "NONE";
+            }
+
+            async function sendFailureAlert(message) {
+              if (!alertWebhookUrl) return;
+              try {
+                await fetch(alertWebhookUrl, {
+                  method: "POST",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify({
+                    username: "OpenScreen",
+                    avatar_url: WEBHOOK_AVATAR,
+                    content: `⚠️ PR Discord sync failed\n${message}\nRun: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+                    allowed_mentions: { parse: [] }
+                  })
+                });
+              } catch {
+                core.warning("Failed to send failure alert webhook.");
+              }
+            }
+
+            try {
+              const pr = await getPullRequest();
+              if (!pr) {
+                core.info("No PR context found. Skipping.");
+                return;
+              }
+
+              if (!webhookUrl) {
+                const strictEvents = new Set(["pull_request_target", "workflow_dispatch"]);
+                const msg =
+                  `Discord sync skipped: webhook secret unavailable for event '${context.eventName}'. ` +
+                  "Set either DISCORD_WEBHOOK_URL or DISCORD_PR_FORUM_WEBHOOK in repository secrets.";
+                if (strictEvents.has(context.eventName)) {
+                  core.setFailed(msg);
+                } else {
+                  core.warning(msg);
+                }
+                return;
+              }
+
+              const action = context.payload.action || "";
+              const owner = context.repo.owner;
+              const repo = context.repo.repo;
+              const number = pr.number;
+              const title = pr.title;
+              const author = pr.user?.login || "unknown";
+              const url = pr.html_url;
+              const authorUrl = pr.user?.html_url || "";
+              const authorAvatar = pr.user?.avatar_url || "";
+              const base = pr.base?.ref || "";
+              const head = pr.head?.ref || "";
+              const repoFullName = pr.base?.repo?.full_name || `${owner}/${repo}`;
+              const labels = (pr.labels || []).map((l) => l.name);
+              const body = (pr.body || "").trim();
+              const reviewState = await getReviewState(owner, repo, number);
+
+              let threadId = extractThreadId(body);
+              const shouldCreateThread =
+                context.eventName === "pull_request_target" &&
+                ["opened", "reopened", "ready_for_review"].includes(action) &&
+                !threadId;
+
+              if (shouldCreateThread) {
+                const fields = [
+                  { name: "PR", value: `[#${number}](${url})`, inline: true },
+                  { name: "Author", value: `[${author}](${authorUrl || url})`, inline: true },
+                  { name: "Status", value: pr.draft ? "Draft" : "Open", inline: true },
+                  { name: "Branches", value: `\`${head}\` -> \`${base}\``, inline: true },
+                  { name: "Changes", value: `+${pr.additions} / -${pr.deletions}`, inline: true },
+                  { name: "Files Changed", value: String(pr.changed_files), inline: true }
+                ];
+
+                if (labels.length) {
+                  fields.push({
+                    name: "Labels",
+                    value: labels.map((l) => `\`${l}\``).join(" "),
+                    inline: false,
+                  });
+                }
+
+                const statusTag = desiredStatusTag({ draft: pr.draft, reviewState, merged: false, closed: false });
+                const mappedLabelTags = tagIdsFromLabels(labels);
+                const appliedTags = [...new Set([statusTag, ...mappedLabelTags].filter(Boolean))];
+
+                const createPayload = {
+                  content: action === "ready_for_review" ? "🔔 PR is now ready for review" : "🔔 New pull request opened",
+                  thread_name: trimThreadName(`PR #${number} - ${title}`),
+                  applied_tags: appliedTags,
+                  embeds: [
+                    {
+                      title: `PR #${number}: ${title}`,
+                      url,
+                      description: cleanDescription(body),
+                      color: pr.draft ? 15105570 : 1998671,
+                      author: {
+                        name: author,
+                        url: authorUrl || undefined,
+                        icon_url: authorAvatar || undefined,
+                      },
+                      fields,
+                      footer: { text: repoFullName },
+                      timestamp: new Date().toISOString(),
+                    },
+                  ],
+                };
+
+                const result = await discordPost(createPayload);
+                const createdThreadId = result.channel_id || null;
+                if (createdThreadId) {
+                  const updatedBody = upsertThreadMarker(body, createdThreadId);
+                  await github.rest.pulls.update({ owner, repo, pull_number: number, body: updatedBody });
+                  core.info(`Created Discord thread ${createdThreadId} and stored mapping.`);
+                } else {
+                  core.warning("Discord thread created but channel_id missing in response.");
+                }
+                return;
+              }
+
+              if (!threadId) {
+                core.info("No mapped Discord thread ID found; skipping update event.");
+                return;
+              }
+
+              if (context.eventName === "pull_request_target" && ["edited", "labeled", "unlabeled", "ready_for_review", "converted_to_draft"].includes(action)) {
+                const statusTag = desiredStatusTag({
+                  draft: action === "converted_to_draft" ? true : pr.draft,
+                  reviewState,
+                  merged: false,
+                  closed: false,
+                });
+                const mappedLabelTags = tagIdsFromLabels(labels);
+                const appliedTags = [...new Set([statusTag, ...mappedLabelTags].filter(Boolean))];
+                await patchDiscordThread(threadId, {
+                  name: trimThreadName(`PR #${number} - ${title}`),
+                  ...(appliedTags.length ? { applied_tags: appliedTags } : {}),
+                });
+              }
+
+              let updateMessage = null;
+              let updateEmbed = null;
+
+              if (context.eventName === "pull_request_target") {
+                if (action === "synchronize") {
+                  const { data: commits } = await github.rest.pulls.listCommits({ owner, repo, pull_number: number, per_page: 5 });
+                  const list = commits.map((c) => `- \`${c.sha.slice(0, 7)}\` ${c.commit.message.split("\n")[0]}`).join("\n") || "- No commit details";
+                  updateMessage = `🧩 New commits pushed to PR #${number}`;
+                  updateEmbed = {
+                    title: `Commit Update • PR #${number}`,
+                    url: `${url}/files`,
+                    description: `${list}`,
+                    color: 1998671,
+                    footer: { text: repoFullName },
+                    timestamp: new Date().toISOString(),
+                  };
+                } else if (action === "edited") {
+                  updateMessage = `✏️ PR #${number} details were edited`;
+                  updateEmbed = {
+                    title: `PR Updated • #${number}`,
+                    url,
+                    description: cleanDescription(body, 1200),
+                    color: 1998671,
+                    timestamp: new Date().toISOString(),
+                  };
+                } else if (action === "closed") {
+                  const isMerged = !!pr.merged;
+                  const statusTag = desiredStatusTag({ draft: false, reviewState, merged: isMerged, closed: true });
+                  const mappedLabelTags = tagIdsFromLabels(labels);
+                  const appliedTags = [...new Set([statusTag, ...mappedLabelTags].filter(Boolean))];
+                  await patchDiscordThread(threadId, {
+                    ...(appliedTags.length ? { applied_tags: appliedTags } : {}),
+                    ...(isMerged ? { archived: true, locked: true } : {}),
+                  });
+
+                  updateMessage = isMerged
+                    ? `✅ PR #${number} was merged`
+                    : `🛑 PR #${number} was closed without merge`;
+                  updateEmbed = {
+                    title: isMerged ? `Merged • PR #${number}` : `Closed • PR #${number}`,
+                    url,
+                    description: isMerged ? "This PR has been merged into the base branch." : "This PR was closed before merge.",
+                    color: isMerged ? 5763719 : 15158332,
+                    timestamp: new Date().toISOString(),
+                  };
+                } else if (action === "ready_for_review") {
+                  updateMessage = `🚀 PR #${number} moved from draft to ready for review`;
+                  if (reviewerRoleId) updateMessage += ` <@&${reviewerRoleId}>`;
+                } else if (action === "converted_to_draft") {
+                  updateMessage = `📝 PR #${number} converted to draft`;
+                }
+              } else if (context.eventName === "pull_request_review") {
+                const review = context.payload.review;
+                if (review) {
+                  const state = (review.state || "commented").toUpperCase();
+                  const reviewer = review.user?.login || "reviewer";
+                  updateMessage = `🧪 Review ${state} by **${reviewer}** on PR #${number}`;
+                  if (state === "CHANGES_REQUESTED" && reviewerRoleId) updateMessage += ` <@&${reviewerRoleId}>`;
+                  updateEmbed = {
+                    title: `Review ${state} • PR #${number}`,
+                    url: review.html_url || url,
+                    description: cleanDescription(review.body || "No review note.", 1000),
+                    color: state === "APPROVED" ? 5763719 : state === "CHANGES_REQUESTED" ? 15158332 : 1998671,
+                    timestamp: new Date().toISOString(),
+                  };
+
+                  if (state === "CHANGES_REQUESTED" || state === "APPROVED") {
+                    const statusTag = desiredStatusTag({ draft: pr.draft, reviewState: state, merged: false, closed: false });
+                    const mappedLabelTags = tagIdsFromLabels(labels);
+                    const appliedTags = [...new Set([statusTag, ...mappedLabelTags].filter(Boolean))];
+                    await patchDiscordThread(threadId, {
+                      ...(appliedTags.length ? { applied_tags: appliedTags } : {}),
+                    });
+                  }
+                }
+              } else if (context.eventName === "issue_comment") {
+                const comment = context.payload.comment;
+                if (comment) {
+                  const commenter = comment.user?.login || "user";
+                  updateMessage = `💬 New comment by **${commenter}** on PR #${number}`;
+                  updateEmbed = {
+                    title: `New PR Comment • #${number}`,
+                    url: comment.html_url || url,
+                    description: cleanDescription(comment.body || "No comment body.", 1000),
+                    color: 1998671,
+                    timestamp: new Date().toISOString(),
+                  };
+                }
+              }
+
+              if (!updateMessage && !updateEmbed) {
+                core.info("No Discord update message for this event/action. Skipping.");
+                return;
+              }
+
+              const payload = { content: updateMessage || "" };
+              if (updateEmbed) payload.embeds = [updateEmbed];
+              await discordPost(payload, { threadId });
+              core.info(`Posted update to Discord thread ${threadId}.`);
+            } catch (err) {
+              const msg = err && err.message ? err.message : String(err);
+              core.setFailed(msg);
+
+              const alertWebhook = process.env.DISCORD_ALERT_WEBHOOK_URL;
+              if (alertWebhook) {
+                try {
+                  await fetch(alertWebhook, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                      username: "OpenScreen",
+                      avatar_url: WEBHOOK_AVATAR,
+                      content: `⚠️ PR->Discord sync failed\n${msg}\nRun: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+                      allowed_mentions: { parse: [] }
+                    })
+                  });
+                } catch {
+                  core.warning("Failed to send alert webhook.");
+                }
+              }
+            }
+
+  weekly-contributor-leaderboard:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post weekly contributor leaderboard
+        uses: actions/github-script@v7
+        env:
+          DISCORD_SPOTLIGHT_WEBHOOK_URL: ${{ secrets.DISCORD_SPOTLIGHT_WEBHOOK_URL }}
+          DISCORD_WEBHOOK_USERNAME: ${{ secrets.DISCORD_WEBHOOK_USERNAME }}
+          DISCORD_WEBHOOK_AVATAR_URL: ${{ secrets.DISCORD_WEBHOOK_AVATAR_URL }}
+        with:
+          script: |
+            const spotlightWebhook = (process.env.DISCORD_SPOTLIGHT_WEBHOOK_URL || "").trim();
+            const webhookUsername = (process.env.DISCORD_WEBHOOK_USERNAME || "OpenScreen").trim();
+            const webhookAvatar = (process.env.DISCORD_WEBHOOK_AVATAR_URL || "").trim();
+            if (!spotlightWebhook) {
+              core.info("DISCORD_SPOTLIGHT_WEBHOOK_URL missing. Skipping leaderboard post.");
+              return;
+            }
+
+            const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+
+            const q = `repo:${owner}/${repo} is:pr is:merged merged:>=${since.substring(0, 10)}`;
+            const search = await github.rest.search.issuesAndPullRequests({
+              q,
+              per_page: 100,
+            });
+
+            const counter = new Map();
+            for (const item of search.data.items) {
+              const login = item.user?.login;
+              if (!login) continue;
+              counter.set(login, (counter.get(login) || 0) + 1);
+            }
+
+            const ranked = [...counter.entries()]
+              .sort((a, b) => b[1] - a[1])
+              .slice(0, 10);
+
+            const totalMerged = search.data.items.length;
+            const lines = ranked.length
+              ? ranked.map(([user, count], idx) => `${idx + 1}. **${user}** - ${count} merged PR(s)`).join("\n")
+              : "No merged PRs this week.";
+
+            const payload = {
+              username: webhookUsername,
+              ...(webhookAvatar ? { avatar_url: webhookAvatar } : {}),
+              embeds: [
+                {
+                  title: "🌟 Weekly Contributor Leaderboard",
+                  description: lines,
+                  color: 1998671,
+                  fields: [
+                    { name: "Merged PRs (7d)", value: String(totalMerged), inline: true },
+                    { name: "Repository", value: `${owner}/${repo}`, inline: true },
+                    { name: "Period", value: "Last 7 days", inline: true }
+                  ],
+                  timestamp: new Date().toISOString()
+                }
+              ],
+              allowed_mentions: { parse: [] }
+            };
+
+            const res = await fetch(`${spotlightWebhook}?wait=true`, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify(payload)
+            });
+
+            if (!res.ok) {
+              const txt = await res.text();
+              core.setFailed(`Leaderboard post failed ${res.status}: ${txt}`);
+            }

.github/workflows/publish-winget.yml

@@ -0,0 +1,26 @@
+name: Publish release to WinGet
+
+on:
+  release:
+    types: [released]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to publish to winget (e.g. v1.4.0)"
+        required: true
+        type: string
+
+jobs:
+  publish:
+    runs-on: windows-latest
+    if: github.event_name == 'workflow_dispatch' || !github.event.release.prerelease
+    steps:
+      - uses: vedantmgoyal9/winget-releaser@v2
+        with:
+          identifier: SiddharthVaddem.OpenScreen
+          # Match the Windows installer asset attached to each release.
+          # Today: "Openscreen.Setup.latest.exe". Adjust this regex if you
+          # ever rename the installer to include a version (e.g. "Setup\.\d+\.\d+\.\d+\.exe").
+          installers-regex: 'Setup\..*\.exe$'
+          release-tag: ${{ inputs.tag || github.event.release.tag_name }}
+          token: ${{ secrets.WINGET_ACC_TOKEN }}

.github/workflows/update-homebrew-cask.yml

@@ -0,0 +1,168 @@
+name: Update Homebrew Cask
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to publish to the tap (e.g. v1.4.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  update-cask:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || !github.event.release.prerelease
+    env:
+      TAP_OWNER: siddharthvaddem
+      TAP_REPO: homebrew-openscreen
+      CASK_NAME: openscreen
+    steps:
+      - name: Resolve tag and version
+        id: meta
+        env:
+          GH_EVENT_TAG: ${{ github.event.release.tag_name }}
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          TAG="${GH_EVENT_TAG:-$INPUT_TAG}"
+          if [[ -z "$TAG" ]]; then
+            echo "::error::No tag resolved from release event or workflow input"
+            exit 1
+          fi
+          VERSION="${TAG#v}"
+          echo "tag=$TAG"         >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Find macOS DMG assets
+        id: assets
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.meta.outputs.tag }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          NAMES=$(gh release view "$TAG" --repo "$REPO" --json assets --jq '.assets[].name')
+
+          # arm64 DMG: explicit "arm64" / "apple silicon" / fallback to any .dmg
+          # whose name does NOT contain "x64" or non-mac platform markers.
+          ARM_NAME=$(echo "$NAMES" | grep -iE '\.dmg$' \
+            | grep -iE '(arm64|apple[-_. ]?silicon)' | head -n1 || true)
+          if [[ -z "$ARM_NAME" ]]; then
+            ARM_NAME=$(echo "$NAMES" | grep -iE '\.dmg$' \
+              | grep -iv 'x64' | grep -iv 'linux' | grep -iv 'win' | head -n1 || true)
+          fi
+
+          # x64 DMG
+          X64_NAME=$(echo "$NAMES" | grep -iE '\.dmg$' \
+            | grep -iE '(x64|x86[-_]?64|intel)' | head -n1 || true)
+
+          if [[ -z "$ARM_NAME" || -z "$X64_NAME" ]]; then
+            echo "::error::Could not locate both arm64 and x64 DMGs in release assets"
+            echo "Available assets:"
+            echo "$NAMES"
+            exit 1
+          fi
+
+          echo "arm_name=$ARM_NAME" >> "$GITHUB_OUTPUT"
+          echo "x64_name=$X64_NAME" >> "$GITHUB_OUTPUT"
+          echo "Found arm64 asset: $ARM_NAME"
+          echo "Found x64 asset:   $X64_NAME"
+
+      - name: Download DMGs and compute sha256
+        id: shas
+        env:
+          REPO: ${{ github.repository }}
+          TAG: ${{ steps.meta.outputs.tag }}
+          ARM_NAME: ${{ steps.assets.outputs.arm_name }}
+          X64_NAME: ${{ steps.assets.outputs.x64_name }}
+        run: |
+          set -euo pipefail
+          BASE="https://github.com/${REPO}/releases/download/${TAG}"
+          curl -fsSL --retry 3 -o /tmp/arm.dmg "${BASE}/${ARM_NAME}"
+          curl -fsSL --retry 3 -o /tmp/x64.dmg "${BASE}/${X64_NAME}"
+          ARM_SHA=$(sha256sum /tmp/arm.dmg | awk '{print $1}')
+          X64_SHA=$(sha256sum /tmp/x64.dmg | awk '{print $1}')
+          echo "arm_sha=$ARM_SHA" >> "$GITHUB_OUTPUT"
+          echo "x64_sha=$X64_SHA" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout tap
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ env.TAP_OWNER }}/${{ env.TAP_REPO }}
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          path: tap
+
+      - name: Write cask file
+        env:
+          REPO: ${{ github.repository }}
+          TAG: ${{ steps.meta.outputs.tag }}
+          VERSION: ${{ steps.meta.outputs.version }}
+          ARM_NAME: ${{ steps.assets.outputs.arm_name }}
+          X64_NAME: ${{ steps.assets.outputs.x64_name }}
+          ARM_SHA: ${{ steps.shas.outputs.arm_sha }}
+          X64_SHA: ${{ steps.shas.outputs.x64_sha }}
+        run: |
+          set -euo pipefail
+          mkdir -p tap/Casks
+          BASE="https://github.com/${REPO}/releases/download/${TAG}"
+
+          # #{version} is Ruby interpolation written literally to the cask
+          # file (bash heredoc leaves "#{...}" alone). \${VERSION}, \${ARM_SHA},
+          # etc. are bash variables expanded by the heredoc. The literal
+          # #{version} fixes Homebrew's "URL is unversioned" audit warning by
+          # making the version string statically detectable.
+          cat > "tap/Casks/${CASK_NAME}.rb" <<EOF
+          cask "${CASK_NAME}" do
+            version "${VERSION}"
+
+            on_arm do
+              sha256 "${ARM_SHA}"
+
+              url "https://github.com/${REPO}/releases/download/v#{version}/${ARM_NAME}"
+            end
+            on_intel do
+              sha256 "${X64_SHA}"
+
+              url "https://github.com/${REPO}/releases/download/v#{version}/${X64_NAME}"
+            end
+
+            name "Openscreen"
+            desc "Screen recorder and video editor"
+            homepage "https://github.com/${REPO}"
+
+            auto_updates false
+            depends_on macos: ">= :big_sur"
+
+            app "Openscreen.app"
+
+            zap trash: [
+              "~/Library/Application Support/Openscreen",
+              "~/Library/Caches/com.siddharthvaddem.openscreen",
+              "~/Library/Logs/Openscreen",
+              "~/Library/Preferences/com.siddharthvaddem.openscreen.plist",
+              "~/Library/Saved Application State/com.siddharthvaddem.openscreen.savedState",
+            ]
+          end
+          EOF
+
+      - name: Commit and push to tap
+        working-directory: tap
+        env:
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          set -euo pipefail
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add "Casks/${CASK_NAME}.rb"
+          if git diff --cached --quiet; then
+            echo "Cask already up to date for ${VERSION} — nothing to commit."
+            exit 0
+          fi
+          git commit -m "Bump ${CASK_NAME} to ${VERSION}"
+          git push

.gitignore

@@ -1,27 +1,60 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
-
-node_modules
-dist
-dist-ssr
-*.local
-
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
-.idea
-.DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
-release/**
-
-# npx electron-builder --mac --win
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-electron
+dist-ssr
+*.local
+.env
+
+# Native helper build outputs
+/electron/native/wgc-capture/build/
+/electron/native/screencapturekit/build/
+/electron/native/screencapturekit/.build/
+/electron/native/screencapturekit/.swiftpm/
+/electron/native/bin/
+
+# Native macOS generated files
+DerivedData/
+*.xcuserstate
+xcuserdata/
+
+# Editor directories and files
+.vscode/*
+.zed/
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+release/**
+*.kiro/
+.claude/
+# npx electron-builder --mac --win
+
+# Playwright
+test-results
+playwright-report/
+
+# Vitest browser mode screenshots
+__screenshots__/
+
+# shell files
+/shell.sh
+# Nix
+result
+result-*
+.direnv/
+
+#kilocode
+.kilo/

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.nvmrc

@@ -0,0 +1 @@
+22.22.1

README.md

@@ -1,67 +1,190 @@
-<p align="center">
-	<img src="openscreen.png" alt="OpenScreen Logo" width="64" />
-</p>
-
-
-# <p align="center">OpenScreen</p>
-
-<p align="center"><strong>OpenScreen is your free, open-source alternative to Screen Studio (sort of).</strong></p>
-
-
-If you don't want to pay $29/month for Screen Studio but want a much simpler version that does what most people seem to need, making beautiful product demos and walkthroughs, here's a free-to-use app for you. OpenScreen does not offer all Screen Studio features, but covers the basics well!
-
-Screen Studio is an awesome product and this is definitely not a 1:1 clone. OpenScreen is a much simpler take, just the basics for folks who want control and don't want to pay. If you need all the fancy features, your best bet is to support Screen Studio (they really do a great job, haha). But if you just want something free (no gotchas) and open, this project does the job!
-
-OpenScreen is 100% free for personal and commercial use. Use it, modify it, distribute it. (Just be cool 😁 and give a shoutout if you feel like it !)
-
-
-
-**⚠️ DISCLAIMER: This is very much in beta and might be buggy here and there (but hope you have a good experience!).**
-
-</p>
-<p align="center">
-	<img src="preview.png" alt="OpenScreen App Preview" style="height: 320px; margin-right: 12px;" />
-	<img src="preview2.png" alt="OpenScreen App Preview 2" style="height: 320px; margin-right: 12px;" />
-	<img src="preview3.png" alt="OpenScreen App Preview 3" style="height: 320px; margin-right: 12px;" />
-	<img src="preview4.png" alt="OpenScreen App Preview 4" style="height: 320px; margin-right: 12px;" />
-	
-</p>
-</p>
-
-## Core Features
-- Record your whole screen or specific apps
-- Add manual zooms (customizable depth levels)
-- Customize the duration and position of zooms however you please
-- Crop video recordings to hide parts
-- Choose between wallpapers, solid colors, gradients or your own picture for your background
-- Motion blur and exponential easing for smoother pan and zoom effects
-
-## macOS Installation instructions
-
-Download the latest installer for your platform from the [GitHub Releases](https://github.com/siddharthvaddem/openscreen/releases) page.
-
-If you encounter issues with macOS Gatekeeper blocking the app (since it does not come with a developer certificate), you can bypass this by running the following command in your terminal after installation:
-
-```bash
-xattr -rd com.apple.quarantine /Applications/Openscreen.app
-```
-
-After running this command, proceed to **System Preferences > Security & Privacy** to grant the necessary permissions for "screen recording" and "accessibility". Once permissions are granted, you can launch the app.
-
-## Built with
-- Electron
-- React
-- TypeScript
-- Vite
-- PixiJS
-- dnd-timeline
-
----
-
-
-_I'm new to open source, idk what I'm doing lol. If something is wrong please raise an issue 🙏_
-
-## License
-
-
-This project is licensed under the [MIT License](./LICENSE). By using this software, you agree that the authors are not liable for any issues, damages, or claims arising from its use.
+> [!WARNING]
+> This started as a side project that took off — it's not production grade and you'll hit bugs, but hopefully it covers what you need.
+
+<p align="center">
+  <img src="public/openscreen.png" alt="OpenScreen Logo" width="64" />
+  <br />
+  <br />
+	<a href="https://trendshift.io/repositories/17427" target="_blank"><img src="https://trendshift.io/api/badge/repositories/17427" alt="siddharthvaddem%2Fopenscreen | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+	<br />
+	<br />
+  <a href="https://deepwiki.com/siddharthvaddem/openscreen">
+    <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" />
+  </a>
+  &nbsp;
+  <a href="https://discord.gg/yAQQhRaEeg">
+    <img src="https://dcbadge.limes.pink/api/server/https://discord.gg/yAQQhRaEeg?style=flat" alt="Join Discord" />
+  </a>
+</p>
+
+# <p align="center">OpenScreen</p>
+
+<p align="center"><strong>OpenScreen is your free, open-source alternative to Screen Studio (sort of).</strong></p>
+
+If you don't want to pay $29/month for Screen Studio but want a much simpler version that does what most people seem to need - quick, polished product demos and walkthroughs you'd post on X, Reddit. OpenScreen does not offer all Screen Studio features, but covers the basics well!
+
+Screen Studio is an awesome product and this is definitely not a 1:1 clone. OpenScreen is a much simpler take, just the basics for folks who want control and don't want to pay. If you need all the fancy features, your best bet is to support Screen Studio (they really do a great job, haha). But if you just want something free (no gotchas) and open, this project does the job!
+
+**100% free** for both **personal** and **commercial** use. Use it, modify it, distribute it — just be cool 😁 and shout out the project if you feel like it.
+
+<p align="center">
+	<img src="public/preview3.png" alt="OpenScreen App Preview 3" style="height: 0.2467; margin-right: 12px;" />
+	<img src="public/preview4.png" alt="OpenScreen App Preview 4" style="height: 0.1678; margin-right: 12px;" />
+</p>
+
+## Core Features
+- Record a specific window, region, or your whole screen.
+- Record microphone and system audio.
+- Webcam overlay with picture-in-picture, drag-to-position, and shape options.
+- Auto or manual zooms with adjustable depth, duration, easing, and pixel-precise position.
+- Wallpapers, solid colors, gradients, or a custom background.
+- Motion blur for smoother pan and zoom transitions.
+- Crop, trim, and per-segment speed control on the timeline.
+- Blur effects to hide sensitive parts of the screen.
+- Cursor and click highlighting.
+- Text, arrow, and image annotations.
+- Save and reopen projects without re-recording.
+- Export to MP4 or GIF in multiple aspect ratios and resolutions.
+- Translated into Arabic, English, Spanish, French, Japanese, Korean, Russian, Turkish, Vietnamese, Simplified Chinese, and Traditional Chinese.
+
+## Installation
+
+Download the latest installer for your platform from the [GitHub Releases](https://github.com/siddharthvaddem/openscreen/releases) page.
+
+### macOS
+
+The easiest way to install on macOS is via [Homebrew](https://brew.sh):
+
+```bash
+brew install --cask siddharthvaddem/openscreen/openscreen
+```
+
+Brew automatically picks the right build for Apple Silicon or Intel, and verifies the download against a notarized signature so Gatekeeper won't block it.
+
+To update later: `brew upgrade --cask openscreen`
+To uninstall: `brew uninstall --cask openscreen` (add `--zap` to also remove app data)
+
+#### Manual install (if you prefer)
+
+If you'd rather grab the `.dmg` directly from the [Releases page](https://github.com/siddharthvaddem/openscreen/releases) and encounter Gatekeeper blocking the app, you can bypass it by running the following command in your terminal after installation:
+
+```bash
+xattr -rd com.apple.quarantine /Applications/Openscreen.app
+```
+
+Note: Give your terminal Full Disk Access in **System Settings > Privacy & Security** to grant you access and then run the above command.
+
+After running this command, proceed to **System Preferences > Security & Privacy** to grant the necessary permissions for "screen recording" and "accessibility". Once permissions are granted, you can launch the app.
+
+### Windows
+
+Install via [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/):
+
+```bash
+winget install SiddharthVaddem.OpenScreen
+```
+
+To update later: `winget upgrade SiddharthVaddem.OpenScreen`
+To uninstall: `winget uninstall SiddharthVaddem.OpenScreen`
+
+If you'd rather grab the `.exe` installer directly, download it from the [Releases page](https://github.com/siddharthvaddem/openscreen/releases).
+
+### Linux
+
+Three packages are published to the [Releases page](https://github.com/siddharthvaddem/openscreen/releases) for each version. Pick the one that matches your distro:
+
+**Debian / Ubuntu / Pop!_OS (`.deb`)**
+```bash
+sudo apt install ./Openscreen-Linux-latest.deb
+```
+
+**Arch / Manjaro (`.pacman`)**
+```bash
+sudo pacman -U Openscreen-Linux-latest.pacman
+```
+
+**Any distro (`.AppImage`)**
+```bash
+chmod +x Openscreen-Linux-*.AppImage
+./Openscreen-Linux-*.AppImage
+```
+
+**NixOS / Nix (flake)**
+
+Try without installing:
+```bash
+nix run github:siddharthvaddem/openscreen
+```
+
+Install into your user profile:
+```bash
+nix profile install github:siddharthvaddem/openscreen
+```
+
+For a NixOS system config (flake):
+```nix
+{
+  inputs.openscreen.url = "github:siddharthvaddem/openscreen";
+
+  outputs = { nixpkgs, openscreen, ... }: {
+    nixosConfigurations.<host> = nixpkgs.lib.nixosSystem {
+      modules = [
+        openscreen.nixosModules.default
+        { programs.openscreen.enable = true; }
+      ];
+    };
+  };
+}
+```
+
+For Home Manager, use `openscreen.homeManagerModules.default` with the same `programs.openscreen.enable = true;`.
+
+You may need to grant screen recording permissions depending on your desktop environment.
+
+**Sandbox error:** If the AppImage fails to launch with a "sandbox" error, run it with `--no-sandbox`:
+```bash
+./Openscreen-Linux-*.AppImage --no-sandbox
+```
+
+### Limitations
+
+System audio capture relies on Electron's [desktopCapturer](https://www.electronjs.org/docs/latest/api/desktop-capturer) and has some platform-specific quirks:
+
+- **macOS**: Requires macOS 13+. On macOS 14.2+ you'll be prompted to grant audio capture permission. macOS 12 and below does not support system audio (mic still works).
+- **Windows**: Works out of the box.
+- **Linux**: Needs PipeWire (default on Ubuntu 22.04+, Fedora 34+). Older PulseAudio-only setups may not support system audio (mic should still work).
+
+## Built with
+- Electron
+- React
+- TypeScript
+- Vite
+- PixiJS
+- dnd-timeline
+
+---
+
+
+## Documentation
+
+See the documentation here:
+[OpenScreen Docs](https://deepwiki.com/siddharthvaddem/openscreen)
+Refresh if outdated.
+
+## Contributing
+
+Contributions are welcome - please **include screenshots or a short video** for any UI change or new user-facing feature. If it touches what users see or do, show it. Skip only when it genuinely doesn't apply. PRs that don't follow this will be closed.
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=siddharthvaddem%2Fopenscreen&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=siddharthvaddem/openscreen&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=siddharthvaddem/openscreen&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=siddharthvaddem/openscreen&type=date&legend=top-left" />
+ </picture>
+</a>
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE). By using this software, you agree that the authors are not liable for any issues, damages, or claims arising from its use.

biome.json

@@ -0,0 +1,134 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
+	"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+	"files": { "ignoreUnknown": false, "includes": ["**", "!**/*.css"] },
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab",
+		"formatWithErrors": true,
+		"lineEnding": "lf",
+		"lineWidth": 100,
+		"attributePosition": "auto"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": false,
+			"complexity": {
+				"noAdjacentSpacesInRegex": "error",
+				"noBannedTypes": "error",
+				"noExtraBooleanCast": "error",
+				"noUselessCatch": "error",
+				"noUselessEscapeInRegex": "error",
+				"noUselessThisAlias": "error",
+				"noUselessTypeConstraint": "error"
+			},
+			"correctness": {
+				"noConstAssign": "error",
+				"noConstantCondition": "error",
+				"noEmptyCharacterClassInRegex": "error",
+				"noEmptyPattern": "error",
+				"noGlobalObjectCalls": "error",
+				"noInnerDeclarations": "error",
+				"noInvalidConstructorSuper": "error",
+				"noNonoctalDecimalEscape": "error",
+				"noPrecisionLoss": "error",
+				"noSelfAssign": "error",
+				"noSetterReturn": "error",
+				"noSwitchDeclarations": "error",
+				"noUndeclaredVariables": "error",
+				"noUnreachable": "error",
+				"noUnreachableSuper": "error",
+				"noUnsafeFinally": "error",
+				"noUnsafeOptionalChaining": "error",
+				"noUnusedLabels": "error",
+				"noUnusedVariables": "error",
+				"useExhaustiveDependencies": "warn",
+				"useHookAtTopLevel": "error",
+				"useIsNan": "error",
+				"useValidForDirection": "error",
+				"useValidTypeof": "error",
+				"useYield": "error"
+			},
+			"style": {
+				"noNamespace": "off",
+				"useArrayLiterals": "error",
+				"useAsConstAssertion": "error",
+				"useComponentExportOnlyModules": "off"
+			},
+			"suspicious": {
+				"noAssignInExpressions": "error",
+				"noAsyncPromiseExecutor": "error",
+				"noCatchAssign": "error",
+				"noClassAssign": "error",
+				"noCompareNegZero": "error",
+				"noControlCharactersInRegex": "error",
+				"noDebugger": "error",
+				"noDuplicateCase": "error",
+				"noDuplicateClassMembers": "error",
+				"noDuplicateElseIf": "error",
+				"noDuplicateObjectKeys": "error",
+				"noDuplicateParameters": "error",
+				"noEmptyBlockStatements": "warn",
+				"noExplicitAny": "warn",
+				"noExtraNonNullAssertion": "error",
+				"noFallthroughSwitchClause": "error",
+				"noFunctionAssign": "error",
+				"noGlobalAssign": "error",
+				"noImportAssign": "error",
+				"noIrregularWhitespace": "error",
+				"noMisleadingCharacterClass": "error",
+				"noMisleadingInstantiator": "error",
+				"noNonNullAssertedOptionalChain": "error",
+				"noPrototypeBuiltins": "error",
+				"noRedeclare": "error",
+				"noShadowRestrictedNames": "error",
+				"noSparseArray": "error",
+				"noTsIgnore": "error",
+				"noUnsafeDeclarationMerging": "error",
+				"noUnsafeNegation": "error",
+				"noUselessRegexBackrefs": "error",
+				"noWith": "error",
+				"useGetterReturn": "error"
+			}
+		},
+		"includes": ["**", "**/dist", "**/.eslintrc.cjs", "!**/*.css"]
+	},
+	"javascript": { "formatter": { "quoteStyle": "double" } },
+	"overrides": [
+		{
+			"includes": ["*.ts", "*.tsx", "*.mts", "*.cts"],
+			"linter": {
+				"rules": {
+					"complexity": { "noArguments": "error" },
+					"correctness": {
+						"noConstAssign": "off",
+						"noGlobalObjectCalls": "off",
+						"noInvalidBuiltinInstantiation": "off",
+						"noInvalidConstructorSuper": "off",
+						"noSetterReturn": "off",
+						"noUndeclaredVariables": "off",
+						"noUnreachable": "off",
+						"noUnreachableSuper": "off"
+					},
+					"style": { "useConst": "error" },
+					"suspicious": {
+						"noDuplicateClassMembers": "off",
+						"noDuplicateObjectKeys": "off",
+						"noDuplicateParameters": "off",
+						"noFunctionAssign": "off",
+						"noImportAssign": "off",
+						"noRedeclare": "off",
+						"noUnsafeNegation": "off",
+						"noVar": "error",
+						"useGetterReturn": "off"
+					}
+				}
+			}
+		}
+	],
+	"assist": {
+		"enabled": true,
+		"actions": { "source": { "organizeImports": "on" } }
+	}
+}

components.json

@@ -1,22 +1,22 @@
 {
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": false,
-  "tsx": true,
-  "tailwind": {
-    "config": "tailwind.config.cjs",
-    "css": "src/index.css",
-    "baseColor": "stone",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "iconLibrary": "lucide",
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "registries": {}
+	"$schema": "https://ui.shadcn.com/schema.json",
+	"style": "new-york",
+	"rsc": false,
+	"tsx": true,
+	"tailwind": {
+		"config": "tailwind.config.cjs",
+		"css": "src/index.css",
+		"baseColor": "stone",
+		"cssVariables": true,
+		"prefix": ""
+	},
+	"iconLibrary": "lucide",
+	"aliases": {
+		"components": "@/components",
+		"utils": "@/lib/utils",
+		"ui": "@/components/ui",
+		"lib": "@/lib",
+		"hooks": "@/hooks"
+	},
+	"registries": {}
 }

dist-electron/main.js

@@ -1,397 +0,0 @@
-import { ipcMain, screen, BrowserWindow, desktopCapturer, shell, app, dialog, nativeImage, Tray, Menu } from "electron";
-import { fileURLToPath } from "node:url";
-import path from "node:path";
-import fs from "node:fs/promises";
-const __dirname$1 = path.dirname(fileURLToPath(import.meta.url));
-const APP_ROOT = path.join(__dirname$1, "..");
-const VITE_DEV_SERVER_URL$1 = process.env["VITE_DEV_SERVER_URL"];
-const RENDERER_DIST$1 = path.join(APP_ROOT, "dist");
-let hudOverlayWindow = null;
-ipcMain.on("hud-overlay-hide", () => {
-  if (hudOverlayWindow && !hudOverlayWindow.isDestroyed()) {
-    hudOverlayWindow.minimize();
-  }
-});
-function createHudOverlayWindow() {
-  const primaryDisplay = screen.getPrimaryDisplay();
-  const { workArea } = primaryDisplay;
-  const windowWidth = 500;
-  const windowHeight = 100;
-  const x = Math.floor(workArea.x + (workArea.width - windowWidth) / 2);
-  const y = Math.floor(workArea.y + workArea.height - windowHeight - 5);
-  const win = new BrowserWindow({
-    width: windowWidth,
-    height: windowHeight,
-    minWidth: 500,
-    maxWidth: 500,
-    minHeight: 100,
-    maxHeight: 100,
-    x,
-    y,
-    frame: false,
-    transparent: true,
-    resizable: false,
-    alwaysOnTop: true,
-    skipTaskbar: true,
-    hasShadow: false,
-    webPreferences: {
-      preload: path.join(__dirname$1, "preload.mjs"),
-      nodeIntegration: false,
-      contextIsolation: true,
-      backgroundThrottling: false
-    }
-  });
-  win.webContents.on("did-finish-load", () => {
-    win == null ? void 0 : win.webContents.send("main-process-message", (/* @__PURE__ */ new Date()).toLocaleString());
-  });
-  hudOverlayWindow = win;
-  win.on("closed", () => {
-    if (hudOverlayWindow === win) {
-      hudOverlayWindow = null;
-    }
-  });
-  if (VITE_DEV_SERVER_URL$1) {
-    win.loadURL(VITE_DEV_SERVER_URL$1 + "?windowType=hud-overlay");
-  } else {
-    win.loadFile(path.join(RENDERER_DIST$1, "index.html"), {
-      query: { windowType: "hud-overlay" }
-    });
-  }
-  return win;
-}
-function createEditorWindow() {
-  const win = new BrowserWindow({
-    width: 1200,
-    height: 800,
-    minWidth: 800,
-    minHeight: 600,
-    titleBarStyle: "hiddenInset",
-    trafficLightPosition: { x: 12, y: 12 },
-    transparent: false,
-    resizable: true,
-    alwaysOnTop: false,
-    skipTaskbar: false,
-    title: "OpenScreen",
-    backgroundColor: "#000000",
-    webPreferences: {
-      preload: path.join(__dirname$1, "preload.mjs"),
-      nodeIntegration: false,
-      contextIsolation: true,
-      webSecurity: false,
-      backgroundThrottling: false
-    }
-  });
-  win.maximize();
-  win.webContents.on("did-finish-load", () => {
-    win == null ? void 0 : win.webContents.send("main-process-message", (/* @__PURE__ */ new Date()).toLocaleString());
-  });
-  if (VITE_DEV_SERVER_URL$1) {
-    win.loadURL(VITE_DEV_SERVER_URL$1 + "?windowType=editor");
-  } else {
-    win.loadFile(path.join(RENDERER_DIST$1, "index.html"), {
-      query: { windowType: "editor" }
-    });
-  }
-  return win;
-}
-function createSourceSelectorWindow() {
-  const { width, height } = screen.getPrimaryDisplay().workAreaSize;
-  const win = new BrowserWindow({
-    width: 620,
-    height: 420,
-    minHeight: 350,
-    maxHeight: 500,
-    x: Math.round((width - 620) / 2),
-    y: Math.round((height - 420) / 2),
-    frame: false,
-    resizable: false,
-    alwaysOnTop: true,
-    transparent: true,
-    backgroundColor: "#00000000",
-    webPreferences: {
-      preload: path.join(__dirname$1, "preload.mjs"),
-      nodeIntegration: false,
-      contextIsolation: true
-    }
-  });
-  if (VITE_DEV_SERVER_URL$1) {
-    win.loadURL(VITE_DEV_SERVER_URL$1 + "?windowType=source-selector");
-  } else {
-    win.loadFile(path.join(RENDERER_DIST$1, "index.html"), {
-      query: { windowType: "source-selector" }
-    });
-  }
-  return win;
-}
-let selectedSource = null;
-function registerIpcHandlers(createEditorWindow2, createSourceSelectorWindow2, getMainWindow, getSourceSelectorWindow, onRecordingStateChange) {
-  ipcMain.handle("get-sources", async (_, opts) => {
-    const sources = await desktopCapturer.getSources(opts);
-    return sources.map((source) => ({
-      id: source.id,
-      name: source.name,
-      display_id: source.display_id,
-      thumbnail: source.thumbnail ? source.thumbnail.toDataURL() : null,
-      appIcon: source.appIcon ? source.appIcon.toDataURL() : null
-    }));
-  });
-  ipcMain.handle("select-source", (_, source) => {
-    selectedSource = source;
-    const sourceSelectorWin = getSourceSelectorWindow();
-    if (sourceSelectorWin) {
-      sourceSelectorWin.close();
-    }
-    return selectedSource;
-  });
-  ipcMain.handle("get-selected-source", () => {
-    return selectedSource;
-  });
-  ipcMain.handle("open-source-selector", () => {
-    const sourceSelectorWin = getSourceSelectorWindow();
-    if (sourceSelectorWin) {
-      sourceSelectorWin.focus();
-      return;
-    }
-    createSourceSelectorWindow2();
-  });
-  ipcMain.handle("switch-to-editor", () => {
-    const mainWin = getMainWindow();
-    if (mainWin) {
-      mainWin.close();
-    }
-    createEditorWindow2();
-  });
-  ipcMain.handle("store-recorded-video", async (_, videoData, fileName) => {
-    try {
-      const videoPath = path.join(RECORDINGS_DIR, fileName);
-      await fs.writeFile(videoPath, Buffer.from(videoData));
-      currentVideoPath = videoPath;
-      return {
-        success: true,
-        path: videoPath,
-        message: "Video stored successfully"
-      };
-    } catch (error) {
-      console.error("Failed to store video:", error);
-      return {
-        success: false,
-        message: "Failed to store video",
-        error: String(error)
-      };
-    }
-  });
-  ipcMain.handle("get-recorded-video-path", async () => {
-    try {
-      const files = await fs.readdir(RECORDINGS_DIR);
-      const videoFiles = files.filter((file) => file.endsWith(".webm"));
-      if (videoFiles.length === 0) {
-        return { success: false, message: "No recorded video found" };
-      }
-      const latestVideo = videoFiles.sort().reverse()[0];
-      const videoPath = path.join(RECORDINGS_DIR, latestVideo);
-      return { success: true, path: videoPath };
-    } catch (error) {
-      console.error("Failed to get video path:", error);
-      return { success: false, message: "Failed to get video path", error: String(error) };
-    }
-  });
-  ipcMain.handle("set-recording-state", (_, recording) => {
-    const source = selectedSource || { name: "Screen" };
-    if (onRecordingStateChange) {
-      onRecordingStateChange(recording, source.name);
-    }
-  });
-  ipcMain.handle("open-external-url", async (_, url) => {
-    try {
-      await shell.openExternal(url);
-      return { success: true };
-    } catch (error) {
-      console.error("Failed to open URL:", error);
-      return { success: false, error: String(error) };
-    }
-  });
-  ipcMain.handle("get-asset-base-path", () => {
-    try {
-      if (app.isPackaged) {
-        return path.join(process.resourcesPath, "assets");
-      }
-      return path.join(app.getAppPath(), "public", "assets");
-    } catch (err) {
-      console.error("Failed to resolve asset base path:", err);
-      return null;
-    }
-  });
-  ipcMain.handle("save-exported-video", async (_, videoData, fileName) => {
-    try {
-      const result = await dialog.showSaveDialog({
-        title: "Save Exported Video",
-        defaultPath: path.join(app.getPath("downloads"), fileName),
-        filters: [
-          { name: "MP4 Video", extensions: ["mp4"] }
-        ],
-        properties: ["createDirectory", "showOverwriteConfirmation"]
-      });
-      if (result.canceled || !result.filePath) {
-        return {
-          success: false,
-          cancelled: true,
-          message: "Export cancelled"
-        };
-      }
-      await fs.writeFile(result.filePath, Buffer.from(videoData));
-      return {
-        success: true,
-        path: result.filePath,
-        message: "Video exported successfully"
-      };
-    } catch (error) {
-      console.error("Failed to save exported video:", error);
-      return {
-        success: false,
-        message: "Failed to save exported video",
-        error: String(error)
-      };
-    }
-  });
-  ipcMain.handle("open-video-file-picker", async () => {
-    try {
-      const result = await dialog.showOpenDialog({
-        title: "Select Video File",
-        defaultPath: RECORDINGS_DIR,
-        filters: [
-          { name: "Video Files", extensions: ["webm", "mp4", "mov", "avi", "mkv"] },
-          { name: "All Files", extensions: ["*"] }
-        ],
-        properties: ["openFile"]
-      });
-      if (result.canceled || result.filePaths.length === 0) {
-        return { success: false, cancelled: true };
-      }
-      return {
-        success: true,
-        path: result.filePaths[0]
-      };
-    } catch (error) {
-      console.error("Failed to open file picker:", error);
-      return {
-        success: false,
-        message: "Failed to open file picker",
-        error: String(error)
-      };
-    }
-  });
-  let currentVideoPath = null;
-  ipcMain.handle("set-current-video-path", (_, path2) => {
-    currentVideoPath = path2;
-    return { success: true };
-  });
-  ipcMain.handle("get-current-video-path", () => {
-    return currentVideoPath ? { success: true, path: currentVideoPath } : { success: false };
-  });
-  ipcMain.handle("clear-current-video-path", () => {
-    currentVideoPath = null;
-    return { success: true };
-  });
-}
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const RECORDINGS_DIR = path.join(app.getPath("userData"), "recordings");
-async function ensureRecordingsDir() {
-  try {
-    await fs.mkdir(RECORDINGS_DIR, { recursive: true });
-    console.log("RECORDINGS_DIR:", RECORDINGS_DIR);
-    console.log("User Data Path:", app.getPath("userData"));
-  } catch (error) {
-    console.error("Failed to create recordings directory:", error);
-  }
-}
-process.env.APP_ROOT = path.join(__dirname, "..");
-const VITE_DEV_SERVER_URL = process.env["VITE_DEV_SERVER_URL"];
-const MAIN_DIST = path.join(process.env.APP_ROOT, "dist-electron");
-const RENDERER_DIST = path.join(process.env.APP_ROOT, "dist");
-process.env.VITE_PUBLIC = VITE_DEV_SERVER_URL ? path.join(process.env.APP_ROOT, "public") : RENDERER_DIST;
-let mainWindow = null;
-let sourceSelectorWindow = null;
-let tray = null;
-let selectedSourceName = "";
-function createWindow() {
-  mainWindow = createHudOverlayWindow();
-}
-function createTray() {
-  const iconPath = path.join(process.env.VITE_PUBLIC || RENDERER_DIST, "rec-button.png");
-  let icon = nativeImage.createFromPath(iconPath);
-  icon = icon.resize({ width: 24, height: 24, quality: "best" });
-  tray = new Tray(icon);
-  updateTrayMenu();
-}
-function updateTrayMenu() {
-  if (!tray) return;
-  const menuTemplate = [
-    {
-      label: "Stop Recording",
-      click: () => {
-        if (mainWindow && !mainWindow.isDestroyed()) {
-          mainWindow.webContents.send("stop-recording-from-tray");
-        }
-      }
-    }
-  ];
-  const contextMenu = Menu.buildFromTemplate(menuTemplate);
-  tray.setContextMenu(contextMenu);
-  tray.setToolTip(`Recording: ${selectedSourceName}`);
-}
-function createEditorWindowWrapper() {
-  if (mainWindow) {
-    mainWindow.close();
-    mainWindow = null;
-  }
-  mainWindow = createEditorWindow();
-}
-function createSourceSelectorWindowWrapper() {
-  sourceSelectorWindow = createSourceSelectorWindow();
-  sourceSelectorWindow.on("closed", () => {
-    sourceSelectorWindow = null;
-  });
-  return sourceSelectorWindow;
-}
-app.on("window-all-closed", () => {
-});
-app.on("activate", () => {
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow();
-  }
-});
-app.whenReady().then(async () => {
-  const { ipcMain: ipcMain2 } = await import("electron");
-  ipcMain2.on("hud-overlay-close", () => {
-    if (process.platform === "darwin") {
-      app.quit();
-    }
-  });
-  await ensureRecordingsDir();
-  registerIpcHandlers(
-    createEditorWindowWrapper,
-    createSourceSelectorWindowWrapper,
-    () => mainWindow,
-    () => sourceSelectorWindow,
-    (recording, sourceName) => {
-      selectedSourceName = sourceName;
-      if (recording) {
-        if (!tray) createTray();
-        updateTrayMenu();
-      } else {
-        if (tray) {
-          tray.destroy();
-          tray = null;
-        }
-        if (mainWindow) mainWindow.restore();
-      }
-    }
-  );
-  createWindow();
-});
-export {
-  MAIN_DIST,
-  RECORDINGS_DIR,
-  RENDERER_DIST,
-  VITE_DEV_SERVER_URL
-};

dist-electron/preload.mjs

@@ -1,60 +0,0 @@
-"use strict";
-const electron = require("electron");
-electron.contextBridge.exposeInMainWorld("electronAPI", {
-  hudOverlayHide: () => {
-    electron.ipcRenderer.send("hud-overlay-hide");
-  },
-  hudOverlayClose: () => {
-    electron.ipcRenderer.send("hud-overlay-close");
-  },
-  getAssetBasePath: async () => {
-    return await electron.ipcRenderer.invoke("get-asset-base-path");
-  },
-  getSources: async (opts) => {
-    return await electron.ipcRenderer.invoke("get-sources", opts);
-  },
-  switchToEditor: () => {
-    return electron.ipcRenderer.invoke("switch-to-editor");
-  },
-  openSourceSelector: () => {
-    return electron.ipcRenderer.invoke("open-source-selector");
-  },
-  selectSource: (source) => {
-    return electron.ipcRenderer.invoke("select-source", source);
-  },
-  getSelectedSource: () => {
-    return electron.ipcRenderer.invoke("get-selected-source");
-  },
-  storeRecordedVideo: (videoData, fileName) => {
-    return electron.ipcRenderer.invoke("store-recorded-video", videoData, fileName);
-  },
-  getRecordedVideoPath: () => {
-    return electron.ipcRenderer.invoke("get-recorded-video-path");
-  },
-  setRecordingState: (recording) => {
-    return electron.ipcRenderer.invoke("set-recording-state", recording);
-  },
-  onStopRecordingFromTray: (callback) => {
-    const listener = () => callback();
-    electron.ipcRenderer.on("stop-recording-from-tray", listener);
-    return () => electron.ipcRenderer.removeListener("stop-recording-from-tray", listener);
-  },
-  openExternalUrl: (url) => {
-    return electron.ipcRenderer.invoke("open-external-url", url);
-  },
-  saveExportedVideo: (videoData, fileName) => {
-    return electron.ipcRenderer.invoke("save-exported-video", videoData, fileName);
-  },
-  openVideoFilePicker: () => {
-    return electron.ipcRenderer.invoke("open-video-file-picker");
-  },
-  setCurrentVideoPath: (path) => {
-    return electron.ipcRenderer.invoke("set-current-video-path", path);
-  },
-  getCurrentVideoPath: () => {
-    return electron.ipcRenderer.invoke("get-current-video-path");
-  },
-  clearCurrentVideoPath: () => {
-    return electron.ipcRenderer.invoke("clear-current-video-path");
-  }
-});

docs/architecture/native-bridge.md

@@ -0,0 +1,39 @@
+# Native Bridge Architecture
+
+## Goal
+
+Provide a single, resilient source of truth for platform-native capabilities while keeping Electron transport thin and renderer APIs unified.
+
+## Layers
+
+1. Native adapters
+Platform-specific providers implement stable domain interfaces such as cursor telemetry or system asset discovery.
+
+2. Main-process services
+Services orchestrate adapters, own runtime state, and expose domain-level operations.
+
+3. Unified IPC transport
+Renderer code talks to a single `native-bridge:invoke` channel using versioned contracts.
+
+4. Renderer client
+React code should consume `src/native/client.ts` rather than binding directly to ad hoc Electron APIs.
+
+## Principles
+
+- Single source of truth: runtime-native state lives in the Electron main process.
+- Capability-first: renderer can query support before attempting native behavior.
+- Versioned contracts: requests and responses are explicit and evolve predictably.
+- Resilience: every response uses a consistent result envelope with stable error codes.
+
+## Current rollout
+
+This repository now contains the initial scaffold:
+
+- shared contracts in `src/native/contracts.ts`
+- renderer SDK in `src/native/client.ts`
+- main-process state store in `electron/native-bridge/store.ts`
+- cursor telemetry adapter in `electron/native-bridge/cursor/telemetryCursorAdapter.ts`
+- domain services in `electron/native-bridge/services/*`
+- unified handler registration in `electron/ipc/nativeBridge.ts`
+
+The legacy `window.electronAPI` surface still exists for backward compatibility. New native-facing features should prefer the unified bridge client.

docs/engineering/macos-native-recorder-roadmap.md

@@ -0,0 +1,210 @@
+# macOS Native Recorder Roadmap
+
+OpenScreen's macOS recorder should follow the same architecture boundaries as the Windows native recorder: Electron owns session orchestration and persistence, while a platform-native helper owns capture, timing, encoding, and platform-specific permissions.
+
+This work is intentionally scoped as a macOS-only port. Windows native capture remains owned by the WGC helper, and Linux remains on the existing Electron path.
+
+## Goals
+
+- Capture displays and windows through ScreenCaptureKit.
+- Exclude the real system cursor during capture when using the editable OpenScreen cursor overlay.
+- Preserve the current high-quality cursor overlay path in preview and export.
+- Capture macOS system audio through ScreenCaptureKit on supported macOS versions.
+- Capture microphone audio through the same native timing domain where the OS supports it, or through an explicit companion path until it can be moved into the helper.
+- Mix system audio and microphone audio into the primary MP4 without renderer-side track assembly.
+- Capture webcam video natively and compose it into the helper-owned MP4 during the native-recording migration.
+- Keep screen video, audio, webcam, and cursor aligned to one native timing origin.
+- Package per-architecture helper binaries with macOS builds.
+
+## Non-Goals
+
+- Replacing the editor/export pipeline.
+- Changing Windows native capture behavior.
+- Adding Linux native capture.
+- Shipping a silent fallback from native macOS capture to Electron capture when the user explicitly requested a native-only feature.
+
+## Architecture
+
+The renderer keeps the existing recording controls. On macOS, `useScreenRecorder` should eventually send a complete recording request to Electron instead of assembling display, audio, microphone, webcam, and cursor streams in the browser.
+
+Electron owns the native recording session:
+
+- resolves the selected display/window source;
+- resolves output paths;
+- starts cursor telemetry capture when editable cursor mode is selected;
+- starts the ScreenCaptureKit helper process;
+- sends pause/resume/stop/cancel commands;
+- writes `RecordingSession` manifests;
+- reports explicit errors when a macOS-native capability is unavailable.
+
+The helper owns macOS media capture:
+
+- ScreenCaptureKit display/window frames;
+- ScreenCaptureKit system audio where supported;
+- microphone capture or helper-owned companion audio capture;
+- webcam capture and initial picture-in-picture composition;
+- AVFoundation/VideoToolbox encoding and muxing;
+- stream timestamp normalization.
+
+## Helper Contract V1
+
+The helper receives a single JSON argument:
+
+```json
+{
+  "schemaVersion": 1,
+  "recordingId": 1234567890,
+  "source": {
+    "type": "display",
+    "sourceId": "screen:0:0",
+    "displayId": 1,
+    "windowId": null,
+    "bounds": { "x": 0, "y": 0, "width": 1920, "height": 1080 }
+  },
+  "video": {
+    "fps": 60,
+    "width": 1920,
+    "height": 1080,
+    "bitrate": 18000000,
+    "hideSystemCursor": true
+  },
+  "audio": {
+    "system": { "enabled": true },
+    "microphone": {
+      "enabled": true,
+      "deviceId": "default",
+      "deviceName": "MacBook Pro Microphone",
+      "gain": 1.4
+    }
+  },
+  "webcam": {
+    "enabled": true,
+    "deviceId": "default",
+    "deviceName": "FaceTime HD Camera",
+    "width": 1280,
+    "height": 720,
+    "fps": 30
+  },
+  "cursor": {
+    "mode": "editable-overlay"
+  },
+  "outputs": {
+    "screenPath": "/Users/me/Library/Application Support/openscreen/recordings/recording-123.mp4",
+    "manifestPath": "/Users/me/Library/Application Support/openscreen/recordings/recording-123.session.json"
+  }
+}
+```
+
+The helper emits newline-delimited JSON events to stdout:
+
+```json
+{ "event": "ready", "schemaVersion": 1 }
+{ "event": "recording-started", "timestampMs": 1234567890 }
+{ "event": "warning", "code": "microphone-unavailable", "message": "..." }
+{ "event": "recording-stopped", "screenPath": "..." }
+{ "event": "error", "code": "screen-permission-denied", "message": "..." }
+```
+
+## Implementation Phases
+
+Current PR status: macOS screen/window capture routes through the ScreenCaptureKit helper when it is available so editable-cursor recordings can hide the system cursor. The helper now writes ScreenCaptureKit system audio into the primary MP4 and attempts runtime-gated native microphone capture on macOS versions that expose ScreenCaptureKit microphone output. Webcam capture is currently an Electron-recorded sidecar attached to the same recording session; native AVFoundation webcam composition remains the target end state.
+
+### 1. Native Session Boundary
+
+- Add a structured macOS native recording request type.
+- Add a macOS helper resolver and build script placeholders.
+- Keep the helper contract process-based, matching the Windows helper boundary.
+- Do not route production macOS recording through this helper until the helper is available and validated.
+
+Acceptance:
+
+- TypeScript build passes.
+- The macOS helper path and request contract are documented and testable without affecting Windows/Linux behavior.
+
+### 2. ScreenCaptureKit Display Capture
+
+- Implement a Swift helper using ScreenCaptureKit.
+- Select display captures by `displayId`.
+- Encode H.264 MP4 through AVFoundation/VideoToolbox.
+- Set `showsCursor = false` when editable cursor overlay mode is selected.
+
+Acceptance:
+
+- Display-only recording produces a valid MP4.
+- The real cursor is not baked into editable-cursor recordings.
+
+### 3. ScreenCaptureKit Window Capture
+
+- Resolve Electron `window:*` selections to ScreenCaptureKit window ids.
+- Capture `SCContentFilter(desktopIndependentWindow:)`.
+- Handle closed/minimized/protected windows with explicit errors.
+- Keep window selection and capture source resolution in Electron/main, not the renderer.
+
+Acceptance:
+
+- Capturing a normal app window works with cursor/audio/webcam disabled.
+- Unsupported windows return clear native errors.
+
+### 4. System Audio
+
+- Enable ScreenCaptureKit system audio on supported macOS versions.
+- Keep audio format and timing owned by the helper.
+- Encode or mux AAC audio into the primary MP4.
+
+Acceptance:
+
+- System-audio-only recordings produce a valid AAC track.
+- Unsupported macOS versions return an explicit capability error.
+
+### 5. Microphone
+
+- Resolve the selected microphone device from the renderer-provided browser `deviceId` and user-visible label.
+- Capture microphone audio in the helper timing domain.
+- Apply OpenScreen microphone gain policy.
+- Mix system and microphone audio before final AAC output.
+
+Acceptance:
+
+- Mic-only and mic-plus-system recordings produce a valid, balanced AAC track.
+- Device selection honors the selected microphone, not only the default device.
+
+### 6. Webcam Composition
+
+- Capture the selected camera natively through AVFoundation.
+- Match browser device id first where possible, then user-visible label.
+- Compose an initial picture-in-picture overlay into the primary MP4.
+- Hide webcam output until the first usable frame to avoid black startup flashes.
+
+Acceptance:
+
+- Native display/window recordings can include webcam without returning to Electron capture.
+- Selected camera is honored.
+
+### 7. Runtime Controls
+
+- Add pause/resume commands to the helper.
+- Add cancel command that removes partial outputs.
+- Keep restart as stop-discard-start until the helper exposes a native restart operation.
+
+Acceptance:
+
+- Pause/resume keeps output duration coherent.
+- Cancel leaves no stale media/session files.
+
+### 8. Test Pipeline
+
+- `npm run build:native:mac`: builds Swift helper binaries on macOS.
+- `npm run test:sck-helper:mac`: display-only helper smoke test.
+- `npm run test:sck-window:mac`: window capture smoke test.
+- `npm run test:sck-audio:mac`: system audio smoke test when supported.
+- `npm run test:sck-mic:mac`: microphone smoke test.
+- `npm run test:sck-webcam:mac`: webcam smoke test when a webcam is available.
+- Packaging check: confirms helpers are available under `electron/native/bin/darwin-${arch}` in packaged builds.
+
+## SSOT Rules
+
+- `src/lib/nativeMacRecording.ts` is the renderer/main TypeScript request contract.
+- This document is the feature-level contract and phase checklist.
+- The Swift helper owns ScreenCaptureKit/AVFoundation media timing.
+- Electron owns output paths, session manifests, and selected source/device resolution.
+- Renderer code must use existing hooks/client APIs and should not bind directly to helper process details.

docs/engineering/windows-native-recorder-roadmap.md

@@ -0,0 +1,248 @@
+# Windows Native Recorder Roadmap
+
+OpenScreen's Windows recorder should be owned by one native backend. Electron capture can remain available for non-Windows platforms and temporary developer diagnostics, but Windows production recording should not silently fall back to `getDisplayMedia` / `MediaRecorder`.
+
+## Goals
+
+- Capture displays and windows through Windows Graphics Capture (WGC).
+- Render the native Windows cursor as OpenScreen's high-quality scalable cursor overlay.
+- Capture system audio through WASAPI loopback.
+- Capture microphone audio through WASAPI.
+- Mix system audio and microphone audio into the primary screen recording.
+- Capture webcam video natively and compose it into the Windows helper MP4 during the native-recording migration.
+- Keep preview/export aligned because screen video, audio, webcam, and cursor share one native timing origin.
+- Keep exported MP4s Windows-friendly: H.264 video plus AAC audio. Opus-in-MP4 is not an acceptable Windows export target.
+- Package the native helper with the Windows app.
+
+## Non-Goals
+
+- Replacing the editor/export pipeline.
+- Replacing the editor/export pipeline. A later pass can reintroduce a separate editable native `webcamVideoPath`; the current Windows-native milestone prioritizes a helper-owned multi-flux MP4 with deterministic screen/audio/mic/webcam sync.
+- Adding a native fallback for macOS or Linux in this branch.
+
+## Target Architecture
+
+The renderer keeps the existing recording controls. On Windows, `useScreenRecorder` sends a complete recording request to Electron and does not assemble Windows `MediaStream` tracks with `MediaRecorder`.
+
+Electron owns the native recording session:
+
+- resolves the selected source;
+- resolves output paths;
+- starts cursor sampling;
+- starts the helper process;
+- sends pause/resume/stop/cancel commands;
+- writes `RecordingSession` manifests;
+- reports explicit errors when a Windows-native capability is unavailable.
+
+The helper owns Windows media capture:
+
+- WGC screen/window frames;
+- WASAPI system loopback;
+- WASAPI microphone input;
+- Media Foundation webcam capture;
+- DirectShow webcam fallback for virtual cameras not visible to Media Foundation;
+- Media Foundation encoding/muxing;
+- stream timestamp normalization.
+
+## Helper Contract V2
+
+The helper receives a single JSON argument:
+
+```json
+{
+  "schemaVersion": 2,
+  "recordingId": 1234567890,
+  "source": {
+    "type": "display",
+    "sourceId": "screen:0:0",
+    "displayId": 123,
+    "windowHandle": null,
+    "bounds": { "x": 0, "y": 0, "width": 1920, "height": 1080 }
+  },
+  "video": {
+    "fps": 60,
+    "width": 1920,
+    "height": 1080,
+    "bitrate": 18000000
+  },
+  "audio": {
+    "system": { "enabled": true },
+    "microphone": { "enabled": true, "deviceId": "default", "gain": 1.4 }
+  },
+  "webcam": {
+    "enabled": true,
+    "deviceId": "default",
+    "deviceName": "Camera (NVIDIA Broadcast)",
+    "width": 1280,
+    "height": 720,
+    "fps": 30,
+    "bitrate": 18000000
+  },
+  "outputs": {
+    "screenPath": "C:\\Users\\me\\recording-123.mp4",
+    "manifestPath": "C:\\Users\\me\\recording-123.session.json"
+  }
+}
+```
+
+The helper emits newline-delimited JSON events to stdout:
+
+```json
+{ "event": "ready", "schemaVersion": 2 }
+{ "event": "recording-started", "timestampMs": 1234567890 }
+{ "event": "warning", "code": "audio-device-unavailable", "message": "..." }
+{ "event": "recording-stopped", "screenPath": "..." }
+{ "event": "error", "code": "unsupported-window-source", "message": "..." }
+```
+
+During migration, Electron also accepts the current textual helper messages so existing display-only smoke tests keep working.
+
+## Implementation Phases
+
+### 1. Native Session Boundary
+
+- Add a structured Windows native recording request type.
+- Pass source kind, audio flags, microphone device, webcam flags, and output paths into the helper.
+- On Windows, do not silently fall back to Electron capture. If the helper is unavailable or a native feature is missing, show a clear error.
+- Keep Electron fallback only for non-Windows and optional developer diagnostics.
+
+Acceptance:
+
+- Display-only recording still works.
+- Enabling an unsupported native feature returns an explicit native error instead of recording through Electron.
+
+### 2. WASAPI System Audio
+
+Status: initial implementation landed. The helper captures the default render endpoint with WASAPI loopback, passes the runtime mix format into `MFEncoder`, and muxes AAC audio into the primary MP4. Long-run drift correction and explicit silence insertion remain follow-up hardening work.
+
+- Add `WasapiLoopbackCapture`.
+- Capture the default render endpoint in shared loopback mode.
+- Keep `WasapiLoopbackCapture` responsible only for device activation, packet capture, and packet timestamps.
+- Keep `MFEncoder` responsible for all Media Foundation stream definitions and muxing.
+- Feed the endpoint mix format into `MFEncoder` as the single source of truth for audio stream shape: sample rate, channel count, bits per sample, block alignment, average bytes/sec, and subtype (`PCM` or `Float`).
+- Encode the primary screen MP4 with H.264 video and AAC audio through one `IMFSinkWriter`.
+- Timestamp audio from the captured frame count in 100ns units. The first implementation uses the WASAPI packet timeline; later drift correction will add explicit silence or resampling if long recordings show measurable clock skew.
+- Treat microphone mixing as a later phase. System loopback must land first without introducing renderer-side audio code.
+
+Acceptance:
+
+- Screen MP4 has an AAC audio track when system audio is enabled.
+- A 5-minute recording has audio/video duration drift below one frame.
+
+SSOT rules for this phase:
+
+- `src/lib/nativeWindowsRecording.ts` is the renderer/main TypeScript request contract.
+- `docs/engineering/windows-native-recorder-roadmap.md` is the feature-level contract and phase checklist.
+- `WgcSession::captureWidth()/captureHeight()` is the encoded screen frame size until a dedicated native scaling stage exists.
+- `WasapiLoopbackCapture::inputFormat()` is the runtime audio format source used by `MFEncoder`.
+- The renderer passes both the browser webcam `deviceId` and selected display label as `deviceName`; `electron/native/wgc-capture/src/webcam_capture.*` is the only place that maps those values to Media Foundation devices.
+- Electron resolves the selected label to a DirectShow filter CLSID once and passes it as `webcamDirectShowClsid`; the helper must not independently guess among DirectShow filters.
+- No duplicated hard-coded audio format assumptions in `main.cpp`.
+
+### 3. WASAPI Microphone
+
+Status: initial implementation in progress. The helper can open the default WASAPI capture endpoint, apply the OpenScreen microphone gain, encode mic-only audio, and mix system loopback plus microphone through a single queued `AudioMixer` timeline when both endpoints expose the same runtime format. Audio endpoints are warmed before WGC starts, the mixer drops pre-roll and begins its paced timeline on the first encoded video frame, then cuts queued tail audio on stop so the MP4 does not drift past the video. Browser `deviceId` to MMDevice id mapping, resampling between mismatched endpoint formats, and drift correction remain follow-up hardening work.
+
+- Add microphone device enumeration and stable device-id mapping.
+- Capture selected/default microphone through WASAPI.
+- Apply OpenScreen's current mic gain policy.
+- Mix microphone and system audio before AAC encoding.
+
+Acceptance:
+
+- Mic-only, system-only, and mixed audio recordings produce a valid AAC track.
+- Device unplug/permission failure produces an explicit error or warning.
+
+### 4. Webcam Capture
+
+- Add Media Foundation webcam source reader.
+- Select requested dimensions/fps or the nearest format accepted by Media Foundation.
+- Convert webcam samples to BGRA and compose them into the primary helper MP4 as an initial bottom-right picture-in-picture overlay.
+- Ignore black webcam warmup frames and keep the overlay hidden until the first visible frame is available, so virtual cameras do not flash a black picture-in-picture rectangle at recording start.
+- Keep the helper process as the SSOT for screen/window, WASAPI system audio, microphone, webcam, and mux timing.
+- Match the requested webcam through Media Foundation friendly names first, then browser device ids/symbolic links, so UI selection remains stable across Chromium and Windows native device namespaces.
+- Use the Electron-resolved DirectShow CLSID when the selected virtual camera, for example NVIDIA Broadcast, is registered for DirectShow but absent from Media Foundation enumeration.
+- Later: promote the same webcam capture source to a separate editable native `webcamVideoPath` if product requirements need post-recording layout edits.
+
+Acceptance:
+
+- Native display/window recordings can include webcam without returning to Electron capture.
+- `npm run test:wgc-webcam:win` validates the helper path when a webcam is available and skips explicitly when no webcam device exists.
+- Combined webcam + system audio + microphone produces one MP4 with H.264 video and AAC audio.
+
+### 5. Native Window Capture
+
+Status: initial implementation in progress. Electron parses the `window:<HWND>:...` desktop source id through the shared native Windows recording contract and passes `windowHandle` to the helper. The helper resolves the `HWND`, validates it with `IsWindow`, and creates the WGC item with `CreateForWindow(HWND)`. Resize/minimize/move hardening and protected-window diagnostics remain follow-up work.
+
+- Resolve Electron `window:*` selections to an `HWND`.
+- Use WGC `CreateForWindow(HWND)`.
+- Handle window close, minimize, resize, DPI scaling, and monitor moves.
+- Return clear errors for unsupported protected windows.
+
+Acceptance:
+
+- Capturing a normal app window works with cursor/audio/mic/webcam.
+- Window resize and movement do not corrupt the recording.
+
+### 6. Runtime Controls
+
+- Add pause/resume commands to the helper.
+- Add cancel command that removes partial screen/webcam outputs.
+- Keep restart as stop-discard-start from Electron until the helper supports a native restart event.
+
+Acceptance:
+
+- Pause/resume keeps preview duration coherent.
+- Cancel leaves no stale media/session/cursor files.
+
+### 7. Test Pipeline
+
+- `npm run test:wgc-helper:win`: display-only helper smoke test.
+- `npm run test:wgc-audio:win`: validates AAC track presence and duration.
+- `npm run test:wgc-window:win`: captures a fixture window by HWND.
+- `npm run test:wgc-webcam:win`: validates webcam output when a webcam is available, otherwise skips explicitly.
+- Packaging check: confirms the helper is in `app.asar.unpacked`.
+- Export check: exported MP4s generated from native recordings keep an AAC audio track when the source has audio.
+- `npm run test:wgc-mic:win`: validates default-microphone capture writes an AAC track when an input endpoint is available.
+- `npm run test:wgc-mixed-audio:win`: validates system loopback plus microphone writes one mixed AAC track when endpoint formats are compatible.
+
+## Backlog
+
+### Native Cursor Click Bounce Is Not Visibly Applied
+
+Status: open. Do not treat Windows native cursor `Click Bounce` as shipped.
+
+Problem:
+
+- The cursor settings UI exposes `Size`, `Smoothing`, `Motion Blur`, and `Click Bounce`.
+- On Windows native cursor recordings, `Size`, `Smoothing`, and `Motion Blur` are visibly applied in preview/export.
+- `Click Bounce` still has no visible effect in manual packaged-app testing, even after adding click-related sample metadata.
+
+What has already been tried:
+
+- Added `interactionType: "click" | "mouseup" | "move"` to native cursor samples.
+- Added polling-based left-button state through `GetAsyncKeyState`.
+- Added the `GetAsyncKeyState` low-bit path to catch quick clicks between samples.
+- Added a PowerShell/C# `WH_MOUSE_LL` mouse hook experiment and launched the sampler through a temporary `.ps1` file to avoid Windows command-line length limits.
+- Updated `npm run test:cursor-native:win` so the diagnostic can observe a synthetic short click and emit `clickSampleCount`.
+
+Current diagnosis:
+
+- The diagnostic can observe synthetic click events, but this has not translated into a visible `Click Bounce` effect in the real packaged app.
+- The test currently proves that some click metadata can be recorded, not that the full OpenScreen record -> preview -> export path displays a bounce at the expected time.
+- The current native implementation may be animating from metadata that is not present in the real recording session, may be using the wrong timestamp origin, or may be applying a scale change too subtle to notice on the DOM/native cursor path.
+
+Next investigation when resumed:
+
+- Inspect the actual `.cursor.json`/session sidecar generated by a packaged-app manual recording and confirm whether real clicks produce `interactionType: "click"` at the right `timeMs`.
+- Add a targeted end-to-end fixture that records a known click, loads the generated project, and asserts the preview/export cursor scale changes across adjacent frames.
+- Compare the native DOM cursor path against the older `PixiCursorOverlay` click visual state and decide whether native cursor bounce should be a scale-only animation, an additional click ring, or a short explicit keyframe animation independent of sample cadence.
+- If event capture remains unreliable in the PowerShell sampler, move click events into a small native cursor helper instead of PowerShell/C# script injection.
+
+## Ship Criteria
+
+- Windows display capture works with cursor, system audio, microphone, and webcam.
+- Windows window capture works with cursor, system audio, microphone, and webcam.
+- Preview and export show no cursor position drift.
+- Preview and export show no measurable audio/video/webcam drift.
+- Windows production builds do not depend on Electron capture fallback.

docs/testing/windows-native-cursor.md

@@ -0,0 +1,130 @@
+# Windows native cursor test pipeline
+
+This branch includes two Windows-focused diagnostics for fast iteration on native cursor capture and rendering. They are intentionally local developer tools: they create short videos and JSON reports so cursor changes can be inspected without doing a full manual record/edit/export cycle.
+
+## Native sampler diagnostic
+
+```powershell
+npm run test:cursor-native:win
+```
+
+This script does not launch OpenScreen. It:
+
+- starts a Windows `GetCursorInfo` sampler
+- moves the real OS pointer with `SetCursorPos`
+- captures native cursor handles, hotspots, assets, and standard `IDC_*` cursor types
+- writes normalized `CursorRecordingData`
+- generates an abstract preview video
+- generates a real-screen preview video using screenshots of the current desktop
+
+The output directory is printed in the command result, for example:
+
+```text
+C:\Users\<user>\AppData\Local\Temp\openscreen-cursor-native-...
+```
+
+Useful files:
+
+- `report.json`: sample counts, asset counts, cursor handles, and generated artifact paths
+- `cursor-recording-data.json`: sidecar-compatible cursor data
+- `preview.webm`: abstract path/asset/hotspot preview
+- `real-capture-preview.webm`: real desktop screenshot background with reconstructed cursor overlay
+- `assets/*.png`: raw cursor bitmaps captured from Windows
+
+Environment overrides:
+
+```powershell
+$env:CURSOR_TEST_DURATION_MS = "3000"
+$env:CURSOR_TEST_SAMPLE_INTERVAL_MS = "16"
+$env:CURSOR_TEST_SCREEN_FRAME_INTERVAL_MS = "80"
+$env:CURSOR_TEST_OUTPUT_DIR = "C:\temp\openscreen-cursor-test"
+npm run test:cursor-native:win
+```
+
+## OpenScreen preview capture
+
+```powershell
+npm run capture:openscreen-preview
+```
+
+This script launches the real Electron app, injects a fixture video plus cursor sidecar data, opens the editor, captures frames from the actual OpenScreen preview UI, and encodes them into a WebM.
+
+By default it uses the latest `cursor-recording-data.json` generated by `npm run test:cursor-native:win`. To force a specific sidecar:
+
+```powershell
+$env:CURSOR_RECORDING_DATA_PATH = "C:\path\to\cursor-recording-data.json"
+npm run capture:openscreen-preview
+```
+
+Useful environment overrides:
+
+```powershell
+$env:OPENSCREEN_PREVIEW_SKIP_BUILD = "true"
+$env:OPENSCREEN_PREVIEW_FRAME_COUNT = "120"
+$env:OPENSCREEN_PREVIEW_FPS = "30"
+$env:OPENSCREEN_PREVIEW_OUTPUT_DIR = "C:\temp\openscreen-preview"
+npm run capture:openscreen-preview
+```
+
+Useful files:
+
+- `openscreen-preview.webm`: video of the real OpenScreen editor preview
+- `frames/*.png`: captured preview frames
+- `report.json`: fixture paths, source sidecar, frame count, and output path
+
+## What these tests validate
+
+Together, the scripts make it quick to inspect:
+
+- whether Windows cursor samples are visible and continuous
+- whether native hotspots stay anchored when scaling to `3x`
+- whether standard Windows cursors are recognized via `IDC_*`
+- whether high-quality SVG cursor replacements follow the native hotspot
+- whether the real OpenScreen preview renders the same cursor behavior as the diagnostic pipeline
+
+They are not a full substitute for an end-to-end manual recording pass. Before shipping cursor changes, also test a real capture session and export from the packaged app.
+
+## Known Gap
+
+Windows native cursor `Click Bounce` is currently backlogged. `Size`, `Smoothing`, and `Motion Blur` can be validated through preview/export, but `Click Bounce` has not shown a visible effect in packaged-app manual testing. The current diagnostic can observe synthetic click metadata, but that is not enough to validate the real OpenScreen record -> preview -> export path.
+
+Track the open item in `docs/engineering/windows-native-recorder-roadmap.md` under `Native Cursor Click Bounce Is Not Visibly Applied`.
+
+## Native Windows capture backend
+
+The app now routes Windows recordings through an external WGC helper instead of Electron `getDisplayMedia`. This is meant to remove the coordinate and clock split that made the reconstructed cursor drift in the preview/export path.
+
+Current native availability rules:
+
+- Windows 10 build 19041 or newer
+- a helper executable is available
+
+The helper currently implements display/window video capture, system audio loopback, default microphone capture, Media Foundation webcam capture, and DirectShow fallback for selected virtual cameras such as NVIDIA Broadcast. Webcam frames are composed into the primary MP4 as a bottom-right picture-in-picture overlay, and black webcam warmup frames are ignored until the first visible frame is available.
+
+Build OpenScreen's helper locally:
+
+```powershell
+npm run build:native:win
+```
+
+Smoke-test the helper directly:
+
+```powershell
+npm run test:wgc-helper:win
+npm run test:wgc-helper:win -- --capture-cursor
+npm run test:wgc-window:win
+npm run test:wgc-audio:win
+npm run test:wgc-mic:win
+npm run test:wgc-mixed-audio:win
+npm run test:wgc-webcam:win
+```
+
+For local diagnostics with another compatible helper, point OpenScreen at that executable:
+
+```powershell
+$env:OPENSCREEN_WGC_CAPTURE_EXE = "C:\path\to\wgc-capture.exe"
+npm run build-vite
+npm run dev
+```
+
+The helper receives one JSON config argument, emits JSON lifecycle events, prints the legacy `Recording started` marker, accepts `stop` on stdin, and prints `Recording stopped. Output path: <path>`. See `electron/native/README.md` for the exact contract and build output paths.

docs/tests/writing-tests.md

@@ -0,0 +1,149 @@
+# Writing Tests
+
+This project uses [Vitest](https://vitest.dev/) for both unit/integration tests and browser tests. There are two separate configs — each targets a different set of files.
+
+## Unit tests
+
+**Config:** `vitest.config.ts`  
+**Runs in:** jsdom (simulated DOM, no real browser)  
+**File pattern:** `src/**/*.test.ts` — anything that does **not** end in `.browser.test.ts`  
+**CI command:** `npm run test`
+
+Use unit tests for pure logic, utility functions, data transformations, and anything that doesn't need real browser APIs (Canvas, WebCodecs, MediaRecorder, etc.).
+
+### File placement
+
+Co-locate the test file next to the source file, or put it in a `__tests__/` folder in the same directory.
+
+```
+src/lib/compositeLayout.ts
+src/lib/compositeLayout.test.ts        # co-located
+
+src/i18n/__tests__/tutorialHelpTranslations.test.ts  # grouped
+```
+
+### Example
+
+```ts
+import { describe, expect, it } from "vitest";
+import { computeCompositeLayout } from "./compositeLayout";
+
+describe("computeCompositeLayout", () => {
+  it("anchors the overlay in the lower-right corner", () => {
+    const layout = computeCompositeLayout({
+      canvasSize: { width: 1920, height: 1080 },
+      screenSize: { width: 1920, height: 1080 },
+      webcamSize: { width: 1280, height: 720 },
+    });
+
+    expect(layout).not.toBeNull();
+    expect(layout!.webcamRect!.x).toBeGreaterThan(1920 / 2);
+    expect(layout!.webcamRect!.y).toBeGreaterThan(1080 / 2);
+  });
+});
+```
+
+### Path aliases
+
+The `@/` alias resolves to `src/`. Use it for imports that would otherwise need long relative paths.
+
+```ts
+import { SUPPORTED_LOCALES } from "@/i18n/config";
+```
+
+### Running locally
+
+```bash
+npm run test          # run once
+npm run test:watch    # watch mode
+```
+
+---
+
+## Browser tests
+
+**Config:** `vitest.browser.config.ts`  
+**Runs in:** real Chromium via Playwright (headless)  
+**File pattern:** `src/**/*.browser.test.ts`  
+**CI commands:** `npm run test:browser:install` then `npm run test:browser`
+
+Use browser tests when the code under test depends on real browser APIs that jsdom doesn't implement: `VideoDecoder`, `VideoEncoder`, `MediaRecorder`, `OffscreenCanvas`, `WebGL`, etc.
+
+### File placement
+
+Name the file `<subject>.browser.test.ts` and place it next to the source file.
+
+```
+src/lib/exporter/videoExporter.ts
+src/lib/exporter/videoExporter.browser.test.ts
+```
+
+### Loading fixture assets
+
+Static assets (video files, images) live in `tests/fixtures/`. Import them with Vite's `?url` suffix so Vite serves them through the dev server.
+
+```ts
+import sampleVideoUrl from "../../../tests/fixtures/sample.webm?url";
+```
+
+### Example
+
+```ts
+import { describe, expect, it } from "vitest";
+import sampleVideoUrl from "../../../tests/fixtures/sample.webm?url";
+import { VideoExporter } from "./videoExporter";
+
+describe("VideoExporter (real browser)", () => {
+  it("exports a valid MP4 blob from a real video", async () => {
+    const exporter = new VideoExporter({
+      videoUrl: sampleVideoUrl,
+      width: 320,
+      height: 180,
+      frameRate: 15,
+      bitrate: 1_000_000,
+      wallpaper: "#1a1a2e",
+      zoomRegions: [],
+      showShadow: false,
+      shadowIntensity: 0,
+      showBlur: false,
+      cropRegion: { x: 0, y: 0, width: 1, height: 1 },
+    });
+
+    const result = await exporter.export();
+
+    expect(result.success, result.error).toBe(true);
+    expect(result.blob).toBeInstanceOf(Blob);
+  });
+});
+```
+
+### Timeouts
+
+Browser tests have a default timeout of 120 seconds per test and 30 seconds per hook (set in `vitest.browser.config.ts`). Export operations are slow — prefer small fixture dimensions (320×180) and low bitrates to keep tests fast.
+
+### Running locally
+
+First install the browser (one-time):
+
+```bash
+npm run test:browser:install
+```
+
+Then run the tests:
+
+```bash
+npm run test:browser
+```
+
+---
+
+## Choosing the right type
+
+| Situation | Use |
+|---|---|
+| Pure function / data transformation | Unit test |
+| i18n key coverage | Unit test |
+| React hook logic (no real browser APIs) | Unit test |
+| `VideoDecoder` / `VideoEncoder` / `MediaRecorder` | Browser test |
+| `OffscreenCanvas` / WebGL / Pixi.js rendering | Browser test |
+| File export producing a real `Blob` | Browser test |

electron-builder.json5

@@ -3,10 +3,14 @@
   "$schema": "https://raw.githubusercontent.com/electron-userland/electron-builder/master/packages/app-builder-lib/scheme.json",
   "appId": "com.siddharthvaddem.openscreen",
   "asar": true,
+  // .node binaries can't be dlopen'd from inside an asar — must live unpacked.
+  "asarUnpack": [
+    "**/*.node"
+  ],
   "productName": "Openscreen",
   "npmRebuild": true,
   "buildDependenciesFromSource": true,
-  "compression": "maximum",
+  "compression": "normal",
   "directories": {
     "output": "release/${version}"
   },
@@ -20,14 +24,20 @@
     "!CONTRIBUTING.md",
     "!LICENSE"
   ],
+  // Asset layout contract: "wallpapers/" under resourcesPath must align with
+  // assetBaseDir in electron/preload.ts (packaged branch).
   "extraResources": [
     {
       "from": "public/wallpapers",
-      "to": "assets/wallpapers"
+      "to": "wallpapers"
     }
   ],
 
   "mac": {
+    "notarize": false,
+    "hardenedRuntime": true,
+    "entitlements": "macos.entitlements",
+    "entitlementsInherit": "macos.entitlements",
     "target": [
       {
         "target": "dmg",
@@ -35,18 +45,47 @@
       }
     ],
     "icon": "icons/icons/mac/icon.icns",
-    "artifactName": "${productName}-Mac-${arch}-${version}-Installer.${ext}"
+    "artifactName": "${productName}-Mac-${arch}-${version}-Installer.${ext}",
+    "extraResources": [
+      {
+        "from": "electron/native/bin",
+        "to": "electron/native/bin",
+        "filter": ["darwin-*/*"]
+      }
+    ],
+    "extendInfo": {
+      "NSAudioCaptureUsageDescription": "OpenScreen needs audio capture permission to record system audio.",
+      "NSMicrophoneUsageDescription": "OpenScreen needs microphone access to record voice audio.",
+      "NSCameraUsageDescription": "OpenScreen needs camera access to record webcam video.",
+      "NSScreenCaptureUsageDescription": "OpenScreen needs screen recording permission to detect and capture windows.",
+      "NSCameraUseContinuityCameraDeviceType": true
+    }
   },
   "linux": {
     "target": [
-      "AppImage"
+      "AppImage",
+      "deb",
+      "pacman"
     ],
-    "artifactName": "${productName}-Linux-${version}.${ext}"
+    "icon": "icons/icons/png",
+    "artifactName": "${productName}-Linux-${version}.${ext}",
+    "category": "AudioVideo"
   },
   "win": {
     "target": [
       "nsis"
     ],
-    "icon": "icons/icons/win/icon.ico"
+    "icon": "icons/icons/win/icon.ico",
+    "extraResources": [
+      {
+        "from": "electron/native/bin",
+        "to": "electron/native/bin",
+        "filter": ["win32-*/*"]
+      }
+    ]
+  },
+  "nsis": {
+    "oneClick": false,
+    "allowToChangeInstallationDirectory": true
   }
 }

electron/electron-env.d.ts

@@ -1,53 +1,278 @@
-/// <reference types="vite-plugin-electron/electron-env" />
-
-declare namespace NodeJS {
-  interface ProcessEnv {
-    /**
-     * The built directory structure
-     *
-     * ```tree
-     * ├─┬─┬ dist
-     * │ │ └── index.html
-     * │ │
-     * │ ├─┬ dist-electron
-     * │ │ ├── main.js
-     * │ │ └── preload.js
-     * │
-     * ```
-     */
-    APP_ROOT: string
-    /** /dist/ or /public/ */
-    VITE_PUBLIC: string
-  }
-}
-
-// Used in Renderer process, expose in `preload.ts`
-interface Window {
-  electronAPI: {
-    getSources: (opts: Electron.SourcesOptions) => Promise<ProcessedDesktopSource[]>
-    switchToEditor: () => Promise<void>
-    openSourceSelector: () => Promise<void>
-    selectSource: (source: any) => Promise<any>
-    getSelectedSource: () => Promise<any>
-    storeRecordedVideo: (videoData: ArrayBuffer, fileName: string) => Promise<{ success: boolean; path?: string; message?: string }>
-    getRecordedVideoPath: () => Promise<{ success: boolean; path?: string; message?: string }>
-    setRecordingState: (recording: boolean) => Promise<void>
-    onStopRecordingFromTray: (callback: () => void) => () => void
-    openExternalUrl: (url: string) => Promise<{ success: boolean; error?: string }>
-    saveExportedVideo: (videoData: ArrayBuffer, fileName: string) => Promise<{ success: boolean; path?: string; message?: string; cancelled?: boolean }>
-    openVideoFilePicker: () => Promise<{ success: boolean; path?: string; cancelled?: boolean }>
-    setCurrentVideoPath: (path: string) => Promise<{ success: boolean }>
-    getCurrentVideoPath: () => Promise<{ success: boolean; path?: string }>
-    clearCurrentVideoPath: () => Promise<{ success: boolean }>
-    hudOverlayHide: () => void;
-    hudOverlayClose: () => void;
-  }
-}
-
-interface ProcessedDesktopSource {
-  id: string
-  name: string
-  display_id: string
-  thumbnail: string | null
-  appIcon: string | null
-}
+/// <reference types="vite-plugin-electron/electron-env" />
+
+declare namespace NodeJS {
+	interface ProcessEnv {
+		/**
+		 * The built directory structure
+		 *
+		 * ```tree
+		 * ├─┬─┬ dist
+		 * │ │ └── index.html
+		 * │ │
+		 * │ ├─┬ dist-electron
+		 * │ │ ├── main.js
+		 * │ │ └── preload.js
+		 * │
+		 * ```
+		 */
+		APP_ROOT: string;
+		/** /dist/ or /public/ */
+		VITE_PUBLIC: string;
+	}
+}
+
+// Used in Renderer process, expose in `preload.ts`
+interface Window {
+	electronAPI: {
+		invokeNativeBridge: <TData = unknown>(
+			request: import("../src/native/contracts").NativeBridgeRequest,
+		) => Promise<import("../src/native/contracts").NativeBridgeResponse<TData>>;
+		getSources: (opts: Electron.SourcesOptions) => Promise<ProcessedDesktopSource[]>;
+		switchToEditor: () => Promise<void>;
+		switchToHud: () => Promise<void>;
+		startNewRecording: () => Promise<{ success: boolean; error?: string }>;
+		openSourceSelector: () => Promise<{
+			opened: boolean;
+			reason?: string;
+			access?: {
+				success: boolean;
+				granted: boolean;
+				status: string;
+				error?: string;
+			};
+		}>;
+		selectSource: (source: ProcessedDesktopSource) => Promise<ProcessedDesktopSource | null>;
+		getSelectedSource: () => Promise<ProcessedDesktopSource | null>;
+		requestCameraAccess: () => Promise<{
+			success: boolean;
+			granted: boolean;
+			status: string;
+			error?: string;
+		}>;
+		requestScreenAccess: () => Promise<{
+			success: boolean;
+			granted: boolean;
+			status: string;
+			error?: string;
+		}>;
+		requestNativeMacCursorAccess: () => Promise<{
+			success: boolean;
+			granted: boolean;
+			status: string;
+			error?: string;
+		}>;
+		assetBaseUrl: string;
+		storeRecordedVideo: (
+			videoData: ArrayBuffer,
+			fileName: string,
+		) => Promise<{
+			success: boolean;
+			path?: string;
+			session?: import("../src/lib/recordingSession").RecordingSession;
+			message?: string;
+			error?: string;
+		}>;
+		storeRecordedSession: (
+			payload: import("../src/lib/recordingSession").StoreRecordedSessionInput,
+		) => Promise<{
+			success: boolean;
+			path?: string;
+			session?: import("../src/lib/recordingSession").RecordingSession;
+			message?: string;
+			error?: string;
+		}>;
+		getRecordedVideoPath: () => Promise<{
+			success: boolean;
+			path?: string;
+			message?: string;
+			error?: string;
+		}>;
+		setRecordingState: (
+			recording: boolean,
+			recordingId?: number,
+			cursorCaptureMode?: import("../src/lib/recordingSession").CursorCaptureMode,
+		) => Promise<void>;
+		isNativeWindowsCaptureAvailable: () => Promise<{
+			success: boolean;
+			available: boolean;
+			helperPath?: string;
+			reason?: string;
+			error?: string;
+		}>;
+		isNativeMacCaptureAvailable: () => Promise<{
+			success: boolean;
+			available: boolean;
+			helperPath?: string;
+			reason?: "unsupported-platform" | "missing-helper" | string;
+			error?: string;
+		}>;
+		startNativeWindowsRecording: (
+			request: import("../src/lib/nativeWindowsRecording").NativeWindowsRecordingRequest,
+		) => Promise<import("../src/lib/nativeWindowsRecording").NativeWindowsRecordingStartResult>;
+		stopNativeWindowsRecording: (discard?: boolean) => Promise<{
+			success: boolean;
+			path?: string;
+			session?: import("../src/lib/recordingSession").RecordingSession;
+			message?: string;
+			discarded?: boolean;
+			error?: string;
+		}>;
+		startNativeMacRecording: (
+			request: import("../src/lib/nativeMacRecording").NativeMacRecordingRequest,
+		) => Promise<import("../src/lib/nativeMacRecording").NativeMacRecordingStartResult>;
+		pauseNativeMacRecording: () => Promise<{
+			success: boolean;
+			error?: string;
+		}>;
+		resumeNativeMacRecording: () => Promise<{
+			success: boolean;
+			error?: string;
+		}>;
+		stopNativeMacRecording: (discard?: boolean) => Promise<{
+			success: boolean;
+			path?: string;
+			session?: import("../src/lib/recordingSession").RecordingSession;
+			message?: string;
+			discarded?: boolean;
+			error?: string;
+		}>;
+		attachNativeMacWebcamRecording: (payload: {
+			screenVideoPath: string;
+			recordingId: number;
+			webcam: import("../src/lib/recordingSession").RecordedVideoAssetInput;
+			cursorCaptureMode?: import("../src/lib/recordingSession").CursorCaptureMode;
+		}) => Promise<{
+			success: boolean;
+			path?: string;
+			session?: import("../src/lib/recordingSession").RecordingSession;
+			message?: string;
+			error?: string;
+		}>;
+		discardCursorTelemetry: (recordingId: number) => Promise<void>;
+		getCursorTelemetry: (videoPath?: string) => Promise<{
+			success: boolean;
+			samples: CursorTelemetryPoint[];
+			clicks: number[];
+			message?: string;
+			error?: string;
+		}>;
+		onStopRecordingFromTray: (callback: () => void) => () => void;
+		openExternalUrl: (url: string) => Promise<{ success: boolean; error?: string }>;
+		pickExportSavePath: (
+			fileName: string,
+			exportFolder?: string,
+		) => Promise<{
+			success: boolean;
+			path?: string;
+			message?: string;
+			canceled?: boolean;
+			error?: string;
+		}>;
+		writeExportToPath: (
+			videoData: ArrayBuffer,
+			filePath: string,
+		) => Promise<{
+			success: boolean;
+			path?: string;
+			message?: string;
+			error?: string;
+		}>;
+		openVideoFilePicker: () => Promise<{ success: boolean; path?: string; canceled?: boolean }>;
+		setCurrentVideoPath: (path: string) => Promise<{ success: boolean }>;
+		setCurrentRecordingSession: (
+			session: import("../src/lib/recordingSession").RecordingSession | null,
+		) => Promise<{
+			success: boolean;
+			session?: import("../src/lib/recordingSession").RecordingSession;
+		}>;
+		getCurrentVideoPath: () => Promise<{ success: boolean; path?: string }>;
+		getCurrentRecordingSession: () => Promise<{
+			success: boolean;
+			session?: import("../src/lib/recordingSession").RecordingSession;
+		}>;
+		readBinaryFile: (filePath: string) => Promise<{
+			success: boolean;
+			data?: ArrayBuffer;
+			path?: string;
+			message?: string;
+			error?: string;
+		}>;
+		preparePreviewAudioTrack: (filePath: string) => Promise<{
+			success: boolean;
+			path?: string | null;
+			message?: string;
+			error?: string;
+		}>;
+		clearCurrentVideoPath: () => Promise<{ success: boolean }>;
+		saveProjectFile: (
+			projectData: unknown,
+			suggestedName?: string,
+			existingProjectPath?: string,
+		) => Promise<{
+			success: boolean;
+			path?: string;
+			message?: string;
+			canceled?: boolean;
+			error?: string;
+		}>;
+		loadProjectFile: () => Promise<{
+			success: boolean;
+			path?: string;
+			project?: unknown;
+			message?: string;
+			canceled?: boolean;
+			error?: string;
+		}>;
+		loadCurrentProjectFile: () => Promise<{
+			success: boolean;
+			path?: string;
+			project?: unknown;
+			message?: string;
+			canceled?: boolean;
+			error?: string;
+		}>;
+		onMenuLoadProject: (callback: () => void) => () => void;
+		onMenuSaveProject: (callback: () => void) => () => void;
+		onMenuSaveProjectAs: (callback: () => void) => () => void;
+		getPlatform: () => Promise<string>;
+		revealInFolder: (
+			filePath: string,
+		) => Promise<{ success: boolean; error?: string; message?: string }>;
+		getShortcuts: () => Promise<Record<string, unknown> | null>;
+		saveShortcuts: (shortcuts: unknown) => Promise<{ success: boolean; error?: string }>;
+		hudOverlayHide: () => void;
+		hudOverlayClose: () => void;
+		setHudOverlayIgnoreMouseEvents: (ignore: boolean) => void;
+		moveHudOverlayBy: (deltaX: number, deltaY: number) => void;
+		showCountdownOverlay: (value: number, runId: number) => Promise<void>;
+		setCountdownOverlayValue: (value: number, runId: number) => Promise<void>;
+		hideCountdownOverlay: (runId: number) => Promise<void>;
+		onCountdownOverlayValue: (callback: (value: number | null) => void) => () => void;
+		setMicrophoneExpanded: (expanded: boolean) => void;
+		setHasUnsavedChanges: (hasChanges: boolean) => void;
+		onRequestSaveBeforeClose: (callback: () => Promise<boolean> | boolean) => () => void;
+		onRequestCloseConfirm: (callback: () => void) => () => void;
+		sendCloseConfirmResponse: (choice: "save" | "discard" | "cancel") => void;
+		setLocale: (locale: string) => Promise<void>;
+		saveDiagnostic: (payload: {
+			error: string;
+			stack?: string;
+			projectState: unknown;
+			logs: string[];
+		}) => Promise<{ success: boolean; path?: string; canceled?: boolean; error?: string }>;
+	};
+}
+
+interface ProcessedDesktopSource {
+	id: string;
+	name: string;
+	display_id: string;
+	thumbnail: string | null;
+	appIcon: string | null;
+}
+
+interface CursorTelemetryPoint {
+	timeMs: number;
+	cx: number;
+	cy: number;
+}

electron/i18n.ts

@@ -0,0 +1,111 @@
+// Lightweight i18n for the Electron main process.
+// Imports the same JSON translation files used by the renderer.
+
+import commonAr from "../src/i18n/locales/ar/common.json";
+import dialogsAr from "../src/i18n/locales/ar/dialogs.json";
+import commonEn from "../src/i18n/locales/en/common.json";
+import dialogsEn from "../src/i18n/locales/en/dialogs.json";
+import commonEs from "../src/i18n/locales/es/common.json";
+import dialogsEs from "../src/i18n/locales/es/dialogs.json";
+import commonFr from "../src/i18n/locales/fr/common.json";
+import dialogsFr from "../src/i18n/locales/fr/dialogs.json";
+import commonIt from "../src/i18n/locales/it/common.json";
+import dialogsIt from "../src/i18n/locales/it/dialogs.json";
+import commonJa from "../src/i18n/locales/ja-JP/common.json";
+import dialogsJa from "../src/i18n/locales/ja-JP/dialogs.json";
+import commonKo from "../src/i18n/locales/ko-KR/common.json";
+import dialogsKo from "../src/i18n/locales/ko-KR/dialogs.json";
+import commonRu from "../src/i18n/locales/ru/common.json";
+import dialogsRu from "../src/i18n/locales/ru/dialogs.json";
+import commonTr from "../src/i18n/locales/tr/common.json";
+import dialogsTr from "../src/i18n/locales/tr/dialogs.json";
+import commonVi from "../src/i18n/locales/vi/common.json";
+import dialogsVi from "../src/i18n/locales/vi/dialogs.json";
+import commonZh from "../src/i18n/locales/zh-CN/common.json";
+import dialogsZh from "../src/i18n/locales/zh-CN/dialogs.json";
+import commonZhTw from "../src/i18n/locales/zh-TW/common.json";
+import dialogsZhTw from "../src/i18n/locales/zh-TW/dialogs.json";
+
+type Locale =
+	| "en"
+	| "ar"
+	| "es"
+	| "fr"
+	| "it"
+	| "ja-JP"
+	| "ko-KR"
+	| "ru"
+	| "tr"
+	| "vi"
+	| "zh-CN"
+	| "zh-TW";
+type Namespace = "common" | "dialogs";
+type MessageMap = Record<string, unknown>;
+
+const messages: Record<Locale, Record<Namespace, MessageMap>> = {
+	en: { common: commonEn, dialogs: dialogsEn },
+	ar: { common: commonAr, dialogs: dialogsAr },
+	es: { common: commonEs, dialogs: dialogsEs },
+	fr: { common: commonFr, dialogs: dialogsFr },
+	it: { common: commonIt, dialogs: dialogsIt },
+	"ja-JP": { common: commonJa, dialogs: dialogsJa },
+	"ko-KR": { common: commonKo, dialogs: dialogsKo },
+	ru: { common: commonRu, dialogs: dialogsRu },
+	tr: { common: commonTr, dialogs: dialogsTr },
+	vi: { common: commonVi, dialogs: dialogsVi },
+	"zh-CN": { common: commonZh, dialogs: dialogsZh },
+	"zh-TW": { common: commonZhTw, dialogs: dialogsZhTw },
+};
+
+let currentLocale: Locale = "en";
+
+export function setMainLocale(locale: string) {
+	if (
+		locale === "en" ||
+		locale === "ar" ||
+		locale === "es" ||
+		locale === "fr" ||
+		locale === "it" ||
+		locale === "ja-JP" ||
+		locale === "ko-KR" ||
+		locale === "ru" ||
+		locale === "tr" ||
+		locale === "vi" ||
+		locale === "zh-CN" ||
+		locale === "zh-TW"
+	) {
+		currentLocale = locale;
+	}
+}
+
+export function getMainLocale(): Locale {
+	return currentLocale;
+}
+
+function getMessageValue(obj: unknown, dotPath: string): string | undefined {
+	const keys = dotPath.split(".");
+	let current: unknown = obj;
+	for (const key of keys) {
+		if (current == null || typeof current !== "object") return undefined;
+		current = (current as Record<string, unknown>)[key];
+	}
+	return typeof current === "string" ? current : undefined;
+}
+
+function interpolate(str: string, vars?: Record<string, string | number>): string {
+	if (!vars) return str;
+	return str.replace(/\{\{(\w+)\}\}/g, (_, key: string) => String(vars[key] ?? `{{${key}}}`));
+}
+
+export function mainT(
+	namespace: Namespace,
+	key: string,
+	vars?: Record<string, string | number>,
+): string {
+	const value =
+		getMessageValue(messages[currentLocale]?.[namespace], key) ??
+		getMessageValue(messages.en?.[namespace], key);
+
+	if (value == null) return `${namespace}.${key}`;
+	return interpolate(value, vars);
+}

electron/ipc/nativeBridge.ts

@@ -0,0 +1,229 @@
+import { ipcMain } from "electron";
+import {
+	NATIVE_BRIDGE_CHANNEL,
+	NATIVE_BRIDGE_VERSION,
+	type NativeBridgeErrorCode,
+	type NativeBridgeRequest,
+	type NativeBridgeResponse,
+	type NativePlatform,
+	type ProjectFileResult,
+	type ProjectPathResult,
+} from "../../src/native/contracts";
+import type { CursorTelemetryLoadResult } from "../native-bridge/cursor/adapter";
+import { TelemetryCursorAdapter } from "../native-bridge/cursor/telemetryCursorAdapter";
+import { CursorService } from "../native-bridge/services/cursorService";
+import { ProjectService } from "../native-bridge/services/projectService";
+import { SystemService } from "../native-bridge/services/systemService";
+import { NativeBridgeStateStore } from "../native-bridge/store";
+
+export interface NativeBridgeContext {
+	getPlatform: () => NodeJS.Platform;
+	getCurrentProjectPath: () => string | null;
+	getCurrentVideoPath: () => string | null;
+	saveProjectFile: (
+		projectData: unknown,
+		suggestedName?: string,
+		existingProjectPath?: string,
+	) => Promise<ProjectFileResult>;
+	loadProjectFile: () => Promise<ProjectFileResult>;
+	loadCurrentProjectFile: () => Promise<ProjectFileResult>;
+	setCurrentVideoPath: (path: string) => ProjectPathResult | Promise<ProjectPathResult>;
+	getCurrentVideoPathResult: () => ProjectPathResult;
+	clearCurrentVideoPath: () => ProjectPathResult;
+	resolveAssetBasePath: () => string | null;
+	resolveVideoPath: (videoPath?: string | null) => string | null;
+	loadCursorRecordingData: (
+		videoPath: string,
+	) => Promise<import("../../src/native/contracts").CursorRecordingData>;
+	loadCursorTelemetry: (videoPath: string) => Promise<CursorTelemetryLoadResult>;
+}
+
+function normalizePlatform(platform: NodeJS.Platform): NativePlatform {
+	if (platform === "darwin" || platform === "win32") {
+		return platform;
+	}
+
+	return "linux";
+}
+
+function createMeta(requestId?: string) {
+	return {
+		version: NATIVE_BRIDGE_VERSION,
+		requestId: requestId || `native-${Date.now()}`,
+		timestampMs: Date.now(),
+	} as const;
+}
+
+function createSuccessResponse<TData>(requestId: string | undefined, data: TData) {
+	return {
+		ok: true,
+		data,
+		meta: createMeta(requestId),
+	} satisfies NativeBridgeResponse<TData>;
+}
+
+function createErrorResponse(
+	requestId: string | undefined,
+	code: NativeBridgeErrorCode,
+	message: string,
+	retryable = false,
+) {
+	return {
+		ok: false,
+		error: {
+			code,
+			message,
+			retryable,
+		},
+		meta: createMeta(requestId),
+	} satisfies NativeBridgeResponse;
+}
+
+function isBridgeRequest(value: unknown): value is NativeBridgeRequest {
+	if (!value || typeof value !== "object") {
+		return false;
+	}
+
+	const candidate = value as Partial<NativeBridgeRequest>;
+	return typeof candidate.domain === "string" && typeof candidate.action === "string";
+}
+
+export function registerNativeBridgeHandlers(context: NativeBridgeContext) {
+	ipcMain.removeHandler(NATIVE_BRIDGE_CHANNEL);
+
+	const platform = normalizePlatform(context.getPlatform());
+	const store = new NativeBridgeStateStore(platform);
+	const projectService = new ProjectService({
+		store,
+		getCurrentProjectPath: context.getCurrentProjectPath,
+		getCurrentVideoPath: context.getCurrentVideoPath,
+		saveProjectFile: context.saveProjectFile,
+		loadProjectFile: context.loadProjectFile,
+		loadCurrentProjectFile: context.loadCurrentProjectFile,
+		setCurrentVideoPath: context.setCurrentVideoPath,
+		getCurrentVideoPathResult: context.getCurrentVideoPathResult,
+		clearCurrentVideoPath: context.clearCurrentVideoPath,
+	});
+	const cursorService = new CursorService({
+		store,
+		adapter: new TelemetryCursorAdapter({
+			loadRecordingData: context.loadCursorRecordingData,
+			resolveVideoPath: context.resolveVideoPath,
+			loadTelemetry: context.loadCursorTelemetry,
+		}),
+	});
+	const systemService = new SystemService({
+		store,
+		getPlatform: () => platform,
+		getAssetBasePath: context.resolveAssetBasePath,
+		getCursorCapabilities: () => cursorService.getCapabilities(),
+	});
+
+	ipcMain.handle(NATIVE_BRIDGE_CHANNEL, async (_, request: unknown) => {
+		if (!isBridgeRequest(request)) {
+			return createErrorResponse(undefined, "INVALID_REQUEST", "Invalid native bridge request.");
+		}
+
+		const requestId = request.requestId;
+		const domain = request.domain as string;
+
+		try {
+			switch (request.domain) {
+				case "system": {
+					const action = request.action as string;
+					switch (request.action) {
+						case "getPlatform":
+							return createSuccessResponse(requestId, systemService.getPlatform());
+						case "getAssetBasePath":
+							return createSuccessResponse(requestId, systemService.getAssetBasePath());
+						case "getCapabilities":
+							return createSuccessResponse(requestId, await systemService.getCapabilities());
+						default:
+							return createErrorResponse(
+								requestId,
+								"UNSUPPORTED_ACTION",
+								`Unsupported system action: ${action}`,
+							);
+					}
+				}
+
+				case "project": {
+					const action = request.action as string;
+					switch (request.action) {
+						case "getCurrentContext":
+							return createSuccessResponse(requestId, projectService.getCurrentContext());
+						case "saveProjectFile":
+							return createSuccessResponse(
+								requestId,
+								await projectService.saveProjectFile(
+									request.payload.projectData,
+									request.payload.suggestedName,
+									request.payload.existingProjectPath,
+								),
+							);
+						case "loadProjectFile":
+							return createSuccessResponse(requestId, await projectService.loadProjectFile());
+						case "loadCurrentProjectFile":
+							return createSuccessResponse(
+								requestId,
+								await projectService.loadCurrentProjectFile(),
+							);
+						case "setCurrentVideoPath":
+							return createSuccessResponse(
+								requestId,
+								await projectService.setCurrentVideoPath(request.payload.path),
+							);
+						case "getCurrentVideoPath":
+							return createSuccessResponse(requestId, projectService.getCurrentVideoPath());
+						case "clearCurrentVideoPath":
+							return createSuccessResponse(requestId, projectService.clearCurrentVideoPath());
+						default:
+							return createErrorResponse(
+								requestId,
+								"UNSUPPORTED_ACTION",
+								`Unsupported project action: ${action}`,
+							);
+					}
+				}
+
+				case "cursor": {
+					const action = request.action as string;
+					switch (request.action) {
+						case "getCapabilities":
+							return createSuccessResponse(requestId, await cursorService.getCapabilities());
+						case "getTelemetry":
+							return createSuccessResponse(
+								requestId,
+								await cursorService.getTelemetry(request.payload?.videoPath),
+							);
+						case "getRecordingData":
+							return createSuccessResponse(
+								requestId,
+								await cursorService.getRecordingData(request.payload?.videoPath),
+							);
+						default:
+							return createErrorResponse(
+								requestId,
+								"UNSUPPORTED_ACTION",
+								`Unsupported cursor action: ${action}`,
+							);
+					}
+				}
+
+				default:
+					return createErrorResponse(
+						requestId,
+						"UNSUPPORTED_ACTION",
+						`Unsupported bridge domain: ${domain}`,
+					);
+			}
+		} catch (error) {
+			return createErrorResponse(
+				requestId,
+				"INTERNAL_ERROR",
+				error instanceof Error ? error.message : "Unknown native bridge error.",
+				true,
+			);
+		}
+	});
+}

electron/main.ts

@@ -1,24 +1,56 @@
-import { app, BrowserWindow, Tray, Menu, nativeImage } from 'electron'
-import { fileURLToPath } from 'node:url'
-import path from 'node:path'
-import fs from 'node:fs/promises'
-import { createHudOverlayWindow, createEditorWindow, createSourceSelectorWindow } from './windows'
-import { registerIpcHandlers } from './ipc/handlers'
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	app,
+	BrowserWindow,
+	ipcMain,
+	Menu,
+	nativeImage,
+	session,
+	systemPreferences,
+	Tray,
+} from "electron";
+import { mainT, setMainLocale } from "./i18n";
+import { getSelectedDesktopSource, registerIpcHandlers } from "./ipc/handlers";
+import {
+	createCountdownOverlayWindow,
+	createEditorWindow,
+	createHudOverlayWindow,
+	createSourceSelectorWindow,
+} from "./windows";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
+// Use Screen & System Audio Recording permissions instead of CoreAudio Tap API on macOS.
+// CoreAudio Tap requires NSAudioCaptureUsageDescription in the parent app's Info.plist,
+// which doesn't work when running from a terminal/IDE during development, makes my life easier
+if (process.platform === "darwin") {
+	app.commandLine.appendSwitch("disable-features", "MacCatapLoopbackAudioForScreenShare");
+}
 
-export const RECORDINGS_DIR = path.join(app.getPath('userData'), 'recordings')
+// Enable Wayland support for proper screen capture and window management
+// on Wayland compositors (Hyprland, GNOME, KDE, etc.)
+if (process.platform === "linux") {
+	const isWayland =
+		process.env.XDG_SESSION_TYPE === "wayland" || process.env.WAYLAND_DISPLAY !== undefined;
+	if (isWayland) {
+		app.commandLine.appendSwitch("ozone-platform", "wayland");
+		// Enable WebRTCPipeWireCapturer for screen capture on Wayland
+		app.commandLine.appendSwitch("enable-features", "WaylandWindowDrag,WebRTCPipeWireCapturer");
+	}
+}
 
+export const RECORDINGS_DIR = path.join(app.getPath("userData"), "recordings");
 
 async function ensureRecordingsDir() {
-  try {
-    await fs.mkdir(RECORDINGS_DIR, { recursive: true })
-    console.log('RECORDINGS_DIR:', RECORDINGS_DIR)
-    console.log('User Data Path:', app.getPath('userData'))
-  } catch (error) {
-    console.error('Failed to create recordings directory:', error)
-  }
+	try {
+		await fs.mkdir(RECORDINGS_DIR, { recursive: true });
+		console.log("RECORDINGS_DIR:", RECORDINGS_DIR);
+		console.log("User Data Path:", app.getPath("userData"));
+	} catch (error) {
+		console.error("Failed to create recordings directory:", error);
+	}
 }
 
 // The built directory structure
@@ -30,112 +62,488 @@ async function ensureRecordingsDir() {
 // │ │ ├── main.js
 // │ │ └── preload.mjs
 // │
-process.env.APP_ROOT = path.join(__dirname, '..')
+process.env.APP_ROOT = path.join(__dirname, "..");
 
 // Use ['ENV_NAME'] avoid vite:define plugin - Vite@2.x
-export const VITE_DEV_SERVER_URL = process.env['VITE_DEV_SERVER_URL']
-export const MAIN_DIST = path.join(process.env.APP_ROOT, 'dist-electron')
-export const RENDERER_DIST = path.join(process.env.APP_ROOT, 'dist')
+export const VITE_DEV_SERVER_URL = process.env["VITE_DEV_SERVER_URL"];
+export const MAIN_DIST = path.join(process.env.APP_ROOT, "dist-electron");
+export const RENDERER_DIST = path.join(process.env.APP_ROOT, "dist");
 
-process.env.VITE_PUBLIC = VITE_DEV_SERVER_URL ? path.join(process.env.APP_ROOT, 'public') : RENDERER_DIST
+process.env.VITE_PUBLIC = VITE_DEV_SERVER_URL
+	? path.join(process.env.APP_ROOT, "public")
+	: RENDERER_DIST;
 
 // Window references
-let mainWindow: BrowserWindow | null = null
-let sourceSelectorWindow: BrowserWindow | null = null
-let tray: Tray | null = null
-let selectedSourceName = ''
+let mainWindow: BrowserWindow | null = null;
+let sourceSelectorWindow: BrowserWindow | null = null;
+let countdownOverlayWindow: BrowserWindow | null = null;
+let tray: Tray | null = null;
+let selectedSourceName = "";
+const isMac = process.platform === "darwin";
+const trayIconSize = isMac ? 16 : 24;
+
+// Tray Icons
+const defaultTrayIcon = getTrayIcon("openscreen.png", trayIconSize);
+const recordingTrayIcon = getTrayIcon("rec-button.png", trayIconSize);
 
 function createWindow() {
-  mainWindow = createHudOverlayWindow()
+	mainWindow = createHudOverlayWindow();
+}
+
+function showMainWindow() {
+	if (mainWindow && !mainWindow.isDestroyed()) {
+		if (mainWindow.isMinimized()) {
+			mainWindow.restore();
+		}
+		mainWindow.show();
+		mainWindow.focus();
+		return;
+	}
+
+	createWindow();
+}
+
+function isEditorWindow(window: BrowserWindow) {
+	return window.webContents.getURL().includes("windowType=editor");
+}
+
+function sendEditorMenuAction(
+	channel: "menu-load-project" | "menu-save-project" | "menu-save-project-as",
+) {
+	let targetWindow = BrowserWindow.getFocusedWindow() ?? mainWindow;
+
+	if (!targetWindow || targetWindow.isDestroyed() || !isEditorWindow(targetWindow)) {
+		createEditorWindowWrapper();
+		targetWindow = mainWindow;
+		if (!targetWindow || targetWindow.isDestroyed()) return;
+
+		targetWindow.webContents.once("did-finish-load", () => {
+			if (!targetWindow || targetWindow.isDestroyed()) return;
+			targetWindow.webContents.send(channel);
+		});
+		return;
+	}
+
+	targetWindow.webContents.send(channel);
+}
+
+function setupApplicationMenu() {
+	const isMac = process.platform === "darwin";
+	const template: Electron.MenuItemConstructorOptions[] = [];
+
+	if (isMac) {
+		template.push({
+			label: app.name,
+			submenu: [
+				{
+					role: "about",
+					label: mainT("common", "actions.about") || "About OpenScreen",
+				},
+				{ type: "separator" },
+				{
+					role: "services",
+					label: mainT("common", "actions.services") || "Services",
+				},
+				{ type: "separator" },
+				{
+					role: "hide",
+					label: mainT("common", "actions.hide") || "Hide OpenScreen",
+				},
+				{
+					role: "hideOthers",
+					label: mainT("common", "actions.hideOthers") || "Hide Others",
+				},
+				{
+					role: "unhide",
+					label: mainT("common", "actions.unhide") || "Show All",
+				},
+				{ type: "separator" },
+				{ role: "quit", label: mainT("common", "actions.quit") || "Quit" },
+			],
+		});
+	}
+
+	template.push(
+		{
+			label: mainT("common", "actions.file") || "File",
+			submenu: [
+				{
+					label: mainT("dialogs", "unsavedChanges.loadProject") || "Load Project…",
+					accelerator: "CmdOrCtrl+O",
+					click: () => sendEditorMenuAction("menu-load-project"),
+				},
+				{
+					label: mainT("dialogs", "unsavedChanges.saveProject") || "Save Project…",
+					accelerator: "CmdOrCtrl+S",
+					click: () => sendEditorMenuAction("menu-save-project"),
+				},
+				{
+					label: mainT("dialogs", "unsavedChanges.saveProjectAs") || "Save Project As…",
+					accelerator: "CmdOrCtrl+Shift+S",
+					click: () => sendEditorMenuAction("menu-save-project-as"),
+				},
+				...(isMac
+					? []
+					: [
+							{ type: "separator" as const },
+							{
+								role: "quit" as const,
+								label: mainT("common", "actions.quit") || "Quit",
+							},
+						]),
+			],
+		},
+		{
+			label: mainT("common", "actions.edit") || "Edit",
+			submenu: [
+				{ role: "undo", label: mainT("common", "actions.undo") || "Undo" },
+				{ role: "redo", label: mainT("common", "actions.redo") || "Redo" },
+				{ type: "separator" },
+				{ role: "cut", label: mainT("common", "actions.cut") || "Cut" },
+				{ role: "copy", label: mainT("common", "actions.copy") || "Copy" },
+				{ role: "paste", label: mainT("common", "actions.paste") || "Paste" },
+				{
+					role: "selectAll",
+					label: mainT("common", "actions.selectAll") || "Select All",
+				},
+			],
+		},
+		{
+			label: mainT("common", "actions.view") || "View",
+			submenu: [
+				{
+					role: "reload",
+					label: mainT("common", "actions.reload") || "Reload",
+				},
+				{
+					role: "forceReload",
+					label: mainT("common", "actions.forceReload") || "Force Reload",
+				},
+				{
+					role: "toggleDevTools",
+					label: mainT("common", "actions.toggleDevTools") || "Toggle Developer Tools",
+				},
+				{ type: "separator" },
+				{
+					role: "resetZoom",
+					label: mainT("common", "actions.actualSize") || "Actual Size",
+				},
+				{
+					role: "zoomIn",
+					label: mainT("common", "actions.zoomIn") || "Zoom In",
+				},
+				{
+					role: "zoomOut",
+					label: mainT("common", "actions.zoomOut") || "Zoom Out",
+				},
+				{ type: "separator" },
+				{
+					role: "togglefullscreen",
+					label: mainT("common", "actions.toggleFullScreen") || "Toggle Full Screen",
+				},
+			],
+		},
+		{
+			label: mainT("common", "actions.window") || "Window",
+			submenu: isMac
+				? [
+						{
+							role: "minimize",
+							label: mainT("common", "actions.minimize") || "Minimize",
+						},
+						{ role: "zoom" },
+						{ type: "separator" },
+						{ role: "front" },
+					]
+				: [
+						{
+							role: "minimize",
+							label: mainT("common", "actions.minimize") || "Minimize",
+						},
+						{
+							role: "close",
+							label: mainT("common", "actions.close") || "Close",
+						},
+					],
+		},
+	);
+
+	const menu = Menu.buildFromTemplate(template);
+	Menu.setApplicationMenu(menu);
 }
 
 function createTray() {
-  const iconPath = path.join(process.env.VITE_PUBLIC || RENDERER_DIST, 'rec-button.png');
-  let icon = nativeImage.createFromPath(iconPath);
-  icon = icon.resize({ width: 24, height: 24, quality: 'best' });
-  tray = new Tray(icon);
-  updateTrayMenu();
+	tray = new Tray(defaultTrayIcon);
+	tray.on("click", () => {
+		showMainWindow();
+	});
+	tray.on("double-click", () => {
+		showMainWindow();
+	});
 }
 
-function updateTrayMenu() {
-  if (!tray) return;
-  const menuTemplate = [
-    {
-      label: 'Stop Recording',
-      click: () => {
-        if (mainWindow && !mainWindow.isDestroyed()) {
-          mainWindow.webContents.send('stop-recording-from-tray');
-        }
-      }
-    }
-  ];
-  const contextMenu = Menu.buildFromTemplate(menuTemplate);
-  tray.setContextMenu(contextMenu);
-  tray.setToolTip(`Recording: ${selectedSourceName}`);
+function getTrayIcon(filename: string, size: number) {
+	return nativeImage
+		.createFromPath(path.join(process.env.VITE_PUBLIC || RENDERER_DIST, filename))
+		.resize({
+			width: size,
+			height: size,
+			quality: "best",
+		});
+}
+
+function updateTrayMenu(recording: boolean = false) {
+	if (!tray) return;
+	const trayIcon = recording ? recordingTrayIcon : defaultTrayIcon;
+	const trayToolTip = recording
+		? mainT("common", "actions.recordingStatus", {
+				source: selectedSourceName,
+			}) || `Recording: ${selectedSourceName}`
+		: "OpenScreen";
+	const menuTemplate = recording
+		? [
+				{
+					label: mainT("common", "actions.stopRecording") || "Stop Recording",
+					click: () => {
+						if (mainWindow && !mainWindow.isDestroyed()) {
+							mainWindow.webContents.send("stop-recording-from-tray");
+						}
+					},
+				},
+			]
+		: [
+				{
+					label: mainT("common", "actions.open") || "Open",
+					click: () => {
+						showMainWindow();
+					},
+				},
+				{
+					label: mainT("common", "actions.quit") || "Quit",
+					click: () => {
+						app.quit();
+					},
+				},
+			];
+	tray.setImage(trayIcon);
+	tray.setToolTip(trayToolTip);
+	tray.setContextMenu(Menu.buildFromTemplate(menuTemplate));
+}
+
+let editorHasUnsavedChanges = false;
+let isForceClosing = false;
+let isCloseConfirmInFlight = false;
+
+ipcMain.on("set-has-unsaved-changes", (_, hasChanges: boolean) => {
+	editorHasUnsavedChanges = hasChanges;
+});
+
+function forceCloseEditorWindow(windowToClose: BrowserWindow | null) {
+	if (!windowToClose || windowToClose.isDestroyed()) return;
+
+	isForceClosing = true;
+	setImmediate(() => {
+		try {
+			if (!windowToClose.isDestroyed()) {
+				windowToClose.close();
+			}
+		} finally {
+			isForceClosing = false;
+		}
+	});
 }
 
 function createEditorWindowWrapper() {
-  if (mainWindow) {
-    mainWindow.close()
-    mainWindow = null
-  }
-  mainWindow = createEditorWindow()
+	if (mainWindow) {
+		isForceClosing = true;
+		mainWindow.close();
+		isForceClosing = false;
+		mainWindow = null;
+	}
+	mainWindow = createEditorWindow();
+	editorHasUnsavedChanges = false;
+
+	mainWindow.on("close", (event) => {
+		if (isForceClosing || !editorHasUnsavedChanges || isCloseConfirmInFlight) return;
+
+		event.preventDefault();
+		isCloseConfirmInFlight = true;
+
+		const windowToClose = mainWindow;
+		if (!windowToClose || windowToClose.isDestroyed()) return;
+
+		// Ask renderer to show the custom in-app dialog
+		windowToClose.webContents.send("request-close-confirm");
+
+		ipcMain.once("close-confirm-response", (event, choice: "save" | "discard" | "cancel") => {
+			if (event.sender.id !== windowToClose?.webContents.id) return;
+			isCloseConfirmInFlight = false;
+			if (!windowToClose || windowToClose.isDestroyed()) return;
+
+			if (choice === "save") {
+				// Tell renderer to save the project, then close when done
+				windowToClose.webContents.send("request-save-before-close");
+				ipcMain.once("save-before-close-done", (event, shouldClose: boolean) => {
+					if (event.sender.id !== windowToClose?.webContents.id) return;
+					if (!shouldClose) return;
+					forceCloseEditorWindow(windowToClose);
+				});
+			} else if (choice === "discard") {
+				forceCloseEditorWindow(windowToClose);
+			}
+			// "cancel": flag reset, window stays open
+		});
+	});
 }
 
 function createSourceSelectorWindowWrapper() {
-  sourceSelectorWindow = createSourceSelectorWindow()
-  sourceSelectorWindow.on('closed', () => {
-    sourceSelectorWindow = null
-  })
-  return sourceSelectorWindow
+	sourceSelectorWindow = createSourceSelectorWindow();
+	sourceSelectorWindow.on("closed", () => {
+		sourceSelectorWindow = null;
+	});
+	return sourceSelectorWindow;
 }
 
-// On macOS, applications and their menu bar stay active until the user quits
-// explicitly with Cmd + Q.
-app.on('window-all-closed', () => {
-  // Keep app running (macOS behavior)
-})
+function createCountdownOverlayWindowWrapper() {
+	if (countdownOverlayWindow && !countdownOverlayWindow.isDestroyed()) {
+		return countdownOverlayWindow;
+	}
 
-app.on('activate', () => {
-  // On OS X it's common to re-create a window in the app when the
-  // dock icon is clicked and there are no other windows open.
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow()
-  }
-})
+	countdownOverlayWindow = createCountdownOverlayWindow();
+	countdownOverlayWindow.on("closed", () => {
+		countdownOverlayWindow = null;
+	});
+	return countdownOverlayWindow;
+}
 
+// Closing every window quits the app entirely (tray icon goes too).
+// The in-app "Return to Recorder" button covers the editor → HUD round-trip,
+// so closing the last window is an explicit "I'm done" signal.
+app.on("window-all-closed", () => {
+	app.quit();
+});
 
+app.on("activate", () => {
+	// On OS X it's common to re-create a window in the app when the
+	// dock icon is clicked and there are no other windows open.
+	const hasVisibleWindow = BrowserWindow.getAllWindows().some((window) => {
+		if (window.isDestroyed() || !window.isVisible()) {
+			return false;
+		}
+
+		const url = window.webContents.getURL();
+		const isCountdownOverlayWindow = url.includes("windowType=countdown-overlay");
+		return !isCountdownOverlayWindow;
+	});
+	if (!hasVisibleWindow) {
+		showMainWindow();
+	}
+});
 
 // Register all IPC handlers when app is ready
 app.whenReady().then(async () => {
-    // Listen for HUD overlay quit event (macOS only)
-    const { ipcMain } = await import('electron');
-    ipcMain.on('hud-overlay-close', () => {
-      if (process.platform === 'darwin') {
-        app.quit();
-      }
-    });
-  // Ensure recordings directory exists
-  await ensureRecordingsDir()
+	// Force the app into "regular" activation policy so the Dock icon appears.
+	// The HUD overlay (transparent + frameless + skipTaskbar) is the first
+	// window we open, and AppKit otherwise classifies us as an accessory app.
+	if (process.platform === "darwin") {
+		app.dock?.show();
+	}
 
-  registerIpcHandlers(
-    createEditorWindowWrapper,
-    createSourceSelectorWindowWrapper,
-    () => mainWindow,
-    () => sourceSelectorWindow,
-    (recording: boolean, sourceName: string) => {
-      selectedSourceName = sourceName
-      if (recording) {
-        if (!tray) createTray();
-        updateTrayMenu();
-      } else {
-        if (tray) {
-          tray.destroy();
-          tray = null;
-        }
-        if (mainWindow) mainWindow.restore();
-      }
-    }
-  )
-  createWindow()
-})
+	// Allow microphone/media/screen permission checks
+	session.defaultSession.setPermissionCheckHandler((_webContents, permission) => {
+		const allowed = [
+			"media",
+			"audioCapture",
+			"microphone",
+			"videoCapture",
+			"camera",
+			"screen",
+			"display-capture",
+		];
+		return allowed.includes(permission);
+	});
+
+	session.defaultSession.setPermissionRequestHandler((_webContents, permission, callback) => {
+		const allowed = [
+			"media",
+			"audioCapture",
+			"microphone",
+			"videoCapture",
+			"camera",
+			"screen",
+			"display-capture",
+		];
+		callback(allowed.includes(permission));
+	});
+
+	session.defaultSession.setDisplayMediaRequestHandler(
+		(request, callback) => {
+			const source = getSelectedDesktopSource();
+			if (!request.videoRequested || !source) {
+				callback({});
+				return;
+			}
+
+			callback({
+				video: source,
+				...(request.audioRequested && process.platform === "win32" ? { audio: "loopback" } : {}),
+			});
+		},
+		{ useSystemPicker: false },
+	);
+
+	// Request microphone permission from macOS. Screen Recording is requested
+	// lazily from the source-picker action so the system prompt is not hidden
+	// behind OpenScreen's source selector window.
+	if (process.platform === "darwin") {
+		const micStatus = systemPreferences.getMediaAccessStatus("microphone");
+		if (micStatus !== "granted") {
+			await systemPreferences.askForMediaAccess("microphone");
+		}
+	}
+
+	// Listen for HUD overlay quit event (macOS only)
+	ipcMain.on("hud-overlay-close", () => {
+		app.quit();
+	});
+	ipcMain.handle("set-locale", (_, locale: string) => {
+		setMainLocale(locale);
+		setupApplicationMenu();
+		updateTrayMenu();
+	});
+
+	createTray();
+	updateTrayMenu();
+	setupApplicationMenu();
+	// Ensure recordings directory exists
+	await ensureRecordingsDir();
+
+	function switchToHudWrapper() {
+		if (mainWindow) {
+			isForceClosing = true;
+			mainWindow.close();
+			isForceClosing = false;
+			mainWindow = null;
+		}
+		showMainWindow();
+	}
+
+	registerIpcHandlers(
+		createEditorWindowWrapper,
+		createSourceSelectorWindowWrapper,
+		createCountdownOverlayWindowWrapper,
+		() => mainWindow,
+		() => sourceSelectorWindow,
+		() => countdownOverlayWindow,
+		(recording: boolean, sourceName: string) => {
+			selectedSourceName = sourceName;
+			if (!tray) createTray();
+			updateTrayMenu(recording);
+			if (!recording) {
+				showMainWindow();
+			}
+		},
+		switchToHudWrapper,
+	);
+	createWindow();
+});

electron/native-bridge/cursor/adapter.ts

@@ -0,0 +1,20 @@
+import type {
+	CursorCapabilities,
+	CursorProviderKind,
+	CursorRecordingData,
+	CursorTelemetryPoint,
+} from "../../../src/native/contracts";
+
+export interface CursorTelemetryLoadResult {
+	success: boolean;
+	samples: CursorTelemetryPoint[];
+	message?: string;
+	error?: string;
+}
+
+export interface CursorNativeAdapter {
+	readonly kind: CursorProviderKind;
+	getCapabilities(): Promise<CursorCapabilities>;
+	getRecordingData(videoPath?: string | null): Promise<CursorRecordingData>;
+	getTelemetry(videoPath?: string | null): Promise<CursorTelemetryLoadResult>;
+}

electron/native-bridge/cursor/recording/factory.ts

@@ -0,0 +1,46 @@
+import type { Rectangle } from "electron";
+import { MacNativeCursorRecordingSession } from "./macNativeCursorRecordingSession";
+import type { CursorRecordingSession } from "./session";
+import { TelemetryRecordingSession } from "./telemetryRecordingSession";
+import { WindowsNativeRecordingSession } from "./windowsNativeRecordingSession";
+
+interface CreateCursorRecordingSessionOptions {
+	getDisplayBounds: () => Rectangle | null;
+	maxSamples: number;
+	platform: NodeJS.Platform;
+	sampleIntervalMs: number;
+	sourceId?: string | null;
+	startTimeMs?: number;
+}
+
+export function createCursorRecordingSession(
+	options: CreateCursorRecordingSessionOptions,
+): CursorRecordingSession {
+	if (options.platform === "win32") {
+		return new WindowsNativeRecordingSession({
+			getDisplayBounds: options.getDisplayBounds,
+			maxSamples: options.maxSamples,
+			sampleIntervalMs: options.sampleIntervalMs,
+			sourceId: options.sourceId,
+			startTimeMs: options.startTimeMs,
+		});
+	}
+
+	if (options.platform === "darwin") {
+		return new MacNativeCursorRecordingSession({
+			getDisplayBounds: options.getDisplayBounds,
+			maxSamples: options.maxSamples,
+			sampleIntervalMs: options.sampleIntervalMs,
+			startTimeMs: options.startTimeMs,
+		});
+	}
+
+	// Linux: capture cursor positions via Electron's `screen` API on an interval.
+	// No cursor sprites/assets and no clicks — just position telemetry.
+	return new TelemetryRecordingSession({
+		getDisplayBounds: options.getDisplayBounds,
+		maxSamples: options.maxSamples,
+		sampleIntervalMs: options.sampleIntervalMs,
+		startTimeMs: options.startTimeMs,
+	});
+}

electron/native-bridge/cursor/recording/macNativeCursorRecordingSession.ts

@@ -0,0 +1,411 @@
+import { type ChildProcessByStdio, spawn } from "node:child_process";
+import { accessSync, constants as fsConstants } from "node:fs";
+import path from "node:path";
+import type { Readable } from "node:stream";
+import { type Rectangle, screen, systemPreferences } from "electron";
+import type {
+	CursorRecordingData,
+	CursorRecordingSample,
+	NativeCursorType,
+} from "../../../../src/native/contracts";
+import type { CursorRecordingSession } from "./session";
+
+interface MacNativeCursorRecordingSessionOptions {
+	getDisplayBounds: () => Rectangle | null;
+	maxSamples: number;
+	sampleIntervalMs: number;
+	startTimeMs?: number;
+}
+
+type MacCursorEvent =
+	| {
+			type: "ready";
+			timestampMs: number;
+			accessibilityTrusted?: boolean;
+			mouseTapReady?: boolean;
+	  }
+	| {
+			type: "sample";
+			timestampMs: number;
+			cursorType?: NativeCursorType | null;
+			leftButtonDown?: boolean;
+			leftButtonPressed?: boolean;
+			leftButtonReleased?: boolean;
+	  };
+
+const HELPER_NAME = "openscreen-macos-cursor-helper";
+const READY_TIMEOUT_MS = 5_000;
+
+function helperCandidates() {
+	const envPath = process.env.OPENSCREEN_MAC_CURSOR_HELPER_EXE?.trim();
+	const appRoot = process.env.APP_ROOT ? path.resolve(process.env.APP_ROOT) : process.cwd();
+	const archTag = process.arch === "arm64" ? "darwin-arm64" : "darwin-x64";
+	const resourceRoot =
+		typeof process.resourcesPath === "string"
+			? process.resourcesPath
+			: path.join(appRoot, "resources");
+
+	return [
+		envPath,
+		path.join(appRoot, "electron", "native", "screencapturekit", "build", HELPER_NAME),
+		path.join(appRoot, "electron", "native", "bin", archTag, HELPER_NAME),
+		path.join(resourceRoot, "electron", "native", "bin", archTag, HELPER_NAME),
+	].filter((candidate): candidate is string => Boolean(candidate));
+}
+
+export function findMacCursorHelperPath() {
+	for (const candidate of helperCandidates()) {
+		try {
+			accessSync(candidate, fsConstants.X_OK);
+			return candidate;
+		} catch {
+			// Try the next helper location.
+		}
+	}
+
+	return null;
+}
+
+export async function requestMacCursorAccessibilityAccess() {
+	if (process.platform !== "darwin") {
+		return { success: true, granted: true, status: "granted" };
+	}
+
+	try {
+		systemPreferences.isTrustedAccessibilityClient(true);
+	} catch {
+		// Continue with helper probing; it can trigger the same macOS prompt.
+	}
+
+	const helperPath = findMacCursorHelperPath();
+	if (!helperPath) {
+		return { success: true, granted: false, status: "missing-helper" };
+	}
+
+	return new Promise<{ success: boolean; granted: boolean; status: string; error?: string }>(
+		(resolve) => {
+			const child = spawn(helperPath, [JSON.stringify({ sampleIntervalMs: 250 })], {
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			let settled = false;
+			let lineBuffer = "";
+			const finish = (result: {
+				success: boolean;
+				granted: boolean;
+				status: string;
+				error?: string;
+			}) => {
+				if (settled) {
+					return;
+				}
+				settled = true;
+				clearTimeout(timer);
+				if (!child.killed) {
+					child.kill("SIGTERM");
+				}
+				resolve(result);
+			};
+			const timer = setTimeout(() => {
+				finish({
+					success: false,
+					granted: false,
+					status: "timeout",
+					error: "Timed out waiting for macOS cursor helper",
+				});
+			}, READY_TIMEOUT_MS);
+
+			child.stdout.setEncoding("utf8");
+			child.stdout.on("data", (chunk: string) => {
+				lineBuffer += chunk;
+				const lines = lineBuffer.split(/\r?\n/);
+				lineBuffer = lines.pop() ?? "";
+				for (const line of lines) {
+					const trimmed = line.trim();
+					if (!trimmed) {
+						continue;
+					}
+					try {
+						const event = JSON.parse(trimmed) as MacCursorEvent;
+						if (event.type === "ready") {
+							finish({
+								success: true,
+								granted: event.accessibilityTrusted === true,
+								status: event.accessibilityTrusted === true ? "granted" : "not-determined",
+							});
+							return;
+						}
+					} catch {
+						// Ignore non-JSON helper output.
+					}
+				}
+			});
+
+			child.once("error", (error) => {
+				finish({
+					success: false,
+					granted: false,
+					status: "error",
+					error: error.message,
+				});
+			});
+			child.once("exit", (code, signal) => {
+				finish({
+					success: false,
+					granted: false,
+					status: "exited",
+					error: `macOS cursor helper exited before ready (code=${code}, signal=${signal})`,
+				});
+			});
+		},
+	);
+}
+
+function clamp(value: number, min: number, max: number) {
+	return Math.min(max, Math.max(min, value));
+}
+
+function normalizeCursorType(value: unknown): NativeCursorType | null {
+	return value === "arrow" || value === "pointer" || value === "text" ? value : null;
+}
+
+export class MacNativeCursorRecordingSession implements CursorRecordingSession {
+	private samples: CursorRecordingSample[] = [];
+	private process: ChildProcessByStdio<null, Readable, Readable> | null = null;
+	private lineBuffer = "";
+	private startTimeMs = 0;
+	private fallbackInterval: NodeJS.Timeout | null = null;
+	private readyResolve: (() => void) | null = null;
+	private readyReject: ((error: Error) => void) | null = null;
+	private readyTimer: NodeJS.Timeout | null = null;
+	private previousLeftButtonDown = false;
+	private consecutiveOutsideSamples = 0;
+	// Only hide after this many consecutive out-of-bounds samples (≈100ms at 33ms interval).
+	// Fast swipes that briefly exit the display are clipped by clip-path instead of disappearing.
+	private static readonly OUTSIDE_HIDE_THRESHOLD = 3;
+
+	constructor(private readonly options: MacNativeCursorRecordingSessionOptions) {}
+
+	async start(): Promise<void> {
+		this.samples = [];
+		this.lineBuffer = "";
+		this.startTimeMs = this.options.startTimeMs ?? Date.now();
+		this.previousLeftButtonDown = false;
+		this.consecutiveOutsideSamples = 0;
+
+		try {
+			systemPreferences.isTrustedAccessibilityClient(true);
+		} catch {
+			// Link cursor detection degrades to arrow when Accessibility is unavailable.
+		}
+
+		const helperPath = findMacCursorHelperPath();
+		if (!helperPath) {
+			this.startPositionOnlyFallback();
+			return;
+		}
+
+		const child = spawn(
+			helperPath,
+			[
+				JSON.stringify({
+					sampleIntervalMs: this.options.sampleIntervalMs,
+				}),
+			],
+			{
+				stdio: ["ignore", "pipe", "pipe"],
+			},
+		);
+		this.process = child;
+
+		child.stdout.setEncoding("utf8");
+		child.stdout.on("data", (chunk: string) => this.handleStdoutChunk(chunk));
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (chunk: string) => {
+			const message = chunk.trim();
+			if (message) {
+				console.error("[cursor-macos]", message);
+			}
+		});
+		child.once("exit", (code, signal) => {
+			this.rejectReady(
+				new Error(`macOS cursor helper exited before ready (code=${code}, signal=${signal})`),
+			);
+			this.process = null;
+		});
+		child.once("error", (error) => {
+			this.rejectReady(error);
+			this.process = null;
+		});
+
+		try {
+			await this.waitUntilReady();
+		} catch (error) {
+			this.killHelperProcess(child);
+			this.process = null;
+			console.warn("[cursor-macos] falling back to position-only cursor telemetry:", error);
+			this.startPositionOnlyFallback();
+		}
+	}
+
+	async stop(): Promise<CursorRecordingData> {
+		const child = this.process;
+		this.process = null;
+		this.clearReadyState();
+
+		if (this.fallbackInterval) {
+			clearInterval(this.fallbackInterval);
+			this.fallbackInterval = null;
+		}
+
+		if (child) {
+			this.killHelperProcess(child);
+		}
+
+		return {
+			version: 2,
+			provider: "none",
+			samples: this.samples,
+			assets: [],
+		};
+	}
+
+	private startPositionOnlyFallback() {
+		this.captureSample(Date.now(), null, false, false, false);
+		this.fallbackInterval = setInterval(() => {
+			this.captureSample(Date.now(), null, false, false, false);
+		}, this.options.sampleIntervalMs);
+	}
+
+	private handleStdoutChunk(chunk: string) {
+		this.lineBuffer += chunk;
+		const lines = this.lineBuffer.split(/\r?\n/);
+		this.lineBuffer = lines.pop() ?? "";
+
+		for (const line of lines) {
+			const trimmedLine = line.trim();
+			if (!trimmedLine) {
+				continue;
+			}
+
+			try {
+				this.handleEvent(JSON.parse(trimmedLine) as MacCursorEvent);
+			} catch (error) {
+				console.error("Failed to parse macOS cursor helper output:", error, trimmedLine);
+			}
+		}
+	}
+
+	private handleEvent(payload: MacCursorEvent) {
+		if (payload.type === "ready") {
+			if (payload.accessibilityTrusted === false) {
+				console.warn(
+					"[cursor-macos] Accessibility is not trusted; cursor shape detection will be arrow-only.",
+				);
+			}
+			this.resolveReady();
+			return;
+		}
+
+		if (payload.type === "sample") {
+			this.captureSample(
+				payload.timestampMs,
+				normalizeCursorType(payload.cursorType),
+				payload.leftButtonDown === true,
+				payload.leftButtonPressed === true,
+				payload.leftButtonReleased === true,
+			);
+		}
+	}
+
+	private captureSample(
+		timestampMs: number,
+		cursorType: NativeCursorType | null,
+		leftButtonDown: boolean,
+		leftButtonPressed: boolean,
+		leftButtonReleased: boolean,
+	) {
+		const cursor = screen.getCursorScreenPoint();
+		const bounds = this.options.getDisplayBounds() ?? screen.getDisplayNearestPoint(cursor).bounds;
+		const width = Math.max(1, bounds.width);
+		const height = Math.max(1, bounds.height);
+		const normalizedX = (cursor.x - bounds.x) / width;
+		const normalizedY = (cursor.y - bounds.y) / height;
+		const isOutsideDisplay =
+			normalizedX < 0 || normalizedX > 1 || normalizedY < 0 || normalizedY > 1;
+		// Fast swipes that briefly exit the display (<THRESHOLD samples) are handled by
+		// clip-path — the cursor clips to the canvas edge instead of snapping invisible.
+		// Sustained exits (≥THRESHOLD samples, ≈100ms) mark visible=false to prevent
+		// ghost cursors and motion trails from multi-display movement.
+		if (isOutsideDisplay) {
+			this.consecutiveOutsideSamples++;
+		} else {
+			this.consecutiveOutsideSamples = 0;
+		}
+		const visible =
+			this.consecutiveOutsideSamples < MacNativeCursorRecordingSession.OUTSIDE_HIDE_THRESHOLD;
+		const interactionType =
+			leftButtonPressed || (leftButtonDown && !this.previousLeftButtonDown)
+				? "click"
+				: leftButtonReleased || (!leftButtonDown && this.previousLeftButtonDown)
+					? "mouseup"
+					: "move";
+		this.previousLeftButtonDown = leftButtonDown;
+
+		this.samples.push({
+			timeMs: Math.max(0, timestampMs - this.startTimeMs),
+			cx: clamp(normalizedX, 0, 1),
+			cy: clamp(normalizedY, 0, 1),
+			visible,
+			interactionType,
+			...(cursorType ? { cursorType } : {}),
+		});
+
+		if (this.samples.length > this.options.maxSamples) {
+			this.samples.shift();
+		}
+	}
+
+	private waitUntilReady() {
+		return new Promise<void>((resolve, reject) => {
+			this.readyResolve = resolve;
+			this.readyReject = reject;
+			this.readyTimer = setTimeout(() => {
+				this.rejectReady(new Error("Timed out waiting for macOS cursor helper"));
+			}, READY_TIMEOUT_MS);
+		});
+	}
+
+	private resolveReady() {
+		const resolve = this.readyResolve;
+		this.clearReadyState();
+		resolve?.();
+	}
+
+	private rejectReady(error: Error) {
+		const reject = this.readyReject;
+		this.clearReadyState();
+		reject?.(error);
+	}
+
+	private clearReadyState() {
+		if (this.readyTimer) {
+			clearTimeout(this.readyTimer);
+			this.readyTimer = null;
+		}
+		this.readyResolve = null;
+		this.readyReject = null;
+	}
+
+	private killHelperProcess(child: ChildProcessByStdio<null, Readable, Readable>) {
+		if (child.killed) {
+			return;
+		}
+
+		child.kill("SIGTERM");
+		setTimeout(() => {
+			if (!child.killed) {
+				child.kill("SIGKILL");
+			}
+		}, 500).unref();
+	}
+}

electron/native-bridge/cursor/recording/session.ts

@@ -0,0 +1,6 @@
+import type { CursorRecordingData } from "../../../../src/native/contracts";
+
+export interface CursorRecordingSession {
+	start(): Promise<void>;
+	stop(): Promise<CursorRecordingData>;
+}

electron/native-bridge/cursor/recording/telemetryRecordingSession.ts

@@ -0,0 +1,63 @@
+import { type Rectangle, screen } from "electron";
+import type { CursorRecordingData, CursorRecordingSample } from "../../../../src/native/contracts";
+import type { CursorRecordingSession } from "./session";
+
+interface TelemetryRecordingSessionOptions {
+	getDisplayBounds: () => Rectangle | null;
+	maxSamples: number;
+	sampleIntervalMs: number;
+	startTimeMs?: number;
+}
+
+function clamp(value: number, min: number, max: number) {
+	return Math.min(max, Math.max(min, value));
+}
+
+export class TelemetryRecordingSession implements CursorRecordingSession {
+	private samples: CursorRecordingSample[] = [];
+	private interval: NodeJS.Timeout | null = null;
+	private startTimeMs = 0;
+
+	constructor(private readonly options: TelemetryRecordingSessionOptions) {}
+
+	async start(): Promise<void> {
+		this.samples = [];
+		this.startTimeMs = this.options.startTimeMs ?? Date.now();
+		this.captureSample();
+		this.interval = setInterval(() => {
+			this.captureSample();
+		}, this.options.sampleIntervalMs);
+	}
+
+	async stop(): Promise<CursorRecordingData> {
+		if (this.interval) {
+			clearInterval(this.interval);
+			this.interval = null;
+		}
+
+		return {
+			version: 2,
+			provider: "none",
+			samples: this.samples,
+			assets: [],
+		};
+	}
+
+	private captureSample() {
+		const cursor = screen.getCursorScreenPoint();
+		const display = this.options.getDisplayBounds() ?? screen.getDisplayNearestPoint(cursor).bounds;
+		const width = Math.max(1, display.width);
+		const height = Math.max(1, display.height);
+
+		this.samples.push({
+			timeMs: Math.max(0, Date.now() - this.startTimeMs),
+			cx: clamp((cursor.x - display.x) / width, 0, 1),
+			cy: clamp((cursor.y - display.y) / height, 0, 1),
+			visible: true,
+		});
+
+		if (this.samples.length > this.options.maxSamples) {
+			this.samples.shift();
+		}
+	}
+}

electron/native-bridge/cursor/recording/windowsNativeRecordingSession.ts

@@ -0,0 +1,326 @@
+import { type ChildProcessByStdio, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Readable } from "node:stream";
+import { app, screen } from "electron";
+import { parseWindowHandleFromSourceId } from "../../../../src/lib/nativeWindowsRecording";
+import type {
+	CursorRecordingData,
+	CursorRecordingSample,
+	NativeCursorAsset,
+} from "../../../../src/native/contracts";
+import type { CursorRecordingSession } from "./session";
+import type {
+	WindowsCursorEvent,
+	WindowsNativeRecordingSessionOptions,
+} from "./windowsNativeRecordingSession.types";
+
+function getCursorSamplerCandidates(): string[] {
+	const envPath = process.env.OPENSCREEN_CURSOR_SAMPLER_EXE?.trim();
+	const archTag = process.arch === "arm64" ? "win32-arm64" : "win32-x64";
+	const resolve = (...segs: string[]) => {
+		const p = join(app.getAppPath(), ...segs);
+		return app.isPackaged ? p.replace(/\.asar([/\\])/, ".asar.unpacked$1") : p;
+	};
+	return [
+		envPath,
+		resolve("electron", "native", "wgc-capture", "build", "cursor-sampler.exe"),
+		resolve("electron", "native", "bin", archTag, "cursor-sampler.exe"),
+	].filter((c): c is string => Boolean(c));
+}
+
+function findCursorSamplerPath(): string | null {
+	for (const candidate of getCursorSamplerCandidates()) {
+		if (existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+
+const READY_TIMEOUT_MS = 5_000;
+
+interface NormalizedSample {
+	sample: CursorRecordingSample;
+	withinBounds: boolean;
+}
+
+export class WindowsNativeRecordingSession implements CursorRecordingSession {
+	private assets = new Map<string, NativeCursorAsset>();
+	private samples: CursorRecordingSample[] = [];
+	private process: ChildProcessByStdio<null, Readable, Readable> | null = null;
+	private lineBuffer = "";
+	private startTimeMs = 0;
+	private readyResolve: (() => void) | null = null;
+	private readyReject: ((error: Error) => void) | null = null;
+	private readyTimer: NodeJS.Timeout | null = null;
+	private sampleCount = 0;
+	private outOfBoundsSampleCount = 0;
+	private previousLeftButtonDown = false;
+
+	constructor(private readonly options: WindowsNativeRecordingSessionOptions) {}
+
+	async start(): Promise<void> {
+		this.assets.clear();
+		this.samples = [];
+		this.lineBuffer = "";
+		this.startTimeMs = this.options.startTimeMs ?? Date.now();
+		this.sampleCount = 0;
+		this.outOfBoundsSampleCount = 0;
+		this.previousLeftButtonDown = false;
+
+		const helperPath = findCursorSamplerPath();
+		if (!helperPath) {
+			throw new Error("Windows cursor sampler helper is not available.");
+		}
+
+		const windowHandle = parseWindowHandleFromSourceId(this.options.sourceId);
+		const args = [String(this.options.sampleIntervalMs)];
+		if (windowHandle) args.push(windowHandle);
+
+		const child = spawn(helperPath, args, {
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+		});
+
+		this.process = child;
+		this.logDiagnostic("spawn", {
+			pid: child.pid ?? null,
+			sampleIntervalMs: this.options.sampleIntervalMs,
+			sourceId: this.options.sourceId ?? null,
+			windowHandle,
+		});
+
+		child.stdout.setEncoding("utf8");
+		child.stdout.on("data", (chunk: string) => {
+			this.handleStdoutChunk(chunk);
+		});
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (chunk: string) => {
+			const message = chunk.trim();
+			if (message) {
+				this.logDiagnostic("stderr", { message });
+			}
+			console.error("[cursor-native]", message);
+		});
+		child.once("exit", (code, signal) => {
+			this.logDiagnostic("exit", {
+				code,
+				signal,
+				sampleCount: this.sampleCount,
+				assetCount: this.assets.size,
+				outOfBoundsSampleCount: this.outOfBoundsSampleCount,
+			});
+			this.rejectReady(
+				new Error(`Windows cursor helper exited before ready (code=${code}, signal=${signal})`),
+			);
+		});
+		child.once("error", (error) => {
+			this.logDiagnostic("process-error", { message: error.message });
+			this.rejectReady(error);
+		});
+
+		try {
+			await this.waitUntilReady();
+		} catch (error) {
+			this.terminateHelperProcess();
+			throw error;
+		}
+	}
+
+	async stop(): Promise<CursorRecordingData> {
+		const child = this.process;
+		this.process = null;
+		this.clearReadyState();
+
+		this.killHelperProcess(child);
+
+		this.logDiagnostic("stop", {
+			sampleCount: this.sampleCount,
+			assetCount: this.assets.size,
+			outOfBoundsSampleCount: this.outOfBoundsSampleCount,
+		});
+
+		return {
+			version: 2,
+			provider: this.assets.size > 0 ? "native" : "none",
+			samples: this.samples,
+			assets: [...this.assets.values()],
+		};
+	}
+
+	private handleStdoutChunk(chunk: string) {
+		this.lineBuffer += chunk;
+		const lines = this.lineBuffer.split(/\r?\n/);
+		this.lineBuffer = lines.pop() ?? "";
+
+		for (const line of lines) {
+			const trimmedLine = line.trim();
+			if (!trimmedLine) {
+				continue;
+			}
+
+			try {
+				const payload = JSON.parse(trimmedLine) as WindowsCursorEvent;
+				this.handleEvent(payload);
+			} catch (error) {
+				console.error("Failed to parse Windows cursor helper output:", error, trimmedLine);
+			}
+		}
+	}
+
+	private handleEvent(payload: WindowsCursorEvent) {
+		if (payload.type === "error") {
+			this.logDiagnostic("helper-error", { message: payload.message });
+			console.error("Windows cursor helper error:", payload.message);
+			this.failHelper(new Error(payload.message));
+			return;
+		}
+
+		if (payload.type === "ready") {
+			this.logDiagnostic("ready", { timestampMs: payload.timestampMs });
+			this.resolveReady();
+			return;
+		}
+
+		if (payload.asset?.id && !this.assets.has(payload.asset.id)) {
+			const assetDisplay = screen.getDisplayNearestPoint({ x: payload.x, y: payload.y });
+			this.assets.set(payload.asset.id, {
+				id: payload.asset.id,
+				platform: "win32",
+				imageDataUrl: payload.asset.imageDataUrl,
+				width: payload.asset.width,
+				height: payload.asset.height,
+				hotspotX: payload.asset.hotspotX,
+				hotspotY: payload.asset.hotspotY,
+				scaleFactor: assetDisplay.scaleFactor,
+				cursorType: payload.asset.cursorType ?? payload.cursorType ?? null,
+			});
+			this.logDiagnostic("asset", {
+				id: payload.asset.id,
+				width: payload.asset.width,
+				height: payload.asset.height,
+				hotspotX: payload.asset.hotspotX,
+				hotspotY: payload.asset.hotspotY,
+				scaleFactor: assetDisplay.scaleFactor,
+			});
+		}
+
+		const normalized = this.normalizeSample(payload);
+		this.sampleCount += 1;
+		if (!normalized.withinBounds) {
+			this.outOfBoundsSampleCount += 1;
+		}
+
+		this.samples.push(normalized.sample);
+
+		if (this.samples.length > this.options.maxSamples) {
+			this.samples.shift();
+		}
+	}
+
+	private normalizeSample(
+		payload: Extract<WindowsCursorEvent, { type: "sample" }>,
+	): NormalizedSample {
+		const bounds =
+			payload.bounds ?? this.options.getDisplayBounds() ?? screen.getPrimaryDisplay().bounds;
+		const width = Math.max(1, bounds.width);
+		const height = Math.max(1, bounds.height);
+		const normalizedX = (payload.x - bounds.x) / width;
+		const normalizedY = (payload.y - bounds.y) / height;
+		const withinBounds =
+			normalizedX >= 0 && normalizedX <= 1 && normalizedY >= 0 && normalizedY <= 1;
+		const leftButtonDown = payload.leftButtonDown === true;
+		const leftButtonPressed = payload.leftButtonPressed === true;
+		const leftButtonReleased = payload.leftButtonReleased === true;
+		const interactionType =
+			leftButtonPressed || (leftButtonDown && !this.previousLeftButtonDown)
+				? "click"
+				: leftButtonReleased || (!leftButtonDown && this.previousLeftButtonDown)
+					? "mouseup"
+					: "move";
+		this.previousLeftButtonDown = leftButtonDown;
+
+		if (this.sampleCount === 0 || (!withinBounds && this.outOfBoundsSampleCount === 0)) {
+			this.logDiagnostic("sample", {
+				rawX: payload.x,
+				rawY: payload.y,
+				normalizedX,
+				normalizedY,
+				visible: payload.visible,
+				withinBounds,
+				bounds,
+				handle: payload.handle,
+			});
+		}
+
+		return {
+			withinBounds,
+			sample: {
+				timeMs: Math.max(0, payload.timestampMs - this.startTimeMs),
+				cx: normalizedX,
+				cy: normalizedY,
+				assetId: payload.handle,
+				visible: payload.visible && withinBounds,
+				cursorType: payload.cursorType ?? payload.asset?.cursorType ?? null,
+				interactionType,
+			},
+		};
+	}
+
+	private waitUntilReady() {
+		return new Promise<void>((resolve, reject) => {
+			this.readyResolve = resolve;
+			this.readyReject = reject;
+			this.readyTimer = setTimeout(() => {
+				this.rejectReady(new Error("Timed out waiting for Windows cursor helper readiness"));
+			}, READY_TIMEOUT_MS);
+		});
+	}
+
+	private resolveReady() {
+		const resolve = this.readyResolve;
+		this.clearReadyState();
+		resolve?.();
+	}
+
+	private rejectReady(error: Error) {
+		const reject = this.readyReject;
+		this.clearReadyState();
+		reject?.(error);
+	}
+
+	private failHelper(error: Error) {
+		this.rejectReady(error);
+		this.terminateHelperProcess();
+	}
+
+	private terminateHelperProcess() {
+		const child = this.process;
+		this.process = null;
+		this.killHelperProcess(child);
+	}
+
+	private killHelperProcess(child: ChildProcessByStdio<null, Readable, Readable> | null) {
+		if (child && !child.killed) {
+			child.kill();
+		}
+	}
+
+	private clearReadyState() {
+		if (this.readyTimer) {
+			clearTimeout(this.readyTimer);
+			this.readyTimer = null;
+		}
+		this.readyResolve = null;
+		this.readyReject = null;
+	}
+
+	private logDiagnostic(event: string, data: Record<string, unknown>) {
+		console.info(
+			"[cursor-native][win32]",
+			JSON.stringify({
+				event,
+				...data,
+			}),
+		);
+	}
+}

electron/native-bridge/cursor/recording/windowsNativeRecordingSession.types.ts

@@ -0,0 +1,56 @@
+import type { Rectangle } from "electron";
+import type { NativeCursorType } from "../../../../src/native/contracts";
+
+export interface WindowsCursorSampleEvent {
+	type: "sample";
+	timestampMs: number;
+	x: number;
+	y: number;
+	visible: boolean;
+	handle: string | null;
+	cursorType?: NativeCursorType | null;
+	leftButtonDown?: boolean;
+	leftButtonPressed?: boolean;
+	leftButtonReleased?: boolean;
+	bounds?: {
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+	} | null;
+	asset: WindowsCursorAssetPayload | null;
+}
+
+export interface WindowsCursorReadyEvent {
+	type: "ready";
+	timestampMs: number;
+}
+
+export interface WindowsCursorErrorEvent {
+	type: "error";
+	timestampMs: number;
+	message: string;
+}
+
+export interface WindowsCursorAssetPayload {
+	id: string;
+	imageDataUrl: string;
+	width: number;
+	height: number;
+	hotspotX: number;
+	hotspotY: number;
+	cursorType?: NativeCursorType | null;
+}
+
+export type WindowsCursorEvent =
+	| WindowsCursorSampleEvent
+	| WindowsCursorReadyEvent
+	| WindowsCursorErrorEvent;
+
+export interface WindowsNativeRecordingSessionOptions {
+	getDisplayBounds: () => Rectangle | null;
+	maxSamples: number;
+	sampleIntervalMs: number;
+	sourceId?: string | null;
+	startTimeMs?: number;
+}

electron/native-bridge/cursor/telemetryCursorAdapter.ts

@@ -0,0 +1,49 @@
+import type { CursorCapabilities, CursorRecordingData } from "../../../src/native/contracts";
+import type { CursorNativeAdapter, CursorTelemetryLoadResult } from "./adapter";
+
+interface TelemetryCursorAdapterOptions {
+	loadRecordingData: (videoPath: string) => Promise<CursorRecordingData>;
+	resolveVideoPath: (videoPath?: string | null) => string | null;
+	loadTelemetry: (videoPath: string) => Promise<CursorTelemetryLoadResult>;
+}
+
+export class TelemetryCursorAdapter implements CursorNativeAdapter {
+	readonly kind = "none" as const;
+
+	constructor(private readonly options: TelemetryCursorAdapterOptions) {}
+
+	async getCapabilities(): Promise<CursorCapabilities> {
+		return {
+			telemetry: true,
+			systemAssets: false,
+			provider: this.kind,
+		};
+	}
+
+	async getRecordingData(videoPath?: string | null): Promise<CursorRecordingData> {
+		const resolvedVideoPath = this.options.resolveVideoPath(videoPath);
+		if (!resolvedVideoPath) {
+			return {
+				version: 2,
+				provider: this.kind,
+				samples: [],
+				assets: [],
+			};
+		}
+
+		return this.options.loadRecordingData(resolvedVideoPath);
+	}
+
+	async getTelemetry(videoPath?: string | null) {
+		const resolvedVideoPath = this.options.resolveVideoPath(videoPath);
+		if (!resolvedVideoPath) {
+			return {
+				success: false,
+				message: "No video path is available for cursor telemetry",
+				samples: [],
+			} satisfies CursorTelemetryLoadResult;
+		}
+
+		return this.options.loadTelemetry(resolvedVideoPath);
+	}
+}

electron/native-bridge/services/cursorService.ts

@@ -0,0 +1,46 @@
+import type {
+	CursorCapabilities,
+	CursorRecordingData,
+	CursorTelemetryPoint,
+} from "../../../src/native/contracts";
+import type { CursorNativeAdapter } from "../cursor/adapter";
+import type { NativeBridgeStateStore } from "../store";
+
+interface CursorServiceOptions {
+	store: NativeBridgeStateStore;
+	adapter: CursorNativeAdapter;
+}
+
+export class CursorService {
+	constructor(private readonly options: CursorServiceOptions) {}
+
+	async getCapabilities(): Promise<CursorCapabilities> {
+		const capabilities = await this.options.adapter.getCapabilities();
+		this.options.store.setCursorCapabilities(capabilities);
+		return capabilities;
+	}
+
+	async getTelemetry(videoPath?: string | null): Promise<CursorTelemetryPoint[]> {
+		const result = await this.options.adapter.getTelemetry(videoPath);
+		if (!result.success) {
+			throw new Error(result.message || result.error || "Failed to load cursor telemetry");
+		}
+
+		const resolvedVideoPath = videoPath ?? this.options.store.getState().project.currentVideoPath;
+		if (resolvedVideoPath) {
+			this.options.store.markCursorTelemetryLoaded(resolvedVideoPath, result.samples.length);
+		}
+
+		return result.samples;
+	}
+
+	async getRecordingData(videoPath?: string | null): Promise<CursorRecordingData> {
+		const data = await this.options.adapter.getRecordingData(videoPath);
+		const resolvedVideoPath = videoPath ?? this.options.store.getState().project.currentVideoPath;
+		if (resolvedVideoPath) {
+			this.options.store.markCursorTelemetryLoaded(resolvedVideoPath, data.samples.length);
+		}
+
+		return data;
+	}
+}

electron/native-bridge/services/projectService.ts

@@ -0,0 +1,80 @@
+import type {
+	ProjectContext,
+	ProjectFileResult,
+	ProjectPathResult,
+} from "../../../src/native/contracts";
+import type { NativeBridgeStateStore } from "../store";
+
+interface ProjectServiceOptions {
+	store: NativeBridgeStateStore;
+	getCurrentProjectPath: () => string | null;
+	getCurrentVideoPath: () => string | null;
+	saveProjectFile: (
+		projectData: unknown,
+		suggestedName?: string,
+		existingProjectPath?: string,
+	) => Promise<ProjectFileResult>;
+	loadProjectFile: () => Promise<ProjectFileResult>;
+	loadCurrentProjectFile: () => Promise<ProjectFileResult>;
+	setCurrentVideoPath: (path: string) => ProjectPathResult | Promise<ProjectPathResult>;
+	getCurrentVideoPathResult: () => ProjectPathResult;
+	clearCurrentVideoPath: () => ProjectPathResult;
+}
+
+export class ProjectService {
+	constructor(private readonly options: ProjectServiceOptions) {}
+
+	getCurrentContext(): ProjectContext {
+		const context = {
+			currentProjectPath: this.options.getCurrentProjectPath(),
+			currentVideoPath: this.options.getCurrentVideoPath(),
+		};
+
+		this.options.store.setProjectContext(context);
+		return context;
+	}
+
+	async saveProjectFile(
+		projectData: unknown,
+		suggestedName?: string,
+		existingProjectPath?: string,
+	) {
+		const result = await this.options.saveProjectFile(
+			projectData,
+			suggestedName,
+			existingProjectPath,
+		);
+		this.getCurrentContext();
+		return result;
+	}
+
+	async loadProjectFile() {
+		const result = await this.options.loadProjectFile();
+		this.getCurrentContext();
+		return result;
+	}
+
+	async loadCurrentProjectFile() {
+		const result = await this.options.loadCurrentProjectFile();
+		this.getCurrentContext();
+		return result;
+	}
+
+	async setCurrentVideoPath(path: string) {
+		const result = await this.options.setCurrentVideoPath(path);
+		this.getCurrentContext();
+		return result;
+	}
+
+	getCurrentVideoPath() {
+		const result = this.options.getCurrentVideoPathResult();
+		this.getCurrentContext();
+		return result;
+	}
+
+	clearCurrentVideoPath() {
+		const result = this.options.clearCurrentVideoPath();
+		this.getCurrentContext();
+		return result;
+	}
+}

electron/native-bridge/services/systemService.ts

@@ -0,0 +1,43 @@
+import type {
+	CursorCapabilities,
+	NativePlatform,
+	SystemCapabilities,
+} from "../../../src/native/contracts";
+import { NATIVE_BRIDGE_VERSION } from "../../../src/native/contracts";
+import type { NativeBridgeStateStore } from "../store";
+
+interface SystemServiceOptions {
+	store: NativeBridgeStateStore;
+	getPlatform: () => NativePlatform;
+	getAssetBasePath: () => string | null;
+	getCursorCapabilities: () => Promise<CursorCapabilities>;
+}
+
+export class SystemService {
+	constructor(private readonly options: SystemServiceOptions) {}
+
+	getPlatform() {
+		return this.options.getPlatform();
+	}
+
+	getAssetBasePath() {
+		return this.options.getAssetBasePath();
+	}
+
+	async getCapabilities(): Promise<SystemCapabilities> {
+		const platform = this.getPlatform();
+		const cursorCapabilities = await this.options.getCursorCapabilities();
+
+		const capabilities: SystemCapabilities = {
+			bridgeVersion: NATIVE_BRIDGE_VERSION,
+			platform,
+			cursor: cursorCapabilities,
+			project: {
+				currentContext: true,
+			},
+		};
+
+		this.options.store.setSystemCapabilities(capabilities);
+		return capabilities;
+	}
+}

electron/native-bridge/store.ts

@@ -0,0 +1,88 @@
+import type {
+	CursorCapabilities,
+	NativePlatform,
+	ProjectContext,
+	SystemCapabilities,
+} from "../../src/native/contracts";
+
+export interface NativeBridgeState {
+	system: {
+		platform: NativePlatform;
+		capabilities: SystemCapabilities | null;
+	};
+	project: ProjectContext;
+	cursor: {
+		capabilities: CursorCapabilities | null;
+		lastTelemetryLoad: {
+			videoPath: string;
+			sampleCount: number;
+			loadedAt: number;
+		} | null;
+	};
+}
+
+export class NativeBridgeStateStore {
+	private state: NativeBridgeState;
+
+	constructor(platform: NativePlatform) {
+		this.state = {
+			system: {
+				platform,
+				capabilities: null,
+			},
+			project: {
+				currentProjectPath: null,
+				currentVideoPath: null,
+			},
+			cursor: {
+				capabilities: null,
+				lastTelemetryLoad: null,
+			},
+		};
+	}
+
+	getState() {
+		return this.state;
+	}
+
+	setProjectContext(project: ProjectContext) {
+		this.state = {
+			...this.state,
+			project,
+		};
+	}
+
+	setSystemCapabilities(capabilities: SystemCapabilities) {
+		this.state = {
+			...this.state,
+			system: {
+				...this.state.system,
+				capabilities,
+			},
+		};
+	}
+
+	setCursorCapabilities(capabilities: CursorCapabilities) {
+		this.state = {
+			...this.state,
+			cursor: {
+				...this.state.cursor,
+				capabilities,
+			},
+		};
+	}
+
+	markCursorTelemetryLoaded(videoPath: string, sampleCount: number) {
+		this.state = {
+			...this.state,
+			cursor: {
+				...this.state.cursor,
+				lastTelemetryLoad: {
+					videoPath,
+					sampleCount,
+					loadedAt: Date.now(),
+				},
+			},
+		};
+	}
+}

electron/native/README.md

@@ -0,0 +1,111 @@
+# Native capture helpers
+
+## macOS
+
+macOS native recording will use a ScreenCaptureKit helper with the same process boundary as the Windows WGC helper:
+
+1. Electron resolves the selected source, output paths, and user-selected devices.
+2. The helper receives one structured JSON request.
+3. The helper owns ScreenCaptureKit/AVFoundation capture, timing, encoding, and muxing.
+4. Electron persists the resulting media/session manifest and reports helper errors explicitly.
+
+Helper locations:
+
+1. `OPENSCREEN_SCK_CAPTURE_EXE`, for local development and diagnostics.
+2. `electron/native/screencapturekit/build/openscreen-screencapturekit-helper`, for locally built Swift output.
+3. `electron/native/bin/darwin-arm64/openscreen-screencapturekit-helper` or `electron/native/bin/darwin-x64/openscreen-screencapturekit-helper`, for packaged prebuilt helpers.
+
+The macOS cursor-shape helper is resolved from `OPENSCREEN_MAC_CURSOR_HELPER_EXE` first, then the matching `openscreen-macos-cursor-helper` binary in the same local build and packaged `electron/native/bin/darwin-${arch}` directories.
+
+Build the macOS helper with:
+
+```bash
+npm run build:native:mac
+```
+
+On non-macOS hosts this command exits successfully and does not affect Windows/Linux development. On macOS it builds the Swift package at `electron/native/screencapturekit`, writes the development binaries to `electron/native/screencapturekit/build`, and copies redistributable binaries to `electron/native/bin/darwin-${arch}`.
+
+The current helper implementation supports display/window ScreenCaptureKit video capture, cursor exclusion through `SCStreamConfiguration.showsCursor`, H.264 encoding, MP4 muxing, and ScreenCaptureKit system audio. It also attempts native ScreenCaptureKit microphone capture when the running macOS version exposes that capability. Webcam recording currently stays as an Electron sidecar and is attached to the same recording session after the native screen capture stops.
+
+Electron exposes `is-native-mac-capture-available` for capability probing. It resolves the same helper locations listed above and reports `missing-helper` until a Swift helper binary is present. When available, macOS recording routes screen/window capture through the native helper so editable cursor recordings do not bake the system cursor into the video. Cursor positions are sampled in Electron; when the cursor helper is available and Accessibility is granted, samples are also tagged with link/text cursor hints such as `pointer`.
+
+See `docs/engineering/macos-native-recorder-roadmap.md` for the contract, rollout phases, and SSOT rules.
+
+## Windows
+
+Windows native recording is resolved from one of these locations:
+
+1. `OPENSCREEN_WGC_CAPTURE_EXE`, for local development and diagnostics.
+2. `electron/native/wgc-capture/build/wgc-capture.exe`, for a locally built Ninja helper.
+3. `electron/native/wgc-capture/build/Release/wgc-capture.exe`, for a locally built multi-config helper.
+4. `electron/native/bin/win32-x64/wgc-capture.exe` or `electron/native/bin/win32-arm64/wgc-capture.exe`, for packaged prebuilt helpers.
+
+Build the Windows helper with:
+
+```powershell
+npm run build:native:win
+```
+
+The build writes the CMake output to `electron/native/wgc-capture/build/wgc-capture.exe` and copies the redistributable binary to `electron/native/bin/win32-x64/wgc-capture.exe`.
+
+The helper contract is process-based: the app starts the process with one JSON argument and sends commands on stdin. `stop\n` finalizes the recording. During migration the helper prints both newline-delimited JSON events and the legacy text messages `Recording started` / `Recording stopped. Output path: <path>`.
+
+Current V2 JSON shape:
+
+```json
+{
+  "schemaVersion": 2,
+  "recordingId": 123,
+  "sourceType": "display",
+  "sourceId": "screen:0:0",
+  "displayId": 1,
+  "windowHandle": null,
+  "outputPath": "C:\\path\\recording-123.mp4",
+  "videoWidth": 1920,
+  "videoHeight": 1080,
+  "fps": 60,
+  "captureSystemAudio": false,
+  "captureMic": false,
+  "microphoneDeviceId": "default",
+  "microphoneDeviceName": "Microphone (NVIDIA Broadcast)",
+  "microphoneGain": 1.4,
+  "webcamEnabled": true,
+  "webcamDeviceId": "default",
+  "webcamDeviceName": "Camera (NVIDIA Broadcast)",
+  "webcamWidth": 1280,
+  "webcamHeight": 720,
+  "webcamFps": 30,
+  "outputs": {
+    "screenPath": "C:\\path\\recording-123.mp4"
+  }
+}
+```
+
+The current helper implementation supports display/window video capture, system audio loopback, selected-microphone capture, Media Foundation webcam capture, and a DirectShow webcam fallback for virtual cameras that are not exposed through Media Foundation. Webcam frames are currently composed into the primary MP4 as a bottom-right picture-in-picture overlay. Browser `deviceId` values do not always map to Media Foundation symbolic links or WASAPI endpoint IDs, so the renderer passes both browser IDs and user-visible device names. For microphones, the helper tries the requested WASAPI endpoint ID first, then resolves an active capture endpoint by `microphoneDeviceName`, then falls back to the default endpoint. For webcams, Electron resolves a matching DirectShow filter CLSID for the selected label; the helper uses Media Foundation first, then that exact DirectShow filter when the requested camera is absent from Media Foundation.
+
+Smoke-test the helper with:
+
+```powershell
+npm run test:wgc-helper:win
+npm run test:wgc-window:win
+npm run test:wgc-audio:win
+npm run test:wgc-mic:win
+npm run test:wgc-mixed-audio:win
+npm run test:wgc-webcam:win
+```
+
+To validate a specific native webcam manually:
+
+```powershell
+$env:OPENSCREEN_WGC_TEST_WEBCAM_DEVICE_NAME = "NVIDIA Broadcast"
+npm run test:wgc-webcam:win
+Remove-Item Env:OPENSCREEN_WGC_TEST_WEBCAM_DEVICE_NAME
+```
+
+To validate a specific native microphone manually:
+
+```powershell
+$env:OPENSCREEN_WGC_TEST_MICROPHONE_DEVICE_NAME = "Microphone (NVIDIA Broadcast)"
+npm run test:wgc-mic:win
+Remove-Item Env:OPENSCREEN_WGC_TEST_MICROPHONE_DEVICE_NAME
+```

electron/native/screencapturekit/Package.swift

@@ -0,0 +1,30 @@
+// swift-tools-version: 5.9
+
+import PackageDescription
+
+let package = Package(
+	name: "OpenScreenScreenCaptureKitHelper",
+	platforms: [
+		.macOS(.v13)
+	],
+	products: [
+		.executable(
+			name: "openscreen-screencapturekit-helper",
+			targets: ["OpenScreenScreenCaptureKitHelper"]
+		),
+		.executable(
+			name: "openscreen-macos-cursor-helper",
+			targets: ["OpenScreenMacOSCursorHelper"]
+		)
+	],
+	targets: [
+		.executableTarget(
+			name: "OpenScreenScreenCaptureKitHelper",
+			path: "Sources/OpenScreenScreenCaptureKitHelper"
+		),
+		.executableTarget(
+			name: "OpenScreenMacOSCursorHelper",
+			path: "Sources/OpenScreenMacOSCursorHelper"
+		)
+	]
+)

electron/native/screencapturekit/Sources/OpenScreenMacOSCursorHelper/main.swift

@@ -0,0 +1,268 @@
+import AppKit
+import ApplicationServices
+import Foundation
+
+struct CursorHelperRequest: Decodable {
+	let sampleIntervalMs: Int?
+}
+
+final class MouseButtonTracker {
+	private let lock = NSLock()
+	private var leftDownCount = 0
+	private var leftUpCount = 0
+	private var eventTap: CFMachPort?
+	private var runLoopSource: CFRunLoopSource?
+
+	struct Events {
+		let leftDownCount: Int
+		let leftUpCount: Int
+	}
+
+	func start() -> Bool {
+		let mask =
+			(1 << CGEventType.leftMouseDown.rawValue) |
+			(1 << CGEventType.leftMouseUp.rawValue)
+		guard let tap = CGEvent.tapCreate(
+			tap: .cgSessionEventTap,
+			place: .headInsertEventTap,
+			options: .listenOnly,
+			eventsOfInterest: CGEventMask(mask),
+			callback: { _, type, event, userInfo in
+				if let userInfo {
+					let tracker = Unmanaged<MouseButtonTracker>.fromOpaque(userInfo).takeUnretainedValue()
+					tracker.record(type)
+				}
+				return Unmanaged.passUnretained(event)
+			},
+			userInfo: UnsafeMutableRawPointer(Unmanaged.passUnretained(self).toOpaque())
+		) else {
+			return false
+		}
+
+		guard let source = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, tap, 0) else {
+			return false
+		}
+
+		eventTap = tap
+		runLoopSource = source
+		CFRunLoopAddSource(CFRunLoopGetCurrent(), source, .commonModes)
+		CGEvent.tapEnable(tap: tap, enable: true)
+		return true
+	}
+
+	func pump() {
+		CFRunLoopRunInMode(.defaultMode, 0.001, false)
+	}
+
+	func consume() -> Events {
+		lock.lock()
+		defer { lock.unlock() }
+		let events = Events(leftDownCount: leftDownCount, leftUpCount: leftUpCount)
+		leftDownCount = 0
+		leftUpCount = 0
+		return events
+	}
+
+	private func record(_ type: CGEventType) {
+		lock.lock()
+		defer { lock.unlock() }
+		if type == .tapDisabledByTimeout || type == .tapDisabledByUserInput {
+			reenableTap()
+			return
+		}
+		if type == .leftMouseDown {
+			leftDownCount += 1
+		} else if type == .leftMouseUp {
+			leftUpCount += 1
+		}
+	}
+
+	private func reenableTap() {
+		if let eventTap {
+			CGEvent.tapEnable(tap: eventTap, enable: true)
+		}
+	}
+}
+
+func emit(_ fields: [String: Any?]) {
+	let compacted = fields.compactMapValues { $0 }
+	if let data = try? JSONSerialization.data(withJSONObject: compacted, options: []),
+		let line = String(data: data, encoding: .utf8)
+	{
+		print(line)
+		fflush(stdout)
+	}
+}
+
+func stringAttribute(_ element: AXUIElement, _ attribute: String) -> String? {
+	var value: CFTypeRef?
+	let result = AXUIElementCopyAttributeValue(element, attribute as CFString, &value)
+	guard result == .success else {
+		return nil
+	}
+
+	return value as? String
+}
+
+func parentElement(_ element: AXUIElement) -> AXUIElement? {
+	var value: CFTypeRef?
+	let result = AXUIElementCopyAttributeValue(element, kAXParentAttribute as CFString, &value)
+	guard result == .success else {
+		return nil
+	}
+
+	guard CFGetTypeID(value) == AXUIElementGetTypeID() else {
+		return nil
+	}
+
+	return (value as! AXUIElement)
+}
+
+func roleDescription(_ element: AXUIElement) -> String? {
+	var value: CFTypeRef?
+	let result = AXUIElementCopyAttributeValue(element, kAXRoleDescriptionAttribute as CFString, &value)
+	guard result == .success else {
+		return nil
+	}
+
+	return value as? String
+}
+
+func actionNames(_ element: AXUIElement) -> [String] {
+	var value: CFArray?
+	let result = AXUIElementCopyActionNames(element, &value)
+	guard result == .success, let value else {
+		return []
+	}
+
+	return (value as NSArray).compactMap { $0 as? String }
+}
+func isTextInputRole(_ role: String?) -> Bool {
+	role == "AXTextField" ||
+		role == "AXTextArea" ||
+		role == "AXTextView" ||
+		role == "AXComboBox"
+}
+
+func isPointerRole(_ role: String?, _ subrole: String?, _ description: String?) -> Bool {
+	if role == "AXLink" ||
+		subrole?.localizedCaseInsensitiveContains("link") == true ||
+		description?.contains("link") == true
+	{
+		return true
+	}
+
+	return role == "AXButton" ||
+		role == "AXMenuButton" ||
+		role == "AXPopUpButton" ||
+		role == "AXCheckBox" ||
+		role == "AXRadioButton" ||
+		role == "AXSwitch" ||
+		role == "AXDisclosureTriangle" ||
+		role == "AXTab" ||
+		role == "AXMenuItem"
+}
+
+func cursorTypeForElement(_ element: AXUIElement) -> String? {
+	var current: AXUIElement? = element
+
+	for _ in 0..<5 {
+		guard let element = current else {
+			break
+		}
+
+		let role = stringAttribute(element, kAXRoleAttribute)
+		let subrole = stringAttribute(element, kAXSubroleAttribute)
+		let description = roleDescription(element)?.lowercased()
+
+		if isTextInputRole(role) {
+			return "text"
+		}
+
+		if isPointerRole(role, subrole, description) {
+			return "pointer"
+		}
+
+		current = parentElement(element)
+	}
+
+	return nil
+}
+
+func accessibilityPointForMouse() -> CGPoint {
+	let mouse = NSEvent.mouseLocation
+	let primaryHeight = NSScreen.screens.first?.frame.height ?? NSScreen.main?.frame.height ?? 0
+	return CGPoint(x: mouse.x, y: primaryHeight - mouse.y)
+}
+
+func currentCursorType() -> String? {
+	guard AXIsProcessTrusted() else {
+		return nil
+	}
+
+	let point = accessibilityPointForMouse()
+	let systemWide = AXUIElementCreateSystemWide()
+	var element: AXUIElement?
+	let result = AXUIElementCopyElementAtPosition(
+		systemWide,
+		Float(point.x),
+		Float(point.y),
+		&element
+	)
+
+	guard result == .success, let element else {
+		return "arrow"
+	}
+
+	return cursorTypeForElement(element) ?? "arrow"
+}
+
+func timestampMs() -> Int {
+	Int(Date().timeIntervalSince1970 * 1000)
+}
+
+func leftButtonDown() -> Bool {
+	CGEventSource.buttonState(.hidSystemState, button: .left)
+}
+
+func requestAccessibilityTrust() -> Bool {
+	let options = [
+		kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true
+	] as CFDictionary
+	return AXIsProcessTrustedWithOptions(options)
+}
+
+let request: CursorHelperRequest
+if CommandLine.arguments.count >= 2,
+	let data = CommandLine.arguments[1].data(using: .utf8),
+	let decoded = try? JSONDecoder().decode(CursorHelperRequest.self, from: data)
+{
+	request = decoded
+} else {
+	request = CursorHelperRequest(sampleIntervalMs: nil)
+}
+
+let intervalMs = max(8, request.sampleIntervalMs ?? 33)
+let accessibilityTrusted = requestAccessibilityTrust()
+let mouseTracker = MouseButtonTracker()
+let mouseTapReady = mouseTracker.start()
+emit([
+	"type": "ready",
+	"timestampMs": timestampMs(),
+	"accessibilityTrusted": accessibilityTrusted,
+	"mouseTapReady": mouseTapReady,
+])
+
+while true {
+	mouseTracker.pump()
+	let mouseEvents = mouseTracker.consume()
+	emit([
+		"type": "sample",
+		"timestampMs": timestampMs(),
+		"cursorType": currentCursorType(),
+		"leftButtonDown": leftButtonDown(),
+		"leftButtonPressed": mouseEvents.leftDownCount > 0,
+		"leftButtonReleased": mouseEvents.leftUpCount > 0,
+	])
+	Thread.sleep(forTimeInterval: Double(intervalMs) / 1000.0)
+}

electron/native/screencapturekit/Sources/OpenScreenScreenCaptureKitHelper/main.swift

@@ -0,0 +1,673 @@
+import AVFoundation
+import CoreGraphics
+import CoreMedia
+import Foundation
+import ScreenCaptureKit
+
+struct Rectangle: Decodable {
+	let x: Double
+	let y: Double
+	let width: Double
+	let height: Double
+}
+
+struct RecordingRequest: Decodable {
+	struct Source: Decodable {
+		let type: String
+		let sourceId: String
+		let displayId: UInt32?
+		let windowId: UInt32?
+		let bounds: Rectangle?
+	}
+
+	struct Video: Decodable {
+		let fps: Int
+		let width: Int
+		let height: Int
+		let bitrate: Int?
+		let hideSystemCursor: Bool
+	}
+
+	struct Audio: Decodable {
+		struct SystemAudio: Decodable {
+			let enabled: Bool
+		}
+
+		struct Microphone: Decodable {
+			let enabled: Bool
+			let deviceId: String?
+			let deviceName: String?
+			let gain: Double
+		}
+
+		let system: SystemAudio
+		let microphone: Microphone
+	}
+
+	struct Webcam: Decodable {
+		let enabled: Bool
+		let deviceId: String?
+		let deviceName: String?
+		let width: Int
+		let height: Int
+		let fps: Int
+	}
+
+	struct Cursor: Decodable {
+		let mode: String
+	}
+
+	struct Outputs: Decodable {
+		let screenPath: String
+		let manifestPath: String?
+	}
+
+	let schemaVersion: Int?
+	let recordingId: Int?
+	let source: Source
+	let video: Video
+	let audio: Audio
+	let webcam: Webcam
+	let cursor: Cursor
+	let outputs: Outputs
+}
+
+enum HelperError: Error, CustomStringConvertible {
+	case invalidArguments
+	case unsupportedMacOS
+	case unsupportedFeature(String)
+	case sourceNotFound(String)
+	case invalidSourceType(String)
+	case permissionDenied(String)
+	case writerSetupFailed(String)
+
+	var description: String {
+		switch self {
+		case .invalidArguments:
+			return "Expected one JSON recording request argument."
+		case .unsupportedMacOS:
+			return "ScreenCaptureKit recording requires macOS 13 or newer."
+		case .unsupportedFeature(let message):
+			return message
+		case .sourceNotFound(let message):
+			return message
+		case .invalidSourceType(let sourceType):
+			return "Unsupported source type: \(sourceType)."
+		case .permissionDenied(let message):
+			return message
+		case .writerSetupFailed(let message):
+			return message
+		}
+	}
+}
+
+func emit(_ fields: [String: Any]) {
+	if let data = try? JSONSerialization.data(withJSONObject: fields, options: []),
+		let line = String(data: data, encoding: .utf8)
+	{
+		print(line)
+		fflush(stdout)
+	}
+}
+
+func emitError(code: String, message: String) {
+	emit([
+		"event": "error",
+		"code": code,
+		"message": message,
+	])
+}
+
+@available(macOS 13.0, *)
+final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
+	private struct CaptureTarget {
+		let filter: SCContentFilter
+		let width: Int
+		let height: Int
+	}
+
+	private let request: RecordingRequest
+	private let sampleQueue = DispatchQueue(label: "app.openscreen.sck-helper.samples")
+	private let stateQueue = DispatchQueue(label: "app.openscreen.sck-helper.state")
+	private var stream: SCStream?
+	private var writer: AVAssetWriter?
+	private var videoInput: AVAssetWriterInput?
+	private var systemAudioInput: AVAssetWriterInput?
+	private var microphoneAudioInput: AVAssetWriterInput?
+	private var didStartWriting = false
+	private var didEmitRecordingStarted = false
+	private var isStopping = false
+	private var isPaused = false
+	private var pauseStartedAt: CMTime?
+	private var totalPausedDuration = CMTime.zero
+	private var nativeMicrophoneEnabled = false
+	private var outputWidth = 1920
+	private var outputHeight = 1080
+	private let microphoneOutputTypeRawValue = 2
+	private let hostClock = CMClockGetHostTimeClock()
+
+	init(request: RecordingRequest) {
+		self.request = request
+	}
+
+	func start() async throws {
+		try ensureRequestedPermissions()
+
+		let content = try await SCShareableContent.excludingDesktopWindows(
+			false,
+			onScreenWindowsOnly: true
+		)
+		let target = try makeCaptureTarget(from: content)
+		outputWidth = target.width
+		outputHeight = target.height
+		let configuration = makeStreamConfiguration()
+		let stream = SCStream(filter: target.filter, configuration: configuration, delegate: self)
+
+		try stream.addStreamOutput(self, type: .screen, sampleHandlerQueue: sampleQueue)
+		if request.audio.system.enabled {
+			try stream.addStreamOutput(self, type: .audio, sampleHandlerQueue: sampleQueue)
+		}
+		if nativeMicrophoneEnabled {
+			guard let microphoneOutputType = SCStreamOutputType(rawValue: microphoneOutputTypeRawValue) else {
+				throw HelperError.unsupportedFeature(
+					"Native microphone capture requires a macOS version with ScreenCaptureKit microphone output."
+				)
+			}
+			try stream.addStreamOutput(self, type: microphoneOutputType, sampleHandlerQueue: sampleQueue)
+		}
+		try setupWriter()
+
+		self.stream = stream
+		emit(["event": "ready", "schemaVersion": 1])
+		try await stream.startCapture()
+	}
+
+	func stop() async {
+		let shouldStop = stateQueue.sync {
+			if isStopping {
+				return false
+			}
+			isStopping = true
+			return true
+		}
+		if !shouldStop {
+			return
+		}
+
+		do {
+			try await stream?.stopCapture()
+		} catch {
+			emit([
+				"event": "warning",
+				"code": "stop-capture-failed",
+				"message": "\(error)",
+			])
+		}
+
+		await finishWriter()
+	}
+
+	func pause() {
+		let didPause = stateQueue.sync {
+			if isStopping || isPaused {
+				return false
+			}
+
+			isPaused = true
+			pauseStartedAt = CMClockGetTime(hostClock)
+			return true
+		}
+
+		if didPause {
+			emit([
+				"event": "recording-paused",
+				"timestampMs": Int(Date().timeIntervalSince1970 * 1000),
+			])
+		}
+	}
+
+	func resume() {
+		let didResume = stateQueue.sync {
+			if isStopping || !isPaused {
+				return false
+			}
+
+			if let pauseStartedAt {
+				let now = CMClockGetTime(hostClock)
+				totalPausedDuration = CMTimeAdd(
+					totalPausedDuration,
+					CMTimeSubtract(now, pauseStartedAt)
+				)
+			}
+			isPaused = false
+			pauseStartedAt = nil
+			return true
+		}
+
+		if didResume {
+			emit([
+				"event": "recording-resumed",
+				"timestampMs": Int(Date().timeIntervalSince1970 * 1000),
+			])
+		}
+	}
+
+	func stream(_ stream: SCStream, didStopWithError error: Error) {
+		emitError(code: "capture-stopped-with-error", message: "\(error)")
+		Task {
+			await stop()
+		}
+	}
+
+	func stream(_ stream: SCStream, didOutputSampleBuffer sampleBuffer: CMSampleBuffer, of type: SCStreamOutputType) {
+		guard CMSampleBufferDataIsReady(sampleBuffer) else {
+			return
+		}
+		let pauseState = currentPauseState()
+		if pauseState.paused {
+			return
+		}
+		guard let sampleBuffer = retimedSampleBuffer(sampleBuffer, subtracting: pauseState.offset) else {
+			return
+		}
+
+		if type == .audio {
+			appendAudioSampleBuffer(sampleBuffer, to: systemAudioInput)
+			return
+		}
+
+		if type.rawValue == microphoneOutputTypeRawValue {
+			appendAudioSampleBuffer(sampleBuffer, to: microphoneAudioInput)
+			return
+		}
+
+		guard type == .screen else {
+			return
+		}
+		guard isCompleteFrame(sampleBuffer) else {
+			return
+		}
+		guard let videoInput, let writer else {
+			return
+		}
+		let presentationTime = CMSampleBufferGetPresentationTimeStamp(sampleBuffer)
+		if !didStartWriting {
+			writer.startWriting()
+			writer.startSession(atSourceTime: presentationTime)
+			didStartWriting = true
+		}
+
+		if videoInput.isReadyForMoreMediaData {
+			if videoInput.append(sampleBuffer), !didEmitRecordingStarted {
+				didEmitRecordingStarted = true
+				emit([
+					"event": "recording-started",
+					"timestampMs": Int(Date().timeIntervalSince1970 * 1000),
+					"width": outputWidth,
+					"height": outputHeight,
+				])
+			}
+		}
+	}
+
+	private func ensureRequestedPermissions() throws {
+		if !CGPreflightScreenCaptureAccess() {
+			let granted = CGRequestScreenCaptureAccess()
+			if !granted {
+				throw HelperError.permissionDenied("Screen recording permission is required for ScreenCaptureKit capture.")
+			}
+		}
+
+		if request.audio.microphone.enabled {
+			switch AVCaptureDevice.authorizationStatus(for: .audio) {
+			case .authorized:
+				break
+			case .notDetermined:
+				let semaphore = DispatchSemaphore(value: 0)
+				AVCaptureDevice.requestAccess(for: .audio) { _ in
+					semaphore.signal()
+				}
+				let waitResult = semaphore.wait(timeout: .now() + 30)
+				if waitResult == .timedOut || AVCaptureDevice.authorizationStatus(for: .audio) != .authorized {
+					throw HelperError.permissionDenied("Microphone permission is required for native microphone capture.")
+				}
+			default:
+				throw HelperError.permissionDenied("Microphone permission is required for native microphone capture.")
+			}
+		}
+	}
+
+	private func makeCaptureTarget(from content: SCShareableContent) throws -> CaptureTarget {
+		switch request.source.type {
+		case "display":
+			guard let displayId = request.source.displayId else {
+				throw HelperError.sourceNotFound("Display capture requires source.displayId.")
+			}
+			guard let display = content.displays.first(where: { $0.displayID == displayId }) else {
+				throw HelperError.sourceNotFound("No ScreenCaptureKit display found for id \(displayId).")
+			}
+			let width = Int(CGDisplayPixelsWide(display.displayID))
+			let height = Int(CGDisplayPixelsHigh(display.displayID))
+			return CaptureTarget(
+				filter: SCContentFilter(display: display, excludingWindows: []),
+				width: clampCaptureDimension(width, fallback: request.video.width),
+				height: clampCaptureDimension(height, fallback: request.video.height)
+			)
+		case "window":
+			guard let windowId = request.source.windowId else {
+				throw HelperError.sourceNotFound("Window capture requires source.windowId.")
+			}
+			guard let window = content.windows.first(where: { $0.windowID == windowId }) else {
+				throw HelperError.sourceNotFound("No ScreenCaptureKit window found for id \(windowId).")
+			}
+			let candidateDisplay = content.displays.first {
+				$0.frame.intersects(window.frame) || $0.frame.contains(CGPoint(x: window.frame.midX, y: window.frame.midY))
+			}
+			let scaleFactor = Self.scaleFactor(for: candidateDisplay?.displayID ?? CGMainDisplayID())
+			let width = Int(window.frame.width) * scaleFactor
+			let height = Int(window.frame.height) * scaleFactor
+			return CaptureTarget(
+				filter: SCContentFilter(desktopIndependentWindow: window),
+				width: clampCaptureDimension(width, fallback: request.video.width),
+				height: clampCaptureDimension(height, fallback: request.video.height)
+			)
+		default:
+			throw HelperError.invalidSourceType(request.source.type)
+		}
+	}
+
+	private func makeStreamConfiguration() -> SCStreamConfiguration {
+		let configuration = SCStreamConfiguration()
+		configuration.width = outputWidth
+		configuration.height = outputHeight
+		configuration.minimumFrameInterval = CMTime(value: 1, timescale: CMTimeScale(max(1, request.video.fps)))
+		configuration.queueDepth = 6
+		configuration.showsCursor = !request.video.hideSystemCursor
+		configuration.pixelFormat = kCVPixelFormatType_32BGRA
+		configuration.sampleRate = 48_000
+		configuration.channelCount = 2
+		configuration.excludesCurrentProcessAudio = true
+		configuration.capturesAudio = request.audio.system.enabled
+
+		if request.audio.microphone.enabled {
+			guard supportsNativeMicrophoneCapture(streamConfig: configuration) else {
+				nativeMicrophoneEnabled = false
+				emit([
+					"event": "warning",
+					"code": "microphone-unavailable",
+					"message": "Native microphone capture requires ScreenCaptureKit microphone support on this macOS version.",
+				])
+				return configuration
+			}
+			nativeMicrophoneEnabled = true
+			configuration.capturesAudio = true
+			configuration.setValue(true, forKey: "captureMicrophone")
+			if let deviceId = resolveMicrophoneCaptureDeviceID() {
+				configuration.setValue(deviceId, forKey: "microphoneCaptureDeviceID")
+			}
+		} else {
+			nativeMicrophoneEnabled = false
+		}
+
+		return configuration
+	}
+
+	private func setupWriter() throws {
+		let outputUrl = URL(fileURLWithPath: request.outputs.screenPath)
+		try? FileManager.default.removeItem(at: outputUrl)
+		try FileManager.default.createDirectory(
+			at: outputUrl.deletingLastPathComponent(),
+			withIntermediateDirectories: true
+		)
+
+		let writer = try AVAssetWriter(outputURL: outputUrl, fileType: .mp4)
+		let settings: [String: Any] = [
+			AVVideoCodecKey: AVVideoCodecType.h264,
+			AVVideoWidthKey: outputWidth,
+			AVVideoHeightKey: outputHeight,
+			AVVideoCompressionPropertiesKey: [
+				AVVideoAverageBitRateKey: request.video.bitrate ?? 18_000_000,
+				AVVideoExpectedSourceFrameRateKey: request.video.fps,
+			],
+		]
+		let input = AVAssetWriterInput(mediaType: .video, outputSettings: settings)
+		input.expectsMediaDataInRealTime = true
+
+		guard writer.canAdd(input) else {
+			throw HelperError.writerSetupFailed("Unable to add H.264 video input to AVAssetWriter.")
+		}
+
+		writer.add(input)
+		self.writer = writer
+		self.videoInput = input
+
+		if request.audio.system.enabled {
+			systemAudioInput = try addAudioInput(to: writer, bitRate: 192_000)
+		}
+		if nativeMicrophoneEnabled {
+			microphoneAudioInput = try addAudioInput(to: writer, bitRate: 128_000)
+		}
+	}
+
+	private func finishWriter() async {
+		guard let writer else {
+			return
+		}
+
+		videoInput?.markAsFinished()
+		systemAudioInput?.markAsFinished()
+		microphoneAudioInput?.markAsFinished()
+
+		await withCheckedContinuation { continuation in
+			writer.finishWriting {
+				continuation.resume()
+			}
+		}
+
+		if writer.status == .completed {
+			emit([
+				"event": "recording-stopped",
+				"screenPath": request.outputs.screenPath,
+			])
+		} else {
+			emitError(
+				code: "writer-failed",
+				message: writer.error.map { "\($0)" } ?? "AVAssetWriter failed with status \(writer.status.rawValue)."
+			)
+		}
+	}
+
+	private func addAudioInput(to writer: AVAssetWriter, bitRate: Int) throws -> AVAssetWriterInput {
+		let settings: [String: Any] = [
+			AVFormatIDKey: kAudioFormatMPEG4AAC,
+			AVSampleRateKey: 48_000,
+			AVNumberOfChannelsKey: 2,
+			AVEncoderBitRateKey: bitRate,
+		]
+		let input = AVAssetWriterInput(mediaType: .audio, outputSettings: settings)
+		input.expectsMediaDataInRealTime = true
+
+		guard writer.canAdd(input) else {
+			throw HelperError.writerSetupFailed("Unable to add AAC audio input to AVAssetWriter.")
+		}
+
+		writer.add(input)
+		return input
+	}
+
+	private func appendAudioSampleBuffer(_ sampleBuffer: CMSampleBuffer, to input: AVAssetWriterInput?) {
+		guard didStartWriting else {
+			return
+		}
+		guard let input, input.isReadyForMoreMediaData else {
+			return
+		}
+
+		input.append(sampleBuffer)
+	}
+
+	private func currentPauseState() -> (paused: Bool, offset: CMTime) {
+		stateQueue.sync {
+			(isPaused, totalPausedDuration)
+		}
+	}
+
+	private func retimedSampleBuffer(_ sampleBuffer: CMSampleBuffer, subtracting offset: CMTime) -> CMSampleBuffer? {
+		if !offset.isValid || offset == .zero {
+			return sampleBuffer
+		}
+
+		let sampleCount = CMSampleBufferGetNumSamples(sampleBuffer)
+		if sampleCount <= 0 {
+			return sampleBuffer
+		}
+
+		var timing = Array(repeating: CMSampleTimingInfo(), count: sampleCount)
+		let timingStatus = CMSampleBufferGetSampleTimingInfoArray(
+			sampleBuffer,
+			entryCount: sampleCount,
+			arrayToFill: &timing,
+			entriesNeededOut: nil
+		)
+		if timingStatus != noErr {
+			emit([
+				"event": "warning",
+				"code": "sample-retime-failed",
+				"message": "Unable to read sample timing info: \(timingStatus).",
+			])
+			return sampleBuffer
+		}
+
+		for index in timing.indices {
+			if timing[index].presentationTimeStamp.isValid {
+				timing[index].presentationTimeStamp = CMTimeSubtract(
+					timing[index].presentationTimeStamp,
+					offset
+				)
+			}
+			if timing[index].decodeTimeStamp.isValid {
+				timing[index].decodeTimeStamp = CMTimeSubtract(timing[index].decodeTimeStamp, offset)
+			}
+		}
+
+		var retimedBuffer: CMSampleBuffer?
+		let copyStatus = CMSampleBufferCreateCopyWithNewTiming(
+			allocator: kCFAllocatorDefault,
+			sampleBuffer: sampleBuffer,
+			sampleTimingEntryCount: sampleCount,
+			sampleTimingArray: &timing,
+			sampleBufferOut: &retimedBuffer
+		)
+		if copyStatus != noErr {
+			emit([
+				"event": "warning",
+				"code": "sample-retime-failed",
+				"message": "Unable to copy sample timing info: \(copyStatus).",
+			])
+			return sampleBuffer
+		}
+
+		return retimedBuffer
+	}
+
+	private func isCompleteFrame(_ sampleBuffer: CMSampleBuffer) -> Bool {
+		guard let attachments = CMSampleBufferGetSampleAttachmentsArray(
+			sampleBuffer,
+			createIfNecessary: false
+		) as? [[SCStreamFrameInfo: Any]],
+			let attachment = attachments.first,
+			let statusRawValue = attachment[SCStreamFrameInfo.status] as? Int,
+			let status = SCFrameStatus(rawValue: statusRawValue)
+		else {
+			return true
+		}
+
+		return status == .complete
+	}
+
+	private func clampCaptureDimension(_ value: Int, fallback: Int) -> Int {
+		let requested = max(2, fallback)
+		let candidate = value > 0 ? value : requested
+		let clamped = min(candidate, requested)
+		return max(2, clamped - (clamped % 2))
+	}
+
+	private static func scaleFactor(for displayId: CGDirectDisplayID) -> Int {
+		guard let mode = CGDisplayCopyDisplayMode(displayId) else {
+			return 1
+		}
+
+		return max(1, mode.pixelWidth / max(1, mode.width))
+	}
+
+	private func supportsNativeMicrophoneCapture(streamConfig: SCStreamConfiguration) -> Bool {
+		streamConfig.responds(to: Selector(("setCaptureMicrophone:"))) &&
+			streamConfig.responds(to: Selector(("setMicrophoneCaptureDeviceID:"))) &&
+			SCStreamOutputType(rawValue: microphoneOutputTypeRawValue) != nil
+	}
+
+	private func resolveMicrophoneCaptureDeviceID() -> String? {
+		let devices = AVCaptureDevice.devices(for: .audio)
+
+		if let deviceName = request.audio.microphone.deviceName?.trimmingCharacters(in: .whitespacesAndNewlines),
+			!deviceName.isEmpty,
+			let device = devices.first(where: { $0.localizedName == deviceName })
+		{
+			return device.uniqueID
+		}
+
+		if let deviceId = request.audio.microphone.deviceId?.trimmingCharacters(in: .whitespacesAndNewlines),
+			!deviceId.isEmpty,
+			devices.contains(where: { $0.uniqueID == deviceId })
+		{
+			return deviceId
+		}
+
+		return nil
+	}
+}
+
+@main
+struct OpenScreenScreenCaptureKitHelper {
+	static func main() async {
+		do {
+			guard CommandLine.arguments.count == 2 else {
+				throw HelperError.invalidArguments
+			}
+
+			guard #available(macOS 13.0, *) else {
+				throw HelperError.unsupportedMacOS
+			}
+
+			let requestData = Data(CommandLine.arguments[1].utf8)
+			let decoder = JSONDecoder()
+			let request = try decoder.decode(RecordingRequest.self, from: requestData)
+			let recorder = ScreenCaptureRecorder(request: request)
+			let stopTask = Task.detached {
+				while let line = readLine() {
+					let command = line.trimmingCharacters(in: .whitespacesAndNewlines)
+					switch command {
+					case "pause":
+						recorder.pause()
+					case "resume":
+						recorder.resume()
+					case "stop":
+						await recorder.stop()
+						exit(0)
+					default:
+						break
+					}
+				}
+			}
+
+			try await recorder.start()
+			await stopTask.value
+		} catch let error as HelperError {
+			emitError(code: "helper-error", message: error.description)
+			exit(1)
+		} catch {
+			emitError(code: "helper-error", message: "\(error)")
+			exit(1)
+		}
+	}
+}

electron/native/wgc-capture/CMakeLists.txt

@@ -0,0 +1,67 @@
+cmake_minimum_required(VERSION 3.20)
+
+# The local Windows SDK image used by some contributors can miss gdi32.lib,
+# while CMake's default MSVC console template links it unconditionally. This
+# helper does not use GDI, so keep the standard library set minimal and explicit.
+set(CMAKE_CXX_STANDARD_LIBRARIES
+  "kernel32.lib user32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib comdlg32.lib advapi32.lib"
+  CACHE STRING "" FORCE)
+
+project(openscreen-wgc-capture LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+add_executable(wgc-capture
+  src/audio_sample_utils.cpp
+  src/audio_sample_utils.h
+  src/dshow_webcam_capture.cpp
+  src/dshow_webcam_capture.h
+  src/main.cpp
+  src/mf_encoder.cpp
+  src/mf_encoder.h
+  src/monitor_utils.cpp
+  src/monitor_utils.h
+  src/wasapi_loopback_capture.cpp
+  src/wasapi_loopback_capture.h
+  src/webcam_capture.cpp
+  src/webcam_capture.h
+  src/wgc_session.cpp
+  src/wgc_session.h
+)
+
+target_compile_definitions(wgc-capture PRIVATE
+  NOMINMAX
+  WIN32_LEAN_AND_MEAN
+  _WIN32_WINNT=0x0A00
+)
+
+target_compile_options(wgc-capture PRIVATE /EHsc /W4 /utf-8)
+
+target_link_libraries(wgc-capture PRIVATE
+  d3d11
+  dxgi
+  mf
+  mfplat
+  mfreadwrite
+  mfuuid
+  runtimeobject
+  windowsapp
+)
+
+add_executable(cursor-sampler
+  src/cursor-sampler.cpp
+)
+
+target_compile_definitions(cursor-sampler PRIVATE
+  NOMINMAX
+  _WIN32_WINNT=0x0A00
+)
+
+target_compile_options(cursor-sampler PRIVATE /EHsc /W4 /utf-8)
+
+target_link_libraries(cursor-sampler PRIVATE
+  gdi32
+  gdiplus
+)

electron/native/wgc-capture/src/audio_sample_utils.cpp

@@ -0,0 +1,420 @@
+#include "audio_sample_utils.h"
+
+#include <mfapi.h>
+
+#include <algorithm>
+#include <chrono>
+#include <cmath>
+#include <cstring>
+#include <limits>
+
+namespace {
+
+bool isFloatFormat(const AudioInputFormat& format) {
+    return format.subtype == MFAudioFormat_Float && format.bitsPerSample == 32;
+}
+
+bool isPcmFormat(const AudioInputFormat& format, UINT32 bitsPerSample) {
+    return format.subtype == MFAudioFormat_PCM && format.bitsPerSample == bitsPerSample;
+}
+
+template <typename T>
+T clampTo(double value) {
+    const double minValue = static_cast<double>(std::numeric_limits<T>::min());
+    const double maxValue = static_cast<double>(std::numeric_limits<T>::max());
+    return static_cast<T>(std::clamp(std::round(value), minValue, maxValue));
+}
+
+size_t bytesPerSample(const AudioInputFormat& format) {
+    return format.bitsPerSample / 8;
+}
+
+double readSampleAsDouble(const BYTE* source, const AudioInputFormat& format, size_t frameIndex, UINT32 channelIndex) {
+    if (!source || format.blockAlign == 0 || channelIndex >= format.channels) {
+        return 0.0;
+    }
+
+    const size_t offset = frameIndex * format.blockAlign + channelIndex * bytesPerSample(format);
+    if (isFloatFormat(format)) {
+        return static_cast<double>(*reinterpret_cast<const float*>(source + offset));
+    }
+    if (isPcmFormat(format, 16)) {
+        return static_cast<double>(*reinterpret_cast<const int16_t*>(source + offset)) / 32768.0;
+    }
+    if (isPcmFormat(format, 32)) {
+        return static_cast<double>(*reinterpret_cast<const int32_t*>(source + offset)) / 2147483648.0;
+    }
+    return 0.0;
+}
+
+void writeSampleFromDouble(BYTE* destination, const AudioInputFormat& format, size_t frameIndex, UINT32 channelIndex, double value) {
+    if (!destination || format.blockAlign == 0 || channelIndex >= format.channels) {
+        return;
+    }
+
+    const double clamped = std::clamp(value, -1.0, 1.0);
+    const size_t offset = frameIndex * format.blockAlign + channelIndex * bytesPerSample(format);
+    if (isFloatFormat(format)) {
+        *reinterpret_cast<float*>(destination + offset) = static_cast<float>(clamped);
+        return;
+    }
+    if (isPcmFormat(format, 16)) {
+        *reinterpret_cast<int16_t*>(destination + offset) = clampTo<int16_t>(clamped * 32767.0);
+        return;
+    }
+    if (isPcmFormat(format, 32)) {
+        *reinterpret_cast<int32_t*>(destination + offset) = clampTo<int32_t>(clamped * 2147483647.0);
+    }
+}
+
+double readMappedChannel(const BYTE* source, const AudioInputFormat& format, size_t frameIndex, UINT32 targetChannel, UINT32 targetChannels) {
+    if (format.channels == 0) {
+        return 0.0;
+    }
+    if (format.channels == targetChannels && targetChannel < format.channels) {
+        return readSampleAsDouble(source, format, frameIndex, targetChannel);
+    }
+    if (format.channels == 1) {
+        return readSampleAsDouble(source, format, frameIndex, 0);
+    }
+    if (targetChannels == 1) {
+        double sum = 0.0;
+        for (UINT32 channel = 0; channel < format.channels; ++channel) {
+            sum += readSampleAsDouble(source, format, frameIndex, channel);
+        }
+        return sum / static_cast<double>(format.channels);
+    }
+    return readSampleAsDouble(source, format, frameIndex, std::min(targetChannel, format.channels - 1));
+}
+
+} // namespace
+
+constexpr int64_t HnsPerSecond = 10'000'000;
+
+bool sameAudioFormatForMixing(const AudioInputFormat& left, const AudioInputFormat& right) {
+    return left.subtype == right.subtype &&
+           left.sampleRate == right.sampleRate &&
+           left.channels == right.channels &&
+           left.bitsPerSample == right.bitsPerSample &&
+           left.blockAlign == right.blockAlign &&
+           left.avgBytesPerSec == right.avgBytesPerSec;
+}
+
+AudioInputFormat makeAacCompatibleAudioFormat(const AudioInputFormat& source) {
+    AudioInputFormat format{};
+    format.subtype = MFAudioFormat_PCM;
+    format.sampleRate = source.sampleRate > 0 ? source.sampleRate : 48000;
+    format.channels = 2;
+    format.bitsPerSample = 16;
+    format.blockAlign = format.channels * (format.bitsPerSample / 8);
+    format.avgBytesPerSec = format.sampleRate * format.blockAlign;
+    return format;
+}
+
+void copyAudioWithGain(
+    const BYTE* source,
+    DWORD byteCount,
+    const AudioInputFormat& format,
+    double gain,
+    std::vector<BYTE>& destination) {
+    destination.resize(byteCount);
+    if (!source || byteCount == 0) {
+        std::fill(destination.begin(), destination.end(), static_cast<BYTE>(0));
+        return;
+    }
+
+    if (std::abs(gain - 1.0) < 0.0001) {
+        std::memcpy(destination.data(), source, byteCount);
+        return;
+    }
+
+    if (isFloatFormat(format)) {
+        const auto* input = reinterpret_cast<const float*>(source);
+        auto* output = reinterpret_cast<float*>(destination.data());
+        const size_t sampleCount = byteCount / sizeof(float);
+        for (size_t index = 0; index < sampleCount; index += 1) {
+            output[index] = static_cast<float>(std::clamp(input[index] * gain, -1.0, 1.0));
+        }
+        return;
+    }
+
+    if (isPcmFormat(format, 16)) {
+        const auto* input = reinterpret_cast<const int16_t*>(source);
+        auto* output = reinterpret_cast<int16_t*>(destination.data());
+        const size_t sampleCount = byteCount / sizeof(int16_t);
+        for (size_t index = 0; index < sampleCount; index += 1) {
+            output[index] = clampTo<int16_t>(static_cast<double>(input[index]) * gain);
+        }
+        return;
+    }
+
+    if (isPcmFormat(format, 32)) {
+        const auto* input = reinterpret_cast<const int32_t*>(source);
+        auto* output = reinterpret_cast<int32_t*>(destination.data());
+        const size_t sampleCount = byteCount / sizeof(int32_t);
+        for (size_t index = 0; index < sampleCount; index += 1) {
+            output[index] = clampTo<int32_t>(static_cast<double>(input[index]) * gain);
+        }
+        return;
+    }
+
+    std::memcpy(destination.data(), source, byteCount);
+}
+
+void convertAudioWithGain(
+    const BYTE* source,
+    DWORD byteCount,
+    const AudioInputFormat& sourceFormat,
+    const AudioInputFormat& targetFormat,
+    double gain,
+    std::vector<BYTE>& destination) {
+    if (!source || byteCount == 0 || sourceFormat.blockAlign == 0 || targetFormat.blockAlign == 0 ||
+        sourceFormat.sampleRate == 0 || targetFormat.sampleRate == 0 || sourceFormat.channels == 0 ||
+        targetFormat.channels == 0) {
+        destination.clear();
+        return;
+    }
+
+    if (sameAudioFormatForMixing(sourceFormat, targetFormat)) {
+        copyAudioWithGain(source, byteCount, targetFormat, gain, destination);
+        return;
+    }
+
+    const size_t sourceFrames = byteCount / sourceFormat.blockAlign;
+    if (sourceFrames == 0) {
+        destination.clear();
+        return;
+    }
+
+    const double rateRatio = static_cast<double>(targetFormat.sampleRate) /
+        static_cast<double>(sourceFormat.sampleRate);
+    const size_t targetFrames = std::max<size_t>(1, static_cast<size_t>(std::llround(sourceFrames * rateRatio)));
+    destination.assign(targetFrames * targetFormat.blockAlign, 0);
+
+    for (size_t targetFrame = 0; targetFrame < targetFrames; ++targetFrame) {
+        const double sourcePosition = static_cast<double>(targetFrame) / rateRatio;
+        const size_t sourceFrame = std::min(
+            sourceFrames - 1,
+            static_cast<size_t>(std::llround(sourcePosition)));
+        for (UINT32 channel = 0; channel < targetFormat.channels; ++channel) {
+            const double sample = readMappedChannel(
+                source,
+                sourceFormat,
+                sourceFrame,
+                channel,
+                targetFormat.channels);
+            writeSampleFromDouble(destination.data(), targetFormat, targetFrame, channel, sample * gain);
+        }
+    }
+}
+
+void mixAudioInPlace(
+    std::vector<BYTE>& destination,
+    const BYTE* source,
+    DWORD byteCount,
+    const AudioInputFormat& format) {
+    if (!source || byteCount == 0 || destination.empty()) {
+        return;
+    }
+
+    const size_t mixByteCount = std::min(destination.size(), static_cast<size_t>(byteCount));
+
+    if (isFloatFormat(format)) {
+        auto* output = reinterpret_cast<float*>(destination.data());
+        const auto* input = reinterpret_cast<const float*>(source);
+        const size_t sampleCount = mixByteCount / sizeof(float);
+        for (size_t index = 0; index < sampleCount; index += 1) {
+            output[index] = static_cast<float>(std::clamp(output[index] + input[index], -1.0f, 1.0f));
+        }
+        return;
+    }
+
+    if (isPcmFormat(format, 16)) {
+        auto* output = reinterpret_cast<int16_t*>(destination.data());
+        const auto* input = reinterpret_cast<const int16_t*>(source);
+        const size_t sampleCount = mixByteCount / sizeof(int16_t);
+        for (size_t index = 0; index < sampleCount; index += 1) {
+            output[index] = clampTo<int16_t>(
+                static_cast<double>(output[index]) + static_cast<double>(input[index]));
+        }
+        return;
+    }
+
+    if (isPcmFormat(format, 32)) {
+        auto* output = reinterpret_cast<int32_t*>(destination.data());
+        const auto* input = reinterpret_cast<const int32_t*>(source);
+        const size_t sampleCount = mixByteCount / sizeof(int32_t);
+        for (size_t index = 0; index < sampleCount; index += 1) {
+            output[index] = clampTo<int32_t>(
+                static_cast<double>(output[index]) + static_cast<double>(input[index]));
+        }
+    }
+}
+
+AudioMixer::AudioMixer(
+    const AudioInputFormat& format,
+    const AudioInputFormat& systemFormat,
+    const AudioInputFormat& microphoneFormat,
+    bool includeSystem,
+    bool includeMicrophone,
+    double microphoneGain,
+    OutputCallback output)
+    : format_(format),
+      systemFormat_(systemFormat),
+      microphoneFormat_(microphoneFormat),
+      includeSystem_(includeSystem),
+      includeMicrophone_(includeMicrophone),
+      microphoneGain_(microphoneGain),
+      output_(std::move(output)) {}
+
+AudioMixer::~AudioMixer() {
+    stop();
+}
+
+bool AudioMixer::start() {
+    if (!output_ || format_.sampleRate == 0 || format_.blockAlign == 0) {
+        return false;
+    }
+
+    stopRequested_ = false;
+    emittedFrames_ = 0;
+    timelineStarted_ = false;
+    thread_ = std::thread([this] {
+        mixLoop();
+    });
+    return true;
+}
+
+void AudioMixer::beginTimeline() {
+    {
+        std::scoped_lock lock(mutex_);
+        systemQueue_.clear();
+        microphoneQueue_.clear();
+        emittedFrames_ = 0;
+        timelineStarted_ = true;
+    }
+    cv_.notify_all();
+}
+
+void AudioMixer::stop() {
+    stopRequested_ = true;
+    cv_.notify_all();
+    if (thread_.joinable()) {
+        thread_.join();
+    }
+}
+
+void AudioMixer::pushSystem(const BYTE* data, DWORD byteCount) {
+    if (!includeSystem_ || stopRequested_) {
+        return;
+    }
+
+    {
+        std::scoped_lock lock(mutex_);
+        append(systemQueue_, data, byteCount, systemFormat_, 1.0);
+    }
+    cv_.notify_all();
+}
+
+void AudioMixer::pushMicrophone(const BYTE* data, DWORD byteCount) {
+    if (!includeMicrophone_ || stopRequested_) {
+        return;
+    }
+
+    {
+        std::scoped_lock lock(mutex_);
+        append(microphoneQueue_, data, byteCount, microphoneFormat_, microphoneGain_);
+    }
+    cv_.notify_all();
+}
+
+void AudioMixer::append(
+    std::vector<BYTE>& queue,
+    const BYTE* data,
+    DWORD byteCount,
+    const AudioInputFormat& sourceFormat,
+    double gain) {
+    if (!data || byteCount == 0) {
+        return;
+    }
+
+    convertAudioWithGain(data, byteCount, sourceFormat, format_, gain, gainBuffer_);
+    queue.insert(queue.end(), gainBuffer_.begin(), gainBuffer_.end());
+}
+
+bool AudioMixer::pop(std::vector<BYTE>& queue, std::vector<BYTE>& chunk, size_t byteCount) {
+    if (queue.empty()) {
+        chunk.assign(byteCount, 0);
+        return false;
+    }
+
+    chunk.assign(byteCount, 0);
+    const size_t copiedBytes = std::min(byteCount, queue.size());
+    std::memcpy(chunk.data(), queue.data(), copiedBytes);
+    queue.erase(queue.begin(), queue.begin() + static_cast<std::ptrdiff_t>(copiedBytes));
+    return copiedBytes > 0;
+}
+
+void AudioMixer::mixLoop() {
+    const uint32_t chunkFrames = std::max<uint32_t>(1, format_.sampleRate / 100);
+    const size_t chunkBytes = static_cast<size_t>(chunkFrames) * format_.blockAlign;
+    std::vector<BYTE> mixedChunk;
+    std::vector<BYTE> sourceChunk;
+    std::chrono::steady_clock::time_point audioClockStart;
+    bool audioClockStarted = false;
+
+    while (true) {
+        {
+            std::unique_lock lock(mutex_);
+            cv_.wait_for(lock, std::chrono::milliseconds(20), [&] {
+                const bool hasSystem = !includeSystem_ || systemQueue_.size() >= chunkBytes;
+                const bool hasMicrophone = !includeMicrophone_ || microphoneQueue_.size() >= chunkBytes;
+                const bool hasAnySource = !systemQueue_.empty() || !microphoneQueue_.empty();
+                return stopRequested_.load() ||
+                    (timelineStarted_ && (hasSystem || hasMicrophone) && hasAnySource);
+            });
+
+            if (stopRequested_) {
+                break;
+            }
+            if (!timelineStarted_) {
+                continue;
+            }
+
+            const bool hasAnyQueuedAudio = !systemQueue_.empty() || !microphoneQueue_.empty();
+            if (!hasAnyQueuedAudio) {
+                continue;
+            }
+
+            mixedChunk.assign(chunkBytes, 0);
+            if (includeSystem_) {
+                pop(systemQueue_, sourceChunk, chunkBytes);
+                mixAudioInPlace(mixedChunk, sourceChunk.data(), static_cast<DWORD>(sourceChunk.size()), format_);
+            }
+            if (includeMicrophone_) {
+                pop(microphoneQueue_, sourceChunk, chunkBytes);
+                mixAudioInPlace(mixedChunk, sourceChunk.data(), static_cast<DWORD>(sourceChunk.size()), format_);
+            }
+        }
+
+        if (!audioClockStarted) {
+            audioClockStart = std::chrono::steady_clock::now();
+            audioClockStarted = true;
+        }
+
+        const int64_t timestampHns =
+            static_cast<int64_t>((emittedFrames_ * HnsPerSecond) / format_.sampleRate);
+        const int64_t durationHns =
+            static_cast<int64_t>((static_cast<uint64_t>(chunkFrames) * HnsPerSecond) / format_.sampleRate);
+        if (!output_(mixedChunk.data(), static_cast<DWORD>(mixedChunk.size()), timestampHns, durationHns)) {
+            stopRequested_ = true;
+            break;
+        }
+        emittedFrames_ += chunkFrames;
+
+        const auto nextDeadline = audioClockStart +
+            std::chrono::duration_cast<std::chrono::steady_clock::duration>(
+                std::chrono::duration<double>(static_cast<double>(emittedFrames_) / format_.sampleRate));
+        std::this_thread::sleep_until(nextDeadline);
+    }
+}

electron/native/wgc-capture/src/audio_sample_utils.h

@@ -0,0 +1,85 @@
+#pragma once
+
+#include "mf_encoder.h"
+
+#include <Windows.h>
+
+#include <atomic>
+#include <condition_variable>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+bool sameAudioFormatForMixing(const AudioInputFormat& left, const AudioInputFormat& right);
+AudioInputFormat makeAacCompatibleAudioFormat(const AudioInputFormat& source);
+void copyAudioWithGain(
+    const BYTE* source,
+    DWORD byteCount,
+    const AudioInputFormat& format,
+    double gain,
+    std::vector<BYTE>& destination);
+void convertAudioWithGain(
+    const BYTE* source,
+    DWORD byteCount,
+    const AudioInputFormat& sourceFormat,
+    const AudioInputFormat& targetFormat,
+    double gain,
+    std::vector<BYTE>& destination);
+void mixAudioInPlace(
+    std::vector<BYTE>& destination,
+    const BYTE* source,
+    DWORD byteCount,
+    const AudioInputFormat& format);
+
+class AudioMixer {
+public:
+    using OutputCallback = std::function<bool(const BYTE* data, DWORD byteCount, int64_t timestampHns, int64_t durationHns)>;
+
+    AudioMixer(
+        const AudioInputFormat& format,
+        const AudioInputFormat& systemFormat,
+        const AudioInputFormat& microphoneFormat,
+        bool includeSystem,
+        bool includeMicrophone,
+        double microphoneGain,
+        OutputCallback output);
+    ~AudioMixer();
+
+    AudioMixer(const AudioMixer&) = delete;
+    AudioMixer& operator=(const AudioMixer&) = delete;
+
+    bool start();
+    void beginTimeline();
+    void stop();
+    void pushSystem(const BYTE* data, DWORD byteCount);
+    void pushMicrophone(const BYTE* data, DWORD byteCount);
+
+private:
+    void append(
+        std::vector<BYTE>& queue,
+        const BYTE* data,
+        DWORD byteCount,
+        const AudioInputFormat& sourceFormat,
+        double gain);
+    bool pop(std::vector<BYTE>& queue, std::vector<BYTE>& chunk, size_t byteCount);
+    void mixLoop();
+
+    AudioInputFormat format_{};
+    AudioInputFormat systemFormat_{};
+    AudioInputFormat microphoneFormat_{};
+    bool includeSystem_ = false;
+    bool includeMicrophone_ = false;
+    double microphoneGain_ = 1.0;
+    OutputCallback output_;
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    std::vector<BYTE> systemQueue_;
+    std::vector<BYTE> microphoneQueue_;
+    std::vector<BYTE> gainBuffer_;
+    std::thread thread_;
+    std::atomic<bool> stopRequested_ = false;
+    bool timelineStarted_ = false;
+    uint64_t emittedFrames_ = 0;
+};

electron/native/wgc-capture/src/cursor-sampler.cpp

@@ -0,0 +1,482 @@
+#include <windows.h>
+#include <gdiplus.h>
+#include <objbase.h>
+
+#include <atomic>
+#include <algorithm>
+#include <chrono>
+#include <cinttypes>
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <iostream>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Global mouse-hook state
+// ─────────────────────────────────────────────────────────────────────────────
+static HHOOK              g_mouseHook    = nullptr;
+static DWORD              g_mainThreadId = 0;
+static std::atomic<int>   g_leftDownCount{0};
+static std::atomic<int>   g_leftUpCount{0};
+static std::atomic<bool>  g_stop{false};
+static std::mutex         g_stdoutMtx;
+
+static LRESULT CALLBACK LowLevelMouseProc(int nCode, WPARAM wParam, LPARAM lParam) {
+    if (nCode >= 0) {
+        if      (wParam == WM_LBUTTONDOWN) g_leftDownCount.fetch_add(1, std::memory_order_relaxed);
+        else if (wParam == WM_LBUTTONUP)   g_leftUpCount.fetch_add(1,   std::memory_order_relaxed);
+    }
+    return CallNextHookEx(g_mouseHook, nCode, wParam, lParam);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+static int64_t nowMs() {
+    return static_cast<int64_t>(
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::system_clock::now().time_since_epoch())
+        .count());
+}
+
+static void writeJsonLine(const std::string& json) {
+    std::lock_guard<std::mutex> lock(g_stdoutMtx);
+    std::cout << json << '\n';
+    std::cout.flush();
+}
+
+static std::string jsonEscape(const std::string& s) {
+    std::string r;
+    r.reserve(s.size());
+    for (unsigned char c : s) {
+        switch (c) {
+            case '"':  r += "\\\""; break;
+            case '\\': r += "\\\\"; break;
+            case '\n': r += "\\n";  break;
+            case '\r': r += "\\r";  break;
+            case '\t': r += "\\t";  break;
+            default:   r.push_back(static_cast<char>(c)); break;
+        }
+    }
+    return r;
+}
+
+static const char kBase64Chars[] =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+static std::string base64Encode(const uint8_t* data, size_t len) {
+    std::string out;
+    out.reserve(((len + 2) / 3) * 4);
+    for (size_t i = 0; i < len; i += 3) {
+        const uint32_t b =
+            (static_cast<uint32_t>(data[i])              << 16) |
+            (i + 1 < len ? static_cast<uint32_t>(data[i + 1]) << 8 : 0u) |
+            (i + 2 < len ? static_cast<uint32_t>(data[i + 2])      : 0u);
+        out.push_back(kBase64Chars[(b >> 18) & 0x3F]);
+        out.push_back(kBase64Chars[(b >> 12) & 0x3F]);
+        out.push_back(i + 1 < len ? kBase64Chars[(b >>  6) & 0x3F] : '=');
+        out.push_back(i + 2 < len ? kBase64Chars[(b      ) & 0x3F] : '=');
+    }
+    return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GDI+ PNG encoder CLSID
+// ─────────────────────────────────────────────────────────────────────────────
+static bool getPngClsid(CLSID& out) {
+    UINT num = 0, sz = 0;
+    if (Gdiplus::GetImageEncodersSize(&num, &sz) != Gdiplus::Ok || sz == 0) return false;
+    std::vector<uint8_t> buf(sz);
+    auto* enc = reinterpret_cast<Gdiplus::ImageCodecInfo*>(buf.data());
+    if (Gdiplus::GetImageEncoders(num, sz, enc) != Gdiplus::Ok) return false;
+    for (UINT i = 0; i < num; ++i) {
+        if (std::wstring(enc[i].MimeType) == L"image/png") {
+            out = enc[i].Clsid;
+            return true;
+        }
+    }
+    return false;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Standard cursor-type lookup
+// ─────────────────────────────────────────────────────────────────────────────
+static const char* standardCursorType(HCURSOR hc) {
+    if (!hc) return nullptr;
+    static const struct { WORD id; const char* name; } kMap[] = {
+        {32512, "arrow"},
+        {32513, "text"},
+        {32514, "wait"},
+        {32515, "crosshair"},
+        {32516, "up-arrow"},
+        {32642, "resize-nwse"},
+        {32643, "resize-nesw"},
+        {32644, "resize-ew"},
+        {32645, "resize-ns"},
+        {32646, "move"},
+        {32648, "not-allowed"},
+        {32649, "pointer"},
+        {32650, "app-starting"},
+        {32651, "help"},
+    };
+    static constexpr int N = static_cast<int>(sizeof(kMap) / sizeof(kMap[0]));
+    static HCURSOR g_handles[N] = {};
+    static bool    g_init       = false;
+    if (!g_init) {
+        for (int i = 0; i < N; ++i)
+            g_handles[i] = LoadCursor(nullptr, MAKEINTRESOURCE(kMap[i].id));
+        g_init = true;
+    }
+    for (int i = 0; i < N; ++i)
+        if (g_handles[i] && g_handles[i] == hc) return kMap[i].name;
+    return nullptr;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Custom cursor-type detection (replicates the PowerShell heuristic)
+// ─────────────────────────────────────────────────────────────────────────────
+static const char* detectCustomCursorType(
+    const uint32_t* pixels, int w, int h, int hotX, int hotY)
+{
+    if (w < 24 || h < 24 || w > 64 || h > 64) return nullptr;
+    if (hotX < w * 0.25 || hotX > w * 0.75)   return nullptr;
+    if (hotY < h * 0.15 || hotY > h * 0.55)   return nullptr;
+
+    int opaque = 0, topHalf = 0;
+    int left = w, top = h, right = -1, bottom = -1;
+
+    for (int y = 0; y < h; ++y) {
+        for (int x = 0; x < w; ++x) {
+            const uint8_t a = static_cast<uint8_t>(pixels[y * w + x] >> 24);
+            if (a <= 32) continue;
+            ++opaque;
+            if (y < h / 2) ++topHalf;
+            if (x < left)   left   = x;
+            if (x > right)  right  = x;
+            if (y < top)    top    = y;
+            if (y > bottom) bottom = y;
+        }
+    }
+
+    if (opaque < 90 || right < left || bottom < top) return nullptr;
+
+    const int ow = right - left + 1;
+    const int oh = bottom - top + 1;
+    if (ow < w * 0.35 || ow > w * 0.9)                   return nullptr;
+    if (oh < h * 0.45 || oh > static_cast<double>(h))    return nullptr;
+    if (top > h * 0.45 || bottom < h * 0.65)             return nullptr;
+
+    return topHalf > opaque * 0.55 ? "closed-hand" : "open-hand";
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Build asset JSON for the given cursor (returns empty string on failure)
+//
+// Renders the cursor via GDI DrawIconEx onto a 32-bpp transparent DIB section
+// and then encodes to PNG — matching the PowerShell approach of
+// Graphics.Clear(Transparent) + Graphics.DrawIcon().  This correctly preserves
+// per-pixel alpha for 32-bit cursors, unlike Gdiplus::Bitmap::FromHICON which
+// can produce incorrect alpha for cursor handles.
+// ─────────────────────────────────────────────────────────────────────────────
+static std::string buildAssetJson(
+    HCURSOR            hCursor,
+    const std::string& handleStr,
+    const CLSID&       pngClsid,
+    const char**       outCustomType)
+{
+    *outCustomType = nullptr;
+
+    // Get hotspot and cursor dimensions from the icon info.
+    // For color cursors hbmColor gives the size; for monochrome cursors the
+    // mask bitmap is twice the cursor height (AND mask stacked on XOR mask).
+    ICONINFO ii{};
+    if (!GetIconInfo(hCursor, &ii)) return {};
+    const int hotX = static_cast<int>(ii.xHotspot);
+    const int hotY = static_cast<int>(ii.yHotspot);
+
+    int w = 0, h = 0;
+    if (ii.hbmColor) {
+        BITMAP bm{};
+        if (GetObject(ii.hbmColor, sizeof(bm), &bm)) { w = bm.bmWidth; h = bm.bmHeight; }
+    }
+    if (ii.hbmMask && (w == 0 || h == 0)) {
+        BITMAP bm{};
+        if (GetObject(ii.hbmMask, sizeof(bm), &bm)) {
+            w = bm.bmWidth;
+            h = ii.hbmColor ? bm.bmHeight : bm.bmHeight / 2;
+        }
+    }
+    if (ii.hbmMask)  DeleteObject(ii.hbmMask);
+    if (ii.hbmColor) DeleteObject(ii.hbmColor);
+    if (w <= 0 || h <= 0) return {};
+
+    // Copy the cursor handle so DrawIconEx cannot affect the live system cursor.
+    const HICON hCopy = CopyIcon(hCursor);
+    if (!hCopy) return {};
+
+    // Allocate a 32-bpp top-down DIB section and clear it to transparent black,
+    // then draw the cursor with DI_NORMAL.  For 32-bit alpha cursors Windows
+    // writes correct per-pixel alpha into the high byte of each BGRA pixel.
+    const int stride = w * 4;
+    BITMAPINFOHEADER bih{};
+    bih.biSize        = sizeof(bih);
+    bih.biWidth       = w;
+    bih.biHeight      = -h;   // negative = top-down scanline order
+    bih.biPlanes      = 1;
+    bih.biBitCount    = 32;
+    bih.biCompression = BI_RGB;
+
+    void*   pBits = nullptr;
+    HDC     hDC   = CreateCompatibleDC(nullptr);
+    HBITMAP hBmp  = hDC ? CreateDIBSection(hDC,
+                              reinterpret_cast<const BITMAPINFO*>(&bih),
+                              DIB_RGB_COLORS, &pBits, nullptr, 0)
+                        : nullptr;
+
+    if (!hBmp || !pBits) {
+        if (hBmp) DeleteObject(hBmp);
+        if (hDC)  DeleteDC(hDC);
+        DestroyIcon(hCopy);
+        return {};
+    }
+
+    HGDIOBJ hOld = SelectObject(hDC, hBmp);
+    std::memset(pBits, 0, static_cast<size_t>(stride * h)); // transparent black
+    DrawIconEx(hDC, 0, 0, hCopy, w, h, 0, nullptr, DI_NORMAL);
+    GdiFlush();
+    SelectObject(hDC, hOld);
+    DeleteDC(hDC);
+    DestroyIcon(hCopy);
+
+    // GDI's 32-bit DIB stores pixels as BGRA in memory.  GDI+'s
+    // PixelFormat32bppARGB interprets each 32-bit word as 0xAARRGGBB which is
+    // identical to BGRA on little-endian, so the alpha byte is always >> 24.
+    {
+        const auto* px = static_cast<const uint32_t*>(pBits);
+        *outCustomType = detectCustomCursorType(px, w, h, hotX, hotY);
+    }
+
+    // Wrap the DIB pixels in a GDI+ Bitmap (zero-copy) and save to PNG.
+    // Keep hBmp alive until after gBmp is destroyed so pBits remains valid.
+    std::vector<uint8_t> pngData;
+    {
+        Gdiplus::Bitmap gBmp(w, h, stride, PixelFormat32bppARGB,
+                             static_cast<BYTE*>(pBits));
+        if (gBmp.GetLastStatus() == Gdiplus::Ok) {
+            IStream* pStream = nullptr;
+            if (SUCCEEDED(CreateStreamOnHGlobal(nullptr, TRUE, &pStream))) {
+                if (gBmp.Save(pStream, &pngClsid) == Gdiplus::Ok) {
+                    ULARGE_INTEGER sz{};
+                    LARGE_INTEGER  zero{};
+                    pStream->Seek(zero, STREAM_SEEK_END, &sz);
+                    pStream->Seek(zero, STREAM_SEEK_SET, nullptr);
+                    pngData.resize(static_cast<size_t>(sz.QuadPart));
+                    ULONG n = 0;
+                    pStream->Read(pngData.data(), static_cast<ULONG>(pngData.size()), &n);
+                    pngData.resize(n);
+                }
+                pStream->Release();
+            }
+        }
+    } // gBmp destroyed here; pBits (owned by hBmp) still valid
+    DeleteObject(hBmp);
+
+    if (pngData.empty()) return {};
+
+    const std::string dataUrl =
+        "data:image/png;base64," + base64Encode(pngData.data(), pngData.size());
+
+    std::string json;
+    json.reserve(dataUrl.size() + 128);
+    json  = "{\"id\":\"" + handleStr + "\"";
+    json += ",\"imageDataUrl\":\"" + jsonEscape(dataUrl) + "\"";
+    json += ",\"width\":"    + std::to_string(w);
+    json += ",\"height\":"   + std::to_string(h);
+    json += ",\"hotspotX\":" + std::to_string(hotX);
+    json += ",\"hotspotY\":" + std::to_string(hotY);
+    if (*outCustomType) {
+        json += ",\"cursorType\":\"";
+        json += *outCustomType;
+        json += "\"";
+    } else {
+        json += ",\"cursorType\":null";
+    }
+    json += "}";
+    return json;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Sampling loop (background thread)
+// ─────────────────────────────────────────────────────────────────────────────
+static void runSamplingLoop(int intervalMs, HWND targetWindow, const CLSID& pngClsid) {
+    HCURSOR lastCursor = nullptr;
+
+    while (!g_stop.load(std::memory_order_relaxed)) {
+        const int downCount = g_leftDownCount.exchange(0, std::memory_order_relaxed);
+        const int upCount   = g_leftUpCount.exchange(0,   std::memory_order_relaxed);
+
+        CURSORINFO ci{};
+        ci.cbSize = sizeof(ci);
+        if (!GetCursorInfo(&ci)) {
+            char buf[160];
+            std::snprintf(buf, sizeof(buf),
+                "{\"type\":\"error\",\"timestampMs\":%" PRId64 ",\"message\":\"GetCursorInfo failed\"}",
+                nowMs());
+            writeJsonLine(buf);
+            std::this_thread::sleep_for(std::chrono::milliseconds(intervalMs));
+            continue;
+        }
+
+        const bool    visible   = (ci.flags & CURSOR_SHOWING) != 0;
+        const HCURSOR hc        = ci.hCursor;
+
+        // Handle string ("0xHEX" or empty for null cursor)
+        char handleBuf[32] = {};
+        if (hc)
+            std::snprintf(handleBuf, sizeof(handleBuf),
+                "0x%" PRIX64, static_cast<uint64_t>(reinterpret_cast<uintptr_t>(hc)));
+        const std::string handleStr = hc ? handleBuf : "";
+
+        // Standard cursor type
+        const char* cursorType = standardCursorType(hc);
+
+        // Mouse button state
+        const SHORT ks          = GetAsyncKeyState(VK_LBUTTON);
+        const bool  leftDown    = (ks & 0x8000) != 0;
+        const bool  leftPressed = downCount > 0 || (ks & 0x0001) != 0;
+        const bool  leftReleased = upCount > 0;
+
+        // Asset — only when the cursor handle changes
+        std::string assetJson;
+        if (visible && hc && hc != lastCursor) {
+            const char* customType = nullptr;
+            assetJson = buildAssetJson(hc, handleStr, pngClsid, &customType);
+            if (!assetJson.empty() && !cursorType && customType)
+                cursorType = customType;
+            lastCursor = hc;
+        }
+
+        // Window bounds
+        std::string boundsJson = "null";
+        if (targetWindow && IsWindow(targetWindow)) {
+            RECT r{};
+            if (GetWindowRect(targetWindow, &r)) {
+                const int bw = r.right  - r.left;
+                const int bh = r.bottom - r.top;
+                if (bw > 0 && bh > 0) {
+                    char buf[128];
+                    std::snprintf(buf, sizeof(buf),
+                        "{\"x\":%ld,\"y\":%ld,\"width\":%d,\"height\":%d}",
+                        r.left, r.top, bw, bh);
+                    boundsJson = buf;
+                }
+            }
+        }
+
+        // Emit sample JSON
+        std::string out;
+        out.reserve(256);
+        out += "{\"type\":\"sample\"";
+        out += ",\"timestampMs\":";        out += std::to_string(nowMs());
+        out += ",\"x\":";                  out += std::to_string(ci.ptScreenPos.x);
+        out += ",\"y\":";                  out += std::to_string(ci.ptScreenPos.y);
+        out += ",\"visible\":";            out += visible      ? "true" : "false";
+        out += ",\"handle\":";             out += hc ? ("\"" + handleStr + "\"") : "null";
+        out += ",\"cursorType\":";         out += cursorType   ? ("\"" + std::string(cursorType) + "\"") : "null";
+        out += ",\"leftButtonDown\":";     out += leftDown     ? "true" : "false";
+        out += ",\"leftButtonPressed\":";  out += leftPressed  ? "true" : "false";
+        out += ",\"leftButtonReleased\":"; out += leftReleased ? "true" : "false";
+        out += ",\"bounds\":";             out += boundsJson;
+        out += ",\"asset\":";              out += assetJson.empty() ? "null" : assetJson;
+        out += "}";
+
+        writeJsonLine(out);
+
+        // Exit if stdout pipe is broken (parent process died)
+        if (std::cout.fail()) {
+            PostThreadMessage(g_mainThreadId, WM_QUIT, 0, 0);
+            break;
+        }
+
+        std::this_thread::sleep_for(std::chrono::milliseconds(intervalMs));
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// main
+// ─────────────────────────────────────────────────────────────────────────────
+int main(int argc, char* argv[]) {
+    if (argc < 2) {
+        std::cerr << "Usage: cursor-sampler <intervalMs> [windowHandle]" << std::endl;
+        return 1;
+    }
+
+    const int intervalMs = std::max(1, std::atoi(argv[1]));
+
+    HWND targetWindow = nullptr;
+    if (argc >= 3) {
+        const std::string arg = argv[2];
+        if (!arg.empty() && arg != "null") {
+            try {
+                const int      base = (arg.rfind("0x", 0) == 0 || arg.rfind("0X", 0) == 0) ? 16 : 10;
+                const uint64_t v    = std::stoull(arg, nullptr, base);
+                if (v) targetWindow = reinterpret_cast<HWND>(static_cast<uintptr_t>(v));
+            } catch (...) {}
+        }
+    }
+
+    // Initialize GDI+
+    Gdiplus::GdiplusStartupInput gdipInput{};
+    ULONG_PTR gdipToken = 0;
+    if (Gdiplus::GdiplusStartup(&gdipToken, &gdipInput, nullptr) != Gdiplus::Ok) {
+        std::cerr << "GDI+ init failed" << std::endl;
+        return 1;
+    }
+
+    CLSID pngClsid{};
+    if (!getPngClsid(pngClsid)) {
+        std::cerr << "PNG encoder not found" << std::endl;
+        Gdiplus::GdiplusShutdown(gdipToken);
+        return 1;
+    }
+
+    // Install global low-level mouse hook on this thread
+    g_mouseHook = SetWindowsHookEx(WH_MOUSE_LL, LowLevelMouseProc, GetModuleHandle(nullptr), 0);
+    if (!g_mouseHook) {
+        std::cerr << "SetWindowsHookEx failed" << std::endl;
+        Gdiplus::GdiplusShutdown(gdipToken);
+        return 1;
+    }
+
+    // Prime GetAsyncKeyState so the first poll doesn't return stale "since-last-call" bits
+    GetAsyncKeyState(VK_LBUTTON);
+
+    // Signal readiness
+    g_mainThreadId = GetCurrentThreadId();
+    {
+        char buf[80];
+        std::snprintf(buf, sizeof(buf),
+            "{\"type\":\"ready\",\"timestampMs\":%" PRId64 "}", nowMs());
+        writeJsonLine(buf);
+    }
+
+    // Start sampling on a background thread
+    std::thread sampler(runSamplingLoop, intervalMs, targetWindow, std::cref(pngClsid));
+
+    // Run the message pump on the main thread — required for WH_MOUSE_LL callbacks
+    MSG msg;
+    while (GetMessage(&msg, nullptr, 0, 0) > 0) {
+        TranslateMessage(&msg);
+        DispatchMessage(&msg);
+    }
+
+    g_stop.store(true, std::memory_order_relaxed);
+    if (sampler.joinable()) sampler.join();
+    UnhookWindowsHookEx(g_mouseHook);
+    Gdiplus::GdiplusShutdown(gdipToken);
+    return 0;
+}

electron/native/wgc-capture/src/dshow_webcam_capture.cpp

@@ -0,0 +1,427 @@
+#include "dshow_webcam_capture.h"
+
+#include <initguid.h>
+#include <dshow.h>
+#include <wrl/client.h>
+
+#include <algorithm>
+#include <array>
+#include <chrono>
+#include <exception>
+#include <iomanip>
+#include <iostream>
+#include <sstream>
+
+namespace {
+
+const CLSID CLSID_SampleGrabberLocal = {0xC1F400A0, 0x3F08, 0x11D3, {0x9F, 0x0B, 0x00, 0x60, 0x08, 0x03, 0x9E, 0x37}};
+const CLSID CLSID_NullRendererLocal = {0xC1F400A4, 0x3F08, 0x11D3, {0x9F, 0x0B, 0x00, 0x60, 0x08, 0x03, 0x9E, 0x37}};
+
+MIDL_INTERFACE("6B652FFF-11FE-4FCE-92AD-0266B5D7C78F")
+ISampleGrabber : public IUnknown {
+public:
+    virtual HRESULT STDMETHODCALLTYPE SetOneShot(BOOL oneShot) = 0;
+    virtual HRESULT STDMETHODCALLTYPE SetMediaType(const AM_MEDIA_TYPE* type) = 0;
+    virtual HRESULT STDMETHODCALLTYPE GetConnectedMediaType(AM_MEDIA_TYPE* type) = 0;
+    virtual HRESULT STDMETHODCALLTYPE SetBufferSamples(BOOL bufferThem) = 0;
+    virtual HRESULT STDMETHODCALLTYPE GetCurrentBuffer(long* bufferSize, long* buffer) = 0;
+    virtual HRESULT STDMETHODCALLTYPE GetCurrentSample(IMediaSample** sample) = 0;
+    virtual HRESULT STDMETHODCALLTYPE SetCallback(IUnknown* callback, long whichMethodToCallback) = 0;
+};
+
+bool succeeded(HRESULT hr, const char* label) {
+    if (SUCCEEDED(hr)) {
+        return true;
+    }
+
+    std::cerr << "ERROR: " << label << " failed (hr=0x" << std::hex << hr << std::dec << ")"
+              << std::endl;
+    return false;
+}
+
+std::string guidToString(const GUID& guid) {
+    if (guid == MEDIASUBTYPE_RGB32) {
+        return "RGB32";
+    }
+    if (guid == MEDIASUBTYPE_YUY2) {
+        return "YUY2";
+    }
+    if (guid == MEDIASUBTYPE_NV12) {
+        return "NV12";
+    }
+
+    std::ostringstream stream;
+    stream << std::hex << std::setfill('0')
+           << '{' << std::setw(8) << guid.Data1
+           << '-' << std::setw(4) << guid.Data2
+           << '-' << std::setw(4) << guid.Data3
+           << '-';
+    for (int index = 0; index < 2; index += 1) {
+        stream << std::setw(2) << static_cast<int>(guid.Data4[index]);
+    }
+    stream << '-';
+    for (int index = 2; index < 8; index += 1) {
+        stream << std::setw(2) << static_cast<int>(guid.Data4[index]);
+    }
+    stream << '}';
+    return stream.str();
+}
+
+void freeMediaType(AM_MEDIA_TYPE& type) {
+    if (type.cbFormat != 0) {
+        CoTaskMemFree(type.pbFormat);
+        type.cbFormat = 0;
+        type.pbFormat = nullptr;
+    }
+    if (type.pUnk) {
+        type.pUnk->Release();
+        type.pUnk = nullptr;
+    }
+}
+
+BYTE clampToByte(int value) {
+    return static_cast<BYTE>(std::clamp(value, 0, 255));
+}
+
+std::array<BYTE, 3> yuvToBgr(int y, int u, int v) {
+    const int c = y - 16;
+    const int d = u - 128;
+    const int e = v - 128;
+    const int blue = (298 * c + 516 * d + 128) >> 8;
+    const int green = (298 * c - 100 * d - 208 * e + 128) >> 8;
+    const int red = (298 * c + 409 * e + 128) >> 8;
+    return {clampToByte(blue), clampToByte(green), clampToByte(red)};
+}
+
+} // namespace
+
+struct DirectShowWebcamCapture::Impl {
+    Microsoft::WRL::ComPtr<IGraphBuilder> graph;
+    Microsoft::WRL::ComPtr<ICaptureGraphBuilder2> captureGraph;
+    Microsoft::WRL::ComPtr<IBaseFilter> captureFilter;
+    Microsoft::WRL::ComPtr<IBaseFilter> sampleGrabberFilter;
+    Microsoft::WRL::ComPtr<ISampleGrabber> sampleGrabber;
+    Microsoft::WRL::ComPtr<IBaseFilter> nullRenderer;
+    Microsoft::WRL::ComPtr<IMediaControl> mediaControl;
+    bool comInitialized = false;
+    bool running = false;
+};
+
+DirectShowWebcamCapture::~DirectShowWebcamCapture() {
+    stop();
+    delete impl_;
+}
+
+bool DirectShowWebcamCapture::initialize(
+    const std::wstring& deviceId,
+    const std::wstring& deviceName,
+    const std::wstring& directShowClsid,
+    int requestedWidth,
+    int requestedHeight,
+    int requestedFps) {
+    (void)deviceId;
+    stop();
+    delete impl_;
+    impl_ = nullptr;
+    impl_ = new Impl();
+    fps_ = std::clamp(requestedFps > 0 ? requestedFps : 30, 1, 60);
+
+    HRESULT hr = CoInitializeEx(nullptr, COINIT_MULTITHREADED);
+    if (SUCCEEDED(hr)) {
+        impl_->comInitialized = true;
+    } else if (hr != RPC_E_CHANGED_MODE) {
+        return succeeded(hr, "CoInitializeEx(DirectShow webcam)");
+    }
+
+    if (directShowClsid.empty()) {
+        std::cerr << "ERROR: DirectShow webcam fallback requires a resolved filter CLSID" << std::endl;
+        return false;
+    }
+
+    CLSID selectedClsid{};
+    if (FAILED(CLSIDFromString(directShowClsid.c_str(), &selectedClsid))) {
+        std::cerr << "ERROR: DirectShow webcam fallback received an invalid filter CLSID" << std::endl;
+        return false;
+    }
+    selectedDeviceName_ = deviceName.empty() ? directShowClsid : deviceName;
+
+    if (!succeeded(CoCreateInstance(selectedClsid, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&impl_->captureFilter)),
+                   "CoCreateInstance(DirectShow webcam filter)")) {
+        return false;
+    }
+    if (!succeeded(CoCreateInstance(CLSID_FilterGraph, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&impl_->graph)),
+                   "CoCreateInstance(FilterGraph)")) {
+        return false;
+    }
+    if (!succeeded(CoCreateInstance(CLSID_CaptureGraphBuilder2, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&impl_->captureGraph)),
+                   "CoCreateInstance(CaptureGraphBuilder2)")) {
+        return false;
+    }
+    if (!succeeded(impl_->captureGraph->SetFiltergraph(impl_->graph.Get()), "SetFiltergraph(DirectShow webcam)")) {
+        return false;
+    }
+    if (!succeeded(impl_->graph->AddFilter(impl_->captureFilter.Get(), L"OpenScreen Webcam Source"),
+                   "AddFilter(DirectShow webcam source)")) {
+        return false;
+    }
+
+    if (!succeeded(CoCreateInstance(CLSID_SampleGrabberLocal, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&impl_->sampleGrabberFilter)),
+                   "CoCreateInstance(SampleGrabber)")) {
+        return false;
+    }
+    if (!succeeded(impl_->sampleGrabberFilter.As(&impl_->sampleGrabber), "QueryInterface(ISampleGrabber)")) {
+        return false;
+    }
+
+    AM_MEDIA_TYPE requestedType{};
+    requestedType.majortype = MEDIATYPE_Video;
+    requestedType.formattype = FORMAT_VideoInfo;
+    if (!succeeded(impl_->sampleGrabber->SetMediaType(&requestedType), "SetMediaType(DirectShow video)")) {
+        return false;
+    }
+
+    if (!succeeded(impl_->graph->AddFilter(impl_->sampleGrabberFilter.Get(), L"OpenScreen Webcam Sample Grabber"),
+                   "AddFilter(SampleGrabber)")) {
+        return false;
+    }
+    if (!succeeded(CoCreateInstance(CLSID_NullRendererLocal, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&impl_->nullRenderer)),
+                   "CoCreateInstance(NullRenderer)")) {
+        return false;
+    }
+    if (!succeeded(impl_->graph->AddFilter(impl_->nullRenderer.Get(), L"OpenScreen Webcam Null Renderer"),
+                   "AddFilter(NullRenderer)")) {
+        return false;
+    }
+
+    if (!succeeded(impl_->captureGraph->RenderStream(
+            &PIN_CATEGORY_CAPTURE,
+            &MEDIATYPE_Video,
+            impl_->captureFilter.Get(),
+            impl_->sampleGrabberFilter.Get(),
+            impl_->nullRenderer.Get()),
+            "RenderStream(DirectShow webcam)")) {
+        return false;
+    }
+
+    AM_MEDIA_TYPE connectedType{};
+    if (!succeeded(impl_->sampleGrabber->GetConnectedMediaType(&connectedType), "GetConnectedMediaType(DirectShow webcam)")) {
+        return false;
+    }
+    if (connectedType.subtype == MEDIASUBTYPE_YUY2) {
+        pixelFormat_ = PixelFormat::Yuy2;
+    } else if (connectedType.subtype == MEDIASUBTYPE_NV12) {
+        pixelFormat_ = PixelFormat::Nv12;
+    } else if (connectedType.subtype == MEDIASUBTYPE_RGB32) {
+        pixelFormat_ = PixelFormat::Bgra;
+    } else {
+        std::cerr << "ERROR: Unsupported DirectShow webcam media subtype "
+                  << guidToString(connectedType.subtype) << std::endl;
+        freeMediaType(connectedType);
+        return false;
+    }
+    if (connectedType.formattype == FORMAT_VideoInfo && connectedType.pbFormat) {
+        const auto* videoInfo = reinterpret_cast<VIDEOINFOHEADER*>(connectedType.pbFormat);
+        width_ = std::abs(videoInfo->bmiHeader.biWidth);
+        height_ = std::abs(videoInfo->bmiHeader.biHeight);
+        const int bitsPerPixel = videoInfo->bmiHeader.biBitCount > 0 ? videoInfo->bmiHeader.biBitCount : 16;
+        if (pixelFormat_ == PixelFormat::Nv12) {
+            sourceStride_ = ((width_ + 3) / 4) * 4;
+        } else {
+            sourceStride_ = ((width_ * bitsPerPixel + 31) / 32) * 4;
+        }
+        sourceTopDown_ = pixelFormat_ != PixelFormat::Bgra || videoInfo->bmiHeader.biHeight < 0;
+    }
+    std::cerr << "INFO: DirectShow webcam connected subtype " << guidToString(connectedType.subtype)
+              << " " << width_ << "x" << height_ << " stride=" << sourceStride_ << std::endl;
+    freeMediaType(connectedType);
+    if (width_ <= 0 || height_ <= 0) {
+        width_ = requestedWidth > 0 ? requestedWidth : 1280;
+        height_ = requestedHeight > 0 ? requestedHeight : 720;
+    }
+    if (sourceStride_ <= 0) {
+        sourceStride_ = pixelFormat_ == PixelFormat::Bgra ? width_ * 4 : ((width_ + 3) / 4) * 4;
+    }
+
+    impl_->sampleGrabber->SetBufferSamples(TRUE);
+    impl_->sampleGrabber->SetOneShot(FALSE);
+    if (!succeeded(impl_->graph.As(&impl_->mediaControl), "QueryInterface(IMediaControl)")) {
+        return false;
+    }
+
+    return true;
+}
+
+bool DirectShowWebcamCapture::start() {
+    if (!impl_ || !impl_->mediaControl || impl_->running) {
+        return false;
+    }
+    HRESULT hr = impl_->mediaControl->Run();
+    if (!succeeded(hr, "Run(DirectShow webcam)")) {
+        return false;
+    }
+    stopRequested_ = false;
+    try {
+        thread_ = std::thread(&DirectShowWebcamCapture::captureLoop, this);
+    } catch (const std::exception& error) {
+        stopRequested_ = true;
+        impl_->mediaControl->Stop();
+        std::cerr << "ERROR: Failed to start DirectShow webcam capture thread: " << error.what() << std::endl;
+        return false;
+    } catch (...) {
+        stopRequested_ = true;
+        impl_->mediaControl->Stop();
+        std::cerr << "ERROR: Failed to start DirectShow webcam capture thread" << std::endl;
+        return false;
+    }
+    impl_->running = true;
+    return true;
+}
+
+void DirectShowWebcamCapture::stop() {
+    stopRequested_ = true;
+    if (thread_.joinable()) {
+        thread_.join();
+    }
+    if (!impl_) {
+        return;
+    }
+    if (impl_->mediaControl && impl_->running) {
+        impl_->mediaControl->Stop();
+    }
+    impl_->running = false;
+    impl_->mediaControl.Reset();
+    impl_->nullRenderer.Reset();
+    impl_->sampleGrabber.Reset();
+    impl_->sampleGrabberFilter.Reset();
+    impl_->captureFilter.Reset();
+    impl_->captureGraph.Reset();
+    impl_->graph.Reset();
+    if (impl_->comInitialized) {
+        CoUninitialize();
+        impl_->comInitialized = false;
+    }
+}
+
+void DirectShowWebcamCapture::captureLoop() {
+    const HRESULT coinitHr = CoInitializeEx(nullptr, COINIT_MULTITHREADED);
+    while (!stopRequested_ && impl_ && impl_->sampleGrabber) {
+        long bufferSize = 0;
+        HRESULT hr = impl_->sampleGrabber->GetCurrentBuffer(&bufferSize, nullptr);
+        if (SUCCEEDED(hr) && bufferSize > 0) {
+            std::vector<BYTE> buffer(static_cast<size_t>(bufferSize));
+            hr = impl_->sampleGrabber->GetCurrentBuffer(&bufferSize, reinterpret_cast<long*>(buffer.data()));
+            if (SUCCEEDED(hr)) {
+                storeFrame(buffer.data(), bufferSize);
+            }
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(1000 / std::max(1, fps_)));
+    }
+    if (SUCCEEDED(coinitHr)) {
+        CoUninitialize();
+    }
+}
+
+void DirectShowWebcamCapture::storeFrame(const BYTE* buffer, long length) {
+    const int destinationStride = width_ * 4;
+    const int sourceStride = sourceStride_ > 0 ? sourceStride_ : destinationStride;
+    const int expectedLength = pixelFormat_ == PixelFormat::Nv12
+        ? sourceStride * height_ + sourceStride * ((height_ + 1) / 2)
+        : sourceStride * height_;
+    if (!buffer || length < expectedLength || width_ <= 0 || height_ <= 0) {
+        return;
+    }
+
+    std::vector<BYTE> frame(static_cast<size_t>(destinationStride * height_));
+    for (int y = 0; y < height_; y += 1) {
+        const int sourceY = sourceTopDown_ ? y : height_ - 1 - y;
+        const BYTE* source = buffer + sourceY * sourceStride;
+        BYTE* destination = frame.data() + y * destinationStride;
+        if (pixelFormat_ == PixelFormat::Bgra) {
+            std::copy(source, source + destinationStride, destination);
+            for (int x = 0; x < width_; x += 1) {
+                destination[x * 4 + 3] = 255;
+            }
+            continue;
+        }
+
+        if (pixelFormat_ == PixelFormat::Nv12) {
+            const BYTE* yPlane = buffer + sourceY * sourceStride;
+            const BYTE* uvPlane = buffer + sourceStride * height_ + (sourceY / 2) * sourceStride;
+            for (int x = 0; x < width_; x += 1) {
+                const int uvX = (x / 2) * 2;
+                const auto color = yuvToBgr(yPlane[x], uvPlane[uvX], uvPlane[uvX + 1]);
+                BYTE* pixel = destination + x * 4;
+                pixel[0] = color[0];
+                pixel[1] = color[1];
+                pixel[2] = color[2];
+                pixel[3] = 255;
+            }
+            continue;
+        }
+
+        for (int x = 0; x + 1 < width_; x += 2) {
+            const BYTE y0 = source[x * 2];
+            const BYTE u = source[x * 2 + 1];
+            const BYTE y1 = source[x * 2 + 2];
+            const BYTE v = source[x * 2 + 3];
+            const auto first = yuvToBgr(y0, u, v);
+            const auto second = yuvToBgr(y1, u, v);
+            BYTE* firstPixel = destination + x * 4;
+            BYTE* secondPixel = firstPixel + 4;
+            firstPixel[0] = first[0];
+            firstPixel[1] = first[1];
+            firstPixel[2] = first[2];
+            firstPixel[3] = 255;
+            secondPixel[0] = second[0];
+            secondPixel[1] = second[1];
+            secondPixel[2] = second[2];
+            secondPixel[3] = 255;
+        }
+        if (width_ % 2 == 1) {
+            const int x = width_ - 1;
+            const int previousPairStart = ((x - 1) / 2) * 4;
+            const BYTE y = source[x * 2];
+            const BYTE u = source[previousPairStart + 1];
+            const BYTE v = source[previousPairStart + 3];
+            const auto color = yuvToBgr(y, u, v);
+            BYTE* pixel = destination + x * 4;
+            pixel[0] = color[0];
+            pixel[1] = color[1];
+            pixel[2] = color[2];
+            pixel[3] = 255;
+        }
+    }
+
+    std::scoped_lock lock(frameMutex_);
+    latestFrame_ = std::move(frame);
+    latestFrameSequence_ += 1;
+}
+
+bool DirectShowWebcamCapture::copyLatestFrame(WebcamFrameSnapshot& destination) {
+    std::scoped_lock lock(frameMutex_);
+    if (latestFrame_.empty() || width_ <= 0 || height_ <= 0) {
+        return false;
+    }
+
+    destination.data = latestFrame_;
+    destination.width = width_;
+    destination.height = height_;
+    destination.sequence = latestFrameSequence_;
+    return true;
+}
+
+int DirectShowWebcamCapture::width() const {
+    return width_;
+}
+
+int DirectShowWebcamCapture::height() const {
+    return height_;
+}
+
+int DirectShowWebcamCapture::fps() const {
+    return fps_;
+}
+
+const std::wstring& DirectShowWebcamCapture::selectedDeviceName() const {
+    return selectedDeviceName_;
+}

electron/native/wgc-capture/src/dshow_webcam_capture.h

@@ -0,0 +1,67 @@
+#pragma once
+
+#include <Windows.h>
+
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+struct WebcamFrameSnapshot {
+    std::vector<BYTE> data;
+    int width = 0;
+    int height = 0;
+    uint64_t sequence = 0;
+};
+
+class DirectShowWebcamCapture {
+public:
+    DirectShowWebcamCapture() = default;
+    ~DirectShowWebcamCapture();
+
+    DirectShowWebcamCapture(const DirectShowWebcamCapture&) = delete;
+    DirectShowWebcamCapture& operator=(const DirectShowWebcamCapture&) = delete;
+
+    bool initialize(
+        const std::wstring& deviceId,
+        const std::wstring& deviceName,
+        const std::wstring& directShowClsid,
+        int requestedWidth,
+        int requestedHeight,
+        int requestedFps);
+    bool start();
+    void stop();
+    bool copyLatestFrame(WebcamFrameSnapshot& destination);
+
+    int width() const;
+    int height() const;
+    int fps() const;
+    const std::wstring& selectedDeviceName() const;
+    void storeFrame(const BYTE* buffer, long length);
+
+private:
+    enum class PixelFormat {
+        Bgra,
+        Nv12,
+        Yuy2,
+    };
+
+    struct Impl;
+    void captureLoop();
+
+    Impl* impl_ = nullptr;
+    std::thread thread_;
+    std::atomic<bool> stopRequested_ = false;
+    std::mutex frameMutex_;
+    std::vector<BYTE> latestFrame_;
+    uint64_t latestFrameSequence_ = 0;
+    int width_ = 0;
+    int height_ = 0;
+    int fps_ = 30;
+    int sourceStride_ = 0;
+    bool sourceTopDown_ = false;
+    PixelFormat pixelFormat_ = PixelFormat::Bgra;
+    std::wstring selectedDeviceName_;
+};

electron/native/wgc-capture/src/main.cpp

@@ -0,0 +1,802 @@
+#include "audio_sample_utils.h"
+#include "mf_encoder.h"
+#include "monitor_utils.h"
+#include "wasapi_loopback_capture.h"
+#include "webcam_capture.h"
+#include "wgc_session.h"
+
+#include <winrt/Windows.Foundation.h>
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cctype>
+#include <cstdint>
+#include <iostream>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+
+namespace {
+
+struct CaptureConfig {
+    int schemaVersion = 1;
+    int64_t displayId = 0;
+    int64_t recordingId = 0;
+    std::string sourceType = "display";
+    std::string sourceId;
+    std::string windowHandle;
+    std::string outputPath;
+    std::string webcamOutputPath;
+    int fps = 60;
+    int width = 0;
+    int height = 0;
+    MonitorBounds bounds{};
+    bool hasDisplayBounds = false;
+    bool captureSystemAudio = false;
+    bool captureMic = false;
+    bool captureCursor = false;
+    bool webcamEnabled = false;
+    std::string microphoneDeviceId;
+    std::string microphoneDeviceName;
+    double microphoneGain = 1.0;
+    std::string webcamDeviceId;
+    std::string webcamDeviceName;
+    std::string webcamDirectShowClsid;
+    int webcamWidth = 0;
+    int webcamHeight = 0;
+    int webcamFps = 0;
+};
+
+std::wstring utf8ToWide(const std::string& value) {
+    if (value.empty()) {
+        return {};
+    }
+
+    const int size = MultiByteToWideChar(CP_UTF8, 0, value.data(), static_cast<int>(value.size()), nullptr, 0);
+    std::wstring result(static_cast<size_t>(size), L'\0');
+    MultiByteToWideChar(CP_UTF8, 0, value.data(), static_cast<int>(value.size()), result.data(), size);
+    return result;
+}
+
+std::string wideToUtf8(const std::wstring& value) {
+    if (value.empty()) {
+        return {};
+    }
+
+    const int size = WideCharToMultiByte(CP_UTF8, 0, value.data(), static_cast<int>(value.size()), nullptr, 0, nullptr, nullptr);
+    std::string result(static_cast<size_t>(size), '\0');
+    WideCharToMultiByte(CP_UTF8, 0, value.data(), static_cast<int>(value.size()), result.data(), size, nullptr, nullptr);
+    return result;
+}
+
+std::string jsonEscape(const std::string& value) {
+    std::string result;
+    result.reserve(value.size());
+    for (const char c : value) {
+        switch (c) {
+            case '\\':
+                result += "\\\\";
+                break;
+            case '"':
+                result += "\\\"";
+                break;
+            case '\n':
+                result += "\\n";
+                break;
+            case '\r':
+                result += "\\r";
+                break;
+            case '\t':
+                result += "\\t";
+                break;
+            default:
+                result.push_back(c);
+                break;
+        }
+    }
+    return result;
+}
+
+bool hasVisibleBgraContent(const std::vector<BYTE>& frame) {
+    if (frame.size() < 4) {
+        return false;
+    }
+
+    uint64_t lumaTotal = 0;
+    BYTE maxLuma = 0;
+    const size_t pixelCount = frame.size() / 4;
+    const size_t step = std::max<size_t>(1, pixelCount / 4096);
+    size_t sampledPixels = 0;
+    for (size_t pixel = 0; pixel < pixelCount; pixel += step) {
+        const size_t offset = pixel * 4;
+        const BYTE b = frame[offset + 0];
+        const BYTE g = frame[offset + 1];
+        const BYTE r = frame[offset + 2];
+        const BYTE luma = static_cast<BYTE>((static_cast<uint16_t>(r) * 54 + static_cast<uint16_t>(g) * 183 + static_cast<uint16_t>(b) * 19) >> 8);
+        lumaTotal += luma;
+        maxLuma = std::max(maxLuma, luma);
+        sampledPixels += 1;
+    }
+
+    const uint64_t averageLuma = sampledPixels > 0 ? lumaTotal / sampledPixels : 0;
+    return maxLuma > 24 || averageLuma > 4;
+}
+
+bool findBool(const std::string& json, const std::string& key, bool fallback) {
+    auto pos = json.find("\"" + key + "\"");
+    if (pos == std::string::npos) {
+        return fallback;
+    }
+    pos = json.find(':', pos);
+    if (pos == std::string::npos) {
+        return fallback;
+    }
+    pos += 1;
+    while (pos < json.size() && std::isspace(static_cast<unsigned char>(json[pos]))) {
+        pos += 1;
+    }
+    if (json.compare(pos, 4, "true") == 0) {
+        return true;
+    }
+    if (json.compare(pos, 5, "false") == 0) {
+        return false;
+    }
+    return fallback;
+}
+
+int64_t findInt64(const std::string& json, const std::string& key, int64_t fallback) {
+    auto pos = json.find("\"" + key + "\"");
+    if (pos == std::string::npos) {
+        return fallback;
+    }
+    pos = json.find(':', pos);
+    if (pos == std::string::npos) {
+        return fallback;
+    }
+    pos += 1;
+    while (pos < json.size() && std::isspace(static_cast<unsigned char>(json[pos]))) {
+        pos += 1;
+    }
+    try {
+        return std::stoll(json.substr(pos));
+    } catch (...) {
+        return fallback;
+    }
+}
+
+int findInt(const std::string& json, const std::string& key, int fallback) {
+    return static_cast<int>(findInt64(json, key, fallback));
+}
+
+double findDouble(const std::string& json, const std::string& key, double fallback) {
+    auto pos = json.find("\"" + key + "\"");
+    if (pos == std::string::npos) {
+        return fallback;
+    }
+    pos = json.find(':', pos);
+    if (pos == std::string::npos) {
+        return fallback;
+    }
+    pos += 1;
+    while (pos < json.size() && std::isspace(static_cast<unsigned char>(json[pos]))) {
+        pos += 1;
+    }
+    try {
+        return std::stod(json.substr(pos));
+    } catch (...) {
+        return fallback;
+    }
+}
+
+std::string findString(const std::string& json, const std::string& key) {
+    auto pos = json.find("\"" + key + "\"");
+    if (pos == std::string::npos) {
+        return {};
+    }
+    pos = json.find(':', pos);
+    if (pos == std::string::npos) {
+        return {};
+    }
+    pos += 1;
+    while (pos < json.size() && std::isspace(static_cast<unsigned char>(json[pos]))) {
+        pos += 1;
+    }
+    if (pos >= json.size() || json[pos] != '"') {
+        return {};
+    }
+    pos += 1;
+
+    std::string result;
+    while (pos < json.size()) {
+        const char c = json[pos++];
+        if (c == '"') {
+            break;
+        }
+        if (c == '\\' && pos < json.size()) {
+            const char escaped = json[pos++];
+            switch (escaped) {
+                case '\\':
+                case '"':
+                case '/':
+                    result.push_back(escaped);
+                    break;
+                case 'n':
+                    result.push_back('\n');
+                    break;
+                case 'r':
+                    result.push_back('\r');
+                    break;
+                case 't':
+                    result.push_back('\t');
+                    break;
+                default:
+                    result.push_back(escaped);
+                    break;
+            }
+            continue;
+        }
+        result.push_back(c);
+    }
+    return result;
+}
+
+std::string parseWindowHandleFromSourceId(const std::string& sourceId) {
+    constexpr char prefix[] = "window:";
+    if (sourceId.rfind(prefix, 0) != 0) {
+        return {};
+    }
+
+    const size_t start = sizeof(prefix) - 1;
+    const size_t end = sourceId.find(':', start);
+    const std::string handle = sourceId.substr(start, end == std::string::npos ? std::string::npos : end - start);
+    return handle.empty() ? std::string{} : handle;
+}
+
+HWND parseWindowHandle(const std::string& value) {
+    if (value.empty()) {
+        return nullptr;
+    }
+
+    try {
+        size_t parsed = 0;
+        const int base = value.rfind("0x", 0) == 0 || value.rfind("0X", 0) == 0 ? 16 : 10;
+        const uint64_t handleValue = std::stoull(value, &parsed, base);
+        if (parsed != value.size() || handleValue == 0) {
+            return nullptr;
+        }
+        return reinterpret_cast<HWND>(static_cast<uintptr_t>(handleValue));
+    } catch (...) {
+        return nullptr;
+    }
+}
+
+bool parseConfig(const std::string& json, CaptureConfig& config) {
+    config.schemaVersion = findInt(json, "schemaVersion", 1);
+    config.outputPath = findString(json, "screenPath");
+    if (config.outputPath.empty()) {
+        config.outputPath = findString(json, "outputPath");
+    }
+    if (config.outputPath.empty()) {
+        return false;
+    }
+
+    config.recordingId = findInt64(json, "recordingId", 0);
+    config.sourceType = findString(json, "sourceType");
+    if (config.sourceType.empty()) {
+        config.sourceType = "display";
+    }
+    config.sourceId = findString(json, "sourceId");
+    config.windowHandle = findString(json, "windowHandle");
+    if (config.windowHandle.empty()) {
+        config.windowHandle = parseWindowHandleFromSourceId(config.sourceId);
+    }
+    config.displayId = findInt64(json, "displayId", 0);
+    config.fps = std::clamp(findInt(json, "fps", 60), 1, 120);
+    config.width = findInt(json, "videoWidth", findInt(json, "width", 0));
+    config.height = findInt(json, "videoHeight", findInt(json, "height", 0));
+    config.bounds.x = findInt(json, "displayX", 0);
+    config.bounds.y = findInt(json, "displayY", 0);
+    config.bounds.width = findInt(json, "displayW", 0);
+    config.bounds.height = findInt(json, "displayH", 0);
+    config.hasDisplayBounds = findBool(json, "hasDisplayBounds", false);
+    config.captureSystemAudio = findBool(json, "captureSystemAudio", false);
+    config.captureMic = findBool(json, "captureMic", false);
+    config.captureCursor = findBool(json, "captureCursor", false);
+    config.webcamEnabled = findBool(json, "webcamEnabled", false);
+    config.microphoneDeviceId = findString(json, "microphoneDeviceId");
+    config.microphoneDeviceName = findString(json, "microphoneDeviceName");
+    config.microphoneGain = findDouble(json, "microphoneGain", 1.0);
+    config.webcamDeviceId = findString(json, "webcamDeviceId");
+    config.webcamDeviceName = findString(json, "webcamDeviceName");
+    config.webcamDirectShowClsid = findString(json, "webcamDirectShowClsid");
+    config.webcamOutputPath = findString(json, "webcamPath");
+    config.webcamWidth = findInt(json, "webcamWidth", 0);
+    config.webcamHeight = findInt(json, "webcamHeight", 0);
+    config.webcamFps = findInt(json, "webcamFps", 0);
+    return true;
+}
+
+void readStopCommands(std::atomic<bool>& stopRequested, std::condition_variable& cv) {
+    std::string line;
+    while (std::getline(std::cin, line)) {
+        if (line == "stop" || line == "q" || line == "quit") {
+            stopRequested = true;
+            cv.notify_all();
+            return;
+        }
+    }
+    stopRequested = true;
+    cv.notify_all();
+}
+
+} // namespace
+
+int main(int argc, char* argv[]) {
+    if (argc < 2) {
+        std::cerr << "ERROR: Missing JSON config argument" << std::endl;
+        return 1;
+    }
+
+    winrt::init_apartment(winrt::apartment_type::multi_threaded);
+
+    CaptureConfig config;
+    if (!parseConfig(argv[1], config)) {
+        std::cerr << "ERROR: Failed to parse config JSON" << std::endl;
+        return 1;
+    }
+
+    std::cout << "{\"event\":\"ready\",\"schemaVersion\":2}" << std::endl;
+
+    WgcSession session;
+    if (config.sourceType == "display") {
+        HMONITOR monitor = findMonitorForCapture(
+            config.displayId,
+            config.hasDisplayBounds ? &config.bounds : nullptr);
+        if (!monitor) {
+            std::cerr << "ERROR: Could not resolve monitor" << std::endl;
+            return 1;
+        }
+        if (!session.initialize(monitor, config.fps, config.captureCursor)) {
+            std::cerr << "ERROR: Failed to initialize WGC display session" << std::endl;
+            return 1;
+        }
+    } else if (config.sourceType == "window") {
+        HWND window = parseWindowHandle(config.windowHandle);
+        if (!window || !IsWindow(window)) {
+            std::cerr << "ERROR: Native window capture requires a valid HWND" << std::endl;
+            return 1;
+        }
+        if (!session.initialize(window, config.fps, config.captureCursor)) {
+            std::cerr << "ERROR: Failed to initialize WGC window session" << std::endl;
+            return 1;
+        }
+    } else {
+        std::cerr << "ERROR: Unsupported native capture source type: " << config.sourceType << std::endl;
+        return 1;
+    }
+
+    // WGC owns the captured texture size. Encoding must use that exact size
+    // until a dedicated GPU scaling pass is introduced; CopyResource requires
+    // matching resource dimensions.
+    int width = session.captureWidth();
+    int height = session.captureHeight();
+    width = (std::max(2, width) / 2) * 2;
+    height = (std::max(2, height) / 2) * 2;
+
+    const int pixels = width * height;
+    const int bitrate = pixels >= 3840 * 2160 ? 45'000'000 : pixels >= 2560 * 1440 ? 28'000'000 : 18'000'000;
+
+    WebcamCapture webcamCapture;
+    bool webcamActive = false;
+    bool writeSeparateWebcam = false;
+    if (config.webcamEnabled) {
+        if (!webcamCapture.initialize(
+                utf8ToWide(config.webcamDeviceId),
+                utf8ToWide(config.webcamDeviceName),
+                utf8ToWide(config.webcamDirectShowClsid),
+                config.webcamWidth,
+                config.webcamHeight,
+                config.webcamFps > 0 ? config.webcamFps : config.fps)) {
+            std::cerr << "ERROR: Failed to initialize native webcam capture" << std::endl;
+            return 1;
+        }
+        std::cout << "{\"event\":\"webcam-format\",\"schemaVersion\":2,\"width\":" << webcamCapture.width()
+                  << ",\"height\":" << webcamCapture.height()
+                  << ",\"fps\":" << webcamCapture.fps()
+                  << ",\"deviceName\":\"" << jsonEscape(wideToUtf8(webcamCapture.selectedDeviceName()))
+                  << "\"}" << std::endl;
+        writeSeparateWebcam = !config.webcamOutputPath.empty();
+    }
+
+    WasapiLoopbackCapture loopbackCapture;
+    WasapiLoopbackCapture microphoneCapture;
+    const AudioInputFormat* audioFormat = nullptr;
+    AudioInputFormat encoderAudioFormat{};
+    AudioInputFormat systemAudioFormat{};
+    AudioInputFormat microphoneAudioFormat{};
+    if (config.captureSystemAudio) {
+        if (!loopbackCapture.initializeSystemLoopback()) {
+            std::cerr << "ERROR: Failed to initialize WASAPI loopback capture" << std::endl;
+            return 1;
+        }
+        systemAudioFormat = loopbackCapture.inputFormat();
+        audioFormat = &loopbackCapture.inputFormat();
+    }
+    if (config.captureMic) {
+        if (!microphoneCapture.initializeMicrophone(
+                utf8ToWide(config.microphoneDeviceId),
+                utf8ToWide(config.microphoneDeviceName))) {
+            std::cerr << "ERROR: Failed to initialize WASAPI microphone capture" << std::endl;
+            return 1;
+        }
+        microphoneAudioFormat = microphoneCapture.inputFormat();
+        if (!audioFormat) {
+            audioFormat = &microphoneCapture.inputFormat();
+        }
+    }
+    if (audioFormat) {
+        std::cout << "{\"event\":\"audio-format\",\"schemaVersion\":2,\"sampleRate\":" << audioFormat->sampleRate
+                  << ",\"channels\":" << audioFormat->channels
+                  << ",\"bitsPerSample\":" << audioFormat->bitsPerSample
+                  << ",\"system\":" << (config.captureSystemAudio ? "true" : "false")
+                  << ",\"microphone\":" << (config.captureMic ? "true" : "false");
+        if (config.captureMic) {
+            std::cout << ",\"microphoneDeviceName\":\""
+                      << jsonEscape(wideToUtf8(microphoneCapture.selectedDeviceName())) << "\"";
+        }
+        std::cout << "}" << std::endl;
+        encoderAudioFormat = makeAacCompatibleAudioFormat(*audioFormat);
+        std::cout << "{\"event\":\"encoder-audio-format\",\"schemaVersion\":2,\"sampleRate\":"
+                  << encoderAudioFormat.sampleRate
+                  << ",\"channels\":" << encoderAudioFormat.channels
+                  << ",\"bitsPerSample\":" << encoderAudioFormat.bitsPerSample
+                  << "}" << std::endl;
+    }
+
+    MFEncoder encoder;
+    if (!encoder.initialize(
+            utf8ToWide(config.outputPath),
+            width,
+            height,
+            config.fps,
+            bitrate,
+            session.device(),
+            session.context(),
+            audioFormat ? &encoderAudioFormat : nullptr)) {
+        std::cerr << "ERROR: Failed to initialize Media Foundation encoder" << std::endl;
+        return 1;
+    }
+
+    MFEncoder webcamEncoder;
+    if (writeSeparateWebcam) {
+        const int webcamPixels = std::max(1, webcamCapture.width()) * std::max(1, webcamCapture.height());
+        const int webcamBitrate = webcamPixels >= 1280 * 720 ? 8'000'000 : 4'000'000;
+        if (!webcamEncoder.initialize(
+                utf8ToWide(config.webcamOutputPath),
+                webcamCapture.width(),
+                webcamCapture.height(),
+                webcamCapture.fps(),
+                webcamBitrate,
+                session.device(),
+                session.context(),
+                nullptr)) {
+            std::cerr << "ERROR: Failed to initialize native webcam encoder" << std::endl;
+            return 1;
+        }
+    }
+
+    std::mutex mutex;
+    std::condition_variable cv;
+    std::atomic<bool> stopRequested = false;
+    std::atomic<bool> firstFrameWritten = false;
+    std::atomic<bool> encodeFailed = false;
+    Microsoft::WRL::ComPtr<ID3D11Texture2D> latestFrameTexture;
+    int64_t latestFrameTimestampHns = 0;
+    int64_t firstFrameTimestampHns = -1;
+    std::vector<BYTE> latestWebcamFrame;
+    int latestWebcamWidth = 0;
+    int latestWebcamHeight = 0;
+    uint64_t latestWebcamSequence = 0;
+    bool hasVisibleWebcamFrame = false;
+
+    session.setFrameCallback([&](ID3D11Texture2D* texture, int64_t timestampHns) {
+        if (stopRequested) {
+            return;
+        }
+
+        std::scoped_lock lock(mutex);
+        if (!latestFrameTexture) {
+            D3D11_TEXTURE2D_DESC desc{};
+            texture->GetDesc(&desc);
+            desc.BindFlags = 0;
+            desc.CPUAccessFlags = 0;
+            desc.MiscFlags = 0;
+            if (FAILED(session.device()->CreateTexture2D(&desc, nullptr, &latestFrameTexture))) {
+                encodeFailed = true;
+                stopRequested = true;
+                cv.notify_all();
+                return;
+            }
+        }
+
+        session.context()->CopyResource(latestFrameTexture.Get(), texture);
+        latestFrameTimestampHns = timestampHns;
+        if (!firstFrameWritten.exchange(true)) {
+            cv.notify_all();
+        }
+    });
+
+    auto writeVideoFrames = [&]() {
+        const auto startedAt = std::chrono::steady_clock::now();
+        uint64_t frameIndex = 0;
+        uint64_t lastWrittenWebcamSequence = 0;
+        uint64_t webcamOutputFrameIndex = 0;
+        int64_t lastEncodedVideoTimestampHns = -1;
+
+        while (!stopRequested && !encodeFailed) {
+            {
+                std::scoped_lock lock(mutex);
+                if (webcamActive) {
+                    WebcamFrameSnapshot candidateWebcamFrame;
+                    if (webcamCapture.copyLatestFrame(candidateWebcamFrame) &&
+                        candidateWebcamFrame.sequence != latestWebcamSequence &&
+                        hasVisibleBgraContent(candidateWebcamFrame.data)) {
+                        latestWebcamFrame = std::move(candidateWebcamFrame.data);
+                        latestWebcamWidth = candidateWebcamFrame.width;
+                        latestWebcamHeight = candidateWebcamFrame.height;
+                        latestWebcamSequence = candidateWebcamFrame.sequence;
+                        hasVisibleWebcamFrame = true;
+                    }
+                }
+                const BgraFrameView webcamFrame{
+                    hasVisibleWebcamFrame && !latestWebcamFrame.empty() ? latestWebcamFrame.data() : nullptr,
+                    latestWebcamWidth,
+                    latestWebcamHeight,
+                };
+                const int64_t syntheticTimestampHns =
+                    static_cast<int64_t>((frameIndex * 10'000'000ULL) / config.fps);
+                const int64_t sourceTimestampHns =
+                    latestFrameTimestampHns > 0 ? latestFrameTimestampHns : syntheticTimestampHns;
+                if (firstFrameTimestampHns < 0) {
+                    firstFrameTimestampHns = sourceTimestampHns;
+                }
+                int64_t frameTimestampHns =
+                    std::max<int64_t>(0, sourceTimestampHns - firstFrameTimestampHns);
+                if (lastEncodedVideoTimestampHns >= 0 &&
+                    frameTimestampHns <= lastEncodedVideoTimestampHns) {
+                    frameTimestampHns =
+                        lastEncodedVideoTimestampHns + static_cast<int64_t>(10'000'000ULL / config.fps);
+                }
+                if (writeSeparateWebcam && webcamFrame.data &&
+                    latestWebcamSequence != lastWrittenWebcamSequence) {
+                    const int64_t webcamTimestampHns = static_cast<int64_t>(
+                        (webcamOutputFrameIndex * 10'000'000ULL) / std::max(1, webcamCapture.fps()));
+                    if (!webcamEncoder.writeBgraFrame(webcamFrame, webcamTimestampHns)) {
+                        encodeFailed = true;
+                        stopRequested = true;
+                        cv.notify_all();
+                        return;
+                    }
+                    lastWrittenWebcamSequence = latestWebcamSequence;
+                    webcamOutputFrameIndex += 1;
+                }
+                if (latestFrameTexture && !encoder.writeFrame(
+                        latestFrameTexture.Get(),
+                        frameTimestampHns,
+                        !writeSeparateWebcam && webcamFrame.data ? &webcamFrame : nullptr)) {
+                    encodeFailed = true;
+                    stopRequested = true;
+                    cv.notify_all();
+                    return;
+                }
+                if (latestFrameTexture) {
+                    lastEncodedVideoTimestampHns = frameTimestampHns;
+                }
+            }
+
+            frameIndex += 1;
+            const auto nextDeadline = startedAt +
+                std::chrono::duration_cast<std::chrono::steady_clock::duration>(
+                    std::chrono::duration<double>(static_cast<double>(frameIndex) / config.fps));
+            std::this_thread::sleep_until(nextDeadline);
+        }
+    };
+
+    std::thread videoWriterThread;
+
+    auto stopVideoWriter = [&]() {
+        if (videoWriterThread.joinable()) {
+            videoWriterThread.join();
+        }
+    };
+
+    auto startVideoWriter = [&]() {
+        videoWriterThread = std::thread(writeVideoFrames);
+    };
+
+    std::unique_ptr<AudioMixer> audioMixer;
+    auto startAudioCaptures = [&]() -> bool {
+        if (!audioFormat) {
+            return true;
+        }
+
+        audioMixer = std::make_unique<AudioMixer>(
+            encoderAudioFormat,
+            config.captureSystemAudio ? systemAudioFormat : encoderAudioFormat,
+            config.captureMic ? microphoneAudioFormat : encoderAudioFormat,
+            config.captureSystemAudio,
+            config.captureMic,
+            config.microphoneGain,
+            [&](const BYTE* data, DWORD byteCount, int64_t timestampHns, int64_t durationHns) {
+                if (!encoder.writeAudio(data, byteCount, timestampHns, durationHns)) {
+                    encodeFailed = true;
+                    stopRequested = true;
+                    cv.notify_all();
+                    return false;
+                }
+                return true;
+            });
+
+        if (!audioMixer->start()) {
+            std::cerr << "ERROR: Failed to start native audio mixer" << std::endl;
+            return false;
+        }
+
+        if (config.captureMic) {
+            if (!microphoneCapture.start([&](const BYTE* data, DWORD byteCount, int64_t timestampHns, int64_t durationHns) {
+                    (void)timestampHns;
+                    (void)durationHns;
+                    if (stopRequested || !audioMixer) {
+                        return;
+                    }
+
+                    audioMixer->pushMicrophone(data, byteCount);
+                })) {
+                std::cerr << "ERROR: Failed to start WASAPI microphone capture" << std::endl;
+                audioMixer->stop();
+                return false;
+            }
+        }
+
+        if (config.captureSystemAudio) {
+            if (!loopbackCapture.start([&](const BYTE* data, DWORD byteCount, int64_t timestampHns, int64_t durationHns) {
+                    (void)timestampHns;
+                    (void)durationHns;
+                    if (stopRequested || !audioMixer) {
+                        return;
+                    }
+
+                    audioMixer->pushSystem(data, byteCount);
+                })) {
+                std::cerr << "ERROR: Failed to start WASAPI loopback capture" << std::endl;
+                microphoneCapture.stop();
+                audioMixer->stop();
+                return false;
+            }
+        }
+
+        return true;
+    };
+
+    if (!startAudioCaptures()) {
+        return 1;
+    }
+    if (config.webcamEnabled) {
+        if (!webcamCapture.start()) {
+            microphoneCapture.stop();
+            loopbackCapture.stop();
+            if (audioMixer) {
+                audioMixer->stop();
+            }
+            std::cerr << "ERROR: Failed to start native webcam capture" << std::endl;
+            return 1;
+        }
+        webcamActive = true;
+        const auto webcamDeadline = std::chrono::steady_clock::now() + std::chrono::seconds(3);
+        while (std::chrono::steady_clock::now() < webcamDeadline && !hasVisibleWebcamFrame) {
+            WebcamFrameSnapshot candidateWebcamFrame;
+            if (webcamCapture.copyLatestFrame(candidateWebcamFrame) &&
+                hasVisibleBgraContent(candidateWebcamFrame.data)) {
+                latestWebcamFrame = std::move(candidateWebcamFrame.data);
+                latestWebcamWidth = candidateWebcamFrame.width;
+                latestWebcamHeight = candidateWebcamFrame.height;
+                latestWebcamSequence = candidateWebcamFrame.sequence;
+                hasVisibleWebcamFrame = true;
+                break;
+            }
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        if (!hasVisibleWebcamFrame) {
+            std::cerr << "WARNING: Native webcam started but no visible frame was available before screen capture"
+                      << std::endl;
+        }
+    }
+
+    if (!session.start()) {
+        webcamCapture.stop();
+        microphoneCapture.stop();
+        loopbackCapture.stop();
+        if (audioMixer) {
+            audioMixer->stop();
+        }
+        std::cerr << "ERROR: Failed to start WGC session" << std::endl;
+        return 1;
+    }
+
+    std::thread stdinThread(readStopCommands, std::ref(stopRequested), std::ref(cv));
+
+    {
+        std::unique_lock lock(mutex);
+        const bool started = cv.wait_for(lock, std::chrono::seconds(10), [&] {
+            return firstFrameWritten.load() || stopRequested.load();
+        });
+        if (!started || !firstFrameWritten) {
+            stopRequested = true;
+            cv.notify_all();
+            if (stdinThread.joinable()) {
+                stdinThread.detach();
+            }
+            microphoneCapture.stop();
+            loopbackCapture.stop();
+            webcamCapture.stop();
+            if (audioMixer) {
+                audioMixer->stop();
+            }
+            session.stop();
+            std::cerr << "ERROR: Timed out waiting for first WGC frame" << std::endl;
+            return 1;
+        }
+    }
+
+    if (audioMixer) {
+        audioMixer->beginTimeline();
+    }
+    startVideoWriter();
+
+    std::cout << "{\"event\":\"recording-started\",\"schemaVersion\":2}" << std::endl;
+    std::cout << "Recording started" << std::endl;
+
+    {
+        std::unique_lock lock(mutex);
+        cv.wait(lock, [&] {
+            return stopRequested.load();
+        });
+    }
+
+    microphoneCapture.stop();
+    loopbackCapture.stop();
+    webcamCapture.stop();
+    if (audioMixer) {
+        audioMixer->stop();
+    }
+    stopVideoWriter();
+    session.stop();
+    {
+        std::scoped_lock lock(mutex);
+        encoder.finalize();
+        if (writeSeparateWebcam) {
+            webcamEncoder.finalize();
+        }
+    }
+
+    if (stdinThread.joinable()) {
+        stdinThread.detach();
+    }
+
+    if (encodeFailed) {
+        std::cerr << "ERROR: Failed to encode WGC frame" << std::endl;
+        return 1;
+    }
+
+    std::cout << "{\"event\":\"recording-stopped\",\"schemaVersion\":2,\"screenPath\":\""
+              << jsonEscape(config.outputPath) << "\"";
+    if (writeSeparateWebcam) {
+        std::cout << ",\"webcamPath\":\"" << jsonEscape(config.webcamOutputPath) << "\"";
+    }
+    std::cout << "}" << std::endl;
+    std::cout << "Recording stopped. Output path: " << config.outputPath << std::endl;
+    return 0;
+}

electron/native/wgc-capture/src/mf_encoder.cpp

@@ -0,0 +1,450 @@
+#include "mf_encoder.h"
+
+#include "audio_sample_utils.h"
+
+#include <mfapi.h>
+#include <mferror.h>
+#include <propvarutil.h>
+
+#include <algorithm>
+#include <cstring>
+#include <iostream>
+
+namespace {
+
+bool succeeded(HRESULT hr, const char* label) {
+    if (SUCCEEDED(hr)) {
+        return true;
+    }
+
+    std::cerr << "ERROR: " << label << " failed (hr=0x" << std::hex << hr << std::dec << ")"
+              << std::endl;
+    return false;
+}
+
+void setFrameSize(IMFMediaType* type, UINT32 width, UINT32 height) {
+    MFSetAttributeSize(type, MF_MT_FRAME_SIZE, width, height);
+}
+
+void setFrameRate(IMFMediaType* type, UINT32 fps) {
+    MFSetAttributeRatio(type, MF_MT_FRAME_RATE, fps, 1);
+}
+
+void setPixelAspectRatio(IMFMediaType* type) {
+    MFSetAttributeRatio(type, MF_MT_PIXEL_ASPECT_RATIO, 1, 1);
+}
+
+void setAudioFormat(IMFMediaType* type, UINT32 channels, UINT32 sampleRate, UINT32 bitsPerSample) {
+    type->SetUINT32(MF_MT_AUDIO_NUM_CHANNELS, channels);
+    type->SetUINT32(MF_MT_AUDIO_SAMPLES_PER_SECOND, sampleRate);
+    type->SetUINT32(MF_MT_AUDIO_BITS_PER_SAMPLE, bitsPerSample);
+}
+
+void compositeWebcam(BYTE* destination, int width, int height, const BgraFrameView& webcamFrame) {
+    if (!webcamFrame.data || webcamFrame.width <= 0 || webcamFrame.height <= 0 || width <= 0 || height <= 0) {
+        return;
+    }
+
+    const int margin = std::max(16, std::min(width, height) / 60);
+    const int maxOverlayWidth = std::max(2, width / 4);
+    int overlayWidth = maxOverlayWidth;
+    int overlayHeight = static_cast<int>(
+        (static_cast<int64_t>(overlayWidth) * webcamFrame.height) / std::max(1, webcamFrame.width));
+    const int maxOverlayHeight = std::max(2, height / 3);
+    if (overlayHeight > maxOverlayHeight) {
+        overlayHeight = maxOverlayHeight;
+        overlayWidth = static_cast<int>(
+            (static_cast<int64_t>(overlayHeight) * webcamFrame.width) / std::max(1, webcamFrame.height));
+    }
+
+    overlayWidth = std::max(2, std::min(overlayWidth, width - margin * 2));
+    overlayHeight = std::max(2, std::min(overlayHeight, height - margin * 2));
+    const int originX = std::max(0, width - overlayWidth - margin);
+    const int originY = std::max(0, height - overlayHeight - margin);
+
+    for (int y = 0; y < overlayHeight; y += 1) {
+        const int sourceY = static_cast<int>((static_cast<int64_t>(y) * webcamFrame.height) / overlayHeight);
+        BYTE* destinationRow = destination + ((originY + y) * width + originX) * 4;
+        for (int x = 0; x < overlayWidth; x += 1) {
+            const int sourceX = static_cast<int>((static_cast<int64_t>(x) * webcamFrame.width) / overlayWidth);
+            const BYTE* source = webcamFrame.data + (sourceY * webcamFrame.width + sourceX) * 4;
+            BYTE* target = destinationRow + x * 4;
+            target[0] = source[0];
+            target[1] = source[1];
+            target[2] = source[2];
+            target[3] = 255;
+        }
+    }
+}
+
+} // namespace
+
+MFEncoder::~MFEncoder() {
+    finalize();
+}
+
+bool MFEncoder::initialize(
+    const std::wstring& outputPath,
+    int width,
+    int height,
+    int fps,
+    int bitrate,
+    ID3D11Device* device,
+    ID3D11DeviceContext* context,
+    const AudioInputFormat* audioFormat) {
+    width_ = (std::max(2, width) / 2) * 2;
+    height_ = (std::max(2, height) / 2) * 2;
+    fps_ = std::max(1, fps);
+    device_ = device;
+    context_ = context;
+
+    if (!succeeded(MFStartup(MF_VERSION), "MFStartup")) {
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IMFMediaType> outputType;
+    if (!succeeded(MFCreateMediaType(&outputType), "MFCreateMediaType(output)")) {
+        return false;
+    }
+    outputType->SetGUID(MF_MT_MAJOR_TYPE, MFMediaType_Video);
+    outputType->SetGUID(MF_MT_SUBTYPE, MFVideoFormat_H264);
+    outputType->SetUINT32(MF_MT_AVG_BITRATE, static_cast<UINT32>(std::max(1, bitrate)));
+    outputType->SetUINT32(MF_MT_INTERLACE_MODE, MFVideoInterlace_Progressive);
+    setFrameSize(outputType.Get(), static_cast<UINT32>(width_), static_cast<UINT32>(height_));
+    setFrameRate(outputType.Get(), static_cast<UINT32>(fps_));
+    setPixelAspectRatio(outputType.Get());
+
+    if (!succeeded(MFCreateSinkWriterFromURL(outputPath.c_str(), nullptr, nullptr, &sinkWriter_),
+                   "MFCreateSinkWriterFromURL")) {
+        return false;
+    }
+    if (!succeeded(sinkWriter_->AddStream(outputType.Get(), &videoStreamIndex_), "AddStream")) {
+        return false;
+    }
+
+    if (audioFormat && !configureAudioStream(*audioFormat)) {
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IMFMediaType> inputType;
+    if (!succeeded(MFCreateMediaType(&inputType), "MFCreateMediaType(input)")) {
+        return false;
+    }
+    inputType->SetGUID(MF_MT_MAJOR_TYPE, MFMediaType_Video);
+    inputType->SetGUID(MF_MT_SUBTYPE, MFVideoFormat_RGB32);
+    inputType->SetUINT32(MF_MT_INTERLACE_MODE, MFVideoInterlace_Progressive);
+    inputType->SetUINT32(MF_MT_DEFAULT_STRIDE, static_cast<UINT32>(width_ * 4));
+    setFrameSize(inputType.Get(), static_cast<UINT32>(width_), static_cast<UINT32>(height_));
+    setFrameRate(inputType.Get(), static_cast<UINT32>(fps_));
+    setPixelAspectRatio(inputType.Get());
+
+    if (!succeeded(sinkWriter_->SetInputMediaType(videoStreamIndex_, inputType.Get(), nullptr),
+                   "SetInputMediaType")) {
+        return false;
+    }
+    if (!succeeded(sinkWriter_->BeginWriting(), "BeginWriting")) {
+        return false;
+    }
+
+    return true;
+}
+
+bool MFEncoder::configureAudioStream(const AudioInputFormat& audioFormat) {
+    if (!sinkWriter_) {
+        return false;
+    }
+    if (audioFormat.sampleRate == 0 || audioFormat.channels == 0 || audioFormat.blockAlign == 0) {
+        std::cerr << "ERROR: Invalid audio input format" << std::endl;
+        return false;
+    }
+
+    const AudioInputFormat encoderFormat = makeAacCompatibleAudioFormat(audioFormat);
+    const UINT32 aacBytesPerSecond = 24'000;
+
+    Microsoft::WRL::ComPtr<IMFMediaType> outputType;
+    if (!succeeded(MFCreateMediaType(&outputType), "MFCreateMediaType(audio output)")) {
+        return false;
+    }
+    outputType->SetGUID(MF_MT_MAJOR_TYPE, MFMediaType_Audio);
+    outputType->SetGUID(MF_MT_SUBTYPE, MFAudioFormat_AAC);
+    setAudioFormat(outputType.Get(), encoderFormat.channels, encoderFormat.sampleRate, 16);
+    outputType->SetUINT32(MF_MT_AUDIO_AVG_BYTES_PER_SECOND, aacBytesPerSecond);
+    outputType->SetUINT32(MF_MT_AAC_PAYLOAD_TYPE, 0);
+
+    if (!succeeded(sinkWriter_->AddStream(outputType.Get(), &audioStreamIndex_), "AddStream(audio)")) {
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IMFMediaType> inputType;
+    if (!succeeded(MFCreateMediaType(&inputType), "MFCreateMediaType(audio input)")) {
+        return false;
+    }
+    inputType->SetGUID(MF_MT_MAJOR_TYPE, MFMediaType_Audio);
+    inputType->SetGUID(MF_MT_SUBTYPE, encoderFormat.subtype);
+    setAudioFormat(inputType.Get(), encoderFormat.channels, encoderFormat.sampleRate, encoderFormat.bitsPerSample);
+    inputType->SetUINT32(MF_MT_AUDIO_BLOCK_ALIGNMENT, encoderFormat.blockAlign);
+    inputType->SetUINT32(MF_MT_AUDIO_AVG_BYTES_PER_SECOND, encoderFormat.avgBytesPerSec);
+    inputType->SetUINT32(MF_MT_ALL_SAMPLES_INDEPENDENT, TRUE);
+
+    if (!succeeded(sinkWriter_->SetInputMediaType(audioStreamIndex_, inputType.Get(), nullptr),
+                   "SetInputMediaType(audio)")) {
+        return false;
+    }
+
+    hasAudioStream_ = true;
+    return true;
+}
+
+bool MFEncoder::ensureStagingTexture(ID3D11Texture2D* texture) {
+    if (stagingTexture_) {
+        return true;
+    }
+
+    D3D11_TEXTURE2D_DESC desc{};
+    texture->GetDesc(&desc);
+    desc.Width = static_cast<UINT>(width_);
+    desc.Height = static_cast<UINT>(height_);
+    desc.MipLevels = 1;
+    desc.ArraySize = 1;
+    desc.Format = DXGI_FORMAT_B8G8R8A8_UNORM;
+    desc.SampleDesc.Count = 1;
+    desc.SampleDesc.Quality = 0;
+    desc.Usage = D3D11_USAGE_STAGING;
+    desc.BindFlags = 0;
+    desc.CPUAccessFlags = D3D11_CPU_ACCESS_READ;
+    desc.MiscFlags = 0;
+
+    return succeeded(device_->CreateTexture2D(&desc, nullptr, &stagingTexture_),
+                     "CreateTexture2D(staging)");
+}
+
+bool MFEncoder::copyFrameToBuffer(
+    ID3D11Texture2D* texture,
+    BYTE* destination,
+    DWORD destinationSize,
+    const BgraFrameView* webcamFrame) {
+    if (!ensureStagingTexture(texture)) {
+        return false;
+    }
+
+    context_->CopyResource(stagingTexture_.Get(), texture);
+
+    D3D11_MAPPED_SUBRESOURCE mapped{};
+    if (!succeeded(context_->Map(stagingTexture_.Get(), 0, D3D11_MAP_READ, 0, &mapped), "Map")) {
+        return false;
+    }
+
+    const DWORD rowBytes = static_cast<DWORD>(width_ * 4);
+    const DWORD requiredBytes = rowBytes * static_cast<DWORD>(height_);
+    if (destinationSize < requiredBytes) {
+        context_->Unmap(stagingTexture_.Get(), 0);
+        std::cerr << "ERROR: Media Foundation buffer is too small" << std::endl;
+        return false;
+    }
+
+    auto* source = static_cast<const BYTE*>(mapped.pData);
+    for (int y = 0; y < height_; y += 1) {
+        std::memcpy(destination + rowBytes * y, source + mapped.RowPitch * y, rowBytes);
+    }
+    if (webcamFrame) {
+        compositeWebcam(destination, width_, height_, *webcamFrame);
+    }
+
+    context_->Unmap(stagingTexture_.Get(), 0);
+    return true;
+}
+
+bool MFEncoder::copyBgraFrameToBuffer(const BgraFrameView& frame, BYTE* destination, DWORD destinationSize) {
+    if (!frame.data || frame.width <= 0 || frame.height <= 0) {
+        return false;
+    }
+
+    const DWORD rowBytes = static_cast<DWORD>(width_ * 4);
+    const DWORD requiredBytes = rowBytes * static_cast<DWORD>(height_);
+    if (destinationSize < requiredBytes) {
+        std::cerr << "ERROR: Media Foundation webcam buffer is too small" << std::endl;
+        return false;
+    }
+
+    if (frame.width == width_ && frame.height == height_) {
+        for (DWORD i = 0; i < requiredBytes; i += 4) {
+            destination[i] = frame.data[i];
+            destination[i + 1] = frame.data[i + 1];
+            destination[i + 2] = frame.data[i + 2];
+            destination[i + 3] = 255;
+        }
+        return true;
+    }
+
+    for (int y = 0; y < height_; y += 1) {
+        const int sourceY = static_cast<int>((static_cast<int64_t>(y) * frame.height) / height_);
+        BYTE* destinationRow = destination + rowBytes * y;
+        for (int x = 0; x < width_; x += 1) {
+            const int sourceX = static_cast<int>((static_cast<int64_t>(x) * frame.width) / width_);
+            const BYTE* source = frame.data + (sourceY * frame.width + sourceX) * 4;
+            BYTE* target = destinationRow + x * 4;
+            target[0] = source[0];
+            target[1] = source[1];
+            target[2] = source[2];
+            target[3] = 255;
+        }
+    }
+
+    return true;
+}
+
+bool MFEncoder::writeFrame(ID3D11Texture2D* texture, int64_t timestampHns, const BgraFrameView* webcamFrame) {
+    std::scoped_lock writerLock(writerMutex_);
+    if (!sinkWriter_ || finalized_) {
+        return false;
+    }
+
+    if (firstTimestampHns_ < 0) {
+        firstTimestampHns_ = timestampHns;
+    }
+
+    int64_t sampleTime = timestampHns - firstTimestampHns_;
+    if (sampleTime <= lastTimestampHns_) {
+        sampleTime = lastTimestampHns_ + (10'000'000LL / fps_);
+    }
+    const int64_t sampleDuration = 10'000'000LL / fps_;
+    lastTimestampHns_ = sampleTime;
+
+    Microsoft::WRL::ComPtr<IMFMediaBuffer> buffer;
+    const DWORD frameBytes = static_cast<DWORD>(width_ * height_ * 4);
+    if (!succeeded(MFCreateMemoryBuffer(frameBytes, &buffer), "MFCreateMemoryBuffer")) {
+        return false;
+    }
+
+    BYTE* data = nullptr;
+    DWORD maxLength = 0;
+    DWORD currentLength = 0;
+    if (!succeeded(buffer->Lock(&data, &maxLength, &currentLength), "IMFMediaBuffer::Lock")) {
+        return false;
+    }
+
+    const bool copied = copyFrameToBuffer(texture, data, maxLength, webcamFrame);
+    buffer->Unlock();
+    if (!copied) {
+        return false;
+    }
+    buffer->SetCurrentLength(frameBytes);
+
+    Microsoft::WRL::ComPtr<IMFSample> sample;
+    if (!succeeded(MFCreateSample(&sample), "MFCreateSample")) {
+        return false;
+    }
+    sample->AddBuffer(buffer.Get());
+    sample->SetSampleTime(sampleTime);
+    sample->SetSampleDuration(sampleDuration);
+
+    return succeeded(sinkWriter_->WriteSample(videoStreamIndex_, sample.Get()), "WriteSample");
+}
+
+bool MFEncoder::writeBgraFrame(const BgraFrameView& frame, int64_t timestampHns) {
+    std::scoped_lock writerLock(writerMutex_);
+    if (!sinkWriter_ || finalized_) {
+        return false;
+    }
+
+    if (firstTimestampHns_ < 0) {
+        firstTimestampHns_ = timestampHns;
+    }
+
+    int64_t sampleTime = timestampHns - firstTimestampHns_;
+    if (sampleTime <= lastTimestampHns_) {
+        sampleTime = lastTimestampHns_ + (10'000'000LL / fps_);
+    }
+    const int64_t sampleDuration = 10'000'000LL / fps_;
+    lastTimestampHns_ = sampleTime;
+
+    Microsoft::WRL::ComPtr<IMFMediaBuffer> buffer;
+    const DWORD frameBytes = static_cast<DWORD>(width_ * height_ * 4);
+    if (!succeeded(MFCreateMemoryBuffer(frameBytes, &buffer), "MFCreateMemoryBuffer(webcam)")) {
+        return false;
+    }
+
+    BYTE* data = nullptr;
+    DWORD maxLength = 0;
+    DWORD currentLength = 0;
+    if (!succeeded(buffer->Lock(&data, &maxLength, &currentLength), "IMFMediaBuffer::Lock(webcam)")) {
+        return false;
+    }
+
+    const bool copied = copyBgraFrameToBuffer(frame, data, maxLength);
+    buffer->Unlock();
+    if (!copied) {
+        return false;
+    }
+    buffer->SetCurrentLength(frameBytes);
+
+    Microsoft::WRL::ComPtr<IMFSample> sample;
+    if (!succeeded(MFCreateSample(&sample), "MFCreateSample(webcam)")) {
+        return false;
+    }
+    sample->AddBuffer(buffer.Get());
+    sample->SetSampleTime(sampleTime);
+    sample->SetSampleDuration(sampleDuration);
+
+    return succeeded(sinkWriter_->WriteSample(videoStreamIndex_, sample.Get()), "WriteSample(webcam)");
+}
+
+bool MFEncoder::writeAudio(const BYTE* data, DWORD byteCount, int64_t timestampHns, int64_t durationHns) {
+    std::scoped_lock writerLock(writerMutex_);
+    if (!sinkWriter_ || finalized_ || !hasAudioStream_) {
+        return false;
+    }
+    if (!data || byteCount == 0 || durationHns <= 0) {
+        return true;
+    }
+
+    Microsoft::WRL::ComPtr<IMFMediaBuffer> buffer;
+    if (!succeeded(MFCreateMemoryBuffer(byteCount, &buffer), "MFCreateMemoryBuffer(audio)")) {
+        return false;
+    }
+
+    BYTE* destination = nullptr;
+    DWORD maxLength = 0;
+    DWORD currentLength = 0;
+    if (!succeeded(buffer->Lock(&destination, &maxLength, &currentLength),
+                   "IMFMediaBuffer::Lock(audio)")) {
+        return false;
+    }
+    if (maxLength < byteCount) {
+        buffer->Unlock();
+        std::cerr << "ERROR: Media Foundation audio buffer is too small" << std::endl;
+        return false;
+    }
+    std::memcpy(destination, data, byteCount);
+    buffer->Unlock();
+    buffer->SetCurrentLength(byteCount);
+
+    Microsoft::WRL::ComPtr<IMFSample> sample;
+    if (!succeeded(MFCreateSample(&sample), "MFCreateSample(audio)")) {
+        return false;
+    }
+    sample->AddBuffer(buffer.Get());
+    sample->SetSampleTime(std::max<int64_t>(0, timestampHns));
+    sample->SetSampleDuration(durationHns);
+
+    return succeeded(sinkWriter_->WriteSample(audioStreamIndex_, sample.Get()), "WriteSample(audio)");
+}
+
+bool MFEncoder::finalize() {
+    std::scoped_lock writerLock(writerMutex_);
+    if (finalized_) {
+        return true;
+    }
+
+    finalized_ = true;
+    bool ok = true;
+    if (sinkWriter_) {
+        ok = succeeded(sinkWriter_->Finalize(), "SinkWriter::Finalize");
+        sinkWriter_.Reset();
+    }
+    stagingTexture_.Reset();
+    context_.Reset();
+    device_.Reset();
+    MFShutdown();
+    return ok;
+}

electron/native/wgc-capture/src/mf_encoder.h

@@ -0,0 +1,75 @@
+#pragma once
+
+#include <Windows.h>
+#include <d3d11.h>
+#include <mfapi.h>
+#include <mfidl.h>
+#include <mfreadwrite.h>
+#include <wrl/client.h>
+
+#include <cstdint>
+#include <mutex>
+#include <string>
+
+struct BgraFrameView {
+    const BYTE* data = nullptr;
+    int width = 0;
+    int height = 0;
+};
+
+struct AudioInputFormat {
+    GUID subtype = MFAudioFormat_PCM;
+    UINT32 sampleRate = 0;
+    UINT32 channels = 0;
+    UINT32 bitsPerSample = 0;
+    UINT32 blockAlign = 0;
+    UINT32 avgBytesPerSec = 0;
+};
+
+class MFEncoder {
+public:
+    MFEncoder() = default;
+    ~MFEncoder();
+
+    MFEncoder(const MFEncoder&) = delete;
+    MFEncoder& operator=(const MFEncoder&) = delete;
+
+    bool initialize(
+        const std::wstring& outputPath,
+        int width,
+        int height,
+        int fps,
+        int bitrate,
+        ID3D11Device* device,
+        ID3D11DeviceContext* context,
+        const AudioInputFormat* audioFormat = nullptr);
+    bool writeFrame(ID3D11Texture2D* texture, int64_t timestampHns, const BgraFrameView* webcamFrame = nullptr);
+    bool writeBgraFrame(const BgraFrameView& frame, int64_t timestampHns);
+    bool writeAudio(const BYTE* data, DWORD byteCount, int64_t timestampHns, int64_t durationHns);
+    bool finalize();
+
+private:
+    bool ensureStagingTexture(ID3D11Texture2D* texture);
+    bool copyFrameToBuffer(
+        ID3D11Texture2D* texture,
+        BYTE* destination,
+        DWORD destinationSize,
+        const BgraFrameView* webcamFrame);
+    bool copyBgraFrameToBuffer(const BgraFrameView& frame, BYTE* destination, DWORD destinationSize);
+    bool configureAudioStream(const AudioInputFormat& audioFormat);
+
+    Microsoft::WRL::ComPtr<IMFSinkWriter> sinkWriter_;
+    Microsoft::WRL::ComPtr<ID3D11Device> device_;
+    Microsoft::WRL::ComPtr<ID3D11DeviceContext> context_;
+    Microsoft::WRL::ComPtr<ID3D11Texture2D> stagingTexture_;
+    std::mutex writerMutex_;
+    DWORD videoStreamIndex_ = 0;
+    DWORD audioStreamIndex_ = 0;
+    bool hasAudioStream_ = false;
+    int width_ = 0;
+    int height_ = 0;
+    int fps_ = 60;
+    int64_t firstTimestampHns_ = -1;
+    int64_t lastTimestampHns_ = -1;
+    bool finalized_ = false;
+};

electron/native/wgc-capture/src/monitor_utils.cpp

@@ -0,0 +1,88 @@
+#include "monitor_utils.h"
+
+#include <algorithm>
+#include <cmath>
+#include <vector>
+
+namespace {
+
+struct MonitorCandidate {
+    HMONITOR monitor = nullptr;
+    RECT rect{};
+};
+
+std::vector<MonitorCandidate> enumerateMonitors() {
+    std::vector<MonitorCandidate> monitors;
+    EnumDisplayMonitors(
+        nullptr,
+        nullptr,
+        [](HMONITOR monitor, HDC, LPRECT rect, LPARAM userData) -> BOOL {
+            auto* result = reinterpret_cast<std::vector<MonitorCandidate>*>(userData);
+            result->push_back({monitor, *rect});
+            return TRUE;
+        },
+        reinterpret_cast<LPARAM>(&monitors));
+    return monitors;
+}
+
+bool rectMatchesBounds(const RECT& rect, const MonitorBounds& bounds) {
+    return rect.left == bounds.x &&
+           rect.top == bounds.y &&
+           (rect.right - rect.left) == bounds.width &&
+           (rect.bottom - rect.top) == bounds.height;
+}
+
+int64_t overlapArea(const RECT& rect, const MonitorBounds& bounds) {
+    const LONG left = std::max<LONG>(rect.left, bounds.x);
+    const LONG top = std::max<LONG>(rect.top, bounds.y);
+    const LONG right = std::min<LONG>(rect.right, bounds.x + bounds.width);
+    const LONG bottom = std::min<LONG>(rect.bottom, bounds.y + bounds.height);
+    if (right <= left || bottom <= top) {
+        return 0;
+    }
+    return static_cast<int64_t>(right - left) * static_cast<int64_t>(bottom - top);
+}
+
+} // namespace
+
+HMONITOR findMonitorForCapture(int64_t displayId, const MonitorBounds* bounds) {
+    const auto monitors = enumerateMonitors();
+    if (monitors.empty()) {
+        return MonitorFromPoint({0, 0}, MONITOR_DEFAULTTOPRIMARY);
+    }
+
+    // Electron's display_id is not stable across all Windows capture backends.
+    // Bounds are the most reliable contract because they come from Electron's
+    // selected display and match the WGC monitor coordinate space.
+    if (bounds && bounds->width > 0 && bounds->height > 0) {
+        for (const auto& candidate : monitors) {
+            if (rectMatchesBounds(candidate.rect, *bounds)) {
+                return candidate.monitor;
+            }
+        }
+
+        HMONITOR bestMonitor = nullptr;
+        int64_t bestArea = 0;
+        for (const auto& candidate : monitors) {
+            const int64_t area = overlapArea(candidate.rect, *bounds);
+            if (area > bestArea) {
+                bestArea = area;
+                bestMonitor = candidate.monitor;
+            }
+        }
+        if (bestMonitor) {
+            return bestMonitor;
+        }
+    }
+
+    // Best-effort fallback for helpers invoked without bounds. Some callers pass
+    // zero-based ids while Win32 monitor handles are pointer values, so only use
+    // this when it exactly matches the HMONITOR value.
+    for (const auto& candidate : monitors) {
+        if (reinterpret_cast<int64_t>(candidate.monitor) == displayId) {
+            return candidate.monitor;
+        }
+    }
+
+    return MonitorFromPoint({0, 0}, MONITOR_DEFAULTTOPRIMARY);
+}

electron/native/wgc-capture/src/monitor_utils.h

@@ -0,0 +1,14 @@
+#pragma once
+
+#include <Windows.h>
+
+#include <cstdint>
+
+struct MonitorBounds {
+    int x = 0;
+    int y = 0;
+    int width = 0;
+    int height = 0;
+};
+
+HMONITOR findMonitorForCapture(int64_t displayId, const MonitorBounds* bounds);

electron/native/wgc-capture/src/wasapi_loopback_capture.cpp

@@ -0,0 +1,411 @@
+#include "wasapi_loopback_capture.h"
+
+#include <Functiondiscoverykeys_devpkey.h>
+#include <ksmedia.h>
+#include <propvarutil.h>
+
+#include <algorithm>
+#include <chrono>
+#include <cwctype>
+#include <iostream>
+
+namespace {
+
+constexpr REFERENCE_TIME BufferDurationHns = 10'000'000;
+constexpr int64_t HnsPerSecond = 10'000'000;
+
+bool succeeded(HRESULT hr, const char* label) {
+    if (SUCCEEDED(hr)) {
+        return true;
+    }
+
+    std::cerr << "ERROR: " << label << " failed (hr=0x" << std::hex << hr << std::dec << ")"
+              << std::endl;
+    return false;
+}
+
+GUID audioSubtypeFromFormat(WAVEFORMATEX* format) {
+    if (format->wFormatTag == WAVE_FORMAT_IEEE_FLOAT) {
+        return MFAudioFormat_Float;
+    }
+    if (format->wFormatTag == WAVE_FORMAT_PCM) {
+        return MFAudioFormat_PCM;
+    }
+    if (format->wFormatTag == WAVE_FORMAT_EXTENSIBLE &&
+        format->cbSize >= sizeof(WAVEFORMATEXTENSIBLE) - sizeof(WAVEFORMATEX)) {
+        auto* extensible = reinterpret_cast<WAVEFORMATEXTENSIBLE*>(format);
+        if (extensible->SubFormat == KSDATAFORMAT_SUBTYPE_IEEE_FLOAT) {
+            return MFAudioFormat_Float;
+        }
+        if (extensible->SubFormat == KSDATAFORMAT_SUBTYPE_PCM) {
+            return MFAudioFormat_PCM;
+        }
+    }
+    return GUID_NULL;
+}
+
+std::wstring normalizeDeviceName(const std::wstring& value) {
+    std::wstring result;
+    result.reserve(value.size());
+    bool lastWasSpace = true;
+
+    for (const wchar_t c : value) {
+        if (std::iswalnum(c)) {
+            result.push_back(static_cast<wchar_t>(std::towlower(c)));
+            lastWasSpace = false;
+        } else if (!lastWasSpace) {
+            result.push_back(L' ');
+            lastWasSpace = true;
+        }
+    }
+
+    if (!result.empty() && result.back() == L' ') {
+        result.pop_back();
+    }
+    return result;
+}
+
+int scoreDeviceName(const std::wstring& candidateName, const std::wstring& candidateId, const std::wstring& requestedName) {
+    const std::wstring candidate = normalizeDeviceName(candidateName);
+    const std::wstring id = normalizeDeviceName(candidateId);
+    const std::wstring requested = normalizeDeviceName(requestedName);
+    if (requested.empty()) {
+        return 0;
+    }
+    if (candidate == requested) {
+        return 1000;
+    }
+    if (!candidate.empty() && (candidate.find(requested) != std::wstring::npos || requested.find(candidate) != std::wstring::npos)) {
+        return 900;
+    }
+    if (!id.empty() && (id.find(requested) != std::wstring::npos || requested.find(id) != std::wstring::npos)) {
+        return 800;
+    }
+
+    int score = 0;
+    size_t pos = 0;
+    while (pos < requested.size()) {
+        const size_t end = requested.find(L' ', pos);
+        const std::wstring word = requested.substr(pos, end == std::wstring::npos ? std::wstring::npos : end - pos);
+        if (word.size() > 1 && word != L"microphone" && word != L"mic" && word != L"audio" && word != L"input") {
+            if (candidate.find(word) != std::wstring::npos) {
+                score += 100;
+            } else if (id.find(word) != std::wstring::npos) {
+                score += 50;
+            }
+        }
+        if (end == std::wstring::npos) {
+            break;
+        }
+        pos = end + 1;
+    }
+    return score;
+}
+
+std::wstring getDeviceFriendlyName(IMMDevice* device) {
+    if (!device) {
+        return {};
+    }
+
+    Microsoft::WRL::ComPtr<IPropertyStore> properties;
+    HRESULT hr = device->OpenPropertyStore(STGM_READ, &properties);
+    if (FAILED(hr) || !properties) {
+        return {};
+    }
+
+    PROPVARIANT value;
+    PropVariantInit(&value);
+    hr = properties->GetValue(PKEY_Device_FriendlyName, &value);
+    std::wstring name;
+    if (SUCCEEDED(hr) && value.vt == VT_LPWSTR && value.pwszVal) {
+        name = value.pwszVal;
+    }
+    PropVariantClear(&value);
+    return name;
+}
+
+} // namespace
+
+WasapiLoopbackCapture::~WasapiLoopbackCapture() {
+    stop();
+    if (mixFormat_) {
+        CoTaskMemFree(mixFormat_);
+        mixFormat_ = nullptr;
+    }
+}
+
+bool WasapiLoopbackCapture::initializeSystemLoopback() {
+    return initialize(WasapiCaptureEndpoint::SystemLoopback, {}, {});
+}
+
+bool WasapiLoopbackCapture::initializeMicrophone(const std::wstring& deviceId, const std::wstring& deviceName) {
+    return initialize(WasapiCaptureEndpoint::Microphone, deviceId, deviceName);
+}
+
+bool WasapiLoopbackCapture::initialize(WasapiCaptureEndpoint endpoint, const std::wstring& deviceId, const std::wstring& deviceName) {
+    HRESULT hr = CoCreateInstance(
+        __uuidof(MMDeviceEnumerator),
+        nullptr,
+        CLSCTX_ALL,
+        IID_PPV_ARGS(&deviceEnumerator_));
+    if (!succeeded(hr, "CoCreateInstance(MMDeviceEnumerator)")) {
+        return false;
+    }
+
+    if (endpoint == WasapiCaptureEndpoint::Microphone && !deviceId.empty() && deviceId != L"default") {
+        hr = deviceEnumerator_->GetDevice(deviceId.c_str(), &device_);
+        if (FAILED(hr)) {
+            std::wcerr << L"WARNING: Could not resolve microphone device id directly"
+                       << std::endl;
+            device_.Reset();
+        }
+    }
+
+    if (endpoint == WasapiCaptureEndpoint::Microphone && !device_ && !deviceName.empty()) {
+        if (!resolveMicrophoneByName(deviceName)) {
+            std::wcerr << L"WARNING: Could not resolve microphone by name; using default capture endpoint"
+                       << std::endl;
+        }
+    }
+
+    if (!device_) {
+        const EDataFlow flow =
+            endpoint == WasapiCaptureEndpoint::SystemLoopback ? eRender : eCapture;
+        hr = deviceEnumerator_->GetDefaultAudioEndpoint(flow, eConsole, &device_);
+        if (!succeeded(hr, "GetDefaultAudioEndpoint")) {
+            return false;
+        }
+    }
+
+    selectedDeviceName_ = getDeviceFriendlyName(device_.Get());
+
+    hr = device_->Activate(__uuidof(IAudioClient), CLSCTX_ALL, nullptr, &audioClient_);
+    if (!succeeded(hr, "IMMDevice::Activate(IAudioClient)")) {
+        return false;
+    }
+
+    hr = audioClient_->GetMixFormat(&mixFormat_);
+    if (!succeeded(hr, "IAudioClient::GetMixFormat") || !mixFormat_) {
+        return false;
+    }
+
+    if (!resolveInputFormat(mixFormat_)) {
+        std::cerr << "ERROR: Unsupported WASAPI loopback mix format" << std::endl;
+        return false;
+    }
+
+    const DWORD streamFlags =
+        endpoint == WasapiCaptureEndpoint::SystemLoopback ? AUDCLNT_STREAMFLAGS_LOOPBACK : 0;
+    hr = audioClient_->Initialize(
+        AUDCLNT_SHAREMODE_SHARED,
+        streamFlags,
+        BufferDurationHns,
+        0,
+        mixFormat_,
+        nullptr);
+    if (!succeeded(hr, "IAudioClient::Initialize(loopback)")) {
+        return false;
+    }
+
+    hr = audioClient_->GetService(IID_PPV_ARGS(&captureClient_));
+    if (!succeeded(hr, "IAudioClient::GetService(IAudioCaptureClient)")) {
+        return false;
+    }
+
+    return true;
+}
+
+bool WasapiLoopbackCapture::resolveMicrophoneByName(const std::wstring& deviceName) {
+    if (!deviceEnumerator_ || deviceName.empty()) {
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IMMDeviceCollection> devices;
+    HRESULT hr = deviceEnumerator_->EnumAudioEndpoints(eCapture, DEVICE_STATE_ACTIVE, &devices);
+    if (!succeeded(hr, "IMMDeviceEnumerator::EnumAudioEndpoints(eCapture)")) {
+        return false;
+    }
+
+    UINT count = 0;
+    hr = devices->GetCount(&count);
+    if (!succeeded(hr, "IMMDeviceCollection::GetCount")) {
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IMMDevice> bestDevice;
+    std::wstring bestId;
+    std::wstring bestName;
+    int bestScore = 0;
+    for (UINT i = 0; i < count; ++i) {
+        Microsoft::WRL::ComPtr<IMMDevice> candidate;
+        hr = devices->Item(i, &candidate);
+        if (FAILED(hr) || !candidate) {
+            continue;
+        }
+
+        LPWSTR rawId = nullptr;
+        std::wstring candidateId;
+        if (SUCCEEDED(candidate->GetId(&rawId)) && rawId) {
+            candidateId = rawId;
+            CoTaskMemFree(rawId);
+        }
+
+        const std::wstring candidateName = getDeviceFriendlyName(candidate.Get());
+        const int score = scoreDeviceName(candidateName, candidateId, deviceName);
+        std::wcerr << L"Native microphone candidate: " << candidateName << L" score=" << score << std::endl;
+        if (score > bestScore) {
+            bestScore = score;
+            bestDevice = candidate;
+            bestId = candidateId;
+            bestName = candidateName;
+        }
+    }
+
+    if (!bestDevice || bestScore <= 0) {
+        return false;
+    }
+
+    device_ = bestDevice;
+    std::wcerr << L"Selected native microphone endpoint: " << bestName << L" id=" << bestId << std::endl;
+    return true;
+}
+
+bool WasapiLoopbackCapture::resolveInputFormat(WAVEFORMATEX* mixFormat) {
+    const GUID subtype = audioSubtypeFromFormat(mixFormat);
+    if (subtype == GUID_NULL) {
+        return false;
+    }
+
+    inputFormat_.subtype = subtype;
+    inputFormat_.sampleRate = mixFormat->nSamplesPerSec;
+    inputFormat_.channels = mixFormat->nChannels;
+    inputFormat_.bitsPerSample = mixFormat->wBitsPerSample;
+    inputFormat_.blockAlign = mixFormat->nBlockAlign;
+    inputFormat_.avgBytesPerSec = mixFormat->nAvgBytesPerSec;
+    return inputFormat_.sampleRate > 0 && inputFormat_.channels > 0 && inputFormat_.blockAlign > 0;
+}
+
+bool WasapiLoopbackCapture::start(AudioCallback callback) {
+    if (!audioClient_ || !captureClient_ || !callback) {
+        return false;
+    }
+
+    callback_ = std::move(callback);
+    stopRequested_ = false;
+    writtenFrames_ = 0;
+    lastDevicePositionEnd_ = 0;
+    hasLastDevicePosition_ = false;
+
+    HRESULT hr = audioClient_->Start();
+    if (!succeeded(hr, "IAudioClient::Start")) {
+        return false;
+    }
+
+    thread_ = std::thread([this] {
+        captureLoop();
+    });
+    return true;
+}
+
+void WasapiLoopbackCapture::stop() {
+    stopRequested_ = true;
+    if (thread_.joinable()) {
+        thread_.join();
+    }
+    if (audioClient_) {
+        audioClient_->Stop();
+    }
+}
+
+const AudioInputFormat& WasapiLoopbackCapture::inputFormat() const {
+    return inputFormat_;
+}
+
+const std::wstring& WasapiLoopbackCapture::selectedDeviceName() const {
+    return selectedDeviceName_;
+}
+
+void WasapiLoopbackCapture::captureLoop() {
+    auto emitSilenceFrames = [&](uint64_t frames, int64_t timestampHns) {
+        constexpr uint64_t MaxSilenceChunkFrames = 4800;
+        uint64_t remainingFrames = frames;
+        int64_t currentTimestampHns = timestampHns;
+        while (remainingFrames > 0 && !stopRequested_) {
+            const uint64_t chunkFrames = std::min<uint64_t>(remainingFrames, MaxSilenceChunkFrames);
+            const DWORD chunkBytes = static_cast<DWORD>(chunkFrames * inputFormat_.blockAlign);
+            const int64_t chunkDurationHns =
+                static_cast<int64_t>((chunkFrames * HnsPerSecond) / inputFormat_.sampleRate);
+            silenceBuffer_.assign(chunkBytes, 0);
+            callback_(silenceBuffer_.data(), chunkBytes, currentTimestampHns, chunkDurationHns);
+            remainingFrames -= chunkFrames;
+            currentTimestampHns += chunkDurationHns;
+        }
+    };
+
+    while (!stopRequested_) {
+        UINT32 packetFrames = 0;
+        HRESULT hr = captureClient_->GetNextPacketSize(&packetFrames);
+        if (FAILED(hr)) {
+            std::cerr << "ERROR: IAudioCaptureClient::GetNextPacketSize failed (hr=0x" << std::hex
+                      << hr << std::dec << ")" << std::endl;
+            break;
+        }
+
+        while (packetFrames > 0 && !stopRequested_) {
+            BYTE* data = nullptr;
+            UINT32 framesAvailable = 0;
+            DWORD flags = 0;
+            UINT64 devicePosition = 0;
+            UINT64 qpcPosition = 0;
+
+            hr = captureClient_->GetBuffer(&data, &framesAvailable, &flags, &devicePosition, &qpcPosition);
+            if (FAILED(hr)) {
+                std::cerr << "ERROR: IAudioCaptureClient::GetBuffer failed (hr=0x" << std::hex
+                          << hr << std::dec << ")" << std::endl;
+                break;
+            }
+
+            (void)qpcPosition;
+            if (hasLastDevicePosition_ && devicePosition > lastDevicePositionEnd_) {
+                const uint64_t gapFrames = devicePosition - lastDevicePositionEnd_;
+                if ((flags & AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY) != 0 || gapFrames > framesAvailable) {
+                    const int64_t gapTimestampHns =
+                        static_cast<int64_t>((lastDevicePositionEnd_ * HnsPerSecond) / inputFormat_.sampleRate);
+                    emitSilenceFrames(gapFrames, gapTimestampHns);
+                }
+            }
+
+            const DWORD byteCount = framesAvailable * inputFormat_.blockAlign;
+            const int64_t timestampHns =
+                static_cast<int64_t>((devicePosition * HnsPerSecond) / inputFormat_.sampleRate);
+            const int64_t durationHns =
+                static_cast<int64_t>((static_cast<uint64_t>(framesAvailable) * HnsPerSecond) /
+                                     inputFormat_.sampleRate);
+
+            if (byteCount > 0) {
+                if ((flags & AUDCLNT_BUFFERFLAGS_SILENT) != 0 || !data) {
+                    silenceBuffer_.assign(byteCount, 0);
+                    callback_(silenceBuffer_.data(), byteCount, timestampHns, durationHns);
+                } else {
+                    callback_(data, byteCount, timestampHns, durationHns);
+                }
+            }
+
+            writtenFrames_ += framesAvailable;
+            lastDevicePositionEnd_ = devicePosition + framesAvailable;
+            hasLastDevicePosition_ = true;
+            captureClient_->ReleaseBuffer(framesAvailable);
+
+            hr = captureClient_->GetNextPacketSize(&packetFrames);
+            if (FAILED(hr)) {
+                std::cerr << "ERROR: IAudioCaptureClient::GetNextPacketSize failed (hr=0x"
+                          << std::hex << hr << std::dec << ")" << std::endl;
+                packetFrames = 0;
+                break;
+            }
+        }
+
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    }
+
+}

electron/native/wgc-capture/src/wasapi_loopback_capture.h

@@ -0,0 +1,60 @@
+#pragma once
+
+#include "mf_encoder.h"
+
+#include <Windows.h>
+#include <audioclient.h>
+#include <mmdeviceapi.h>
+#include <wrl/client.h>
+
+#include <atomic>
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <thread>
+#include <vector>
+
+enum class WasapiCaptureEndpoint {
+    SystemLoopback,
+    Microphone,
+};
+
+class WasapiLoopbackCapture {
+public:
+    using AudioCallback = std::function<void(const BYTE* data, DWORD byteCount, int64_t timestampHns, int64_t durationHns)>;
+
+    WasapiLoopbackCapture() = default;
+    ~WasapiLoopbackCapture();
+
+    WasapiLoopbackCapture(const WasapiLoopbackCapture&) = delete;
+    WasapiLoopbackCapture& operator=(const WasapiLoopbackCapture&) = delete;
+
+    bool initializeSystemLoopback();
+    bool initializeMicrophone(const std::wstring& deviceId, const std::wstring& deviceName);
+    bool start(AudioCallback callback);
+    void stop();
+
+    const AudioInputFormat& inputFormat() const;
+    const std::wstring& selectedDeviceName() const;
+
+private:
+    bool initialize(WasapiCaptureEndpoint endpoint, const std::wstring& deviceId, const std::wstring& deviceName);
+    bool resolveMicrophoneByName(const std::wstring& deviceName);
+    void captureLoop();
+    bool resolveInputFormat(WAVEFORMATEX* mixFormat);
+
+    Microsoft::WRL::ComPtr<IMMDeviceEnumerator> deviceEnumerator_;
+    Microsoft::WRL::ComPtr<IMMDevice> device_;
+    Microsoft::WRL::ComPtr<IAudioClient> audioClient_;
+    Microsoft::WRL::ComPtr<IAudioCaptureClient> captureClient_;
+    WAVEFORMATEX* mixFormat_ = nullptr;
+    AudioInputFormat inputFormat_{};
+    std::wstring selectedDeviceName_;
+    AudioCallback callback_;
+    std::thread thread_;
+    std::atomic<bool> stopRequested_ = false;
+    std::vector<BYTE> silenceBuffer_;
+    uint64_t writtenFrames_ = 0;
+    uint64_t lastDevicePositionEnd_ = 0;
+    bool hasLastDevicePosition_ = false;
+};

electron/native/wgc-capture/src/webcam_capture.cpp

@@ -0,0 +1,419 @@
+#include "webcam_capture.h"
+
+#include <mfapi.h>
+#include <mferror.h>
+#include <propvarutil.h>
+
+#include <algorithm>
+#include <chrono>
+#include <cwctype>
+#include <iostream>
+
+namespace {
+
+bool succeeded(HRESULT hr, const char* label) {
+    if (SUCCEEDED(hr)) {
+        return true;
+    }
+
+    std::cerr << "ERROR: " << label << " failed (hr=0x" << std::hex << hr << std::dec << ")"
+              << std::endl;
+    return false;
+}
+
+std::wstring readAllocatedString(IMFActivate* activate, REFGUID key) {
+    WCHAR* value = nullptr;
+    UINT32 length = 0;
+    if (FAILED(activate->GetAllocatedString(key, &value, &length)) || !value) {
+        return {};
+    }
+
+    std::wstring result(value, value + length);
+    CoTaskMemFree(value);
+    return result;
+}
+
+bool containsInsensitive(const std::wstring& haystack, const std::wstring& needle) {
+    if (haystack.empty() || needle.empty()) {
+        return false;
+    }
+
+    std::wstring lowerHaystack = haystack;
+    std::wstring lowerNeedle = needle;
+    std::transform(lowerHaystack.begin(), lowerHaystack.end(), lowerHaystack.begin(), ::towlower);
+    std::transform(lowerNeedle.begin(), lowerNeedle.end(), lowerNeedle.begin(), ::towlower);
+    return lowerHaystack.find(lowerNeedle) != std::wstring::npos ||
+        lowerNeedle.find(lowerHaystack) != std::wstring::npos;
+}
+
+std::wstring normalizeDeviceName(const std::wstring& value) {
+    std::wstring normalized;
+    normalized.reserve(value.size());
+    bool lastWasSpace = true;
+    for (const wchar_t ch : value) {
+        if (std::iswalnum(ch)) {
+            normalized.push_back(static_cast<wchar_t>(std::towlower(ch)));
+            lastWasSpace = false;
+            continue;
+        }
+        if (!lastWasSpace) {
+            normalized.push_back(L' ');
+            lastWasSpace = true;
+        }
+    }
+    while (!normalized.empty() && normalized.back() == L' ') {
+        normalized.pop_back();
+    }
+    return normalized;
+}
+
+std::vector<std::wstring> splitWords(const std::wstring& value) {
+    std::vector<std::wstring> words;
+    size_t start = 0;
+    while (start < value.size()) {
+        const size_t end = value.find(L' ', start);
+        const auto word = value.substr(start, end == std::wstring::npos ? std::wstring::npos : end - start);
+        if (word.size() > 1 && word != L"camera" && word != L"webcam" && word != L"video" && word != L"input") {
+            words.push_back(word);
+        }
+        if (end == std::wstring::npos) {
+            break;
+        }
+        start = end + 1;
+    }
+    return words;
+}
+
+int deviceMatchScore(
+    const std::wstring& candidateName,
+    const std::wstring& candidateLink,
+    const std::wstring& requestedName,
+    const std::wstring& requestedId) {
+    int score = 0;
+    const auto normalizedName = normalizeDeviceName(candidateName);
+    const auto normalizedLink = normalizeDeviceName(candidateLink);
+    const auto normalizedRequestedName = normalizeDeviceName(requestedName);
+    const auto normalizedRequestedId = normalizeDeviceName(requestedId);
+
+    if (!normalizedRequestedName.empty()) {
+        if (normalizedName == normalizedRequestedName) {
+            score = std::max(score, 1000);
+        }
+        if (containsInsensitive(normalizedName, normalizedRequestedName)) {
+            score = std::max(score, 900);
+        }
+        if (containsInsensitive(normalizedLink, normalizedRequestedName)) {
+            score = std::max(score, 800);
+        }
+
+        int wordScore = 0;
+        for (const auto& word : splitWords(normalizedRequestedName)) {
+            if (normalizedName.find(word) != std::wstring::npos) {
+                wordScore += 100;
+            } else if (normalizedLink.find(word) != std::wstring::npos) {
+                wordScore += 50;
+            }
+        }
+        score = std::max(score, wordScore);
+    }
+
+    if (!normalizedRequestedId.empty()) {
+        if (containsInsensitive(normalizedLink, normalizedRequestedId)) {
+            score = std::max(score, 700);
+        }
+        if (containsInsensitive(normalizedName, normalizedRequestedId)) {
+            score = std::max(score, 600);
+        }
+    }
+
+    return score;
+}
+
+} // namespace
+
+WebcamCapture::~WebcamCapture() {
+    stop();
+}
+
+bool WebcamCapture::initialize(
+    const std::wstring& deviceId,
+    const std::wstring& deviceName,
+    const std::wstring& directShowClsid,
+    int requestedWidth,
+    int requestedHeight,
+    int requestedFps) {
+    fps_ = std::clamp(requestedFps > 0 ? requestedFps : 30, 1, 60);
+    usingDirectShow_ = false;
+    selectedMatchScore_ = 0;
+    if (!succeeded(MFStartup(MF_VERSION), "MFStartup(webcam)")) {
+        if (directShowCapture_.initialize(deviceId, deviceName, directShowClsid, requestedWidth, requestedHeight, fps_)) {
+            usingDirectShow_ = true;
+            return true;
+        }
+        return false;
+    }
+    mfStarted_ = true;
+    if (!selectDevice(deviceId, deviceName)) {
+        if (mfStarted_) {
+            MFShutdown();
+            mfStarted_ = false;
+        }
+        if (directShowCapture_.initialize(deviceId, deviceName, directShowClsid, requestedWidth, requestedHeight, fps_)) {
+            usingDirectShow_ = true;
+            return true;
+        }
+        return false;
+    }
+
+    if ((!deviceId.empty() || !deviceName.empty()) && selectedMatchScore_ <= 0) {
+        if (mediaSource_) {
+            mediaSource_->Shutdown();
+        }
+        sourceReader_.Reset();
+        mediaSource_.Reset();
+        if (mfStarted_) {
+            MFShutdown();
+            mfStarted_ = false;
+        }
+        if (directShowCapture_.initialize(deviceId, deviceName, directShowClsid, requestedWidth, requestedHeight, fps_)) {
+            usingDirectShow_ = true;
+            return true;
+        }
+        std::cerr << "ERROR: Requested webcam device was not found by native Windows webcam providers"
+                  << std::endl;
+        return false;
+    }
+
+    return configureReader(requestedWidth, requestedHeight, fps_);
+}
+
+bool WebcamCapture::selectDevice(const std::wstring& deviceId, const std::wstring& deviceName) {
+    Microsoft::WRL::ComPtr<IMFAttributes> attributes;
+    if (!succeeded(MFCreateAttributes(&attributes, 1), "MFCreateAttributes(webcam enumeration)")) {
+        return false;
+    }
+    if (!succeeded(attributes->SetGUID(
+            MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE,
+            MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_GUID),
+            "SetGUID(webcam source type)")) {
+        return false;
+    }
+
+    IMFActivate** devices = nullptr;
+    UINT32 deviceCount = 0;
+    HRESULT hr = MFEnumDeviceSources(attributes.Get(), &devices, &deviceCount);
+    if (!succeeded(hr, "MFEnumDeviceSources") || deviceCount == 0) {
+        if (devices) {
+            CoTaskMemFree(devices);
+        }
+        std::cerr << "ERROR: No native Windows webcam devices were found" << std::endl;
+        return false;
+    }
+
+    UINT32 selectedIndex = 0;
+    int bestScore = 0;
+    for (UINT32 index = 0; index < deviceCount; index += 1) {
+        const std::wstring name = readAllocatedString(devices[index], MF_DEVSOURCE_ATTRIBUTE_FRIENDLY_NAME);
+        const std::wstring symbolicLink = readAllocatedString(devices[index], MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK);
+        const int score = deviceMatchScore(name, symbolicLink, deviceName, deviceId);
+        std::wcerr << L"INFO: Native webcam candidate [" << index << L"] name=\"" << name << L"\" score=" << score << std::endl;
+        if (score > bestScore) {
+            selectedIndex = index;
+            bestScore = score;
+        }
+    }
+
+    if ((!deviceId.empty() || !deviceName.empty()) && bestScore <= 0) {
+        std::cerr << "WARNING: Requested webcam device was not found by Media Foundation; trying DirectShow"
+                  << std::endl;
+    }
+
+    selectedMatchScore_ = bestScore;
+    selectedDeviceName_ = readAllocatedString(devices[selectedIndex], MF_DEVSOURCE_ATTRIBUTE_FRIENDLY_NAME);
+    hr = devices[selectedIndex]->ActivateObject(IID_PPV_ARGS(&mediaSource_));
+
+    for (UINT32 index = 0; index < deviceCount; index += 1) {
+        devices[index]->Release();
+    }
+    CoTaskMemFree(devices);
+
+    return succeeded(hr, "ActivateObject(webcam)");
+}
+
+bool WebcamCapture::configureReader(int requestedWidth, int requestedHeight, int requestedFps) {
+    Microsoft::WRL::ComPtr<IMFAttributes> attributes;
+    if (!succeeded(MFCreateAttributes(&attributes, 2), "MFCreateAttributes(webcam reader)")) {
+        return false;
+    }
+    attributes->SetUINT32(MF_SOURCE_READER_ENABLE_VIDEO_PROCESSING, TRUE);
+    attributes->SetUINT32(MF_READWRITE_DISABLE_CONVERTERS, FALSE);
+
+    if (!succeeded(MFCreateSourceReaderFromMediaSource(mediaSource_.Get(), attributes.Get(), &sourceReader_),
+                   "MFCreateSourceReaderFromMediaSource(webcam)")) {
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IMFMediaType> mediaType;
+    if (!succeeded(MFCreateMediaType(&mediaType), "MFCreateMediaType(webcam output)")) {
+        return false;
+    }
+    mediaType->SetGUID(MF_MT_MAJOR_TYPE, MFMediaType_Video);
+    mediaType->SetGUID(MF_MT_SUBTYPE, MFVideoFormat_RGB32);
+    if (requestedWidth > 0 && requestedHeight > 0) {
+        MFSetAttributeSize(mediaType.Get(), MF_MT_FRAME_SIZE, static_cast<UINT32>(requestedWidth), static_cast<UINT32>(requestedHeight));
+    }
+    MFSetAttributeRatio(mediaType.Get(), MF_MT_FRAME_RATE, static_cast<UINT32>(std::max(1, requestedFps)), 1);
+
+    if (!succeeded(sourceReader_->SetCurrentMediaType(MF_SOURCE_READER_FIRST_VIDEO_STREAM, nullptr, mediaType.Get()),
+                   "SetCurrentMediaType(webcam RGB32)")) {
+        return false;
+    }
+    sourceReader_->SetStreamSelection(MF_SOURCE_READER_ALL_STREAMS, FALSE);
+    sourceReader_->SetStreamSelection(MF_SOURCE_READER_FIRST_VIDEO_STREAM, TRUE);
+
+    Microsoft::WRL::ComPtr<IMFMediaType> currentType;
+    if (!succeeded(sourceReader_->GetCurrentMediaType(MF_SOURCE_READER_FIRST_VIDEO_STREAM, &currentType),
+                   "GetCurrentMediaType(webcam)")) {
+        return false;
+    }
+
+    UINT32 width = 0;
+    UINT32 height = 0;
+    if (FAILED(MFGetAttributeSize(currentType.Get(), MF_MT_FRAME_SIZE, &width, &height)) || width == 0 || height == 0) {
+        width = static_cast<UINT32>(requestedWidth > 0 ? requestedWidth : 1280);
+        height = static_cast<UINT32>(requestedHeight > 0 ? requestedHeight : 720);
+    }
+    width_ = static_cast<int>(width);
+    height_ = static_cast<int>(height);
+    return true;
+}
+
+bool WebcamCapture::start() {
+    if (usingDirectShow_) {
+        return directShowCapture_.start();
+    }
+    if (!sourceReader_ || thread_.joinable()) {
+        return false;
+    }
+
+    stopRequested_ = false;
+    thread_ = std::thread(&WebcamCapture::captureLoop, this);
+    return true;
+}
+
+void WebcamCapture::stop() {
+    directShowCapture_.stop();
+    stopRequested_ = true;
+    if (thread_.joinable()) {
+        thread_.join();
+    }
+    if (mediaSource_) {
+        mediaSource_->Shutdown();
+    }
+    sourceReader_.Reset();
+    mediaSource_.Reset();
+    if (mfStarted_) {
+        MFShutdown();
+        mfStarted_ = false;
+    }
+}
+
+void WebcamCapture::captureLoop() {
+    CoInitializeEx(nullptr, COINIT_MULTITHREADED);
+
+    while (!stopRequested_) {
+        DWORD streamIndex = 0;
+        DWORD flags = 0;
+        LONGLONG timestamp = 0;
+        Microsoft::WRL::ComPtr<IMFSample> sample;
+        HRESULT hr = sourceReader_->ReadSample(
+            MF_SOURCE_READER_FIRST_VIDEO_STREAM,
+            0,
+            &streamIndex,
+            &flags,
+            &timestamp,
+            &sample);
+        (void)streamIndex;
+        (void)timestamp;
+
+        if (FAILED(hr)) {
+            std::cerr << "WARNING: Failed to read webcam sample (hr=0x" << std::hex << hr << std::dec << ")"
+                      << std::endl;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+            continue;
+        }
+        if ((flags & MF_SOURCE_READERF_ENDOFSTREAM) != 0) {
+            break;
+        }
+        if (!sample) {
+            continue;
+        }
+
+        Microsoft::WRL::ComPtr<IMFMediaBuffer> buffer;
+        if (FAILED(sample->ConvertToContiguousBuffer(&buffer)) || !buffer) {
+            continue;
+        }
+
+        BYTE* data = nullptr;
+        DWORD maxLength = 0;
+        DWORD currentLength = 0;
+        if (FAILED(buffer->Lock(&data, &maxLength, &currentLength)) || !data) {
+            continue;
+        }
+
+        const DWORD expectedLength = static_cast<DWORD>(std::max(0, width_) * std::max(0, height_) * 4);
+        if (currentLength >= expectedLength && expectedLength > 0) {
+            std::scoped_lock lock(frameMutex_);
+            latestFrame_.assign(data, data + expectedLength);
+            latestFrameSequence_ += 1;
+        }
+
+        buffer->Unlock();
+    }
+
+    CoUninitialize();
+}
+
+bool WebcamCapture::copyLatestFrame(WebcamFrameSnapshot& destination) {
+    if (usingDirectShow_) {
+        return directShowCapture_.copyLatestFrame(destination);
+    }
+    std::scoped_lock lock(frameMutex_);
+    if (latestFrame_.empty() || width_ <= 0 || height_ <= 0) {
+        return false;
+    }
+
+    destination.data = latestFrame_;
+    destination.width = width_;
+    destination.height = height_;
+    destination.sequence = latestFrameSequence_;
+    return true;
+}
+
+int WebcamCapture::width() const {
+    if (usingDirectShow_) {
+        return directShowCapture_.width();
+    }
+    return width_;
+}
+
+int WebcamCapture::height() const {
+    if (usingDirectShow_) {
+        return directShowCapture_.height();
+    }
+    return height_;
+}
+
+int WebcamCapture::fps() const {
+    if (usingDirectShow_) {
+        return directShowCapture_.fps();
+    }
+    return fps_;
+}
+
+const std::wstring& WebcamCapture::selectedDeviceName() const {
+    if (usingDirectShow_) {
+        return directShowCapture_.selectedDeviceName();
+    }
+    return selectedDeviceName_;
+}

electron/native/wgc-capture/src/webcam_capture.h

@@ -0,0 +1,61 @@
+#pragma once
+
+#include "dshow_webcam_capture.h"
+
+#include <Windows.h>
+#include <mfidl.h>
+#include <mfreadwrite.h>
+#include <wrl/client.h>
+
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+class WebcamCapture {
+public:
+    WebcamCapture() = default;
+    ~WebcamCapture();
+
+    WebcamCapture(const WebcamCapture&) = delete;
+    WebcamCapture& operator=(const WebcamCapture&) = delete;
+
+    bool initialize(
+        const std::wstring& deviceId,
+        const std::wstring& deviceName,
+        const std::wstring& directShowClsid,
+        int requestedWidth,
+        int requestedHeight,
+        int requestedFps);
+    bool start();
+    void stop();
+    bool copyLatestFrame(WebcamFrameSnapshot& destination);
+
+    int width() const;
+    int height() const;
+    int fps() const;
+    const std::wstring& selectedDeviceName() const;
+
+private:
+    bool selectDevice(const std::wstring& deviceId, const std::wstring& deviceName);
+    bool configureReader(int requestedWidth, int requestedHeight, int requestedFps);
+    void captureLoop();
+
+    Microsoft::WRL::ComPtr<IMFMediaSource> mediaSource_;
+    Microsoft::WRL::ComPtr<IMFSourceReader> sourceReader_;
+    DirectShowWebcamCapture directShowCapture_;
+    std::thread thread_;
+    std::atomic<bool> stopRequested_ = false;
+    std::mutex frameMutex_;
+    std::vector<BYTE> latestFrame_;
+    uint64_t latestFrameSequence_ = 0;
+    int width_ = 0;
+    int height_ = 0;
+    int fps_ = 30;
+    bool mfStarted_ = false;
+    bool usingDirectShow_ = false;
+    int selectedMatchScore_ = 0;
+    std::wstring selectedDeviceName_;
+};

electron/native/wgc-capture/src/wgc_session.cpp

@@ -0,0 +1,315 @@
+#include "wgc_session.h"
+
+#include <Windows.Graphics.Capture.Interop.h>
+#include <dxgi1_2.h>
+#include <inspectable.h>
+#include <winrt/base.h>
+
+#include <iostream>
+
+namespace wf = winrt::Windows::Foundation;
+namespace wgcap = winrt::Windows::Graphics::Capture;
+namespace wgdx = winrt::Windows::Graphics::DirectX;
+namespace wgd3d = winrt::Windows::Graphics::DirectX::Direct3D11;
+
+extern "C" HRESULT __stdcall CreateDirect3D11DeviceFromDXGIDevice(
+    ::IDXGIDevice* dxgiDevice,
+    ::IInspectable** graphicsDevice);
+
+namespace {
+
+bool succeeded(HRESULT hr, const char* label) {
+    if (SUCCEEDED(hr)) {
+        return true;
+    }
+
+    std::cerr << "ERROR: " << label << " failed (hr=0x" << std::hex << hr << std::dec << ")"
+              << std::endl;
+    return false;
+}
+
+int64_t timeSpanToHns(wf::TimeSpan const& value) {
+    return value.count();
+}
+
+} // namespace
+
+WgcSession::~WgcSession() {
+    stop();
+}
+
+bool WgcSession::createD3DDevice() {
+    UINT flags = D3D11_CREATE_DEVICE_BGRA_SUPPORT;
+#if defined(_DEBUG)
+    flags |= D3D11_CREATE_DEVICE_DEBUG;
+#endif
+
+    D3D_FEATURE_LEVEL featureLevels[] = {
+        D3D_FEATURE_LEVEL_11_1,
+        D3D_FEATURE_LEVEL_11_0,
+        D3D_FEATURE_LEVEL_10_1,
+        D3D_FEATURE_LEVEL_10_0,
+    };
+    D3D_FEATURE_LEVEL featureLevel{};
+
+    HRESULT hr = D3D11CreateDevice(
+        nullptr,
+        D3D_DRIVER_TYPE_HARDWARE,
+        nullptr,
+        flags,
+        featureLevels,
+        ARRAYSIZE(featureLevels),
+        D3D11_SDK_VERSION,
+        &d3dDevice_,
+        &featureLevel,
+        &d3dContext_);
+
+#if defined(_DEBUG)
+    if (FAILED(hr)) {
+        flags &= ~D3D11_CREATE_DEVICE_DEBUG;
+        hr = D3D11CreateDevice(
+            nullptr,
+            D3D_DRIVER_TYPE_HARDWARE,
+            nullptr,
+            flags,
+            featureLevels,
+            ARRAYSIZE(featureLevels),
+            D3D11_SDK_VERSION,
+            &d3dDevice_,
+            &featureLevel,
+            &d3dContext_);
+    }
+#endif
+
+    if (!succeeded(hr, "D3D11CreateDevice")) {
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IDXGIDevice> dxgiDevice;
+    if (!succeeded(d3dDevice_.As(&dxgiDevice), "Query IDXGIDevice")) {
+        return false;
+    }
+
+    winrt::com_ptr<::IInspectable> inspectableDevice;
+    if (!succeeded(CreateDirect3D11DeviceFromDXGIDevice(dxgiDevice.Get(), inspectableDevice.put()),
+                   "CreateDirect3D11DeviceFromDXGIDevice")) {
+        return false;
+    }
+
+    winrtDevice_ = inspectableDevice.as<wgd3d::IDirect3DDevice>();
+    return true;
+}
+
+bool WgcSession::createCaptureItem(HMONITOR monitor) {
+    auto factory = winrt::get_activation_factory<wgcap::GraphicsCaptureItem>();
+    auto interop = factory.as<IGraphicsCaptureItemInterop>();
+
+    wgcap::GraphicsCaptureItem item{nullptr};
+    HRESULT hr = interop->CreateForMonitor(
+        monitor,
+        winrt::guid_of<wgcap::GraphicsCaptureItem>(),
+        reinterpret_cast<void**>(winrt::put_abi(item)));
+    if (!succeeded(hr, "CreateForMonitor")) {
+        return false;
+    }
+
+    item_ = item;
+    const auto size = item_.Size();
+    width_ = static_cast<int>(size.Width);
+    height_ = static_cast<int>(size.Height);
+    return width_ > 0 && height_ > 0;
+}
+
+bool WgcSession::createCaptureItem(HWND window) {
+    auto factory = winrt::get_activation_factory<wgcap::GraphicsCaptureItem>();
+    auto interop = factory.as<IGraphicsCaptureItemInterop>();
+
+    wgcap::GraphicsCaptureItem item{nullptr};
+    HRESULT hr = interop->CreateForWindow(
+        window,
+        winrt::guid_of<wgcap::GraphicsCaptureItem>(),
+        reinterpret_cast<void**>(winrt::put_abi(item)));
+    if (!succeeded(hr, "CreateForWindow")) {
+        return false;
+    }
+
+    item_ = item;
+    const auto size = item_.Size();
+    width_ = static_cast<int>(size.Width);
+    height_ = static_cast<int>(size.Height);
+    return width_ > 0 && height_ > 0;
+}
+
+bool WgcSession::applySessionOptions(bool captureCursor) {
+    captureCursor_ = captureCursor;
+
+    try {
+        auto session2 = session_.try_as<wgcap::IGraphicsCaptureSession2>();
+        if (!session2) {
+            if (!captureCursor) {
+                std::cerr << "ERROR: WGC cursor suppression is not supported by this Windows runtime"
+                          << std::endl;
+                return false;
+            }
+        } else {
+            session2.IsCursorCaptureEnabled(captureCursor);
+            const bool appliedCursorCapture = session2.IsCursorCaptureEnabled();
+            std::cout << "{\"event\":\"cursor-capture\",\"schemaVersion\":2,\"requested\":"
+                      << (captureCursor ? "true" : "false")
+                      << ",\"applied\":" << (appliedCursorCapture ? "true" : "false") << "}"
+                      << std::endl;
+
+            if (appliedCursorCapture != captureCursor) {
+                std::cerr << "ERROR: WGC cursor capture setting did not apply" << std::endl;
+                return false;
+            }
+        }
+    } catch (winrt::hresult_error const& error) {
+        std::cerr << "ERROR: Failed to configure WGC cursor capture (hr=0x" << std::hex
+                  << static_cast<uint32_t>(error.code()) << std::dec << ")" << std::endl;
+        if (!captureCursor) {
+            return false;
+        }
+    } catch (...) {
+        std::cerr << "ERROR: Failed to configure WGC cursor capture" << std::endl;
+        if (!captureCursor) {
+            return false;
+        }
+    }
+
+    try {
+        session_.IsBorderRequired(false);
+    } catch (...) {
+        // IsBorderRequired is Windows 11-only. Ignore it on older builds.
+    }
+
+    return true;
+}
+
+bool WgcSession::initialize(HMONITOR monitor, int fps, bool captureCursor) {
+    fps_ = fps > 0 ? fps : 60;
+    if (!createD3DDevice()) {
+        return false;
+    }
+    if (!createCaptureItem(monitor)) {
+        return false;
+    }
+
+    framePool_ = wgcap::Direct3D11CaptureFramePool::CreateFreeThreaded(
+        winrtDevice_,
+        wgdx::DirectXPixelFormat::B8G8R8A8UIntNormalized,
+        2,
+        item_.Size());
+    session_ = framePool_.CreateCaptureSession(item_);
+
+    if (!applySessionOptions(captureCursor)) {
+        return false;
+    }
+
+    frameArrivedToken_ = framePool_.FrameArrived({this, &WgcSession::onFrameArrived});
+    return true;
+}
+
+bool WgcSession::initialize(HWND window, int fps, bool captureCursor) {
+    fps_ = fps > 0 ? fps : 60;
+    if (!createD3DDevice()) {
+        return false;
+    }
+    if (!createCaptureItem(window)) {
+        return false;
+    }
+
+    framePool_ = wgcap::Direct3D11CaptureFramePool::CreateFreeThreaded(
+        winrtDevice_,
+        wgdx::DirectXPixelFormat::B8G8R8A8UIntNormalized,
+        2,
+        item_.Size());
+    session_ = framePool_.CreateCaptureSession(item_);
+
+    if (!applySessionOptions(captureCursor)) {
+        return false;
+    }
+
+    frameArrivedToken_ = framePool_.FrameArrived({this, &WgcSession::onFrameArrived});
+    return true;
+}
+
+void WgcSession::setFrameCallback(FrameCallback callback) {
+    std::scoped_lock lock(callbackMutex_);
+    frameCallback_ = std::move(callback);
+}
+
+bool WgcSession::start() {
+    if (!session_) {
+        return false;
+    }
+    if (!applySessionOptions(captureCursor_)) {
+        return false;
+    }
+    session_.StartCapture();
+    started_ = true;
+    return true;
+}
+
+void WgcSession::stop() {
+    if (framePool_) {
+        framePool_.FrameArrived(frameArrivedToken_);
+    }
+    if (session_) {
+        session_.Close();
+        session_ = nullptr;
+    }
+    if (framePool_) {
+        framePool_.Close();
+        framePool_ = nullptr;
+    }
+    item_ = nullptr;
+    winrtDevice_ = nullptr;
+    d3dContext_.Reset();
+    d3dDevice_.Reset();
+    started_ = false;
+}
+
+void WgcSession::onFrameArrived(
+    wgcap::Direct3D11CaptureFramePool const& sender,
+    wf::IInspectable const&) {
+    auto frame = sender.TryGetNextFrame();
+    if (!frame) {
+        return;
+    }
+
+    auto surface = frame.Surface();
+    auto access = surface.as<::Windows::Graphics::DirectX::Direct3D11::IDirect3DDxgiInterfaceAccess>();
+    Microsoft::WRL::ComPtr<ID3D11Texture2D> texture;
+    HRESULT hr = access->GetInterface(__uuidof(ID3D11Texture2D), reinterpret_cast<void**>(texture.GetAddressOf()));
+    if (FAILED(hr) || !texture) {
+        return;
+    }
+
+    FrameCallback callback;
+    {
+        std::scoped_lock lock(callbackMutex_);
+        callback = frameCallback_;
+    }
+
+    if (callback) {
+        callback(texture.Get(), timeSpanToHns(frame.SystemRelativeTime()));
+    }
+    frame.Close();
+}
+
+int WgcSession::captureWidth() const {
+    return width_;
+}
+
+int WgcSession::captureHeight() const {
+    return height_;
+}
+
+ID3D11Device* WgcSession::device() const {
+    return d3dDevice_.Get();
+}
+
+ID3D11DeviceContext* WgcSession::context() const {
+    return d3dContext_.Get();
+}

electron/native/wgc-capture/src/wgc_session.h

@@ -0,0 +1,59 @@
+#pragma once
+
+#include <Windows.h>
+#include <d3d11.h>
+#include <windows.graphics.capture.h>
+#include <windows.graphics.directx.direct3d11.interop.h>
+#include <winrt/Windows.Foundation.h>
+#include <winrt/Windows.Graphics.Capture.h>
+#include <winrt/Windows.Graphics.DirectX.Direct3D11.h>
+#include <wrl/client.h>
+
+#include <functional>
+#include <mutex>
+
+class WgcSession {
+public:
+    using FrameCallback = std::function<void(ID3D11Texture2D*, int64_t)>;
+
+    WgcSession() = default;
+    ~WgcSession();
+
+    WgcSession(const WgcSession&) = delete;
+    WgcSession& operator=(const WgcSession&) = delete;
+
+    bool initialize(HMONITOR monitor, int fps, bool captureCursor);
+    bool initialize(HWND window, int fps, bool captureCursor);
+    void setFrameCallback(FrameCallback callback);
+    bool start();
+    void stop();
+
+    int captureWidth() const;
+    int captureHeight() const;
+    ID3D11Device* device() const;
+    ID3D11DeviceContext* context() const;
+
+private:
+    bool createD3DDevice();
+    bool createCaptureItem(HMONITOR monitor);
+    bool createCaptureItem(HWND window);
+    bool applySessionOptions(bool captureCursor);
+    void onFrameArrived(
+        winrt::Windows::Graphics::Capture::Direct3D11CaptureFramePool const& sender,
+        winrt::Windows::Foundation::IInspectable const&);
+
+    Microsoft::WRL::ComPtr<ID3D11Device> d3dDevice_;
+    Microsoft::WRL::ComPtr<ID3D11DeviceContext> d3dContext_;
+    winrt::Windows::Graphics::DirectX::Direct3D11::IDirect3DDevice winrtDevice_{nullptr};
+    winrt::Windows::Graphics::Capture::GraphicsCaptureItem item_{nullptr};
+    winrt::Windows::Graphics::Capture::Direct3D11CaptureFramePool framePool_{nullptr};
+    winrt::Windows::Graphics::Capture::GraphicsCaptureSession session_{nullptr};
+    winrt::event_token frameArrivedToken_{};
+    FrameCallback frameCallback_;
+    std::mutex callbackMutex_;
+    int width_ = 0;
+    int height_ = 0;
+    int fps_ = 60;
+    bool captureCursor_ = false;
+    bool started_ = false;
+};

electron/preload.ts

@@ -1,63 +1,241 @@
-import { contextBridge, ipcRenderer } from 'electron'
+import { contextBridge, ipcRenderer } from "electron";
+import type { NativeMacRecordingRequest } from "../src/lib/nativeMacRecording";
+import type { NativeWindowsRecordingRequest } from "../src/lib/nativeWindowsRecording";
+import type { RecordingSession, StoreRecordedSessionInput } from "../src/lib/recordingSession";
+import { NATIVE_BRIDGE_CHANNEL, type NativeBridgeRequest } from "../src/native/contracts";
 
-contextBridge.exposeInMainWorld('electronAPI', {
-    hudOverlayHide: () => {
-      ipcRenderer.send('hud-overlay-hide');
-    },
-    hudOverlayClose: () => {
-      ipcRenderer.send('hud-overlay-close');
-    },
-  getAssetBasePath: async () => {
-    // ask main process for the correct base path (production vs dev)
-    return await ipcRenderer.invoke('get-asset-base-path')
-  },
-  getSources: async (opts: Electron.SourcesOptions) => {
-    return await ipcRenderer.invoke('get-sources', opts)
-  },
-  switchToEditor: () => {
-    return ipcRenderer.invoke('switch-to-editor')
-  },
-  openSourceSelector: () => {
-    return ipcRenderer.invoke('open-source-selector')
-  },
-  selectSource: (source: any) => {
-    return ipcRenderer.invoke('select-source', source)
-  },
-  getSelectedSource: () => {
-    return ipcRenderer.invoke('get-selected-source')
-  },
+// Asset base URL is passed from the main process via webPreferences.additionalArguments
+// (see windows.ts). Sandboxed preloads cannot import node:path / node:url, so we
+// can't compute it here.
+const ASSET_BASE_URL_ARG_PREFIX = "--asset-base-url=";
+const assetBaseUrlArg = process.argv.find((arg) => arg.startsWith(ASSET_BASE_URL_ARG_PREFIX));
+const assetBaseUrl = assetBaseUrlArg ? assetBaseUrlArg.slice(ASSET_BASE_URL_ARG_PREFIX.length) : "";
 
-  storeRecordedVideo: (videoData: ArrayBuffer, fileName: string) => {
-    return ipcRenderer.invoke('store-recorded-video', videoData, fileName)
-  },
+contextBridge.exposeInMainWorld("electronAPI", {
+	assetBaseUrl,
+	invokeNativeBridge: <TData>(request: NativeBridgeRequest) => {
+		return ipcRenderer.invoke(NATIVE_BRIDGE_CHANNEL, request) as Promise<TData>;
+	},
+	hudOverlayHide: () => {
+		ipcRenderer.send("hud-overlay-hide");
+	},
+	hudOverlayClose: () => {
+		ipcRenderer.send("hud-overlay-close");
+	},
+	setHudOverlayIgnoreMouseEvents: (ignore: boolean) => {
+		ipcRenderer.send("hud-overlay-ignore-mouse-events", ignore);
+	},
+	moveHudOverlayBy: (deltaX: number, deltaY: number) => {
+		ipcRenderer.send("hud-overlay-move-by", deltaX, deltaY);
+	},
+	getSources: async (opts: Electron.SourcesOptions) => {
+		return await ipcRenderer.invoke("get-sources", opts);
+	},
+	switchToEditor: () => {
+		return ipcRenderer.invoke("switch-to-editor");
+	},
+	switchToHud: () => {
+		return ipcRenderer.invoke("switch-to-hud");
+	},
+	startNewRecording: () => {
+		return ipcRenderer.invoke("start-new-recording");
+	},
+	openSourceSelector: () => {
+		return ipcRenderer.invoke("open-source-selector");
+	},
+	selectSource: (source: ProcessedDesktopSource) => {
+		return ipcRenderer.invoke("select-source", source);
+	},
+	getSelectedSource: () => {
+		return ipcRenderer.invoke("get-selected-source");
+	},
+	requestCameraAccess: () => {
+		return ipcRenderer.invoke("request-camera-access");
+	},
+	requestScreenAccess: () => {
+		return ipcRenderer.invoke("request-screen-access");
+	},
+	requestNativeMacCursorAccess: () => {
+		return ipcRenderer.invoke("request-native-mac-cursor-access");
+	},
+	storeRecordedVideo: (videoData: ArrayBuffer, fileName: string) => {
+		return ipcRenderer.invoke("store-recorded-video", videoData, fileName);
+	},
+	storeRecordedSession: (payload: StoreRecordedSessionInput) => {
+		return ipcRenderer.invoke("store-recorded-session", payload);
+	},
 
-  getRecordedVideoPath: () => {
-    return ipcRenderer.invoke('get-recorded-video-path')
-  },
-  setRecordingState: (recording: boolean) => {
-    return ipcRenderer.invoke('set-recording-state', recording)
-  },
-  onStopRecordingFromTray: (callback: () => void) => {
-    const listener = () => callback()
-    ipcRenderer.on('stop-recording-from-tray', listener)
-    return () => ipcRenderer.removeListener('stop-recording-from-tray', listener)
-  },
-  openExternalUrl: (url: string) => {
-    return ipcRenderer.invoke('open-external-url', url)
-  },
-  saveExportedVideo: (videoData: ArrayBuffer, fileName: string) => {
-    return ipcRenderer.invoke('save-exported-video', videoData, fileName)
-  },
-  openVideoFilePicker: () => {
-    return ipcRenderer.invoke('open-video-file-picker')
-  },
-  setCurrentVideoPath: (path: string) => {
-    return ipcRenderer.invoke('set-current-video-path', path)
-  },
-  getCurrentVideoPath: () => {
-    return ipcRenderer.invoke('get-current-video-path')
-  },
-  clearCurrentVideoPath: () => {
-    return ipcRenderer.invoke('clear-current-video-path')
-  },
-})
+	getRecordedVideoPath: () => {
+		return ipcRenderer.invoke("get-recorded-video-path");
+	},
+	setRecordingState: (
+		recording: boolean,
+		recordingId?: number,
+		cursorCaptureMode?: import("../src/lib/recordingSession").CursorCaptureMode,
+	) => {
+		return ipcRenderer.invoke("set-recording-state", recording, recordingId, cursorCaptureMode);
+	},
+	isNativeWindowsCaptureAvailable: () => {
+		return ipcRenderer.invoke("is-native-windows-capture-available");
+	},
+	isNativeMacCaptureAvailable: () => {
+		return ipcRenderer.invoke("is-native-mac-capture-available");
+	},
+	startNativeWindowsRecording: (request: NativeWindowsRecordingRequest) => {
+		return ipcRenderer.invoke("start-native-windows-recording", request);
+	},
+	stopNativeWindowsRecording: (discard?: boolean) => {
+		return ipcRenderer.invoke("stop-native-windows-recording", discard);
+	},
+	startNativeMacRecording: (request: NativeMacRecordingRequest) => {
+		return ipcRenderer.invoke("start-native-mac-recording", request);
+	},
+	pauseNativeMacRecording: () => {
+		return ipcRenderer.invoke("pause-native-mac-recording");
+	},
+	resumeNativeMacRecording: () => {
+		return ipcRenderer.invoke("resume-native-mac-recording");
+	},
+	stopNativeMacRecording: (discard?: boolean) => {
+		return ipcRenderer.invoke("stop-native-mac-recording", discard);
+	},
+	attachNativeMacWebcamRecording: (payload: {
+		screenVideoPath: string;
+		recordingId: number;
+		webcam: { fileName: string; videoData: ArrayBuffer };
+		cursorCaptureMode?: import("../src/lib/recordingSession").CursorCaptureMode;
+	}) => {
+		return ipcRenderer.invoke("attach-native-mac-webcam-recording", payload);
+	},
+	getCursorTelemetry: (videoPath?: string) => {
+		return ipcRenderer.invoke("get-cursor-telemetry", videoPath);
+	},
+	discardCursorTelemetry: (recordingId: number) => {
+		return ipcRenderer.invoke("discard-cursor-telemetry", recordingId);
+	},
+	onStopRecordingFromTray: (callback: () => void) => {
+		const listener = () => callback();
+		ipcRenderer.on("stop-recording-from-tray", listener);
+		return () => ipcRenderer.removeListener("stop-recording-from-tray", listener);
+	},
+	openExternalUrl: (url: string) => {
+		return ipcRenderer.invoke("open-external-url", url);
+	},
+	pickExportSavePath: (fileName: string, exportFolder?: string) => {
+		return ipcRenderer.invoke("pick-export-save-path", fileName, exportFolder);
+	},
+	writeExportToPath: (videoData: ArrayBuffer, filePath: string) => {
+		return ipcRenderer.invoke("write-export-to-path", videoData, filePath);
+	},
+	openVideoFilePicker: () => {
+		return ipcRenderer.invoke("open-video-file-picker");
+	},
+	setCurrentVideoPath: (path: string) => {
+		return ipcRenderer.invoke("set-current-video-path", path);
+	},
+	setCurrentRecordingSession: (session: RecordingSession | null) => {
+		return ipcRenderer.invoke("set-current-recording-session", session);
+	},
+	getCurrentVideoPath: () => {
+		return ipcRenderer.invoke("get-current-video-path");
+	},
+	getCurrentRecordingSession: () => {
+		return ipcRenderer.invoke("get-current-recording-session");
+	},
+	readBinaryFile: (filePath: string) => {
+		return ipcRenderer.invoke("read-binary-file", filePath);
+	},
+	preparePreviewAudioTrack: (filePath: string) => {
+		return ipcRenderer.invoke("prepare-preview-audio-track", filePath);
+	},
+	clearCurrentVideoPath: () => {
+		return ipcRenderer.invoke("clear-current-video-path");
+	},
+	saveProjectFile: (projectData: unknown, suggestedName?: string, existingProjectPath?: string) => {
+		return ipcRenderer.invoke("save-project-file", projectData, suggestedName, existingProjectPath);
+	},
+	loadProjectFile: () => {
+		return ipcRenderer.invoke("load-project-file");
+	},
+	loadCurrentProjectFile: () => {
+		return ipcRenderer.invoke("load-current-project-file");
+	},
+	onMenuLoadProject: (callback: () => void) => {
+		const listener = () => callback();
+		ipcRenderer.on("menu-load-project", listener);
+		return () => ipcRenderer.removeListener("menu-load-project", listener);
+	},
+	onMenuSaveProject: (callback: () => void) => {
+		const listener = () => callback();
+		ipcRenderer.on("menu-save-project", listener);
+		return () => ipcRenderer.removeListener("menu-save-project", listener);
+	},
+	onMenuSaveProjectAs: (callback: () => void) => {
+		const listener = () => callback();
+		ipcRenderer.on("menu-save-project-as", listener);
+		return () => ipcRenderer.removeListener("menu-save-project-as", listener);
+	},
+	getPlatform: () => {
+		return ipcRenderer.invoke("get-platform");
+	},
+	revealInFolder: (filePath: string) => {
+		return ipcRenderer.invoke("reveal-in-folder", filePath);
+	},
+	getShortcuts: () => {
+		return ipcRenderer.invoke("get-shortcuts");
+	},
+	saveShortcuts: (shortcuts: unknown) => {
+		return ipcRenderer.invoke("save-shortcuts", shortcuts);
+	},
+	setLocale: (locale: string) => {
+		return ipcRenderer.invoke("set-locale", locale);
+	},
+	saveDiagnostic: (payload: {
+		error: string;
+		stack?: string;
+		projectState: unknown;
+		logs: string[];
+	}) => {
+		return ipcRenderer.invoke("save-diagnostic", payload);
+	},
+	setMicrophoneExpanded: (expanded: boolean) => {
+		ipcRenderer.send("hud:setMicrophoneExpanded", expanded);
+	},
+	setHasUnsavedChanges: (hasChanges: boolean) => {
+		ipcRenderer.send("set-has-unsaved-changes", hasChanges);
+	},
+	showCountdownOverlay: (value: number, runId: number) => {
+		return ipcRenderer.invoke("countdown-overlay-show", value, runId);
+	},
+	setCountdownOverlayValue: (value: number, runId: number) => {
+		return ipcRenderer.invoke("countdown-overlay-set-value", value, runId);
+	},
+	hideCountdownOverlay: (runId: number) => {
+		return ipcRenderer.invoke("countdown-overlay-hide", runId);
+	},
+	onCountdownOverlayValue: (callback: (value: number | null) => void) => {
+		const listener = (_event: unknown, value: number | null) => callback(value);
+		ipcRenderer.on("countdown-overlay-value", listener);
+		return () => ipcRenderer.removeListener("countdown-overlay-value", listener);
+	},
+	onRequestSaveBeforeClose: (callback: () => Promise<boolean> | boolean) => {
+		const listener = async () => {
+			try {
+				const shouldClose = await callback();
+				ipcRenderer.send("save-before-close-done", shouldClose);
+			} catch {
+				ipcRenderer.send("save-before-close-done", false);
+			}
+		};
+		ipcRenderer.on("request-save-before-close", listener);
+		return () => ipcRenderer.removeListener("request-save-before-close", listener);
+	},
+	onRequestCloseConfirm: (callback: () => void) => {
+		const listener = () => callback();
+		ipcRenderer.on("request-close-confirm", listener);
+		return () => ipcRenderer.removeListener("request-close-confirm", listener);
+	},
+	sendCloseConfirmResponse: (choice: "save" | "discard" | "cancel") => {
+		ipcRenderer.send("close-confirm-response", choice);
+	},
+});

electron/windows.ts

@@ -1,151 +1,263 @@
-import { BrowserWindow, screen } from 'electron'
-import { ipcMain } from 'electron'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { BrowserWindow, ipcMain, screen } from "electron";
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-const APP_ROOT = path.join(__dirname, '..')
-const VITE_DEV_SERVER_URL = process.env['VITE_DEV_SERVER_URL']
-const RENDERER_DIST = path.join(APP_ROOT, 'dist')
+const APP_ROOT = path.join(__dirname, "..");
+const VITE_DEV_SERVER_URL = process.env["VITE_DEV_SERVER_URL"];
+const RENDERER_DIST = path.join(APP_ROOT, "dist");
+const HEADLESS = process.env["HEADLESS"] === "true";
+
+// Asset base URL for renderer (wallpapers, etc.). Packaged: extraResources copies
+// public/wallpapers -> resources/wallpapers. Unpackaged: <appRoot>/public/.
+const ASSET_BASE_DIR = process.defaultApp
+	? path.join(__dirname, "..", "public")
+	: process.resourcesPath;
+const ASSET_BASE_URL_ARG = `--asset-base-url=${pathToFileURL(`${ASSET_BASE_DIR}${path.sep}`).toString()}`;
 
 let hudOverlayWindow: BrowserWindow | null = null;
 
-ipcMain.on('hud-overlay-hide', () => {
-  if (hudOverlayWindow && !hudOverlayWindow.isDestroyed()) {
-    hudOverlayWindow.minimize();
-  }
+ipcMain.on("hud-overlay-hide", () => {
+	if (hudOverlayWindow && !hudOverlayWindow.isDestroyed()) {
+		hudOverlayWindow.minimize();
+	}
 });
 
+ipcMain.on("hud-overlay-ignore-mouse-events", (_event, ignore: boolean) => {
+	if (hudOverlayWindow && !hudOverlayWindow.isDestroyed()) {
+		hudOverlayWindow.setIgnoreMouseEvents(ignore, { forward: true });
+	}
+});
+
+ipcMain.on("hud-overlay-move-by", (_event, deltaX: number, deltaY: number) => {
+	if (
+		!hudOverlayWindow ||
+		hudOverlayWindow.isDestroyed() ||
+		!Number.isFinite(deltaX) ||
+		!Number.isFinite(deltaY)
+	) {
+		return;
+	}
+
+	const [x, y] = hudOverlayWindow.getPosition();
+	hudOverlayWindow.setPosition(Math.round(x + deltaX), Math.round(y + deltaY), false);
+});
+
+/**
+ * Creates the always-on-top HUD overlay window centred at the bottom of the
+ * primary display. The window is frameless, transparent, and follows the user
+ * across macOS Spaces so it is never lost when switching virtual desktops.
+ */
 export function createHudOverlayWindow(): BrowserWindow {
-  const primaryDisplay = screen.getPrimaryDisplay();
-  const { workArea } = primaryDisplay;
+	const primaryDisplay = screen.getPrimaryDisplay();
+	const { workArea } = primaryDisplay;
 
+	const windowWidth = 600;
+	const windowHeight = 160;
 
-  const windowWidth = 500;
-  const windowHeight = 100;
+	const x = Math.floor(workArea.x + (workArea.width - windowWidth) / 2);
+	const y = Math.floor(workArea.y + workArea.height - windowHeight - 5);
 
-  const x = Math.floor(workArea.x + (workArea.width - windowWidth) / 2);
-  const y = Math.floor(workArea.y + workArea.height - windowHeight - 5);
+	const win = new BrowserWindow({
+		width: windowWidth,
+		height: windowHeight,
+		minWidth: 600,
+		maxWidth: 600,
+		minHeight: 160,
+		maxHeight: 160,
+		x: x,
+		y: y,
+		frame: false,
+		transparent: true,
+		resizable: false,
+		alwaysOnTop: true,
+		skipTaskbar: true,
+		hasShadow: false,
+		show: !HEADLESS,
+		webPreferences: {
+			preload: path.join(__dirname, "preload.mjs"),
+			additionalArguments: [ASSET_BASE_URL_ARG],
+			nodeIntegration: false,
+			contextIsolation: true,
+			backgroundThrottling: false,
+		},
+	});
+	win.setIgnoreMouseEvents(true, { forward: true });
 
-  const win = new BrowserWindow({
-    width: windowWidth,
-    height: windowHeight,
-    minWidth: 500,
-    maxWidth: 500,
-    minHeight: 100,
-    maxHeight: 100,
-    x: x,
-    y: y,
-    frame: false,
-    transparent: true,
-    resizable: false,
-    alwaysOnTop: true,
-    skipTaskbar: true,
-    hasShadow: false,
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.mjs'),
-      nodeIntegration: false,
-      contextIsolation: true,
-      backgroundThrottling: false,
-    },
-  })
+	// Follow the user across macOS Spaces (virtual desktops).
+	// Without this the HUD stays pinned to the Space it was first opened on.
+	if (process.platform === "darwin") {
+		win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+	}
 
+	win.webContents.on("did-finish-load", () => {
+		win?.webContents.send("main-process-message", new Date().toLocaleString());
+	});
 
-  win.webContents.on('did-finish-load', () => {
-    win?.webContents.send('main-process-message', (new Date).toLocaleString())
-  })
+	hudOverlayWindow = win;
 
-  hudOverlayWindow = win;
+	win.on("closed", () => {
+		if (hudOverlayWindow === win) {
+			hudOverlayWindow = null;
+		}
+	});
 
-  win.on('closed', () => {
-    if (hudOverlayWindow === win) {
-      hudOverlayWindow = null;
-    }
-  });
+	if (VITE_DEV_SERVER_URL) {
+		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=hud-overlay");
+	} else {
+		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
+			query: { windowType: "hud-overlay" },
+		});
+	}
 
-
-  if (VITE_DEV_SERVER_URL) {
-    win.loadURL(VITE_DEV_SERVER_URL + '?windowType=hud-overlay')
-  } else {
-    win.loadFile(path.join(RENDERER_DIST, 'index.html'), { 
-      query: { windowType: 'hud-overlay' } 
-    })
-  }
-
-  return win
+	return win;
 }
 
+/**
+ * Creates the main editor window. Starts maximised with a hidden title bar on
+ * macOS. This window is not always-on-top and appears in the taskbar/dock.
+ */
 export function createEditorWindow(): BrowserWindow {
-  const win = new BrowserWindow({
-    width: 1200,
-    height: 800,
-    minWidth: 800,
-    minHeight: 600,
-    titleBarStyle: 'hiddenInset',
-    trafficLightPosition: { x: 12, y: 12 },
-    transparent: false,
-    resizable: true,
-    alwaysOnTop: false,
-    skipTaskbar: false,
-    title: 'OpenScreen',
-    backgroundColor: '#000000',
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.mjs'),
-      nodeIntegration: false,
-      contextIsolation: true,
-      webSecurity: false,
-      backgroundThrottling: false,
-    },
-  })
+	const isMac = process.platform === "darwin";
 
-  // Maximize the window by default
-  win.maximize();
+	const win = new BrowserWindow({
+		width: 1200,
+		height: 800,
+		minWidth: 800,
+		minHeight: 600,
+		...(isMac && {
+			titleBarStyle: "hiddenInset",
+			trafficLightPosition: { x: 12, y: 12 },
+		}),
+		transparent: false,
+		resizable: true,
+		alwaysOnTop: false,
+		skipTaskbar: false,
+		title: "OpenScreen",
+		backgroundColor: "#000000",
+		show: !HEADLESS,
+		webPreferences: {
+			preload: path.join(__dirname, "preload.mjs"),
+			additionalArguments: [ASSET_BASE_URL_ARG],
+			nodeIntegration: false,
+			contextIsolation: true,
+			webSecurity: false,
+			backgroundThrottling: false,
+		},
+	});
 
-  win.webContents.on('did-finish-load', () => {
-    win?.webContents.send('main-process-message', (new Date).toLocaleString())
-  })
+	// Maximize the window by default
+	win.maximize();
 
-  if (VITE_DEV_SERVER_URL) {
-    win.loadURL(VITE_DEV_SERVER_URL + '?windowType=editor')
-  } else {
-    win.loadFile(path.join(RENDERER_DIST, 'index.html'), { 
-      query: { windowType: 'editor' } 
-    })
-  }
+	win.webContents.on("did-finish-load", () => {
+		win?.webContents.send("main-process-message", new Date().toLocaleString());
+	});
 
-  return win
+	if (VITE_DEV_SERVER_URL) {
+		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=editor");
+	} else {
+		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
+			query: { windowType: "editor" },
+		});
+	}
+
+	return win;
 }
 
+/**
+ * Creates the floating source-selector window used to pick a screen or window
+ * to record. Frameless, transparent, and follows the user across macOS Spaces.
+ */
 export function createSourceSelectorWindow(): BrowserWindow {
-  const { width, height } = screen.getPrimaryDisplay().workAreaSize
-  
-  const win = new BrowserWindow({
-    width: 620,
-    height: 420,
-    minHeight: 350,
-    maxHeight: 500,
-    x: Math.round((width - 620) / 2),
-    y: Math.round((height - 420) / 2),
-    frame: false,
-    resizable: false,
-    alwaysOnTop: true,
-    transparent: true,
-    backgroundColor: '#00000000',
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.mjs'),
-      nodeIntegration: false,
-      contextIsolation: true,
-    },
-  })
+	const { width, height } = screen.getPrimaryDisplay().workAreaSize;
 
-  if (VITE_DEV_SERVER_URL) {
-    win.loadURL(VITE_DEV_SERVER_URL + '?windowType=source-selector')
-  } else {
-    win.loadFile(path.join(RENDERER_DIST, 'index.html'), { 
-      query: { windowType: 'source-selector' } 
-    })
-  }
+	const win = new BrowserWindow({
+		width: 620,
+		height: 420,
+		minHeight: 350,
+		maxHeight: 500,
+		x: Math.round((width - 620) / 2),
+		y: Math.round((height - 420) / 2),
+		frame: false,
+		resizable: false,
+		alwaysOnTop: true,
+		transparent: true,
+		backgroundColor: "#00000000",
+		webPreferences: {
+			preload: path.join(__dirname, "preload.mjs"),
+			additionalArguments: [ASSET_BASE_URL_ARG],
+			nodeIntegration: false,
+			contextIsolation: true,
+		},
+	});
 
-  return win
+	// Follow the user across macOS Spaces so the selector appears on the
+	// active desktop regardless of where the HUD was originally opened.
+	if (process.platform === "darwin") {
+		win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+	}
+
+	if (VITE_DEV_SERVER_URL) {
+		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=source-selector");
+	} else {
+		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
+			query: { windowType: "source-selector" },
+		});
+	}
+
+	return win;
+}
+
+/**
+ * Creates a centered transparent countdown overlay window that sits above the
+ * HUD while recording pre-roll is running.
+ */
+export function createCountdownOverlayWindow(): BrowserWindow {
+	const { workArea } = screen.getPrimaryDisplay();
+	const overlayWidth = 420;
+	const overlayHeight = 260;
+
+	const win = new BrowserWindow({
+		width: overlayWidth,
+		height: overlayHeight,
+		minWidth: overlayWidth,
+		maxWidth: overlayWidth,
+		minHeight: overlayHeight,
+		maxHeight: overlayHeight,
+		x: Math.round(workArea.x + (workArea.width - overlayWidth) / 2),
+		y: Math.round(workArea.y + (workArea.height - overlayHeight) / 2),
+		frame: false,
+		resizable: false,
+		alwaysOnTop: true,
+		skipTaskbar: true,
+		focusable: false,
+		transparent: true,
+		backgroundColor: "#00000000",
+		hasShadow: false,
+		show: false,
+		webPreferences: {
+			preload: path.join(__dirname, "preload.mjs"),
+			additionalArguments: [ASSET_BASE_URL_ARG],
+			nodeIntegration: false,
+			contextIsolation: true,
+			backgroundThrottling: false,
+		},
+	});
+
+	win.setIgnoreMouseEvents(true);
+
+	if (process.platform === "darwin") {
+		win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+	}
+
+	if (VITE_DEV_SERVER_URL) {
+		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=countdown-overlay");
+	} else {
+		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
+			query: { windowType: "countdown-overlay" },
+		});
+	}
+
+	return win;
 }

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1775710090,
+        "narHash": "sha256-ar3rofg+awPB8QXDaFJhJ2jJhu+KqN/PRCXeyuXR76E=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "4c1018dae018162ec878d42fec712642d214fdfa",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,122 @@
+{
+  description = "OpenScreen — desktop screen recorder with built-in editor";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs =
+    { self, nixpkgs }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+      ];
+      forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f nixpkgs.legacyPackages.${system});
+    in
+    {
+      # -- Per-system outputs (packages, dev shells) --
+
+      packages = forAllSystems (pkgs: {
+        openscreen = pkgs.callPackage ./nix/package.nix { };
+        default = self.packages.${pkgs.stdenv.hostPlatform.system}.openscreen;
+      });
+
+      devShells = forAllSystems (
+        pkgs:
+        let
+          electron = pkgs.electron;
+
+          # Libraries Electron needs at runtime on Linux
+          runtimeLibs = with pkgs; [
+            # X11
+            libx11
+            libxcomposite
+            libxdamage
+            libxext
+            libxfixes
+            libxrandr
+            libxtst
+            libxcb
+            libxshmfence
+
+            # Wayland
+            wayland
+
+            # GTK / UI toolkit
+            gtk3
+            glib
+            pango
+            cairo
+            gdk-pixbuf
+            atk
+            at-spi2-atk
+            at-spi2-core
+
+            # Graphics
+            mesa
+            libGL
+            libdrm
+            vulkan-loader
+
+            # Networking / crypto (NSS for Chromium)
+            nss
+            nspr
+
+            # Audio
+            alsa-lib
+            pipewire
+            pulseaudio
+
+            # System
+            dbus
+            cups
+            expat
+            libnotify
+            libsecret
+            util-linux # libuuid
+          ];
+        in
+        {
+          default = pkgs.mkShell {
+            packages = with pkgs; [
+              nodejs_22
+              electron
+
+              # Native module compilation
+              python3
+              pkg-config
+              gcc
+
+              # Playwright browser tests
+              playwright-driver.browsers
+            ];
+
+            # Electron's prebuilt binary needs these at runtime
+            LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath runtimeLibs;
+
+            # Tell the npm `electron` package to use the Nix-provided binary
+            # instead of downloading its own. vite-plugin-electron respects this.
+            ELECTRON_OVERRIDE_DIST_PATH = "${electron}/libexec/electron";
+
+            # Playwright browser path for test:browser / test:e2e
+            PLAYWRIGHT_BROWSERS_PATH = "${pkgs.playwright-driver.browsers}";
+            PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = "1";
+
+            shellHook = ''
+              echo "OpenScreen dev shell — node $(node --version), electron v$(electron --version 2>/dev/null | tr -d 'v')"
+            '';
+          };
+        }
+      );
+
+      # -- System-wide outputs (modules, overlay) --
+
+      overlays.default = final: _prev: {
+        openscreen = self.packages.${final.stdenv.hostPlatform.system}.openscreen;
+      };
+
+      nixosModules.default = import ./nix/module.nix self;
+      homeManagerModules.default = import ./nix/hm-module.nix self;
+    };
+}

macos.entitlements

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- Required for Electron's V8 JIT compilation -->
+    <key>com.apple.security.cs.allow-jit</key>
+    <true/>
+
+    <!-- Required for Electron's native module loading -->
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+
+    <!-- Required for loading Electron's bundled frameworks/dylibs -->
+    <key>com.apple.security.cs.disable-library-validation</key>
+    <true/>
+
+    <!-- Audio input (microphone / system audio capture) -->
+    <key>com.apple.security.device.audio-input</key>
+    <true/>
+
+    <!-- Camera (webcam capture) -->
+    <key>com.apple.security.device.camera</key>
+    <true/>
+
+    <!-- Screen recording (required for desktopCapturer.getSources() on macOS 10.15+) -->
+    <key>com.apple.security.device.screen-capture</key>
+    <true/>
+</dict>
+</plist>

nix/hm-module.nix

@@ -0,0 +1,36 @@
+# Home Manager module for OpenScreen
+# Usage in flake-based Home Manager config:
+#
+#   inputs.openscreen.url = "github:siddharthvaddem/openscreen";
+#
+#   { inputs, ... }: {
+#     imports = [ inputs.openscreen.homeManagerModules.default ];
+#     programs.openscreen.enable = true;
+#   }
+self:
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+let
+  cfg = config.programs.openscreen;
+in
+{
+  options.programs.openscreen = {
+    enable = lib.mkEnableOption "OpenScreen screen recorder";
+
+    package = lib.mkOption {
+      type = lib.types.package;
+      default = self.packages.${pkgs.stdenv.hostPlatform.system}.openscreen;
+      defaultText = lib.literalExpression "inputs.openscreen.packages.\${pkgs.stdenv.hostPlatform.system}.openscreen";
+      description = "The OpenScreen package to use.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    home.packages = [ cfg.package ];
+  };
+}

nix/module.nix

@@ -0,0 +1,42 @@
+# NixOS module for OpenScreen
+# Usage in flake-based NixOS config:
+#
+#   inputs.openscreen.url = "github:siddharthvaddem/openscreen";
+#
+#   { inputs, ... }: {
+#     imports = [ inputs.openscreen.nixosModules.default ];
+#     programs.openscreen.enable = true;
+#   }
+self:
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+let
+  cfg = config.programs.openscreen;
+in
+{
+  options.programs.openscreen = {
+    enable = lib.mkEnableOption "OpenScreen screen recorder";
+
+    package = lib.mkOption {
+      type = lib.types.package;
+      default = self.packages.${pkgs.stdenv.hostPlatform.system}.openscreen;
+      defaultText = lib.literalExpression "inputs.openscreen.packages.\${pkgs.stdenv.hostPlatform.system}.openscreen";
+      description = "The OpenScreen package to use.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    environment.systemPackages = [ cfg.package ];
+
+    # Screen capture on Wayland requires xdg-desktop-portal.
+    # We enable the base portal; users should also enable a
+    # desktop-specific portal (e.g. xdg-desktop-portal-gtk,
+    # xdg-desktop-portal-hyprland) in their DE config.
+    xdg.portal.enable = lib.mkDefault true;
+  };
+}

nix/package.nix

@@ -0,0 +1,124 @@
+{
+  lib,
+  buildNpmPackage,
+  nodejs_22,
+  electron,
+  makeWrapper,
+  makeDesktopItem,
+  copyDesktopItems,
+}:
+
+buildNpmPackage {
+  nodejs = nodejs_22;
+  pname = "openscreen";
+  version = "1.4.0";
+
+  src =
+    let
+      fs = lib.fileset;
+      # gitTracked fails when source is already a store path (path: flake inputs).
+      # Detect this and fall back to cleanSource which handles both cases.
+      isStorePath = builtins.storeDir == builtins.substring 0 (builtins.stringLength builtins.storeDir) (toString ../.);
+      baseFiles = if isStorePath then fs.fromSource (lib.cleanSource ../.) else fs.gitTracked ../.;
+    in
+    fs.toSource {
+      root = ../.;
+      fileset = fs.difference baseFiles (
+        fs.unions [
+          ../nix
+          ../flake.nix
+          ../flake.lock
+          (fs.fileFilter (file: file.hasExt "md") ../.)
+        ]
+      );
+    };
+
+  npmDepsHash = "sha256-tOpoJPzaZDK3HJijGHpZ0+jWsbrYyQUuw1pO0Uxcifg=";
+
+  env.ELECTRON_SKIP_BINARY_DOWNLOAD = "1";
+
+  # electron-builder is not needed — we wrap system electron directly
+  npmFlags = [ "--ignore-scripts" ];
+  makeCacheWritable = true;
+
+  # vite-plugin-electron compiles electron/ sources into dist-electron/
+  # tsconfig has noEmit — tsc is type-check only
+  buildPhase = ''
+    runHook preBuild
+    npx vite build
+    runHook postBuild
+  '';
+
+  installPhase = ''
+    runHook preInstall
+
+    mkdir -p "$out/lib/openscreen"
+
+    # Renderer build output (index.html, JS chunks, copied public/ assets)
+    cp -r dist "$out/lib/openscreen/"
+
+    # Main process + preload (compiled by vite-plugin-electron)
+    cp -r dist-electron "$out/lib/openscreen/"
+
+    # Package manifest (electron reads "main" field to find entry point)
+    cp package.json "$out/lib/openscreen/"
+
+    # Strip devDependencies (electron, vitest, biome, playwright, etc.)
+    npm prune --omit=dev --no-save
+    cp -r node_modules "$out/lib/openscreen/"
+
+    # Asset resolution: when app.isPackaged is false, the main process resolves
+    # assets at <appPath>/public/. Place wallpapers at that root to match the
+    # packaged layout (electron-builder extraResources -> resources/wallpapers).
+    mkdir -p "$out/lib/openscreen/public"
+    cp -r public/wallpapers "$out/lib/openscreen/public/wallpapers"
+
+    # Wrap system electron with the app directory
+    mkdir -p "$out/bin"
+    makeWrapper "${electron}/bin/electron" "$out/bin/openscreen" \
+      --add-flags "$out/lib/openscreen" \
+      --set ELECTRON_IS_DEV 0
+
+    # Install icons to hicolor theme
+    for size in 16 24 32 48 64 128 256 512 1024; do
+      icon="icons/icons/png/''${size}x''${size}.png"
+      if [ -f "$icon" ]; then
+        install -Dm644 "$icon" \
+          "$out/share/icons/hicolor/''${size}x''${size}/apps/openscreen.png"
+      fi
+    done
+
+    runHook postInstall
+  '';
+
+  nativeBuildInputs = [
+    makeWrapper
+    copyDesktopItems
+  ];
+
+  desktopItems = [
+    (makeDesktopItem {
+      name = "openscreen";
+      desktopName = "OpenScreen";
+      genericName = "Screen Recorder";
+      exec = "openscreen %U";
+      icon = "openscreen";
+      comment = "Desktop screen recorder with built-in editor";
+      categories = [
+        "AudioVideo"
+        "Video"
+        "Recorder"
+      ];
+      startupWMClass = "Openscreen";
+      terminal = false;
+    })
+  ];
+
+  meta = {
+    description = "Desktop screen recorder with built-in editor";
+    homepage = "https://github.com/siddharthvaddem/openscreen";
+    license = lib.licenses.mit;
+    mainProgram = "openscreen";
+    platforms = lib.platforms.linux;
+  };
+}

package.json

@@ -1,65 +1,124 @@
 {
-  "name": "openscreen",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build && electron-builder",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
-    "preview": "vite preview",
-    "build:mac": "tsc && vite build && electron-builder --mac",
-    "build:win": "tsc && vite build && electron-builder --win"
-  },
-  "dependencies": {
-    "@fix-webm-duration/fix": "^1.0.1",
-    "@pixi/filter-drop-shadow": "^5.2.0",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-slider": "^1.3.6",
-    "@radix-ui/react-slot": "^1.2.3",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@uiw/color-convert": "^2.9.2",
-    "@uiw/react-color-colorful": "^2.9.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "dnd-timeline": "^2.2.0",
-    "lucide-react": "^0.545.0",
-    "mediabunny": "^1.25.1",
-    "mp4box": "^2.2.0",
-    "pixi.js": "^8.14.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "react-icons": "^5.5.0",
-    "react-resizable-panels": "^3.0.6",
-    "sonner": "^2.0.7",
-    "tailwind-merge": "^3.3.1",
-    "tailwindcss-animate": "^1.0.7",
-    "uuid": "^13.0.0"
-  },
-  "devDependencies": {
-    "@types/react": "^18.2.64",
-    "@types/react-dom": "^18.2.21",
-    "@types/uuid": "^10.0.0",
-    "@typescript-eslint/eslint-plugin": "^7.1.1",
-    "@typescript-eslint/parser": "^7.1.1",
-    "@vitejs/plugin-react": "^4.2.1",
-    "autoprefixer": "^10.4.21",
-    "electron": "^30.0.1",
-    "electron-builder": "^24.13.3",
-    "electron-icon-builder": "^2.0.1",
-    "electron-rebuild": "^3.2.9",
-    "eslint": "^8.57.0",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-react-refresh": "^0.4.5",
-    "postcss": "^8.5.6",
-    "tailwindcss": "^3.4.18",
-    "terser": "^5.44.1",
-    "typescript": "^5.2.2",
-    "vite": "^5.1.6",
-    "vite-plugin-electron": "^0.28.6",
-    "vite-plugin-electron-renderer": "^0.14.5"
-  },
-  "main": "dist-electron/main.js"
+	"name": "openscreen",
+	"private": true,
+	"version": "1.4.0",
+	"type": "module",
+	"packageManager": "npm@10.9.4",
+	"engines": {
+		"node": "22.22.1",
+		"npm": "10.9.4"
+	},
+	"author": {
+		"name": "Sid",
+		"email": "svaddem@asu.edu"
+	},
+	"scripts": {
+		"dev": "vite",
+		"build": "tsc && vite build && electron-builder",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"format": "biome format --write .",
+		"i18n:check": "node scripts/i18n-check.mjs",
+		"preview": "vite preview",
+		"build:native:mac": "node scripts/build-macos-screencapturekit-helper.mjs",
+		"build:mac": "npm run build:native:mac && tsc && vite build && electron-builder --mac",
+		"build:native:win": "node scripts/build-windows-wgc-helper.mjs",
+		"build:win": "npm run build:native:win && tsc && vite build && electron-builder --win --config.npmRebuild=false",
+		"build:linux": "tsc && vite build && electron-builder --linux AppImage deb pacman --config.npmRebuild=false",
+		"test": "vitest --run",
+		"test:watch": "vitest",
+		"test:cursor-native:win": "node scripts/test-windows-native-cursor.mjs",
+		"test:wgc-helper:win": "node scripts/test-windows-wgc-helper.mjs",
+		"test:wgc-window:win": "node scripts/test-windows-wgc-helper.mjs --window",
+		"test:wgc-audio:win": "node scripts/test-windows-wgc-helper.mjs --system-audio",
+		"test:wgc-mic:win": "node scripts/test-windows-wgc-helper.mjs --microphone",
+		"test:wgc-mixed-audio:win": "node scripts/test-windows-wgc-helper.mjs --system-audio --microphone",
+		"test:wgc-webcam:win": "node scripts/test-windows-wgc-helper.mjs --webcam",
+		"test:wgc-full:win": "node scripts/test-windows-wgc-helper.mjs --webcam --system-audio --microphone",
+		"capture:openscreen-preview": "node scripts/capture-openscreen-preview.mjs",
+		"inspect:cursor-click-bounce": "node scripts/inspect-native-cursor-click-bounce.mjs",
+		"build-vite": "tsc && vite build",
+		"test:browser": "vitest --config vitest.browser.config.ts --run",
+		"test:browser:install": "playwright install --with-deps chromium-headless-shell",
+		"test:e2e": "playwright test",
+		"test:e2e:windows-native-checklist": "playwright test tests/e2e/windows-native-checklist.spec.ts",
+		"prepare": "husky"
+	},
+	"dependencies": {
+		"@fix-webm-duration/fix": "^1.0.1",
+		"@pixi/filter-drop-shadow": "^5.2.0",
+		"@radix-ui/react-accordion": "^1.2.12",
+		"@radix-ui/react-dialog": "^1.1.15",
+		"@radix-ui/react-dropdown-menu": "^2.1.16",
+		"@radix-ui/react-popover": "^1.1.15",
+		"@radix-ui/react-select": "^2.2.6",
+		"@radix-ui/react-slider": "^1.3.6",
+		"@radix-ui/react-slot": "^1.2.4",
+		"@radix-ui/react-switch": "^1.2.6",
+		"@radix-ui/react-tabs": "^1.1.13",
+		"@radix-ui/react-toggle": "^1.1.10",
+		"@radix-ui/react-toggle-group": "^1.1.11",
+		"@radix-ui/react-tooltip": "^1.2.8",
+		"@types/gif.js": "^0.2.5",
+		"@uiw/color-convert": "^2.10.1",
+		"@uiw/react-color-block": "^2.10.1",
+		"@uiw/react-color-colorful": "^2.9.2",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"dnd-timeline": "^2.4.0",
+		"emoji-picker-react": "^4.18.0",
+		"fix-webm-duration": "^1.0.6",
+		"gif.js": "^0.2.0",
+		"gsap": "^3.15.0",
+		"lucide-react": "^0.545.0",
+		"mediabunny": "^1.40.1",
+		"motion": "^12.38.0",
+		"mp4box": "^2.3.0",
+		"pixi-filters": "^6.1.5",
+		"pixi.js": "^8.18.1",
+		"react": "^18.3.1",
+		"react-dom": "^18.3.1",
+		"react-icons": "^5.6.0",
+		"react-resizable-panels": "^3.0.6",
+		"react-rnd": "^10.5.3",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.5.0",
+		"tailwindcss-animate": "^1.0.7",
+		"uuid": "^13.0.0",
+		"web-demuxer": "^4.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.12",
+		"@electron/rebuild": "^4.0.4",
+		"@playwright/test": "^1.59.1",
+		"@testing-library/jest-dom": "^6.9.1",
+		"@testing-library/react": "^16.3.2",
+		"@testing-library/user-event": "^14.6.1",
+		"@types/node": "^22.19.17",
+		"@types/react": "^18.3.28",
+		"@types/react-dom": "^18.3.7",
+		"@vitejs/plugin-react": "^5.2.0",
+		"@vitest/browser": "^4.1.4",
+		"@vitest/browser-playwright": "^4.1.4",
+		"autoprefixer": "^10.5.0",
+		"electron": "^41.2.1",
+		"electron-builder": "^26.8.1",
+		"esbuild": "^0.27.0",
+		"fast-check": "^4.7.0",
+		"husky": "^9.1.7",
+		"jsdom": "^29.0.2",
+		"lint-staged": "^16.4.0",
+		"postcss": "^8.5.10",
+		"tailwindcss": "^3.4.19",
+		"terser": "^5.46.1",
+		"typescript": "^5.9.3",
+		"vite": "^7.3.2",
+		"vite-plugin-electron": "^0.29.1",
+		"vite-plugin-electron-renderer": "^0.14.6",
+		"vitest": "^4.1.4"
+	},
+	"main": "dist-electron/main.js",
+	"lint-staged": {
+		"*.{ts,tsx,js,jsx,mts,cts,json}": "biome check --no-errors-on-unmatched"
+	}
 }

playwright.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+	testDir: "./tests/e2e",
+	timeout: 120_000, // GIF encoding is CPU-bound; give it room
+	retries: 0,
+	reporter: "list",
+});

pnpm-workspace.yaml

@@ -1,5 +0,0 @@
-onlyBuiltDependencies:
-  - electron
-  - esbuild
-  - lzma-native
-  - phantomjs-prebuilt

postcss.config.cjs

@@ -1,6 +1,6 @@
 module.exports = {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-}
+	plugins: {
+		tailwindcss: {},
+		autoprefixer: {},
+	},
+};

public/electron-vite.animate.svg

@@ -1,34 +0,0 @@
-<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M63.9202 127.84C99.2223 127.84 127.84 99.2223 127.84 63.9202C127.84 28.6181 99.2223 0 63.9202 0C28.6181 0 0 28.6181 0 63.9202C0 99.2223 28.6181 127.84 63.9202 127.84Z" fill="url(#paint0_linear_103_2)"/>
-<g id="not-lightning" clip-path="url(#clip0_103_2)">
-<animateTransform
-  attributeName="transform"
-  attributeType="XML"
-  type="rotate"
-  from="0 64 64"
-  to="360 64 64"
-  dur="20s"
-  repeatCount="indefinite"/>
-<path d="M51.3954 39.5028C52.3733 39.6812 53.3108 39.033 53.4892 38.055C53.6676 37.0771 53.0194 36.1396 52.0414 35.9612L51.3954 39.5028ZM28.9393 60.9358C29.4332 61.7985 30.5329 62.0976 31.3957 61.6037C32.2585 61.1098 32.5575 60.0101 32.0636 59.1473L28.9393 60.9358ZM37.6935 66.7457C37.025 66.01 35.8866 65.9554 35.1508 66.6239C34.415 67.2924 34.3605 68.4308 35.029 69.1666L37.6935 66.7457ZM96.9206 89.515C97.7416 88.9544 97.9526 87.8344 97.3919 87.0135C96.8313 86.1925 95.7113 85.9815 94.8904 86.5422L96.9206 89.515ZM52.0414 35.9612C46.4712 34.9451 41.2848 34.8966 36.9738 35.9376C32.6548 36.9806 29.0841 39.1576 27.0559 42.6762L30.1748 44.4741C31.5693 42.0549 34.1448 40.3243 37.8188 39.4371C41.5009 38.5479 46.1547 38.5468 51.3954 39.5028L52.0414 35.9612ZM27.0559 42.6762C24.043 47.9029 25.2781 54.5399 28.9393 60.9358L32.0636 59.1473C28.6579 53.1977 28.1088 48.0581 30.1748 44.4741L27.0559 42.6762ZM35.029 69.1666C39.6385 74.24 45.7158 79.1355 52.8478 83.2597L54.6499 80.1432C47.8081 76.1868 42.0298 71.5185 37.6935 66.7457L35.029 69.1666ZM52.8478 83.2597C61.344 88.1726 70.0465 91.2445 77.7351 92.3608C85.359 93.4677 92.2744 92.6881 96.9206 89.515L94.8904 86.5422C91.3255 88.9767 85.4902 89.849 78.2524 88.7982C71.0793 87.7567 62.809 84.8612 54.6499 80.1432L52.8478 83.2597ZM105.359 84.9077C105.359 81.4337 102.546 78.6127 99.071 78.6127V82.2127C100.553 82.2127 101.759 83.4166 101.759 84.9077H105.359ZM99.071 78.6127C95.5956 78.6127 92.7831 81.4337 92.7831 84.9077H96.3831C96.3831 83.4166 97.5892 82.2127 99.071 82.2127V78.6127ZM92.7831 84.9077C92.7831 88.3817 95.5956 91.2027 99.071 91.2027V87.6027C97.5892 87.6027 96.3831 86.3988 96.3831 84.9077H92.7831ZM99.071 91.2027C102.546 91.2027 105.359 88.3817 105.359 84.9077H101.759C101.759 86.3988 100.553 87.6027 99.071 87.6027V91.2027Z" fill="#A2ECFB"/>
-<path d="M91.4873 65.382C90.8456 66.1412 90.9409 67.2769 91.7002 67.9186C92.4594 68.5603 93.5951 68.465 94.2368 67.7058L91.4873 65.382ZM84.507 35.2412C83.513 35.2282 82.6967 36.0236 82.6838 37.0176C82.6708 38.0116 83.4661 38.8279 84.4602 38.8409L84.507 35.2412ZM74.9407 39.8801C75.9127 39.6716 76.5315 38.7145 76.323 37.7425C76.1144 36.7706 75.1573 36.1517 74.1854 36.3603L74.9407 39.8801ZM25.5491 80.9047C25.6932 81.8883 26.6074 82.5688 27.5911 82.4247C28.5747 82.2806 29.2552 81.3664 29.1111 80.3828L25.5491 80.9047ZM94.2368 67.7058C97.8838 63.3907 100.505 58.927 101.752 54.678C103.001 50.4213 102.9 46.2472 100.876 42.7365L97.7574 44.5344C99.1494 46.9491 99.3603 50.0419 98.2974 53.6644C97.2323 57.2945 94.9184 61.3223 91.4873 65.382L94.2368 67.7058ZM100.876 42.7365C97.9119 37.5938 91.7082 35.335 84.507 35.2412L84.4602 38.8409C91.1328 38.9278 95.7262 41.0106 97.7574 44.5344L100.876 42.7365ZM74.1854 36.3603C67.4362 37.8086 60.0878 40.648 52.8826 44.8146L54.6847 47.931C61.5972 43.9338 68.5948 41.2419 74.9407 39.8801L74.1854 36.3603ZM52.8826 44.8146C44.1366 49.872 36.9669 56.0954 32.1491 62.3927C27.3774 68.63 24.7148 75.2115 25.5491 80.9047L29.1111 80.3828C28.4839 76.1026 30.4747 70.5062 35.0084 64.5802C39.496 58.7143 46.2839 52.7889 54.6847 47.931L52.8826 44.8146Z" fill="#A2ECFB"/>
-<path d="M49.0825 87.2295C48.7478 86.2934 47.7176 85.8059 46.7816 86.1406C45.8455 86.4753 45.358 87.5055 45.6927 88.4416L49.0825 87.2295ZM78.5635 96.4256C79.075 95.5732 78.7988 94.4675 77.9464 93.9559C77.0941 93.4443 75.9884 93.7205 75.4768 94.5729L78.5635 96.4256ZM79.5703 85.1795C79.2738 86.1284 79.8027 87.1379 80.7516 87.4344C81.7004 87.7308 82.71 87.2019 83.0064 86.2531L79.5703 85.1795ZM69.156 22.5301C68.2477 22.1261 67.1838 22.535 66.7799 23.4433C66.3759 24.3517 66.7848 25.4155 67.6931 25.8194L69.156 22.5301ZM45.6927 88.4416C47.5994 93.7741 50.1496 98.2905 53.2032 101.505C56.2623 104.724 59.9279 106.731 63.9835 106.731V103.131C61.1984 103.131 58.4165 101.765 55.8131 99.0249C53.2042 96.279 50.8768 92.2477 49.0825 87.2295L45.6927 88.4416ZM63.9835 106.731C69.8694 106.731 74.8921 102.542 78.5635 96.4256L75.4768 94.5729C72.0781 100.235 68.0122 103.131 63.9835 103.131V106.731ZM83.0064 86.2531C85.0269 79.7864 86.1832 72.1831 86.1832 64.0673H82.5832C82.5832 71.8536 81.4723 79.0919 79.5703 85.1795L83.0064 86.2531ZM86.1832 64.0673C86.1832 54.1144 84.4439 44.922 81.4961 37.6502C78.5748 30.4436 74.3436 24.8371 69.156 22.5301L67.6931 25.8194C71.6364 27.5731 75.3846 32.1564 78.1598 39.0026C80.9086 45.7836 82.5832 54.507 82.5832 64.0673H86.1832Z" fill="#A2ECFB"/>
-<path fill-rule="evenodd" clip-rule="evenodd" d="M103.559 84.9077C103.559 82.4252 101.55 80.4127 99.071 80.4127C96.5924 80.4127 94.5831 82.4252 94.5831 84.9077C94.5831 87.3902 96.5924 89.4027 99.071 89.4027C101.55 89.4027 103.559 87.3902 103.559 84.9077Z" stroke="#A2ECFB" stroke-width="3.6" stroke-linecap="round"/>
-<path fill-rule="evenodd" clip-rule="evenodd" d="M28.8143 89.4027C31.2929 89.4027 33.3023 87.3902 33.3023 84.9077C33.3023 82.4252 31.2929 80.4127 28.8143 80.4127C26.3357 80.4127 24.3264 82.4252 24.3264 84.9077C24.3264 87.3902 26.3357 89.4027 28.8143 89.4027Z" stroke="#A2ECFB" stroke-width="3.6" stroke-linecap="round"/>
-<path d="M63.9835 27.6986C66.4621 27.6986 68.4714 25.6861 68.4714 23.2036C68.4714 20.7211 66.4621 18.7086 63.9835 18.7086C61.5049 18.7086 59.4956 20.7211 59.4956 23.2036C59.4956 25.6861 61.5049 27.6986 63.9835 27.6986Z" stroke="#A2ECFB" stroke-width="3.6" stroke-linecap="round"/>
-</g>
-<path d="M70.7175 48.0096L56.3133 50.676C56.0766 50.7199 55.9013 50.9094 55.887 51.1369L55.001 65.2742C54.9801 65.6072 55.3038 65.8656 55.6478 65.7907L59.6582 64.9163C60.0334 64.8346 60.3724 65.1468 60.2953 65.5033L59.1038 71.0151C59.0237 71.386 59.3923 71.7032 59.7758 71.5932L62.2528 70.8822C62.6368 70.7721 63.0057 71.0902 62.9245 71.4615L61.031 80.1193C60.9126 80.6608 61.6751 80.9561 61.9931 80.4918L62.2055 80.1817L73.9428 58.053C74.1393 57.6825 73.8004 57.26 73.3696 57.3385L69.2417 58.0912C68.8538 58.1618 68.5237 57.8206 68.6332 57.462L71.3274 48.6385C71.437 48.2794 71.1058 47.9378 70.7175 48.0096Z" fill="url(#paint1_linear_103_2)"/>
-<defs>
-<linearGradient id="paint0_linear_103_2" x1="1.43824" y1="7.91009" x2="56.3296" y2="82.4569" gradientUnits="userSpaceOnUse">
-<stop stop-color="#41D1FF"/>
-<stop offset="1" stop-color="#BD34FE"/>
-</linearGradient>
-<linearGradient id="paint1_linear_103_2" x1="60.3173" y1="48.7336" x2="64.237" y2="77.1962" gradientUnits="userSpaceOnUse">
-<stop stop-color="#FFEA83"/>
-<stop offset="0.0833333" stop-color="#FFDD35"/>
-<stop offset="1" stop-color="#FFA800"/>
-</linearGradient>
-<clipPath id="clip0_103_2">
-<rect width="128" height="128" fill="white"/>
-</clipPath>
-</defs>
-</svg>

public/electron-vite.svg

@@ -1,26 +0,0 @@
-<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg">
-<g clip-path="url(#clip0_103_2)">
-<path d="M63.9202 127.84C99.2223 127.84 127.84 99.2223 127.84 63.9202C127.84 28.6181 99.2223 0 63.9202 0C28.6181 0 0 28.6181 0 63.9202C0 99.2223 28.6181 127.84 63.9202 127.84Z" fill="url(#paint0_linear_103_2)"/>
-<path d="M51.3954 39.5028C52.3733 39.6812 53.3108 39.033 53.4892 38.055C53.6676 37.0771 53.0194 36.1396 52.0414 35.9612L51.3954 39.5028ZM28.9393 60.9358C29.4332 61.7985 30.5329 62.0976 31.3957 61.6037C32.2585 61.1098 32.5575 60.0101 32.0636 59.1473L28.9393 60.9358ZM37.6935 66.7457C37.025 66.01 35.8866 65.9554 35.1508 66.6239C34.415 67.2924 34.3605 68.4308 35.029 69.1666L37.6935 66.7457ZM96.9206 89.515C97.7416 88.9544 97.9526 87.8344 97.3919 87.0135C96.8313 86.1925 95.7113 85.9815 94.8904 86.5422L96.9206 89.515ZM52.0414 35.9612C46.4712 34.9451 41.2848 34.8966 36.9738 35.9376C32.6548 36.9806 29.0841 39.1576 27.0559 42.6762L30.1748 44.4741C31.5693 42.0549 34.1448 40.3243 37.8188 39.4371C41.5009 38.5479 46.1547 38.5468 51.3954 39.5028L52.0414 35.9612ZM27.0559 42.6762C24.043 47.9029 25.2781 54.5399 28.9393 60.9358L32.0636 59.1473C28.6579 53.1977 28.1088 48.0581 30.1748 44.4741L27.0559 42.6762ZM35.029 69.1666C39.6385 74.24 45.7158 79.1355 52.8478 83.2597L54.6499 80.1432C47.8081 76.1868 42.0298 71.5185 37.6935 66.7457L35.029 69.1666ZM52.8478 83.2597C61.344 88.1726 70.0465 91.2445 77.7351 92.3608C85.359 93.4677 92.2744 92.6881 96.9206 89.515L94.8904 86.5422C91.3255 88.9767 85.4902 89.849 78.2524 88.7982C71.0793 87.7567 62.809 84.8612 54.6499 80.1432L52.8478 83.2597ZM105.359 84.9077C105.359 81.4337 102.546 78.6127 99.071 78.6127V82.2127C100.553 82.2127 101.759 83.4166 101.759 84.9077H105.359ZM99.071 78.6127C95.5956 78.6127 92.7831 81.4337 92.7831 84.9077H96.3831C96.3831 83.4166 97.5892 82.2127 99.071 82.2127V78.6127ZM92.7831 84.9077C92.7831 88.3817 95.5956 91.2027 99.071 91.2027V87.6027C97.5892 87.6027 96.3831 86.3988 96.3831 84.9077H92.7831ZM99.071 91.2027C102.546 91.2027 105.359 88.3817 105.359 84.9077H101.759C101.759 86.3988 100.553 87.6027 99.071 87.6027V91.2027Z" fill="#A2ECFB"/>
-<path d="M91.4873 65.382C90.8456 66.1412 90.9409 67.2769 91.7002 67.9186C92.4594 68.5603 93.5951 68.465 94.2368 67.7058L91.4873 65.382ZM84.507 35.2412C83.513 35.2282 82.6967 36.0236 82.6838 37.0176C82.6708 38.0116 83.4661 38.8279 84.4602 38.8409L84.507 35.2412ZM74.9407 39.8801C75.9127 39.6716 76.5315 38.7145 76.323 37.7425C76.1144 36.7706 75.1573 36.1517 74.1854 36.3603L74.9407 39.8801ZM25.5491 80.9047C25.6932 81.8883 26.6074 82.5688 27.5911 82.4247C28.5747 82.2806 29.2552 81.3664 29.1111 80.3828L25.5491 80.9047ZM94.2368 67.7058C97.8838 63.3907 100.505 58.927 101.752 54.678C103.001 50.4213 102.9 46.2472 100.876 42.7365L97.7574 44.5344C99.1494 46.9491 99.3603 50.0419 98.2974 53.6644C97.2323 57.2945 94.9184 61.3223 91.4873 65.382L94.2368 67.7058ZM100.876 42.7365C97.9119 37.5938 91.7082 35.335 84.507 35.2412L84.4602 38.8409C91.1328 38.9278 95.7262 41.0106 97.7574 44.5344L100.876 42.7365ZM74.1854 36.3603C67.4362 37.8086 60.0878 40.648 52.8826 44.8146L54.6847 47.931C61.5972 43.9338 68.5948 41.2419 74.9407 39.8801L74.1854 36.3603ZM52.8826 44.8146C44.1366 49.872 36.9669 56.0954 32.1491 62.3927C27.3774 68.63 24.7148 75.2115 25.5491 80.9047L29.1111 80.3828C28.4839 76.1026 30.4747 70.5062 35.0084 64.5802C39.496 58.7143 46.2839 52.7889 54.6847 47.931L52.8826 44.8146Z" fill="#A2ECFB"/>
-<path d="M49.0825 87.2295C48.7478 86.2934 47.7176 85.8059 46.7816 86.1406C45.8455 86.4753 45.358 87.5055 45.6927 88.4416L49.0825 87.2295ZM78.5635 96.4256C79.075 95.5732 78.7988 94.4675 77.9464 93.9559C77.0941 93.4443 75.9884 93.7205 75.4768 94.5729L78.5635 96.4256ZM79.5703 85.1795C79.2738 86.1284 79.8027 87.1379 80.7516 87.4344C81.7004 87.7308 82.71 87.2019 83.0064 86.2531L79.5703 85.1795ZM69.156 22.5301C68.2477 22.1261 67.1838 22.535 66.7799 23.4433C66.3759 24.3517 66.7848 25.4155 67.6931 25.8194L69.156 22.5301ZM45.6927 88.4416C47.5994 93.7741 50.1496 98.2905 53.2032 101.505C56.2623 104.724 59.9279 106.731 63.9835 106.731V103.131C61.1984 103.131 58.4165 101.765 55.8131 99.0249C53.2042 96.279 50.8768 92.2477 49.0825 87.2295L45.6927 88.4416ZM63.9835 106.731C69.8694 106.731 74.8921 102.542 78.5635 96.4256L75.4768 94.5729C72.0781 100.235 68.0122 103.131 63.9835 103.131V106.731ZM83.0064 86.2531C85.0269 79.7864 86.1832 72.1831 86.1832 64.0673H82.5832C82.5832 71.8536 81.4723 79.0919 79.5703 85.1795L83.0064 86.2531ZM86.1832 64.0673C86.1832 54.1144 84.4439 44.922 81.4961 37.6502C78.5748 30.4436 74.3436 24.8371 69.156 22.5301L67.6931 25.8194C71.6364 27.5731 75.3846 32.1564 78.1598 39.0026C80.9086 45.7836 82.5832 54.507 82.5832 64.0673H86.1832Z" fill="#A2ECFB"/>
-<path fill-rule="evenodd" clip-rule="evenodd" d="M103.559 84.9077C103.559 82.4252 101.55 80.4127 99.071 80.4127C96.5924 80.4127 94.5831 82.4252 94.5831 84.9077C94.5831 87.3902 96.5924 89.4027 99.071 89.4027C101.55 89.4027 103.559 87.3902 103.559 84.9077Z" stroke="#A2ECFB" stroke-width="3.6" stroke-linecap="round"/>
-<path fill-rule="evenodd" clip-rule="evenodd" d="M28.8143 89.4027C31.2929 89.4027 33.3023 87.3902 33.3023 84.9077C33.3023 82.4252 31.2929 80.4127 28.8143 80.4127C26.3357 80.4127 24.3264 82.4252 24.3264 84.9077C24.3264 87.3902 26.3357 89.4027 28.8143 89.4027Z" stroke="#A2ECFB" stroke-width="3.6" stroke-linecap="round"/>
-<path d="M63.9835 27.6986C66.4621 27.6986 68.4714 25.6861 68.4714 23.2036C68.4714 20.7211 66.4621 18.7086 63.9835 18.7086C61.5049 18.7086 59.4956 20.7211 59.4956 23.2036C59.4956 25.6861 61.5049 27.6986 63.9835 27.6986Z" stroke="#A2ECFB" stroke-width="3.6" stroke-linecap="round"/>
-<path d="M70.7175 48.0096L56.3133 50.676C56.0766 50.7199 55.9013 50.9094 55.887 51.1369L55.001 65.2742C54.9801 65.6072 55.3038 65.8656 55.6478 65.7907L59.6582 64.9163C60.0334 64.8346 60.3724 65.1468 60.2953 65.5033L59.1038 71.0151C59.0237 71.386 59.3923 71.7032 59.7758 71.5932L62.2528 70.8822C62.6368 70.7721 63.0057 71.0902 62.9245 71.4615L61.031 80.1193C60.9126 80.6608 61.6751 80.9561 61.9931 80.4918L62.2055 80.1817L73.9428 58.053C74.1393 57.6825 73.8004 57.26 73.3696 57.3385L69.2417 58.0912C68.8538 58.1618 68.5237 57.8206 68.6332 57.462L71.3274 48.6385C71.437 48.2794 71.1058 47.9378 70.7175 48.0096Z" fill="url(#paint1_linear_103_2)"/>
-</g>
-<defs>
-<linearGradient id="paint0_linear_103_2" x1="1.43824" y1="7.91009" x2="56.3296" y2="82.4569" gradientUnits="userSpaceOnUse">
-<stop stop-color="#41D1FF"/>
-<stop offset="1" stop-color="#BD34FE"/>
-</linearGradient>
-<linearGradient id="paint1_linear_103_2" x1="60.3173" y1="48.7336" x2="64.237" y2="77.1962" gradientUnits="userSpaceOnUse">
-<stop stop-color="#FFEA83"/>
-<stop offset="0.0833333" stop-color="#FFDD35"/>
-<stop offset="1" stop-color="#FFA800"/>
-</linearGradient>
-<clipPath id="clip0_103_2">
-<rect width="128" height="128" fill="white"/>
-</clipPath>
-</defs>
-</svg>

scripts/build-macos-screencapturekit-helper.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+if (process.platform !== "darwin") {
+	console.log("Skipping macOS ScreenCaptureKit helper build: host platform is not macOS.");
+	process.exit(0);
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, "..");
+const helperName = "openscreen-screencapturekit-helper";
+const cursorHelperName = "openscreen-macos-cursor-helper";
+const packageDir = path.join(root, "electron", "native", "screencapturekit");
+const buildDir = path.join(packageDir, "build");
+const swiftBuildDir = path.join(buildDir, "swiftpm");
+const builtHelperPath = path.join(swiftBuildDir, "release", helperName);
+const localHelperPath = path.join(buildDir, helperName);
+const builtCursorHelperPath = path.join(swiftBuildDir, "release", cursorHelperName);
+const localCursorHelperPath = path.join(buildDir, cursorHelperName);
+const archTag = process.arch === "arm64" ? "darwin-arm64" : "darwin-x64";
+const distributableDir = path.join(root, "electron", "native", "bin", archTag);
+const distributablePath = path.join(distributableDir, helperName);
+const distributableCursorHelperPath = path.join(distributableDir, cursorHelperName);
+
+const xcodebuildVersion = spawnSync("xcodebuild", ["-version"], {
+	cwd: root,
+	encoding: "utf8",
+});
+
+if (xcodebuildVersion.status !== 0) {
+	const message = `${xcodebuildVersion.stderr ?? ""}${xcodebuildVersion.stdout ?? ""}`.trim();
+	console.error(
+		[
+			"Unable to build the macOS ScreenCaptureKit helper because full Xcode is not active.",
+			"",
+			message,
+			"",
+			"Install Xcode from the App Store or Apple Developer downloads, then run:",
+			"  sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer",
+			"  sudo xcodebuild -license accept",
+			"",
+			"Command Line Tools alone may not include the Swift SDK/platform metadata required by SwiftPM.",
+		].join("\n"),
+	);
+	process.exit(1);
+}
+
+const result = spawnSync(
+	"swift",
+	["build", "-c", "release", "--package-path", packageDir, "--build-path", swiftBuildDir],
+	{
+		cwd: root,
+		stdio: "inherit",
+	},
+);
+
+if (result.error) {
+	console.error(`Failed to start Swift build: ${result.error.message}`);
+	process.exit(1);
+}
+
+if (result.status !== 0) {
+	process.exit(result.status ?? 1);
+}
+
+fs.mkdirSync(buildDir, { recursive: true });
+fs.mkdirSync(distributableDir, { recursive: true });
+for (const artifactPath of [builtHelperPath, builtCursorHelperPath]) {
+	if (!fs.existsSync(artifactPath)) {
+		console.error(`Swift build completed but expected artifact was not found: ${artifactPath}`);
+		process.exit(1);
+	}
+}
+fs.copyFileSync(builtHelperPath, localHelperPath);
+fs.copyFileSync(builtHelperPath, distributablePath);
+fs.copyFileSync(builtCursorHelperPath, localCursorHelperPath);
+fs.copyFileSync(builtCursorHelperPath, distributableCursorHelperPath);
+fs.chmodSync(localHelperPath, 0o755);
+fs.chmodSync(distributablePath, 0o755);
+fs.chmodSync(localCursorHelperPath, 0o755);
+fs.chmodSync(distributableCursorHelperPath, 0o755);
+
+console.log(`Built macOS ScreenCaptureKit helper: ${localHelperPath}`);
+console.log(`Copied redistributable helper: ${distributablePath}`);
+console.log(`Built macOS cursor helper: ${localCursorHelperPath}`);
+console.log(`Copied redistributable cursor helper: ${distributableCursorHelperPath}`);

scripts/build-windows-wgc-helper.mjs

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.join(__dirname, "..");
+const SOURCE_DIR = path.join(ROOT, "electron", "native", "wgc-capture");
+const BUILD_DIR = path.join(SOURCE_DIR, "build");
+const COMPAT_LIB_DIR = path.join(BUILD_DIR, "compat-libs");
+const BIN_DIR = path.join(ROOT, "electron", "native", "bin", "win32-x64");
+const CMAKE = process.env.CMAKE_EXE ?? "cmake";
+
+function findVcVarsAll() {
+	const explicit = process.env.VCVARSALL;
+	if (explicit && fs.existsSync(explicit)) {
+		return explicit;
+	}
+
+	const roots = [
+		process.env.VSINSTALLDIR,
+		"C:\\Program Files\\Microsoft Visual Studio\\2022\\Community",
+		"C:\\Program Files\\Microsoft Visual Studio\\2022\\Professional",
+		"C:\\Program Files\\Microsoft Visual Studio\\2022\\Enterprise",
+		"C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools",
+		"C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\Community",
+	];
+
+	for (const root of roots.filter(Boolean)) {
+		const candidate = path.join(root, "VC", "Auxiliary", "Build", "vcvarsall.bat");
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+
+	return null;
+}
+
+function run(command, args, options = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd: ROOT,
+			stdio: "inherit",
+			windowsHide: true,
+			...options,
+		});
+		child.once("error", reject);
+		child.once("exit", (code) => {
+			if (code === 0) {
+				resolve();
+			} else {
+				reject(new Error(`${command} ${args.join(" ")} failed with code ${code}`));
+			}
+		});
+	});
+}
+
+async function runInVsEnv(command) {
+	const vcvarsAll = findVcVarsAll();
+	if (!vcvarsAll) {
+		throw new Error(
+			"Could not find Visual Studio vcvarsall.bat. Install Visual Studio Build Tools with C++.",
+		);
+	}
+
+	const cmdPath = path.join(os.tmpdir(), `openscreen-build-wgc-${process.pid}-${Date.now()}.cmd`);
+	fs.writeFileSync(
+		cmdPath,
+		[
+			"@echo off",
+			`call "${vcvarsAll}" x64`,
+			"if errorlevel 1 exit /b %errorlevel%",
+			`if not exist "${COMPAT_LIB_DIR}" mkdir "${COMPAT_LIB_DIR}"`,
+			`for %%L in (gdi32.lib winspool.lib shell32.lib oleaut32.lib uuid.lib comdlg32.lib advapi32.lib) do if not exist "%WindowsSdkDir%Lib\\%WindowsSDKLibVersion%um\\x64\\%%L" copy /Y "%WindowsSdkDir%Lib\\%WindowsSDKLibVersion%um\\x64\\kernel32.Lib" "${COMPAT_LIB_DIR}\\%%L" >nul`,
+			"if errorlevel 1 exit /b %errorlevel%",
+			`set "LIB=${COMPAT_LIB_DIR};%LIB%"`,
+			command,
+			"exit /b %errorlevel%",
+			"",
+		].join("\r\n"),
+	);
+	try {
+		await run("cmd.exe", ["/d", "/c", cmdPath]);
+	} finally {
+		fs.rmSync(cmdPath, { force: true });
+	}
+}
+
+if (process.platform !== "win32") {
+	console.log("Skipping WGC helper build: Windows-only.");
+	process.exit(0);
+}
+
+fs.mkdirSync(BUILD_DIR, { recursive: true });
+
+await runInVsEnv(
+	`"${CMAKE}" -S "${SOURCE_DIR}" -B "${BUILD_DIR}" -G Ninja -DCMAKE_BUILD_TYPE=Release`,
+);
+await runInVsEnv(`"${CMAKE}" --build "${BUILD_DIR}" --config Release`);
+
+const outputPath = path.join(BUILD_DIR, "wgc-capture.exe");
+if (!fs.existsSync(outputPath)) {
+	throw new Error(`WGC helper build completed but ${outputPath} was not found.`);
+}
+
+const cursorSamplerOutputPath = path.join(BUILD_DIR, "cursor-sampler.exe");
+if (!fs.existsSync(cursorSamplerOutputPath)) {
+	throw new Error(`WGC helper build completed but ${cursorSamplerOutputPath} was not found.`);
+}
+
+fs.mkdirSync(BIN_DIR, { recursive: true });
+const distributablePath = path.join(BIN_DIR, "wgc-capture.exe");
+fs.copyFileSync(outputPath, distributablePath);
+
+const cursorSamplerDistributablePath = path.join(BIN_DIR, "cursor-sampler.exe");
+fs.copyFileSync(cursorSamplerOutputPath, cursorSamplerDistributablePath);
+
+console.log(`Built ${outputPath}`);
+console.log(`Copied ${distributablePath}`);
+console.log(`Built ${cursorSamplerOutputPath}`);
+console.log(`Copied ${cursorSamplerDistributablePath}`);