Add optional desktop mirror and native ARM64 release packaging

Integrate Frame OpenXR input, SteamVR video controls, gaze foveation, native audio, frame pacing and source-based packaging.

.containerignore

@@ -0,0 +1,20 @@
+**/.git
+/build-frame-arm64/
+/build/
+/build-test/
+/build_*/
+/frame-ui-local/
+/rbx_bin/
+/runtime/
+/data/
+/dist/
+/out/
+**/__pycache__/
+*.log
+*.bundle
+*.apk
+*.xapk
+*.aab
+*.obb
+libroblox.so
+cookies*.txt

.gitattributes

@@ -2,3 +2,7 @@
 # snapshot. Local Mocktail sources remain subject to git diff --check.
 third_party/mcpelauncher-linker/core/** -whitespace
 packaging/freebsd/*.patch -whitespace
+
+# Preserve original third-party shader/header whitespace.
+src/vr/smaa/** -whitespace
+tools/frame_video_settings/openvr.h -whitespace

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,6 +1,6 @@
 # Modified by vii from komaruworld/mocktail. See README "About this fork".
 name: Bug report
-description: Report a reproducible problem in Nightcap
+description: Report a reproducible problem on Steam Frame
 title: "[Bug]: "
 labels:
   - bug
@@ -11,14 +11,13 @@ body:
       value: |
         Please include enough detail for someone else to reproduce the bug.
 
-        Use any language you are comfortable with. The maintainer can read Russian and English directly, so either is preferred. If you are more comfortable in another language, use it.
+        Use any language you are comfortable with.
 
-        Please write issues and pull requests yourself. Do not use AI-generated text.
 
   - type: input
     id: version
     attributes:
-      label: Mocktail version
+      label: Nightcap version
       description: Provide the release version, package version, or commit hash.
       placeholder: "For example: v0.4.0 or 1a2b3c4"
     validations:
@@ -28,8 +27,8 @@ body:
     id: system
     attributes:
       label: System information
-      description: Include your distribution, desktop session, GPU, and graphics driver when relevant.
-      placeholder: "For example: Arch Linux, KDE Plasma 6 on Wayland, AMD RX 6600, Mesa 26.1"
+      description: Include the SteamOS, SteamVR and graphics driver versions.
+      placeholder: "Steam Frame, SteamOS version, SteamVR build, Turnip version"
     validations:
       required: true
 
@@ -37,8 +36,8 @@ body:
     id: installation
     attributes:
       label: Installation method
-      description: Tell us how Mocktail was installed or built.
-      placeholder: "For example: AppImage, Flatpak, AUR, or built from source"
+      description: Tell us how Nightcap was installed or built.
+      placeholder: "Source build using the Steam Frame container recipe"
     validations:
       required: true
 
@@ -56,7 +55,7 @@ body:
       label: Steps to reproduce
       description: List the smallest reliable sequence of actions that triggers the problem.
       placeholder: |
-        1. Start Mocktail with ...
+        1. Start Nightcap with ...
         2. Open ...
         3. Select ...
         4. Observe ...
@@ -76,10 +75,8 @@ body:
       value: |
         Latest log:
 
-        - Flatpak: `~/.var/app/io.github.CoderDayton.nightcap/.local/state/mocktail/logs/latest.log`
-        - Other installs: `~/.local/state/mocktail/logs/latest.log`
+        `~/.local/share/nightcap-vr-arm64/last-launch.log`
 
-        Older logs are in the `sessions` directory next to `latest.log`.
 
   - type: textarea
     id: logs

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,5 +1,6 @@
+# Modified by vii from komaruworld/mocktail. See README "About this fork".
 name: Feature request
-description: Suggest an improvement or a new capability for Mocktail
+description: Suggest an improvement or a new capability for Nightcap
 title: "[Feature]: "
 labels:
   - enhancement
@@ -10,9 +11,8 @@ body:
       value: |
         Describe what you want to change and why it would be useful.
 
-        Use any language you are comfortable with. The maintainer can read Russian and English directly, so either is preferred. If you are more comfortable in another language, use it.
+        Use any language you are comfortable with.
 
-        Please write issues and pull requests yourself. Do not use AI-generated text.
 
   - type: textarea
     id: problem
@@ -26,7 +26,7 @@ body:
     id: proposal
     attributes:
       label: Proposed solution
-      description: Describe how you would like Mocktail to behave.
+      description: Describe how you would like Nightcap to behave.
     validations:
       required: true
 

.github/pull_request_template.md

@@ -1,3 +1,7 @@
-<!-- Briefly describe what this pull request adds, changes, or removes. Write it yourself and do not use AI-generated text. Link the issue with "Closes #123" or "Fixes #123". -->
+## Change
 
-Closes #
+Describe the behavior changed on Steam Frame and link any relevant issue.
+
+## Checks
+
+Describe the build, tests or device checks run for this change.

.github/workflows/aur.yml

@@ -1,114 +0,0 @@
-name: Publish AUR packages
-
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: aur-packages
-  cancel-in-progress: true
-
-jobs:
-  publish:
-    name: Publish AUR packages
-    runs-on: ubuntu-24.04
-    timeout-minutes: 15
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-
-      - name: Prepare AUR metadata
-        shell: bash
-        run: |
-          set -Eeuo pipefail
-          package_dir="$GITHUB_WORKSPACE/packaging/aur/mocktail-git"
-          version="$(sed -n \
-            's/^[[:space:]]*VERSION[[:space:]]\+\([0-9][0-9.]*\).*/\1/p' \
-            CMakeLists.txt | head -n 1)"
-          [[ "$version" =~ ^[0-9]+(\.[0-9]+)*$ ]]
-          pkgver="${version}.r$(git rev-list --count HEAD).g$(git rev-parse --short=7 HEAD)"
-          sed -i "s/^pkgver=.*/pkgver=${pkgver}/" "$package_dir/PKGBUILD"
-
-          docker run --rm \
-            --volume "$package_dir:/pkg" \
-            archlinux:base-devel bash -Eeuo pipefail -c '
-              useradd --create-home builder
-              install -d -o builder -g builder /tmp/mocktail-git
-              install -o builder -g builder -m 0644 \
-                /pkg/PKGBUILD /tmp/mocktail-git/PKGBUILD
-              runuser -u builder -- bash -c \
-                "cd /tmp/mocktail-git && makepkg --printsrcinfo" \
-                > /pkg/.SRCINFO
-            '
-
-          grep -Fqx "pkgver=${pkgver}" "$package_dir/PKGBUILD"
-          grep -Fqx $'\tpkgver = '"${pkgver}" "$package_dir/.SRCINFO"
-          printf 'AUR_PKGVER=%s\n' "$pkgver" >> "$GITHUB_ENV"
-
-      - name: Publish to the AUR
-        shell: bash
-        env:
-          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
-          AUR_SSH_KEY_PASSPHRASE: ${{ secrets.AUR_SSH_KEY_PASSPHRASE }}
-        run: |
-          set -Eeuo pipefail
-          [[ -n "$AUR_SSH_PRIVATE_KEY" ]]
-          [[ -n "$AUR_SSH_KEY_PASSPHRASE" ]]
-
-          private_key="$RUNNER_TEMP/aur_ed25519"
-          askpass="$RUNNER_TEMP/aur_askpass"
-          known_hosts="$RUNNER_TEMP/aur_known_hosts"
-          printf '%s\n' "$AUR_SSH_PRIVATE_KEY" > "$private_key"
-          unset AUR_SSH_PRIVATE_KEY
-          chmod 0600 "$private_key"
-          printf '%s\n' \
-            '#!/usr/bin/env bash' \
-            'printf '\''%s\n'\'' "$AUR_SSH_KEY_PASSPHRASE"' \
-            > "$askpass"
-          chmod 0700 "$askpass"
-          eval "$(ssh-agent -s)"
-          trap 'ssh-agent -k >/dev/null; rm -f -- "$private_key" "$askpass"' EXIT
-          DISPLAY=:0 SSH_ASKPASS="$askpass" SSH_ASKPASS_REQUIRE=force \
-            ssh-add "$private_key" </dev/null
-          unset AUR_SSH_KEY_PASSPHRASE
-
-          ssh-keyscan -T 10 -t ed25519 aur.archlinux.org > "$known_hosts"
-          fingerprint="$(ssh-keygen -lf "$known_hosts" -E sha256 | awk '{print $2}')"
-          [[ "$fingerprint" == \
-            'SHA256:RFzBCUItH9LZS0cKB5UE6ceAYhBD5C8GeOBip8Z11+4' ]]
-
-          export GIT_SSH_COMMAND="ssh -F /dev/null -i $private_key \
-            -o BatchMode=yes -o IdentitiesOnly=yes \
-            -o StrictHostKeyChecking=yes \
-            -o UserKnownHostsFile=$known_hosts"
-          publish_aur_package() {
-            local package_name="$1"
-            local commit_message="$2"
-            local source_dir="packaging/aur/$package_name"
-            local aur_dir="$RUNNER_TEMP/${package_name}-aur"
-
-            git clone --branch master --single-branch \
-              "ssh://aur@aur.archlinux.org/${package_name}.git" "$aur_dir"
-            install -m 0644 "$source_dir/PKGBUILD" "$aur_dir/PKGBUILD"
-            install -m 0644 "$source_dir/.SRCINFO" "$aur_dir/.SRCINFO"
-
-            git -C "$aur_dir" config user.name komaruworld
-            git -C "$aur_dir" config user.email rtysus228@gmail.com
-            git -C "$aur_dir" add PKGBUILD .SRCINFO
-            if git -C "$aur_dir" diff --cached --quiet; then
-              printf '%s is already published\n' "$package_name"
-              return
-            fi
-            git -C "$aur_dir" commit -m "$commit_message"
-            git -C "$aur_dir" push origin HEAD:master
-          }
-
-          publish_aur_package mocktail-git "Update to ${AUR_PKGVER}"
-          publish_aur_package mocktail 'make builds stable'
-          publish_aur_package mocktail-bin 'make builds stable'

.github/workflows/ci.yml

@@ -1,67 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - '.github/workflows/**'
-      - 'CMakeLists.txt'
-      - 'Makefile'
-      - 'README.md'
-      - 'config/**'
-      - 'packaging/**'
-      - 'scripts/**'
-      - 'stubs/**'
-      - 'tests/**'
-  pull_request:
-    paths:
-      - '.github/workflows/**'
-      - 'CMakeLists.txt'
-      - 'Makefile'
-      - 'README.md'
-      - 'config/**'
-      - 'packaging/**'
-      - 'scripts/**'
-      - 'stubs/**'
-      - 'tests/**'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ci-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  contracts:
-    name: Repository contracts
-    runs-on: ubuntu-24.04
-    timeout-minutes: 15
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-          submodules: recursive
-
-      - name: Validate shell and JSON files
-        shell: bash
-        run: |
-          find scripts tests -type f -name '*.sh' -print0 | xargs -0 -n1 bash -n
-          find config packaging/flatpak -type f -name '*.json' -print0 \
-            | xargs -0 -n1 python3 -m json.tool >/dev/null
-
-      - name: Run script unit tests
-        shell: bash
-        run: |
-          python3 -m pip install --disable-pip-version-check requests
-          python3 -m unittest discover -s tests -p '*_test.py' -v
-
-      - name: Verify build and packaging contracts
-        shell: bash
-        run: |
-          bash tests/managed_payload_build_contract_test.sh .
-          bash tests/flatpak_packaging_test.sh .
-          bash tests/native_packaging_test.sh .
-          bash tests/anylinux_dependencies_test.sh .

.github/workflows/flatpak.yml

@@ -1,192 +0,0 @@
-# Modified by vii from komaruworld/mocktail. See README "About this fork".
-name: Flatpak
-
-on:
-  push:
-    tags: ['v*']
-  pull_request:
-    paths:
-      - '.github/workflows/flatpak.yml'
-      - '.gitmodules'
-      - 'CMakeLists.txt'
-      - 'LICENSE'
-      - 'assets/screenshots/**'
-      - 'cmake/**'
-      - 'config/**'
-      - 'include/**'
-      - 'packaging/flatpak/**'
-      - 'packaging/icons/**'
-      - 'packaging/io.github.CoderDayton.nightcap.desktop'
-      - 'packaging/io.github.CoderDayton.nightcap.metainfo.xml'
-      - 'packaging/io.github.CoderDayton.nightcap.svg'
-      - 'scripts/assemble_flatpak_pages.sh'
-      - 'site/**'
-      - 'src/**'
-      - 'stubs/**'
-      - 'third_party/**'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: flatpak-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  flatpak:
-    name: Flatpak build
-    runs-on: ubuntu-24.04
-    timeout-minutes: 120
-    env:
-      # Publish on release tags and on manual runs from main. Pull requests
-      # only verify that the manifest still builds.
-      MOCKTAIL_PUBLISH: ${{ startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') }}
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-          submodules: recursive
-
-      - name: Install Flatpak builder
-        shell: bash
-        run: |
-          sudo apt-get update
-          sudo apt-get install --yes flatpak flatpak-builder gnupg
-          flatpak remote-add --user --if-not-exists flathub \
-            https://dl.flathub.org/repo/flathub.flatpakrepo
-
-      - name: Build Flatpak repository and bundle
-        shell: bash
-        env:
-          FLATPAK_GPG_PRIVATE_KEY: ${{ secrets.FLATPAK_GPG_PRIVATE_KEY }}
-          FLATPAK_GPG_KEY_ID: ${{ secrets.FLATPAK_GPG_KEY_ID }}
-        run: |
-          set -Eeuo pipefail
-          # The manifest builds the local checkout from refs/heads/main.
-          git update-ref refs/heads/main "$GITHUB_SHA"
-          builder_signing=()
-          bundle_keys=()
-          if [[ "$MOCKTAIL_PUBLISH" == true ]]; then
-            [[ -n "$FLATPAK_GPG_PRIVATE_KEY" && \
-               -n "$FLATPAK_GPG_KEY_ID" ]]
-            install -d -m 0700 "$RUNNER_TEMP/nightcap-gnupg"
-            printf '%s' "$FLATPAK_GPG_PRIVATE_KEY" | \
-              gpg --batch --homedir "$RUNNER_TEMP/nightcap-gnupg" --import
-            gpg --batch --homedir "$RUNNER_TEMP/nightcap-gnupg" \
-              --export "$FLATPAK_GPG_KEY_ID" >nightcap-flatpak.gpg
-            builder_signing=(
-              "--gpg-sign=$FLATPAK_GPG_KEY_ID"
-              "--gpg-homedir=$RUNNER_TEMP/nightcap-gnupg"
-            )
-            bundle_keys=(--gpg-keys=nightcap-flatpak.gpg)
-          fi
-          flatpak-builder \
-            --arch=x86_64 \
-            --jobs=4 \
-            --user \
-            --install-deps-from=flathub \
-            --disable-rofiles-fuse \
-            --force-clean \
-            --default-branch=stable \
-            --repo=repo \
-            "${builder_signing[@]}" \
-            build-flatpak-ci \
-            packaging/flatpak/io.github.CoderDayton.nightcap.json
-          if [[ "$MOCKTAIL_PUBLISH" == true ]]; then
-            flatpak build-update-repo \
-              --generate-static-deltas \
-              --static-delta-jobs=2 \
-              --prune \
-              --gpg-sign="$FLATPAK_GPG_KEY_ID" \
-              --gpg-homedir="$RUNNER_TEMP/nightcap-gnupg" \
-              repo
-          fi
-          flatpak build-bundle \
-            --arch=x86_64 \
-            "${bundle_keys[@]}" \
-            repo \
-            Nightcap-x86_64.flatpak \
-            io.github.CoderDayton.nightcap \
-            stable
-          if [[ "$MOCKTAIL_PUBLISH" == true ]]; then
-            ./scripts/assemble_flatpak_pages.sh \
-              repo Nightcap-x86_64.flatpak nightcap-flatpak.gpg public
-          fi
-
-      - name: Upload Flatpak
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: Nightcap-x86_64-flatpak
-          path: Nightcap-x86_64.flatpak
-          if-no-files-found: error
-          retention-days: 14
-
-      - name: Configure GitHub Pages
-        if: env.MOCKTAIL_PUBLISH == 'true'
-        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
-
-      - name: Upload GitHub Pages repository
-        if: env.MOCKTAIL_PUBLISH == 'true'
-        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
-        with:
-          path: public
-
-  deploy-pages:
-    name: Publish Flatpak repository
-    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
-    needs: flatpak
-    runs-on: ubuntu-24.04
-    timeout-minutes: 10
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
-
-  release:
-    name: Attach bundle to GitHub release
-    if: startsWith(github.ref, 'refs/tags/v')
-    needs: flatpak
-    runs-on: ubuntu-24.04
-    timeout-minutes: 15
-    permissions:
-      contents: write
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Download Flatpak
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: Nightcap-x86_64-flatpak
-          path: release
-
-      - name: Upload to release
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -Eeuo pipefail
-          tag="${GITHUB_REF_NAME}"
-          (cd release && sha256sum Nightcap-x86_64.flatpak > Nightcap-x86_64.flatpak.sha256)
-          ./scripts/release_notes.sh "$tag" > release/notes.md
-          # The Release workflow creates the same release; whichever job
-          # arrives second sees "already exists" and continues.
-          if ! gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
-            gh release create "$tag" --repo "$GITHUB_REPOSITORY" \
-              --title "Nightcap $tag" --notes-file release/notes.md ||
-              gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null
-          fi
-          gh release edit "$tag" --repo "$GITHUB_REPOSITORY" \
-            --title "Nightcap $tag" --notes-file release/notes.md
-          gh release upload "$tag" --repo "$GITHUB_REPOSITORY" --clobber \
-            release/Nightcap-x86_64.flatpak \
-            release/Nightcap-x86_64.flatpak.sha256

.github/workflows/packages.yml

@@ -1,215 +0,0 @@
-name: Nightly AppImage
-
-on:
-  schedule:
-    # 05:00 UTC daily. A run whose commit already carries the continuous tag
-    # exits without rebuilding, so a quiet day costs one probe job.
-    - cron: '0 5 * * *'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: nightly-appimage
-  cancel-in-progress: false
-
-jobs:
-  probe:
-    name: Check for new commits
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
-    outputs:
-      build: ${{ steps.decide.outputs.build }}
-    steps:
-      - name: Compare HEAD against the published continuous tag
-        id: decide
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -Eeuo pipefail
-          published="$(gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/continuous" \
-            --jq .object.sha 2>/dev/null || true)"
-          if [[ "$GITHUB_EVENT_NAME" == "schedule" && "$published" == "$GITHUB_SHA" ]]; then
-            echo 'build=false' >>"$GITHUB_OUTPUT"
-            echo "continuous already points at $GITHUB_SHA; nothing to build"
-          else
-            echo 'build=true' >>"$GITHUB_OUTPUT"
-          fi
-
-  appimage:
-    name: AppImage (AnyLinux)
-    needs: probe
-    if: needs.probe.outputs.build == 'true'
-    runs-on: ubuntu-24.04
-    timeout-minutes: 90
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-          submodules: recursive
-
-      - name: Build AppImage
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          docker run --rm \
-            --volume "$GITHUB_WORKSPACE:/workspace" \
-            --workdir /workspace \
-            --env GH_TOKEN \
-            ghcr.io/archlinux/archlinux:base-devel@sha256:c3953446016873a756fb7814f10087cac1634c127f7302e80c81c512da796d05 bash -Eeuo pipefail -c '
-              pacman -Syu --noconfirm --needed \
-                cmake git ninja pkgconf lld sdl3 sdl3_ttf curl openssl \
-                nlohmann-json libyaml libelf minizip minizip-ng capstone gtk4 \
-                libadwaita webkitgtk-6.0 libutf8proc fontconfig libglvnd \
-                vulkan-headers zlib libplacebo bubblewrap xdg-dbus-proxy \
-                patchelf jq unzip file ca-certificates dbus zsync
-
-              # Reduced ABI-compatible packages belong only in this builder.
-              # The native updater does not require a JRE or Android SDK.
-              ./scripts/install_anylinux_dependencies.sh
-
-              curl --fail --location --retry 3 \
-                --output /tmp/quick-sharun \
-                https://raw.githubusercontent.com/pkgforge-dev/Anylinux-AppImages/2a025cef14483c5bc2a75b479071f4d5c58a906f/useful-tools/quick-sharun.sh
-              echo "fa66d0189e1e87df781c049dfb23cbb1e753786056f693a4483d6d3af61e7ee1  /tmp/quick-sharun" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/quick-sharun
-
-              curl --fail --location --retry 3 \
-                --output /tmp/sharun \
-                https://github.com/pkgforge-dev/Anylinux-sharun/releases/download/2.2.6/sharun-x86_64
-              echo "a4d51752f9861b4870ca529fea04087310b28f8943cc55b99a95b777d4db92ec  /tmp/sharun" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/sharun
-
-              curl --fail --location --retry 3 \
-                --output /tmp/anylinux.c \
-                https://raw.githubusercontent.com/pkgforge-dev/Anylinux-AppImages/2a025cef14483c5bc2a75b479071f4d5c58a906f/useful-tools/lib/anylinux.c
-              echo "f50650ad96d177559bdd0737df509fa20bd4af08887631c738fc1f31bfac185f  /tmp/anylinux.c" | \
-                sha256sum --check --strict
-
-              curl --fail --location --retry 3 \
-                --output /tmp/appimagetool \
-                https://github.com/pkgforge-dev/appimagetool/releases/download/0.3.3/appimagetool-x86_64-linux
-              echo "0d01a4e2628efc897be9663f0faeed6a171e1851270b4e1ce4c22434a36ecebd  /tmp/appimagetool" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/appimagetool
-
-              curl --fail --location --retry 3 \
-                --output /tmp/uruntime \
-                https://github.com/VHSgunzo/uruntime/releases/download/v0.5.9/uruntime-appimage-dwarfs-lite-x86_64
-              echo "cef962c299f2fa19b2b3cdf2fa1565ee8541796cc89b9a97a591f94041e8b083  /tmp/uruntime" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/uruntime
-
-              curl --fail --location --retry 3 \
-                --output /tmp/mkdwarfs \
-                https://github.com/mhx/dwarfs/releases/download/v0.15.6/dwarfs-universal-0.15.6-Linux-x86_64
-              echo "50891c38ba359db8271819a6cbf6aaa8068681523f0c4f2b8242007a45edaa28  /tmp/mkdwarfs" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/mkdwarfs
-
-              git config --global --add safe.directory /workspace
-              git config --global --add safe.directory /workspace/third_party/Vulkan-Headers
-              git config --global --add safe.directory /workspace/third_party/libjnivm
-              # Install into the disposable container /usr before deployment.
-              export MOCKTAIL_ANYLINUX_SYSTEM_INSTALL=1
-              export MOCKTAIL_ANYLINUX_SHARUN=/tmp/sharun
-              export MOCKTAIL_ANYLINUX_C_SOURCE=/tmp/anylinux.c
-              export RUNTIME=/tmp/uruntime
-              export DWARFS_CMD=/tmp/mkdwarfs
-              make appimage BUILD_DIR=build-appimage JOBS=4 \
-                APPIMAGE=dist/Mocktail-x86_64.AppImage \
-                PORTABLE_MODE=standalone APPIMAGE_FORMAT=anylinux \
-                ANYLINUX_PACKAGER=/tmp/quick-sharun \
-                ANYLINUX_APPIMAGETOOL=/tmp/appimagetool
-              test -x dist/Mocktail-x86_64.AppImage
-            '
-
-      - name: Smoke-test AppImage without FUSE
-        shell: bash
-        run: |
-          smoke_dir="$(mktemp -d)"
-          trap 'rm -rf -- "$smoke_dir"' EXIT
-          export XDG_DATA_HOME="$smoke_dir/data"
-          export XDG_CONFIG_HOME="$smoke_dir/config"
-          export XDG_CACHE_HOME="$smoke_dir/cache"
-          export XDG_STATE_HOME="$smoke_dir/state"
-          mkdir -p "$XDG_DATA_HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME" "$XDG_STATE_HOME"
-          timeout 60s dist/Mocktail-x86_64.AppImage --appimage-extract-and-run --help
-          timeout 60s dist/Mocktail-x86_64.AppImage --appimage-extract-and-run mocktail_updater status
-
-      - name: Upload AppImage
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: Nightcap-AppImage
-          path: dist/Mocktail-x86_64.AppImage
-          if-no-files-found: error
-          retention-days: 14
-
-  publish:
-    name: Publish continuous release
-    needs: [probe, appimage]
-    # A manual run from another branch still builds and smoke-tests, but the
-    # continuous tag and release only ever follow main.
-    if: needs.probe.outputs.build == 'true' && github.ref == 'refs/heads/main'
-    runs-on: ubuntu-24.04
-    timeout-minutes: 30
-    permissions:
-      contents: write
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-
-      - name: Download AppImage
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: Nightcap-AppImage
-          path: release
-
-      - name: Name and checksum the nightly build
-        shell: bash
-        run: |
-          set -Eeuo pipefail
-          # The Makefile builds under upstream's artifact name; the published
-          # asset carries this fork's.
-          mv -- release/Mocktail-x86_64.AppImage release/Nightcap-nightly-x86_64.AppImage
-          (cd release && sha256sum Nightcap-nightly-x86_64.AppImage \
-            > Nightcap-nightly-x86_64.AppImage.sha256)
-          find release -maxdepth 1 -type f -print
-
-      - name: Update continuous release
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -Eeuo pipefail
-          git config user.name 'github-actions[bot]'
-          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
-          git tag --force continuous "$GITHUB_SHA"
-          git push origin refs/tags/continuous --force
-          notes="Automated build of main at ${GITHUB_SHA:0:8}. Untested and unreleased; use a tagged release for normal play."
-          if ! gh release view continuous >/dev/null 2>&1; then
-            gh release create continuous \
-              --prerelease \
-              --title "Nightcap continuous" \
-              --notes "$notes"
-          fi
-          gh release edit continuous --title "Nightcap continuous" --notes "$notes"
-          gh release upload continuous release/* --clobber
-          # Drop assets left by earlier runs under other names.
-          while IFS= read -r asset; do
-            case "$asset" in
-              Nightcap-nightly-x86_64.AppImage|Nightcap-nightly-x86_64.AppImage.sha256)
-                ;;
-              *)
-                gh release delete-asset continuous "$asset" --yes
-                ;;
-            esac
-          done < <(gh release view continuous --json assets --jq '.assets[].name')

.github/workflows/release.yml

@@ -1,168 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags: ['v*']
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: release-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  appimage:
-    name: AppImage (AnyLinux)
-    runs-on: ubuntu-24.04
-    timeout-minutes: 90
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-          submodules: recursive
-
-      - name: Check release notes
-        if: startsWith(github.ref, 'refs/tags/v')
-        shell: bash
-        run: ./scripts/release_notes.sh "$GITHUB_REF_NAME" >/dev/null
-
-      - name: Build AppImage
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          docker run --rm \
-            --volume "$GITHUB_WORKSPACE:/workspace" \
-            --workdir /workspace \
-            --env GH_TOKEN \
-            ghcr.io/archlinux/archlinux:base-devel@sha256:c3953446016873a756fb7814f10087cac1634c127f7302e80c81c512da796d05 bash -Eeuo pipefail -c '
-              pacman -Syu --noconfirm --needed \
-                cmake git ninja pkgconf lld sdl3 sdl3_ttf curl openssl \
-                nlohmann-json libyaml libelf minizip minizip-ng capstone gtk4 \
-                libadwaita webkitgtk-6.0 libutf8proc fontconfig libglvnd \
-                vulkan-headers zlib libplacebo bubblewrap xdg-dbus-proxy \
-                patchelf jq unzip file ca-certificates dbus zsync
-
-              ./scripts/install_anylinux_dependencies.sh
-
-              curl --fail --location --retry 3 \
-                --output /tmp/quick-sharun \
-                https://raw.githubusercontent.com/pkgforge-dev/Anylinux-AppImages/2a025cef14483c5bc2a75b479071f4d5c58a906f/useful-tools/quick-sharun.sh
-              echo "fa66d0189e1e87df781c049dfb23cbb1e753786056f693a4483d6d3af61e7ee1  /tmp/quick-sharun" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/quick-sharun
-
-              curl --fail --location --retry 3 \
-                --output /tmp/sharun \
-                https://github.com/pkgforge-dev/Anylinux-sharun/releases/download/2.2.6/sharun-x86_64
-              echo "a4d51752f9861b4870ca529fea04087310b28f8943cc55b99a95b777d4db92ec  /tmp/sharun" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/sharun
-
-              curl --fail --location --retry 3 \
-                --output /tmp/anylinux.c \
-                https://raw.githubusercontent.com/pkgforge-dev/Anylinux-AppImages/2a025cef14483c5bc2a75b479071f4d5c58a906f/useful-tools/lib/anylinux.c
-              echo "f50650ad96d177559bdd0737df509fa20bd4af08887631c738fc1f31bfac185f  /tmp/anylinux.c" | \
-                sha256sum --check --strict
-
-              curl --fail --location --retry 3 \
-                --output /tmp/appimagetool \
-                https://github.com/pkgforge-dev/appimagetool/releases/download/0.3.3/appimagetool-x86_64-linux
-              echo "0d01a4e2628efc897be9663f0faeed6a171e1851270b4e1ce4c22434a36ecebd  /tmp/appimagetool" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/appimagetool
-
-              curl --fail --location --retry 3 \
-                --output /tmp/uruntime \
-                https://github.com/VHSgunzo/uruntime/releases/download/v0.5.9/uruntime-appimage-dwarfs-lite-x86_64
-              echo "cef962c299f2fa19b2b3cdf2fa1565ee8541796cc89b9a97a591f94041e8b083  /tmp/uruntime" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/uruntime
-
-              curl --fail --location --retry 3 \
-                --output /tmp/mkdwarfs \
-                https://github.com/mhx/dwarfs/releases/download/v0.15.6/dwarfs-universal-0.15.6-Linux-x86_64
-              echo "50891c38ba359db8271819a6cbf6aaa8068681523f0c4f2b8242007a45edaa28  /tmp/mkdwarfs" | \
-                sha256sum --check --strict
-              chmod 0755 /tmp/mkdwarfs
-
-              git config --global --add safe.directory /workspace
-              git config --global --add safe.directory /workspace/third_party/Vulkan-Headers
-              git config --global --add safe.directory /workspace/third_party/libjnivm
-              export MOCKTAIL_ANYLINUX_SYSTEM_INSTALL=1
-              export MOCKTAIL_ANYLINUX_SHARUN=/tmp/sharun
-              export MOCKTAIL_ANYLINUX_C_SOURCE=/tmp/anylinux.c
-              export RUNTIME=/tmp/uruntime
-              export DWARFS_CMD=/tmp/mkdwarfs
-              make appimage BUILD_DIR=build-appimage JOBS=4 \
-                APPIMAGE=dist/Mocktail-x86_64.AppImage \
-                PORTABLE_MODE=standalone APPIMAGE_FORMAT=anylinux \
-                ANYLINUX_PACKAGER=/tmp/quick-sharun \
-                ANYLINUX_APPIMAGETOOL=/tmp/appimagetool
-              test -x dist/Mocktail-x86_64.AppImage
-            '
-
-      - name: Smoke-test AppImage without FUSE
-        shell: bash
-        run: |
-          smoke_dir="$(mktemp -d)"
-          trap 'rm -rf -- "$smoke_dir"' EXIT
-          export XDG_DATA_HOME="$smoke_dir/data"
-          export XDG_CONFIG_HOME="$smoke_dir/config"
-          export XDG_CACHE_HOME="$smoke_dir/cache"
-          export XDG_STATE_HOME="$smoke_dir/state"
-          mkdir -p "$XDG_DATA_HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME" "$XDG_STATE_HOME"
-          timeout 60s dist/Mocktail-x86_64.AppImage --appimage-extract-and-run --help
-          timeout 60s dist/Mocktail-x86_64.AppImage --appimage-extract-and-run mocktail_updater status
-
-      - name: Upload AppImage
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: Mocktail-AppImage
-          path: dist/Mocktail-x86_64.AppImage
-          if-no-files-found: error
-          retention-days: 14
-
-  publish:
-    name: Publish GitHub release
-    if: startsWith(github.ref, 'refs/tags/v')
-    needs: [appimage]
-    runs-on: ubuntu-24.04
-    timeout-minutes: 15
-    permissions:
-      contents: write
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Download AppImage
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: Mocktail-AppImage
-          path: release
-
-      - name: Create release
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -Eeuo pipefail
-          tag="${GITHUB_REF_NAME}"
-          mv release/Mocktail-x86_64.AppImage release/Nightcap-x86_64.AppImage
-          (cd release && sha256sum Nightcap-x86_64.AppImage > Nightcap-x86_64.AppImage.sha256)
-          ./scripts/release_notes.sh "$tag" > release/notes.md
-          # The Flatpak workflow creates the same release; whichever job
-          # arrives second sees "already exists" and continues.
-          if ! gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
-            gh release create "$tag" --repo "$GITHUB_REPOSITORY" \
-              --title "Nightcap $tag" --notes-file release/notes.md ||
-              gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null
-          fi
-          gh release edit "$tag" --repo "$GITHUB_REPOSITORY" \
-            --title "Nightcap $tag" --notes-file release/notes.md
-          gh release upload "$tag" --repo "$GITHUB_REPOSITORY" --clobber \
-            release/Nightcap-x86_64.AppImage \
-            release/Nightcap-x86_64.AppImage.sha256

.github/workflows/steam-frame-arm64.yml

@@ -0,0 +1,202 @@
+name: Steam Frame ARM64
+
+on:
+  push:
+    branches: [steam-frame]
+    tags: ['steam-frame-*']
+  pull_request:
+    branches: [steam-frame]
+  workflow_dispatch:
+    inputs:
+      publish_release:
+        description: Publish a release for an existing steam-frame-* tag
+        type: boolean
+        default: false
+      release_tag:
+        description: Existing tag to build when publishing (leave empty for artifact only)
+        type: string
+        default: ''
+
+permissions:
+  contents: read
+
+concurrency:
+  group: steam-frame-arm64-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  IMAGE: localhost/nightcap-vr-arm64:frame-foveated
+  ASSET: nightcap-steam-frame-arm64.oci.tar.zst
+
+jobs:
+  source-checks:
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish_release && inputs.release_tag || github.ref }}
+      - name: Check Native settings and package scripts
+        run: |
+          for script in build-frame-nightcap.sh packaging/steam-frame/verify_image.sh; do
+            bash -n "$script"
+          done
+          python3 - <<'PY'
+          import ast
+          from pathlib import Path
+          paths = list(Path('tools/steam_frame').glob('*.py'))
+          paths.append(Path('tools/steam_frame/nightcap-vr-arm64'))
+          for path in paths:
+              ast.parse(path.read_text(), filename=str(path))
+          PY
+          python3 -m unittest discover -s tests -p 'steam_frame_*_test.py'
+          node tests/steamvr_video_controls_test.js
+
+  build:
+    if: github.event_name != 'pull_request'
+    needs: source-checks
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 90
+    outputs:
+      release_tag: ${{ steps.release-target.outputs.tag }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          submodules: recursive
+          persist-credentials: false
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish_release && inputs.release_tag || github.ref }}
+      - name: Validate release target
+        id: release-target
+        env:
+          EVENT: ${{ github.event_name }}
+          REF_TYPE: ${{ github.ref_type }}
+          REF_NAME: ${{ github.ref_name }}
+          PUBLISH: ${{ inputs.publish_release }}
+          REQUESTED_TAG: ${{ inputs.release_tag }}
+        run: |
+          tag=''
+          if [[ "$EVENT" == push && "$REF_TYPE" == tag ]]; then
+            tag="$REF_NAME"
+          elif [[ "$EVENT" == workflow_dispatch && "$PUBLISH" == true ]]; then
+            tag="$REQUESTED_TAG"
+          fi
+          if [[ -n "$tag" || "$PUBLISH" == true ]]; then
+            [[ "$tag" =~ ^steam-frame-[A-Za-z0-9][A-Za-z0-9._-]*$ ]]
+            [[ "$(git rev-parse "refs/tags/$tag^{commit}")" == "$(git rev-parse HEAD)" ]]
+          fi
+          printf 'tag=%s\n' "$tag" >> "$GITHUB_OUTPUT"
+      - name: Install container tools
+        run: |
+          test "$(uname -m)" = aarch64
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends -y podman zstd
+      - name: Build Native ARM64 image
+        run: |
+          sudo podman build --arch arm64 --jobs 1 \
+            --label "org.opencontainers.image.source=https://github.com/$GITHUB_REPOSITORY" \
+            --label "org.opencontainers.image.revision=$(git rev-parse HEAD)" \
+            --label org.opencontainers.image.title='Nightcap Steam Frame ARM64' \
+            -f packaging/steam-frame/Containerfile -t "$IMAGE" .
+      - name: Run mirror and runtime configuration regressions
+        run: |
+          sudo podman run --rm --entrypoint /bin/bash "$IMAGE" -lc '
+            set -euo pipefail
+            cmake -S /work -B /work/build-frame-arm64 -DBUILD_TESTING=ON
+            cmake --build /work/build-frame-arm64 -j3 \
+              --target desktop_mirror_test runtime_config_test runtime_config_file_test
+            /work/build-frame-arm64/tests/desktop_mirror_test
+            /work/build-frame-arm64/tests/runtime_config_test
+            /work/build-frame-arm64/tests/runtime_config_file_test
+          '
+      - name: Check payload-free image
+        run: |
+          mkdir -p dist
+          sudo bash packaging/steam-frame/verify_image.sh "$IMAGE" > dist/image-check.json
+          cat dist/image-check.json
+      - name: Export image and checksums
+        run: |
+          sudo podman save --format oci-archive "$IMAGE" | zstd -T2 -6 -o "dist/$ASSET"
+          test "$(stat -c %s "dist/$ASSET")" -lt 2147483648
+          python3 - <<'PY'
+          import json, os, pathlib, subprocess, tarfile
+          archive = pathlib.Path('dist') / os.environ['ASSET']
+          process = subprocess.Popen(['zstd', '-dc', str(archive)], stdout=subprocess.PIPE)
+          index = None
+          with tarfile.open(fileobj=process.stdout, mode='r|') as stream:
+              for member in stream:
+                  if member.name == 'index.json':
+                      index = json.load(stream.extractfile(member))
+          while process.stdout.read(1024 * 1024):
+              pass
+          if process.wait() != 0:
+              raise SystemExit('Compressed OCI archive integrity check failed')
+          manifests = index.get('manifests', []) if index else []
+          if (len(manifests) != 1 or manifests[0].get('annotations', {}).get(
+                  'org.opencontainers.image.ref.name') != os.environ['IMAGE']):
+              raise SystemExit('OCI archive must restore the normal launcher image tag')
+          print('Compressed OCI archive and launcher tag verified')
+          PY
+          cd dist
+          sha256sum "$ASSET" > "$ASSET.sha256"
+      - name: Write build metadata
+        env:
+          RELEASE_TAG: ${{ steps.release-target.outputs.tag }}
+        run: |
+          python3 - <<'PY'
+          import json, os, pathlib, subprocess
+          commit = subprocess.check_output(['git', 'rev-parse', 'HEAD'], text=True).strip()
+          image_id = subprocess.check_output(['sudo', 'podman', 'image', 'inspect', '--format', '{{.Id}}', os.environ['IMAGE']], text=True).strip()
+          metadata = {
+              'source': 'https://github.com/' + os.environ['GITHUB_REPOSITORY'],
+              'commit': commit, 'release_tag': os.environ['RELEASE_TAG'] or None,
+              'platform': 'linux/arm64', 'image_tag': os.environ['IMAGE'], 'image_id': image_id,
+              'archive': os.environ['ASSET'], 'upscaling': 'Native', 'fsr3_compiled': False,
+              'default_eye_size': [2160, 2160], 'default_refresh_hz': 72,
+              'default_antialiasing': 'SMAA High',
+              'checks': ['Native single-sample policy', 'refresh-rate policy', 'desktop mirror policy', 'video controls',
+                         'mirror command recording and runtime configuration',
+                         'AArch64 ELF and dynamic dependencies', 'payload and license packaging',
+                         'compressed OCI integrity and launcher tag'],
+              'runtime_testing': 'CI packaging checks do not start SteamVR or Roblox',
+              'licenses': 'Source notices and third-party notices are included under /work in the image',
+          }
+          pathlib.Path('dist/build-info.json').write_text(json.dumps(metadata, indent=2) + '\n')
+          PY
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: nightcap-steam-frame-arm64
+          path: dist/
+          if-no-files-found: error
+          compression-level: 0
+          retention-days: 14
+
+  release:
+    if: needs.build.outputs.release_tag != ''
+    needs: build
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 15
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: nightcap-steam-frame-arm64
+          path: dist
+      - name: Publish checked ARM64 package
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ needs.build.outputs.release_tag }}
+        run: |
+          cd dist
+          sha256sum --check "$ASSET.sha256"
+          printf '%s\n' \
+            'Native ARM64 Steam Frame image and packaging-check metadata.' \
+            'Roblox, SteamVR and host graphics drivers are downloaded or provided separately.' \
+            'Verify the SHA256, then import with: zstd -dc nightcap-steam-frame-arm64.oci.tar.zst | podman load' \
+            'See docs/INSTALL.md in this tag for launcher and SteamVR setup.' > release-notes.md
+          gh release create "$RELEASE_TAG" --verify-tag \
+            --title "Steam Frame ARM64 $RELEASE_TAG" --notes-file release-notes.md \
+            "$ASSET" "$ASSET.sha256" image-check.json build-info.json

.gitignore

@@ -177,3 +177,23 @@ lsan.log*
 # Test fixtures
 !/third_party/mcpelauncher-linker/core/libziparchive/**/*.zip
 !/third_party/mcpelauncher-linker/core/libziparchive/**/*.apk
+
+# Working plans, not part of the shipped documentation
+/docs/plans/
+
+# Steam Frame local builds and generated SteamVR assets
+/build-frame-arm64/
+/frame-ui-local/
+/tools/steam_frame/steamvr-*.original.*
+/tools/steam_frame/steamvr-*.sharpening.*
+/tools/steam_frame/steamvr-sharpening-ui-patch.json
+/steam-shortcut.json
+
+# Local Frame payloads, images and source-transfer archives
+/data/
+/host-drivers/
+*.bundle
+*.oci
+*.img
+/current.json
+/previous_good.json

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "third_party/Vulkan-Headers"]
 	path = third_party/Vulkan-Headers
 	url = https://github.com/KhronosGroup/Vulkan-Headers.git
+[submodule "third_party/OpenXR-SDK"]
+	path = third_party/OpenXR-SDK
+	url = https://github.com/KhronosGroup/OpenXR-SDK.git

CHANGELOG.md

@@ -1,80 +0,0 @@
-# Changelog
-
-All notable changes to Nightcap. The format follows
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Release notes on
-GitHub are taken from the matching section here.
-
-## [Unreleased]
-
-## [0.2.0] - 2026-09-16
-
-### Added
-
-- FAQ covering Discord RPC, log locations, and VR, adapted from upstream.
-- `input.raw_mouse` in `config.yaml` sends mouse look deltas in the host's
-  own units. Turn it on when first-person aiming feels too slow or too fast
-  under fractional display scaling. Off by default.
-- Nightly AppImage builds, published as the `continuous` prerelease. They are
-  untested; use a tagged release for normal play.
-
-### Changed
-
-- Values in `fflags.json` now win over the performance preset instead of
-  stopping the launch. Startup prints each key it kept.
-- Discord Rich Presence uses Nightcap's own Discord application, so it shows
-  as "Playing Nightcap". Terms and privacy pages for it live on the
-  project site.
-- Discord Rich Presence is on by default. Set
-  `integrations.discord_rpc.enabled: false` to turn it off.
-- The AppImage build verifies its reduced dependency packages against digests
-  taken at build time, rather than a digest list kept in the repository.
-
-### Fixed
-
-- Mouse look keeps responding after a long turn. The tracked pointer position
-  could drift past the edge of the view, which swallowed every reversal until
-  the mouse travelled all the way back.
-- Nightcap no longer refuses to start with `cannot lock appStorage`. It
-  created its own credential directory using the process umask, then rejected
-  that directory for being group writable. Systems with a permissive umask,
-  such as `002`, failed on first run.
-
-## [0.1.0] - 2026-09-15
-
-First Nightcap release, forked from komaruworld/mocktail.
-
-### Added
-
-- ETC2 and EAC texture emulation on Vulkan, so games that use compressed
-  mobile textures render correctly on desktop GPUs. Decoding runs on worker
-  threads to avoid stutter.
-- PNG texture overrides in `~/.config/mocktail/textures`, keyed by upload
-  hash, with a dump mode to find the texture you want to replace.
-- Small textures are upscaled 4x by default. Set
-  `MOCKTAIL_SMALL_TEXTURE_UPSCALE=1` to turn it off.
-- AppImage and signed Flatpak builds on every release tag. The Flatpak repo
-  is published at https://coderdayton.github.io/nightcap/.
-- Roadmap in `docs/ROADMAP.md`.
-
-### Changed
-
-- Frames are presented as soon as they are ready instead of waiting in a
-  queue, which lowers input latency.
-- Roblox now sees the real host RAM and display size instead of a low-end
-  phone profile.
-- App ID is `io.github.CoderDayton.nightcap`, so Nightcap installs next to
-  upstream Mocktail. The binary and config paths keep the `mocktail` name.
-- New name, icon, and colors.
-- The desktop entry launches on Wayland and points at the installed binary.
-
-### Fixed
-
-- Servers no longer kick with error 319 shortly after joining.
-- The FMOD output-device bridge is optional, so the updater no longer fails
-  without it.
-- The AppImage build no longer fails on stale checksums for the slimmed
-  Arch packages.
-
-[Unreleased]: https://github.com/CoderDayton/nightcap/compare/v0.2.0...HEAD
-[0.2.0]: https://github.com/CoderDayton/nightcap/releases/tag/v0.2.0
-[0.1.0]: https://github.com/CoderDayton/nightcap/releases/tag/v0.1.0

CMakeLists.txt

@@ -9,8 +9,8 @@
 
 cmake_minimum_required(VERSION 3.20)
 project(Mocktail
-  VERSION 1.0.4
-  DESCRIPTION "Android x86-64 Roblox compatibility runtime for Linux"
+  VERSION 0.3.4
+  DESCRIPTION "Android Roblox compatibility runtime for Linux"
   LANGUAGES CXX
 )
 
@@ -126,6 +126,8 @@ set(VULKAN_HEADERS_ENABLE_INSTALL OFF CACHE BOOL
   "Install vendored Vulkan-Headers" FORCE)
 add_subdirectory(third_party/Vulkan-Headers EXCLUDE_FROM_ALL)
 
+include(${CMAKE_SOURCE_DIR}/cmake/MocktailVR.cmake)
+
 include(CTest)
 if(BUILD_TESTING)
   # Package builds disable tests and do not fetch Google Test.
@@ -249,6 +251,10 @@ mocktail_apply_compile_options(mocktail_updater)
 
 add_library(mocktail_legacy_jnivm STATIC
   src/jnivm/jnivm.cc
+  src/jnivm/jni_references.cc
+  src/jnivm/jni_fields.cc
+  src/jnivm/jni_strings.cc
+  src/jnivm/jni_method_names.cc
 )
 add_library(Mocktail::LegacyJni ALIAS mocktail_legacy_jnivm)
 target_include_directories(mocktail_legacy_jnivm PUBLIC include)
@@ -266,6 +272,7 @@ add_library(mocktail_runtime STATIC
   src/runtime/crash_report_policy.cc
   src/runtime/discord_rpc.cc
   src/runtime/device_profile.cc
+  src/runtime/engine_pump_rest.cc
   src/runtime/environment.cc
   src/runtime/external_launch_broker.cc
   src/runtime/frame_rate_policy.cc
@@ -274,6 +281,7 @@ add_library(mocktail_runtime STATIC
   src/runtime/game_session_coordinator.cc
   src/runtime/graphics_launch_policy.cc
   src/runtime/http_client_policy.cc
+  src/runtime/luau_codegen_switch.cc
   src/runtime/memory_limit.cc
   src/runtime/owned_pthread.cc
   src/runtime/performance_policy.cc
@@ -284,12 +292,18 @@ add_library(mocktail_runtime STATIC
   src/runtime/roblox_capability_resolver.cc
   src/runtime/roblox_experience_launch_bridge.cc
   src/runtime/roblox_launch_uri.cc
+  src/runtime/roblox_presence_resolver.cc
   src/runtime/roblox_game_session_native_adapter.cc
   src/runtime/roblox_web_view_bridge.cc
   src/runtime/roblox_permissions_bridge.cc
+  src/runtime/roblox_account_bridge.cc
+  src/runtime/roblox_message_bus_request_bridge.cc
+  src/runtime/roblox_call_protocol_bridge.cc
+  src/runtime/roblox_haptic_protocol_bridge.cc
   src/runtime/payload_update_preflight.cc
   src/runtime/process_launch_policy.cc
   src/runtime/process_diagnostics.cc
+  src/runtime/asset_overlay_names.cc
   src/runtime/runtime_config.cc
   src/runtime/runtime_config_bootstrap.cc
   src/runtime/runtime_config_file.cc
@@ -384,7 +398,8 @@ add_library(mocktail_webview_helper_policy STATIC
   src/webview/webview_helper_policy.cc
 )
 add_library(Mocktail::WebViewHelperPolicy ALIAS mocktail_webview_helper_policy)
-target_include_directories(mocktail_webview_helper_policy PUBLIC src)
+target_include_directories(mocktail_webview_helper_policy PUBLIC src
+  PRIVATE include)
 target_link_libraries(mocktail_webview_helper_policy PUBLIC
   PkgConfig::WEBKITGTK6
   nlohmann_json::nlohmann_json
@@ -471,7 +486,7 @@ target_link_libraries(mocktail_window PUBLIC
   Mocktail::SdlVulkanWsi
   SDL3::SDL3
   ${CMAKE_DL_LIBS}
-  PRIVATE Mocktail::Runtime Mocktail::GlesTextOverlay
+  PRIVATE Mocktail::Runtime Mocktail::GlesTextOverlay Mocktail::GraphicsFoundation
 )
 
 add_library(mocktail_roblox_output_device_runtime STATIC
@@ -552,50 +567,6 @@ target_link_libraries(mocktail_bionic_abi_exports PRIVATE
   Threads::Threads
 )
 
-include(CheckCXXSourceCompiles)
-include(CheckIncludeFileCXX)
-include(CMakePushCheckState)
-
-check_include_file_cxx(execinfo.h MOCKTAIL_HAVE_EXECINFO_H)
-if(NOT MOCKTAIL_HAVE_EXECINFO_H)
-  message(FATAL_ERROR
-    "execinfo.h is required for crash diagnostics; on musl install "
-    "libexecinfo-devel"
-  )
-endif()
-
-set(MOCKTAIL_EXECINFO_LINK_LIBRARY "")
-set(_mocktail_execinfo_link_probe [=[
-  #include <execinfo.h>
-  int main() {
-    void* frames[1] = {};
-    const int count = backtrace(frames, 1);
-    return backtrace_symbols(frames, count) == nullptr;
-  }
-]=])
-check_cxx_source_compiles(
-  "${_mocktail_execinfo_link_probe}"
-  MOCKTAIL_EXECINFO_IN_HOST_LIBC
-)
-if(NOT MOCKTAIL_EXECINFO_IN_HOST_LIBC)
-  find_library(MOCKTAIL_EXECINFO_LIBRARY NAMES execinfo REQUIRED)
-  cmake_push_check_state(RESET)
-  set(CMAKE_REQUIRED_LIBRARIES "${MOCKTAIL_EXECINFO_LIBRARY}")
-  check_cxx_source_compiles(
-    "${_mocktail_execinfo_link_probe}"
-    MOCKTAIL_EXECINFO_IN_EXTERNAL_LIBRARY
-  )
-  cmake_pop_check_state()
-  if(NOT MOCKTAIL_EXECINFO_IN_EXTERNAL_LIBRARY)
-    message(FATAL_ERROR
-      "execinfo.h is available, but backtrace and backtrace_symbols cannot "
-      "be linked"
-    )
-  endif()
-  set(MOCKTAIL_EXECINFO_LINK_LIBRARY "${MOCKTAIL_EXECINFO_LIBRARY}")
-endif()
-unset(_mocktail_execinfo_link_probe)
-
 add_library(mocktail_legacy_runtime STATIC
   src/legacy/legacy_runtime.cc
   src/runtime/roblox_text_input_jni_bridge.cc
@@ -620,7 +591,6 @@ target_link_libraries(mocktail_legacy_runtime PRIVATE
   libc_shim
   mocktail_window
   mocktail_graphics_foundation
-  ${MOCKTAIL_EXECINFO_LINK_LIBRARY}
 )
 target_compile_definitions(mocktail_legacy_runtime PRIVATE
   "MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST=\"${MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST}\""
@@ -633,6 +603,7 @@ target_compile_definitions(mocktail PRIVATE
   "MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST=\"${MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST}\""
 )
 target_link_libraries(mocktail PRIVATE
+  Mocktail::VR
   mocktail_legacy_runtime
   mocktail_auth_runtime_composition
   mocktail_failure_dialog_runtime
@@ -649,6 +620,11 @@ target_link_options(mocktail PRIVATE
 )
 
 # Native FreeBSD helper for Linuxulator's unsupported DF socket option.
+# The helper is x86-64 assembly; other host architectures have nothing to
+# assemble.
+if(NOT CMAKE_SYSTEM_PROCESSOR MATCHES "^(x86_64|amd64|AMD64)$")
+  set(MOCKTAIL_BUILD_FREEBSD_SOCKET_HELPER OFF)
+endif()
 option(MOCKTAIL_BUILD_FREEBSD_SOCKET_HELPER
   "Build the native FreeBSD Linuxulator socket helper" ON)
 if(MOCKTAIL_BUILD_FREEBSD_SOCKET_HELPER)
@@ -785,33 +761,39 @@ install(CODE "
   endif()
 ")
 
+set(MOCKTAIL_PACKAGE_NAMES mocktail mocktail-nightly nightcap nightcap-nightly)
 set(MOCKTAIL_PACKAGE_NAME "mocktail" CACHE STRING
   "Native package name"
 )
+set(MOCKTAIL_PACKAGE_VERSION "${PROJECT_VERSION}" CACHE STRING
+  "Native package version"
+)
 set(MOCKTAIL_PACKAGE_VERSION_SUFFIX "" CACHE STRING
   "Native package version suffix"
 )
-if(NOT MOCKTAIL_PACKAGE_NAME STREQUAL "mocktail" AND
-   NOT MOCKTAIL_PACKAGE_NAME STREQUAL "mocktail-nightly")
+if(NOT MOCKTAIL_PACKAGE_NAME IN_LIST MOCKTAIL_PACKAGE_NAMES)
+  string(JOIN ", " MOCKTAIL_PACKAGE_NAMES_TEXT ${MOCKTAIL_PACKAGE_NAMES})
   message(FATAL_ERROR
-    "MOCKTAIL_PACKAGE_NAME must be mocktail or mocktail-nightly")
+    "MOCKTAIL_PACKAGE_NAME must be one of ${MOCKTAIL_PACKAGE_NAMES_TEXT}")
 endif()
 
 set(CPACK_PACKAGE_NAME "${MOCKTAIL_PACKAGE_NAME}")
-set(CPACK_PACKAGE_VERSION "${PROJECT_VERSION}${MOCKTAIL_PACKAGE_VERSION_SUFFIX}")
-set(CPACK_PACKAGE_VENDOR "Mocktail Project")
-set(CPACK_PACKAGE_CONTACT "komaruworld <rtysus228@gmail.com>")
-set(CPACK_PACKAGE_HOMEPAGE_URL "https://github.com/komaruworld/mocktail")
+set(CPACK_PACKAGE_VERSION
+  "${MOCKTAIL_PACKAGE_VERSION}${MOCKTAIL_PACKAGE_VERSION_SUFFIX}"
+)
+set(CPACK_PACKAGE_VENDOR "Nightcap")
+set(CPACK_PACKAGE_CONTACT "vii <coderdayton14@gmail.com>")
+set(CPACK_PACKAGE_HOMEPAGE_URL "https://github.com/CoderDayton/nightcap")
 set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "${PROJECT_DESCRIPTION}")
 set(CPACK_PACKAGE_DESCRIPTION
-  "Runs the Android x86-64 Roblox client on Linux."
+  "Runs the Android Roblox client on Linux."
 )
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_SOURCE_DIR}/LICENSE")
 set(CPACK_PACKAGING_INSTALL_PREFIX "/usr")
 set(CPACK_STRIP_FILES TRUE)
 
 set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)
-set(CPACK_DEBIAN_PACKAGE_MAINTAINER "komaruworld <rtysus228@gmail.com>")
+set(CPACK_DEBIAN_PACKAGE_MAINTAINER "vii <coderdayton14@gmail.com>")
 set(CPACK_DEBIAN_PACKAGE_SECTION "games")
 set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional")
 set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
@@ -821,15 +803,14 @@ set(CPACK_RPM_PACKAGE_LICENSE "Apache-2.0")
 set(CPACK_RPM_PACKAGE_GROUP "Amusements/Games")
 set(CPACK_RPM_PACKAGE_AUTOREQPROV ON)
 
-if(MOCKTAIL_PACKAGE_NAME STREQUAL "mocktail-nightly")
-  set(CPACK_DEBIAN_PACKAGE_CONFLICTS "mocktail")
-  set(CPACK_DEBIAN_PACKAGE_REPLACES "mocktail")
-  set(CPACK_RPM_PACKAGE_CONFLICTS "mocktail")
-else()
-  set(CPACK_DEBIAN_PACKAGE_CONFLICTS "mocktail-nightly")
-  set(CPACK_DEBIAN_PACKAGE_REPLACES "mocktail-nightly")
-  set(CPACK_RPM_PACKAGE_CONFLICTS "mocktail-nightly")
-endif()
+# Every variant installs the same /usr/bin/mocktail and /usr/share/mocktail,
+# so only one of them can be present at a time.
+set(MOCKTAIL_PACKAGE_SIBLINGS ${MOCKTAIL_PACKAGE_NAMES})
+list(REMOVE_ITEM MOCKTAIL_PACKAGE_SIBLINGS "${MOCKTAIL_PACKAGE_NAME}")
+string(JOIN ", " MOCKTAIL_PACKAGE_CONFLICTS ${MOCKTAIL_PACKAGE_SIBLINGS})
+set(CPACK_DEBIAN_PACKAGE_CONFLICTS "${MOCKTAIL_PACKAGE_CONFLICTS}")
+set(CPACK_DEBIAN_PACKAGE_REPLACES "${MOCKTAIL_PACKAGE_CONFLICTS}")
+set(CPACK_RPM_PACKAGE_CONFLICTS "${MOCKTAIL_PACKAGE_CONFLICTS}")
 include(CPack)
 
 add_dependencies(mocktail all_stubs)
@@ -839,3 +820,17 @@ add_dependencies(mocktail mocktail_webview_helper)
 if(BUILD_TESTING)
   add_subdirectory(tests)
 endif()
+
+# Native SteamVR identity/settings helper; a background client never takes scene focus.
+add_executable(nightcap-vr-settings tools/frame_video_settings/nightcap-vr-settings.cc)
+target_include_directories(nightcap-vr-settings PRIVATE tools/frame_video_settings)
+target_link_libraries(nightcap-vr-settings PRIVATE ${CMAKE_DL_LIBS})
+install(TARGETS nightcap-vr-settings RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+if(MOCKTAIL_ENABLE_VR)
+  add_executable(nightcap-vr-performance tools/frame_video_settings/performance_overlay.cc)
+  target_include_directories(nightcap-vr-performance PRIVATE include tools/frame_video_settings)
+  target_link_libraries(nightcap-vr-performance PRIVATE SDL3::SDL3 SDL3_ttf::SDL3_ttf
+    PkgConfig::FONTCONFIG ${CMAKE_DL_LIBS})
+  install(TARGETS nightcap-vr-performance RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+endif()

FAQ.md

@@ -1,65 +0,0 @@
-<!-- Modified by vii from komaruworld/mocktail. See README "About this fork". -->
-# FAQ
-
-## How do I turn Discord RPC off?
-
-RPC is on by default. It never signs in to Discord and never reads an
-account token. To turn it off, launch Nightcap once to create the config,
-then close it. Open `config.yaml`:
-
-- Native / AppImage: `~/.config/mocktail/config.yaml`
-- Flatpak: `~/.var/app/io.github.CoderDayton.nightcap/config/mocktail/config.yaml`
-
-For native installs, a custom `$XDG_CONFIG_HOME` replaces `~/.config`.
-
-Set `enabled` to `false` under `integrations.discord_rpc`. If the block is
-missing, add it under the existing `integrations` section:
-
-```yaml
-integrations:
-  discord_rpc:
-    enabled: false
-```
-
-Save the file and restart Nightcap. Set `enabled` back to `true` to turn
-RPC on again.
-
-## Can Discord count Nightcap as Roblox play time or quests?
-
-No. Discord only credits play time and quests to games its own scanner
-detects, and Rich Presence never counts. On Linux the scanner only matches
-games with a Linux entry in Discord's list. Roblox has none, so no process
-name Nightcap could use would be detected. Only Roblox or Discord can change
-that.
-
-## Where can I find logs for a bug report?
-
-Nightcap saves logs automatically. Reproduce the issue, close Nightcap, and
-attach `latest.log`:
-
-- Native / AppImage: `~/.local/state/mocktail/logs/latest.log`
-- Flatpak: `~/.var/app/io.github.CoderDayton.nightcap/.local/state/mocktail/logs/latest.log`
-
-For native installs, a custom `$XDG_STATE_HOME` replaces `~/.local/state`.
-
-## Can I play in VR?
-
-VR is experimental and lives on upstream's `vr` branch, which does not
-include the Nightcap changes. Install the
-[build dependencies](README.md#building), then switch to that branch and
-build:
-
-```bash
-git remote add upstream https://github.com/komaruworld/mocktail.git
-git fetch upstream
-git switch -c vr upstream/vr
-git submodule update --init --recursive
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DMOCKTAIL_ENABLE_VR=ON
-cmake --build build -j4
-```
-
-Start WiVRn or SteamVR/ALVR, connect your headset, then run:
-
-```bash
-./build/mocktail -vr
-```

Makefile

@@ -21,7 +21,7 @@ ANYLINUX_APPIMAGETOOL ?= appimagetool
 PREFIX ?= /usr
 FLATPAK_BUILD_DIR ?= build-flatpak
 FLATPAK_MANIFEST ?= packaging/flatpak/io.github.CoderDayton.nightcap.json
-FLATPAK_JOBS ?= 4
+FLATPAK_JOBS ?= 2
 
 define build_native_runtime
 	@git submodule update --init --recursive
@@ -130,8 +130,8 @@ auto-run: ## Build/run loop with crash summaries
 run-gles: build ## Run strict system EGL/OpenGL ES 3 without Vulkan fallback
 	@$(BINARY) --graphics opengl
 
-run-angle: ## Run with ANGLE/Vulkan compatibility backend
-	@MOCKTAIL_GRAPHICS_BACKEND=angle-vulkan ./scripts/run_sober.sh
+run-angle: build ## Run with ANGLE/Vulkan compatibility backend
+	@$(BINARY) --graphics angle-vulkan
 
 update-roblox: ## Validate and import the current x86_64 Roblox bundle cached by Sober
 	@./scripts/update_roblox_payload.sh

README.md

@@ -1,204 +1,62 @@
-<!-- Modified by vii from komaruworld/mocktail. See "About this fork" below. -->
-# Nightcap
+<div align="center">
+  <img src="packaging/io.github.CoderDayton.nightcap.svg" alt="Nightcap logo" width="128">
+  <h1>Nightcap Roblox VR for Steam Frame</h1>
+</div>
 
-[![CI](https://github.com/CoderDayton/nightcap/actions/workflows/ci.yml/badge.svg)](https://github.com/CoderDayton/nightcap/actions/workflows/ci.yml)
-[![Stars](https://img.shields.io/github/stars/CoderDayton/nightcap?style=flat&logo=github)](https://github.com/CoderDayton/nightcap/stargazers)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+Native ARM64 Roblox VR for Steam Frame, with eye-tracked foveated rendering,
+controller input and SteamVR integration.
 
-Nightcap is Mocktail, tuned for playing on a real PC. It runs the Android
-`x86_64` Roblox client on Linux, including a Linux userspace hosted by
-FreeBSD's Linuxulator. It provides the Android ABI and JNI pieces the client
-expects, then connects them to SDL3 and Vulkan or OpenGL on the Linux side.
+The standard video profile is **native 2160 × 2160 per eye**, **72 Hz**,
+**SMAA High** and **Performance** foveation. Frame rate depends on the Roblox
+experience and its graphics settings; 72 FPS is the target.
 
-Nightcap is an independent community project. It is not affiliated with Roblox
-Corporation or VinegarHQ and does not distribute the Roblox client.
+## Features
+
+- Native ARM64 execution through Nightcap's Android compatibility layer.
+- Stereo OpenXR rendering, head tracking, VR controllers, haptics and an
+  in-headset keyboard.
+- Direct eye tracking with a full-detail gaze region and gradual reductions in
+  peripheral shading quality.
+- Adjustable gaze radius and Quality, Balanced and Performance foveation modes.
+- Gaze-only FXAA, SMAA Low and SMAA High anti-aliasing.
+- Native-resolution rendering with a 2160 × 2160 per-eye recommended default.
+- Roblox's internal frame-rate cap follows the selected headset refresh rate.
+- Renderer and session handling across menu, game and game-to-game transitions.
+- Native microphone capture bridge for Roblox voice chat.
+- One **Nightcap Roblox VR** Steam entry with the original Nightcap icon and an
+  optional desktop mirror. The mirror is off by default on Steam Frame.
+- Simple **Foveated Rendering**, **Gaze sharp radius** and **Anti Aliasing**
+  controls in SteamVR's Video settings.
+- Optional in-headset performance overlay with actual game FPS, headset Hz,
+  frame time, GPU time and current per-eye resolution.
+
+## Install
+
+Install the native ARM64 build from [Releases](https://github.com/InstanceBrick/nightcap/releases),
+or build it on the Frame using the [installation guide](docs/INSTALL.md).
+The ARM64 package contains Nightcap and its open-source runtime dependencies.
+Roblox is downloaded separately on the device. Roblox binaries, account data,
+SteamVR files and the Frame's graphics drivers are not included in the package.
+
+Current ARM64 client support: **2.742.1059 (3222)** and **2.736.1408 (2998)**.
+
+- [Installation and updates](docs/INSTALL.md)
+- [Video, input and microphone settings](docs/SETTINGS.md)
+- [Building and source layout](docs/DEVELOPMENT.md)
 
 ## About this fork
 
-Nightcap is a fork of [komaruworld/mocktail](https://github.com/komaruworld/mocktail)
-with extra fixes for playing on a PC. The program and config paths keep the
-`mocktail` name so upstream fixes still apply cleanly. The app ID is
-`io.github.CoderDayton.nightcap`, so Nightcap and upstream can be installed
-side by side.
-
-- **Lower input lag.** Frames are shown as soon as they are ready instead of
-  waiting in a queue.
-- **Sharper textures.** Small textures are upscaled 4x by default, and you
-  can replace any texture with your own PNG in `~/.config/mocktail/textures`.
-  Set `MOCKTAIL_SMALL_TEXTURE_UPSCALE=1` to turn the upscale off.
-- **ETC2 textures on any GPU.** Games that use compressed mobile textures now
-  render correctly on desktop GPUs, without stutter.
-- **No more error 319 kicks.** Servers no longer drop you shortly after
-  joining.
-- **Correct device info.** Roblox sees your real RAM and screen size.
-- **Better desktop launcher.** Runs on Wayland and always finds the installed
-  binary.
-
-Everything else works the same as upstream. See the
-[roadmap](docs/ROADMAP.md) for what is coming next, the
-[changelog](CHANGELOG.md) for what each release changed, and the
-[FAQ](FAQ.md) for Discord RPC, logs, and VR.
-
-## Install with Flatpak
-
-```bash
-flatpak install --user https://coderdayton.github.io/nightcap/nightcap.flatpakref
-flatpak run io.github.CoderDayton.nightcap
-```
-
-Updates arrive through `flatpak update`. Nightcap is not on Flathub yet.
-
-## AppImage
-
-Grab the AppImage from the
-[latest release](https://github.com/CoderDayton/nightcap/releases/latest),
-make it executable, and run it:
-
-```bash
-chmod +x Nightcap-x86_64.AppImage
-./Nightcap-x86_64.AppImage
-```
-
-Or build and install it from source using the steps under
-[Building](#building). There are no AUR, DEB, or RPM packages of Nightcap.
-Upstream ships those for unmodified Mocktail, see
-[komaruworld/mocktail](https://github.com/komaruworld/mocktail#readme).
-
-## How it works
-
-```
-Roblox APK -> signature and ABI checks -> Bionic + JNI -> SDL3 + Vulkan/OpenGL
-```
-
-The APK is checked before any native code is loaded. It is downloaded on first
-launch and is not bundled with Nightcap. The last working copy is kept in case
-an update fails.
-
-<details>
-<summary>Screenshots</summary>
-
-![Roblox home in Nightcap](assets/screenshots/flatpak-home.png)
-
-![Roblox gameplay in Nightcap](assets/screenshots/flatpak-gameplay-tower.png)
-
-![Roblox experience in Nightcap](assets/screenshots/flatpak-gameplay-lobby.png)
-
-</details>
-
-## FFlag overrides
-
-Put a JSON object in `$XDG_CONFIG_HOME/mocktail/fflags.json` (usually
-`~/.config/mocktail/fflags.json`). Nightcap applies it on the next launch.
-
-PC profiles use the legacy Charts page by default to avoid the blank screen
-caused by `Color3` errors in the newer SDUI page. An explicit
-`FFlagLuaAppChartsAppPage` override takes precedence over this default.
-
-```json
-{
-  "FFlagExample": "True",
-  "DFIntExample": "120"
-}
-```
-## Settings
-
-Edit `~/.config/mocktail/config.yaml`. Useful options:
-
-- `graphics.frame_rate_limit: display` to unlock FPS to your monitor's rate.
-- `graphics.vsync: off` for the lowest lag, at the cost of tearing.
-- `graphics.backend: opengl` if Vulkan does not work on your GPU.
-
-## Building
-
-Linux `x86_64` is supported. Experimental FreeBSD 15.1 Linuxulator support has
-been tested with an `x86_64` Fedora 44 userspace. On FreeBSD, Nightcap runs
-inside Linuxulator; it is not a native FreeBSD binary. Building requires CMake
-3.20+, Git, pkg-config, LLD, binutils, a C++17 compiler, SDL 3.4+, SDL3_ttf,
-Vulkan, EGL, libplacebo, fontconfig, libcurl, OpenSSL, libelf, libyaml, minizip,
-Capstone 5, utf8proc, nlohmann/json, GTK4, libadwaita 1.6+, and WebKitGTK 6.0.
-
-See the [FreeBSD Guide](packaging/freebsd/README.md) for setup and launch instructions.
-
-<details>
-<summary>Ubuntu 26.04+</summary>
-
-```bash
-sudo apt update
-sudo apt install build-essential cmake git ninja-build pkg-config lld \
-  libsdl3-dev libsdl3-ttf-dev libcurl4-openssl-dev libssl-dev \
-  nlohmann-json3-dev libyaml-dev libelf-dev libminizip-dev \
-  libcapstone-dev libgtk-4-dev libadwaita-1-dev libwebkitgtk-6.0-dev \
-  libutf8proc-dev libfontconfig1-dev libegl-dev libvulkan-dev \
-  libplacebo-dev zlib1g-dev
-```
-</details>
-
-<details>
-<summary>Arch Linux</summary>
-
-```bash
-sudo pacman -S --needed base-devel cmake git ninja pkgconf lld sdl3 sdl3_ttf \
-  curl openssl nlohmann-json libyaml libelf minizip capstone gtk4 \
-  libadwaita webkitgtk-6.0 libutf8proc fontconfig libglvnd \
-  libplacebo vulkan-headers vulkan-icd-loader zlib
-```
-</details>
-
-<details>
-<summary>Fedora 44+</summary>
-
-```bash
-sudo dnf install gcc-c++ cmake git ninja-build pkgconf-pkg-config lld \
-  SDL3-devel SDL3_ttf-devel libcurl-devel openssl-devel \
-  nlohmann-json-devel libyaml-devel elfutils-libelf-devel minizip-ng-compat-devel \
-  capstone-devel gtk4-devel libadwaita-devel webkitgtk6.0-devel \
-  utf8proc-devel fontconfig-devel libglvnd-devel vulkan-headers \
-  vulkan-loader-devel libplacebo-devel zlib-ng-compat-devel
-```
-</details>
-
-```bash
-git clone --recurse-submodules https://github.com/CoderDayton/nightcap.git
-cd nightcap
-make build
-./build/mocktail
-```
-
-To install it for your user, with an app menu entry and Roblox link handling:
-
-```bash
-make install PREFIX=~/.local
-```
-
-Use `sudo make install` instead to install system-wide under `/usr`. To make
-Roblox website links open the build tree copy without installing, run
-`make register-url-handler`.
-
-To run the same checks as CI before each commit and push, install
-[lefthook](https://github.com/evilmartians/lefthook) and run once:
-
-```bash
-lefthook install
-```
-
-## Known limitations
-
-Nightcap does not currently work with `hardened_malloc`. Using
-`hardened_malloc` may cause Nightcap to fail to start or crash during runtime.
-Run Nightcap without `hardened_malloc` enabled.
+The `steam-frame` branch is the Steam Frame edition of the `vr` branch of
+[CoderDayton/nightcap](https://github.com/CoderDayton/nightcap), itself a fork of
+[komaruworld/mocktail](https://github.com/komaruworld/mocktail). It adds the native
+ARM64 VR bridge and Frame rendering, input, audio and Steam integration changes.
+The original Nightcap artwork is retained. Internal executable and configuration
+names keep `mocktail` for compatibility with the upstream source.
 
 ## License
 
-[Apache License 2.0](LICENSE). Third-party components keep their own licenses.
+[Apache License 2.0](LICENSE). Original copyright notices and third-party
+licenses remain in their source directories. See [third-party credits](THIRD_PARTY.md).
 
-## Support
-
-Support this fork by giving it a star or with cryptocurrency:
-
-- LTC: `LdABR2ELRYrUESWZWrEk1uNx38gHHMuHUU`
-- SOL: `tjeDnPoWeyW8zfTf8c5CVAm5QTV8vFPaPouaScAdwfT`
-
-Support the upstream project, which does most of the heavy lifting:
-
-- USDT (TON): `UQCi6Yzcc9cOctoij6n_r1K90-OdVxAT0D_xo2UzGKkQaJDY`
-- USDT (TRC20): `TNPMG9Vig2xiuo2r1QqnXRChPH7Vu28Jmx`
+Nightcap is an independent community project and is not affiliated with Roblox
+Corporation or Valve.

THIRD_PARTY.md

@@ -0,0 +1,31 @@
+# Credits and third-party components
+
+This edition includes modifications for Steam Frame ARM64 and is based on:
+
+- [Nightcap](https://github.com/CoderDayton/nightcap), including vii's changes to
+  Mocktail and the upstream `vr` branch.
+- [Mocktail](https://github.com/komaruworld/mocktail), by the Mocktail project
+  authors.
+
+The Steam Frame edition incorporates the upstream VR tree through
+[`753a3f81`](https://github.com/CoderDayton/nightcap/commit/753a3f8106e4d7fdafea457601a5ff238e77c2d0)
+(15 October 2026), including GPU-ordered presentation, asynchronous eye and
+mirror copies, cached JNI method dispatch, headset detection and the JNI haptic
+protocol. ARM64 client contracts and Frame gaze AA remain platform-specific.
+
+The project is distributed under the [Apache License 2.0](LICENSE). Existing
+copyright and modification notices are retained in the source.
+
+Third-party components retain their own licenses and notices, including the
+Android/Bionic linker sources under `third_party/mcpelauncher-linker`, the pinned
+OpenXR SDK, Vulkan headers and libjnivm submodules, SMAA under `src/vr/smaa`, AMD FidelityFX FSR 1 under `src/vr/fsr`
+([MIT license](src/vr/fsr/LICENSE.txt)),
+AMD FidelityFX SDK 1.1.4's FSR 3.1.4 upscaler, Optical Flow component and Vulkan
+backend under `third_party/fidelityfx`
+([MIT license](third_party/fidelityfx/LICENSE.txt)), and
+the OpenVR interface header under `tools/frame_video_settings`. The original
+Nightcap icon and artwork are retained from the upstream project.
+
+Roblox client binaries and Valve SteamVR dashboard assets are not included.
+The client is downloaded separately and the Video settings tools read dashboard
+files from the user's installed SteamVR copy.

build-frame-nightcap.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+cmake -S /work -B /work/build-frame-arm64 -G Ninja -DCMAKE_BUILD_TYPE=Release -DMOCKTAIL_ENABLE_VR=ON -DMOCKTAIL_ENABLE_FSR3=OFF -DMOCKTAIL_VR_DIAGNOSTICS=OFF -DBUILD_TESTING=OFF -DMOCKTAIL_BUILD_FREEBSD_SOCKET_HELPER=OFF -DCMAKE_INSTALL_PREFIX=/opt/nightcap-vr-arm64
+cmake --build /work/build-frame-arm64 -j3
+cmake --install /work/build-frame-arm64
+c++ -std=c++17 -O2 /work/tools/frame_video_settings/nightcap-vr-settings.cc -ldl -o /opt/nightcap-vr-arm64/bin/nightcap-vr-settings
+printf 'NIGHTCAP_ARM64_BUILD_COMPLETE\n'

cmake/MocktailInput.cmake

@@ -22,6 +22,7 @@ add_library(mocktail_input_runtime STATIC
   ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_text_font_resolver.cc
   ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_text_surface_overlay.cc
   ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_window_input_runtime.cc
+  ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_xr_controller_input.cc
 )
 add_library(Mocktail::InputRuntime ALIAS mocktail_input_runtime)
 target_include_directories(mocktail_input_runtime PUBLIC
@@ -33,12 +34,14 @@ target_include_directories(mocktail_input_runtime PRIVATE
 target_link_libraries(mocktail_input_runtime PUBLIC
   Mocktail::PlatformSdl
   Mocktail::Runtime
+  Mocktail::VR
   mocktail_window
   PkgConfig::UTF8PROC
   PRIVATE
     PkgConfig::FONTCONFIG
     SDL3_ttf::SDL3_ttf
     nlohmann_json::nlohmann_json
+    ${CMAKE_DL_LIBS}
 )
 target_compile_features(mocktail_input_runtime PUBLIC cxx_std_17)
 mocktail_apply_compile_options(mocktail_input_runtime)
@@ -47,6 +50,7 @@ if(BUILD_TESTING AND TARGET GTest::gtest_main)
   add_executable(roblox_input_router_test
     ${MOCKTAIL_INPUT_ROOT}/tests/roblox_gamepad_input_test.cc
     ${MOCKTAIL_INPUT_ROOT}/tests/roblox_input_router_test.cc
+    ${MOCKTAIL_INPUT_ROOT}/tests/roblox_xr_controller_input_test.cc
   )
   target_link_libraries(roblox_input_router_test PRIVATE
     Mocktail::InputRuntime

cmake/MocktailVR.cmake

@@ -0,0 +1,121 @@
+# Copyright 2026 Mocktail Project Authors
+# Licensed under the Apache License, Version 2.0.
+
+include_guard(GLOBAL)
+
+option(MOCKTAIL_ENABLE_FSR3 "Build the optional temporal upscaler SDK" OFF)
+
+# AUTO builds OpenXR support when the third_party/OpenXR-SDK submodule is
+# checked out and skips it otherwise, so source packages that do not fetch
+# submodules still build. ON requires the submodule; OFF never builds it.
+set(MOCKTAIL_ENABLE_VR "AUTO" CACHE STRING
+  "Build experimental OpenXR support: AUTO, ON or OFF")
+set_property(CACHE MOCKTAIL_ENABLE_VR PROPERTY STRINGS AUTO ON OFF)
+set(_mocktail_openxr_sdk "${CMAKE_SOURCE_DIR}/third_party/OpenXR-SDK/CMakeLists.txt")
+string(TOUPPER "${MOCKTAIL_ENABLE_VR}" _mocktail_vr_request)
+if(_mocktail_vr_request STREQUAL "AUTO")
+  if(EXISTS "${_mocktail_openxr_sdk}" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    set(MOCKTAIL_ENABLE_VR ON)
+  else()
+    message(STATUS "OpenXR SDK submodule not found; building without VR "
+      "(git submodule update --init third_party/OpenXR-SDK to enable it)")
+    set(MOCKTAIL_ENABLE_VR OFF)
+  endif()
+elseif(MOCKTAIL_ENABLE_VR)
+  set(MOCKTAIL_ENABLE_VR ON)
+else()
+  set(MOCKTAIL_ENABLE_VR OFF)
+endif()
+
+add_library(mocktail_vr STATIC
+  src/vr/gaze_aa.cc
+  src/vr/fsr_upscaler.cc
+  src/vr/fsr3_scene_capture.cc
+  src/vr/diagnostics.cc
+  src/vr/headset_detection.cc
+  src/vr/openxr_backend_mode.cc
+  src/vr/vr_perf.cc
+  src/vr/vr_mirror.cc
+  src/vr/xr_controller.cc
+  src/vr/roblox_vr_device_bridge.cc
+  src/vr/virtual_keyboard.cc)
+add_library(Mocktail::VR ALIAS mocktail_vr)
+target_include_directories(mocktail_vr PUBLIC "${CMAKE_SOURCE_DIR}/include")
+target_include_directories(mocktail_vr PRIVATE "${CMAKE_SOURCE_DIR}/src")
+target_link_libraries(mocktail_vr PUBLIC Vulkan::Headers PRIVATE nlohmann_json::nlohmann_json)
+# shm_open for the desktop eye mirror lives in librt on glibc.
+find_library(MOCKTAIL_RT_LIBRARY rt)
+if(MOCKTAIL_RT_LIBRARY)
+  target_link_libraries(mocktail_vr PUBLIC ${MOCKTAIL_RT_LIBRARY})
+endif()
+mocktail_apply_compile_options(mocktail_vr)
+
+if(MOCKTAIL_ENABLE_VR)
+  if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    message(FATAL_ERROR "Mocktail OpenXR support currently targets Linux")
+  endif()
+  if(NOT EXISTS "${_mocktail_openxr_sdk}")
+    message(FATAL_ERROR
+      "Initialize OpenXR: git submodule update --init third_party/OpenXR-SDK")
+  endif()
+
+  # Scope upstream's generic option names to this dependency. Static linking
+  # packages the pinned loader without requiring a matching system loader.
+  function(mocktail_add_openxr_sdk)
+    set(BUILD_LOADER ON)
+    set(DYNAMIC_LOADER OFF)
+    set(BUILD_WITH_SYSTEM_JSONCPP OFF)
+    set(BUILD_TESTS OFF)
+    set(BUILD_API_LAYERS OFF)
+    set(BUILD_CONFORMANCE_TESTS OFF)
+    set(BUILD_SDK_TESTS OFF)
+    set(BUILD_FORCE_GENERATION OFF)
+    add_subdirectory("${CMAKE_SOURCE_DIR}/third_party/OpenXR-SDK"
+      "${CMAKE_BINARY_DIR}/third_party/OpenXR-SDK" EXCLUDE_FROM_ALL)
+  endfunction()
+  mocktail_add_openxr_sdk()
+  if(MOCKTAIL_ENABLE_FSR3)
+    add_subdirectory(third_party/fidelityfx)
+    target_sources(mocktail_vr PRIVATE src/vr/fsr3_upscaler.cc src/vr/fsr3_gaze_transport.cc)
+    target_link_libraries(mocktail_vr PRIVATE nightcap_fsr3)
+    target_compile_definitions(mocktail_vr PUBLIC MOCKTAIL_ENABLE_FSR3=1)
+  endif()
+  target_sources(mocktail_vr PRIVATE src/vr/openxr_probe.cc src/vr/openxr_preview.cc
+    src/vr/openxr_backend.cc src/vr/xr_foveation_maps.cc src/vr/gles_transport.cc src/vr/xr_actions.cc
+    src/vr/virtual_keyboard_raster.cc)
+  # The in-headset keyboard draws its labels with the same SDL3_ttf and
+  # fontconfig stack as the TextBox overlay.
+  find_package(SDL3 3.4 REQUIRED CONFIG)
+  find_package(SDL3_ttf REQUIRED CONFIG)
+  find_package(PkgConfig REQUIRED)
+  pkg_check_modules(FONTCONFIG REQUIRED IMPORTED_TARGET fontconfig)
+  target_link_libraries(mocktail_vr PRIVATE SDL3_ttf::SDL3_ttf SDL3::SDL3
+    PkgConfig::FONTCONFIG)
+  # Error unwinding is confined to these native session implementations; their
+  # public entry points catch errors before returning to the guest runtime.
+  set_source_files_properties(src/vr/openxr_preview.cc src/vr/openxr_backend.cc
+    src/vr/xr_actions.cc src/vr/xr_foveation_maps.cc
+    PROPERTIES COMPILE_OPTIONS -fexceptions)
+  target_compile_definitions(mocktail_vr PRIVATE XR_USE_GRAPHICS_API_VULKAN)
+  option(MOCKTAIL_VR_DIAGNOSTICS
+    "Compile VR diagnostics: scripted head pose, eye evidence dumps" OFF)
+  if(MOCKTAIL_VR_DIAGNOSTICS)
+    target_compile_definitions(mocktail_vr PRIVATE MOCKTAIL_VR_DIAGNOSTICS=1)
+  endif()
+  set_source_files_properties(src/vr/openxr_backend.cc PROPERTIES COMPILE_DEFINITIONS "XR_USE_GRAPHICS_API_OPENGL_ES;XR_USE_PLATFORM_EGL")
+  target_include_directories(mocktail_vr PRIVATE ${MOCKTAIL_EGL_INCLUDE_DIR} ${MOCKTAIL_GLES3_INCLUDE_DIR})
+  target_link_libraries(mocktail_vr PRIVATE OpenXR::openxr_loader Vulkan::Headers ${CMAKE_DL_LIBS})
+else()
+  target_sources(mocktail_vr PRIVATE src/vr/openxr_disabled.cc
+    src/vr/xr_actions_disabled.cc src/vr/xr_foveation_maps_disabled.cc)
+endif()
+
+if(MOCKTAIL_ENABLE_VR)
+  add_executable(mocktail_vr_probe src/vr/probe_main.cc)
+  set_target_properties(mocktail_vr_probe PROPERTIES
+    OUTPUT_NAME mocktail-vr-probe)
+  target_link_libraries(mocktail_vr_probe PRIVATE Mocktail::VR)
+  mocktail_apply_compile_options(mocktail_vr_probe)
+  install(TARGETS mocktail_vr_probe
+    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}")
+endif()

config/mocktail.example.yaml

@@ -28,7 +28,7 @@ device: pc-windows-11
 runtime:
   # Boolean (default: false): start without a visible SDL window.
   headless: false
-  # String (optional): use a specific x86_64 libroblox.so instead of the
+  # String (optional): use a specific native-architecture libroblox.so instead of the
   # active verified payload.
   # roblox_library: /absolute/path/to/libroblox.so
 
@@ -52,6 +52,31 @@ graphics:
   # unless frame_rate_limit is unlimited.
   # vsync: off
 
+# vr:
+  # String (default: off): experimental VR through OpenXR on supported Roblox
+  # builds (ARM64: 2998 and 3222). off starts on the desktop; on starts in
+  # VR like --vr. auto starts in VR when SteamVR is already running with a connected
+  # headset (ALVR included), and on the desktop otherwise. auto never starts
+  # SteamVR. --vr and --no-vr override this for one launch. The older
+  # enabled: true/false still works as on/off; set one or the other.
+  # Standalone OpenXR test scene: mocktail-vr-probe --scene.
+  # mode: off
+  # Boolean (default: true): also show the left-eye VR view in the desktop
+  # window. Restart Nightcap after changing this setting. Steam Frame
+  # uses its Video settings Desktop Mirror control, off by default.
+  # desktop_mirror: true
+  # String (default: fxaa): smooth jagged edges in the headset. Roblox draws
+  # the VR eyes without anti-aliasing; fxaa filters each eye on its way to the
+  # headset. The Steam Frame profile uses its separate gaze AA control.
+  # off sends the eyes as rendered.
+  # anti_aliasing: fxaa
+  # Optional string or integer: frame-rate limit used instead of
+  # graphics.frame_rate_limit while VR is active. Same values: -1 (Roblox's
+  # own cap, usually 60), display, unlimited, or any positive integer. The
+  # default, unlimited, lets the OpenXR runtime pace frames at the headset's
+  # refresh rate.
+  # frame_rate_limit: unlimited
+
 performance:
   # Boolean (default: false): size Roblox scheduler/render queues from every
   # physical CPU core. A place's Lua/main thread can still remain serial.
@@ -112,12 +137,24 @@ integrations:
       public_servers_only: true
       # button_label: Join Server
     # English defaults. Uncomment only the lines you want to customize.
+    # Text and image fields accept {place_name}, {place_icon}, and
+    # {creator_name}. A field that expands an empty placeholder is left out,
+    # and a "" title shows the app name.
+    # title, state, and the images fields may be "" to hide them.
     # text:
     #   browsing: Browsing experiences
     #   joining: Joining an experience
-    #   playing: "{place_name}"
-    #   state: Playing Roblox
+    #   playing: "Playing {place_name}"
+    #   state: "by {creator_name}"
     #   unknown_place: Unknown experience
+    #   title: Roblox
+    # Images take an https:// URL, or an asset key uploaded to application_id.
+    # large: "" hides both images; the small image needs a large one.
+    # images:
+    #   large: "{place_icon}"
+    #   large_text: "{place_name}"
+    #   small: roblox_small
+    #   small_text: Roblox
     # Advanced: overrides the application bundled by the package maintainer.
     # application_id: 123456789012345678
 

config/roblox_compatibility.json

@@ -4,6 +4,7 @@
     {
       "version_name": "2.721.1108",
       "version_code": 2350,
+      "abi": "x86_64",
       "elf_build_id": "50e1b0abd123350e794226062fe3a1ef360c5f0d",
       "status": "legacy-researched",
       "default_allowed": false,
@@ -15,6 +16,7 @@
     {
       "version_name": "2.725.1142",
       "version_code": 2546,
+      "abi": "x86_64",
       "elf_build_id": "d0cb1fa0deb3d9161b4cd77530cbcd2e50de3a21",
       "status": "supported",
       "default_allowed": true,
@@ -35,6 +37,7 @@
     {
       "version_name": "2.727.1199",
       "version_code": 2628,
+      "abi": "x86_64",
       "elf_build_id": "1686400865ae0e408cd7bd67de7a439625c6fd13",
       "status": "supported",
       "default_allowed": true,
@@ -46,6 +49,7 @@
     {
       "version_name": "2.734.917",
       "version_code": 2908,
+      "abi": "x86_64",
       "elf_build_id": "63c5109637b7d7b2bdb8ed8f858023ff5ef49326",
       "status": "supported",
       "default_allowed": true,
@@ -66,6 +70,32 @@
     {
       "version_name": "2.736.1408",
       "version_code": 2998,
+      "abi": "arm64-v8a",
+      "elf_build_id": "ed2b035768b1513561d0e6ea7f9bbec35b0e60e5",
+      "status": "supported",
+      "default_allowed": true,
+      "allow_legacy_binary_patches": false,
+      "allow_host_abi_bridges": true,
+      "allow_host_constructor_replay": true,
+      "reason": "AArch64 arm64-v8a payload of the same 2.736.1408 release as the verified x86-64 profile; allocator, constructor replay, and pre-JNI bootstrap RVAs were derived by cross-architecture semantic matching.",
+      "fmod_output_device_bridge": {
+        "vtable_rva": "0x632aeb0",
+        "string_constructor_rva": "0x1d5a6b0",
+        "count_method_rva": "0x2f96540",
+        "info_method_rva": "0x2f96600",
+        "current_method_rva": "0x2f965a0",
+        "select_method_rva": "0x2f962d4",
+        "input_count_method_rva": "0x2f968b4",
+        "input_info_method_rva": "0x2f968c4",
+        "input_current_method_rva": "0x2f9697c",
+        "input_select_method_rva": "0x2f96088",
+        "vtable_layout_version": 1
+      }
+    },
+    {
+      "version_name": "2.736.1408",
+      "version_code": 2998,
+      "abi": "x86_64",
       "elf_build_id": "ade08266c67aee88ec9c1d00902150e1684dad3a",
       "status": "supported",
       "default_allowed": true,
@@ -85,7 +115,80 @@
         "input_current_method_rva": "0x32d13a6",
         "input_select_method_rva": "0x32d0a56"
       },
-      "reason": "Verified 2026-09-06: exact Build-ID profile passed two isolated no-recovery Tier C Vulkan canaries and real game sessions, including fullscreen state synchronization and host FMOD output-device interposition; legacy executable patches and signal recovery remain disabled."
+      "vr_debug_device_bridge": {
+        "vtable_rva": "0x6c87b38",
+        "constructor_rva": "0x3810614",
+        "state_getter_rva": "0x38109f6",
+        "eye_getter_rva": "0x38109e6",
+        "eye_initializer_rva": "0x3810a18",
+        "emulator_flag_storage_rva": "0x7369920",
+        "device_create_framebuffer_vtable_offset": "0x180"
+      },
+      "reason": "Verified 2026-09-06: exact Build-ID profile passed two isolated no-recovery Tier C Vulkan canaries and real game sessions, including fullscreen state synchronization and host FMOD output-device interposition; legacy executable patches and signal recovery remain disabled. Experimental vr_debug_device_bridge metadata (DebugDeviceVR constructor/state/eye/initializer RVAs) is machine-validated at activation and gated behind --vr; native stereo output is not yet verified end-to-end."
+    },
+    {
+      "allow_host_abi_bridges": true,
+      "allow_host_constructor_replay": true,
+      "allow_legacy_binary_patches": false,
+      "default_allowed": true,
+      "elf_build_id": "5f0704edd9064f566ee3d6df2bd2fabbcc709f03",
+      "fmod_output_device_bridge": {
+        "count_method_rva": "0x320c676",
+        "current_method_rva": "0x320c6c6",
+        "info_method_rva": "0x320c716",
+        "select_method_rva": "0x320bf78",
+        "string_constructor_rva": "0x1d7a038",
+        "vtable_layout_version": 2,
+        "vtable_rva": "0x6cd3ce0"
+      },
+      "reason": "Exact-Build-ID host ABI promoted from the validated probation profile; native stereo, VR state/pointer/haptic contracts and FMOD output-device layout v2 were re-derived for 3092. Experimental: runs when selected explicitly (--roblox-lib) but is never an update target, so non-VR users stay on the default payload.",
+      "status": "experimental",
+      "user_game_settings_fullscreen_setter_rva": "0x45c5f42",
+      "version_code": 3092,
+      "version_name": "2.738.1397",
+      "vr_debug_device_bridge": {
+        "vtable_rva": "0x6d08108",
+        "constructor_rva": "0x37f9fe4",
+        "state_getter_rva": "0x37fa3c6",
+        "eye_getter_rva": "0x37fa3b6",
+        "eye_initializer_rva": "0x37fa3e8",
+        "emulator_flag_storage_rva": "0x73f4690",
+        "device_create_framebuffer_vtable_offset": "0x188"
+      }
+    },
+    {
+      "version_name": "2.742.1059",
+      "version_code": 3222,
+      "abi": "arm64-v8a",
+      "elf_build_id": "25aa7fd31008a744c3c99f717e7d16d81d371d12",
+      "status": "supported",
+      "default_allowed": true,
+      "allow_legacy_binary_patches": false,
+      "allow_host_abi_bridges": true,
+      "allow_host_constructor_replay": true,
+      "reason": "Verified on Steam Frame 2026-10-15: signed ARM64 3222 payload, exact allocator/bootstrap and reordered constructor roles, VR state/pointer/reflection/framebuffer contracts and layout-2 FMOD bridge; native startup, two distinct eye bindings at 2592x2592, real OpenXR projection and controlled experience transitions. Worn-headset quality and remote voice audibility remain unconfirmed.",
+      "fmod_output_device_bridge": {
+        "vtable_rva": "0x6569770",
+        "string_constructor_rva": "0x1e47180",
+        "count_method_rva": "0x2c35714",
+        "info_method_rva": "0x2c357d4",
+        "current_method_rva": "0x2c35774",
+        "select_method_rva": "0x2c34f18",
+        "input_count_method_rva": "0x2c35d58",
+        "input_info_method_rva": "0x2c35d68",
+        "input_current_method_rva": "0x2c361a0",
+        "input_select_method_rva": "0x2c34c80",
+        "vtable_layout_version": 2
+      },
+      "vr_debug_device_bridge": {
+        "vtable_rva": "0x67b6688",
+        "constructor_rva": "0x4e5558c",
+        "state_getter_rva": "0x4e55964",
+        "eye_getter_rva": "0x4e55958",
+        "eye_initializer_rva": "0x4e55974",
+        "emulator_flag_storage_rva": "0x6c0d1b0",
+        "device_create_framebuffer_vtable_offset": "0x188"
+      }
     }
   ]
 }

config/steam-frame.example.yaml

@@ -0,0 +1,20 @@
+version: 1
+device: pc-windows-11
+
+graphics:
+  backend: direct-vulkan
+  vsync: off
+
+vr:
+  enabled: true
+  desktop_mirror: false
+  frame_rate_limit: unlimited
+
+audio:
+  output_device: default
+  input_device: default
+
+updates:
+  automatic: false
+  launch_after_update: false
+  source: auto

config/upstream_dependencies.json

@@ -32,7 +32,7 @@
       "mode": "vendored-patched-snapshot",
       "url": "https://github.com/minecraft-linux/mcpelauncher-linker.git",
       "upstream_commit": "1ac3ea6c1cf4f73a84d73f0bff510fba94a7d0f2",
-      "vendor_tree": "fca44d85e3773c135ccfc603b14abdf6aeb8efd1",
+      "vendor_tree": "0637221e48f382ec8d0bc701385f4b10bcd07a65",
       "patch": "third_party/patches/mcpelauncher-linker.patch",
       "nested_sources": {
         "android_bionic": {

docs/DEVELOPMENT.md

@@ -0,0 +1,203 @@
+# Building and source layout
+
+The [installation guide](INSTALL.md) covers a complete source build on Steam
+Frame. The container recipe uses Fedora 44 ARM64 with CMake, Ninja, SDL3,
+OpenXR, Vulkan, WebKitGTK and Nightcap's other native dependencies.
+The Frame build enables OpenXR and the ARM64 bridge, disables runtime
+diagnostics, and uses native rendering. Fedora's `glslang` and `spirv-tools`
+packages are included for shader generation and validation. The ARM64 workflow
+builds the same container recipe and checks the package before export.
+
+## Upstream source
+
+This branch includes Nightcap's `vr` additions through
+[`adccf4e4841275bce85d0330013367e2c124bd10`](https://github.com/CoderDayton/nightcap/commit/adccf4e4841275bce85d0330013367e2c124bd10),
+including all changes from its `main` branch at that revision. The update adds
+emoji fallback fonts for native text fields, decoded/compressed emulated-texture
+byte counters, menu-only native Luau compilation, and queued game switching.
+Menu compilation is enabled only after validating the native flag on ARM64;
+explicit client settings remain in control.
+
+Frame already uses the same reference SMAA revision as this update. Its existing
+gaze AA path is retained without adding a second full-eye filter. Frame's native
+2160 × 2160 rendering, 72 Hz profile, simple Video controls, controllers, audio
+and foveation integration remain the platform defaults.
+
+## Build scripts
+
+`build-frame-nightcap.sh` configures a Release build at `/work/build-frame-arm64`
+and installs to `/opt/nightcap-vr-arm64`. VR is enabled and runtime diagnostics
+are disabled. It also builds the Steam application identity helper.
+
+For incremental development in an existing Frame image, with Nightcap closed:
+
+```bash
+podman run --arch arm64 --name nightcap-frame-development \
+  --cpus 3 --memory 8g --security-opt label=disable \
+  -v "$PWD:/work" --entrypoint /bin/bash \
+  localhost/nightcap-vr-arm64:frame-foveated -lc \
+  'bash /work/build-frame-nightcap.sh && bash /work/test-arm64-bridge.sh'
+```
+
+The test script runs focused ARM64 bridge, pose, controller, lifecycle, JNI,
+audio and host ABI tests, including the native assembly return-value fixture.
+It also builds the GPU test tools. Build and test commands share one CMake tree;
+run them sequentially.
+
+## Main components
+
+| Path | Purpose |
+| --- | --- |
+| `src/vr/` | OpenXR lifecycle, gaze, stereo eye transport, controllers, AA and foveation maps |
+| `src/vr/roblox_vr_arm64_build_contracts.h` | Selects exact ARM64 client contracts |
+| `src/vr/roblox_vr_arm64_contract*.h` | Client-specific ARM instruction and object layout contracts |
+| `src/audio/` | Audio playback and microphone recording bridges |
+| `src/compat/host_abi_profile.cc` | Client startup, allocator and native host ABI profiles |
+| `src/graphics/vulkan_foveation_adapter.inc` | Scene rendering integration for density maps |
+| `tools/steam_frame/` | Frame launcher, Steam shortcut and Video settings integration |
+| `tools/frame_video_settings/` | OpenVR settings, refresh-rate and timing helpers |
+| `config/roblox_compatibility.json` | Supported client identities and compatibility metadata |
+| `config/steam-frame.example.yaml` | Initial Frame runtime settings |
+
+## Client compatibility
+
+The ARM64 bridge supports these client identities:
+
+| Version | Build | ELF build ID |
+| --- | --- | --- |
+| 2.742.1059 | 3222 | `25aa7fd31008a744c3c99f717e7d16d81d371d12` |
+| 2.736.1408 | 2998 | `ed2b035768b1513561d0e6ea7f9bbec35b0e60e5` |
+
+New clients can change native methods, virtual tables, object fields and startup
+ordering. Add matching ARM64 contracts and host/audio profiles before enabling a
+new client. Keep the existing signature and build identity checks in place.
+
+The timing helper in `tools/frame_video_settings/frame_timings.cc` reports the
+scene process, dashboard visibility, headset activity and compositor throttling
+alongside frame times. Compare the same view in the same experience while the
+headset is displaying projection frames. Standby or desktop-only frames do not
+measure active VR throughput.
+
+Shader sources and their generated SPIR-V header are included. Regenerating the
+AA shaders with `tools/compile_gaze_aa.py` additionally needs `glslangValidator`.
+The SMAA sources retain their upstream license in `src/vr/smaa/`.
+
+## Native rendering
+
+The shipping Frame profile uses native rendering with gaze anti-aliasing.
+MSAA and upscaling controls are absent from the Frame Video settings. The build
+sets `MOCKTAIL_ENABLE_FSR3=OFF`, so the FidelityFX SDK is not linked into the
+Frame runtime. Reference upscaler sources and their licenses remain in the tree.
+
+To regenerate the gaze AA shaders after changing them:
+
+```sh
+python3 tools/compile_gaze_aa.py .
+```
+
+This requires `glslangValidator`. The SMAA sources retain their upstream license
+in `src/vr/smaa/`.
+
+## Foveation tile calibration
+
+Density-map texels and GMEM render tiles have different sizes. The gaze guard
+must protect every render tile touching the full-detail disk. The narrow entry
+in `include/mocktail/vr/foveation_tile_bounds.h` applies only to this identity:
+
+- Turnip driver ID 18, vendor `0x5143`, device `0x43051401`, version `109060195`.
+- Driver name `turnip Mesa driver`, info `Mesa 26.3.0-devel (git-abc426bb62)`.
+- Driver UUID `586b9fa4514cb88b3c11a968ef4d62e4`; measured ELF build ID
+  `b7e5995d0b202f06e81cd5a0f809ec1b744a0cb8`.
+- A 2160 × 2160 framebuffer, one layer/subpass, single-sample
+  `R8G8B8A8_UNORM` color and `D32_SFLOAT` depth, plus the density attachment.
+  Offsets, resolves, extra attachments, multiview and feedback/input attachments
+  retain the conservative guard.
+
+On that binary, `vkCmdBeginRenderPass2` at RVA `0xb12180` calls the layout
+selector at `0xad67c0`. The selector initializes its layout from the FDM flag
+at render-pass byte 145; subsequent checks can only select `AVOID_CCU` again.
+The divisor routine at `0xa9e300` returns 1 for FDM. CPU-only creation of 72
+render-pass/imageless-framebuffer combinations, covering FDM on/off and every
+standard color/depth load/store combination, produced identical budgets:
+356352 pixels for `FULL`, 350208 for `AVOID_CCU`. Their base tiles are
+480 × 736 and 768 × 448 respectively. FDM therefore selects 768 × 448
+independently of shaders and load/store operations for this tuple.
+
+The GPU qualification compared a high-frequency full-density reference against
+the production map helper with its 68 × 68 map and 768 × 448 guard. Sweep both
+gaze axes through `{-1, -.75, -.4, 0, .4, .75, 1}`, radii
+`{.08, .15, .22, .35}`, and all three active profiles. All 588 cases preserved
+every pixel inside the gaze disk exactly, with 588 valid fragment-invocation
+queries and no validation errors. Mean fragment invocations were 51.46% of the
+reference in this fixture; this measures shading work, not game FPS. Requalify
+both the driver invariant and this image/counter sweep before adding identities
+or pass tuples. Unknown identities retain the conservative policy.
+
+The CPU identity and coordinate contracts can be rerun with:
+
+```sh
+cmake --build build-frame-arm64 --target foveation_tile_bounds_test framebuffer_density_map_test
+ctest --test-dir build-frame-arm64 -R 'FoveationTileBounds|FramebufferDensityMap' --output-on-failure
+```
+
+## Frame-time stability
+
+The Android `mallinfo` bridge shares a real host allocator snapshot for up to
+500 ms. glibc scans allocator free lists under arena locks; several consecutive
+queries therefore reuse a recent coherent sample. A scan runs outside the cache
+mutex, and concurrent readers can keep using the previous completed sample.
+Allocation, deallocation and the process-memory limit checks retain their normal
+behavior.
+
+Gaze density generation reuses per-eye pixel and half-float buffers across
+frames. The density values and gaze protection are unchanged. At a 1:1 render and output size, the native path avoids unnecessary
+reconstruction, temporal resource tracking and upscaler shader dispatches.
+Gaze anti-aliasing runs on the composed eye image.
+
+
+The Vulkan eye copy is submitted on the OpenXR binding queue before releasing
+its swapchain images, so SteamVR can enqueue composition immediately. When the
+guest device requested exactly one unprotected queue, completion is deferred
+until the next use of its eye-copy and anti-aliasing resources. GPU queue ordering keeps subsequent guest
+commands behind the copy. The upstream submission ring tracks command buffers, fences and source/destination
+images. Presentation dependencies are consumed on the GPU and replaced with a
+per-swapchain-image semaphore, so the CPU does not wait for the current render.
+AA resources wait only for previous eye-copy users;
+current-frame present dependencies are excluded from that resource wait.
+Captured source-image handles are drained before
+image destruction; queue exposure, swapchain replacement and teardown also
+drain pending work before releasing resources. `xrWaitFrame` remains on the
+original render thread. Additional queues, readbacks and the virtual keyboard
+retain completed-copy synchronization. `MOCKTAIL_VR_EARLY_SUBMIT=0` restores
+the original submission order, while `MOCKTAIL_VR_DEFER_COPY_WAIT=0` keeps the
+early submission but completes its fence before waiting for the next frame.
+
+Density-map generation skips the distance/ramp calculation inside the protected
+full-detail disk and beyond the peripheral plateau. Transition cells retain the
+same distance calculation and spatial pattern. This reduces CPU work without
+changing gaze protection or density values.
+
+The Frame launcher enables a render-thread CPU preference after projection
+submission starts. It reads Linux CPU capacity values only for the thread's
+existing allowed CPUs and selects capacity peers within 80% of their maximum.
+Incomplete capacity information or fewer than two preferred CPUs retains the
+original allocation. This keeps render work on the application's performance
+cores while respecting SteamVR's CPU reservation. Other engine threads retain
+their normal allocation.
+
+## Upstream integration
+
+The imported Nightcap VR revision is recorded in [the credits](../THIRD_PARTY.md).
+The Frame launcher disables the generic full-eye FXAA pass so Steam Video's
+Anti Aliasing setting remains the single AA control. The upstream JNI haptic
+protocol runs natively on ARM64. Its optional x86 SetMotor instruction scanner
+is gated to x86; ARM64 build IDs, instruction checks and native return-value
+bridges retain their own contracts.
+
+Steam Video settings are loaded once at startup and then refreshed on a worker.
+The rendering callbacks copy a completed snapshot; they never read the settings
+file or parse JSON. Unchanged content reuses its parsed values. A failed refresh
+keeps the last completed snapshot, and shutdown wakes the polling worker.
+The launcher gives a configured per-app headset refresh rate precedence over
+the desktop rate observed before the app gains focus, and derives Roblox's
+startup FPS cap from that selected profile.

docs/INSTALL.md

@@ -0,0 +1,168 @@
+# Install on Steam Frame
+
+## Requirements
+
+- Steam Frame running its ARM64 Linux desktop, with Steam and SteamVR installed.
+- Native SteamVR at `/opt/steamvr`, including `steamxr_linuxarm64.json`.
+- The Frame's Turnip/Freedreno Vulkan driver under `/usr/lib` and its Vulkan ICD
+  under `/usr/share/vulkan/icd.d`.
+- Rootless Podman, Git, Python 3 and a C++17 compiler on the Frame.
+- `zstd` for importing the compressed ARM64 release archive.
+- A Linux filesystem for the checkout, internet access and space for the source,
+  Fedora build image and a separate Roblox client download.
+
+The runtime uses Fedora 44 ARM64 in a rootless container. Keep the Frame's
+own graphics drivers: the launcher mounts them into the container. Building
+from source also needs a case-sensitive Linux checkout because some Android
+headers differ only by letter case. The source and ARM64 build are public.
+
+## 1. Get the source
+
+```bash
+git clone --branch steam-frame --recurse-submodules \
+  https://github.com/InstanceBrick/nightcap.git \
+  "$HOME/.local/share/nightcap-steam-frame-src"
+cd "$HOME/.local/share/nightcap-steam-frame-src"
+```
+
+## 2. Install the ARM64 image
+
+Download `nightcap-steam-frame-arm64.oci.tar.zst` and its `.sha256` file from
+[Releases](https://github.com/InstanceBrick/nightcap/releases). From the
+directory containing both files:
+
+```bash
+set -euo pipefail
+sha256sum -c nightcap-steam-frame-arm64.oci.tar.zst.sha256
+zstd -dc nightcap-steam-frame-arm64.oci.tar.zst | podman load
+```
+
+The archive imports as `localhost/nightcap-vr-arm64:frame-foveated`. It contains
+the ARM64 Nightcap runtime and its Fedora dependencies, with no Roblox client,
+personal data, SteamVR installation or proprietary graphics drivers.
+
+To build the same image from source instead:
+
+```bash
+podman build --arch arm64 --jobs 1 \
+  -f packaging/steam-frame/Containerfile \
+  -t localhost/nightcap-vr-arm64:frame-foveated .
+```
+
+This builds Nightcap and its helpers from source. It does not download or bundle
+Roblox. The image tag is also the one used by the Frame launcher.
+
+## 3. Install the launcher and refresh-rate helper
+
+```bash
+python3 tools/steam_frame/install_launcher.py
+mkdir -p "$HOME/.local/share/nightcap-vr-arm64/data/tools"
+c++ -std=c++17 -O2 tools/frame_video_settings/refresh_rate.cc -ldl \
+  -o "$HOME/.local/share/nightcap-vr-arm64/data/tools/refresh_rate"
+```
+
+The application menu entry is **Nightcap Roblox VR**.
+
+## 4. Download the compatible Roblox client
+
+Close Nightcap first. Prepare its data directory and copy the initial settings
+only if no configuration exists yet:
+
+```bash
+frame_data="$HOME/.local/share/nightcap-vr-arm64/data"
+mkdir -p "$frame_data/.config/mocktail"
+if [ ! -f "$frame_data/.config/mocktail/config.yaml" ]; then
+  cp config/steam-frame.example.yaml "$frame_data/.config/mocktail/config.yaml"
+fi
+podman run --rm --arch arm64 --userns=keep-id \
+  --security-opt label=disable \
+  -v "$frame_data:/data:rw" \
+  -e HOME=/data -e XDG_CONFIG_HOME=/data/.config \
+  -e XDG_DATA_HOME=/data/.local/share -e XDG_CACHE_HOME=/data/.cache \
+  --entrypoint /opt/nightcap-vr-arm64/lib64/mocktail/mocktail_updater \
+  localhost/nightcap-vr-arm64:frame-foveated \
+  update --no-latest-check --skip-canary
+```
+
+The updater downloads the newest ARM64 client supported by the included catalog.
+The command retains APK signature, architecture, build identity and payload
+integrity checks. `--skip-canary` skips the separate desktop graphics test; VR
+starts through the Frame launcher in the next step. Client files stay in your
+local data directory.
+
+## 5. Launch in VR and add to Steam
+
+Start SteamVR and connect the headset, then open **Nightcap Roblox VR** from the
+application menu. Sign in through Roblox's normal interface.
+
+To add the Steam shortcut automatically, enable Steam's local browser debugging
+endpoint at `127.0.0.1:8080`, keep Steam running and use:
+
+```bash
+python3 tools/steam_frame/register_steam_shortcut.py
+```
+
+The script creates or reuses the launcher shortcut, sets its Nightcap icon and
+marks it as a VR application. It saves the generated identity locally. If the
+endpoint is unavailable, use Steam's **Add a Non-Steam Game** dialog and select
+`~/.local/bin/nightcap-vr-arm64`, then mark the shortcut as a VR application.
+
+## 6. Add the SteamVR Video controls
+
+The settings integration supports a specific SteamVR dashboard revision. It
+checks the installed dashboard before applying changes and leaves other
+revisions untouched. Valve dashboard files are read from your local installation.
+
+With SteamVR closed and the original dashboard files visible:
+
+```bash
+mkdir -p frame-ui-local/originals frame-ui-local/generated
+cp /opt/steamvr/resources/webinterface/dashboard/chunk~8012d0c89.js \
+  frame-ui-local/originals/steamvr-dashboard.original.js
+cp /opt/steamvr/resources/webinterface/dashboard/systemui.html \
+  frame-ui-local/originals/steamvr-systemui.original.html
+cp /opt/steamvr/resources/webinterface/dashboard/settings_desktop.html \
+  frame-ui-local/originals/steamvr-settings_desktop.original.html
+python3 tools/steam_frame/prepare_video_ui.py \
+  frame-ui-local/originals frame-ui-local/generated
+sudo python3 tools/steam_frame/install_video_ui.py frame-ui-local/generated
+```
+
+Start SteamVR again. The settings are described in [Video settings](SETTINGS.md).
+The service mounts three generated files read-only; the original SteamVR files
+are preserved. If upgrading an existing installation, reuse your saved original
+files instead of copying the already patched dashboard.
+
+## Update Nightcap
+
+Close Nightcap before replacing its image or launcher. Pull the `steam-frame`
+branch, then load the new ARM64 release archive as in step 2 and rerun the
+launcher installer. Existing Roblox downloads, sign-in state and settings stay
+in the separate data directory.
+
+For source builds, pull this branch and rebuild under a temporary image tag:
+
+```bash
+git pull --ff-only
+git submodule update --init --recursive
+podman build --arch arm64 --jobs 1 \
+  -f packaging/steam-frame/Containerfile \
+  -t localhost/nightcap-vr-arm64:next .
+podman tag localhost/nightcap-vr-arm64:frame-foveated \
+  localhost/nightcap-vr-arm64:previous
+podman tag localhost/nightcap-vr-arm64:next \
+  localhost/nightcap-vr-arm64:frame-foveated
+python3 tools/steam_frame/install_launcher.py
+```
+
+Existing Roblox downloads, sign-in state and settings remain in the data
+directory. To install a newly supported Roblox client, repeat step 4 after
+updating Nightcap. Automatic client updates are off in the supplied Frame
+configuration, since the ARM64 VR bridge needs matching client interfaces.
+
+To restore the previous Nightcap image with the app closed:
+
+```bash
+podman tag localhost/nightcap-vr-arm64:previous \
+  localhost/nightcap-vr-arm64:frame-foveated
+```

docs/ROADMAP.md

@@ -1,95 +0,0 @@
-# Nightcap roadmap
-
-What Nightcap is working toward, in priority order. Items move to
-[Shipped](#shipped) when they land on `main`. Open an issue to propose a
-change to this list.
-
-## 1. Settings UI
-
-Nightcap is configured by editing `~/.config/mocktail/config.yaml`. Most
-people never open it, so they never find the FPS unlock or the vsync switch.
-
-Goal: a small GTK4 settings window, reachable from the app menu and from a
-`--settings` flag, that reads and writes the same `config.yaml`.
-
-- Graphics tab: backend, frame rate limit, vsync, small texture upscale.
-- Input tab: the `input.raw_mouse` toggle and controller options.
-- Advanced tab: FFlag overrides with a plain text editor for `fflags.json`.
-- Discord tab: the `discord_rpc` block (see item 3).
-- Changes apply on next launch. A restart button restarts Nightcap.
-
-Done when every option in `config/mocktail.example.yaml` that a player would
-touch can be set without a text editor.
-
-## 2. Controller button glyphs
-
-Upstream added Xbox and PlayStation gamepad support through SDL. Controllers
-already hot-plug and release their held inputs when unplugged. One rough edge
-is left.
-
-- Correct button glyphs for the connected pad. `SDL_GetGamepadType` is only
-  read for Xbox and PlayStation pads, so a Switch Pro, a GameCube pad, or any
-  generic pad SDL reports as `SDL_GAMEPAD_TYPE_STANDARD` reaches Roblox as
-  type 0 and draws generic glyphs. `SDL_GetRealGamepadType`, and the vendor
-  and product IDs, are available and unused.
-
-Done when a plugged-in pad shows its own buttons.
-
-## 3. Discord Rich Presence
-
-Upstream ships Discord RPC. Nightcap turns it on by default; see the
-[FAQ](../FAQ.md) to switch it off. It shows the experience name, elapsed
-time, the experience icon, and a join button when the server is public.
-
-- Custom presence: set the title, details line, state line, and large and
-  small icons from `config.yaml`, with placeholders like the experience name
-  and elapsed time.
-- A Discord tab in the settings window to toggle each field.
-
-Done when a friend can see what you are playing and join in one click, and
-you can switch it all off in one click.
-
-## 4. Performance profiling
-
-Every performance change should come with numbers. Today they come with a
-feeling.
-
-- A frame time overlay, toggled by a key and a config flag, showing CPU time,
-  GPU time, and present latency.
-- Shader compile and pipeline cache tracing, so first-load stutter can be
-  measured and cut.
-- A `--profile` flag that writes a Chrome-format trace file, readable in
-  `ui.perfetto.dev` and `chrome://tracing`.
-- A short benchmark guide in `docs/` with a fixed set of experiences, so
-  before and after numbers can be compared across machines.
-
-Done when a pull request that claims a speedup can show the trace that
-proves it.
-
-## Shipped
-
-- Lower input latency: frames are presented as soon as they are ready.
-- Controllers hot-plug without a restart, and a pad that is unplugged mid-game
-  releases its held buttons and sticks instead of leaving them stuck.
-- Mouse look keeps responding after a long turn, instead of going dead until
-  the pointer travels back from past the screen edge.
-- Optional raw mouse input: `input.raw_mouse` in `config.yaml` sends look
-  deltas in host units, so fractional display scaling no longer changes
-  first-person sensitivity.
-- Small textures upscaled 4x by default, with PNG overrides in
-  `~/.config/mocktail/textures`.
-- ETC2 textures decoded on desktop GPUs without stutter.
-- No more error 319 kicks after joining a server.
-- Roblox sees the real host RAM and screen size.
-- Desktop launcher that works on Wayland and finds the installed binary.
-- Discord Rich Presence on by default.
-- Own app ID `io.github.CoderDayton.nightcap`, so Nightcap installs next to
-  upstream.
-- AppImage and signed Flatpak releases on every `v*` tag, with the Flatpak
-  repo on GitHub Pages.
-
-## Not planned
-
-- Replacing the `mocktail` binary and config names. Keeping them makes
-  upstream merges clean.
-- DEB, RPM, and AUR packages. Upstream ships those for unmodified Mocktail.

docs/SETTINGS.md

@@ -0,0 +1,124 @@
+# Settings
+
+## Video
+
+Open the game's SteamVR **Video** settings after installing the settings
+integration.
+
+The standard profile is **native 2160 × 2160 per eye**, **72 Hz**, **SMAA High**
+and **Performance** foveated rendering. The application targets 72 FPS at 72 Hz;
+actual frame rate depends on the experience and Roblox's graphics settings.
+The gaze radius remains adjustable, and existing saved choices are preserved.
+
+| Setting | Effect |
+| --- | --- |
+| Foveated Rendering | Off uses full-density shading throughout. Quality, Balanced and Performance progressively reduce peripheral shading work. Each mode keeps the same full-detail gaze region. |
+| Gaze sharp radius | Sets the minimum full-detail region around your gaze, from 8% to 35%. Larger values preserve more of the view at full density and cost more GPU time. Hardware tile boundaries can enlarge this region. |
+| Anti Aliasing | Off, FXAA, SMAA Low or SMAA High. Filtering runs around your gaze on the composed eye image, including interface edges. SMAA High is the default. |
+| Desktop Mirror | Off by default on Frame. On displays the VR image in the desktop window as well as the headset. Relaunch Nightcap after changing it. |
+| Performance Overlay | Shows actual game FPS, headset Hz, average frame time, SteamVR GPU time and per-eye resolution at the bottom center of the headset view. It hides while the Steam menu is open and does not capture controller input. |
+| Resolution Per Eye | Sets the headset eye-buffer size. Nightcap's recommended default is 2160 × 2160 per eye; Auto and Reset to Defaults use this baseline. Explicit custom values stay selected. Changes apply after the slider settles, with a brief pause while eye buffers are rebuilt at a safe frame boundary. |
+| Display Refresh Rate | The standard profile uses 72 Hz. The launcher follows the selected per-game headset rate and any explicit Steam frame limit. Restart Nightcap after changing the rate or frame limit so Roblox's internal cap matches it. |
+
+Enable **Performance Overlay**, then close the Steam menu. **APP FPS** counts
+new Roblox projections over a rolling second. **HMD Hz** is the headset refresh
+rate. **FRAME** is average time per submitted game frame, **TARGET** is the
+configured application frame rate, and **BUDGET** is the time available per
+application frame: 13.89 ms for 72 FPS at 72 Hz. Repeated or reprojected
+compositor frames do not count as new game frames.
+
+**GPU** averages SteamVR timings for new application frames, excluding
+compositor-only reprojections. It can include scheduling gaps. The overlay
+reports standby or missing frames instead of retaining a stale FPS. Its setting
+persists between launches and can be turned off at any time.
+
+Foveated rendering reduces fragment-shader work in the 3D scene before the
+image is composed. The final composition stays at native resolution, keeping
+screen-space text and interface elements from being coarsened a second time.
+Your gaze region retains the detail available at the selected eye resolution;
+the periphery uses progressively lower shading density.
+
+Foveation, gaze radius and anti-aliasing controls update while the application
+is running. Higher eye resolutions improve fine detail and increase GPU and
+memory cost. For more headroom, keep Performance foveation, reduce the gaze
+radius if needed, or lower Roblox's own graphics quality.
+
+The launcher uses the selected Steam Video resolution without an extra
+multiplier. To add supersampling, set `NIGHTCAP_VR_RENDER_SCALE` when launching
+Nightcap; for example, `NIGHTCAP_VR_RENDER_SCALE=1.25`. The default is `1.0`.
+Larger values increase GPU work.
+
+The launcher reads the selected headset refresh rate and SteamVR's frame limit
+on every launch. At 72 Hz with no frame limit, Roblox's internal scheduler is
+capped at 72 FPS. Half-rate rendering is not forced automatically.
+
+On Frame, the render thread prefers higher-capacity cores within the CPU
+allocation supplied by SteamVR. To use the default thread placement, launch with
+`NIGHTCAP_VR_PREFER_PERFORMANCE_CORES=0`.
+
+## Controllers and typing
+
+The native VR bridge supplies controller tracking, buttons, axes and haptics.
+Roblox experiences choose how to use those inputs. The in-headset keyboard opens
+when a text field receives focus; point at a key and pull the trigger to type.
+Steam Controller desktop navigation can also be configured through the Steam
+shortcut's controller layout.
+
+## Microphone
+
+Set the Frame's headset microphone as the default input in the desktop audio
+settings and check that it is not muted. Roblox voice chat uses its normal
+account eligibility, microphone permission and in-experience controls.
+
+Nightcap's native recording bridge captures the selected input when Roblox
+requests recording. To choose a different input, close Nightcap and edit
+`~/.local/share/nightcap-vr-arm64/data/.config/mocktail/config.yaml`:
+
+```yaml
+audio:
+  input_device: default
+```
+
+An exact SDL device name can replace `default`. Input device names appear in the
+launch log.
+
+## Desktop mirror
+
+Open SteamVR's per-game **Video** settings and set **Desktop Mirror** to **On**
+to show the VR view in a desktop window. Set it to **Off** to keep the Frame's
+single headset application without the extra desktop view. Relaunch Nightcap
+after changing this setting. The Frame default is **Off**.
+
+The Frame launcher reads the saved SteamVR mirror choice and coordinates both
+the mirror renderer and desktop-window visibility. This setting takes precedence
+over the YAML value when using the Frame launcher. Generic Nightcap launches
+can configure the mirror beside the VR option:
+
+```yaml
+vr:
+  enabled: true
+  desktop_mirror: true
+```
+
+`MOCKTAIL_VR_DESKTOP_MIRROR=1` or `0` overrides the YAML setting for generic
+launches. VR and desktop mirroring are separate options; enabling VR does not
+require the desktop mirror.
+
+Roblox's desktop viewport stays at 1920 × 1080 during VR for stable in-game
+menu size, independently of headset eye resolution. On Frame, desktop window geometry
+is not restored or saved in VR, including when the mirror is enabled.
+
+## Files and troubleshooting
+
+| Item | Location |
+| --- | --- |
+| Launcher | `~/.local/bin/nightcap-vr-arm64` |
+| Launch log | `~/.local/share/nightcap-vr-arm64/last-launch.log` |
+| Configuration | `~/.local/share/nightcap-vr-arm64/data/.config/mocktail/config.yaml` |
+| Local client store | `~/.local/share/nightcap-vr-arm64/data/.local/share/mocktail` |
+| Steam shortcut identity | `~/.local/share/nightcap-vr-arm64/steam-shortcut.json` |
+
+If launching fails, check the launch log, make sure SteamVR is running and confirm
+that the `localhost/nightcap-vr-arm64:frame-foveated` image exists. If the game
+reports an unsupported client, update Nightcap before replacing the client.
+Keep account data and client downloads outside source control.

flake.nix

@@ -49,6 +49,17 @@
               gdb
             ];
 
+            desktopItems = [
+              (pkgs.makeDesktopItem {
+                name = "Mocktail";
+                exec = "mocktail";
+                icon = "mocktail";
+                desktopName = "Mocktail";
+                comment = "Experimental Roblox compatibility runtime for Linux and FreeBSD";
+                categories = [ "Game" ];
+              })
+            ];
+
             shellHook = ''
               export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${pkgs.lib.makeLibraryPath package.buildInputs}"
 

include/compat/allocator_snapshot_cache.h

@@ -0,0 +1,34 @@
+#pragma once
+#include "compat/bionic_host_libc_runtime.h"
+#include <cstdint>
+#include <mutex>
+
+namespace mocktail::compat {
+// Heap accounting is a sampled statistic. A glibc scan walks free lists while
+// holding arena locks, so back-to-back Android queries share a recent sample.
+// The scan runs outside this mutex; concurrent callers can use the last complete
+// sample without waiting for another allocator walk.
+class AllocatorSnapshotCache {
+ public:
+  static constexpr std::uint64_t kRefreshNs=500'000'000ULL;
+  template<class Reader>
+  BionicMallinfoSnapshot Read(std::uint64_t now,Reader reader) noexcept {
+    std::unique_lock<std::mutex> lock(mutex_);
+    if(refreshing_ || (initialized_ && now<refresh_after_))return snapshot_;
+    refreshing_=true;
+    lock.unlock();
+    const auto fresh=reader();
+    lock.lock();
+    snapshot_=fresh;
+    initialized_=true;
+    refresh_after_=now+kRefreshNs;
+    refreshing_=false;
+    return snapshot_;
+  }
+ private:
+  std::mutex mutex_;
+  BionicMallinfoSnapshot snapshot_{};
+  bool initialized_=false,refreshing_=false;
+  std::uint64_t refresh_after_=0;
+};
+}

include/compat/bionic_abi_exports.h

@@ -33,6 +33,23 @@ void SetLegacyBionicDiagnosticsEnabled(bool enabled);
 // guest layout explicit instead of exposing the incompatible host libc type.
 using MocktailBionicMutexAttr = int64_t;
 
+// Bionic LP64 pthread_attr_t: 56 bytes with explicit field offsets. The host
+// glibc layout is opaque and wider on aarch64, so guest buffers must be read
+// and written through this struct only.
+struct MocktailBionicPthreadAttr {
+  std::uint32_t flags;
+  void* stack_base;
+  std::size_t stack_size;
+  std::size_t guard_size;
+  std::int32_t sched_policy;
+  std::int32_t sched_priority;
+  char reserved[16];
+};
+static_assert(sizeof(MocktailBionicPthreadAttr) == 56);
+
+inline constexpr std::uint32_t kMocktailBionicAttrFlagDetached = 0x1;
+inline constexpr std::uint32_t kMocktailBionicAttrFlagUserStack = 0x2;
+
 extern "C" {
 
 void mocktail_set_current_jni_env(void* env);
@@ -84,6 +101,19 @@ int mocktail_pthread_barrier_init(pthread_barrier_t* barrier,
 int mocktail_pthread_barrier_destroy(pthread_barrier_t* barrier);
 int mocktail_pthread_barrier_wait(pthread_barrier_t* barrier);
 
+int mocktail_pthread_attr_init(MocktailBionicPthreadAttr* attr);
+int mocktail_pthread_attr_destroy(MocktailBionicPthreadAttr* attr);
+int mocktail_pthread_attr_setstacksize(MocktailBionicPthreadAttr* attr,
+                                       size_t stack_size);
+int mocktail_pthread_attr_setdetachstate(MocktailBionicPthreadAttr* attr,
+                                         int detach_state);
+int mocktail_pthread_attr_setschedparam(MocktailBionicPthreadAttr* attr,
+                                        const struct sched_param* parameters);
+int mocktail_pthread_getattr_np(pthread_t thread,
+                                MocktailBionicPthreadAttr* attr);
+int mocktail_pthread_attr_getstack(const MocktailBionicPthreadAttr* attr,
+                                   void** stack_base, size_t* stack_size);
+
 extern void* mocktail_gameactivity_on_start_native;
 extern void* mocktail_gameactivity_on_resume_native;
 extern void* mocktail_gameactivity_on_surface_created_native;

include/compat/bionic_host_libc_runtime.h

@@ -11,19 +11,27 @@
 
 namespace mocktail::compat {
 
+// glibc's atoi is (int)strtol(), exactly like Bionic's, so the host symbol is
+// used as-is there. Other libcs (musl) differ on overflow and need the shim.
+#ifdef __GLIBC__
+inline constexpr bool kHostAtoiMatchesBionic = true;
+#else
+inline constexpr bool kHostAtoiMatchesBionic = false;
+#endif
+
 // Android uses size_t fields here; glibc uses int and musl has no equivalent.
 // An all-zero fallback means unknown, not zero usage.
 struct BionicMallinfoSnapshot {
-  size_t arena = 0;
-  size_t ordblks = 0;
-  size_t smblks = 0;
-  size_t hblks = 0;
-  size_t hblkhd = 0;
-  size_t usmblks = 0;
-  size_t fsmblks = 0;
-  size_t uordblks = 0;
-  size_t fordblks = 0;
-  size_t keepcost = 0;
+  size_t arena;
+  size_t ordblks;
+  size_t smblks;
+  size_t hblks;
+  size_t hblkhd;
+  size_t usmblks;
+  size_t fsmblks;
+  size_t uordblks;
+  size_t fordblks;
+  size_t keepcost;
 };
 
 struct BionicLocaleState;
@@ -90,6 +98,7 @@ int mocktail_bionic_cxa_thread_atexit_impl(
     mocktail::compat::BionicThreadDestructor destructor, void* argument,
     void* dso_handle);
 void mocktail_bionic_arc4random_buf(void* buffer, size_t size);
+int mocktail_bionic_atoi(const char* text);
 mocktail::compat::BionicMallinfoSnapshot mocktail_bionic_mallinfo();
 int mocktail_bionic_sysinfo(struct sysinfo* info);
 int mocktail_bionic_uname(struct utsname* name);

include/compat/bionic_pthread_create_runtime.h

@@ -25,11 +25,12 @@ void ConfigureBionicPthreadThreadInitializer(
 
 }  // namespace mocktail::compat
 
+struct MocktailBionicPthreadAttr;
+
 // Rebuilds attributes instead of passing Android pthread_attr_t to glibc.
-extern "C" int mocktail_bionic_pthread_create(pthread_t* thread,
-                                               const pthread_attr_t* attr,
-                                               void* (*start_routine)(void*),
-                                               void* argument);
+extern "C" int mocktail_bionic_pthread_create(
+    pthread_t* thread, const MocktailBionicPthreadAttr* attr,
+    void* (*start_routine)(void*), void* argument);
 
 // Guest real-time scheduling is denied to avoid the host RLIMIT_RTTIME watchdog.
 extern "C" int mocktail_bionic_pthread_setschedparam(

include/compat/build_profile.h

@@ -36,6 +36,11 @@ struct FmodOutputDeviceBridgeProfile {
                ? std::array<std::size_t, 4>{9, 10, 12, 18}
                : std::array<std::size_t, 4>{8, 9, 10, 16};
   }
+  std::array<std::size_t, 6> capture_vtable_indexes() const {
+    return vtable_layout_version == 2
+               ? std::array<std::size_t, 6>{4, 13, 14, 15, 16, 17}
+               : std::array<std::size_t, 6>{4, 11, 12, 13, 14, 15};
+  }
 
   bool valid_vtable_layout() const {
     return vtable_layout_version == 1 || vtable_layout_version == 2;
@@ -48,6 +53,19 @@ struct FmodOutputDeviceBridgeProfile {
   }
 };
 
+// Exact-build metadata for the experimental native VR bridge. The bridge
+// interposes DebugDeviceVR slots and a checked world-pointer trampoline.
+// All RVAs are validated against machine-code contracts before first use.
+struct VrDebugDeviceBridgeProfile {
+  std::uintptr_t vtable_rva = 0;
+  std::uintptr_t constructor_rva = 0;
+  std::uintptr_t state_getter_rva = 0;
+  std::uintptr_t eye_getter_rva = 0;
+  std::uintptr_t eye_initializer_rva = 0;
+  std::uintptr_t emulator_flag_storage_rva = 0;
+  std::uintptr_t device_create_framebuffer_vtable_offset = 0;
+};
+
 struct BuildProfile {
   std::string version_name;
   int version_code = 0;
@@ -65,6 +83,8 @@ struct BuildProfile {
   // output-device virtual slots and restores them during controlled teardown;
   // executable guest code is never modified.
   std::optional<FmodOutputDeviceBridgeProfile> fmod_output_device_bridge;
+  // Optional exact-build experimental VR capability; see the struct above.
+  std::optional<VrDebugDeviceBridgeProfile> vr_debug_device_bridge;
   std::string reason;
 };
 

include/compat/guest_abi.h

@@ -0,0 +1,38 @@
+#ifndef MOCKTAIL_COMPAT_GUEST_ABI_H_
+#define MOCKTAIL_COMPAT_GUEST_ABI_H_
+
+#include <elf.h>
+#include <string_view>
+
+namespace mocktail::compat {
+
+#if defined(__aarch64__)
+// Android ABI name as it appears in APK lib/ directories and build metadata.
+inline constexpr std::string_view kGuestAbi = "arm64-v8a";
+// APK split-config name carrying the guest native libraries.
+inline constexpr std::string_view kGuestApkSplitName = "config.arm64_v8a";
+// File name the payload store uses for the split APK.
+inline constexpr std::string_view kGuestSplitApkFile =
+    "split_config.arm64_v8a.apk";
+// sha256 map key holding the split APK digest in payload metadata.
+inline constexpr std::string_view kGuestSplitApkHashKey = "arm64_v8a_split_apk";
+// Short CPU label for device metadata and user-facing strings.
+inline constexpr std::string_view kGuestCpuName = "aarch64";
+inline constexpr int kGuestElfMachine = EM_AARCH64;
+#elif defined(__x86_64__)
+inline constexpr std::string_view kGuestAbi = "x86_64";
+inline constexpr std::string_view kGuestApkSplitName = "config.x86_64";
+inline constexpr std::string_view kGuestSplitApkFile = "split_config.x86_64.apk";
+inline constexpr std::string_view kGuestSplitApkHashKey = "x86_64_split_apk";
+inline constexpr std::string_view kGuestCpuName = "x86_64";
+inline constexpr int kGuestElfMachine = EM_X86_64;
+#else
+#error "mocktail only supports aarch64 and x86_64 hosts"
+#endif
+
+// APK zip entry holding the guest libroblox.so.
+inline constexpr std::string_view kGuestLibApkEntryPrefix = "lib/";
+
+}  // namespace mocktail::compat
+
+#endif  // MOCKTAIL_COMPAT_GUEST_ABI_H_

include/compat/host_abi_profile.h

@@ -109,6 +109,15 @@ struct HostAbiProfile {
   size_t NativeMimallocConstructorRangeEndExclusive() const noexcept;
   bool ShouldInitializeNativeMimallocThreadAfterConstructor(
       size_t index) const noexcept;
+  // True when both replays have the one verified shape. The native replay is
+  // one range that runs to the end of .init_array. Its first four
+  // constructors are the process-load constructor at the thread-initializer
+  // checkpoint, the JNI singleton initializer, and two wiring entries. The
+  // host-bridge replay runs the same constructors without the two wiring
+  // entries. `jni_singleton_constructor` is the .init_array index of the JNI
+  // singleton initializer.
+  bool HasVerifiedConstructorPolicy(
+      size_t jni_singleton_constructor) const noexcept;
   bool HasValidNativePreJniBootstrap() const noexcept;
   HostAllocatorStrategy ResolveAllocatorStrategy(
       bool host_bridges_override_present,

include/compat/web_view_protocol_contract.h

@@ -0,0 +1,190 @@
+#ifndef MOCKTAIL_COMPAT_WEB_VIEW_PROTOCOL_CONTRACT_H_
+#define MOCKTAIL_COMPAT_WEB_VIEW_PROTOCOL_CONTRACT_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <optional>
+#include <string_view>
+
+// Roblox's Subsystem<IWebViewProtocol> getter is not exported. The exported
+// WebViewProtocol.initializeAndroidWebViewProtocol calls it first, into a
+// stack slot, then reads the protocol from the returned holder:
+//
+//   x86-64:  lea slot(%rbp),%rbx; mov %rbx,%rdi; call getter;
+//            mov (%rbx),%rbx; mov 0x18(%rbx),%rax
+//   AArch64: add x8, sp, #slot; bl getter; ldr xN, [sp, #slot];
+//            ldr x8, [xN, #0x18]
+//
+// These functions find that call site in the initializer's first bytes and
+// check the getter's own code. Only relocated or build-varying fields (stack
+// slots, frame sizes, PC-relative offsets, the call target) are masked.
+// Verified on x86_64 2.734.917, 2.736.1408 and 2.738.1397, and on arm64-v8a
+// 2.738.1397 and 2.740.931.
+
+namespace mocktail::compat {
+
+// Covers the call site in every verified build (x86-64 +0x27, AArch64 +0x34).
+inline constexpr std::size_t kWebViewProtocolInitializerScanBytes = 128;
+inline constexpr std::size_t kWebViewProtocolGetterBytesX86_64 = 44;
+inline constexpr std::size_t kWebViewProtocolGetterBytesArm64 = 60;
+
+namespace web_view_protocol_contract_detail {
+
+inline bool MatchesMasked(std::string_view code, std::size_t offset,
+                          std::string_view pattern,
+                          std::string_view wildcard) {
+  if (offset > code.size() || code.size() - offset < pattern.size()) {
+    return false;
+  }
+  for (std::size_t index = 0; index < pattern.size(); ++index) {
+    if (wildcard[index] == 'x') continue;
+    if (code[offset + index] != pattern[index]) return false;
+  }
+  return true;
+}
+
+// AArch64 instructions are little-endian words.
+inline std::uint32_t Word(std::string_view code, std::size_t index) {
+  std::uint32_t word = 0;
+  for (std::size_t byte = 0; byte < 4; ++byte) {
+    word |= static_cast<std::uint32_t>(
+                static_cast<unsigned char>(code[index * 4 + byte]))
+            << (8 * byte);
+  }
+  return word;
+}
+
+// One AArch64 instruction word: bits outside `mask` may vary.
+struct MaskedWord {
+  std::uint32_t mask;
+  std::uint32_t value;
+};
+
+inline constexpr std::uint32_t kExact = 0xffffffffU;
+// adrp Xd, page: immlo and immhi vary.
+inline constexpr std::uint32_t kAdrpMask = 0x9f00001fU;
+// add Xd, Xn, #imm12: imm12 varies.
+inline constexpr std::uint32_t kAddImmediateMask = 0xffc003ffU;
+
+}  // namespace web_view_protocol_contract_detail
+
+// Returns the getter address called from the x86-64 initializer at
+// `address`, or nullopt unless the frame setup and exactly one call site
+// match.
+inline std::optional<std::uintptr_t> FindWebViewProtocolGetterCallX86_64(
+    std::string_view code, std::uintptr_t address) {
+  using web_view_protocol_contract_detail::MatchesMasked;
+  // push %rbp; mov %rsp,%rbp
+  if (!MatchesMasked(code, 0, "\x55\x48\x89\xe5", "....")) {
+    return std::nullopt;
+  }
+  static constexpr std::string_view kCallSite(
+      "\x48\x8d\x5d\x00\x48\x89\xdf\xe8\x00\x00\x00\x00\x48\x8b\x1b\x48\x8b\x43"
+      "\x18",
+      19);
+  static constexpr std::string_view kCallSiteWildcard("...x....xxxx.......");
+  static constexpr std::size_t kCallDisplacement = 8;
+  const std::string_view window =
+      code.substr(0, kWebViewProtocolInitializerScanBytes);
+  std::optional<std::size_t> call_site;
+  for (std::size_t offset = 0; offset < window.size(); ++offset) {
+    if (MatchesMasked(window, offset, kCallSite, kCallSiteWildcard)) {
+      if (call_site.has_value()) return std::nullopt;
+      call_site = offset;
+    }
+  }
+  if (!call_site.has_value()) return std::nullopt;
+  std::int32_t displacement = 0;
+  std::memcpy(&displacement, window.data() + *call_site + kCallDisplacement,
+              sizeof(displacement));
+  const std::uintptr_t next_instruction =
+      address + *call_site + kCallDisplacement + sizeof(displacement);
+  return next_instruction +
+         static_cast<std::uintptr_t>(static_cast<std::intptr_t>(displacement));
+}
+
+// The x86-64 getter stores the holder returned by the subsystem's acquire
+// into its result slot (%rdi) and returns that slot.
+inline bool HasWebViewProtocolGetterContractX86_64(std::string_view code) {
+  return web_view_protocol_contract_detail::MatchesMasked(
+      code, 0,
+      std::string_view(
+          "\x55\x48\x89\xe5\x53\x50\x48\x89\xfb\x8a\x05\x00\x00\x00\x00\x84\xc0"
+          "\x74\x19\x48\x8d\x3d\x00\x00\x00\x00\xe8\x59\x00\x00\x00\x48\x89\x03"
+          "\x48\x89\xd8\x48\x83\xc4\x08\x5b\x5d\xc3",
+          kWebViewProtocolGetterBytesX86_64),
+      "...........xxxx.......xxxx..................");
+}
+
+// Returns the getter address called from the AArch64 initializer at
+// `address`, or nullopt unless exactly one call site matches.
+inline std::optional<std::uintptr_t> FindWebViewProtocolGetterCallArm64(
+    std::string_view code, std::uintptr_t address) {
+  using web_view_protocol_contract_detail::Word;
+  const std::size_t words =
+      code.substr(0, kWebViewProtocolInitializerScanBytes).size() / 4;
+  std::optional<std::uintptr_t> getter;
+  for (std::size_t index = 0; index + 4 <= words; ++index) {
+    const std::uint32_t slot_address = Word(code, index);
+    const std::uint32_t call = Word(code, index + 1);
+    const std::uint32_t handle_load = Word(code, index + 2);
+    const std::uint32_t protocol_load = Word(code, index + 3);
+    // add x8, sp, #slot
+    if ((slot_address & 0xffc003ffU) != 0x910003e8U) continue;
+    // bl getter
+    if ((call & 0xfc000000U) != 0x94000000U) continue;
+    // ldr xN, [sp, #slot]
+    if ((handle_load & 0xffc003e0U) != 0xf94003e0U) continue;
+    const std::uint32_t slot = (slot_address >> 10) & 0xfffU;
+    if (((handle_load >> 10) & 0xfffU) * 8 != slot) continue;
+    // ldr x8, [xN, #0x18]
+    const std::uint32_t handle_register = handle_load & 0x1fU;
+    if (protocol_load != (0xf9400c08U | (handle_register << 5))) continue;
+    if (getter.has_value()) return std::nullopt;
+    // imm26 is a signed word offset from the bl instruction.
+    const std::int64_t imm26 = call & 0x03ffffffU;
+    const std::int64_t words_from_call =
+        (imm26 & 0x02000000) != 0 ? imm26 - 0x04000000 : imm26;
+    getter = address + (index + 1) * 4 +
+             static_cast<std::uintptr_t>(words_from_call * 4);
+  }
+  return getter;
+}
+
+// The AArch64 getter saves its result slot (x8) and stores the holder
+// returned by the subsystem's acquire there.
+inline bool HasWebViewProtocolGetterContractArm64(std::string_view code) {
+  using namespace web_view_protocol_contract_detail;
+  static constexpr MaskedWord kGetter[] = {
+      {kExact, 0xa9be7bfdU},              // stp x29, x30, [sp, #-0x20]!
+      {kExact, 0xf9000bf3U},              // str x19, [sp, #0x10]
+      {kExact, 0x910003fdU},              // mov x29, sp
+      {kAdrpMask, 0x90000009U},           // adrp x9, guard
+      {kAddImmediateMask, 0x91000129U},   // add x9, x9, :lo12:guard
+      {kExact, 0xaa0803f3U},              // mov x19, x8
+      {kExact, 0x08dffd29U},              // ldarb w9, [x9]
+      {kExact, 0x36000109U},              // tbz w9, #0, initialize
+      {kAdrpMask, 0x90000000U},           // adrp x0, holder
+      {kAddImmediateMask, 0x91000000U},   // add x0, x0, :lo12:holder
+      {kExact, 0x94000017U},              // bl acquire
+      {kExact, 0xf9000260U},              // str x0, [x19]
+      {kExact, 0xf9400bf3U},              // ldr x19, [sp, #0x10]
+      {kExact, 0xa8c27bfdU},              // ldp x29, x30, [sp], #0x20
+      {kExact, 0xd65f03c0U},              // ret
+  };
+  static_assert(sizeof(kGetter) / sizeof(kGetter[0]) * 4 ==
+                kWebViewProtocolGetterBytesArm64);
+  if (code.size() < kWebViewProtocolGetterBytesArm64) return false;
+  for (std::size_t index = 0; index < sizeof(kGetter) / sizeof(kGetter[0]);
+       ++index) {
+    if ((Word(code, index) & kGetter[index].mask) != kGetter[index].value) {
+      return false;
+    }
+  }
+  return true;
+}
+
+}  // namespace mocktail::compat
+
+#endif  // MOCKTAIL_COMPAT_WEB_VIEW_PROTOCOL_CONTRACT_H_

include/jnivm/jnivm.h

@@ -48,9 +48,15 @@ struct PlatformIdentity {
   std::string manufacturer = "Mocktail";
   std::string model = "Mocktail Headless";
   std::string brand = "Mocktail";
+#if defined(__aarch64__)
+  std::string device_code = "linux-arm64";
+  std::string device_sku = "mocktail-arm64";
+  std::string soc_model = "aarch64";
+#else
   std::string device_code = "linux-x86_64";
   std::string device_sku = "mocktail-x86_64";
   std::string soc_model = "x86_64";
+#endif
 };
 
 struct RobloxCredentialView {

include/mocktail/audio/fmod_thread_floating_point.h

@@ -6,6 +6,9 @@
 #if defined(__x86_64__)
 #include <xmmintrin.h>
 #endif
+#if defined(__aarch64__)
+#include <cstdint>
+#endif
 
 namespace mocktail::audio {
 
@@ -22,16 +25,23 @@ class FmodThreadFloatingPointMode final {
       delete;
 
   bool Enable(const char* thread_name) noexcept {
-#if defined(__x86_64__)
+#if defined(__x86_64__) || defined(__aarch64__)
     if (active_ || thread_name == nullptr) return false;
     const std::string_view name(thread_name);
     if (name != "FMOD mixer thread" && name != "FMOD feeder thread" &&
         name != "FMOD Convolution thread" && name != "FMOD Worker Thread") {
       return false;
     }
+#if defined(__x86_64__)
     const unsigned int control = _mm_getcsr();
     original_mode_ = control & kModeMask;
     _mm_setcsr(control | kModeMask);
+#else
+    std::uint64_t control;
+    __asm__ volatile("mrs %0, fpcr" : "=r"(control));
+    original_mode_ = control & kModeMask;
+    __asm__ volatile("msr fpcr, %0" ::"r"(control | kModeMask));
+#endif
     active_ = true;
     return true;
 #else
@@ -41,11 +51,18 @@ class FmodThreadFloatingPointMode final {
   }
 
   void Restore() noexcept {
-#if defined(__x86_64__)
+#if defined(__x86_64__) || defined(__aarch64__)
     if (active_) {
       // Restore only our two bits, preserving rounding, exception masks and
       // status flags set by the guest while the thread was attached.
+#if defined(__x86_64__)
       _mm_setcsr((_mm_getcsr() & ~kModeMask) | original_mode_);
+#else
+      std::uint64_t control;
+      __asm__ volatile("mrs %0, fpcr" : "=r"(control));
+      __asm__ volatile("msr fpcr, %0" ::"r"((control & ~kModeMask) |
+                                          original_mode_));
+#endif
       active_ = false;
     }
 #endif
@@ -56,6 +73,13 @@ class FmodThreadFloatingPointMode final {
   static constexpr unsigned int kModeMask = (1U << 15) | (1U << 6);
   unsigned int original_mode_ = 0;
   bool active_ = false;
+#elif defined(__aarch64__)
+  // FPCR FZ flushes single/double subnormals; FZ16 covers the half-precision
+  // path used by some voice DSP filters.
+  static constexpr std::uint64_t kModeMask =
+      (std::uint64_t{1} << 24) | (std::uint64_t{1} << 19);
+  std::uint64_t original_mode_ = 0;
+  bool active_ = false;
 #endif
 };
 

include/mocktail/audio/roblox_output_device_bridge.h

@@ -44,7 +44,10 @@ class RobloxOutputDeviceBridge final {
                                     std::string_view logical_name,
                                     std::uintptr_t image_base);
   static int GetOutputDeviceCount(void* self);
-  static void* GetOutputDeviceInfo(void* result, void* self, int index);
+  // A trivial aggregate lets the compiler implement the guest's platform
+  // sret convention (x8 on AArch64, hidden first argument on x86-64).
+  struct alignas(8) DeviceInfoResult { std::uint8_t bytes[56]{}; };
+  static DeviceInfoResult GetOutputDeviceInfo(void* self, int index);
   static int GetCurrentOutputDevice(void* self);
   static void SetCurrentOutputDevice(void* self, int index);
 
@@ -52,7 +55,7 @@ class RobloxOutputDeviceBridge final {
   Status PatchVtableLocked();
   bool RestoreVtableLocked();
   static int GetInputDeviceCount(void *self);
-  static void *GetInputDeviceInfo(void *result, void *self, int index);
+  static DeviceInfoResult GetInputDeviceInfo(void* self, int index);
   static int GetCurrentInputDevice(void *self);
   static void SetCurrentInputDevice(void *self, int index);
   int DeviceCount(bool input = false);
@@ -61,8 +64,7 @@ class RobloxOutputDeviceBridge final {
   void SelectDevice(int index, bool input = false);
   void ConstructGuestString(void* destination, std::string_view value) const;
 
-  std::unique_ptr<NativeInputCapture> capture_;
-  bool capture_profile_supported_ = false;
+  std::shared_ptr<NativeInputCapture> capture_;
   std::array<std::uintptr_t, 6> original_capture_methods_{};
   mutable std::mutex mutex_;
   compat::FmodOutputDeviceBridgeProfile profile_;

include/mocktail/graphics/angle_probe.h

@@ -16,6 +16,9 @@ struct AngleProbeOptions {
   bool allow_software_device = false;
 };
 
+// Checks ANGLE entry points and client extensions without initializing a display.
+BackendCapability InspectAngleLibraries(const AngleProbeOptions& options);
+
 // Loads a pinned ANGLE pair, verifies the required EGL/GLES symbols, and
 // initializes an EGL_PLATFORM_ANGLE Vulkan display. No context is fabricated.
 BackendCapability ProbeAngleVulkan(const AngleProbeOptions& options);

include/mocktail/graphics/chrome_trace_writer.h

@@ -0,0 +1,150 @@
+#ifndef MOCKTAIL_GRAPHICS_CHROME_TRACE_WRITER_H_
+#define MOCKTAIL_GRAPHICS_CHROME_TRACE_WRITER_H_
+
+#include <condition_variable>
+#include <cstdint>
+#include <cstdio>
+#include <filesystem>
+#include <initializer_list>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+
+namespace mocktail {
+namespace graphics {
+
+// Environment variable naming the trace file the Vulkan adapter writes.
+inline constexpr char kProfileTraceEnvironment[] = "MOCKTAIL_PROFILE_TRACE";
+
+struct TraceArg {
+  const char* key;
+  std::int64_t value;
+};
+
+// CLOCK_MONOTONIC in nanoseconds.
+std::uint64_t TraceClockNanos();
+// CPU time used so far by the calling thread, in nanoseconds.
+std::uint64_t TraceThreadCpuNanos();
+// CPU time used so far by every thread of the process, in nanoseconds.
+std::uint64_t TraceProcessCpuNanos();
+
+// CPU time spent between two successive presents.
+struct FrameCpuSample {
+  double process_ms = 0;
+  // Set only when the previous present came from the same thread; thread CPU
+  // clocks of different threads cannot be subtracted.
+  bool has_thread = false;
+  double thread_ms = 0;
+};
+
+// Turns CPU clocks read at each present into per-frame CPU time.
+// Thread-safe.
+class FrameCpuSampler final {
+ public:
+  // Returns false for the first present, which ends no frame.
+  bool Sample(std::uint64_t thread_id, std::uint64_t thread_cpu_ns,
+              std::uint64_t process_cpu_ns, FrameCpuSample* sample);
+
+ private:
+  std::mutex mutex_;
+  bool has_previous_ = false;
+  std::uint64_t previous_thread_id_ = 0;
+  std::uint64_t previous_thread_cpu_ns_ = 0;
+  std::uint64_t previous_process_cpu_ns_ = 0;
+};
+
+// Writes the Trace Event Format JSON array read by chrome://tracing and
+// ui.perfetto.dev. Recording threads only format into a shared buffer; a
+// background thread owns file writes, so disk stalls do not land inside the
+// measured calls. Events are written in arrival order. Each write ends the
+// file with the closing bracket, so a killed session leaves a loadable trace
+// holding everything written before it died.
+// Names, categories, and keys must outlive the call.
+class ChromeTraceWriter final {
+ public:
+  static std::unique_ptr<ChromeTraceWriter> Open(
+      const std::filesystem::path& path, std::string* error);
+
+  ~ChromeTraceWriter();
+  ChromeTraceWriter(const ChromeTraceWriter&) = delete;
+  ChromeTraceWriter& operator=(const ChromeTraceWriter&) = delete;
+
+  // A complete ("X") slice on the calling thread. Slices on one thread must
+  // nest, which scoped timing gives.
+  void Slice(const char* name, const char* category, std::uint64_t start_ns,
+             std::uint64_t end_ns, std::initializer_list<TraceArg> args = {});
+  void Slice(const char* name, const char* category, std::uint64_t start_ns,
+             std::uint64_t end_ns, const TraceArg* args,
+             std::size_t arg_count);
+  // A counter ("C") sample; each name becomes one counter track.
+  void Counter(const char* name, std::uint64_t timestamp_ns, double value);
+
+  // Returns once every event recorded before the call is on disk.
+  void Flush();
+  // Flushes, closes the file, and drops later events. Idempotent.
+  void Close();
+
+ private:
+  explicit ChromeTraceWriter(std::FILE* file);
+  void Append(const char* event, std::size_t size);
+  void WriterLoop();
+  void WritePending();
+
+  std::FILE* file_;
+  const int owner_pid_;
+  std::mutex file_mutex_;  // Guards file_ and spare_.
+  std::string spare_;
+  std::mutex mutex_;
+  std::condition_variable wake_;
+  std::string pending_;
+  bool first_event_ = true;
+  bool closed_ = false;
+  bool stopping_ = false;
+  std::thread writer_;
+};
+
+// The process trace named by MOCKTAIL_PROFILE_TRACE, opened on first use.
+// Null when profiling is off or the file could not be opened. The writer is
+// never destroyed; it is closed when the process exits normally.
+ChromeTraceWriter* ActiveProfileTrace();
+
+// Times its own lifetime as one slice. A null writer records nothing.
+class TraceScope final {
+ public:
+  TraceScope(ChromeTraceWriter* writer, const char* name,
+             const char* category)
+      : writer_(writer),
+        name_(name),
+        category_(category),
+        start_ns_(writer != nullptr ? TraceClockNanos() : 0) {}
+  ~TraceScope() {
+    if (writer_ != nullptr) {
+      writer_->Slice(name_, category_, start_ns_, TraceClockNanos(), args_,
+                     arg_count_);
+    }
+  }
+  TraceScope(const TraceScope&) = delete;
+  TraceScope& operator=(const TraceScope&) = delete;
+
+  // Keeps the first kMaxArgs arguments.
+  void Arg(const char* key, std::int64_t value) {
+    if (writer_ != nullptr && arg_count_ < kMaxArgs) {
+      args_[arg_count_++] = {key, value};
+    }
+  }
+
+ private:
+  static constexpr std::size_t kMaxArgs = 4;
+  ChromeTraceWriter* writer_;
+  const char* name_;
+  const char* category_;
+  std::uint64_t start_ns_;
+  TraceArg args_[kMaxArgs]{};
+  std::size_t arg_count_ = 0;
+};
+
+}  // namespace graphics
+}  // namespace mocktail
+
+#endif  // MOCKTAIL_GRAPHICS_CHROME_TRACE_WRITER_H_

include/mocktail/graphics/etc2_decoder.h

@@ -66,6 +66,14 @@ struct EtcDecodeJob {
 void DecodeEtcJobs(EtcDecodeJob* jobs, std::size_t count,
                    unsigned worker_count);
 
+// Calls run(context) worker_count times, once on the caller and the rest on
+// pooled decode workers that run alongside it, and returns when every call
+// has returned. `run` must be safe to call from several threads at once, so
+// it should drain a shared queue. When the pool is busy with another batch,
+// or no worker could be started, run is called on the caller alone.
+void RunOnDecodeWorkers(void (*run)(void*), void* context,
+                        unsigned worker_count);
+
 }  // namespace mocktail::graphics
 
 #endif  // MOCKTAIL_GRAPHICS_ETC2_DECODER_H_

include/mocktail/graphics/present_mode_policy.h

@@ -2,6 +2,7 @@
 #define MOCKTAIL_GRAPHICS_PRESENT_MODE_POLICY_H_
 
 #include <cstdint>
+#include <cstdio>
 #include <string_view>
 #include <vector>
 
@@ -29,6 +30,36 @@ FilterPresentModes(PresentModePolicy policy,
 const char *PresentModePolicyName(PresentModePolicy policy);
 const char *PresentModeKhrName(VkPresentModeKHR mode);
 
+// Creates the swapchain with the mode in `info`. A driver can reject a mode
+// that the device did not enable, so a failed create is retried once with the
+// mode the game asked for. `create` takes the info and returns a VkResult.
+template <typename Create>
+VkResult CreateSwapchainWithPresentModeFallback(VkSwapchainCreateInfoKHR &info,
+                                                VkPresentModeKHR requested,
+                                                Create create) {
+  const VkResult result = create(info);
+  if (result == VK_SUCCESS || info.presentMode == requested) {
+    return result;
+  }
+  switch (result) {
+  case VK_ERROR_OUT_OF_HOST_MEMORY:
+  case VK_ERROR_OUT_OF_DEVICE_MEMORY:
+  case VK_ERROR_DEVICE_LOST:
+  case VK_ERROR_SURFACE_LOST_KHR:
+  case VK_ERROR_NATIVE_WINDOW_IN_USE_KHR:
+    return result; // Another present mode cannot fix these.
+  default:
+    break;
+  }
+  std::fprintf(stderr,
+               "  [vulkan] swapchain presentMode %s failed (%d); retrying "
+               "with %s\n",
+               PresentModeKhrName(info.presentMode), static_cast<int>(result),
+               PresentModeKhrName(requested));
+  info.presentMode = requested;
+  return create(info);
+}
+
 // Extra images so acquire does not wait on the compositor-held buffer.
 std::uint32_t PreferSwapchainMinImageCount(PresentModePolicy policy,
                                            std::uint32_t requested,

include/mocktail/graphics/texture_override.h

@@ -35,6 +35,10 @@ void ResampleRgba(const RgbaImage& source, std::uint32_t width,
 void ResampleRgba(const std::uint8_t* source, std::uint32_t source_width,
                   std::uint32_t source_height, std::uint32_t width,
                   std::uint32_t height, std::uint8_t* destination);
+void ResampleRgba(const std::uint8_t* source, std::uint32_t source_width,
+                  std::uint32_t source_height, std::size_t source_stride_bytes,
+                  std::uint32_t width, std::uint32_t height,
+                  std::uint8_t* destination);
 
 // Replacement textures keyed by the hash of a texture's level-0 compressed
 // bytes. An override lives at <override_dir>/<hash>.png. With a dump

include/mocktail/graphics/vulkan_barrier_adjustment.h

@@ -0,0 +1,55 @@
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+#include <vulkan/vulkan.h>
+
+namespace mocktail::graphics::internal {
+
+// Only transfers between two concrete queue families can be converted for a
+// desktop swapchain. External/foreign ownership must reach the driver intact.
+inline bool NeedsDesktopQueueNormalization(std::uint32_t source,
+                                            std::uint32_t destination) {
+  return source != destination && source < VK_QUEUE_FAMILY_FOREIGN_EXT &&
+         destination < VK_QUEUE_FAMILY_FOREIGN_EXT;
+}
+
+template <class Barrier>
+inline bool HasDesktopQueueTransfers(std::uint32_t count,
+                                    const Barrier* barriers) {
+  if (!barriers) return false;
+  for (std::uint32_t i = 0; i < count; ++i)
+    if (NeedsDesktopQueueNormalization(barriers[i].srcQueueFamilyIndex,
+                                       barriers[i].dstQueueFamilyIndex))
+      return true;
+  return false;
+}
+
+// Keep the caller's array for the common no-ownership-transfer path. A batch
+// callback can inspect a mixed array under one backend lock; the original
+// array and every structure chained through pNext remain untouched.
+template <class Barrier, class Normalize, class Forward>
+inline void WithDesktopQueueBarriers(std::uint32_t count,
+                                     const Barrier* barriers,
+                                     Normalize&& normalize, Forward&& forward) {
+  if (!HasDesktopQueueTransfers(count, barriers)) {
+    forward(barriers);
+    return;
+  }
+  constexpr std::size_t kStackCount = 8;
+  if (count <= kStackCount) {
+    std::array<Barrier, kStackCount> adjusted;
+    std::copy_n(barriers, count, adjusted.data());
+    normalize(count, adjusted.data());
+    forward(adjusted.data());
+  } else {
+    std::vector<Barrier> adjusted(barriers, barriers + count);
+    normalize(count, adjusted.data());
+    forward(adjusted.data());
+  }
+}
+
+}  // namespace mocktail::graphics::internal

include/mocktail/graphics/vulkan_etc2_emulation.h

@@ -30,6 +30,18 @@ bool Etc2UploadByteCounts(EtcFormat format, const VkExtent3D& extent,
                           std::uint32_t layer_count, VkDeviceSize* compressed,
                           VkDeviceSize* decoded);
 
+// Sums every mip level and layer; `scale` multiplies the host image's
+// level-0 width and height only.
+bool Etc2ImageByteCounts(EtcFormat format, const VkExtent3D& extent,
+                         std::uint32_t mip_levels, std::uint32_t layers,
+                         std::uint32_t scale, VkDeviceSize* compressed,
+                         VkDeviceSize* decoded);
+
+struct EmulatedTextureBytes {
+  VkDeviceSize compressed = 0;
+  VkDeviceSize decoded = 0;
+};
+
 // Whether emulated ETC2 is reported to the application as a supported
 // feature, from the MOCKTAIL_ADVERTISE_ETC2 value: "0" hides it, anything
 // else (or unset) reports it. Hidden ETC2 still decodes ETC2 images the
@@ -47,17 +59,30 @@ inline constexpr std::uint32_t kSmallTextureMaxExtent = 64;
 inline constexpr std::uint32_t kDefaultSmallTextureUpscale = 4;
 std::uint32_t SmallTextureUpscale(const char* value);
 
+// Staging for decoded uploads is carved out of host-visible blocks this
+// large; an upload that needs more gets a block of its own.
+inline constexpr VkDeviceSize kEtc2StagingBlockBytes = 16 * 1024 * 1024;
+
+// A timeline semaphore and the value an asynchronous decode will signal.
+// `semaphore` is VK_NULL_HANDLE when the decode already finished on the
+// calling thread and the submit needs no extra wait.
+struct Etc2SubmitWait {
+  VkSemaphore semaphore = VK_NULL_HANDLE;
+  std::uint64_t value = 0;
+};
+
 // Reports ETC2/EAC support on hosts without native ETC2 (desktop GPUs) and
 // stores those textures decoded. Images are created with the host format;
 // each staged upload into one is redirected to a host-visible staging buffer
 // that is filled by decoding the application's staging bytes when the
 // command buffer is submitted. Every submit decodes again, as a native copy
 // re-reads its source on each execution.
-// Staging buffers live until their command buffer is begun, reset or freed.
+// Staging ranges live until their command buffer is begun, reset or freed.
 // MOCKTAIL_DISABLE_ETC2_EMULATION=1 turns the emulation off.
 class VulkanEtc2Emulation final {
  public:
-  VulkanEtc2Emulation();
+  explicit VulkanEtc2Emulation(
+      VkDeviceSize staging_block_bytes = kEtc2StagingBlockBytes);
   ~VulkanEtc2Emulation();
   VulkanEtc2Emulation(const VulkanEtc2Emulation&) = delete;
   VulkanEtc2Emulation& operator=(const VulkanEtc2Emulation&) = delete;
@@ -66,10 +91,14 @@ class VulkanEtc2Emulation final {
   bool PhysicalDeviceNeedsEmulation(VkPhysicalDevice physical_device,
                                     PFN_vkGetPhysicalDeviceFeatures host);
 
+  // `timeline_semaphore` states whether the device was created with the
+  // timelineSemaphore feature enabled. Without it every decode runs on the
+  // calling thread.
   void RegisterDevice(VkDevice device, VkPhysicalDevice physical_device,
                       bool emulated,
                       const VkPhysicalDeviceMemoryProperties& memory,
-                      PFN_vkGetDeviceProcAddr get_device_proc_addr);
+                      PFN_vkGetDeviceProcAddr get_device_proc_addr,
+                      bool timeline_semaphore = false);
   void DestroyDevice(VkDevice device);
 
   VkResult CreateImage(VkDevice device, const VkImageCreateInfo* create_info,
@@ -112,14 +141,33 @@ class VulkanEtc2Emulation final {
                           const VkCommandBuffer* secondaries);
 
   // Decodes every upload recorded into these command buffers and the
-  // secondary command buffers they execute. Large batches decode on worker
-  // threads; this returns once every upload is decoded.
-  void PrepareSubmit(const VkCommandBuffer* command_buffers,
-                     std::uint32_t count);
+  // secondary command buffers they execute.
+  //
+  // With `allow_async` on a device that has a timeline semaphore, the decode
+  // runs on worker threads, and so does the gather of the compressed bytes
+  // whenever the application already has them mapped. The returned semaphore
+  // and value must then be added to the submit's waits, so the GPU copy
+  // cannot execute before the decode finishes. Values are signalled in the
+  // order they are handed out.
+  //
+  // Those threads read the application's source bytes after this returns,
+  // which Vulkan allows: the application may not write them between the
+  // submit and the copy's completion. Unmapping or freeing that memory waits
+  // for the decodes still reading it.
+  //
+  // Returns `{VK_NULL_HANDLE, 0}` when there was nothing to decode, when
+  // `allow_async` is false, or when the device has no timeline semaphore. In
+  // those cases every upload is already decoded when this returns.
+  Etc2SubmitWait PrepareSubmit(const VkCommandBuffer* command_buffers,
+                               std::uint32_t count, bool allow_async = false);
   // Destroys the staging buffers owned by a command buffer that is no longer
-  // pending.
+  // pending, after waiting for any decode still writing into them.
   void ReleaseCommandBuffer(VkCommandBuffer command_buffer);
 
+  // Traced as the "emulated texture (MB)" and "compressed texture (MB)"
+  // counters.
+  EmulatedTextureBytes TextureBytes() const;
+
   struct State;
 
  private:

include/mocktail/graphics/vulkan_foveation_device_policy.h

@@ -0,0 +1,44 @@
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <vulkan/vulkan.h>
+
+namespace mocktail::graphics::internal {
+
+struct FoveationDevicePolicy {
+  bool density_offsets_enabled = true;
+};
+
+// Capture before invoking a runtime/loader device callback: its temporary
+// feature-chain records must never be inspected after the call returns.
+inline FoveationDevicePolicy SnapshotFoveationDevicePolicy(
+    const VkDeviceCreateInfo* info) {
+  if (!info || info->sType != VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO ||
+      info->enabledExtensionCount > 4096 ||
+      (info->enabledExtensionCount && !info->ppEnabledExtensionNames)) return {};
+  bool offsets = false;
+  for (std::uint32_t i = 0; i < info->enabledExtensionCount; ++i) {
+    const char* name = info->ppEnabledExtensionNames[i];
+    if (!name) return {};
+    if (!std::strcmp(name, "VK_QCOM_fragment_density_map_offset") ||
+        !std::strcmp(name, "VK_EXT_fragment_density_map_offset"))
+      offsets = true;
+  }
+  std::array<const VkBaseInStructure*, 64> seen{};
+  std::size_t count = 0;
+  for (auto* node = static_cast<const VkBaseInStructure*>(info->pNext);
+       node; node = node->pNext) {
+    if (count == seen.size()) return {};
+    for (std::size_t i = 0; i < count; ++i) if (seen[i] == node) return {};
+    seen[count++] = node;
+    if (node->sType == VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_FEATURES_EXT)
+      offsets |= reinterpret_cast<const VkPhysicalDeviceFragmentDensityMapOffsetFeaturesEXT*>(node)
+                     ->fragmentDensityMapOffset != VK_FALSE;
+  }
+  return {offsets};
+}
+
+}  // namespace mocktail::graphics::internal

include/mocktail/platform/platform_runtime.h

@@ -152,6 +152,10 @@ struct MouseMotionEvent {
   float delta_x = 0.0f;
   float delta_y = 0.0f;
   std::uint32_t buttons = 0;
+  // True while the window holds relative mouse mode. The absolute coordinates
+  // are meaningless then: X11 reports zeroes, Wayland reports a position that
+  // accumulates the deltas and can leave the window entirely.
+  bool relative = false;
 };
 
 struct MouseButtonEvent {
@@ -160,6 +164,8 @@ struct MouseButtonEvent {
   std::uint8_t clicks = 0;
   float x = 0.0f;
   float y = 0.0f;
+  // See MouseMotionEvent::relative.
+  bool relative = false;
 };
 
 struct MouseWheelEvent {
@@ -167,6 +173,8 @@ struct MouseWheelEvent {
   float delta_y = 0.0f;
   float mouse_x = 0.0f;
   float mouse_y = 0.0f;
+  // See MouseMotionEvent::relative.
+  bool relative = false;
 };
 
 struct TouchEvent {

include/mocktail/vr/anti_aliasing_settings.h

@@ -0,0 +1,10 @@
+#pragma once
+
+#include <cstdint>
+
+namespace mocktail::vr::internal {
+// Retired multisample choices use the native profile's SMAA High default.
+constexpr int NativeAntiAliasingMode(std::int64_t value) {
+  return value >= 0 && value <= 3 ? static_cast<int>(value) : 3;
+}
+}  // namespace mocktail::vr::internal

include/mocktail/vr/async_settings.h

@@ -0,0 +1,70 @@
+#pragma once
+
+#include <chrono>
+#include <condition_variable>
+#include <functional>
+#include <mutex>
+#include <thread>
+#include <type_traits>
+
+namespace mocktail::vr::internal {
+
+// Load once during startup, then keep file I/O and parsing on a worker. The
+// render thread only copies a completed snapshot under a short-held lock.
+template <typename T>
+class AsyncSettings {
+ public:
+  using Reader = std::function<T(const T&)>;
+  AsyncSettings(T initial, Reader reader, std::chrono::milliseconds interval)
+      : value_(initial), reader_(std::move(reader)), interval_(interval) {
+    static_assert(std::is_trivially_copyable_v<T>);
+    Refresh();
+    worker_ = std::thread([this] {
+      std::unique_lock<std::mutex> stop_lock(stop_mutex_);
+      while (!stopped_) {
+        if (wake_.wait_for(stop_lock, interval_, [this] { return stopped_; }))
+          break;
+        stop_lock.unlock();
+        Refresh();
+        stop_lock.lock();
+      }
+    });
+  }
+  ~AsyncSettings() {
+    {
+      std::lock_guard<std::mutex> lock(stop_mutex_);
+      stopped_ = true;
+    }
+    wake_.notify_one();
+    if (worker_.joinable()) worker_.join();
+  }
+  AsyncSettings(const AsyncSettings&) = delete;
+  AsyncSettings& operator=(const AsyncSettings&) = delete;
+
+  T Get() const {
+    std::lock_guard<std::mutex> lock(value_mutex_);
+    return value_;
+  }
+
+ private:
+  void Refresh() {
+    try {
+      const T next = reader_(Get());
+      std::lock_guard<std::mutex> lock(value_mutex_);
+      value_ = next;
+    } catch (...) {
+      // A failed read retains the last completed settings. In particular,
+      // parsing must never throw through a guest rendering callback.
+    }
+  }
+  mutable std::mutex value_mutex_;
+  T value_;
+  Reader reader_;
+  std::chrono::milliseconds interval_;
+  std::mutex stop_mutex_;
+  std::condition_variable wake_;
+  bool stopped_ = false;
+  std::thread worker_;
+};
+
+}  // namespace mocktail::vr::internal

include/mocktail/vr/desktop_mirror.h

@@ -0,0 +1,78 @@
+#ifndef MOCKTAIL_VR_DESKTOP_MIRROR_H_
+#define MOCKTAIL_VR_DESKTOP_MIRROR_H_
+
+#include <algorithm>
+#include <vulkan/vulkan.h>
+
+namespace mocktail::vr::internal {
+
+struct DesktopMirrorDispatch {
+  PFN_vkCmdPipelineBarrier barrier;
+  PFN_vkCmdClearColorImage clear;
+  PFN_vkCmdBlitImage blit;
+};
+
+// Record the whole copy, including layout restoration, into the submission's
+// command buffer. The caller owns synchronization, begin/end and submission.
+inline void RecordDesktopMirrorCommands(
+    VkCommandBuffer command, VkImage source, VkImageLayout source_layout,
+    VkExtent2D source_extent, VkImage destination, VkExtent2D destination_extent,
+    const DesktopMirrorDispatch& vk) {
+  VkImageMemoryBarrier barriers[2]{};
+  for (auto& barrier : barriers) {
+    barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
+    barrier.srcQueueFamilyIndex = barrier.dstQueueFamilyIndex =
+        VK_QUEUE_FAMILY_IGNORED;
+    barrier.subresourceRange = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1};
+    barrier.srcAccessMask = VK_ACCESS_MEMORY_WRITE_BIT | VK_ACCESS_MEMORY_READ_BIT;
+  }
+  barriers[0].image = source;
+  barriers[0].oldLayout = source_layout;
+  barriers[0].newLayout = VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL;
+  barriers[0].dstAccessMask = VK_ACCESS_TRANSFER_READ_BIT;
+  barriers[1].image = destination;
+  barriers[1].oldLayout = VK_IMAGE_LAYOUT_PRESENT_SRC_KHR;
+  barriers[1].newLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
+  barriers[1].dstAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
+  vk.barrier(command, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
+             VK_PIPELINE_STAGE_TRANSFER_BIT, 0, 0, nullptr, 0, nullptr, 2,
+             barriers);
+  const VkClearColorValue black{{0.f, 0.f, 0.f, 1.f}};
+  vk.clear(command, destination, barriers[1].newLayout, &black, 1,
+           &barriers[1].subresourceRange);
+  VkMemoryBarrier clear_barrier{};
+  clear_barrier.sType = VK_STRUCTURE_TYPE_MEMORY_BARRIER;
+  clear_barrier.srcAccessMask = clear_barrier.dstAccessMask =
+      VK_ACCESS_TRANSFER_WRITE_BIT;
+  vk.barrier(command, VK_PIPELINE_STAGE_TRANSFER_BIT,
+             VK_PIPELINE_STAGE_TRANSFER_BIT, 0, 1, &clear_barrier, 0, nullptr, 0,
+             nullptr);
+  const double scale =
+      std::min(double(destination_extent.width) / source_extent.width,
+               double(destination_extent.height) / source_extent.height);
+  const int width = std::max(1, int(source_extent.width * scale));
+  const int height = std::max(1, int(source_extent.height * scale));
+  const int x = (int(destination_extent.width) - width) / 2;
+  const int y = (int(destination_extent.height) - height) / 2;
+  VkImageBlit region{};
+  region.srcSubresource =
+      region.dstSubresource = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1};
+  region.srcOffsets[1] = {static_cast<int>(source_extent.width),
+                          static_cast<int>(source_extent.height), 1};
+  region.dstOffsets[0] = {x, y, 0};
+  region.dstOffsets[1] = {x + width, y + height, 1};
+  vk.blit(command, source, barriers[0].newLayout, destination,
+          barriers[1].newLayout, 1, &region, VK_FILTER_NEAREST);
+  for (auto& barrier : barriers) {
+    std::swap(barrier.oldLayout, barrier.newLayout);
+    barrier.srcAccessMask = barrier.dstAccessMask;
+    barrier.dstAccessMask = VK_ACCESS_MEMORY_READ_BIT;
+  }
+  vk.barrier(command, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
+             VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, 0, 0, nullptr, 0, nullptr, 2,
+             barriers);
+}
+
+}  // namespace mocktail::vr::internal
+
+#endif  // MOCKTAIL_VR_DESKTOP_MIRROR_H_

include/mocktail/vr/eye_resize_boundary.h

@@ -0,0 +1,18 @@
+#ifndef MOCKTAIL_VR_EYE_RESIZE_BOUNDARY_H_
+#define MOCKTAIL_VR_EYE_RESIZE_BOUNDARY_H_
+
+namespace mocktail::vr::internal {
+// Eye getters return borrowed render targets. Replacing those targets after
+// either eye has been requested can invalidate work recorded earlier in the
+// same frame, even if all previously submitted GPU work has finished.
+class EyeResizeBoundary {
+ public:
+  void OnPresent() { presented_ = true; eyes_used_ = false; }
+  void OnEyeGetter() { eyes_used_ = true; }
+  bool CanResize() const { return presented_ && !eyes_used_; }
+ private:
+  bool presented_ = false;
+  bool eyes_used_ = false;
+};
+}  // namespace mocktail::vr::internal
+#endif

include/mocktail/vr/foveation_focus.h

@@ -0,0 +1,226 @@
+#pragma once
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <vector>
+
+namespace mocktail::vr::internal {
+struct QuantizedGazeCenter {unsigned x=0,y=0;};
+inline QuantizedGazeCenter QuantizeGazeCenter(unsigned width,unsigned height,float x,float y) {
+  if(!width || !height || !std::isfinite(x) || !std::isfinite(y))return {};
+  return {unsigned(std::round((std::clamp(x,-1.f,1.f)+1.f)*.5f*width*4.f)),
+          unsigned(std::round((1.f-std::clamp(y,-1.f,1.f))*.5f*height*4.f))};
+}
+inline float ClampGazeRadius(float radius) {
+  return std::isfinite(radius)?std::clamp(radius,.08f,.35f):.22f;
+}
+inline bool ProjectGazeNdc(const float* gaze,const float* eye,const float* fov,float* x,float* y) {
+  if(!gaze || !eye || !fov || !x || !y)return false;
+  auto rotate=[](const float* q,const float* v,float* out) {
+    float length=0;for(int i=0;i<4;++i){if(!std::isfinite(q[i]))return false;length+=q[i]*q[i];}
+    if(length<1e-8f)return false;
+    const float inverse=1.f/std::sqrt(length);
+    const float a=q[0]*inverse,b=q[1]*inverse,c=q[2]*inverse,d=q[3]*inverse;
+    const float tx=2.f*(b*v[2]-c*v[1]),ty=2.f*(c*v[0]-a*v[2]),tz=2.f*(a*v[1]-b*v[0]);
+    out[0]=v[0]+d*tx+b*tz-c*ty;out[1]=v[1]+d*ty+c*tx-a*tz;out[2]=v[2]+d*tz+a*ty-b*tx;
+    return true;
+  };
+  const float forward[3]={0,0,-1};float local[3],world[3];
+  const float inverse_eye[4]={-eye[0],-eye[1],-eye[2],eye[3]};
+  if(!rotate(gaze,forward,world) || !rotate(inverse_eye,world,local) || local[2]>=-1e-5f)return false;
+  const float left=std::tan(fov[0]),right=std::tan(fov[1]),up=std::tan(fov[2]),down=std::tan(fov[3]);
+  if(!std::isfinite(left+right+up+down) || right<=left || up<=down)return false;
+  *x=2.f*(local[0]/-local[2]-left)/(right-left)-1.f;
+  *y=2.f*(local[1]/-local[2]-down)/(up-down)-1.f;
+  return std::isfinite(*x)&&std::isfinite(*y);
+}
+// OpenXR eye-foveation centers use NDC (+Y up). Vulkan framebuffer/image rows
+// run downwards. Preserve a generous full-density disk around the actual gaze;
+// reduce shading only outside it. Density maps store reciprocal fragment size.
+inline void FillGazeDensityMap(std::vector<std::uint8_t>& pixels,unsigned width,unsigned height,
+    float ndc_x,float ndc_y,int level=2,float radius=.22f,
+    float region_half_width=0.f,float region_half_height=0.f) {
+  pixels.assign(std::size_t(width)*height*2,255);
+  if(!width || !height || !std::isfinite(ndc_x) || !std::isfinite(ndc_y) || level<=0)return;
+  // Quarter-cell quantization avoids uploading new maps for tiny gaze jitter.
+  // Its maximum position error is well inside the cell-diagonal guard below.
+  const auto center=QuantizeGazeCenter(width,height,ndc_x,ndc_y);
+  const float cx=center.x/(width*4.f),cy=center.y/(height*4.f);
+  const float inner=ClampGazeRadius(radius);
+  // Performance reduces detail sooner outside the same protected focus disk.
+  const float outer=inner+(level==1?.36f:level==2?.26f:.10f);
+  const float peripheral_work=level==1?.25f:.0625f;
+  // A scalar ramp is quantized by the GPU into a few hard rings. Mix adjacent
+  // supported fragment areas over a stable spatial pattern instead. This gives
+  // intermediate average shading densities without temporal random noise or a
+  // second full-resolution render. Alternate the elongated fragment direction
+  // so intermediate stages do not consistently favour horizontal edges.
+  constexpr float work[]={1.f,.5f,.25f,.125f,.0625f};
+  constexpr unsigned sizes[][2]={{1,1},{1,2},{2,2},{2,4},{4,4}};
+  constexpr unsigned threshold[4][4]={{0,8,2,10},{12,4,14,6},{3,11,1,9},{15,7,13,5}};
+  // Each map cell covers an area, not a point. Extend the full-detail region
+  // by a cell diagonal so a gaze near a cell boundary cannot land in a coarse
+  // fragment just outside the mathematical disk.
+  const float margin=std::hypot(1.f/width,1.f/height);
+  const float inner_squared=(inner+margin)*(inner+margin);
+  const float outer_squared=(outer+margin)*(outer+margin);
+  const auto peripheral_density=static_cast<std::uint8_t>(level==1?127:63);
+  for(unsigned y=0;y<height;++y)for(unsigned x=0;x<width;++x) {
+    // A tiled GPU samples density at its region centre and applies it to the
+    // entire region. Protect every region that could intersect the focus, not
+    // just the tiny map cell containing the gaze. The bound comes from the
+    // device's maxFragmentDensityTexelSize in framebuffer pixels.
+    const float dx=std::max(0.f,std::abs((x+.5f)/width-cx)-region_half_width);
+    const float dy=std::max(0.f,std::abs((y+.5f)/height-cy)-region_half_height);
+    // Flat regions need no square root or density-stage search. The output
+    // was initialized to full detail above; the peripheral reciprocal is exact.
+    // Keep the existing hypot/ramp calculation throughout the transition.
+    const float squared=dx*dx+dy*dy;
+    if(squared<=inner_squared)continue;
+    if(squared>=outer_squared) {
+      const auto index=(std::size_t(y)*width+x)*2;
+      pixels[index]=pixels[index+1]=peripheral_density;
+      continue;
+    }
+    const float distance=std::hypot(dx,dy);
+    float t=std::clamp((distance-inner-margin)/(outer-inner),0.f,1.f);
+    t=t*t*(3.f-2.f*t);
+    const float target=1.f-t*(1.f-peripheral_work);
+    unsigned stage=0;
+    while(stage<4 && target<work[stage+1])++stage;
+    if(stage<4) {
+      const float blend=(work[stage]-target)/(work[stage]-work[stage+1]);
+      if(blend>(threshold[y%4][x%4]+.5f)/16.f)++stage;
+    }
+    const unsigned flip=(x+y)&1u;
+    const auto index=(std::size_t(y)*width+x)*2;
+    // Round density down: 128/255 requests an area smaller than 2 pixels,
+    // which a conforming driver may clamp to 1; 127/255 actually permits 2.
+    pixels[index]=static_cast<std::uint8_t>(255u/sizes[stage][flip]);
+    pixels[index+1]=static_cast<std::uint8_t>(255u/sizes[stage][1u-flip]);
+  }
+}
+inline std::vector<std::uint8_t> GazeDensityMap(unsigned width,unsigned height,
+    float ndc_x,float ndc_y,int level=2,float radius=.22f,
+    float region_half_width=0.f,float region_half_height=0.f) {
+  std::vector<std::uint8_t> pixels;
+  FillGazeDensityMap(pixels,width,height,ndc_x,ndc_y,level,radius,region_half_width,region_half_height);
+  return pixels;
+}
+
+struct FramebufferDensityLayout {
+  unsigned map_width=0,map_height=0,width=0,height=0;
+  unsigned texel_width=0,texel_height=0,active_width=0,active_height=0;
+  bool valid=false;
+};
+// Turnip samples at pixel>>ceil(log2(framebuffer/map)), clamped to the
+// advertised power-of-two texel limits. Allocation padding is not scene UV.
+inline FramebufferDensityLayout TurnipDensityLayout(unsigned map_width,unsigned map_height,
+    unsigned width,unsigned height,unsigned min_width,unsigned min_height,
+    unsigned max_width,unsigned max_height) {
+  FramebufferDensityLayout result{map_width,map_height,width,height};
+  const auto power=[](unsigned value){return value && !(value&(value-1));};
+  if(!map_width || !map_height || !width || !height || !power(min_width) ||
+      !power(min_height) || !power(max_width) || !power(max_height) ||
+      min_width>max_width || min_height>max_height)return result;
+  const auto step=[](unsigned pixels,unsigned cells,unsigned minimum,unsigned maximum) {
+    unsigned value=minimum;
+    while(value<maximum && value<pixels/cells)value*=2;
+    return value;
+  };
+  result.texel_width=step(width,map_width,min_width,max_width);
+  result.texel_height=step(height,map_height,min_height,max_height);
+  result.active_width=1+(width-1)/result.texel_width;
+  result.active_height=1+(height-1)/result.texel_height;
+  result.valid=result.active_width<=map_width && result.active_height<=map_height;
+  return result;
+}
+inline QuantizedGazeCenter QuantizeFramebufferGaze(const FramebufferDensityLayout& layout,
+    float x,float y) {
+  if(!layout.valid || !std::isfinite(x) || !std::isfinite(y))return {};
+  return {unsigned(std::round((std::clamp(x,-1.f,1.f)+1.f)*.5f*layout.width*4.f/layout.texel_width)),
+          unsigned(std::round((1.f-std::clamp(y,-1.f,1.f))*.5f*layout.height*4.f/layout.texel_height))};
+}
+struct GazeDensityMapKey {
+  unsigned x=0,y=0,width=0,height=0,map_width=0,map_height=0,texel_width=0,texel_height=0;
+  int level=0;float radius=0;
+  unsigned guard_width=0,guard_height=0,color_format=0,depth_format=0,samples=0,attachments=0;
+  bool operator==(const GazeDensityMapKey& other) const {
+    return x==other.x && y==other.y && width==other.width && height==other.height &&
+        map_width==other.map_width && map_height==other.map_height &&
+        texel_width==other.texel_width && texel_height==other.texel_height &&
+        level==other.level && radius==other.radius &&
+        guard_width==other.guard_width && guard_height==other.guard_height &&
+        color_format==other.color_format && depth_format==other.depth_format &&
+        samples==other.samples && attachments==other.attachments;
+  }
+};
+enum class GazeDensityCacheAction { kUpload,kReuse,kNeutral };
+inline GazeDensityCacheAction DensityCacheAction(bool initialized,bool cached,
+    std::uint64_t uploaded_frame,std::uint64_t frame,const GazeDensityMapKey& previous,
+    const GazeDensityMapKey& requested) {
+  if(initialized && cached && previous==requested)return GazeDensityCacheAction::kReuse;
+  // A map already referenced in this frame cannot safely be overwritten for
+  // another extent. Its pass uses the neutral map until the next frame.
+  if(initialized && uploaded_frame==frame)return GazeDensityCacheAction::kNeutral;
+  return GazeDensityCacheAction::kUpload;
+}
+inline bool FillFramebufferGazeDensityMap(std::vector<std::uint8_t>& pixels,
+    const FramebufferDensityLayout& layout,float ndc_x,float ndc_y,int level,float radius,
+    float region_half_width_pixels,float region_half_height_pixels) {
+  pixels.assign(std::size_t(layout.map_width)*layout.map_height*2,255);
+  if(!layout.valid || !std::isfinite(ndc_x) || !std::isfinite(ndc_y) ||
+      !std::isfinite(region_half_width_pixels) || !std::isfinite(region_half_height_pixels) ||
+      region_half_width_pixels<0 || region_half_height_pixels<0)return false;
+  if(level<=0)return true;
+  const auto center=QuantizeFramebufferGaze(layout,ndc_x,ndc_y);
+  const float cx=float(center.x)*layout.texel_width/(4.f*layout.width);
+  const float cy=float(center.y)*layout.texel_height/(4.f*layout.height);
+  const float guard_x=region_half_width_pixels/layout.width;
+  const float guard_y=region_half_height_pixels/layout.height;
+  const float inner=ClampGazeRadius(radius);
+  const float outer=inner+(level==1?.36f:level==2?.26f:.10f);
+  const float margin=std::hypot(float(layout.texel_width)/layout.width,
+                              float(layout.texel_height)/layout.height);
+  const float inner_squared=(inner+margin)*(inner+margin);
+  const float outer_squared=(outer+margin)*(outer+margin);
+  const float peripheral_work=level==1?.25f:.0625f;
+  const auto peripheral_density=static_cast<std::uint8_t>(level==1?127:63);
+  constexpr float work[]={1.f,.5f,.25f,.125f,.0625f};
+  constexpr unsigned sizes[][2]={{1,1},{1,2},{2,2},{2,4},{4,4}};
+  constexpr unsigned threshold[4][4]={{0,8,2,10},{12,4,14,6},{3,11,1,9},{15,7,13,5}};
+  for(unsigned y=0;y<layout.active_height;++y)for(unsigned x=0;x<layout.active_width;++x) {
+    const float px=(x+.5f)*layout.texel_width/layout.width;
+    const float py=(y+.5f)*layout.texel_height/layout.height;
+    const float dx=std::max(0.f,std::abs(px-cx)-guard_x);
+    const float dy=std::max(0.f,std::abs(py-cy)-guard_y);
+    const float squared=dx*dx+dy*dy;
+    if(squared<=inner_squared)continue;
+    const auto index=(std::size_t(y)*layout.map_width+x)*2;
+    if(squared>=outer_squared) {pixels[index]=pixels[index+1]=peripheral_density;continue;}
+    float t=std::clamp((std::hypot(dx,dy)-inner-margin)/(outer-inner),0.f,1.f);
+    t=t*t*(3.f-2.f*t);
+    const float target=1.f-t*(1.f-peripheral_work);
+    unsigned stage=0;
+    while(stage<4 && target<work[stage+1])++stage;
+    if(stage<4 && (work[stage]-target)/(work[stage]-work[stage+1])>
+        (threshold[y%4][x%4]+.5f)/16.f)++stage;
+    const unsigned flip=(x+y)&1u;
+    pixels[index]=static_cast<std::uint8_t>(255u/sizes[stage][flip]);
+    pixels[index+1]=static_cast<std::uint8_t>(255u/sizes[stage][1u-flip]);
+  }
+  return true;
+}
+// The driver advertises R16G16_SFLOAT density attachments. These exact binary
+// reciprocals avoid UNORM rounding and cover every area generated above.
+inline void FillHalfDensityMap(std::vector<std::uint16_t>& result,const std::vector<std::uint8_t>& pixels) {
+  result.resize(pixels.size());
+  for(std::size_t i=0;i<pixels.size();++i)
+    result[i]=pixels[i]==127?0x3800u:pixels[i]==63?0x3400u:0x3c00u;
+}
+inline std::vector<std::uint16_t> HalfDensityMap(const std::vector<std::uint8_t>& pixels) {
+  std::vector<std::uint16_t> result;
+  FillHalfDensityMap(result,pixels);
+  return result;
+}
+}

include/mocktail/vr/foveation_msaa_contract.h

@@ -0,0 +1,56 @@
+#pragma once
+
+#include <vulkan/vulkan.h>
+
+namespace mocktail::vr {
+
+inline bool IsFoveationSceneSampleCount(VkSampleCountFlagBits samples) {
+  return samples == VK_SAMPLE_COUNT_1_BIT || samples == VK_SAMPLE_COUNT_2_BIT ||
+         samples == VK_SAMPLE_COUNT_4_BIT || samples == VK_SAMPLE_COUNT_8_BIT;
+}
+
+// Preserve the native MSAA attachments and resolve. Only the extra density map
+// is single-sampled; changing the scene images or pipeline sample count here
+// would invalidate native framebuffers and memory allocations.
+inline bool IsFoveationScenePassCompatible(const VkRenderPassCreateInfo& info) {
+  if (info.pNext || info.flags || info.subpassCount != 1 || !info.pSubpasses ||
+      !info.pAttachments) {
+    return false;
+  }
+  const auto& subpass = info.pSubpasses[0];
+  if (subpass.flags || subpass.pipelineBindPoint != VK_PIPELINE_BIND_POINT_GRAPHICS ||
+      subpass.colorAttachmentCount != 1 || !subpass.pColorAttachments ||
+      !subpass.pDepthStencilAttachment || subpass.inputAttachmentCount ||
+      subpass.preserveAttachmentCount) {
+    return false;
+  }
+  const auto color = subpass.pColorAttachments[0].attachment;
+  const auto depth = subpass.pDepthStencilAttachment->attachment;
+  if (color >= info.attachmentCount || depth >= info.attachmentCount || color == depth) {
+    return false;
+  }
+  const auto samples = info.pAttachments[color].samples;
+  if (!IsFoveationSceneSampleCount(samples) || info.pAttachments[depth].samples != samples) {
+    return false;
+  }
+  const auto resolve = subpass.pResolveAttachments ?
+      subpass.pResolveAttachments[0].attachment : VK_ATTACHMENT_UNUSED;
+  if (resolve != VK_ATTACHMENT_UNUSED) {
+    if (samples == VK_SAMPLE_COUNT_1_BIT || info.attachmentCount != 3 ||
+        resolve >= info.attachmentCount || resolve == color || resolve == depth ||
+        info.pAttachments[resolve].samples != VK_SAMPLE_COUNT_1_BIT ||
+        info.pAttachments[resolve].format != info.pAttachments[color].format) {
+      return false;
+    }
+  } else if (info.attachmentCount != 2) {
+    return false;
+  }
+  for (unsigned i = 0; i < info.attachmentCount; ++i) {
+    if (info.pAttachments[i].flags) {
+      return false;
+    }
+  }
+  return true;
+}
+
+}  // namespace mocktail::vr

include/mocktail/vr/foveation_tile_bounds.h

@@ -0,0 +1,85 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <string_view>
+
+namespace mocktail::vr {
+
+struct FoveationTileDriverIdentity {
+  std::uint32_t vendor_id = 0;
+  std::uint32_t device_id = 0;
+  std::uint32_t driver_id = 0;
+  std::uint32_t driver_version = 0;
+  std::string_view driver_name;
+  std::string_view driver_info;
+  std::array<std::uint8_t, 16> driver_uuid{};
+};
+
+// Values describe the complete render pass, including its density attachment.
+// Attachment formats use VkFormat's numeric values without requiring Vulkan.
+struct FoveationTilePassIdentity {
+  std::uint32_t width = 0;
+  std::uint32_t height = 0;
+  std::uint32_t color_format = 0;
+  std::uint32_t depth_format = 0;
+  std::uint32_t color_samples = 0;
+  std::uint32_t depth_samples = 0;
+  std::uint32_t framebuffer_layers = 0;
+  std::uint32_t subpass_count = 0;
+  std::uint32_t total_attachment_count = 0;
+  std::uint32_t color_attachment_count = 0;
+  std::uint32_t gmem_attachment_count = 0;
+  std::uint32_t resolve_attachment_mask = 0;
+  std::uint32_t input_attachment_mask = 0;
+  std::uint32_t feedback_attachment_mask = 0;
+  std::uint32_t view_mask = 0;
+  bool has_depth_attachment = false;
+  bool has_density_attachment = false;
+  bool density_offsets_enabled = false;
+  bool multisampled_render_to_single_sampled = false;
+  bool custom_resolve = false;
+  bool has_shading_rate_attachment = false;
+};
+
+struct FoveationTileBound {
+  std::uint32_t width;
+  std::uint32_t height;
+};
+
+// A calibrated entry for one driver and pass tuple, not a hardware maximum.
+// Unknown identities retain the caller's conservative policy. This exact entry
+// passed 588 GPU focus cases; the matching driver ELF forces FDM's AVOID_CCU
+// layout for all calibrated load/store combinations and the autotune path.
+inline std::optional<FoveationTileBound> KnownFoveationTileBound(
+    const FoveationTileDriverIdentity& driver,
+    const FoveationTilePassIdentity& pass) {
+  constexpr std::array<std::uint8_t, 16> kDriverUuid{
+      0x58, 0x6b, 0x9f, 0xa4, 0x51, 0x4c, 0xb8, 0x8b,
+      0x3c, 0x11, 0xa9, 0x68, 0xef, 0x4d, 0x62, 0xe4};
+  if (driver.vendor_id != 0x5143 || driver.device_id != 0x43051401 ||
+      driver.driver_id != 18 || driver.driver_version != 109060195 ||
+      driver.driver_name != "turnip Mesa driver" ||
+      driver.driver_info != "Mesa 26.3.0-devel (git-abc426bb62)" ||
+      driver.driver_uuid != kDriverUuid) {
+    return std::nullopt;
+  }
+  if (pass.width != 2160 || pass.height != 2160 ||
+      pass.color_format != 37 || pass.depth_format != 126 ||
+      pass.color_samples != 1 || pass.depth_samples != 1 ||
+      pass.framebuffer_layers != 1 || pass.subpass_count != 1 ||
+      pass.total_attachment_count != 3 || pass.color_attachment_count != 1 ||
+      pass.gmem_attachment_count != 2 ||
+      pass.resolve_attachment_mask || pass.input_attachment_mask ||
+      pass.feedback_attachment_mask || pass.view_mask ||
+      !pass.has_depth_attachment || !pass.has_density_attachment ||
+      pass.density_offsets_enabled ||
+      pass.multisampled_render_to_single_sampled || pass.custom_resolve ||
+      pass.has_shading_rate_attachment) {
+    return std::nullopt;
+  }
+  return FoveationTileBound{768, 448};
+}
+
+}  // namespace mocktail::vr

include/mocktail/vr/fsr3_device_features.h

@@ -0,0 +1,298 @@
+#pragma once
+
+#include <algorithm>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+#include <vulkan/vulkan.h>
+
+namespace mocktail::vr {
+
+struct Fsr3DeviceFeatureSupport {
+  bool shader_float16 = false;
+  bool shader_int16 = false;
+  bool float16_extension_available = false;
+  bool shader_storage_image_extended_formats = false;
+  bool shader_storage_image_write_without_format = false;
+  // The effective instance/device API version, not merely a header version.
+  std::uint32_t api_version = VK_API_VERSION_1_0;
+};
+
+// A call-scoped, owned device-create feature chain. This object must remain
+// alive until xrCreateVulkanDeviceKHR/vkCreateDevice returns. Queue descriptions
+// and layer names stay borrowed and unmodified, as in the original call.
+// Unsupported or unfamiliar chains return the original create info verbatim.
+class Fsr3DeviceFeatures final {
+  // The runtime normalizer reuses the same typed ownership/whitelist without
+  // relaxing the guest feature-chain validation performed by this class.
+  friend class Fsr3RuntimeTimelineFeatures;
+ public:
+  Fsr3DeviceFeatures(const VkDeviceCreateInfo& original,
+                     const Fsr3DeviceFeatureSupport& support)
+      : original_(original), info_(original) {
+    Build(support);
+  }
+  Fsr3DeviceFeatures(const Fsr3DeviceFeatures&) = delete;
+  Fsr3DeviceFeatures& operator=(const Fsr3DeviceFeatures&) = delete;
+  Fsr3DeviceFeatures(Fsr3DeviceFeatures&&) = delete;
+  Fsr3DeviceFeatures& operator=(Fsr3DeviceFeatures&&) = delete;
+
+  const VkDeviceCreateInfo& create_info() const {
+    return enabled_ ? info_ : original_;
+  }
+  bool fp16_enabled() const { return enabled_; }
+  bool changed() const { return enabled_ && changed_; }
+  const char* reason() const { return reason_; }
+
+ private:
+  struct Record {
+    virtual ~Record() = default;
+    virtual void* address() = 0;
+    virtual void next(void*) = 0;
+  };
+  template<class T> struct TypedRecord final : Record {
+    explicit TypedRecord(const T& source) : value(source) {}
+    void* address() override { return &value; }
+    void next(void* value_next) override { value.pNext = value_next; }
+    T value;
+  };
+  template<class T> T* Clone(const T& value) {
+    auto record = std::make_unique<TypedRecord<T>>(value);
+    auto* result = &record->value;
+    chain_.push_back(std::move(record));
+    return result;
+  }
+  static constexpr std::uint64_t Bit(unsigned value) { return 1ull << value; }
+  static constexpr std::uint64_t Range(unsigned first, unsigned last) {
+    return ((1ull << (last + 1)) - 1) & ~((1ull << first) - 1);
+  }
+
+  bool CloneKnown(const VkBaseInStructure* source, std::uint64_t* families) {
+    std::uint64_t used = 0;
+#define FEATURE(type, tag, mask) \
+    case tag: { \
+      used = (mask); \
+      if (*families & used) return false; \
+      Clone(*reinterpret_cast<const type*>(source)); \
+      break; \
+    }
+    switch (source->sType) {
+      case VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2: {
+        used = Bit(0);
+        if (*families & used) return false;
+        auto* value = Clone(*reinterpret_cast<const VkPhysicalDeviceFeatures2*>(source));
+        base_features_ = &value->features;
+        features2_ = true;
+        break;
+      }
+      FEATURE(VkPhysicalDeviceVulkan11Features,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES, Range(1, 6))
+      case VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES: {
+        used = Range(7, 19);
+        if (*families & used) return false;
+        auto* value = Clone(*reinterpret_cast<const VkPhysicalDeviceVulkan12Features*>(source));
+        float16_ = &value->shaderFloat16;
+        break;
+      }
+      FEATURE(VkPhysicalDeviceVulkan13Features,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES, Range(20, 32))
+      FEATURE(VkPhysicalDevice16BitStorageFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES, Bit(1))
+      FEATURE(VkPhysicalDeviceMultiviewFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES, Bit(2))
+      FEATURE(VkPhysicalDeviceVariablePointersFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES, Bit(3))
+      FEATURE(VkPhysicalDeviceProtectedMemoryFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_FEATURES, Bit(4))
+      FEATURE(VkPhysicalDeviceSamplerYcbcrConversionFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES, Bit(5))
+      FEATURE(VkPhysicalDeviceShaderDrawParametersFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES, Bit(6))
+      FEATURE(VkPhysicalDevice8BitStorageFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES, Bit(7))
+      FEATURE(VkPhysicalDeviceShaderAtomicInt64Features,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES, Bit(8))
+      case VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES: {
+        used = Bit(9);
+        if (*families & used) return false;
+        auto* value = Clone(*reinterpret_cast<const VkPhysicalDeviceShaderFloat16Int8Features*>(source));
+        float16_ = &value->shaderFloat16;
+        break;
+      }
+      FEATURE(VkPhysicalDeviceDescriptorIndexingFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES, Bit(10))
+      FEATURE(VkPhysicalDeviceScalarBlockLayoutFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES, Bit(11))
+      FEATURE(VkPhysicalDeviceImagelessFramebufferFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES, Bit(12))
+      FEATURE(VkPhysicalDeviceUniformBufferStandardLayoutFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES, Bit(13))
+      FEATURE(VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES, Bit(14))
+      FEATURE(VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES, Bit(15))
+      FEATURE(VkPhysicalDeviceHostQueryResetFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES, Bit(16))
+      FEATURE(VkPhysicalDeviceTimelineSemaphoreFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES, Bit(17))
+      FEATURE(VkPhysicalDeviceBufferDeviceAddressFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES, Bit(18))
+      FEATURE(VkPhysicalDeviceVulkanMemoryModelFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES, Bit(19))
+      FEATURE(VkPhysicalDeviceImageRobustnessFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES, Bit(20))
+      FEATURE(VkPhysicalDeviceInlineUniformBlockFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES, Bit(21))
+      FEATURE(VkPhysicalDevicePipelineCreationCacheControlFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES, Bit(22))
+      FEATURE(VkPhysicalDevicePrivateDataFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES, Bit(23))
+      FEATURE(VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES, Bit(24))
+      FEATURE(VkPhysicalDeviceShaderTerminateInvocationFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES, Bit(25))
+      FEATURE(VkPhysicalDeviceSubgroupSizeControlFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES, Bit(26))
+      FEATURE(VkPhysicalDeviceSynchronization2Features,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES, Bit(27))
+      FEATURE(VkPhysicalDeviceTextureCompressionASTCHDRFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES, Bit(28))
+      FEATURE(VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES, Bit(29))
+      FEATURE(VkPhysicalDeviceDynamicRenderingFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES, Bit(30))
+      FEATURE(VkPhysicalDeviceShaderIntegerDotProductFeatures,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES, Bit(31))
+      FEATURE(VkPhysicalDeviceMaintenance4Features,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES, Bit(32))
+      FEATURE(VkPhysicalDeviceFragmentDensityMapFeaturesEXT,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_FEATURES_EXT, Bit(33))
+      FEATURE(VkPhysicalDeviceFragmentDensityMap2FeaturesEXT,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_FEATURES_EXT, Bit(34))
+      FEATURE(VkPhysicalDeviceHostImageCopyFeaturesEXT,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES_EXT, Bit(35))
+      FEATURE(VkPhysicalDeviceFragmentShadingRateFeaturesKHR,
+              VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_FEATURES_KHR, Bit(36))
+      default: return false;
+    }
+#undef FEATURE
+    *families |= used;
+    return true;
+  }
+
+  bool CopyExtensionNames() {
+    if (original_.enabledExtensionCount && !original_.ppEnabledExtensionNames)
+      return false;
+    for (std::uint32_t i = 0; i < original_.enabledExtensionCount; ++i) {
+      const char* name = original_.ppEnabledExtensionNames[i];
+      if (!name) return false;
+      std::size_t length = 0;
+      while (length < VK_MAX_EXTENSION_NAME_SIZE && name[length]) ++length;
+      if (!length || length == VK_MAX_EXTENSION_NAME_SIZE) return false;
+      const std::string value(name, length);
+      if (std::find(extension_names_.begin(), extension_names_.end(), value) == extension_names_.end())
+        extension_names_.push_back(value);
+      else changed_ = true;
+    }
+    return true;
+  }
+
+  void Build(const Fsr3DeviceFeatureSupport& support) {
+    if (!support.shader_float16 || !support.shader_int16) {
+      reason_ = "shaderFloat16 or shaderInt16 unsupported";
+      return;
+    }
+    if (original_.sType != VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO) {
+      reason_ = "invalid device create info";
+      return;
+    }
+    std::uint64_t families = 0;
+    std::vector<const void*> seen;
+    for (auto* next = static_cast<const VkBaseInStructure*>(original_.pNext);
+         next; next = next->pNext) {
+      if (seen.size() == 64 || std::find(seen.begin(), seen.end(), next) != seen.end() ||
+          !CloneKnown(next, &families)) {
+        reason_ = "unknown, cyclic, or duplicate feature chain";
+        return;
+      }
+      if (next->sType == VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES)
+        // The Vulkan11 aggregate structure itself was introduced in1.2.
+        minimum_api_ = std::max(minimum_api_, VK_API_VERSION_1_2);
+      if (next->sType == VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES)
+        minimum_api_ = std::max(minimum_api_, VK_API_VERSION_1_2);
+      if (next->sType == VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES)
+        minimum_api_ = std::max(minimum_api_, VK_API_VERSION_1_3);
+      seen.push_back(next);
+    }
+    if (features2_ && original_.pEnabledFeatures) {
+      reason_ = "duplicate base feature records";
+      return;
+    }
+    if (support.api_version < minimum_api_) {
+      reason_ = "core feature record exceeds effective Vulkan API";
+      return;
+    }
+    if (support.api_version < VK_API_VERSION_1_2 && !support.float16_extension_available) {
+      reason_ = "shaderFloat16 extension unavailable";
+      return;
+    }
+    if (!CopyExtensionNames()) {
+      reason_ = "invalid device extension list";
+      return;
+    }
+    if (support.api_version < VK_API_VERSION_1_2) {
+      const std::string extension = VK_KHR_SHADER_FLOAT16_INT8_EXTENSION_NAME;
+      if (std::find(extension_names_.begin(), extension_names_.end(), extension) == extension_names_.end()) {
+        extension_names_.push_back(extension);
+        changed_ = true;
+      }
+    }
+    if (!float16_) {
+      VkPhysicalDeviceShaderFloat16Int8Features value{};
+      value.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES;
+      float16_ = &Clone(value)->shaderFloat16;
+      changed_ = true;
+    }
+    if (!base_features_) {
+      if (original_.pEnabledFeatures) features_ = *original_.pEnabledFeatures;
+      base_features_ = &features_;
+      info_.pEnabledFeatures = base_features_;
+    }
+    changed_ |= *float16_ != VK_TRUE || base_features_->shaderInt16 != VK_TRUE;
+    *float16_ = VK_TRUE;
+    base_features_->shaderInt16 = VK_TRUE;
+    if (support.shader_storage_image_extended_formats) {
+      changed_ |= base_features_->shaderStorageImageExtendedFormats != VK_TRUE;
+      base_features_->shaderStorageImageExtendedFormats = VK_TRUE;
+    }
+    if (support.shader_storage_image_write_without_format) {
+      changed_ |= base_features_->shaderStorageImageWriteWithoutFormat != VK_TRUE;
+      base_features_->shaderStorageImageWriteWithoutFormat = VK_TRUE;
+    }
+    for (std::size_t i = 0; i < chain_.size(); ++i)
+      chain_[i]->next(i + 1 < chain_.size() ? chain_[i + 1]->address() : nullptr);
+    info_.pNext = chain_.empty() ? nullptr : chain_[0]->address();
+    for (const auto& name : extension_names_) extension_pointers_.push_back(name.c_str());
+    info_.enabledExtensionCount = static_cast<std::uint32_t>(extension_pointers_.size());
+    info_.ppEnabledExtensionNames = extension_pointers_.empty() ? nullptr : extension_pointers_.data();
+    enabled_ = true;
+    reason_ = "enabled";
+  }
+
+  const VkDeviceCreateInfo& original_;
+  VkDeviceCreateInfo info_;
+  std::vector<std::unique_ptr<Record>> chain_;
+  std::vector<std::string> extension_names_;
+  std::vector<const char*> extension_pointers_;
+  VkPhysicalDeviceFeatures features_{};
+  VkPhysicalDeviceFeatures* base_features_ = nullptr;
+  VkBool32* float16_ = nullptr;
+  bool features2_ = false;
+  std::uint32_t minimum_api_ = VK_API_VERSION_1_0;
+  bool enabled_ = false;
+  bool changed_ = false;
+  const char* reason_ = "disabled";
+};
+
+}  // namespace mocktail::vr

include/mocktail/vr/fsr3_gaze_transport.h

@@ -0,0 +1,46 @@
+#pragma once
+#include "mocktail/vr/fsr3_upscaler.h"
+#include <memory>
+
+namespace mocktail::vr {
+
+// A fixed-size temporal focus region with a cheap full-image periphery.
+// The owner retires pending GPU users before reusing descriptors or resetting.
+class Fsr3GazeTransport {
+ public:
+  struct BeginInfo {
+    VkImage encoded_source{};  // TRANSFER_SRC_OPTIMAL; encoded UNORM or sRGB.
+    Fsr3Upscaler::Image depth;  // Full-input size, SHADER_READ_ONLY_OPTIMAL.
+    Fsr3Upscaler::Image motion; // Optional native clip-NDC delta, same layout/size.
+    float gaze_x=.5f, gaze_y=.5f; // Normalized image UV, +Y down.
+    bool reset=false;
+  };
+  struct Dimensions {
+    std::uint32_t input_width{},input_height{},output_width{},output_height{};
+  };
+  Fsr3GazeTransport();
+  ~Fsr3GazeTransport();
+  Fsr3GazeTransport(const Fsr3GazeTransport&)=delete;
+  Fsr3GazeTransport& operator=(const Fsr3GazeTransport&)=delete;
+  bool Prepare(VkDevice,PFN_vkGetDeviceProcAddr,
+      const VkPhysicalDeviceMemoryProperties&,VkFormat encoded_format,
+      std::uint32_t full_input_width,std::uint32_t full_input_height,
+      std::uint32_t full_output_width,std::uint32_t full_output_height,
+      float sharp_radius);
+  bool Begin(VkCommandBuffer,int eye,const BeginInfo&);
+  void Finish(VkCommandBuffer,int eye);
+  Dimensions dimensions()const;
+  float vertical_fov_scale()const;
+  bool reset_history(int eye)const;
+  Fsr3Upscaler::Image color(int eye)const;
+  Fsr3Upscaler::Image depth(int eye)const;
+  Fsr3Upscaler::Image motion(int eye)const;
+  Fsr3Upscaler::Image output(int eye)const;
+  VkImage encoded(int eye)const;
+  VkFormat encoded_format()const;
+  void Reset();
+ private:
+  struct Impl;
+  std::unique_ptr<Impl> impl_;
+};
+}

include/mocktail/vr/fsr3_runtime_device.h

@@ -0,0 +1,135 @@
+#pragma once
+
+#include <atomic>
+#include <cstring>
+#include "mocktail/vr/fsr3_device_features.h"
+
+namespace mocktail::vr {
+
+// SteamVR can append a TimelineSemaphore feature record even when a guest
+// already supplied Vulkan12Features. Fold that single promoted feature into
+// its aggregate immediately before the host vkCreateDevice call. Every known
+// record is cloned so no borrowed pNext pointer is rewritten. Unknown records,
+// conflicting records, and malformed chains pass through verbatim.
+class Fsr3RuntimeTimelineFeatures final {
+ public:
+  explicit Fsr3RuntimeTimelineFeatures(const VkDeviceCreateInfo& original)
+      : owned_(original, Fsr3DeviceFeatureSupport{}) {
+    if (original.sType != VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO) return;
+    const VkPhysicalDeviceVulkan12Features* aggregate = nullptr;
+    const VkPhysicalDeviceTimelineSemaphoreFeatures* timeline = nullptr;
+    std::vector<const VkBaseInStructure*> records;
+    for (auto* record = static_cast<const VkBaseInStructure*>(original.pNext);
+         record; record = record->pNext) {
+      if (records.size() == 64 ||
+          std::find(records.begin(), records.end(), record) != records.end()) return;
+      if (record->sType == VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES) {
+        if (aggregate) return;
+        aggregate = reinterpret_cast<const VkPhysicalDeviceVulkan12Features*>(record);
+      }
+      if (record->sType == VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES) {
+        if (timeline) return;
+        timeline = reinterpret_cast<const VkPhysicalDeviceTimelineSemaphoreFeatures*>(record);
+      }
+      records.push_back(record);
+    }
+    if (!aggregate || !timeline) return;
+    std::uint64_t families = 0;
+    VkPhysicalDeviceVulkan12Features* cloned_aggregate = nullptr;
+    for (auto* record : records) {
+      if (record == reinterpret_cast<const VkBaseInStructure*>(timeline)) continue;
+      if (!owned_.CloneKnown(record, &families)) return;
+      if (record == reinterpret_cast<const VkBaseInStructure*>(aggregate))
+        cloned_aggregate = static_cast<VkPhysicalDeviceVulkan12Features*>(
+            owned_.chain_.back()->address());
+    }
+    if (!cloned_aggregate || (owned_.features2_ && original.pEnabledFeatures)) return;
+    cloned_aggregate->timelineSemaphore =
+        aggregate->timelineSemaphore || timeline->timelineSemaphore ? VK_TRUE : VK_FALSE;
+    for (std::size_t i = 0; i < owned_.chain_.size(); ++i)
+      owned_.chain_[i]->next(i + 1 < owned_.chain_.size()
+          ? owned_.chain_[i + 1]->address() : nullptr);
+    owned_.info_.pNext = owned_.chain_.front()->address();
+    changed_ = true;
+  }
+  Fsr3RuntimeTimelineFeatures(const Fsr3RuntimeTimelineFeatures&) = delete;
+  Fsr3RuntimeTimelineFeatures& operator=(const Fsr3RuntimeTimelineFeatures&) = delete;
+  const VkDeviceCreateInfo& create_info() const {
+    return changed_ ? owned_.info_ : owned_.original_;
+  }
+  bool changed() const { return changed_; }
+
+ private:
+  Fsr3DeviceFeatures owned_;
+  bool changed_ = false;
+};
+
+// Only calls made in this thread's scope normalize vkCreateDevice. Retained
+// callbacks and calls on other threads use an atomic snapshot of the raw host
+// dispatch, without normalization. The backend must clear that fallback before
+// unloading its private host Vulkan library.
+class ScopedFsr3VulkanDeviceCreate final {
+ public:
+  ScopedFsr3VulkanDeviceCreate(PFN_vkGetInstanceProcAddr raw, VkInstance instance)
+      : raw_(raw), previous_(current_) {
+    if (raw_)
+      create_ = reinterpret_cast<PFN_vkCreateDevice>(raw_(instance, "vkCreateDevice"));
+    if (create_ && create_ != &CreateDevice) {
+      current_ = this;
+      std::shared_ptr<const RawDispatch> dispatch =
+          std::make_shared<RawDispatch>(RawDispatch{raw_, create_});
+      std::atomic_store_explicit(&fallback_, std::move(dispatch), std::memory_order_release);
+    } else create_ = nullptr;
+  }
+  ~ScopedFsr3VulkanDeviceCreate() {
+    if (current_ == this) current_ = previous_;
+  }
+  ScopedFsr3VulkanDeviceCreate(const ScopedFsr3VulkanDeviceCreate&) = delete;
+  ScopedFsr3VulkanDeviceCreate& operator=(const ScopedFsr3VulkanDeviceCreate&) = delete;
+  PFN_vkGetInstanceProcAddr get_instance_proc_addr() const {
+    return create_ ? &GetInstanceProcAddr : raw_;
+  }
+  bool active() const { return create_ != nullptr; }
+  static void ClearFallback() {
+    std::atomic_store_explicit(&fallback_, std::shared_ptr<const RawDispatch>{},
+                               std::memory_order_release);
+  }
+
+ private:
+  struct RawDispatch {
+    PFN_vkGetInstanceProcAddr gipa = nullptr;
+    PFN_vkCreateDevice create = nullptr;
+  };
+  static VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL GetInstanceProcAddr(
+      VkInstance instance, const char* name) {
+    auto* scope = current_;
+    if (!scope || !scope->raw_) {
+      const auto dispatch = std::atomic_load_explicit(&fallback_, std::memory_order_acquire);
+      return dispatch && dispatch->gipa ? dispatch->gipa(instance, name) : nullptr;
+    }
+    if (name && std::strcmp(name, "vkCreateDevice") == 0)
+      return reinterpret_cast<PFN_vkVoidFunction>(&CreateDevice);
+    return scope->raw_(instance, name);
+  }
+  static VKAPI_ATTR VkResult VKAPI_CALL CreateDevice(
+      VkPhysicalDevice physical, const VkDeviceCreateInfo* info,
+      const VkAllocationCallbacks* allocator, VkDevice* device) {
+    auto* scope = current_;
+    if (!scope || !scope->create_) {
+      const auto dispatch = std::atomic_load_explicit(&fallback_, std::memory_order_acquire);
+      return dispatch && dispatch->create
+          ? dispatch->create(physical, info, allocator, device)
+          : VK_ERROR_INITIALIZATION_FAILED;
+    }
+    if (!info) return scope->create_(physical, info, allocator, device);
+    Fsr3RuntimeTimelineFeatures normalized(*info);
+    return scope->create_(physical, &normalized.create_info(), allocator, device);
+  }
+  inline static thread_local ScopedFsr3VulkanDeviceCreate* current_ = nullptr;
+  inline static std::shared_ptr<const RawDispatch> fallback_;
+  PFN_vkGetInstanceProcAddr raw_ = nullptr;
+  PFN_vkCreateDevice create_ = nullptr;
+  ScopedFsr3VulkanDeviceCreate* previous_ = nullptr;
+};
+
+}  // namespace mocktail::vr

include/mocktail/vr/fsr3_scene_capture.h

@@ -0,0 +1,58 @@
+#pragma once
+#include <array>
+#include <cstdint>
+#include <unordered_map>
+#include <vulkan/vulkan.h>
+#include "mocktail/vr/fsr3_scene_inputs.h"
+
+namespace mocktail::vr {
+// Owns depth snapshots, recorded before the guest reuses its scene depth.
+// All methods are serialized by the backend and use its single graphics queue.
+class Fsr3SceneCapture {
+ public:
+  struct Eye {
+    VkImage depth{};
+    VkDeviceMemory memory{};
+    VkFormat format{};
+    std::uint32_t width{},height{};
+    std::uint64_t submitted_frame{};
+    bool initialized{};
+  };
+  struct Motion {
+    VkImage image{};VkDeviceMemory memory{};VkFormat format{};
+    std::uint32_t width{},height{};std::uint64_t submitted_frame{};
+    float previous_uv_scale_x=-.5f,previous_uv_scale_y=.5f;
+  };
+  ~Fsr3SceneCapture() { Reset(); }
+  bool NeedsResize(const TemporalSceneInputs&) const;
+  bool Record(VkDevice, PFN_vkGetDeviceProcAddr,
+              const VkPhysicalDeviceMemoryProperties&, VkCommandBuffer,
+              const TemporalSceneInputs&, std::uint64_t frame);
+  bool RecordMotion(VkDevice, PFN_vkGetDeviceProcAddr,
+                    const VkPhysicalDeviceMemoryProperties&, VkCommandBuffer,
+                    const TemporalMotionInputs&, std::uint64_t frame);
+  void Submitted(std::uint32_t,const VkCommandBuffer*);
+  void Discard(VkCommandBuffer);
+  bool HasUnsubmitted() const;
+  const Eye* Get(int eye,std::uint64_t frame,std::uint32_t width,
+                 std::uint32_t height) const;
+  const Motion* GetMotion(int eye,std::uint64_t frame,std::uint32_t width,
+                          std::uint32_t height) const;
+  void Reset();
+ private:
+  template<class T> T Proc(const char* name) const {
+    return reinterpret_cast<T>(proc_(device_,name));
+  }
+  bool Create(Eye&,const TemporalSceneInputs&,
+              const VkPhysicalDeviceMemoryProperties&);
+  bool Allocate(VkImage&,VkDeviceMemory&,VkFormat,std::uint32_t,std::uint32_t,
+                const VkPhysicalDeviceMemoryProperties&);
+  void Destroy(Eye&);
+  VkDevice device_{};
+  PFN_vkGetDeviceProcAddr proc_{};
+  std::array<Eye,2> eyes_{};
+  std::array<Motion,2> motion_{};
+  struct Pending {std::array<std::uint64_t,2> depth{},motion{};bool submitted=false;};
+  std::unordered_map<VkCommandBuffer,Pending> pending_;
+};
+}

include/mocktail/vr/fsr3_scene_inputs.h

@@ -0,0 +1,134 @@
+#pragma once
+
+#include <cstdint>
+#include <vulkan/vulkan.h>
+
+namespace mocktail::vr {
+
+// A scene-pass candidate, not an asynchronous borrow. This is delivered while
+// the guest command buffer is recording, immediately after its render pass.
+// The backend must verify owner/eye/generation, then record any required copies
+// on that command buffer before returning. Image handles may be reused by the
+// very next guest pass. A later queue submission/fence establishes completion.
+struct TemporalSceneInputs {
+  std::uint32_t version = 1;
+  std::uint32_t size = sizeof(TemporalSceneInputs);
+  VkFramebuffer framebuffer = VK_NULL_HANDLE;
+  VkImage color = VK_NULL_HANDLE;
+  VkImage depth = VK_NULL_HANDLE;
+  VkFormat color_format = VK_FORMAT_UNDEFINED;
+  VkFormat depth_format = VK_FORMAT_UNDEFINED;
+  VkImageLayout color_layout = VK_IMAGE_LAYOUT_UNDEFINED;
+  VkImageLayout depth_layout = VK_IMAGE_LAYOUT_UNDEFINED;
+  VkImageSubresourceRange color_range{};
+  VkImageSubresourceRange depth_range{};
+  std::uint32_t width = 0;
+  std::uint32_t height = 0;
+  // Set only when this pass actually clears its depth attachment. This is
+  // evidence for normal (clear=1) versus reversed (clear=0) device depth.
+  float depth_clear = 0.f;
+  bool depth_clear_valid = false;
+  void* owner = nullptr;
+  void* guest_framebuffer = nullptr;
+  int eye = -1;
+  // Zero means the adapter has no frame number. The backend must stamp the
+  // current published frame after matching the exact live eye provenance.
+  std::uint64_t frame = 0;
+};
+
+// Native 3222 motion shader output before conversion: current clip.xyz/w minus
+// previous clip.xyz/w. Its vertex shader negates Y only for gl_Position, so
+// previous-UV minus current-UV is nativeDelta.xy * (-0.5, +0.5). XYZ are signed
+// floats; W is zero, not a validity mask. The shader can discard large deltas.
+struct TemporalMotionInputs {
+  std::uint32_t version = 1;
+  std::uint32_t size = sizeof(TemporalMotionInputs);
+  VkFramebuffer framebuffer = VK_NULL_HANDLE;
+  VkImage image = VK_NULL_HANDLE;
+  VkFormat format = VK_FORMAT_UNDEFINED;
+  VkImageLayout layout = VK_IMAGE_LAYOUT_UNDEFINED;
+  VkImageSubresourceRange range{};
+  std::uint32_t width = 0, height = 0;
+  void* owner = nullptr;
+  void* guest_framebuffer = nullptr;
+  int eye = -1;
+  std::uint64_t frame = 0;
+  float previous_uv_scale_x = -.5f;
+  float previous_uv_scale_y = .5f;
+};
+
+inline bool IsTemporalMotionFormat(VkFormat format) {
+  return format == VK_FORMAT_R16G16_SFLOAT ||
+         format == VK_FORMAT_R16G16B16A16_SFLOAT ||
+         format == VK_FORMAT_R32G32_SFLOAT ||
+         format == VK_FORMAT_R32G32B32A32_SFLOAT;
+}
+
+inline bool IsTemporalClipMotionShaders(std::uint64_t vertex,
+                                        std::uint64_t fragment) {
+  // FNV-1a of exact native shader module bytes, verified against both the
+  // fragment subtraction and vertex current/previous clip outputs. The three
+  // adjacent world-space variants deliberately have a different contract.
+  return fragment == 0x821fff499ec5bdbbull &&
+      (vertex == 0x9b0d6a7041cad338ull ||
+       vertex == 0x4a99a561ef9805b6ull ||
+       vertex == 0x6dcaa6712cd5a2cdull);
+}
+
+inline bool IsTemporalDepthFormat(VkFormat format) {
+  return format == VK_FORMAT_D16_UNORM ||
+         format == VK_FORMAT_X8_D24_UNORM_PACK32 ||
+         format == VK_FORMAT_D32_SFLOAT ||
+         format == VK_FORMAT_D16_UNORM_S8_UINT ||
+         format == VK_FORMAT_D24_UNORM_S8_UINT ||
+         format == VK_FORMAT_D32_SFLOAT_S8_UINT;
+}
+
+inline bool IsTemporalColorFormat(VkFormat format) {
+  return format == VK_FORMAT_R8G8B8A8_UNORM ||
+         format == VK_FORMAT_R8G8B8A8_SRGB ||
+         format == VK_FORMAT_B8G8R8A8_UNORM ||
+         format == VK_FORMAT_B8G8R8A8_SRGB ||
+         format == VK_FORMAT_R16G16B16A16_SFLOAT ||
+         format == VK_FORMAT_B10G11R11_UFLOAT_PACK32 ||
+         format == VK_FORMAT_A2B10G10R10_UNORM_PACK32;
+}
+
+inline bool IsTemporalImageCandidate(const VkImageCreateInfo& info) {
+  const bool depth = IsTemporalDepthFormat(info.format) &&
+      (info.usage & VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT);
+  const bool color = IsTemporalColorFormat(info.format) &&
+      (info.usage & VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT);
+  const bool motion = IsTemporalMotionFormat(info.format) &&
+      (info.usage & VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT);
+  // Native transient targets may request lazy memory; changing their usage would
+  // disagree with the engine allocator's original memory-type request.
+  return (depth || color || motion) &&
+      !(info.usage & VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT) &&
+      info.imageType == VK_IMAGE_TYPE_2D &&
+      info.tiling == VK_IMAGE_TILING_OPTIMAL &&
+      info.samples == VK_SAMPLE_COUNT_1_BIT && info.extent.depth == 1 &&
+      info.extent.width >= 256 && info.extent.height >= 256 &&
+      info.arrayLayers == 1 && info.mipLevels == 1 && info.flags == 0;
+}
+
+// Depth/stencil formats use depth only. FSR samples device depth; stencil must
+// never be reinterpreted as scene depth or included in a depth-only copy.
+inline VkImageAspectFlags TemporalDepthAspect(VkFormat format) {
+  return IsTemporalDepthFormat(format) ? VK_IMAGE_ASPECT_DEPTH_BIT : 0;
+}
+
+}  // namespace mocktail::vr
+
+extern "C" {
+// Availability tracks compatible resources from Vulkan startup. Enabled only
+// selects preserving passes and per-frame capture while temporal FSR is active.
+bool mocktail_vr_xr_fsr3_inputs_available();
+bool mocktail_vr_xr_fsr3_inputs_enabled();
+void mocktail_vr_xr_fsr3_scene_end(
+    VkDevice device, VkCommandBuffer command,
+    const mocktail::vr::TemporalSceneInputs* inputs);
+void mocktail_vr_xr_fsr3_motion_end(
+    VkDevice device, VkCommandBuffer command,
+    const mocktail::vr::TemporalMotionInputs* inputs);
+}

include/mocktail/vr/fsr3_transport.h

@@ -0,0 +1,37 @@
+#pragma once
+#include <array>
+#include <vulkan/vulkan.h>
+#include "mocktail/vr/fsr3_upscaler.h"
+
+namespace mocktail::vr {
+// Explicit encoded-native -> linear-FSR -> encoded-native transport.
+// The caller drains uses before resizing/resetting these reusable eye images.
+class Fsr3Transport {
+ public:
+  ~Fsr3Transport() { Reset(); }
+  bool Prepare(VkDevice,PFN_vkGetDeviceProcAddr,
+               const VkPhysicalDeviceMemoryProperties&,VkFormat source,
+               std::uint32_t width,std::uint32_t height,
+               std::uint32_t output_width,std::uint32_t output_height);
+  void Begin(VkCommandBuffer,int eye,VkImage encoded_source);
+  void Finish(VkCommandBuffer,int eye);
+  Fsr3Upscaler::Image color(int eye) const;
+  Fsr3Upscaler::Image output(int eye) const;
+  VkImage encoded(int eye) const {return eyes_[eye].encoded.image;}
+  VkFormat encoded_format() const {return srgb_format_;}
+  void Reset();
+ private:
+  struct Resource {VkImage image{};VkDeviceMemory memory{};};
+  struct Eye {Resource color,output,encoded;};
+  template<class T>T Proc(const char* name)const{return reinterpret_cast<T>(proc_(device_,name));}
+  bool Create(Resource&,VkFormat,std::uint32_t,std::uint32_t,VkImageUsageFlags,
+              const VkPhysicalDeviceMemoryProperties&);
+  void Destroy(Resource&);
+  void Barrier(VkCommandBuffer,VkImage,VkImageLayout,VkImageLayout,VkAccessFlags,VkAccessFlags);
+  VkDevice device_{};
+  PFN_vkGetDeviceProcAddr proc_{};
+  VkFormat source_format_{},srgb_format_{};
+  std::uint32_t width_{},height_{},output_width_{},output_height_{};
+  std::array<Eye,2> eyes_{};
+};
+}

include/mocktail/vr/fsr3_upscaler.h

@@ -0,0 +1,64 @@
+#pragma once
+
+#include <vulkan/vulkan.h>
+#include <cstdint>
+#include <memory>
+
+namespace mocktail::vr {
+
+// AMD FSR 3.1.4 temporal upscaling. Each eye owns independent temporal history.
+// GPU completion is the owner's responsibility before Reset or destruction.
+class Fsr3Upscaler {
+ public:
+  struct Configuration {
+    std::uint32_t render_width{}, render_height{};
+    std::uint32_t output_width{}, output_height{};
+    bool inverted_depth=false, infinite_depth=false, hdr=false;
+    // Estimate image motion with AMD Optical Flow when engine vectors are
+    // unavailable. This is a fallback with its own compute cost and limits.
+    bool estimate_motion=false;
+    bool motion_vectors_jittered=false;
+    // Enable only when shaderFloat16 was enabled on the logical VkDevice.
+    bool allow_fp16=false;
+  };
+  struct Image {
+    VkImage image{};
+    VkFormat format{};
+    std::uint32_t width{}, height{};
+  };
+  struct JitterOffset { float x{}, y{}; };
+  struct Frame {
+    // Inputs must be sampled images in SHADER_READ_ONLY_OPTIMAL, output a
+    // storage image in GENERAL. The SDK restores those layouts after dispatch.
+    // Color is LINEAR: an sRGB image format decodes encoded source bytes.
+    // The output should be RGBA16F linear; encode it before copying to an
+    // encoded UNORM eye image. Depth and color must describe the same view.
+    Image color, depth, motion_vectors, output;
+    Image reactive, transparency;
+    // Unjittered motion is previous pixel position minus current position.
+    // Pixel-unit vectors use {1,1}; normalized UV vectors use render size.
+    float motion_vector_scale[2]{1.f,1.f};
+    JitterOffset jitter;
+    float delta_ms=16.667f, near_plane=.1f, far_plane=1000.f;
+    float vertical_fov=1.5707963f, meters_per_world_unit=1.f;
+    float pre_exposure=1.f, sharpness=.2f;
+    bool sharpening=true, reset=false;
+  };
+
+  Fsr3Upscaler();
+  ~Fsr3Upscaler();
+  Fsr3Upscaler(const Fsr3Upscaler&)=delete;
+  Fsr3Upscaler& operator=(const Fsr3Upscaler&)=delete;
+  bool Configure(VkPhysicalDevice, VkDevice, PFN_vkGetDeviceProcAddr,
+                 const VkPhysicalDeviceMemoryProperties&, const Configuration&);
+  bool Record(VkCommandBuffer, int eye, const Frame&);
+  Image estimated_motion(int eye) const;
+  void Reset();
+  int last_error() const;
+  static JitterOffset Jitter(std::uint64_t frame, std::uint32_t render_width,
+                             std::uint32_t output_width);
+ private:
+  struct Impl;
+  std::unique_ptr<Impl> impl_;
+};
+}

include/mocktail/vr/fsr_settings.h

@@ -0,0 +1,45 @@
+#pragma once
+#include <algorithm>
+#include <cstdint>
+
+namespace mocktail::vr {
+struct FsrSettings {
+  int quality=0;  // Custom scale, Ultra Quality, Quality, Balanced, Performance, Custom resolution.
+  int scale_percent=80;
+  std::uint32_t input_resolution=1728;
+  bool operator==(const FsrSettings& other) const {
+    return quality==other.quality && scale_percent==other.scale_percent &&
+           input_resolution==other.input_resolution;
+  }
+  bool operator!=(const FsrSettings& other) const { return !(*this==other); }
+};
+
+inline std::uint32_t FsrRenderSize(std::uint32_t output, int mode,
+                                  const FsrSettings& settings={}) {
+  if((mode!=1 && mode!=2 && mode!=3) || output<2)return output;
+  if(settings.quality==5)
+    return std::clamp(settings.input_resolution,2u,output)&~1u;
+  std::uint64_t numerator=std::clamp(settings.scale_percent,25,100),denominator=100;
+  switch(settings.quality) {
+    case 1:numerator=10;denominator=13;break;
+    case 2:numerator=2;denominator=3;break;
+    case 3:numerator=10;denominator=17;break;
+    case 4:numerator=1;denominator=2;break;
+    default:break;
+  }
+  const auto scaled=static_cast<std::uint32_t>(
+      2*((std::uint64_t(output)*numerator+denominator)/(2*denominator)));
+  return std::clamp(scaled,2u,output&~1u);
+}
+inline std::uint32_t FsrRenderHeight(std::uint32_t output_width,
+                                    std::uint32_t output_height,int mode,
+                                    const FsrSettings& settings={}) {
+  if(settings.quality!=5 || mode==0 || !output_width || output_height<2)
+    return FsrRenderSize(output_height,mode,settings);
+  const auto width=FsrRenderSize(output_width,mode,settings);
+  const auto height=static_cast<std::uint32_t>(
+      2*((std::uint64_t(output_height)*width+output_width)/(2*std::uint64_t(output_width))));
+  return std::clamp(height,2u,output_height&~1u);
+}
+
+}

include/mocktail/vr/fsr_upscaler.h

@@ -0,0 +1,84 @@
+#pragma once
+#include <vulkan/vulkan.h>
+#include "mocktail/vr/fsr_settings.h"
+#include "mocktail/vr/temporal_reprojection.h"
+#include <cstdint>
+#include <cstddef>
+#include <unordered_map>
+
+namespace mocktail::vr {
+// FP32 FSR 1 EASU, followed by gaze-only RCAS after the normal gaze AA.
+// Uses raw host dispatch and the backend's existing copy command/fence.
+class FsrUpscaler {
+ public:
+  ~FsrUpscaler() { Reset(); }
+  bool Prepare(VkDevice, PFN_vkGetDeviceProcAddr,
+               const VkPhysicalDeviceMemoryProperties&, int eye,
+               VkImage source, VkFormat source_format, VkImage destination,
+               VkFormat output_format, std::uint32_t input_width,
+               std::uint32_t input_height, std::uint32_t output_width,
+               std::uint32_t output_height, bool temporal=false);
+  void RecordUpscale(VkCommandBuffer, int eye, float gaze_x=0, float gaze_y=0,
+                     float radius=.15f);
+  void RecordTemporal(VkCommandBuffer,int eye,const TemporalEyePose&,
+                      float gaze_x,float gaze_y,float radius,std::uint64_t now);
+  void RecordSharpen(VkCommandBuffer, int eye, float gaze_x, float gaze_y,
+                     float radius);
+  VkImage image(int eye) const { return eyes_[eye].image; }
+  VkFormat intermediate_format() const;
+  void ForgetImage(VkImage);
+  void Reset();
+ private:
+  template<class T> T Proc(const char* name) const {
+    return reinterpret_cast<T>(proc_(device_, name));
+  }
+  bool Initialize(VkDevice, PFN_vkGetDeviceProcAddr, VkFormat);
+  VkPipeline Pipeline(VkRenderPass, const std::uint32_t*, std::size_t);
+  struct Eye {
+    VkImage image{}, source{}, destination{}, gamma_image{};
+    VkDeviceMemory memory{}, gamma_memory{};
+    VkImageView view{}, source_view{};
+    VkFramebuffer framebuffer{};
+    VkDescriptorSet sets[3]{};
+    VkImage history_image{};VkDeviceMemory history_memory{};VkImageView history_view{};
+    bool history_initialized=false,history_failed=false;
+    TemporalEyePose previous_pose;
+    float previous_center[2]{},previous_radius=0;
+    std::uint64_t previous_time=0;
+    VkFormat source_format{};
+    std::uint32_t in_width=0, in_height=0, width=0, height=0;
+  };
+  struct Target { VkImageView view{}; VkFramebuffer framebuffer{}; };
+  void FreeEye(Eye&);
+  bool PrepareHistory(const VkPhysicalDeviceMemoryProperties&,int eye);
+  struct alignas(16) Constants {
+    std::uint32_t con[4][4]{};
+    float texel[2]{}, center[2]{};
+    float radius=0;
+    std::uint32_t input_srgb=0, output_srgb=0, reserved=0;
+  };
+  static_assert(sizeof(Constants)==96);
+  struct alignas(16) TemporalConstants {
+    float rows[3][4]{},texel[2]{},center[2]{},previous_center[2]{};
+    float radius=0,previous_radius=0,blend=0;
+    std::uint32_t output_srgb=0,reserved[2]{};
+  };
+  static_assert(sizeof(TemporalConstants)==96);
+  void Draw(VkCommandBuffer, VkRenderPass, VkFramebuffer, VkPipeline,
+            VkDescriptorSet, const void*, const Eye&, VkRect2D);
+  void Barrier(VkCommandBuffer, VkImage, VkImageLayout, VkImageLayout,
+               VkAccessFlags, VkAccessFlags, VkPipelineStageFlags,
+               VkPipelineStageFlags);
+  VkDevice device_{};
+  PFN_vkGetDeviceProcAddr proc_{};
+  VkFormat format_{};
+  VkRenderPass passes_[2]{};
+  VkPipeline pipelines_[3]{};
+  VkDescriptorSetLayout descriptor_layout_{};
+  VkDescriptorPool descriptor_pool_{};
+  VkPipelineLayout layout_{};
+  VkSampler sampler_{};
+  Eye eyes_[2];
+  std::unordered_map<VkImage,Target> targets_;
+};
+}

include/mocktail/vr/gaze_aa.h

@@ -0,0 +1,70 @@
+#pragma once
+#include <vulkan/vulkan.h>
+#include <cstdint>
+#include <cstddef>
+#include <unordered_map>
+
+namespace mocktail::vr {
+
+// Gaze-limited edge filtering after the normal eye copy.
+// Every call uses raw host dispatch. The owner waits its copy fence before
+// changing descriptors, dropping views, or destroying resources.
+class GazeAa {
+ public:
+  ~GazeAa() { Reset(); }
+  bool Prepare(VkDevice, PFN_vkGetDeviceProcAddr, int eye, VkImage source,
+               VkFormat source_format, VkImage destination,
+               VkFormat destination_format, std::uint32_t width,
+               std::uint32_t height, int mode=1,
+               const VkPhysicalDeviceMemoryProperties* memory=nullptr);
+  bool Record(VkCommandBuffer, int eye, float gaze_x, float gaze_y, int mode=1,
+              float radius=.22f);
+  void ForgetImage(VkImage);
+  void Reset();
+
+ private:
+  template<class T> T Proc(const char* name) const {
+    return reinterpret_cast<T>(get_proc_(device_,name));
+  }
+  bool Initialize(VkDevice,PFN_vkGetDeviceProcAddr,VkFormat);
+  VkPipeline MakePipeline(VkRenderPass,const std::uint32_t*,std::size_t);
+  bool PrepareSmaa(int,const VkPhysicalDeviceMemoryProperties&,int mode);
+  void RecordSmaa(VkCommandBuffer,int,int,const void*,const VkRect2D&);
+  void RecordPass(VkCommandBuffer,int,VkPipeline,VkRenderPass,VkFramebuffer,
+                  VkDescriptorSet,const void*,const VkRect2D&,bool);
+  void DestroySmaa();
+  struct Texture { VkImage image{}; VkDeviceMemory memory{}; VkImageView view{}; };
+  bool MakeTexture(Texture&,VkFormat,unsigned,unsigned,VkImageUsageFlags);
+  void FreeTexture(Texture&);
+  struct SmaaEye {
+    Texture textures[2];
+    VkFramebuffer framebuffers[2]{};
+    VkDescriptorSet descriptors[2]{};
+    std::uint32_t width=0,height=0;
+    VkImageView descriptor_source{};
+  };
+  struct Source { VkImage image{}; VkImageView view{}; VkFormat format{}; bool descriptor_ready=false; };
+  struct Target { VkImageView view{}; VkFramebuffer framebuffer{}; };
+  VkDevice device_{};
+  PFN_vkGetDeviceProcAddr get_proc_{};
+  VkFormat format_=VK_FORMAT_UNDEFINED;
+  VkDescriptorSetLayout descriptor_layout_{};
+  VkDescriptorPool descriptor_pool_{};
+  VkDescriptorSet descriptor_sets_[2]{};
+  VkPipelineLayout pipeline_layout_{};
+  VkPipeline pipeline_{};
+  VkRenderPass render_pass_{};
+  VkSampler sampler_{};
+  VkRenderPass smaa_pass_{};
+  VkPipeline smaa_pipelines_[2][3]{};
+  SmaaEye smaa_eyes_[2];
+  Texture smaa_luts_[2];
+  VkBuffer smaa_staging_{};
+  VkDeviceMemory smaa_staging_memory_{};
+  bool smaa_uploaded_=false;
+  Source sources_[2];
+  std::unordered_map<VkImage,Target> targets_;
+  VkImage destinations_[2]{};
+  std::uint32_t widths_[2]{},heights_[2]{};
+};
+}

include/mocktail/vr/headset_detection.h

@@ -0,0 +1,35 @@
+#ifndef MOCKTAIL_VR_HEADSET_DETECTION_H_
+#define MOCKTAIL_VR_HEADSET_DETECTION_H_
+
+#include <chrono>
+#include <string>
+
+namespace mocktail::vr {
+
+// Set on the child process that answers DetectSteamVrHeadset. main() checks
+// it first and returns RunHeadsetProbeChild() without starting Roblox.
+inline constexpr const char* kHeadsetProbeEnvironment =
+    "MOCKTAIL_VR_HEADSET_PROBE";
+
+struct HeadsetDetection {
+  bool headset = false;
+  std::string reason;
+};
+
+// vr.mode: auto. True only when this user's SteamVR is running and its OpenXR
+// runtime reports a head-mounted display. SteamVR is never started. The
+// runtime is asked from a child process (`self_executable` with
+// kHeadsetProbeEnvironment set) so its libraries never load into this one
+// before the VR backend arms.
+HeadsetDetection DetectSteamVrHeadset(
+    const std::string& self_executable,
+    std::chrono::milliseconds timeout = std::chrono::seconds(5),
+    const std::string& proc_root = "/proc");
+
+// The child side: probes the OpenXR runtime in XR_RUNTIME_JSON and returns
+// the probe's exit code (0 when a headset is available).
+int RunHeadsetProbeChild();
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_HEADSET_DETECTION_H_

include/mocktail/vr/native_projection.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <cstdint>
+
+namespace mocktail::vr {
+
+struct NativeProjectionSample {
+  // The actual engine camera projection before temporal jitter, row-major.
+  // This is read from the native camera rather than rebuilt from tracking FOV.
+  float projection[16] = {};
+  // The full world-view-projection used by the engine, including player
+  // locomotion. Supplied by the separately verified native combined getter.
+  float view_projection[16] = {};
+  float jitter_pixels[2] = {};
+  std::uint32_t render_width = 0;
+  std::uint32_t render_height = 0;
+  float camera_near = 0.f;
+  float camera_far = 0.f;
+  std::uintptr_t camera_identity = 0;
+  std::uint64_t frame = 0;
+  bool depth_inverted = false;
+  bool depth_infinite = false;
+  bool jitter_applied = false;
+  bool view_projection_valid = false;
+  bool valid = false;
+};
+
+// True only when the exact native per-eye projection function was verified and
+// hooked. Unsupported clients retain their original projections.
+bool NativeProjectionBridgeReady();
+// Copies only a projection from the requested frame. A stale or unsupported
+// camera never supplies temporal reconstruction parameters.
+bool ReadNativeProjectionSample(int eye, std::uint64_t expected_frame,
+                                NativeProjectionSample* sample);
+
+}  // namespace mocktail::vr

include/mocktail/vr/openxr_backend.h

@@ -0,0 +1,720 @@
+#ifndef MOCKTAIL_VR_OPENXR_BACKEND_H_
+#define MOCKTAIL_VR_OPENXR_BACKEND_H_
+
+#include <vulkan/vulkan.h>
+
+#include <array>
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <vector>
+
+#include <memory>
+
+#include "mocktail/status.h"
+#include "mocktail/vr/xr_foveation_maps.h"
+#include "mocktail/vr/gaze_aa.h"
+#include "mocktail/vr/fsr_upscaler.h"
+#include "mocktail/vr/fsr3_scene_capture.h"
+#ifdef MOCKTAIL_ENABLE_FSR3
+#include "mocktail/vr/fsr3_upscaler.h"
+#include "mocktail/vr/fsr3_gaze_transport.h"
+#endif
+#include "mocktail/vr/virtual_keyboard.h"
+#include "mocktail/vr/vr_mirror.h"
+#include "mocktail/vr/xr_actions.h"
+#include "mocktail/vr/xr_controller.h"
+
+namespace mocktail::vr {
+
+namespace internal {
+// Deferral is safe only when the guest requested exactly one unprotected queue.
+bool SingleUnprotectedVulkanQueue(const VkDeviceCreateInfo* info);
+// Frame's native Video slider stores a per-eye pixel dimension per app.
+std::uint32_t SteamFrameEyeResolution(std::string_view settings,
+                                     std::string_view steam_app_id);
+
+// Swapchain format for guest eyes of `eye` given the runtime's formats:
+// `eye` itself, else its UNORM/SRGB sibling (a raw byte copy, since the guest
+// writes sRGB-encoded bytes either way), else the other channel order with
+// the same sRGB-ness (a blit that only swizzles). VK_FORMAT_UNDEFINED when
+// only a gamma-converting blit remains.
+VkFormat PreferredEyeSwapchainFormat(VkFormat eye,
+                                     const std::vector<std::int64_t>& available);
+// Consume binary present dependencies exactly once. On success a later present
+// must omit them. VK_NOT_READY means nothing was consumed and the guest's
+// present proceeds unchanged; any other failure consumed them (or lost the
+// device) and must be propagated, not retried.
+VkResult WaitForPresentDependencies(VkDevice device, VkQueue queue,
+                                    const VkPresentInfoKHR& present,
+                                    VkFence fence, PFN_vkResetFences reset,
+                                    PFN_vkQueueSubmit submit,
+                                    PFN_vkWaitForFences wait);
+// Hands binary present dependencies to the GPU instead: one empty batch on
+// `queue` waits on them and signals `signal`, which the present waits on
+// instead. Work submitted to `queue` afterwards is ordered after the waits.
+// The CPU never blocks. VK_NOT_READY means nothing was consumed.
+VkResult ChainPresentDependencies(VkDevice device, VkQueue queue,
+                                  const VkPresentInfoKHR& present,
+                                  VkSemaphore signal, PFN_vkQueueSubmit submit);
+// Makes the Vulkan adapter serialize queue calls for the rest of the process.
+// Called when a backend arms; the adapter library may load before or after.
+void RequestVulkanQueueSharing();
+}  // namespace internal
+
+// Resolved --vr output mode. kXrOutput drives the real Roblox stereo images
+// into an OpenXR projection layer; kNativeOnly keeps the diagnostic native
+// stereo prototype without any runtime requirement. Selected through
+// MOCKTAIL_VR_BACKEND ("xr" default, "native" diagnostic).
+enum class VrBackendMode {
+  kDisabled,
+  kNativeOnly,
+  kXrOutput,
+};
+
+// Explicit XR_RUNTIME_JSON wins. Runtime preference can select SteamVR (ALVR),
+// WiVRn, or the registered OpenXR runtime without changing system registration.
+std::string SelectVrRuntimeManifest(const std::string& explicit_manifest,
+                                   const std::vector<std::string>& candidates);
+std::vector<std::string> VrRuntimeManifestCandidates(
+    const std::string &preference, const std::string &home,
+    const std::string &config_home, const std::string &config_dirs);
+struct VrRuntimeDiscovery {
+  std::vector<std::string> candidates;
+  std::string reason;
+};
+VrRuntimeDiscovery DiscoverVrRuntime(
+    const std::string& preference, const std::string& home,
+    const std::string& config_home, const std::string& config_dirs,
+    const std::string& runtime_dir, const std::string& proc_root = "/proc");
+std::string VrRuntimeUnavailableHint(bool user_selected, const std::string& manifest);
+// SteamVR's OpenXR manifest when this user's vrserver is running, else empty.
+std::string RunningSteamVrManifest(const std::string& proc_root = "/proc");
+VrBackendMode ResolveVrBackendMode(bool vr_enabled);
+const char* VrBackendModeName(VrBackendMode mode);
+
+// One deterministic head pose sample. Position is metres, orientation is a
+// quaternion (x, y, z, w) in the OpenXR LOCAL reference space.
+// VrHandPose (tracked controller hands) is defined in xr_controller.h.
+struct ScriptedPoseSample {
+  float position[3] = {0.f, 0.f, 0.f};
+  float orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  float eye_offset[2][3] = {};  // metres in head space
+  float eye_fov[2][4] = {};  // left, right, up, down angles
+  float projection_jitter_pixels[2] = {};  // raster displacement: right/down
+  std::uint32_t projection_render_width = 0, projection_render_height = 0;
+  bool projection_jitter_valid = false;
+  // Index 0 = left, 1 = right (Roblox UserCFrame LeftHand/RightHand).
+  VrHandPose hands[2];
+  float floor_position[3] = {};
+  float floor_orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  bool floor_valid = false;
+  // Verified DebugDeviceVR input channels, published with the same pose.
+  float controller_channels[28] = {};
+  bool controllers_connected = false;
+  std::uint64_t frame = 0;
+  bool valid = false;
+};
+
+// Production OpenXR backend for the native stereo prototype.
+//
+// Lifecycle: main arms the backend before Roblox startup (xrCreateInstance
+// and xrGetSystem fail fast with a clear message when no runtime exists).
+// The Vulkan adapter delegates the guest's vkCreateInstance/vkCreateDevice
+// through xrCreateVulkanInstanceKHR/xrCreateVulkanDeviceKHR so the runtime's
+// extension and GPU requirements are satisfied by the very device Roblox
+// renders with. The session is created on that device; per-frame XR work runs
+// on the render thread from the adapter's host-present notification:
+//   xrEndFrame(N) with the two eye images of frame N copied into the
+//   projection swapchains, then xrWaitFrame/xrBeginFrame/xrLocateViews for
+//   frame N+1 and publishing the scripted/runtime head pose that the device
+//   bridge injects into Roblox before its eye passes run.
+//
+// EGL/OpenGL ES uses XR_MNDX_egl_enable on the guest SDL context and GPU
+// framebuffer blits into GLES swapchain textures. It shares the same frame
+// scheduling, tracking, pose application and session recovery below.
+//
+// Eye image provenance is recorded in the adapter during the guest eye
+// initializer (owner = DebugDeviceVR object) and bound to an eye index only
+// through the real per-frame eye-getter request plus the actual render-pass
+// attachment, mirroring the validated evidence-layer semantics. Creation
+// order or size alone never selects an eye.
+//
+// All public entry points are exception-free at their boundary; the
+// implementation is compiled with exceptions like openxr_preview.cc and
+// translates failures into Status/log outcomes.
+class GlesTransport;
+enum class VrGraphicsApi { kVulkan, kOpenGles };
+
+class OpenXrBackend final {
+ public:
+  OpenXrBackend() = default;
+  ~OpenXrBackend();
+  OpenXrBackend(const OpenXrBackend&) = delete;
+  OpenXrBackend& operator=(const OpenXrBackend&) = delete;
+
+  // Claims the process-wide backend slot and creates XrInstance/system.
+  Status Arm(VrGraphicsApi graphics_api = VrGraphicsApi::kVulkan);
+  // EGL context must be current on the calling thread. Resolver bypasses guest
+  // hooks.
+  Status AttachGlesContext(void *display, void *config, void *context,
+                           void *egl_get_proc, void *(*resolve)(const char *));
+  void DetachGlesContext(void *context);
+  void NoteGlesPresent();
+  void *WrapGlesProcAddress(const char *name, void *raw);
+  // Idempotent full teardown (XR resources first, then the instance).
+  void Disarm();
+  bool armed() const { return armed_.load(std::memory_order_acquire); }
+
+  // Adapter delegation. Return false when the backend does not own creation
+  // (caller falls back to the plain host loader path).
+  bool CreateVulkanInstance(const VkInstanceCreateInfo* create_info,
+                            const VkAllocationCallbacks* allocator,
+                            VkInstance* instance, VkResult* result);
+  bool CreateVulkanDevice(VkPhysicalDevice physical_device,
+                          const VkDeviceCreateInfo* create_info,
+                          const VkAllocationCallbacks* allocator,
+                          VkDevice* device, VkResult* result);
+  // True transfers native device destruction to this backend.
+  bool NoteDeviceDestroyed(VkDevice device);
+  bool FoveationEnabled(VkDevice device) const;
+  VkImageView FoveationViewForFramebuffer(VkDevice device, VkFramebuffer framebuffer);
+  bool FoveationFocus(VkDevice device,VkFramebuffer framebuffer,float* x,float* y,std::uint64_t* frame,int* eye,int* level);
+  bool FoveationSnapshot(VkDevice device,float* centers,float* radius,std::uint64_t* frame,int* level);
+  // A scene intermediate may be shared between eyes. Resolve it from the live
+  // eye getter, never from its framebuffer handle or dimensions alone.
+  bool FoveationRenderFocus(VkDevice device, VkFramebuffer framebuffer,
+      std::uint32_t scene_width, std::uint32_t scene_height, float* x, float* y,
+      float* radius, std::uint64_t* frame, int* eye, int* level);
+  bool FoveationHostCopyEnabled(VkDevice device) const;
+  bool Fsr3InputsAvailable() const;
+  bool Fsr3InputsEnabled() const;
+  void CaptureFsr3Scene(VkDevice, VkCommandBuffer, const TemporalSceneInputs&);
+  void CaptureFsr3Motion(VkDevice, VkCommandBuffer, const TemporalMotionInputs&);
+  VkExtent2D FoveationMapExtent(VkDevice device) const;
+  // True transfers native instance destruction to this backend.
+  bool NoteInstanceDestroyed(VkInstance instance);
+  void NoteQueue(VkDevice device, VkQueue queue, std::uint32_t family,
+                 std::uint32_t index);
+  std::vector<std::uint32_t> DesktopQueueFamilies(VkDevice device) const;
+  void RecordCommandPool(VkDevice device, VkCommandPool pool,
+                         std::uint32_t family);
+  void RecordCommandBuffers(VkDevice device, VkCommandPool pool,
+                            std::uint32_t count,
+                            const VkCommandBuffer* buffers);
+  void ForgetCommandBuffers(std::uint32_t count,
+                            const VkCommandBuffer* buffers);
+  void ForgetCommandPool(VkCommandPool pool);
+  void ResetCommandPool(VkCommandPool pool);
+  void ResetCommandBuffer(VkCommandBuffer buffer);
+  void NoteCommandBuffersSubmitted(VkQueue queue, std::uint32_t count,
+                                   const VkCommandBuffer* buffers);
+  VkImageLayout NormalizeDesktopBarrier(VkCommandBuffer command, VkImage image,
+                                        std::uint32_t* source,
+                                        std::uint32_t* destination,
+                                        VkImageLayout* old_layout,
+                                        VkImageLayout new_layout);
+
+  void NormalizeDesktopBarriers(VkCommandBuffer command, std::uint32_t count,
+                                 VkImageMemoryBarrier* barriers);
+  void NormalizeDesktopBarriers(VkCommandBuffer command, std::uint32_t count,
+                                 VkImageMemoryBarrier2* barriers);
+
+  // Resource provenance recording (adapter wrappers).
+  bool WantsResourceRecords() const {
+    return recording_.load(std::memory_order_acquire);
+  }
+  void RecordImage(VkDevice device, VkImage image,
+                   const VkImageCreateInfo* info);
+  void RecordImageView(VkImageView view, VkImage image);
+  void RecordFramebuffer(VkFramebuffer framebuffer,
+                         const VkFramebufferCreateInfo* info);
+  void RecordRenderPass(VkRenderPass render_pass,
+                        const VkRenderPassCreateInfo* info);
+  void NoteDestroyImage(VkImage image);
+  void NoteDestroyImageView(VkImageView view);
+  void NoteDestroyFramebuffer(VkFramebuffer framebuffer);
+  void NoteRenderPassBegin(VkCommandBuffer command_buffer,
+                           const VkRenderPassBeginInfo* info);
+  bool EyeBindingComplete() const {
+    return eyes_bound_.load(std::memory_order_acquire);
+  }
+
+  // Render-thread frame cycle at host present begin.
+  void NoteHostPresent(VkQueue queue, VkDevice device);
+  // VK_NOT_READY leaves the present untouched until eye submission provenance
+  // is known. VK_SUCCESS means its waits were consumed on the graphics queue,
+  // so the eye copies that follow there are ordered after them. The present
+  // must then wait on *ready instead (none when it is VK_NULL_HANDLE).
+  VkResult PrepareHostPresent(VkQueue queue, VkDevice device,
+                              const VkPresentInfoKHR* info, VkSemaphore* ready);
+  void RecordDesktopSwapchain(VkDevice device, VkSwapchainKHR swapchain,
+                              const VkSwapchainCreateInfoKHR* info,
+                              const VkImage* images, unsigned count,
+                              bool converted_to_concurrent = false);
+  // On success the original present semaphores have been consumed by the
+  // mirror blit on the GPU. The caller must present waiting only on *ready,
+  // which the blit signals. The CPU never waits for the guest's frame here.
+  VkResult MirrorDesktop(VkQueue queue, const VkPresentInfoKHR* info,
+                         VkSemaphore* ready);
+
+  // Pose published for the frame that is about to render. The device bridge
+  // reads it once per frame on the render thread and injects it into the
+  // guest. valid=false until the XR session located a usable head pose.
+  // hands[0]=left, hands[1]=right carry this frame's tracked controller grip
+  // poses (metres, LOCAL space) when a controller layer is active.
+  ScriptedPoseSample PublishedHeadPose() const;
+  bool RecommendedEyeExtent(std::uint32_t* width, std::uint32_t* height) const;
+  // Render-thread boundary only: rebuild XR targets when Steam's settled
+  // resolution changes. The guest then reruns its verified eye initializer.
+  bool UpdateEyeResolution();
+  void NotePoseApplied(void* owner, std::uint64_t frame);
+
+  // Controller input delivery, consumed by the window-thread input runtime
+  // through the C ABI in xr_controller_abi.h. TakeControllerDelivery pops one
+  // batch produced by the once-per-frame action sync; it returns false when
+  // no controller layer is active or nothing is queued. The snapshot exposes
+  // the current levels for overflow resync. Haptics requests are thread-safe.
+  bool TakeControllerDelivery(ControllerDelivery* out);
+  ControllerSnapshot ControllerSnapshotForFrame() const;
+  void RequestControllerHaptics(int hand, float amplitude,
+                                std::uint64_t duration_ns, float frequency_hz);
+
+  void StopControllerHaptics(int hand);
+
+  // Diagnostics.
+  std::uint64_t submitted_frames() const {
+    return submitted_frames_.load(std::memory_order_relaxed);
+  }
+  std::uint64_t skipped_frames() const {
+    return skipped_frames_.load(std::memory_order_relaxed);
+  }
+  bool session_running() const {
+    return session_running_.load(std::memory_order_relaxed);
+  }
+  std::string runtime_name() const;
+
+ private:
+  VkImageLayout NormalizeDesktopBarrierLocked(std::uint32_t family,
+      VkImage image, std::uint32_t* source, std::uint32_t* destination,
+      VkImageLayout* old_layout, VkImageLayout new_layout);
+  bool FoveationSnapshotLocked(VkDevice,float*,float*,std::uint64_t*,int*);
+  int FoveationSceneEyeLocked(VkDevice, std::uint32_t, std::uint32_t) const;
+  friend struct OpenXrBackendTestAccess;
+  struct ImageRecord {
+    VkImage image = VK_NULL_HANDLE;
+    VkDevice device = VK_NULL_HANDLE;
+    std::uint32_t width = 0;
+    std::uint32_t height = 0;
+    VkFormat format = VK_FORMAT_UNDEFINED;
+    VkImageUsageFlags usage = 0;
+    VkSampleCountFlagBits samples = VK_SAMPLE_COUNT_1_BIT;
+    void* owner = nullptr;
+    std::uint64_t order = 0;
+  };
+  struct EyeBinding {
+    bool valid = false;
+    std::uint64_t frame = 0;
+    VkImage image = VK_NULL_HANDLE;
+    VkFramebuffer framebuffer = VK_NULL_HANDLE;
+    void* guest_framebuffer = nullptr;
+    VkImageLayout final_layout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL;
+    void* owner = nullptr;
+    std::uint32_t width = 0;
+    std::uint32_t height = 0;
+    VkFormat format = VK_FORMAT_UNDEFINED;
+  };
+  struct EyeSwapchain {
+    void* swapchain = nullptr;  // XrSwapchain (opaque to keep the header XR-free)
+    std::vector<VkImage> images;
+    std::vector<std::uint32_t> gl_images;
+    std::uint32_t acquired_index = 0;
+    bool image_acquired = false;
+    std::uint32_t width = 0;
+    std::uint32_t height = 0;
+    VkFormat format = VK_FORMAT_UNDEFINED;
+  };
+
+  bool InitializeSessionLocked(VkPhysicalDevice physical_device,
+                               VkDevice device,
+                               const VkDeviceCreateInfo* create_info,
+                               std::string* error);
+  // Session-owned controller action layer (poses, buttons, axes, haptics).
+  // Created at instance level, attached per session, detached on teardown so
+  // a replacement session never reuses stale spaces.
+  XrActions actions_;
+  bool actions_created_ = false;
+  // Shared by action sync, snapshots, haptics and lifecycle operations.
+  // Acquired after mutex_ on the render thread, but never held across
+  // xrWaitFrame; the input thread takes only this controller lock.
+  mutable std::mutex controller_mutex_;
+  // Syncs actions once per frame at the predicted display time and folds the
+  // resulting hand poses into published_pose_ before the guest renders.
+  void SyncControllersLocked(std::uint64_t predicted_display_time);
+  bool InitializeGlesSessionLocked(std::string *error);
+  bool InitializeSessionResourcesLocked(std::string *error);
+  bool CopyGlesEyesIntoSwapchains();
+  bool EnsureXrInstanceLocked(std::string* error = nullptr);
+  void DestroyXrInstanceLocked();
+  void DisarmLocked();
+  void* ResolveFunction(const char* name) const;
+  void SetupDeviceAfterCreationLocked(VkPhysicalDevice physical_device,
+                                      VkDevice device,
+                                      const VkDeviceCreateInfo* create_info);
+  void TeardownSessionLocked(const char* reason, bool preserve_device = false);
+  void HandleSessionState(int state);
+  void HandleReferenceSpaceChange(std::int64_t change_time);
+  bool RecoverSessionLocked(std::uint64_t now_ns);
+  // False only when the runtime names a GPU other than the guest device's.
+  bool RuntimeUsesGuestGpuLocked();
+  void PollSessionEvents();
+  bool SupportsPresentQueueLocked(VkQueue queue) const;
+  VkQueue FrameQueueForPresentLocked(VkQueue queue) const;
+  VkQueue GraphicsQueueForPresentLocked(VkQueue present) const;
+  bool unsupported_present_queue_logged_ = false;
+  // Drops the pose/images of the frame currently in flight without touching
+  // guest ownership, so the next xrEndFrame submits no layer instead of an
+  // image paired with a pose that no longer describes the same origin.
+  void InvalidateInFlightPose(const char* reason);
+  void RunFrameCycle(VkQueue queue, VkDevice device);
+  // Returns true when the backend owns this present but ran no XR frame, so
+  // the caller paces the guest itself.
+  bool NoteHostPresentLocked(VkQueue queue, VkDevice device);
+  bool NeedsIdlePacingLocked() const;
+  bool CreateSwapchains(std::string* error);
+  // Recreates the eye swapchains once in the format that copies the guest's
+  // eye bytes without a gamma change (see PreferredEyeSwapchainFormat).
+  void MatchSwapchainFormatToEyesLocked();
+  void DestroySwapchains();
+  void ResetFsr3Locked();
+  bool EnsureCopyResources(VkDevice device, std::uint32_t queue_family,
+                           std::string* error);
+  void DestroyCopyResources();
+  // Records both eye copies (and, when the mirror is enabled, both staging
+  // readbacks) into one command buffer and submits it once. Only the shared
+  // memory mirror waits for it; the headset path leaves it to the GPU.
+  bool CopyEyesIntoSwapchains(VkQueue queue);
+  void RecordEyeCopiesLocked(VkCommandBuffer command, const VkImage source[2],
+                             const VkImage destination[2]);
+  void RecordFxaaEyesLocked(VkCommandBuffer command);
+  // Per-frame GPU work (desktop mirror, eye copies) is submitted without a CPU
+  // wait. A slot is reused only after its fence signalled; its images let a
+  // guest destroy wait for the submissions that still read them.
+  struct AsyncSubmission {
+    VkCommandBuffer command = VK_NULL_HANDLE;
+    VkFence fence = VK_NULL_HANDLE;
+    bool pending = false;
+    bool eye_resources = false;
+    std::uint64_t serial = 0;  // bumped per submission
+    std::vector<VkImage> images;
+  };
+  // The shared-memory mirror's readback from the previous frame copy. It is
+  // published at the next copy, when the GPU has long finished it, so neither
+  // the headset nor the mirror makes the CPU wait for the frame.
+  struct MirrorReadback {
+    AsyncSubmission* slot = nullptr;
+    std::uint64_t serial = 0;
+    std::uint64_t frame = 0;
+    VkFormat format = VK_FORMAT_UNDEFINED;
+    std::uint32_t width = 0;
+    std::uint32_t height = 0;
+  };
+  void PublishMirrorReadbackLocked();
+  // vr.anti_aliasing: fxaa. The eye copy becomes one FXAA draw per eye into
+  // the runtime's swapchain image. Anything it cannot set up falls back to
+  // the plain copy, which never loses headset output.
+  struct FxaaState {
+    VkFormat target_format = VK_FORMAT_UNDEFINED;
+    VkShaderModule vertex = VK_NULL_HANDLE;
+    VkShaderModule fragment = VK_NULL_HANDLE;
+    VkSampler sampler = VK_NULL_HANDLE;
+    VkDescriptorSetLayout set_layout = VK_NULL_HANDLE;
+    VkDescriptorPool pool = VK_NULL_HANDLE;
+    VkDescriptorSet sets[2] = {};
+    VkPipelineLayout layout = VK_NULL_HANDLE;
+    VkRenderPass render_pass = VK_NULL_HANDLE;
+    VkPipeline pipeline = VK_NULL_HANDLE;
+    // The eye image each set samples, and its view.
+    VkImage sources[2] = {};
+    VkImageView source_views[2] = {};
+    // Per eye, one view and framebuffer per runtime swapchain image.
+    std::vector<VkImageView> target_views[2];
+    std::vector<VkFramebuffer> framebuffers[2];
+    bool failed = false;
+  };
+  bool FxaaEnabled() const;
+  // Pipeline, targets and eye bindings for this frame; false means copy.
+  bool PrepareFxaaLocked();
+  bool CreateFxaaPipelineLocked(VkFormat target_format);
+  void DestroyFxaaTargetsLocked();
+  void ForgetFxaaSourceLocked(VkImage image);
+  void DestroyFxaaLocked();
+  // The next slot, recorded-ready, or nullptr when its previous submission
+  // did not finish in time (the device is hung or lost).
+  AsyncSubmission* NextAsyncSubmissionLocked();
+  VkResult SubmitAsyncLocked(VkQueue queue, AsyncSubmission* slot,
+                             const VkSubmitInfo& submit);
+  // Waits for pending submissions reading `image`, or all of them for
+  // VK_NULL_HANDLE.
+  void WaitAsyncSubmissionsLocked(VkImage image);
+  // AA/FSR descriptors and history are shared between eye copies. Wait only
+  // for their previous users, never the current guest-present dependency.
+  void WaitEyeResourcesLocked();
+  // Semaphore the present of `image_index` waits on, created on first use.
+  enum class PresentStep { kMirror, kPrepare };
+  VkSemaphore PresentReadySemaphoreLocked(VkSwapchainKHR swapchain,
+                                          std::uint32_t image_index,
+                                          PresentStep step);
+  void DestroyRetiredSemaphoresLocked();
+  // In-headset keyboard: show/hide from the host's TextBox request, pointer
+  // input, and trigger masking. Runs inside the controller sync.
+  void UpdateVirtualKeyboardLocked();
+  // Rasterizes and uploads the panel when it changed. Returns true when the
+  // keyboard swapchain holds a released image ready for a quad layer.
+  bool PrepareVirtualKeyboardLayerLocked(VkQueue queue);
+  bool UploadVirtualKeyboardVulkan(VkQueue queue, VkImage image);
+  void DestroyVirtualKeyboardStaging();
+  void DestroyVirtualKeyboardResources();
+  bool CaptureEyeEvidence(VkQueue queue, int eye);
+  ScriptedPoseSample ComputeScriptedPose(std::uint64_t frame) const;
+  void EnsureMirrorForExtent(std::uint32_t width, std::uint32_t height);
+  MirrorVkProcs MirrorProcs() const;
+
+  VrGraphicsApi graphics_api_ = VrGraphicsApi::kVulkan;
+  GlesTransport *gles_ = nullptr;
+  std::uint64_t gl_min_version_ = 0;
+  std::uint64_t gl_max_version_ = 0;
+
+  // Held for a whole XR frame cycle and by every path that can destroy the
+  // session; always taken before mutex_.
+  std::mutex frame_mutex_;
+  mutable std::mutex mutex_;
+  // The frame cycle's hold on mutex_, so it can release it around
+  // xrWaitFrame. Only set while NoteHostPresent runs the cycle.
+  std::unique_lock<std::mutex>* state_lock_ = nullptr;
+  std::atomic<bool> armed_{false};
+  std::atomic<bool> recording_{false};
+  std::atomic<bool> eyes_bound_{false};
+  std::atomic<bool> session_running_{false};
+  std::atomic<std::uint64_t> submitted_frames_{0};
+  std::atomic<std::uint64_t> skipped_frames_{0};
+
+  // XR handles are stored as opaque pointers in the header; the implementation
+  // casts them back. This keeps vulkan-only consumers free of OpenXR headers.
+  void* xr_instance_ = nullptr;
+  std::uint64_t xr_system_ = 0;
+  void* xr_session_ = nullptr;
+  void* xr_local_space_ = nullptr;
+  void* xr_view_space_ = nullptr;
+  void* xr_stage_space_ = nullptr;
+  std::uint32_t xr_eye_width_[2] = {};
+  std::uint32_t xr_eye_height_[2] = {};
+  std::uint32_t xr_max_eye_width_[2] = {};
+  std::uint32_t xr_max_eye_height_[2] = {};
+  std::uint32_t resize_candidate_ = 0;
+  std::uint64_t resize_candidate_since_ = 0;
+  EyeSwapchain eye_swapchains_[2];
+  VirtualKeyboard keyboard_;
+  std::unique_ptr<VirtualKeyboardRasterizer> keyboard_raster_;
+  EyeSwapchain keyboard_swapchain_;
+  bool keyboard_swapchain_failed_ = false;
+  bool keyboard_image_ready_ = false;
+  std::uint64_t keyboard_uploaded_revision_ = 0;
+  // A new showKeyboard request may open the panel; Close disarms it until
+  // Roblox drops that request.
+  bool keyboard_armed_ = true;
+  pose::Pose keyboard_head_{};
+  bool keyboard_head_valid_ = false;
+  std::vector<std::uint8_t> keyboard_pixels_;
+  VkBuffer keyboard_staging_ = VK_NULL_HANDLE;
+  VkDeviceMemory keyboard_staging_memory_ = VK_NULL_HANDLE;
+  void* keyboard_staging_mapped_ = nullptr;
+  int xr_blend_mode_ = 0;
+  // Runtime name captured at xrCreateInstance so the bind-time diagnostics line
+  // can report it without re-entering runtime_name() under the held mutex.
+  std::string runtime_name_;
+  bool xr_instance_used_ = false;
+  // Libraries the runtime's first instance loaded; later instances load them
+  // with RTLD_DEEPBIND (see EnsureXrInstanceLocked).
+  std::vector<std::string> runtime_libraries_;
+  std::string user_manifest_;
+  std::string runtime_manifest_;
+
+  VkInstance vk_instance_ = VK_NULL_HANDLE;
+  std::uint32_t vk_instance_api_version_ = VK_API_VERSION_1_0;
+  bool fsr3_device_supported_ = false;
+  // One retained instance avoids invalid SteamVR ARM graphics-device caches
+  // during menu/game transitions. Only an identical creation request reuses it.
+  bool vk_instance_retained_ = false;
+  bool vk_device_retained_ = false;
+  bool foveation_runtime_available_ = false;
+  bool eye_gaze_available_ = false;
+  bool foveation_device_enabled_ = false;
+  bool foveation_host_copy_enabled_ = false;
+  bool foveation_used_in_frame_ = false;
+  XrFoveationMaps foveation_;
+  GazeAa gaze_aa_;
+  FsrUpscaler fsr_;
+  Fsr3SceneCapture fsr3_capture_;
+#ifdef MOCKTAIL_ENABLE_FSR3
+  Fsr3Upscaler fsr3_;
+  Fsr3GazeTransport fsr3_transport_;
+#endif
+  std::atomic<bool> fsr3_inputs_enabled_{false};
+  bool fsr3_failure_logged_ = false;
+  std::uint64_t fsr3_last_frame_ns_ = 0;
+  std::uint64_t fsr3_last_frame_ = 0;
+  bool fsr3_has_resources_ = false;
+  bool fsr3_capture_seen_[2]{};
+  float fsr3_gaze_radius_ = -1.f;
+  bool fsr3_contexts_configured_ = false;
+  bool fsr3_estimate_motion_ = true;
+  bool fsr3_depth_inverted_ = false, fsr3_depth_infinite_ = false;
+  std::uint64_t fsr3_camera_identity_[2]{};
+  float fsr3_camera_near_[2]{}, fsr3_camera_far_[2]{};
+  static constexpr int upscale_mode_ = 0;
+    FsrSettings fsr_settings_{};
+  bool fsr_failure_logged_ = false;
+  std::string guest_device_key_;
+  static std::string VulkanDeviceKey(const VkDeviceCreateInfo* info);
+  void ReleaseGuestRendererLocked();
+  unsigned guest_device_generation_ = 0;
+  bool defer_initial_session_ = false;
+  std::string guest_instance_key_;
+  VkDevice vk_device_ = VK_NULL_HANDLE;
+  VkPhysicalDevice vk_physical_device_ = VK_NULL_HANDLE;
+  std::uint32_t vk_queue_family_ = 0;
+  VkQueue vk_graphics_queue_ = VK_NULL_HANDLE;
+  std::vector<std::uint32_t> device_queue_families_;
+  bool single_guest_queue_ = false;
+  void* vk_loader_ = nullptr;
+  struct VkProcs;
+  VkProcs* vk_ = nullptr;
+
+  VkCommandPool copy_pool_ = VK_NULL_HANDLE;
+  // Synchronous one-off work: keyboard uploads, evidence, present fallback.
+  VkCommandBuffer copy_command_ = VK_NULL_HANDLE;
+  VkFence copy_fence_ = VK_NULL_HANDLE;
+  // Two submissions per frame, so three frames may be in flight.
+  static constexpr std::size_t kAsyncSubmissions = 6;
+  std::array<AsyncSubmission, kAsyncSubmissions> async_{};
+  std::size_t next_async_ = 0;
+  MirrorReadback mirror_readback_{};
+  FxaaState fxaa_{};
+  // The mirror's signal for this present, which PrepareHostPresent passes on.
+  VkSemaphore mirror_ready_ = VK_NULL_HANDLE;
+  // Semaphores of destroyed desktop swapchains. A present may still wait on
+  // one, so they are destroyed only once the device is idle.
+  std::vector<VkSemaphore> retired_semaphores_;
+  std::unordered_map<VkFormat, VkFormatFeatureFlags> blit_features_;
+
+  // Optional desktop two-eye mirror (MOCKTAIL_VR_MIRROR_SHM). Publishes the
+  // latest complete pair through shared memory; inert when unset.
+  VrMirror mirror_;
+
+  std::unordered_map<VkImage, ImageRecord> images_;
+  struct DesktopSwapchain {
+    VkExtent2D extent;
+    VkFormat format;
+    std::vector<VkImage> images;
+    VkSharingMode sharing_mode = VK_SHARING_MODE_EXCLUSIVE;
+    std::vector<std::uint32_t> families;
+    bool converted_to_concurrent = false;
+    // Two per image, see PresentReadySemaphoreLocked.
+    std::vector<VkSemaphore> ready;
+  };
+  std::unordered_map<VkSwapchainKHR, DesktopSwapchain> desktop_swapchains_;
+  std::unordered_map<VkImageView, VkImage> image_views_;
+  std::unordered_map<VkFramebuffer, std::vector<VkImageView>> framebuffer_views_;
+  std::unordered_map<VkFramebuffer, VkRenderPass> framebuffer_render_pass_;
+  std::unordered_map<VkRenderPass, std::vector<VkImageLayout>> render_pass_final_layouts_;
+  std::unordered_map<VkQueue, std::uint32_t> queue_families_;
+  struct CommandRecord {
+    VkCommandPool pool = VK_NULL_HANDLE;
+    std::uint32_t family = UINT32_MAX;
+    std::vector<std::pair<VkImage, std::uint64_t>> eye_images;
+  };
+  std::unordered_map<VkCommandPool, std::uint32_t> command_pool_families_;
+  std::unordered_map<VkCommandBuffer, CommandRecord> command_records_;
+  std::unordered_map<VkImage, VkQueue> eye_render_queues_;
+  std::unordered_map<VkImage, std::uint64_t> eye_render_frames_;
+  std::uint64_t image_order_ = 0;
+  EyeBinding eyes_[2];
+
+  // Frame cycle state (render thread only).
+  bool frame_open_ = false;
+  bool frame_should_render_ = false;
+  // A running session is hidden in SYNCHRONIZED; shouldRender still governs rendering.
+  bool visibility_lost_ = false;
+  bool session_recovery_pending_ = false;
+  std::uint64_t next_session_retry_ns_ = 0;
+  // Consecutive failed session recoveries, for backoff and for deciding when
+  // the XrInstance itself must be recreated (e.g. after a runtime restart).
+  std::uint32_t session_recovery_failures_ = 0;
+  bool xr_instance_stale_ = false;
+  bool present_sync_failure_logged_ = false;
+  bool gles_attach_failed_ = false;
+  // Runtime swapchain formats, and the format chosen once the guest eye
+  // format is known (VK_FORMAT_UNDEFINED until then).
+  std::vector<std::int64_t> xr_swapchain_formats_;
+  VkFormat eye_swapchain_format_ = VK_FORMAT_UNDEFINED;
+  VkFormat eye_format_checked_ = VK_FORMAT_UNDEFINED;
+  std::uint64_t frame_display_time_ = 0;
+  // MOCKTAIL_VR_UNPACED benchmark mode: guest presents before this monotonic
+  // time leave the open XR frame alone instead of blocking in xrWaitFrame.
+  std::uint64_t frame_due_ns_ = 0;
+  struct ViewState {
+    float position[3];
+    float orientation[4];
+    float fov[4];  // angleLeft, angleRight, angleUp, angleDown (radians)
+    bool valid;
+  };
+  ViewState frame_views_[2] = {};
+  struct PoseStorage {
+    float position[3] = {0.f, 0.f, 0.f};
+    float orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  };
+  PoseStorage frame_view_poses_[2];
+  bool frame_views_valid_ = false;
+  // One-shot guard so a canted-view runtime reports the rejection reason once
+  // instead of once per frame per eye.
+  bool projection_rejection_logged_ = false;
+  mutable ScriptedPoseSample published_pose_;
+  std::uint64_t xr_frame_counter_ = 0;
+  // All begun XR frames, including an unworn/invisible headset.
+  std::uint64_t xr_begun_frames_ = 0;
+  std::unordered_map<void*, std::uint64_t> applied_poses_;
+};
+
+// Process-wide single backend owned by main. Adapter hooks resolve these
+// exported C symbols; they are inert while no backend is armed.
+OpenXrBackend* ActiveVrBackend();
+
+// Paths of the shared objects mapped into the process.
+std::vector<std::string> LoadedSharedObjects();
+// Paths mapped now that were not in `before`.
+std::vector<std::string> SharedObjectsLoadedSince(
+    const std::vector<std::string>& before);
+
+// Holds the runtime's libraries open with RTLD_DEEPBIND while the OpenXR
+// loader loads the runtime, so its Vulkan calls bind to its own libvulkan
+// dependency instead of the Vulkan adapter's exported hooks. Released after
+// the loader holds its own reference, so the runtime still unloads with its
+// instance.
+class DeepBoundLibraries {
+ public:
+  explicit DeepBoundLibraries(const std::vector<std::string>& paths);
+  ~DeepBoundLibraries();
+  DeepBoundLibraries(const DeepBoundLibraries&) = delete;
+  DeepBoundLibraries& operator=(const DeepBoundLibraries&) = delete;
+
+ private:
+  std::vector<void*> handles_;
+};
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_OPENXR_BACKEND_H_

include/mocktail/vr/openxr_preview.h

@@ -0,0 +1,34 @@
+#ifndef MOCKTAIL_VR_OPENXR_PREVIEW_H_
+#define MOCKTAIL_VR_OPENXR_PREVIEW_H_
+
+#include <array>
+#include <cstdint>
+#include <string>
+
+namespace mocktail::vr {
+
+struct PreviewOptions {
+  // Zero keeps the scene open until the runtime or user requests exit.
+  std::uint32_t frame_limit = 0;
+};
+
+struct PreviewResult {
+  bool success = false;
+  std::string message;
+  std::uint64_t frames = 0;
+  std::uint64_t rendered_frames = 0;
+  std::uint64_t tracked_frames = 0;
+  std::array<float, 3> head_position{};
+  std::array<float, 4> head_orientation{0, 0, 0, 1};
+};
+
+// Runs a native Vulkan/OpenXR scene with a panel fixed in LOCAL space. The
+// compositor projects it into both eyes. Roblox images/input are not connected.
+// Call on the main thread: SIGINT/SIGTERM request a graceful session exit, and
+// their previous handlers are restored before returning.
+PreviewResult RunOpenXrPreview(const PreviewOptions& options = {});
+std::string FormatPreviewResult(const PreviewResult& result);
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_OPENXR_PREVIEW_H_

include/mocktail/vr/openxr_probe.h

@@ -0,0 +1,52 @@
+#ifndef MOCKTAIL_VR_OPENXR_PROBE_H_
+#define MOCKTAIL_VR_OPENXR_PROBE_H_
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace mocktail::vr {
+
+enum class ProbeStatus {
+  kReady,
+  kBuildDisabled,
+  kRuntimeUnavailable,
+  kHeadsetUnavailable,
+  kIncompatibleRuntime,
+  kError,
+};
+
+struct ViewConfiguration {
+  std::uint32_t width = 0;
+  std::uint32_t height = 0;
+  std::uint32_t samples = 0;
+};
+
+struct ProbeReport {
+  ProbeStatus status = ProbeStatus::kError;
+  std::string message;
+  std::string sdk_version;
+  std::string runtime_name;
+  std::string runtime_version;
+  std::string system_name;
+  std::vector<std::string> extensions;
+  std::vector<ViewConfiguration> views;
+  bool orientation_tracking = false;
+  bool position_tracking = false;
+  std::string minimum_vulkan_version;
+  std::string maximum_vulkan_version;
+};
+
+// Native host discovery only. Does not load Roblox, change the active runtime,
+// create a graphics device/session, or claim that VR rendering is implemented.
+ProbeReport ProbeOpenXr();
+std::string FormatProbeReport(const ProbeReport& report);
+int ProbeExitCode(ProbeStatus status);
+
+// False in builds configured without MOCKTAIL_ENABLE_VR; --vr fails closed
+// early in that case instead of starting Roblox without VR support.
+bool IsOpenXrSupportCompiled();
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_OPENXR_PROBE_H_

include/mocktail/vr/performance_stats.h

@@ -0,0 +1,50 @@
+#ifndef MOCKTAIL_VR_PERFORMANCE_STATS_H_
+#define MOCKTAIL_VR_PERFORMANCE_STATS_H_
+
+#include <cstdint>
+#include <deque>
+
+namespace mocktail::vr {
+
+struct PerformanceSnapshot {
+  std::uint64_t timestamp_ns = 0;
+  std::uint64_t frames = 0;
+  std::uint64_t last_frame_ns = 0;
+  std::uint64_t process = 0;
+  std::uint64_t width = 0, height = 0;
+  bool visible = false;
+  std::uint64_t render_width = 0, render_height = 0;
+};
+
+// Count successful application projections over a rolling second. Neither
+// the scheduler's cap nor compositor repeats count as new game frames.
+class PerformanceRate {
+ public:
+  void Reset() { samples_.clear(); }
+  double Sample(std::uint64_t now, const PerformanceSnapshot& snapshot) {
+    if (!snapshot.visible || snapshot.timestamp_ns > now ||
+        now - snapshot.timestamp_ns > kSecond ||
+        (!samples_.empty() && (now <= samples_.back().time ||
+                              snapshot.frames < samples_.back().frames))) {
+      Reset();
+      return -1.;
+    }
+    samples_.push_back({now, snapshot.frames});
+    const auto cutoff = now > kSecond ? now - kSecond : 0;
+    while (samples_.size() > 2 && samples_[1].time <= cutoff)
+      samples_.pop_front();
+    if (!snapshot.last_frame_ns || snapshot.last_frame_ns > now ||
+        now - snapshot.last_frame_ns >= kSecond) return 0.;
+    const auto elapsed = now - samples_.front().time;
+    if (elapsed < kSecond / 2) return -1.;
+    return double(snapshot.frames - samples_.front().frames) * 1.e9 /
+           double(elapsed);
+  }
+ private:
+  static constexpr std::uint64_t kSecond = 1'000'000'000;
+  struct SamplePoint { std::uint64_t time, frames; };
+  std::deque<SamplePoint> samples_;
+};
+
+}  // namespace mocktail::vr
+#endif

include/mocktail/vr/performance_telemetry.h

@@ -0,0 +1,122 @@
+#ifndef MOCKTAIL_VR_PERFORMANCE_TELEMETRY_H_
+#define MOCKTAIL_VR_PERFORMANCE_TELEMETRY_H_
+
+#include "mocktail/vr/performance_stats.h"
+#include <atomic>
+#include <cstdlib>
+#include <new>
+#include <fcntl.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+namespace mocktail::vr {
+
+// The launcher owns a private tmpfs file for the lifetime of one application.
+// Only lock-free stores run in the frame path: no file writes, GPU waits or
+// frame history allocations. A separate noninteractive overlay reads it.
+struct alignas(64) SharedPerformanceStats {
+  static constexpr std::uint64_t kMagic = 0x4e43504600000002ULL;
+  std::atomic<std::uint64_t> magic{0}, sequence{0};
+  std::atomic<std::uint64_t> timestamp_ns{0}, frames{0}, last_frame_ns{0};
+  std::atomic<std::uint64_t> process{0}, width{0}, height{0}, visible{0};
+  std::atomic<std::uint64_t> render_width{0}, render_height{0};
+};
+static_assert(std::atomic<std::uint64_t>::is_always_lock_free);
+
+class PerformanceMapping {
+ public:
+  PerformanceMapping() = default;
+  PerformanceMapping(const PerformanceMapping&) = delete;
+  PerformanceMapping& operator=(const PerformanceMapping&) = delete;
+  ~PerformanceMapping() {
+    if (record_) munmap(record_, sizeof(SharedPerformanceStats));
+  }
+  bool Open(const char* path, bool writer) {
+    if (record_) return true;
+    if (!path || path[0] != '/') return false;
+    const int fd = open(path, (writer ? O_RDWR : O_RDONLY) | O_CLOEXEC | O_NOFOLLOW);
+    if (fd < 0) return false;
+    struct stat info{};
+    if (fstat(fd, &info) || !S_ISREG(info.st_mode) || info.st_uid != geteuid() ||
+        (info.st_mode & 0077) || info.st_size < static_cast<off_t>(sizeof(SharedPerformanceStats))) {
+      close(fd);
+      return false;
+    }
+    void* mapped = mmap(nullptr, sizeof(SharedPerformanceStats),
+                        writer ? PROT_READ | PROT_WRITE : PROT_READ, MAP_SHARED, fd, 0);
+    close(fd);
+    if (mapped == MAP_FAILED) return false;
+    record_ = static_cast<SharedPerformanceStats*>(mapped);
+    if (writer) {
+      new (record_) SharedPerformanceStats;
+      record_->magic.store(SharedPerformanceStats::kMagic, std::memory_order_release);
+    }
+    return true;
+  }
+  void Publish(const PerformanceSnapshot& value) {
+    if (!record_) return;
+    record_->sequence.fetch_add(1, std::memory_order_acq_rel);
+    record_->timestamp_ns.store(value.timestamp_ns, std::memory_order_relaxed);
+    record_->frames.store(value.frames, std::memory_order_relaxed);
+    record_->last_frame_ns.store(value.last_frame_ns, std::memory_order_relaxed);
+    record_->process.store(value.process, std::memory_order_relaxed);
+    record_->width.store(value.width, std::memory_order_relaxed);
+    record_->height.store(value.height, std::memory_order_relaxed);
+    record_->visible.store(value.visible, std::memory_order_relaxed);
+    record_->render_width.store(value.render_width, std::memory_order_relaxed);
+    record_->render_height.store(value.render_height, std::memory_order_relaxed);
+    record_->sequence.fetch_add(1, std::memory_order_release);
+  }
+  bool Read(PerformanceSnapshot* value) const {
+    if (!record_ || record_->magic.load(std::memory_order_acquire) != SharedPerformanceStats::kMagic)
+      return false;
+    for (int attempt = 0; attempt < 8; ++attempt) {
+      const auto sequence = record_->sequence.load(std::memory_order_acquire);
+      if (sequence & 1) continue;
+      PerformanceSnapshot snapshot;
+      snapshot.timestamp_ns = record_->timestamp_ns.load(std::memory_order_relaxed);
+      snapshot.frames = record_->frames.load(std::memory_order_relaxed);
+      snapshot.last_frame_ns = record_->last_frame_ns.load(std::memory_order_relaxed);
+      snapshot.process = record_->process.load(std::memory_order_relaxed);
+      snapshot.width = record_->width.load(std::memory_order_relaxed);
+      snapshot.height = record_->height.load(std::memory_order_relaxed);
+      snapshot.visible = record_->visible.load(std::memory_order_relaxed) != 0;
+      snapshot.render_width = record_->render_width.load(std::memory_order_relaxed);
+      snapshot.render_height = record_->render_height.load(std::memory_order_relaxed);
+      std::atomic_thread_fence(std::memory_order_acquire);
+      if (sequence == record_->sequence.load(std::memory_order_relaxed)) {
+        *value = snapshot;
+        return true;
+      }
+    }
+    return false;
+  }
+ private:
+  SharedPerformanceStats* record_ = nullptr;
+};
+
+class PerformancePublisher {
+ public:
+  void Update(std::uint64_t now, std::uint64_t frames, bool visible,
+              std::uint32_t width, std::uint32_t height,
+              std::uint32_t render_width, std::uint32_t render_height) {
+    if (!attempted_) {
+      attempted_ = true;
+      process_ = static_cast<std::uint64_t>(getpid());
+      enabled_ = mapping_.Open(std::getenv("NIGHTCAP_PERFORMANCE_TELEMETRY"), true);
+    }
+    if (!enabled_) return;
+    if (frames != previous_frames_) last_frame_ns_ = now;
+    previous_frames_ = frames;
+    mapping_.Publish({now, frames, last_frame_ns_, process_,
+                      width, height, visible, render_width, render_height});
+  }
+ private:
+  PerformanceMapping mapping_;
+  bool attempted_ = false, enabled_ = false;
+  std::uint64_t previous_frames_ = 0, last_frame_ns_ = 0, process_ = 0;
+};
+
+}  // namespace mocktail::vr
+#endif

include/mocktail/vr/projection_jitter.h

@@ -0,0 +1,136 @@
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdint>
+#include <limits>
+
+namespace mocktail::vr {
+
+inline bool ValidRasterJitter(bool enabled, const float (&jitter_pixels)[2],
+                             std::uint32_t width, std::uint32_t height) {
+  return enabled && width && height &&
+         std::isfinite(jitter_pixels[0]) && std::isfinite(jitter_pixels[1]) &&
+         std::abs(jitter_pixels[0]) <= 1.f &&
+         std::abs(jitter_pixels[1]) <= 1.f;
+}
+
+// Adjusts the native projection's positive {up, down, left, right} tangent
+// extents. Jitter is image displacement in render pixels: +X right, +Y down.
+// With the existing right-handed camera looking down -Z, a ray projects to
+// u=(x/-z+left)/(left+right), v=(up-y/-z)/(up+down). Translating both frustum
+// bounds preserves its angular span and displaces every ray by the same pixels.
+// Only the caller-owned projection changes; runtime FOV and tracking do not.
+inline bool ApplyRasterProjectionJitter(float (&tangents)[4], bool enabled,
+                                        const float (&jitter_pixels)[2],
+                                        std::uint32_t render_width,
+                                        std::uint32_t render_height) {
+  if (!ValidRasterJitter(enabled, jitter_pixels, render_width, render_height))
+    return false;
+  for (float value : tangents)
+    if (!std::isfinite(value) || value <= 0.f)
+      return false;
+
+  const double dx = static_cast<double>(jitter_pixels[0]) *
+                    (static_cast<double>(tangents[2]) + tangents[3]) /
+                    render_width;
+  const double dy = static_cast<double>(jitter_pixels[1]) *
+                    (static_cast<double>(tangents[0]) + tangents[1]) /
+                    render_height;
+  const std::array<float, 4> shifted = {
+      static_cast<float>(tangents[0] + dy),
+      static_cast<float>(tangents[1] - dy),
+      static_cast<float>(tangents[2] + dx),
+      static_cast<float>(tangents[3] - dx)};
+  for (float value : shifted)
+    if (!std::isfinite(value) || value <= 0.f)
+      return false;
+  for (int i = 0; i < 4; ++i)
+    tangents[i] = shifted[i];
+  return true;
+}
+
+// The verified native Camera getter mirrors M02 for the right eye. Apply jitter
+// after that operation to give both eyes the same displacement. Vulkan image Y
+// increases downward; the verified native scene shader negates clip Y before
+// its Vulkan viewport, while camera-space Y and this projection increase up.
+inline bool ApplyRasterMatrixProjectionJitter(float (&matrix)[16], bool enabled,
+                                              const float (&jitter_pixels)[2],
+                                              std::uint32_t render_width,
+                                              std::uint32_t render_height) {
+  if (!ValidRasterJitter(enabled, jitter_pixels, render_width, render_height))
+    return false;
+  for (float value : matrix)
+    if (!std::isfinite(value))
+      return false;
+  if (matrix[0] <= 0.f || matrix[5] <= 0.f || matrix[14] != -1.f ||
+      matrix[15] != 0.f)
+    return false;
+  const float x = matrix[2] - 2.f * jitter_pixels[0] / render_width;
+  const float y = matrix[6] + 2.f * jitter_pixels[1] / render_height;
+  if (!std::isfinite(x) || !std::isfinite(y))
+    return false;
+  matrix[2] = x;
+  matrix[6] = y;
+  return true;
+}
+
+inline bool ApplyRasterViewProjectionJitter(float (&matrix)[16], bool enabled,
+                                           const float (&jitter_pixels)[2],
+                                           std::uint32_t render_width,
+                                           std::uint32_t render_height) {
+  if (!ValidRasterJitter(enabled, jitter_pixels, render_width, render_height))
+    return false;
+  for (float value : matrix)
+    if (!std::isfinite(value))
+      return false;
+  double denominator_norm = 0.;
+  for (int i = 12; i < 16; ++i)
+    denominator_norm += static_cast<double>(matrix[i]) * matrix[i];
+  if (denominator_norm <= 0.)
+    return false;
+  const float dx = 2.f * jitter_pixels[0] / render_width;
+  const float dy = -2.f * jitter_pixels[1] / render_height;
+  float shifted[8];
+  for (int column = 0; column < 4; ++column) {
+    shifted[column] = matrix[column] + dx * matrix[12 + column];
+    shifted[4 + column] = matrix[4 + column] + dy * matrix[12 + column];
+  }
+  for (float value : shifted)
+    if (!std::isfinite(value))
+      return false;
+  std::copy_n(shifted, 8, matrix);
+  return true;
+}
+
+// The observed native reverse-Z perspective builder writes M22=n/(f-n),
+// M23=n*f/(f-n), M32=-1. Derive its actual clip planes without assuming a
+// fixed near plane, which the client changes with its camera mode.
+inline bool DecodeReverseProjectionDepth(const float (&matrix)[16],
+                                         float* camera_near,
+                                         float* camera_far,
+                                         bool* infinite) {
+  if (!camera_near || !camera_far || !infinite || matrix[14] != -1.f ||
+      matrix[15] != 0.f)
+    return false;
+  for (float value : matrix)
+    if (!std::isfinite(value))
+      return false;
+  const double a = matrix[10], b = matrix[11];
+  if (a < 0. || b <= 0.)
+    return false;
+  const float near = static_cast<float>(b / (a + 1.));
+  const bool is_infinite = a == 0.;
+  const float far = is_infinite ? std::numeric_limits<float>::infinity()
+                               : static_cast<float>(b / a);
+  if (!std::isfinite(near) || near <= 0.f ||
+      (!is_infinite && (!std::isfinite(far) || far <= near)))
+    return false;
+  *camera_near = near;
+  *camera_far = far;
+  *infinite = is_infinite;
+  return true;
+}
+
+}  // namespace mocktail::vr

include/mocktail/vr/render_core_preference.h

@@ -0,0 +1,29 @@
+#pragma once
+#include <algorithm>
+#include <cstdint>
+#include <vector>
+
+namespace mocktail::vr::internal {
+struct CpuCapacity { unsigned id; unsigned capacity; };
+
+// Input contains only CPUs already allowed for this thread. Keep near-peer
+// performance cores together, and retain the original mask if information is
+// incomplete or a preference would leave fewer than two available cores.
+inline std::vector<unsigned> PerformanceCpuSubset(
+    const std::vector<CpuCapacity>& allowed) {
+  std::vector<unsigned> original;
+  unsigned maximum = 0;
+  bool complete = true;
+  for (const auto& cpu : allowed) {
+    original.push_back(cpu.id);
+    maximum = std::max(maximum, cpu.capacity);
+    complete = complete && cpu.capacity > 0;
+  }
+  if (!complete || !maximum || allowed.size() < 2) return original;
+  std::vector<unsigned> selected;
+  for (const auto& cpu : allowed)
+    if (std::uint64_t(cpu.capacity) * 5 >= std::uint64_t(maximum) * 4)
+      selected.push_back(cpu.id);
+  return selected.size() >= 2 ? selected : original;
+}
+}  // namespace mocktail::vr::internal

include/mocktail/vr/roblox_vr_device_bridge.h

@@ -0,0 +1,131 @@
+#ifndef MOCKTAIL_VR_ROBLOX_VR_DEVICE_BRIDGE_H_
+#define MOCKTAIL_VR_ROBLOX_VR_DEVICE_BRIDGE_H_
+
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <string_view>
+
+#include "compat/build_profile.h"
+#include "mocktail/status.h"
+#include "mocktail/vr/roblox_vr_guest_abi.h"
+
+namespace mocktail::vr {
+namespace internal {
+struct VrBridgeTestAccess;
+struct VrBuildContract;
+}
+
+const compat::VrDebugDeviceBridgeProfile* FindRobloxVrDeviceProfile(
+    std::string_view build_id);
+
+// Human-readable list of the Roblox builds VR supports, e.g.
+// "2998 (2.736.1408) and 3092 (2.738.1397)", for error messages.
+std::string DescribeSupportedVrBuilds();
+
+// Experimental native stereo bring-up for the exact Build-ID-scoped
+// RBX::Graphics::DebugDeviceVR object of the guest client.
+//
+// The bridge interposes the state and eye getters of the exact guest build.
+// Resource readiness is checked on the live object during each state call;
+// initialization never dereferences cached guest object/device pointers. The
+// guest owns resource destruction. Recreated objects and reused addresses
+// therefore need no cache invalidation. Initialization happens only on a thread
+// observed presenting.
+class RobloxVrDeviceBridge final {
+public:
+  using StateGetterFn = guest_abi::StateGetterFn;
+  using EyeGetterFn = void *(*)(void *device_object, int eye_index);
+  using EyeInitializerFn = void (*)(void *device_object, void *graphics_device);
+
+  RobloxVrDeviceBridge() = default;
+  ~RobloxVrDeviceBridge();
+
+  RobloxVrDeviceBridge(const RobloxVrDeviceBridge &) = delete;
+  RobloxVrDeviceBridge &operator=(const RobloxVrDeviceBridge &) = delete;
+
+  // Arms the bridge for an exact-build profile that carries
+  // vr_debug_device_bridge metadata. Claims the process-wide bridge slot.
+  Status Install(const compat::BuildProfile &profile);
+
+  // Validates machine contracts at the loaded image base and interposes the
+  // two DebugDeviceVR vtable slots. Called once, after libroblox relocations
+  // and before any guest startup code runs.
+  Status Activate(std::uintptr_t image_base);
+
+  // Restores the interposed vtable slots and disarms. Safe to call twice.
+  void Shutdown();
+
+  bool installed() const { return installed_; }
+  bool active() const { return active_.load(std::memory_order_acquire); }
+
+  // Render-thread notification from the Vulkan adapter's host present path.
+  void NoteHostPresent();
+
+  // Guest-side hooks invoked by the interposed vtable stubs.
+  void OnHapticsCall(void* device_object, int hand, float amplitude);
+  // HapticService:SetMotor on Gamepad1 LeftHand (0) / RightHand (1); the
+  // level holds until the game sets it again.
+  void OnSetMotorCall(int hand, float amplitude);
+  void OnPointerFrameCall(void* result, void* service);
+  void OnStateGetterCall(void *result_buffer, void *device_object);
+  void OnEyeGetterCall(void *device_object, int eye_index, void *framebuffer);
+
+  StateGetterFn original_state_getter() const {
+    return original_state_getter_.load(std::memory_order_acquire);
+  }
+  EyeGetterFn original_eye_getter() const {
+    return original_eye_getter_.load(std::memory_order_acquire);
+  }
+
+  // Cumulative initialization diagnostics (not a count of live devices).
+  std::uintptr_t image_base() const {
+    return image_base_.load(std::memory_order_acquire);
+  }
+  int captured_device_count() const;
+  int initialized_device_count() const;
+  std::uint64_t present_count() const {
+    return present_count_.load(std::memory_order_relaxed);
+  }
+  std::uint64_t eye_getter_call_count(int eye_index) const;
+
+private:
+  friend struct internal::VrBridgeTestAccess;
+  static constexpr std::uint64_t kEyeGetterSummaryInterval = 600;
+  bool ValidateObjectHeader(void *self) const;
+  void *ValidatedGraphicsDevice(void *self) const;
+  void TryInitializeEyes(void *self);
+  bool RestoreVtableLocked();
+
+  mutable std::mutex mutex_;
+  compat::VrDebugDeviceBridgeProfile profile_{};
+  const internal::VrBuildContract* contract_ = nullptr;
+  bool installed_ = false;
+  std::atomic<bool> active_{false};
+  std::atomic<std::uintptr_t> image_base_{0};
+  std::atomic<std::uintptr_t> image_size_{0};
+  std::uintptr_t *vtable_ = nullptr;
+  std::uintptr_t original_haptic_slot_ = 0;
+  std::uintptr_t original_state_slot_ = 0;
+  std::uintptr_t original_eye_slot_ = 0;
+  std::atomic<StateGetterFn> original_state_getter_{nullptr};
+  std::atomic<EyeGetterFn> original_eye_getter_{nullptr};
+  std::atomic<std::uint64_t> present_thread_{0};
+  std::atomic<std::uint64_t> present_count_{0};
+  std::atomic<bool> flag_warning_logged_{false};
+  std::atomic<int> captured_count_{0};
+  std::atomic<int> initialized_count_{0};
+  mutable std::atomic<std::uint64_t> eye_call_totals_[2] = {};
+};
+
+// Process-wide single active bridge, mirroring the audio output-device
+// bridge ownership model. Install claims the slot; the destructor releases
+// it. legacy_runtime forwards the loaded libroblox image base through
+// NotifyRobloxVrImageLoaded; it is a successful no-op while no bridge is
+// armed, and fail-closed once one is.
+Status NotifyRobloxVrImageLoaded(std::uintptr_t image_base);
+
+} // namespace mocktail::vr
+
+#endif // MOCKTAIL_VR_ROBLOX_VR_DEVICE_BRIDGE_H_

include/mocktail/vr/roblox_vr_guest_abi.h

@@ -0,0 +1,34 @@
+#ifndef MOCKTAIL_VR_ROBLOX_VR_GUEST_ABI_H_
+#define MOCKTAIL_VR_ROBLOX_VR_GUEST_ABI_H_
+#include <cstdint>
+#include <cstring>
+namespace mocktail::vr::guest_abi {
+// AAPCS64 uses x0 for self and x8 for an indirect aggregate result. Declaring
+// the actual aggregate return lets the compiler preserve the guest ABI.
+struct StateResult { std::uint8_t bytes[0x138]; };
+struct FrameResult { float elements[12]; };
+static_assert(sizeof(StateResult) == 0x138);
+static_assert(sizeof(FrameResult) == 0x30);
+#if defined(__aarch64__)
+using StateGetterFn = StateResult (*)(void* self);
+using PointerFrameFn = FrameResult (*)(void* self);
+inline void CallState(StateGetterFn fn, void* result, void* self) {
+  const auto value = fn(self);
+  std::memcpy(result, &value, sizeof(value));
+}
+inline void CallPointer(PointerFrameFn fn, void* result, void* self) {
+  const auto value = fn(self);
+  std::memcpy(result, &value, sizeof(value));
+}
+#else
+using StateGetterFn = void* (*)(void* result, void* self);
+using PointerFrameFn = void* (*)(void* result, void* self);
+inline void CallState(StateGetterFn fn, void* result, void* self) {
+  fn(result, self);
+}
+inline void CallPointer(PointerFrameFn fn, void* result, void* self) {
+  fn(result, self);
+}
+#endif
+} // namespace mocktail::vr::guest_abi
+#endif

include/mocktail/vr/temporal_reprojection.h

@@ -0,0 +1,39 @@
+#pragma once
+#include "mocktail/vr/vr_pose_math.h"
+#include <cmath>
+#include <cstdint>
+
+namespace mocktail::vr {
+struct TemporalEyePose {
+  float orientation[4]={0,0,0,1};
+  float fov[4]={-1,1,1,-1};
+  float position[3]={};
+};
+
+// Depthless rotational reprojection. Translation has no reliable depth-based
+// correspondence, so reject history during appreciable eye translation.
+inline bool TemporalReprojection(const TemporalEyePose& current,
+                                 const TemporalEyePose& previous,
+                                 float rows[3][4]) {
+  pose::Quat c,p;
+  if(!pose::QuatNormalize({current.orientation[0],current.orientation[1],current.orientation[2],current.orientation[3]},&c) ||
+     !pose::QuatNormalize({previous.orientation[0],previous.orientation[1],previous.orientation[2],previous.orientation[3]},&p))return false;
+  float distance=0;
+  for(int i=0;i<3;++i){const float d=current.position[i]-previous.position[i];if(!std::isfinite(d))return false;distance+=d*d;}
+  if(distance>.0025f*.0025f)return false;
+  const auto rotation=pose::QuatMultiply(pose::QuatConjugate(p),c);
+  if(std::abs(rotation.w)<.99905f)return false; // Reject large jumps (>5 degrees/frame).
+  float f[4],old[4];
+  for(int i=0;i<4;++i){f[i]=std::tan(current.fov[i]);old[i]=std::tan(previous.fov[i]);if(!std::isfinite(f[i]+old[i]))return false;}
+  if(f[1]<=f[0] || f[2]<=f[3] || old[1]<=old[0] || old[2]<=old[3])return false;
+  const pose::Vec3 basis[3]={{f[1]-f[0],0,0},{0,f[3]-f[2],0},{f[0],f[2],-1}};
+  for(int column=0;column<3;++column){
+    const auto ray=pose::QuatRotate(rotation,basis[column]);
+    rows[0][column]=(ray.x+old[0]*ray.z)/(old[1]-old[0]);
+    rows[1][column]=(-old[2]*ray.z-ray.y)/(old[2]-old[3]);
+    rows[2][column]=-ray.z;
+  }
+  for(int i=0;i<3;++i)rows[i][3]=0;
+  return true;
+}
+}

include/mocktail/vr/virtual_keyboard.h

@@ -0,0 +1,191 @@
+#ifndef MOCKTAIL_VR_VIRTUAL_KEYBOARD_H_
+#define MOCKTAIL_VR_VIRTUAL_KEYBOARD_H_
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "mocktail/vr/vr_pose_math.h"
+
+namespace mocktail::vr {
+
+// Host side of the in-headset keyboard. The window module owns Roblox's
+// TextBox focus and the SDL event path; main wires these callbacks so the VR
+// library never links the window library. Every callback may be called from
+// the render thread and must be thread-safe.
+struct VirtualKeyboardHost {
+  void* context = nullptr;
+  // True while Roblox has asked for an on-screen keyboard (showKeyboard).
+  bool (*input_requested)(void* context) = nullptr;
+  // Commits UTF-8 text exactly like an SDL_EVENT_TEXT_INPUT.
+  void (*commit_text)(void* context, const char* utf8) = nullptr;
+  // Presses and releases one SDL scancode exactly like a physical key.
+  void (*press_key)(void* context, std::uint32_t scancode) = nullptr;
+};
+
+// Installs the process-wide host. Passing nullptr clears it.
+void SetVirtualKeyboardHost(const VirtualKeyboardHost* host);
+VirtualKeyboardHost CurrentVirtualKeyboardHost();
+
+// The focused TextBox's current contents, shown in the panel's text field.
+// The desktop draws TextBox text as a window overlay that never reaches the
+// eye images, so the headset would otherwise show an empty box. Safe from any
+// thread; the text is sensitive and is never logged.
+struct VirtualKeyboardText {
+  std::string utf8;
+  int cursor_utf16 = 0;
+  bool password = false;
+  std::uint64_t revision = 0;
+};
+void SetVirtualKeyboardText(const char* utf8, std::size_t size,
+                            int cursor_utf16, bool password);
+void ClearVirtualKeyboardText();
+VirtualKeyboardText CurrentVirtualKeyboardText();
+
+enum class VirtualKeyAction {
+  kText,       // commits text, or shift_text under Shift/Caps Lock
+  kBackspace,
+  kEnter,
+  kTab,
+  kShift,      // one-shot
+  kCapsLock,
+  kSpace,
+  kClose,      // Escape: leaves the TextBox and hides the panel
+};
+
+struct VirtualKey {
+  std::string label;
+  std::string text;        // committed text for kText
+  std::string shift_text;  // committed under Shift (Caps Lock for letters)
+  VirtualKeyAction action = VirtualKeyAction::kText;
+  // Panel UV rectangle, origin top-left, both axes 0..1.
+  float u0 = 0.f, v0 = 0.f, u1 = 0.f, v1 = 0.f;
+};
+
+// One controller's pointing state for a frame. Positions are metres in the
+// OpenXR LOCAL space; the ray points along the aim pose's -Z axis.
+struct VirtualKeyboardPointer {
+  bool valid = false;
+  pose::Pose aim{};
+  float trigger = 0.f;  // 0..1
+};
+
+// What the keyboard asks the host to do after an Update.
+struct VirtualKeyboardOutput {
+  std::vector<std::string> text;          // committed in order
+  std::vector<std::uint32_t> scancodes;   // pressed in order, after text
+};
+
+// Ray/quad intersection. The quad is centred on `quad` with its face along
+// +Z, `width` x `height` metres. Returns false when the ray misses or points
+// away. u/v are panel UVs (origin top-left).
+bool IntersectVirtualKeyboardPanel(const pose::Pose& quad, float width,
+                                   float height, const pose::Pose& aim,
+                                   float* u, float* v, float* distance);
+
+// Pure keyboard state machine: layout, paging, shift, hover, trigger edges and
+// backspace auto-repeat. No OpenXR, Vulkan or SDL types, so it is unit-tested
+// directly.
+class VirtualKeyboard {
+ public:
+  // A text field over 15 x 5 normal-key units, 4 cm per unit.
+  static constexpr float kPanelWidthMetres = 0.60f;
+  static constexpr float kPanelHeightMetres = 0.248f;
+  // Texture aspect matches the panel so keys are not stretched.
+  static constexpr int kTextureWidth = 1500;
+  static constexpr int kTextureHeight = 620;
+  // Top share of the panel holding the text field; keys fill the rest.
+  static constexpr float kFieldFraction = 120.f / 620.f;
+
+  VirtualKeyboard();
+
+  // Opens the panel in front of `head` (LOCAL space), below eye level and
+  // tilted up toward the viewer. Resets Shift and hover; keeps Caps Lock.
+  void Show(const pose::Pose& head);
+  void Hide();
+  bool visible() const { return visible_; }
+  const pose::Pose& panel_pose() const { return panel_; }
+
+  // Text shown in the field. Bumps the revision only when it changed.
+  void SetText(const VirtualKeyboardText& text);
+  const std::string& text() const { return text_.utf8; }
+  int text_cursor_utf16() const { return text_.cursor_utf16; }
+  bool text_password() const { return text_.password; }
+
+  // Processes one frame of both pointers. now_ns is monotonic.
+  VirtualKeyboardOutput Update(std::uint64_t now_ns,
+                               const VirtualKeyboardPointer (&pointers)[2]);
+
+  // True when this hand's trigger belongs to the keyboard this frame (aimed
+  // at the panel, or a press that began on it is still held, including after
+  // the panel hid mid-press). The backend withholds that trigger from Roblox
+  // so a key press is not also a click.
+  bool CapturesTrigger(int hand) const;
+
+  // Current layout, with Shift/Caps Lock applied to the labels.
+  const std::vector<VirtualKey>& keys() const;
+  // -1 when the hand is not over a key.
+  int hovered_key(int hand) const { return hands_[hand & 1].hovered; }
+  int pressed_key(int hand) const { return hands_[hand & 1].pressed; }
+  // Pointer position on the panel, when the hand is over it.
+  bool cursor(int hand, float* u, float* v) const;
+  bool shifted() const { return shift_; }
+  bool caps_lock() const { return caps_lock_; }
+
+  // Advances whenever anything visible changes; the backend re-rasterizes
+  // and re-uploads only when this moves.
+  std::uint64_t revision() const { return revision_; }
+
+ private:
+  struct Hand {
+    int hovered = -1;
+    int pressed = -1;   // key under an active press, -1 otherwise
+    bool trigger_down = false;
+    bool captured = false;
+    bool over_panel = false;
+    float u = 0.f, v = 0.f;
+    std::uint64_t repeat_at_ns = 0;
+  };
+
+  void RebuildLayout();
+  int KeyAt(float u, float v) const;
+  std::string Output(const VirtualKey& key) const;
+  void Activate(const VirtualKey& key, VirtualKeyboardOutput* output);
+  void Touch() { ++revision_; }
+
+  bool visible_ = false;
+  bool shift_ = false;
+  bool caps_lock_ = false;
+  pose::Pose panel_{};
+  VirtualKeyboardText text_;
+  Hand hands_[2];
+  // A press the keyboard owned when it hid; held until that trigger releases.
+  bool release_pending_[2] = {false, false};
+  std::uint64_t cursor_drawn_ns_ = 0;
+  std::vector<VirtualKey> keys_;
+  std::uint64_t revision_ = 1;
+};
+
+// Draws the keyboard into a tightly packed RGBA8 buffer
+// (VirtualKeyboard::kTextureWidth x kTextureHeight, sRGB-encoded, opaque).
+// Glyphs come from SDL3_ttf with fontconfig's sans fallback chain and are
+// cached per label, so redraws after the first are plain fills and blits.
+class VirtualKeyboardRasterizer {
+ public:
+  VirtualKeyboardRasterizer();
+  ~VirtualKeyboardRasterizer();
+  VirtualKeyboardRasterizer(const VirtualKeyboardRasterizer&) = delete;
+  VirtualKeyboardRasterizer& operator=(const VirtualKeyboardRasterizer&) =
+      delete;
+
+  // Returns false when no font could be opened; keys still draw, unlabelled.
+  bool Draw(const VirtualKeyboard& keyboard, std::vector<std::uint8_t>* rgba);
+
+ private:
+  struct Impl;
+  Impl* impl_ = nullptr;
+};
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_VIRTUAL_KEYBOARD_H_

include/mocktail/vr/vr_mirror.h

@@ -0,0 +1,105 @@
+#ifndef MOCKTAIL_VR_MIRROR_H_
+#define MOCKTAIL_VR_MIRROR_H_
+
+#include <vulkan/vulkan.h>
+
+#include <cstdint>
+#include <string>
+
+#include "mocktail/vr/vr_mirror_shm.h"
+
+namespace mocktail::vr {
+
+// The subset of device/instance procs the mirror needs, supplied by the XR
+// backend from its already-resolved guest-device table. Keeping this explicit
+// avoids a second proc table and keeps the mirror independently testable.
+struct MirrorVkProcs {
+  PFN_vkCreateBuffer CreateBuffer = nullptr;
+  PFN_vkDestroyBuffer DestroyBuffer = nullptr;
+  PFN_vkGetBufferMemoryRequirements GetBufferMemoryRequirements = nullptr;
+  PFN_vkAllocateMemory AllocateMemory = nullptr;
+  PFN_vkFreeMemory FreeMemory = nullptr;
+  PFN_vkBindBufferMemory BindBufferMemory = nullptr;
+  PFN_vkMapMemory MapMemory = nullptr;
+  PFN_vkUnmapMemory UnmapMemory = nullptr;
+  PFN_vkCmdCopyImageToBuffer CmdCopyImageToBuffer = nullptr;
+  PFN_vkCmdPipelineBarrier CmdPipelineBarrier = nullptr;
+  PFN_vkGetPhysicalDeviceMemoryProperties GetPhysicalDeviceMemoryProperties =
+      nullptr;
+};
+
+// Producer side of the desktop two-eye mirror. Maps a POSIX shared-memory
+// segment (created with the name from MOCKTAIL_VR_MIRROR_SHM) and publishes
+// the latest complete eye pair under a seqlock. It owns two persistent,
+// bounded host-visible staging buffers reused across frames; the GPU->staging
+// copies are recorded into the caller's single batched command buffer so the
+// mirror adds no extra queue submission or fence wait.
+//
+// The mirror never touches the filesystem on the frame path and keeps only the
+// newest pair (one latest slot), so a slow consumer drops rather than queues
+// old frames.
+class VrMirror {
+ public:
+  VrMirror() = default;
+  ~VrMirror();
+  VrMirror(const VrMirror&) = delete;
+  VrMirror& operator=(const VrMirror&) = delete;
+
+  bool enabled() const { return mapping_ != nullptr; }
+
+  // Opens the shared segment. Returns false (and stays disabled) when the name
+  // is empty or mapping fails; the XR path then runs without a mirror.
+  bool Open(const std::string& shm_name, std::uint32_t width,
+            std::uint32_t height, std::string* error);
+  void Close();
+
+  // Ensures the two staging buffers match width*height*4 bytes on this device.
+  // Allocates once; a size/device change recreates them. Existing contents are
+  // discarded on resize.
+  bool EnsureStaging(const MirrorVkProcs& vk, VkDevice device,
+                     VkPhysicalDevice physical, std::uint32_t width,
+                     std::uint32_t height, std::string* error);
+  void DestroyStaging(const MirrorVkProcs& vk);
+
+  // Records a source-eye -> staging-buffer copy for one eye into cmd, adding
+  // the layout barriers around it. The source is returned to final_layout so
+  // the next guest render pass sees it unchanged.
+  void RecordEyeCopy(const MirrorVkProcs& vk, VkCommandBuffer cmd, int eye,
+                     VkImage source, VkImageLayout final_layout,
+                     std::uint32_t width, std::uint32_t height);
+
+  // After the batched fence wait completed, copies both staging buffers into
+  // the shared segment and bumps the seqlock with the frame id and a monotonic
+  // timestamp. No-op when staging does not cover width*height.
+  void Publish(std::uint64_t frame, VkFormat format, std::uint32_t width,
+               std::uint32_t height, std::uint64_t now_ns);
+
+  std::uint64_t published_pairs() const { return published_pairs_; }
+  std::uint32_t staging_width() const { return staging_width_; }
+  std::uint32_t staging_height() const { return staging_height_; }
+  const void* mapping() const { return mapping_; }
+
+  // Test seam: publish a pair from caller-supplied staging bytes without any
+  // Vulkan resources, exercising the same seqlock/segment write as the GPU
+  // path. Both buffers must hold width*height*4 bytes.
+  void PublishFromBytesForTest(std::uint64_t frame, VkFormat format,
+                               std::uint32_t width, std::uint32_t height,
+                               std::uint64_t now_ns, const void* eye0,
+                               const void* eye1);
+
+ private:
+  void* mapping_ = nullptr;
+  std::uint64_t mapping_bytes_ = 0;
+  std::string shm_name_;
+  VkBuffer staging_[2] = {VK_NULL_HANDLE, VK_NULL_HANDLE};
+  VkDeviceMemory staging_memory_[2] = {VK_NULL_HANDLE, VK_NULL_HANDLE};
+  void* staging_map_[2] = {nullptr, nullptr};
+  std::uint32_t staging_width_ = 0;
+  std::uint32_t staging_height_ = 0;
+  VkDevice staging_device_ = VK_NULL_HANDLE;
+  std::uint64_t published_pairs_ = 0;
+};
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_MIRROR_H_

include/mocktail/vr/vr_mirror_shm.h

@@ -0,0 +1,42 @@
+#ifndef MOCKTAIL_VR_MIRROR_SHM_H_
+#define MOCKTAIL_VR_MIRROR_SHM_H_
+
+#include <cstdint>
+
+namespace mocktail::vr {
+
+// Shared-memory transport for the desktop two-eye mirror. The producer (XR
+// backend, inside the client process) publishes the latest complete eye pair
+// under a seqlock; the consumer (desktop viewer) reads the newest pair without
+// any per-frame filesystem transport, image encode/decode, or allocation.
+//
+// Layout is fixed and little-endian.
+// sizeof(VrMirrorHeader) == kVrMirrorHeaderBytes.
+struct VrMirrorHeader {
+  std::uint32_t magic;          // kVrMirrorMagic
+  std::uint32_t header_bytes;   // kVrMirrorHeaderBytes (pixel area offset)
+  std::uint64_t seq;            // seqlock: odd while writing, even when stable
+  std::uint64_t frame;          // XR frame id the pair belongs to
+  std::uint32_t width;          // eye width in pixels
+  std::uint32_t height;         // eye height in pixels
+  std::uint32_t format;         // VkFormat of the source eye images
+  std::uint32_t flags;          // bit0: a complete, valid pair is present
+  std::uint64_t producer_ns;    // CLOCK_MONOTONIC publish timestamp
+  std::uint64_t published_pairs;
+  std::uint64_t reserved;
+};
+
+inline constexpr std::uint32_t kVrMirrorMagic = 0x3152564D;  // 'MVR1'
+inline constexpr std::uint32_t kVrMirrorHeaderBytes = 64;
+inline constexpr std::uint32_t kVrMirrorFlagValid = 1u << 0;
+
+// Total mapped bytes for a given eye extent (header + two RGBA/BGRA images).
+inline std::uint64_t VrMirrorBytes(std::uint32_t width, std::uint32_t height) {
+  return static_cast<std::uint64_t>(kVrMirrorHeaderBytes) +
+         2ull * static_cast<std::uint64_t>(width) *
+             static_cast<std::uint64_t>(height) * 4ull;
+}
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_MIRROR_SHM_H_

include/mocktail/vr/vr_perf.h

@@ -0,0 +1,103 @@
+#ifndef MOCKTAIL_VR_PERF_H_
+#define MOCKTAIL_VR_PERF_H_
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace mocktail::vr::perf {
+
+// Opt-in, low-overhead stage timing and counter instrumentation. Collection is
+// compiled out at runtime unless MOCKTAIL_VR_PERF is set, so the steady-state
+// path only pays a single cached boolean test per record.
+bool Enabled();
+
+enum class Stage {
+  kFrameCycle,
+  kXrWaitFrame,
+  kXrBeginFrame,
+  kXrLocateViews,
+  kSwapchainAcquire,
+  kSwapchainWait,
+  kCopyRecord,
+  kCopySubmit,
+  kCopyFenceWait,
+  kMirrorPublish,
+  kEvidence,
+  kControllerSync,
+  kPresentDependencies,
+  kDesktopMirror,
+  kPresentPrepare,
+  kPresentInterval,
+  kStageCount,
+};
+
+enum class Counter {
+  kPresents,
+  kFramesBegun,
+  kFramesSubmitted,
+  kFramesSkipped,
+  kSkipShouldRender,
+  kSkipPoseInvalid,
+  kSkipEyesUnbound,
+  kSkipEyeFrameMismatch,
+  kSubmits,
+  kFenceWaits,
+  kMirrorPairs,
+  kMirrorDrops,
+  kSkipVisibilityLost,
+  kReferenceSpaceChanges,
+  kVisibilityLost,
+  kVisibilityGained,
+  kFramesInvalidated,
+  kControllerSyncs,
+  kCounterCount,
+};
+
+const char* StageName(Stage stage);
+const char* CounterName(Counter counter);
+
+// Bounded reservoir per stage: the most recent N samples are kept and ranked
+// only when a report is emitted (once per interval), never on the frame path.
+class Collector {
+ public:
+  static constexpr std::size_t kReservoir = 4096;
+  static constexpr std::uint64_t kIntervalNs = 1'000'000'000ULL;
+
+  void Record(Stage stage, std::uint64_t nanos);
+  void Count(Counter counter, std::uint64_t delta = 1);
+
+  // Emits one distribution line per active stage plus a counter line when at
+  // least kIntervalNs elapsed since the previous emission. Cheap no-op
+  // otherwise. now_ns is a CLOCK_MONOTONIC timestamp supplied by the caller so
+  // the collector stays clock-agnostic and testable.
+  void EmitIfDue(std::uint64_t now_ns, const char* context);
+
+  // Test/inspection accessors.
+  std::uint64_t counter(Counter counter_id) const;
+  std::vector<std::uint64_t> Percentiles(Stage stage) const;  // p50,p95,p99,max
+  std::size_t Samples(Stage stage) const;
+  void Reset();
+
+ private:
+  struct StageStat {
+    std::vector<std::uint64_t> samples;  // ring, bounded by kReservoir
+    std::size_t head = 0;
+    std::size_t count = 0;
+    std::uint64_t total_ns = 0;
+  };
+  StageStat stages_[static_cast<std::size_t>(Stage::kStageCount)]{};
+  std::uint64_t counters_[static_cast<std::size_t>(Counter::kCounterCount)]{};
+  std::uint64_t last_emit_ns_ = 0;
+  std::uint64_t window_start_ns_ = 0;
+};
+
+// Process-wide collector used by the XR backend frame cycle.
+Collector& ProcessCollector();
+
+// Monotonic nanoseconds (CLOCK_MONOTONIC), 0 on failure.
+std::uint64_t NowNs();
+
+}  // namespace mocktail::vr::perf
+
+#endif  // MOCKTAIL_VR_PERF_H_

include/mocktail/vr/vr_pose_math.h

@@ -0,0 +1,217 @@
+#ifndef MOCKTAIL_VR_POSE_MATH_H_
+#define MOCKTAIL_VR_POSE_MATH_H_
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+
+namespace mocktail::vr::pose {
+
+// Coordinate spaces and units used across the whole camera path, documented so
+// every stage is auditable:
+//
+//   OpenXR head/views  metres, right-handed, +Y up, -Z forward, LOCAL space
+//     -> published pose  metres, quaternion (x, y, z, w), unchanged units
+//     -> guest state     metres; the exact-build native helper converts metres
+//                        to studs itself (factor 10/3). This layer must never
+//                        pre-apply that scale.
+//     -> camera          engine composes
+//                        out.rotation = base.rotation * head.rotation
+//                        out.position = base.position
+//                                       + base.rotation * head.position * HeadScale
+//                        where HeadScale is an engine value distinct from the
+//                        metres-to-studs conversion factor.
+//     -> render          one pass per eye using the per-eye offset/FOV
+//     -> XR submission   metres again, the very pose used to render the pair.
+
+struct Vec3 {
+  float x = 0.f, y = 0.f, z = 0.f;
+};
+
+struct Quat {
+  float x = 0.f, y = 0.f, z = 0.f, w = 1.f;
+};
+
+struct Pose {
+  Vec3 position{};
+  Quat orientation{};
+};
+
+inline constexpr float kPi = 3.14159265358979323846f;
+
+inline Quat QuatMultiply(const Quat& a, const Quat& b) {
+  return Quat{
+      a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+      a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+      a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
+      a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
+  };
+}
+
+inline Quat QuatConjugate(const Quat& q) { return Quat{-q.x, -q.y, -q.z, q.w}; }
+
+inline float QuatNorm(const Quat& q) {
+  return std::sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w);
+}
+
+// Returns false for a non-finite or near-zero quaternion; the output is left
+// untouched in that case so callers never publish a fabricated rotation.
+inline bool QuatNormalize(const Quat& in, Quat* out) {
+  if (out == nullptr) {
+    return false;
+  }
+  if (!std::isfinite(in.x) || !std::isfinite(in.y) || !std::isfinite(in.z) ||
+      !std::isfinite(in.w)) {
+    return false;
+  }
+  const float norm = QuatNorm(in);
+  if (!(norm > 1e-6f) || !std::isfinite(norm)) {
+    return false;
+  }
+  const float inverse = 1.f / norm;
+  *out = Quat{in.x * inverse, in.y * inverse, in.z * inverse, in.w * inverse};
+  return true;
+}
+
+// q and -q denote the same rotation. Used to prove the path is sign-invariant.
+inline bool QuatSameRotation(const Quat& a, const Quat& b, float tolerance) {
+  const float dot = a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
+  return std::abs(std::abs(dot) - 1.f) <= tolerance;
+}
+
+inline Vec3 QuatRotate(const Quat& q, const Vec3& v) {
+  // t = 2 * cross(q.xyz, v); v' = v + q.w * t + cross(q.xyz, t)
+  const Vec3 u{q.x, q.y, q.z};
+  const Vec3 cross1{u.y * v.z - u.z * v.y, u.z * v.x - u.x * v.z,
+                    u.x * v.y - u.y * v.x};
+  const Vec3 t{2.f * cross1.x, 2.f * cross1.y, 2.f * cross1.z};
+  const Vec3 cross2{u.y * t.z - u.z * t.y, u.z * t.x - u.x * t.z,
+                    u.x * t.y - u.y * t.x};
+  return Vec3{v.x + q.w * t.x + cross2.x, v.y + q.w * t.y + cross2.y,
+              v.z + q.w * t.z + cross2.z};
+}
+
+// result = a * b in SE(3): apply b first, then a.
+inline Pose PoseMultiply(const Pose& a, const Pose& b) {
+  Pose result;
+  result.orientation = QuatMultiply(a.orientation, b.orientation);
+  const Vec3 rotated = QuatRotate(a.orientation, b.position);
+  result.position = Vec3{a.position.x + rotated.x, a.position.y + rotated.y,
+                         a.position.z + rotated.z};
+  return result;
+}
+
+inline Pose PoseInverse(const Pose& p) {
+  Pose result;
+  result.orientation = QuatConjugate(p.orientation);
+  const Vec3 neg{-p.position.x, -p.position.y, -p.position.z};
+  result.position = QuatRotate(result.orientation, neg);
+  return result;
+}
+
+// Rotation for a head turned by yaw about +Y then pitched about +X, matching
+// the scripted diagnostic motion. Quaternion order is (x, y, z, w).
+inline Quat QuatFromYawPitch(float yaw, float pitch) {
+  const float cy = std::cos(yaw * 0.5f), sy = std::sin(yaw * 0.5f);
+  const float cp = std::cos(pitch * 0.5f), sp = std::sin(pitch * 0.5f);
+  return Quat{cy * sp, sy * cp, -sy * sp, cy * cp};
+}
+
+inline Quat QuatFromAxisAngle(const Vec3& axis, float angle) {
+  const float half = angle * 0.5f;
+  const float s = std::sin(half);
+  return Quat{axis.x * s, axis.y * s, axis.z * s, std::cos(half)};
+}
+
+// Per-eye FOV as the runtime reports it: angleLeft, angleRight, angleUp,
+// angleDown in radians, each signed relative to the eye's forward axis.
+struct EyeFov {
+  float angle_left = 0.f;
+  float angle_right = 0.f;
+  float angle_up = 0.f;
+  float angle_down = 0.f;
+};
+
+// The guest state stores projection tangents, not angles. The 2998 layout is
+// up, down, left, right in that order; down/left are negated because the
+// guest's tangent space measures them in the opposite direction. Getting this
+// order or a sign wrong flips or shears the image, so it is pinned by test.
+struct ProjectionTangents {
+  float up = 0.f;
+  float down = 0.f;
+  float left = 0.f;
+  float right = 0.f;
+};
+
+inline ProjectionTangents FovToTangents(const EyeFov& fov) {
+  return ProjectionTangents{std::tan(fov.angle_up), std::tan(-fov.angle_down),
+                            std::tan(-fov.angle_left), std::tan(fov.angle_right)};
+}
+
+inline constexpr float kMaxEyeFovAngle = 1.56f;
+
+// Enclose the display frustum in a head-parallel camera for the guest renderer.
+// The compositor receives this rendered FOV and pose, not the canted display's.
+inline bool ParallelEyeFov(const Quat& eye_orientation, const EyeFov& display,
+                           EyeFov* rendered) {
+  Quat orientation;
+  if (!rendered || !QuatNormalize(eye_orientation, &orientation) ||
+      !(display.angle_left < display.angle_right) ||
+      !(display.angle_down < display.angle_up)) {
+    return false;
+  }
+  const float angles[] = {display.angle_left, display.angle_right,
+                          display.angle_up, display.angle_down};
+  for (float angle : angles) {
+    if (!std::isfinite(angle) || std::abs(angle) >= kMaxEyeFovAngle)
+      return false;
+  }
+  if (orientation.x == 0.f && orientation.y == 0.f && orientation.z == 0.f) {
+    *rendered = display;
+    return true;
+  }
+  const float xs[] = {std::tan(display.angle_left),
+                      std::tan(display.angle_right)};
+  const float ys[] = {std::tan(display.angle_down), std::tan(display.angle_up)};
+  float left = 0.f, right = 0.f, down = 0.f, up = 0.f;
+  bool first = true;
+  for (float x : xs) {
+    for (float y : ys) {
+      const Vec3 ray = QuatRotate(orientation, {x, y, -1.f});
+      if (!std::isfinite(ray.z) || ray.z >= -1e-6f) return false;
+      const float horizontal = ray.x / -ray.z;
+      const float vertical = ray.y / -ray.z;
+      if (!std::isfinite(horizontal) || !std::isfinite(vertical)) return false;
+      if (first) {
+        left = right = horizontal;
+        down = up = vertical;
+        first = false;
+      } else {
+        left = std::min(left, horizontal);
+        right = std::max(right, horizontal);
+        down = std::min(down, vertical);
+        up = std::max(up, vertical);
+      }
+    }
+  }
+  const EyeFov result{std::atan(left), std::atan(right), std::atan(up),
+                      std::atan(down)};
+  const float bounds[] = {result.angle_left, result.angle_right,
+                          result.angle_up, result.angle_down};
+  for (float angle : bounds) {
+    if (std::abs(angle) >= kMaxEyeFovAngle) return false;
+  }
+  *rendered = result;
+  return true;
+}
+
+// Metres-to-studs factor the exact-build native helper applies itself. Exposed
+// only so tests can prove this layer does NOT pre-apply it.
+inline constexpr float kMetresToStuds = 10.f / 3.f;
+
+// Expected stud value for a metre offset, for numerical unit checks.
+inline float MetresToStuds(float metres) { return metres * kMetresToStuds; }
+
+}  // namespace mocktail::vr::pose
+
+#endif  // MOCKTAIL_VR_POSE_MATH_H_

include/mocktail/vr/xr_actions.h

@@ -0,0 +1,104 @@
+#ifndef MOCKTAIL_VR_XR_ACTIONS_H_
+#define MOCKTAIL_VR_XR_ACTIONS_H_
+
+#include <cstdint>
+#include <string>
+
+#include "mocktail/status.h"
+#include "mocktail/vr/vr_pose_math.h"
+#include "mocktail/vr/xr_controller.h"
+
+namespace mocktail::vr {
+
+// Session-owned OpenXR action layer: one action set, left/right subactions,
+// grip+aim pose spaces, and interaction-profile bindings for Touch (primary),
+// Quest 2, Index, Vive wands and the simple controller. All XR handles stay
+// opaque here so non-OpenXR consumers (bridge, tests) need no XR headers.
+//
+// Frame contract: Sync() runs exactly once per frame from the backend frame
+// cycle, immediately after xrWaitFrame returned the predicted display time and
+// before the guest renders, so located hand poses share the head/eye frame.
+// There is no second frame wait and no polling from guest getters.
+class XrActions final {
+public:
+  XrActions() = default;
+  ~XrActions();
+  XrActions(const XrActions &) = delete;
+  XrActions &operator=(const XrActions &) = delete;
+
+  // Creates the action set/actions and suggests bindings. Instance-level:
+  // valid before any session exists. Failure is non-fatal for XR output; the
+  // backend logs and continues without controller input.
+  Status Create(void *xr_instance, bool enable_eye_gaze=false);
+  struct EyeGazePose {float orientation[4]={0,0,0,1};bool valid=false;std::uint64_t frame=0;};
+  const EyeGazePose& eye_gaze() const {return eye_gaze_;}
+
+  // Attaches to a session and creates the per-hand pose spaces. Must be
+  // called after xrCreateSession and before the first Sync; recreated on every
+  // session replacement (no stale handles survive).
+  Status Attach(void *xr_instance, void *xr_session, void *xr_local_space);
+
+  // Destroys spaces and detaches; the action set survives for reattach.
+  void Detach();
+  void Destroy();
+
+  bool attached() const { return attached_; }
+
+  // One per-frame sync at predicted_display_time. Locates grip and aim poses
+  // in the session's LOCAL space, reads analog/boolean states, refreshes
+  // connection state from the runtime's current interaction profile, and
+  // builds the coherent snapshot + delivery batch. Returns false when actions
+  // are unavailable (runtime refused sync); input is reset and a disconnect
+  // remains drainable even while the session is detached.
+  bool Sync(void *xr_session, std::uint64_t predicted_display_time,
+            std::uint64_t frame, std::uint64_t session_generation);
+
+  // Latest coherent snapshot (frame/session generation tagged).
+  const ControllerSnapshot &snapshot() const { return snapshot_; }
+  // Hand poses in metres/LOCAL space for the state-copy records.
+  const VrHandPose &hand(int index) const { return hands_[index & 1]; }
+
+  // Drains the next pending delivery batch built by Sync. Returns false when
+  // nothing is queued. Thread-safe: Sync runs on the render thread, the drain
+  // runs on the window thread. Backed by a bounded queue, so a slow consumer
+  // drops oldest frames and converges via resync rather than growing.
+  bool TakeDelivery(ControllerDelivery *out);
+
+  // Queues a vibration request for one hand. Safe from any thread; applied on
+  // the next Sync's XR call window. amplitude [0,1], duration in nanoseconds
+  // (0 = runtime default). A newer request for the same hand replaces the
+  // pending one. StopHaptics cancels.
+  void RequestHaptics(int hand, float amplitude, std::uint64_t duration_ns,
+                      float frequency_hz);
+
+  void StopHaptics(int hand);
+
+  // Interaction-profile diagnostics (refreshed on profile-change events and
+  // every Sync that observes a change).
+  std::string ActiveProfile(int hand) const;
+
+  // Test seam: publish an externally sourced profile name (event dispatch in
+  // the backend) without XR calls.
+  void NoteProfileChanged();
+
+  // Called by the backend on focus/session loss, under controller ownership.
+  void ResetInput();
+
+private:
+  struct Impl;
+  Impl *impl_ = nullptr;
+  bool created_ = false;
+  bool attached_ = false;
+  ControllerStateBuilder builder_;
+  ControllerSnapshot snapshot_;
+  VrHandPose hands_[2];
+  EyeGazePose eye_gaze_;
+  ControllerDeliveryQueue delivery_queue_;
+  std::uint64_t session_generation_ = 0;
+  // Last connection level handed to the consumer, to mark connection changes.
+  bool last_delivered_connected_[2] = {false, false};
+};
+
+} // namespace mocktail::vr
+
+#endif // MOCKTAIL_VR_XR_ACTIONS_H_

include/mocktail/vr/xr_controller.h

@@ -0,0 +1,236 @@
+#ifndef MOCKTAIL_VR_XR_CONTROLLER_H_
+#define MOCKTAIL_VR_XR_CONTROLLER_H_
+
+#include "mocktail/vr/xr_controller_abi.h"
+#include <array>
+#include <cstdint>
+#include <deque>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace mocktail::vr {
+
+// One tracked controller hand, located at the same predicted display time as
+// the head. Grip is the held-object pose; aim is the pointing pose. They are
+// not interchangeable: the guest consumes grip for hands/tools and aim for UI
+// rays. Position is metres, orientation a quaternion (x, y, z, w) in the
+// OpenXR LOCAL reference space. The guest applies its own metres-to-studs
+// conversion and hand pitch offset, so neither is pre-applied here.
+struct VrHandPose {
+  float grip_position[3] = {0.f, 0.f, 0.f};
+  float grip_orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  float aim_position[3] = {0.f, 0.f, 0.f};
+  float aim_orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  // Pose validity, reported separately from button activity and connection so
+  // a controller can be connected with an untracked pose.
+  bool grip_valid = false;
+  bool aim_valid = false;
+};
+
+// Engine-facing controller capability, independent of which OpenXR
+// interaction profile supplied it. The guest receives buttons and analog axes
+// through its verified Android gamepad route, so this layer normalizes every
+// supported profile onto that one stable contract.
+enum class ControllerButton {
+  kTrigger,    // analog click semantics; value reported separately
+  kSqueeze,    // grip/squeeze
+  kThumbstick, // stick click
+  kFaceNorth,  // right B / left Y
+  kFaceSouth,  // right A / left X
+  kFaceEast,   // right B equivalent on layouts that have it
+  kFaceWest,   // left X equivalent
+  kMenu,       // application-accessible menu only; never a system button
+  kCount,
+};
+
+// Capacitive contacts are distinct from presses. Some runtimes/profiles do
+// not expose them; active=false means unavailable, not an inferred contact.
+enum class ControllerTouch {
+  kTrigger,
+  kThumbstick,
+  kThumbrest,
+  kA,
+  kB,
+  kX,
+  kY,
+  kCount
+};
+
+enum class ControllerAxis {
+  kTrigger,     // 0..1
+  kSqueeze,     // 0..1
+  kThumbstickX, // -1..1
+  kThumbstickY, // -1..1
+  kCount,
+};
+
+// Analog trigger/squeeze thresholds used only where the runtime exposes a
+// boolean click for an analog control. Hysteresis prevents edge chattering at
+// the boundary; native analog values are always preserved alongside it.
+struct AnalogClickThresholds {
+  float press = 0.75f;
+  float release = 0.6f;
+};
+
+// One coherent per-frame controller snapshot. Built once per frame by the
+// backend after a single xrSyncActions, then read by native getters without
+// re-polling. Button booleans are level state; edge detection happens once, at
+// publish time, so repeated native getters never emit duplicate edges.
+struct ControllerHandState {
+  bool connected = false;
+  bool pose_valid = false;
+  std::array<bool, static_cast<std::size_t>(ControllerTouch::kCount)> touches{};
+  std::array<bool, static_cast<std::size_t>(ControllerTouch::kCount)>
+      touch_active{};
+  std::array<bool, static_cast<std::size_t>(ControllerButton::kCount)>
+      buttons{};
+  std::array<float, static_cast<std::size_t>(ControllerAxis::kCount)> axes{};
+  // Interaction profile actually reported by the runtime for this hand, for
+  // diagnostics only (never used to gate input).
+  std::string profile;
+};
+
+struct ControllerSnapshot {
+  ControllerHandState hands[2]; // 0 = left, 1 = right
+  std::uint64_t frame = 0;
+  std::uint64_t session_generation = 0;
+};
+
+// Pure state machine: maps raw OpenXR action values onto the normalized
+// contract and derives edges exactly once per published frame. No OpenXR or
+// JNI types, so it is unit-testable with injected values.
+class ControllerStateBuilder {
+public:
+  explicit ControllerStateBuilder(AnalogClickThresholds thresholds = {});
+
+  // Records one raw action value for the given hand. Values not set by the
+  // runtime are neutral when explicitly marked inactive.
+  void SetTouch(int hand, ControllerTouch touch, bool value, bool active);
+  void SetButton(int hand, ControllerButton button, bool value, bool active);
+  void SetAxis(int hand, ControllerAxis axis, float value, bool active);
+  void SetConnected(int hand, bool connected);
+  void SetProfile(int hand, std::string profile);
+  void SetPoseValid(int hand, bool valid);
+
+  // Produces the snapshot for this frame and records which buttons changed so
+  // the caller can emit exactly one native edge per transition. frame must
+  // advance monotonically; publishing the same frame twice yields no edges.
+  struct Edge {
+    int hand = 0;
+    ControllerButton button = ControllerButton::kTrigger;
+    bool pressed = false;
+  };
+  ControllerSnapshot Publish(std::uint64_t frame, std::uint64_t generation,
+                             std::vector<Edge> *edges);
+
+  // Neutralizes all axes and releases held buttons once (focus loss,
+  // disconnect, session stop). Produces release edges for anything held so no
+  // button can stay stuck down.
+  void ReleaseAll(std::uint64_t frame, std::uint64_t generation,
+                  std::vector<Edge> *edges);
+
+  // Derives the click state for an analog control with hysteresis: latches on
+  // at `press`, off at `release`. Call after SetAxis for the same hand. Used
+  // for profiles that expose a trigger value without a click action; native
+  // analog values are always preserved regardless.
+  bool AnalogClick(int hand, ControllerAxis axis);
+
+  const ControllerSnapshot &snapshot() const { return snapshot_; }
+
+private:
+  AnalogClickThresholds thresholds_;
+  ControllerSnapshot snapshot_;
+  // Last published level per hand/button, used for edge detection.
+  std::array<
+      std::array<bool, static_cast<std::size_t>(ControllerButton::kCount)>, 2>
+      published_buttons_{};
+  // Hysteresis latch per (hand, analog control): [hand*2 + axis].
+  std::array<bool, 4> analog_latch_{};
+  bool have_published_ = false;
+};
+
+// Maps the normalized contract onto the guest's verified Android gamepad
+// identifiers, so XR controllers reuse the single authoritative input route
+// and cannot double-fire alongside a physical SDL gamepad. hand selects the
+// per-hand squeeze/thumbstick/trigger identifiers (0 = left, 1 = right).
+// Returns -1 when the control has no keycode (analog click).
+int32_t ControllerButtonToAndroidKey(int hand, ControllerButton button);
+// Returns the Android MotionEvent axis id for one axis of the given hand
+// (left/right trigger differ), or -1 when the control has no analog axis.
+int32_t ControllerAxisToAndroidAxis(int hand, ControllerAxis axis);
+// How many float components the guest expects for this axis (sticks 2, triggers
+// 1).
+int32_t ControllerAxisComponentCount(ControllerAxis axis);
+
+// SDL3 gamepad ordinals. XR controller delivery reuses the existing router
+// (RobloxInputRouter::HandleEvent) as the single authoritative event route:
+// the router performs the verified SDL->Android key/axis conversion, level
+// deduplication, focus gating and release-on-disconnect itself. Synthesized
+// platform events must therefore carry SDL ordinals, not Android codes.
+// hand selects the per-hand squeeze/thumbstick/trigger ordinals.
+int32_t ControllerButtonToSdlOrdinal(int hand, ControllerButton button);
+// SDL axis ordinal per hand for stick/trigger delivery; -1 when not an axis.
+// Left hand: LEFTX/LEFTY/TRIGGERLEFT; right: RIGHTX/RIGHTY/TRIGGERRIGHT.
+int32_t ControllerAxisToSdlOrdinal(int hand, ControllerAxis axis);
+
+// One drained delivery batch from the XR backend to the input route. Built
+// once per frame after xrSyncActions; edges appear exactly once. `resync`
+// requests full level re-delivery (recovery after queue overflow or an
+// unfocused drop) — the router deduplicates, so re-delivery is idempotent and
+// guarantees no button sticks down.
+struct ControllerDelivery {
+  std::uint64_t session_generation = 0;
+  bool button_levels[2][static_cast<std::size_t>(ControllerButton::kCount)] =
+      {};
+  bool connected[2] = {false, false};
+  bool connection_changed[2] = {false, false};
+  struct ButtonEdge {
+    int hand = 0;
+    ControllerButton button = ControllerButton::kTrigger;
+    bool pressed = false;
+  };
+  std::vector<ButtonEdge> edges;
+  // SDL ordinal order: LEFTX, LEFTY, RIGHTX, RIGHTY, TRIGGERLEFT, TRIGGERRIGHT.
+  float axes[6] = {0.f, 0.f, 0.f, 0.f, 0.f, 0.f};
+  bool axes_valid[2] = {false, false};
+  bool resync = false;
+  std::uint64_t frame = 0;
+
+  // Bounded growth guard: the backend caps the edge queue and sets resync
+  // instead of growing without limit.
+  static constexpr std::size_t kMaxEdges = 64;
+};
+
+bool EncodeNativeControllerChannels(const ControllerSnapshot &snapshot,
+                                    float (&channels)[28]);
+
+void EncodeControllerDelivery(const ControllerDelivery &delivery,
+                              MocktailVrControllerDelivery *out);
+
+// Thread-safe bounded queue between the XR render-thread producer (one push
+// per frame after xrSyncActions) and the window-thread consumer that drains
+// into the verified input route. Overflow drops the oldest frames and arms a
+// resync on the next delivered frame, so the consumer always converges to the
+// current levels and a full queue can never leave a button stuck down.
+class ControllerDeliveryQueue {
+public:
+  static constexpr std::size_t kCapacity = 8;
+
+  void Push(ControllerDelivery delivery);
+  bool Pop(ControllerDelivery *out);
+  std::size_t size() const;
+  bool overflowed() const { return overflowed_; }
+  std::uint64_t dropped_frames() const { return dropped_frames_; }
+  void Clear();
+
+private:
+  mutable std::mutex mutex_;
+  std::deque<ControllerDelivery> queue_;
+  bool overflowed_ = false;
+  std::uint64_t dropped_frames_ = 0;
+};
+
+} // namespace mocktail::vr
+
+#endif // MOCKTAIL_VR_XR_CONTROLLER_H_

include/mocktail/vr/xr_controller_abi.h

@@ -0,0 +1,76 @@
+#ifndef MOCKTAIL_VR_XR_CONTROLLER_ABI_H_
+#define MOCKTAIL_VR_XR_CONTROLLER_ABI_H_
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* Plain-C mirror of mocktail::vr::ControllerDelivery for crossing the
+ * dlsym module boundary (XR backend -> input runtime) without exporting C++
+ * types or requiring the consumer to link OpenXR. Field order and types are
+ * the ABI; both sides include this header. Keep it POD: no constructors, no
+ * std, fixed arrays only. */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define MOCKTAIL_VR_CONTROLLER_MAX_EDGES 64
+#define MOCKTAIL_VR_CONTROLLER_BUTTON_COUNT 8
+#define MOCKTAIL_VR_CONTROLLER_AXIS_COUNT 6
+
+/* Button indices: mirror mocktail::vr::ControllerButton enum order. */
+enum {
+  MOCKTAIL_VR_BUTTON_TRIGGER = 0,
+  MOCKTAIL_VR_BUTTON_SQUEEZE = 1,
+  MOCKTAIL_VR_BUTTON_THUMBSTICK = 2,
+  MOCKTAIL_VR_BUTTON_FACE_NORTH = 3,
+  MOCKTAIL_VR_BUTTON_FACE_SOUTH = 4,
+  MOCKTAIL_VR_BUTTON_FACE_EAST = 5,
+  MOCKTAIL_VR_BUTTON_FACE_WEST = 6,
+  MOCKTAIL_VR_BUTTON_MENU = 7
+};
+
+typedef struct MocktailVrControllerEdge {
+  int32_t hand;    /* 0 = left, 1 = right */
+  int32_t button;  /* MOCKTAIL_VR_BUTTON_* */
+  int32_t pressed; /* 0/1 */
+} MocktailVrControllerEdge;
+
+typedef struct MocktailVrControllerDelivery {
+  uint64_t frame;
+  uint64_t session_generation;
+  int32_t connected[2];
+  int32_t connection_changed[2];
+  /* Current button levels per hand (MOCKTAIL_VR_BUTTON_* order). Used for
+   * resync after queue overflow: the consumer re-delivers every level and the
+   * router's deduplication makes it idempotent. */
+  int32_t button_levels[2][MOCKTAIL_VR_CONTROLLER_BUTTON_COUNT];
+  /* Analog levels in SDL gamepad axis order:
+   * 0=LEFTX 1=LEFTY 2=RIGHTX 3=RIGHTY 4=TRIGGERLEFT 5=TRIGGERRIGHT. */
+  float axes[MOCKTAIL_VR_CONTROLLER_AXIS_COUNT];
+  int32_t axes_valid[2];
+  int32_t resync;
+  int32_t edge_count;
+  MocktailVrControllerEdge edges[MOCKTAIL_VR_CONTROLLER_MAX_EDGES];
+} MocktailVrControllerDelivery;
+
+/* Pops the next delivery batch produced by the XR backend's once-per-frame
+ * action sync. Returns 1 and fills *out when a batch was queued, 0 when the
+ * queue is empty or no XR controller layer is active. Inert (returns 0) in
+ * non-VR builds and while no backend is armed. */
+typedef int32_t (*MocktailVrControllerPopFn)(MocktailVrControllerDelivery *out);
+
+/* Queues a vibration request for one hand (0=left, 1=right). amplitude is
+ * clamped to [0,1]; duration_ns 0 means the runtime default. Safe from any
+ * thread; applied on the next XR sync. No-op when no controller layer is
+ * active. */
+typedef void (*MocktailVrControllerHapticsFn)(int32_t hand, float amplitude,
+                                              uint64_t duration_ns,
+                                              float frequency_hz);
+typedef void (*MocktailVrControllerStopHapticsFn)(int32_t hand);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MOCKTAIL_VR_XR_CONTROLLER_ABI_H_ */

include/mocktail/vr/xr_foveation_maps.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <vulkan/vulkan.h>
+#include "mocktail/status.h"
+
+namespace mocktail::vr {
+
+// Runtime-owned eye-tracked density maps. The unused control color images are
+// never submitted; ordinary output swapchains retain their transfer-copy path.
+// Caller serializes access and completes GPU use before EndFrame/Destroy.
+class XrFoveationMaps {
+ public:
+  XrFoveationMaps();
+  ~XrFoveationMaps();
+  XrFoveationMaps(const XrFoveationMaps&) = delete;
+  XrFoveationMaps& operator=(const XrFoveationMaps&) = delete;
+  Status Initialize(void* instance, std::uint64_t system, void* session,
+                    VkDevice device, PFN_vkGetDeviceProcAddr get_device_proc,
+                    std::uint32_t width, std::uint32_t height, VkFormat format);
+  bool BeginFrame();
+  void EndFrame();
+  void Destroy();
+  bool ready() const;
+  bool acquired() const;
+  bool tracking() const;
+  VkImageView view(int eye) const;
+  std::uint32_t width() const;
+  std::uint32_t height() const;
+  bool center(int eye, float* x, float* y) const;
+
+ private:
+  struct Impl;
+  std::unique_ptr<Impl> impl_;
+};
+}  // namespace mocktail::vr

include/runtime/asset_overlay_names.h

@@ -0,0 +1,27 @@
+#ifndef MOCKTAIL_RUNTIME_ASSET_OVERLAY_NAMES_H_
+#define MOCKTAIL_RUNTIME_ASSET_OVERLAY_NAMES_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <filesystem>
+#include <string>
+#include <vector>
+
+namespace mocktail {
+namespace runtime {
+
+// The rbxasset:// name of every regular file under <overlay_dir>/content, such
+// as rbxasset://textures/MouseLockedCursor.png. Sorted.
+std::vector<std::string> OverlayRbxAssetNames(
+    const std::filesystem::path& overlay_dir);
+
+// Roblox opens no local file for an rbxasset:// name it maps to a download.
+// Writes '!' over the first byte of each whole NUL-terminated copy of a name
+// in `data`, which unmaps it. Returns the number of copies changed.
+std::size_t DisableAssetNameMappings(std::uint8_t* data, std::size_t size,
+                                     const std::vector<std::string>& names);
+
+}
+}
+
+#endif

include/runtime/command_line.h

@@ -1,6 +1,7 @@
 #ifndef MOCKTAIL_RUNTIME_COMMAND_LINE_H_
 #define MOCKTAIL_RUNTIME_COMMAND_LINE_H_
 
+#include <optional>
 #include <string>
 #include <vector>
 
@@ -21,6 +22,7 @@ enum class WindowMode {
 struct CommandLineOptions {
   CommandMode mode = CommandMode::kRun;
   WindowMode window_mode = WindowMode::kUnspecified;
+  std::optional<bool> vr_enabled;
   std::string program_name = "mocktail";
   std::string roblox_library_path;
   std::string graphics_backend;
@@ -33,6 +35,8 @@ struct CommandLineOptions {
   // Requests one explicit launch of the provider latest without promoting it
   // into the managed payload state.
   bool force_run_latest = false;
+  // Chrome trace file the Vulkan adapter writes; empty when not profiling.
+  std::string profile_trace_path;
 };
 
 struct CommandLineParseResult {

include/runtime/discord_rpc.h

@@ -13,11 +13,14 @@ namespace mocktail {
 namespace runtime {
 
 struct DiscordRpcActivity {
+  std::string name;
   std::string details;
   std::string state;
   std::optional<int64_t> start_timestamp;
   std::string large_image;
   std::string large_text;
+  std::string small_image;
+  std::string small_text;
   std::string button_label;
   std::string button_url;
 };
@@ -27,7 +30,8 @@ std::string BuildDiscordJoinUrl(const RobloxExperienceLaunchRequest& request);
 DiscordRpcActivity BuildDiscordRpcActivity(
     const DiscordRpcConfig& config, RobloxExperiencePresencePhase phase,
     const RobloxExperienceLaunchRequest* request, std::string place_name,
-    int64_t session_started_at, std::string place_icon_url = {});
+    int64_t session_started_at, std::string place_icon_url = {},
+    std::string creator_name = {});
 
 // Maintains a direct, unauthenticated Discord Desktop RPC connection. The
 // worker owns all network and IPC work; lifecycle notifications only replace

include/runtime/engine_pump_rest.h

@@ -0,0 +1,65 @@
+#ifndef MOCKTAIL_RUNTIME_ENGINE_PUMP_REST_H_
+#define MOCKTAIL_RUNTIME_ENGINE_PUMP_REST_H_
+
+#include <cstdint>
+
+namespace mocktail::runtime {
+
+// The engine posts its per-frame main-thread step at a time of its own
+// choosing, with no signal the host can block on, so the host main thread
+// polls nativeCallMessagesFromMainThread. An empty poll costs a few
+// microseconds; polled back to back it burns a core.
+//
+// Between polls the thread rests for kEnginePumpRestNs. A post is then picked
+// up at most kEnginePumpRestNs + timer slack + wake latency late, far under
+// the engine's sub-millisecond slack.
+//
+// How it rests decides the clock. Under a power-saving governor the CPU clocks
+// a bursty core down unless some core stays awake, and the engine's render
+// thread then runs slower and drops frames. So:
+//   kSleep   nanosleep. The core idles. Correct only when the governor holds
+//            the clock up on its own (performance, which GameMode sets).
+//   kTpause  TPAUSE in C0.2. The core stays awake at reduced power, the clock
+//            holds, and the OS books the time as busy. Needs WAITPKG.
+//   kSpin    No rest. The core stays awake at full power.
+inline constexpr uint64_t kEnginePumpRestNs = 100'000;
+// Timer slack the calling thread is set to; the kernel default of 50 us would
+// otherwise stretch every sleep.
+inline constexpr uint64_t kEnginePumpTimerSlackNs = 10'000;
+// Shallow C-state exit plus scheduler latency on the host, for the bound.
+inline constexpr uint64_t kShallowWakeNs = 50'000;
+
+enum class EnginePumpRestMode { kSleep, kTpause, kSpin };
+
+const char* EnginePumpRestModeName(EnginePumpRestMode mode);
+
+struct EnginePumpRestInputs {
+  bool governor_performance = false;
+  bool cpu_has_waitpkg = false;
+  // MOCKTAIL_ENGINE_PUMP_REST: "sleep", "tpause" or "spin". Null, empty or
+  // unknown defers to the policy; "tpause" without WAITPKG does too.
+  const char* override = nullptr;
+};
+
+EnginePumpRestMode ChooseEnginePumpRestMode(const EnginePumpRestInputs& inputs);
+
+// True when the file holds "performance". `path` is a cpufreq
+// scaling_governor file; cpu0's stands for the machine.
+bool CpuGovernorIsPerformance(const char* path);
+
+bool CpuHasWaitPkg();
+
+// The mode chosen from the host on first use.
+EnginePumpRestMode ActiveEnginePumpRestMode();
+
+// Rests the calling thread in the given mode and returns the rest length, 0
+// for kSpin. The first call lowers the thread's timer slack to
+// kEnginePumpTimerSlackNs.
+uint64_t RestAfterEnginePump(EnginePumpRestMode mode);
+inline uint64_t RestAfterEnginePump() {
+  return RestAfterEnginePump(ActiveEnginePumpRestMode());
+}
+
+}  // namespace mocktail::runtime
+
+#endif  // MOCKTAIL_RUNTIME_ENGINE_PUMP_REST_H_

include/runtime/game_mode.h

@@ -1,6 +1,8 @@
 #ifndef MOCKTAIL_RUNTIME_GAME_MODE_H_
 #define MOCKTAIL_RUNTIME_GAME_MODE_H_
 
+#include <sched.h>
+
 #include <string>
 #include <string_view>
 
@@ -22,6 +24,7 @@ enum class GameModeSessionState {
   kDisabled,
   kUnavailable,
   kRequestFailed,
+  kDeclinedCorePinning,
   kAlreadyActive,
   kActive,
   kStopped,
@@ -43,9 +46,37 @@ struct GameModeClientApi {
   ErrorFn error_string = nullptr;
 };
 
+// The CPU affinity calls, injectable so tests exercise the restore without
+// moving the threads they run on.
+struct CpuAffinityApi {
+  // Reads the calling thread's permitted CPUs. GameMode pins every thread
+  // alike, so one thread's mask is enough to detect the pin.
+  using GetFn = int (*)(cpu_set_t* mask);
+  // Applies `mask` to every thread of this process, not only the caller.
+  // Returns 0 when each live thread took it.
+  using SetFn = int (*)(const cpu_set_t* mask);
+
+  GetFn get = nullptr;
+  SetFn set = nullptr;
+};
+
+CpuAffinityApi HostCpuAffinityApi();
+
+// True when `after` permits a strict subset of the CPUs `before` permits.
+// An equal, wider or merely relocated set is not a narrowing.
+bool CpuAffinityNarrowed(const cpu_set_t& before, const cpu_set_t& after);
+
 // Owns at most one ref-counted GameMode request. Missing host support and
 // daemon rejection remain nonfatal because GameMode is an optimization, not a
 // correctness dependency.
+//
+// GameMode pins the calling process to the host's fastest cores when it sees a
+// wide core-speed spread. Roblox spreads its own work over a worker pool, so
+// that pin concentrates the load onto a couple of cores instead of helping,
+// and the daemon re-applies it every few seconds, so correcting the mask in
+// place does not hold. Under `auto`, a request that narrows the affinity is
+// released again: ending the request is what releases the pin. `on` is an
+// explicit choice and keeps the pinned session.
 class GameModeSession final {
  public:
   GameModeSession() = default;
@@ -59,6 +90,8 @@ class GameModeSession final {
   static GameModeSession Start(GameModePolicy policy);
   static GameModeSession StartWithClientForTesting(
       GameModePolicy policy, GameModeClientApi api);
+  static GameModeSession StartWithClientForTesting(
+      GameModePolicy policy, GameModeClientApi api, CpuAffinityApi affinity);
 
   GameModeSessionState state() const { return state_; }
   const std::string& detail() const { return detail_; }
@@ -73,6 +106,7 @@ class GameModeSession final {
  private:
   static GameModeSession StartBound(GameModePolicy policy,
                                     GameModeClientApi api,
+                                    CpuAffinityApi affinity,
                                     void* library_handle);
   void CloseLibrary();
 

include/runtime/graphics_launch_policy.h

@@ -18,6 +18,26 @@ std::string SelectVulkanIcdManifest(
     const std::vector<std::filesystem::path>& directories,
     std::string_view vendor);
 
+// One GPU as the kernel reports it.
+struct HostGpu {
+  unsigned int vendor = 0;    // PCI vendor ID.
+  std::string kernel_driver;  // Bound kernel driver; empty when unknown.
+};
+
+struct VulkanIcdSelection {
+  std::string manifest;              // Empty when no GPU has a usable driver.
+  std::vector<std::string> skipped;  // Why each passed-over GPU was skipped.
+};
+
+// ICD manifest for the first GPU whose bound kernel driver has an installed
+// Vulkan driver. NVIDIA and AMD cards are tried before Intel when
+// `prefer_discrete` is set, and after it otherwise. A GPU with an unknown
+// kernel driver is matched by vendor alone.
+VulkanIcdSelection SelectHostVulkanIcd(
+    const std::vector<HostGpu>& gpus,
+    const std::vector<std::filesystem::path>& directories,
+    bool prefer_discrete);
+
 // Publishes the resolved graphics backend before the managed payload updater
 // starts. OpenGL is a strict system EGL/GLES path; it never silently retries
 // through ANGLE/Vulkan or accepts a window without a real graphics context.

include/runtime/luau_codegen_switch.h

@@ -0,0 +1,72 @@
+#ifndef MOCKTAIL_RUNTIME_LUAU_CODEGEN_SWITCH_H_
+#define MOCKTAIL_RUNTIME_LUAU_CODEGEN_SWITCH_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <string_view>
+#include <vector>
+
+#include "runtime/roblox_experience_presence.h"
+
+namespace mocktail {
+namespace runtime {
+
+// A user value in fflags.json or the overrides environment disables switching.
+// ARM64 prepares the writable flag before enabling menu code generation.
+inline constexpr std::string_view kLuauCodegenAllClientSetting =
+    "FFlagDebugLuauCodegenAll";
+inline constexpr std::string_view kLuauCodegenAllFastFlagName =
+    "DebugLuauCodegenAll";
+
+struct LoadedImageSegment {
+  std::uintptr_t address = 0;
+  std::size_t size = 0;
+  bool writable = false;
+};
+
+std::vector<LoadedImageSegment> LoadedImageSegments(std::uintptr_t image_base);
+
+// Record layout: {u8 value; pad; const char* name; size_t length}, in a
+// writable segment filled by libroblox's static constructors. Returns null
+// unless exactly one record names a NUL-terminated copy of `name`.
+std::uint8_t* FindFastFlagValue(
+    const std::vector<LoadedImageSegment>& segments, std::string_view name);
+
+bool ClientSettingsSetLuauCodegenAll(std::string_view overrides_json);
+
+bool LuauCodegenAllForPhase(RobloxExperiencePresencePhase phase);
+
+// Locates the flag once; a missing/ambiguous record or non-boolean byte is left
+// alone. Automatic ARM64 startup must not force the flag on before preparation.
+class LuauCodegenMenuSwitch {
+ public:
+  using LocateFlagFn = std::function<std::uint8_t*()>;
+
+  LuauCodegenMenuSwitch(LocateFlagFn locate_flag,
+                        RobloxExperiencePresenceObserver next);
+
+  // Call after constructors/settings initialization, before starting LuaApp.
+  // Does not notify the downstream presence observer. False leaves it unchanged.
+  bool PrepareForMenus();
+  RobloxExperiencePresenceObserver observer();
+  void OnPhase(RobloxExperiencePresencePhase phase,
+               const RobloxExperienceLaunchRequest* request);
+
+ private:
+  static void Notify(void* context, RobloxExperiencePresencePhase phase,
+                     const RobloxExperienceLaunchRequest* request);
+  bool SetEnabledLocked(bool enabled);
+
+  std::mutex mutex_;
+  LocateFlagFn locate_flag_;
+  bool located_ = false;
+  std::uint8_t* flag_ = nullptr;
+  const RobloxExperiencePresenceObserver next_;
+};
+
+}  // namespace runtime
+}  // namespace mocktail
+
+#endif  // MOCKTAIL_RUNTIME_LUAU_CODEGEN_SWITCH_H_

include/runtime/performance_policy.h

@@ -64,6 +64,13 @@ bool MergeRuntimeClientSettingsOverrides(
     std::string_view base_json, std::string* merged_json, std::string* error,
     std::vector<std::string>* kept_overrides = nullptr);
 
+// The resolved VR mode owns these flags in both client-settings channels.
+// Temporal depth preservation also requires non-memoryless native targets.
+bool MergeVrClientSettingsOverrides(bool enabled, std::string_view base_json,
+                                    std::string* merged_json,
+                                    std::string* error,
+                                    bool preserve_temporal_depth = false);
+
 // Keeps the legacy test bypass disabled. The host PermissionsProtocol now
 // answers microphone authorization from capture configuration. No permission
 // query opens a recording device.