Merge branch 'main' into vr

vr.anti_aliasing now takes fxaa, smaa or off. SMAA runs the reference
implementation (third_party/smaa, MIT) at its High preset: luma edge
detection and blending weights into per-eye images, then neighborhood
blending into the runtime's swapchain through FXAA's final pass. Its area and
search lookup textures are uploaded once per device. If SMAA cannot be set
up, the eyes fall back to FXAA.

Also export vr.anti_aliasing from config.yaml: the VR backend reads the
process environment, so the setting only worked as an environment variable.

On a Quest 2 through SteamVR at 120 Hz (2136x2236 per eye), SMAA ran at 118.6
fps against 118.8 for FXAA, with p99 frame times of 10.1 and 9.5 ms.

.envrc

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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,103 @@
+# Modified by vii from komaruworld/mocktail. See README "About this fork".
+name: Bug report
+description: Report a reproducible problem in Nightcap
+title: "[Bug]: "
+labels:
+  - bug
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please include enough detail for someone else to reproduce the bug.
+
+        Use any language you are comfortable with.
+
+        Please write issues and pull requests yourself.
+
+  - type: input
+    id: version
+    attributes:
+      label: Nightcap version
+      description: Provide the release version, package version, or commit hash.
+      placeholder: "For example: v0.4.0 or 1a2b3c4"
+    validations:
+      required: true
+
+  - type: input
+    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"
+    validations:
+      required: true
+
+  - type: input
+    id: installation
+    attributes:
+      label: Installation method
+      description: Tell us how Nightcap was installed or built.
+      placeholder: "For example: AppImage, Flatpak, AUR, or built from source"
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened?
+      description: Describe the problem and its impact.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: List the smallest reliable sequence of actions that triggers the problem.
+      placeholder: |
+        1. Start Nightcap with ...
+        2. Open ...
+        3. Select ...
+        4. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Explain what you expected to happen instead.
+    validations:
+      required: true
+
+  - type: markdown
+    attributes:
+      value: |
+        Latest log:
+
+        - Flatpak: `~/.var/app/io.github.CoderDayton.nightcap/.local/state/mocktail/logs/latest.log`
+        - Other installs: `~/.local/state/mocktail/logs/latest.log`
+
+        Older logs are in the `sessions` directory next to `latest.log`.
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Paste the relevant part of latest.log or the terminal output.
+      render: shell
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add screenshots, videos, workarounds, or any other useful details.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched the existing issues and did not find a duplicate.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: true
+contact_links: []

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,52 @@
+# Modified by vii from komaruworld/mocktail. See README "About this fork".
+name: Feature request
+description: Suggest an improvement or a new capability for Nightcap
+title: "[Feature]: "
+labels:
+  - enhancement
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Describe what you want to change and why it would be useful.
+
+        Use any language you are comfortable with.
+
+        Please write issues and pull requests yourself.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: What are you trying to do, and what makes it difficult today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe how you would like Nightcap to behave.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Describe any workarounds or alternative designs you have considered.
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add mockups, screenshots, links, or implementation notes if useful.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched the existing issues and did not find a duplicate.
+          required: true

.github/pull_request_template.md

@@ -0,0 +1,4 @@
+<!-- Modified by vii from komaruworld/mocktail. See README "About this fork". -->
+<!-- Briefly describe what this pull request adds, changes, or removes. Link the issue with "Closes #123" or "Fixes #123". -->
+
+Closes #

.github/workflows/aur-publish.yml

@@ -0,0 +1,119 @@
+name: Publish AUR packages
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish, such as v0.3.4
+        required: true
+        type: string
+  workflow_call:
+    inputs:
+      tag:
+        required: true
+        type: string
+    secrets:
+      AUR_SSH_PRIVATE_KEY:
+        required: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: aur-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish nightcap and nightcap-bin
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment: release
+    steps:
+      - name: Check out the release
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.tag }}
+          persist-credentials: false
+
+      - name: Render the recipes
+        shell: bash
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -Eeuo pipefail
+          [[ "$TAG" =~ ^v[0-9]+(\.[0-9]+)*$ ]]
+          version="${TAG#v}"
+          archive="nightcap-${version}-1-x86_64.pkg.tar.zst"
+          # nightcap-bin installs the pacman package from the release page, so
+          # its checksum is the one published beside that asset.
+          checksum="$(curl -fsSL \
+            "https://github.com/${GITHUB_REPOSITORY}/releases/download/${TAG}/${archive}.sha256" |
+            awk '{print $1}')"
+          [[ "$checksum" =~ ^[0-9a-f]{64}$ ]]
+
+          sed -i "s/^pkgver=.*/pkgver=${version}/" \
+            packaging/aur/nightcap/PKGBUILD packaging/aur/nightcap-bin/PKGBUILD
+          sed -i "s/^sha256sums=('SKIP')$/sha256sums=('${checksum}')/" \
+            packaging/aur/nightcap-bin/PKGBUILD
+          grep -Fqx "sha256sums=('${checksum}')" packaging/aur/nightcap-bin/PKGBUILD
+
+          docker run --rm \
+            --volume "$GITHUB_WORKSPACE/packaging/aur:/aur" \
+            ghcr.io/archlinux/archlinux:base-devel@sha256:c3953446016873a756fb7814f10087cac1634c127f7302e80c81c512da796d05 bash -Eeuo pipefail -c '
+              useradd --create-home builder
+              for package in nightcap nightcap-bin; do
+                install -d -o builder -g builder "/tmp/${package}"
+                install -o builder -g builder -m 0644 \
+                  "/aur/${package}/PKGBUILD" "/tmp/${package}/PKGBUILD"
+                runuser -u builder -- bash -c \
+                  "cd /tmp/${package} && makepkg --printsrcinfo" \
+                  > "/aur/${package}/.SRCINFO"
+              done
+            '
+
+          for package in nightcap nightcap-bin; do
+            grep -Fqx "pkgver=${version}" "packaging/aur/${package}/PKGBUILD"
+            grep -Fqx $'\tpkgver = '"${version}" "packaging/aur/${package}/.SRCINFO"
+          done
+          echo "VERSION=${version}" >> "$GITHUB_ENV"
+
+      - name: Push to the AUR
+        shell: bash
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          set -Eeuo pipefail
+          if [[ -z "${AUR_SSH_PRIVATE_KEY}" ]]; then
+            echo "::notice::AUR_SSH_PRIVATE_KEY is not set; nothing was pushed to the AUR"
+            exit 0
+          fi
+
+          ssh_dir="$(mktemp -d)"
+          trap 'rm -rf "$ssh_dir"' EXIT
+          install -m 0600 /dev/null "$ssh_dir/key"
+          printf '%s\n' "$AUR_SSH_PRIVATE_KEY" > "$ssh_dir/key"
+          # The AUR lists this key's fingerprint on its front page:
+          # SHA256:RFzBCUItH9LZS0cKB5UE6ceAYhBD5C8GeOBip8Z11+4
+          printf '%s\n' \
+            'aur.archlinux.org ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEuBKrPzbawxA/k2g6NcyV5jmqwJ2s+zpgZGZ7tpLIcN' \
+            > "$ssh_dir/known_hosts"
+          export GIT_SSH_COMMAND="ssh -i $ssh_dir/key -o IdentitiesOnly=yes -o UserKnownHostsFile=$ssh_dir/known_hosts -o StrictHostKeyChecking=yes"
+
+          for package in nightcap nightcap-bin; do
+            checkout="$ssh_dir/$package"
+            git clone "ssh://aur@aur.archlinux.org/${package}.git" "$checkout"
+            cp "packaging/aur/${package}/PKGBUILD" "packaging/aur/${package}/.SRCINFO" \
+              "$checkout/"
+            git -C "$checkout" add PKGBUILD .SRCINFO
+            if git -C "$checkout" diff --cached --quiet; then
+              echo "::notice::${package} is already at ${VERSION}"
+              continue
+            fi
+            git -C "$checkout" \
+              -c user.name='Nightcap release' \
+              -c user.email='CoderDayton@users.noreply.github.com' \
+              commit --quiet -m "Update to ${VERSION}"
+            # The AUR only accepts the master branch.
+            git -C "$checkout" push origin HEAD:master
+          done

.github/workflows/aur.yml

@@ -1,20 +1,18 @@
-name: Publish AUR development package
+name: Check AUR packages
 
 on:
-  push:
-    branches: [main]
   workflow_dispatch:
 
 permissions:
   contents: read
 
 concurrency:
-  group: aur-mocktail-git
+  group: aur-packages
   cancel-in-progress: true
 
 jobs:
-  publish:
-    name: Publish mocktail-git
+  metadata:
+    name: Refresh AUR metadata
     runs-on: ubuntu-24.04
     timeout-minutes: 15
     steps:
@@ -27,10 +25,9 @@ jobs:
         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)"
+          package_dir="$GITHUB_WORKSPACE/packaging/aur/nightcap-git"
+          version="$(git describe --tags --abbrev=0 --match='v[0-9]*')"
+          version="${version#v}"
           [[ "$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"
@@ -39,66 +36,21 @@ jobs:
             --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 -d -o builder -g builder /tmp/nightcap-git
               install -o builder -g builder -m 0644 \
-                /pkg/PKGBUILD /tmp/mocktail-git/PKGBUILD
+                /pkg/PKGBUILD /tmp/nightcap-git/PKGBUILD
               runuser -u builder -- bash -c \
-                "cd /tmp/mocktail-git && makepkg --printsrcinfo" \
+                "cd /tmp/nightcap-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"
-          aur_dir="$RUNNER_TEMP/mocktail-git-aur"
-          git clone --branch master --single-branch \
-            ssh://aur@aur.archlinux.org/mocktail-git.git "$aur_dir"
-          install -m 0644 packaging/aur/mocktail-git/PKGBUILD "$aur_dir/PKGBUILD"
-          install -m 0644 packaging/aur/mocktail-git/.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 'mocktail-git %s is already published\n' "$AUR_PKGVER"
-            exit 0
-          fi
-          git -C "$aur_dir" commit -m "Update to ${AUR_PKGVER}"
-          git -C "$aur_dir" push origin HEAD:master
+      - name: Upload AUR metadata
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: Nightcap-AUR
+          path: packaging/aur/nightcap-git/.SRCINFO
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/ci.yml

@@ -8,22 +8,32 @@ on:
       - 'CMakeLists.txt'
       - 'Makefile'
       - 'README.md'
+      - '.gitmodules'
+      - 'cmake/**'
       - 'config/**'
+      - 'include/**'
       - 'packaging/**'
       - 'scripts/**'
+      - 'src/**'
       - 'stubs/**'
       - 'tests/**'
+      - 'third_party/**'
   pull_request:
     paths:
       - '.github/workflows/**'
       - 'CMakeLists.txt'
       - 'Makefile'
       - 'README.md'
+      - '.gitmodules'
+      - 'cmake/**'
       - 'config/**'
+      - 'include/**'
       - 'packaging/**'
       - 'scripts/**'
+      - 'src/**'
       - 'stubs/**'
       - 'tests/**'
+      - 'third_party/**'
   workflow_dispatch:
 
 permissions:
@@ -52,9 +62,75 @@ jobs:
           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 .
+
+  native-build:
+    name: Native build (${{ matrix.arch }}, VR ${{ matrix.vr }})
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: x86_64
+            runner: ubuntu-26.04
+            vr: 'ON'
+          - arch: aarch64
+            runner: ubuntu-26.04-arm
+            vr: 'ON'
+          # Packaging recipes build without the OpenXR submodule; keep the
+          # non-VR configuration compiling and passing on its own.
+          - arch: x86_64
+            runner: ubuntu-26.04
+            vr: 'OFF'
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          submodules: recursive
+
+      - name: Install build dependencies
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes --no-install-recommends \
+            build-essential binutils 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 libpng-dev zlib1g-dev \
+            xvfb xauth libgl1-mesa-dri jq patchelf
+
+      - name: Build and check native executables
+        shell: bash
+        run: |
+          test "$(uname -m)" = "${{ matrix.arch }}"
+          cmake -S . -B build-ci -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON \
+            -DMOCKTAIL_ENABLE_VR=${{ matrix.vr }}
+          cmake --build build-ci --parallel 4
+          ./build-ci/mocktail --help
+          ./build-ci/mocktail_updater status
+
+      - name: Run C++ and integration tests
+        shell: bash
+        env:
+          SDL_AUDIODRIVER: dummy
+          SDL_VIDEODRIVER: x11
+          LIBGL_ALWAYS_SOFTWARE: '1'
+        run: |
+          xvfb-run -a ctest --test-dir build-ci --output-on-failure \
+            --parallel 4 --timeout 120

.github/workflows/flatpak.yml

@@ -1,9 +1,9 @@
+# Modified by vii from komaruworld/mocktail. See README "About this fork".
 name: Flatpak
 
 on:
-  workflow_run:
-    workflows: [Native packages]
-    types: [completed]
+  push:
+    tags: ['v*']
   pull_request:
     paths:
       - '.github/workflows/flatpak.yml'
@@ -15,13 +15,11 @@ on:
       - 'config/**'
       - 'include/**'
       - 'packaging/flatpak/**'
-      - 'packaging/discord-join.html'
       - 'packaging/icons/**'
-      - 'packaging/space.bigrat.mocktail.desktop'
-      - 'packaging/space.bigrat.mocktail.metainfo.xml'
-      - 'packaging/space.bigrat.mocktail.svg'
+      - 'packaging/io.github.CoderDayton.nightcap.desktop'
+      - 'packaging/io.github.CoderDayton.nightcap.metainfo.xml'
+      - 'packaging/io.github.CoderDayton.nightcap.svg'
       - 'scripts/assemble_flatpak_pages.sh'
-      - 'scripts/assemble_native_repositories.sh'
       - 'site/**'
       - 'src/**'
       - 'stubs/**'
@@ -29,61 +27,31 @@ on:
   workflow_dispatch:
 
 permissions:
-  actions: read
   contents: read
 
 concurrency:
-  group: flatpak-${{ github.event.workflow_run.head_sha || github.ref }}
-  cancel-in-progress: true
+  group: flatpak-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   flatpak:
     name: Flatpak build
-    if: >-
-      github.event_name != 'workflow_run' ||
-      (github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.event != 'pull_request' &&
-      github.event.workflow_run.head_branch == 'main')
     runs-on: ubuntu-24.04
     timeout-minutes: 120
+    # The signing key lives in the release environment, which only main and
+    # v* tags may use. Builds that do not publish run without it.
+    environment: ${{ (startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')) && 'release' || '' }}
     env:
-      MOCKTAIL_PUBLISH: ${{ (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event != 'pull_request' && github.event.workflow_run.head_branch == 'main') || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') }}
-      MOCKTAIL_SOURCE_SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
+      # 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
-          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
           submodules: recursive
 
-      - name: Download package repositories
-        if: env.MOCKTAIL_PUBLISH == 'true'
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -Eeuo pipefail
-          run_id="${{ github.event.workflow_run.id }}"
-          if [[ -z "$run_id" ]]; then
-            run_id="$(gh run list \
-              --workflow packages.yml \
-              --branch main \
-              --event push \
-              --status success \
-              --limit 1 \
-              --json databaseId \
-              --jq '.[0].databaseId')"
-          fi
-          [[ -n "$run_id" ]]
-          gh run download "$run_id" \
-            --name Mocktail-native-repositories \
-            --dir native-repositories
-          [[ -d native-repositories/apt && \
-             -d native-repositories/rpm && \
-             -d native-repositories/downloads && \
-             -s native-repositories/mocktail-packages.gpg ]]
-
       - name: Install Flatpak builder
         shell: bash
         run: |
@@ -99,22 +67,23 @@ jobs:
           FLATPAK_GPG_KEY_ID: ${{ secrets.FLATPAK_GPG_KEY_ID }}
         run: |
           set -Eeuo pipefail
-          git update-ref refs/heads/main "$MOCKTAIL_SOURCE_SHA"
+          # 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/mocktail-gnupg"
+            install -d -m 0700 "$RUNNER_TEMP/nightcap-gnupg"
             printf '%s' "$FLATPAK_GPG_PRIVATE_KEY" | \
-              gpg --batch --homedir "$RUNNER_TEMP/mocktail-gnupg" --import
-            gpg --batch --homedir "$RUNNER_TEMP/mocktail-gnupg" \
-              --export "$FLATPAK_GPG_KEY_ID" >mocktail-flatpak.gpg
+              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/mocktail-gnupg"
+              "--gpg-homedir=$RUNNER_TEMP/nightcap-gnupg"
             )
-            bundle_keys=(--gpg-keys=mocktail-flatpak.gpg)
+            bundle_keys=(--gpg-keys=nightcap-flatpak.gpg)
           fi
           flatpak-builder \
             --arch=x86_64 \
@@ -127,34 +96,33 @@ jobs:
             --repo=repo \
             "${builder_signing[@]}" \
             build-flatpak-ci \
-            packaging/flatpak/space.bigrat.mocktail.json
+            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/mocktail-gnupg" \
+              --gpg-homedir="$RUNNER_TEMP/nightcap-gnupg" \
               repo
           fi
           flatpak build-bundle \
             --arch=x86_64 \
             "${bundle_keys[@]}" \
             repo \
-            Mocktail-x86_64.flatpak \
-            space.bigrat.mocktail \
+            Nightcap-x86_64.flatpak \
+            io.github.CoderDayton.nightcap \
             stable
           if [[ "$MOCKTAIL_PUBLISH" == true ]]; then
             ./scripts/assemble_flatpak_pages.sh \
-              repo Mocktail-x86_64.flatpak mocktail-flatpak.gpg \
-              public native-repositories
+              repo Nightcap-x86_64.flatpak nightcap-flatpak.gpg public
           fi
 
       - name: Upload Flatpak
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: Mocktail-x86_64-flatpak
-          path: Mocktail-x86_64.flatpak
+          name: Nightcap-x86_64-flatpak
+          path: Nightcap-x86_64.flatpak
           if-no-files-found: error
           retention-days: 14
 
@@ -170,13 +138,7 @@ jobs:
 
   deploy-pages:
     name: Publish Flatpak repository
-    if: >-
-      (github.event_name == 'workflow_run' &&
-      github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.event != 'pull_request' &&
-      github.event.workflow_run.head_branch == 'main') ||
-      (github.event_name == 'workflow_dispatch' &&
-      github.ref == 'refs/heads/main')
+    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
@@ -191,3 +153,43 @@ jobs:
       - 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,41 +1,51 @@
-name: Native packages
+name: Nightly AppImage
 
 on:
-  push:
-    branches: [main]
-    paths-ignore:
-      - '.github/workflows/ci.yml'
-      - '.gitignore'
-      - 'README.md'
-      - 'assets/screenshots/**'
-      - 'docs/**'
-      - 'packaging/aur/**'
-      - 'scripts/build_flatpak.sh'
-      - 'tests/**'
-  pull_request:
-    paths-ignore:
-      - '.github/workflows/ci.yml'
-      - '.gitignore'
-      - 'README.md'
-      - 'assets/screenshots/**'
-      - 'docs/**'
-      - 'packaging/aur/**'
-      - 'scripts/build_flatpak.sh'
-      - 'tests/**'
+  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: packages-${{ github.ref }}
-  cancel-in-progress: true
+  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 (Ubuntu 26.04)
+    name: AppImage (AnyLinux)
+    needs: probe
+    if: needs.probe.outputs.build == 'true'
     runs-on: ubuntu-24.04
     timeout-minutes: 90
+    env:
+      UPINFO: gh-releases-zsync|${{ github.repository_owner }}|${{ github.event.repository.name }}|continuous|Nightcap-nightly-x86_64.AppImage.zsync
     steps:
       - name: Check out source
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -45,205 +55,115 @@ jobs:
 
       - name: Build AppImage
         shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
           docker run --rm \
             --volume "$GITHUB_WORKSPACE:/workspace" \
             --workdir /workspace \
-            ubuntu:26.04 bash -Eeuo pipefail -c '
-              export DEBIAN_FRONTEND=noninteractive
-              apt-get update
-              apt-get install --yes --no-install-recommends \
-                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 zlib1g-dev \
-                libplacebo-dev \
-                bubblewrap xdg-dbus-proxy patchelf jq unzip file curl \
-                ca-certificates default-jdk-headless libgif7 python3 \
-                python3-capstone python3-yaml python3-requests \
-                python3-urllib3 python3-certifi python3-charset-normalizer \
-                python3-idna squashfs-tools
+            --env GH_TOKEN \
+            --env UPINFO \
+            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/AppImage/appimagetool/releases/download/1.9.1/appimagetool-x86_64.AppImage
-              echo "ed4ce84f0d9caff66f50bcca6ff6f35aae54ce8135408b3fa33abfc3cb384eb0  /tmp/appimagetool" | \
+                https://github.com/pkgforge-dev/appimagetool/releases/download/0.3.3/appimagetool-x86_64-linux
+              echo "0d01a4e2628efc897be9663f0faeed6a171e1851270b4e1ce4c22434a36ecebd  /tmp/appimagetool" | \
                 sha256sum --check --strict
-              install -m 0755 /tmp/appimagetool /usr/local/bin/appimagetool
+              chmod 0755 /tmp/appimagetool
 
               curl --fail --location --retry 3 \
-                --output /tmp/android-build-tools.zip \
-                https://dl.google.com/android/repository/build-tools_r35_linux.zip
-              echo "bd3a4966912eb8b30ed0d00b0cda6b6543b949d5ffe00bea54c04c81e1561d88  /tmp/android-build-tools.zip" | \
+                --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
-              unzip -q /tmp/android-build-tools.zip -d /tmp/android-build-tools
-              android_tools_root="$(dirname -- "$(find /tmp/android-build-tools -type f -name apksigner -print -quit)")"
-              [[ -n "$android_tools_root" ]]
+              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 APPIMAGE_EXTRACT_AND_RUN=1
-              export MOCKTAIL_ANDROID_BUILD_TOOLS_ROOT="$android_tools_root"
+              # 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
-              test -x dist/Mocktail-x86_64.AppImage
+                APPIMAGE=dist/Nightcap-nightly-x86_64.AppImage \
+                PORTABLE_MODE=standalone APPIMAGE_FORMAT=anylinux \
+                ANYLINUX_PACKAGER=/tmp/quick-sharun \
+                ANYLINUX_APPIMAGETOOL=/tmp/appimagetool
+              test -x dist/Nightcap-nightly-x86_64.AppImage
+              test -s dist/Nightcap-nightly-x86_64.AppImage.zsync
             '
 
+      - 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"
+          test "$(dist/Nightcap-nightly-x86_64.AppImage --appimage-updateinformation)" = "$UPINFO"
+          timeout 60s dist/Nightcap-nightly-x86_64.AppImage --appimage-extract-and-run --help
+          timeout 60s dist/Nightcap-nightly-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
-
-  deb:
-    name: DEB (Ubuntu 26.04)
-    runs-on: ubuntu-24.04
-    timeout-minutes: 45
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-          submodules: recursive
-
-      - name: Build DEB
-        shell: bash
-        run: |
-          nightly_suffix=".nightly.$(git show -s --format=%cd --date=format:%Y%m%d%H%M%S "$GITHUB_SHA").g${GITHUB_SHA:0:8}"
-          docker run --rm \
-            --volume "$GITHUB_WORKSPACE:/workspace" \
-            --workdir /workspace \
-            --env MOCKTAIL_PACKAGE_VERSION_SUFFIX="$nightly_suffix" \
-            ubuntu:26.04 bash -Eeuo pipefail -c '
-              export DEBIAN_FRONTEND=noninteractive
-              apt-get update
-              apt-get install --yes --no-install-recommends \
-                build-essential cmake git ninja-build pkg-config lld fakeroot \
-                dpkg-dev file 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
-              cmake -S . -B build-deb -G Ninja \
-                -DCMAKE_BUILD_TYPE=Release \
-                -DCMAKE_INSTALL_PREFIX=/usr \
-                -DMOCKTAIL_PACKAGE_NAME=mocktail-nightly \
-                -DMOCKTAIL_PACKAGE_VERSION_SUFFIX="$MOCKTAIL_PACKAGE_VERSION_SUFFIX" \
-                -DBUILD_TESTING=OFF
-              cmake --build build-deb --parallel 4
-              cpack --config build-deb/CPackConfig.cmake \
-                -G DEB -B dist/deb
-              dpkg-deb --info dist/deb/*.deb >/dev/null
-            '
-
-      - name: Upload DEB
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: Mocktail-DEB
-          path: dist/deb/*.deb
-          if-no-files-found: error
-          retention-days: 14
-
-  rpm:
-    name: RPM (Fedora 44)
-    runs-on: ubuntu-24.04
-    timeout-minutes: 45
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-          submodules: recursive
-
-      - name: Build RPM
-        shell: bash
-        run: |
-          nightly_suffix=".nightly.$(git show -s --format=%cd --date=format:%Y%m%d%H%M%S "$GITHUB_SHA").g${GITHUB_SHA:0:8}"
-          docker run --rm \
-            --volume "$GITHUB_WORKSPACE:/workspace" \
-            --workdir /workspace \
-            --env MOCKTAIL_PACKAGE_VERSION_SUFFIX="$nightly_suffix" \
-            fedora:44 bash -Eeuo pipefail -c '
-              dnf install --assumeyes \
-                gcc-c++ cmake git ninja-build pkgconf-pkg-config lld rpm-build \
-                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
-              cmake -S . -B build-rpm -G Ninja \
-                -DCMAKE_BUILD_TYPE=Release \
-                -DCMAKE_INSTALL_PREFIX=/usr \
-                -DMOCKTAIL_PACKAGE_NAME=mocktail-nightly \
-                -DMOCKTAIL_PACKAGE_VERSION_SUFFIX="$MOCKTAIL_PACKAGE_VERSION_SUFFIX" \
-                -DBUILD_TESTING=OFF
-              cmake --build build-rpm --parallel 4
-              cpack --config build-rpm/CPackConfig.cmake \
-                -G RPM -B dist/rpm
-              rpm --query --package --info dist/rpm/*.rpm >/dev/null
-            '
-
-      - name: Upload RPM
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: Mocktail-RPM
-          path: dist/rpm/*.rpm
-          if-no-files-found: error
-          retention-days: 14
-
-  arch:
-    name: Pacman package (Arch Linux)
-    runs-on: ubuntu-24.04
-    timeout-minutes: 45
-    steps:
-      - name: Check out source
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0
-          submodules: recursive
-
-      - name: Build pacman package
-        shell: bash
-        run: |
-          docker run --rm \
-            --volume "$GITHUB_WORKSPACE:/workspace" \
-            --workdir /workspace \
-            archlinux:base-devel bash -Eeuo pipefail -c '
-              pacman -Syu --needed --noconfirm \
-                cmake git ninja pkgconf lld sdl3 sdl3_ttf curl openssl \
-                nlohmann-json libyaml libelf minizip capstone gtk4 \
-                libadwaita webkitgtk-6.0 libutf8proc fontconfig \
-                libplacebo vulkan-headers vulkan-icd-loader libglvnd zlib
-              useradd --create-home builder
-              chown -R builder:builder /workspace
-              runuser -u builder -- env MOCKTAIL_SOURCE_DIR=/workspace \
-                makepkg --dir /workspace/packaging/arch \
-                  --noconfirm --cleanbuild --force
-              install -d dist/arch
-              cp packaging/arch/*.pkg.tar.zst dist/arch/
-              pacman -Qp dist/arch/*.pkg.tar.zst >/dev/null
-            '
-
-      - name: Upload pacman package
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: Mocktail-Arch
-          path: dist/arch/*.pkg.tar.zst
+          name: Nightcap-AppImage
+          path: |
+            dist/Nightcap-nightly-x86_64.AppImage
+            dist/Nightcap-nightly-x86_64.AppImage.zsync
           if-no-files-found: error
           retention-days: 14
 
   publish:
-    name: Publish continuous packages
-    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
-    needs: [appimage, deb, rpm, arch]
+    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:
@@ -254,84 +174,50 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Download packages
+      - name: Download AppImage
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          pattern: Mocktail-*
+          name: Nightcap-AppImage
           path: release
-          merge-multiple: true
 
-      - name: Prepare continuous packages
+      - name: Checksum the nightly build
         shell: bash
         run: |
           set -Eeuo pipefail
-          mv -- release/*.AppImage release/mocktail-nightly.AppImage
-          mv -- release/*.deb release/mocktail-nightly.deb
-          mv -- release/*.rpm release/mocktail-nightly.rpm
-          mv -- release/*.pkg.tar.zst release/mocktail-nightly.pkg.tar.zst
+          # The .zsync file names the AppImage it updates, so the build already
+          # carries the published name.
+          test -s release/Nightcap-nightly-x86_64.AppImage
+          test -s release/Nightcap-nightly-x86_64.AppImage.zsync
+          (cd release && sha256sum Nightcap-nightly-x86_64.AppImage \
+            > Nightcap-nightly-x86_64.AppImage.sha256)
           find release -maxdepth 1 -type f -print
 
-      - name: Build package repositories
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-          FLATPAK_GPG_PRIVATE_KEY: ${{ secrets.FLATPAK_GPG_PRIVATE_KEY }}
-          FLATPAK_GPG_KEY_ID: ${{ secrets.FLATPAK_GPG_KEY_ID }}
-        run: |
-          set -Eeuo pipefail
-          [[ -n "$FLATPAK_GPG_PRIVATE_KEY" && -n "$FLATPAK_GPG_KEY_ID" ]]
-          sudo apt-get update
-          sudo apt-get install --yes --no-install-recommends \
-            apt-utils createrepo-c gnupg rpm
-          install -d stable/deb stable/rpm
-          stable_tag="$(gh api "repos/$GITHUB_REPOSITORY/releases/latest" --jq .tag_name)"
-          gh release download "$stable_tag" --pattern '*.deb' --dir stable/deb
-          gh release download "$stable_tag" --pattern '*.rpm' --dir stable/rpm
-          mapfile -t stable_debs < <(find stable/deb -maxdepth 1 -type f -name '*.deb' -print)
-          mapfile -t stable_rpms < <(find stable/rpm -maxdepth 1 -type f -name '*.rpm' -print)
-          [[ "${#stable_debs[@]}" -eq 1 && "${#stable_rpms[@]}" -eq 1 ]]
-          install -d -m 0700 "$RUNNER_TEMP/mocktail-native-gnupg"
-          printf '%s' "$FLATPAK_GPG_PRIVATE_KEY" | \
-            gpg --batch --homedir "$RUNNER_TEMP/mocktail-native-gnupg" --import
-          gpg --batch --homedir "$RUNNER_TEMP/mocktail-native-gnupg" \
-            --export "$FLATPAK_GPG_KEY_ID" >mocktail-packages.gpg
-          ./scripts/assemble_native_repositories.sh \
-            "${stable_debs[0]}" release/mocktail-nightly.deb \
-            "${stable_rpms[0]}" release/mocktail-nightly.rpm \
-            mocktail-packages.gpg "$FLATPAK_GPG_KEY_ID" \
-            "$RUNNER_TEMP/mocktail-native-gnupg" native-repositories
-
       - name: Update continuous release
         shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           set -Eeuo pipefail
-          git config user.name komaruworld
-          git config user.email rtysus228@gmail.com
+          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 "Mocktail continuous" \
-              --notes "Automated development packages from main."
+              --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
-              mocktail-nightly.AppImage|mocktail-nightly.deb|mocktail-nightly.rpm|mocktail-nightly.pkg.tar.zst)
+              Nightcap-nightly-x86_64.AppImage|Nightcap-nightly-x86_64.AppImage.zsync|Nightcap-nightly-x86_64.AppImage.sha256)
                 ;;
-              Mocktail-*.AppImage|mocktail_*.deb|mocktail-*.deb|mocktail-*.rpm|mocktail-*.pkg.tar.zst)
+              *)
                 gh release delete-asset continuous "$asset" --yes
                 ;;
             esac
           done < <(gh release view continuous --json assets --jq '.assets[].name')
-
-      - name: Upload package repositories
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: Mocktail-native-repositories
-          path: native-repositories
-          if-no-files-found: error
-          retention-days: 14

.github/workflows/release.yml

@@ -0,0 +1,350 @@
+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
+
+  deb:
+    name: DEB (Ubuntu 26.04)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Build DEB
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          docker run --rm \
+            --volume "$GITHUB_WORKSPACE:/workspace" \
+            --workdir /workspace \
+            --env MOCKTAIL_PACKAGE_VERSION="$(./scripts/package_version.sh)" \
+            ubuntu:26.04 bash -Eeuo pipefail -c '
+              export DEBIAN_FRONTEND=noninteractive
+              apt-get update
+              apt-get install --yes --no-install-recommends \
+                build-essential cmake git ninja-build pkg-config lld fakeroot \
+                dpkg-dev file 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 libpng-dev
+              cmake -S . -B build-deb -G Ninja \
+                -DCMAKE_BUILD_TYPE=Release \
+                -DCMAKE_INSTALL_PREFIX=/usr \
+                -DMOCKTAIL_PACKAGE_NAME=nightcap \
+                -DMOCKTAIL_PACKAGE_VERSION="$MOCKTAIL_PACKAGE_VERSION" \
+                -DBUILD_TESTING=OFF
+              cmake --build build-deb --parallel 4
+              cpack --config build-deb/CPackConfig.cmake \
+                -G DEB -B dist/deb
+              dpkg-deb --info dist/deb/*.deb >/dev/null
+            '
+
+      - name: Upload DEB
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: Nightcap-DEB
+          path: dist/deb/*.deb
+          if-no-files-found: error
+          retention-days: 14
+
+  rpm:
+    name: RPM (Fedora 44)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Build RPM
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          docker run --rm \
+            --volume "$GITHUB_WORKSPACE:/workspace" \
+            --workdir /workspace \
+            --env MOCKTAIL_PACKAGE_VERSION="$(./scripts/package_version.sh)" \
+            fedora:44 bash -Eeuo pipefail -c '
+              dnf install --assumeyes \
+                gcc-c++ cmake git ninja-build pkgconf-pkg-config lld rpm-build \
+                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 libpng-devel
+              cmake -S . -B build-rpm -G Ninja \
+                -DCMAKE_BUILD_TYPE=Release \
+                -DCMAKE_INSTALL_PREFIX=/usr \
+                -DCMAKE_INSTALL_LIBDIR=lib \
+                -DMOCKTAIL_PACKAGE_NAME=nightcap \
+                -DMOCKTAIL_PACKAGE_VERSION="$MOCKTAIL_PACKAGE_VERSION" \
+                -DBUILD_TESTING=OFF
+              cmake --build build-rpm --parallel 4
+              cpack --config build-rpm/CPackConfig.cmake \
+                -G RPM -B dist/rpm
+              rpm --query --package --info dist/rpm/*.rpm >/dev/null
+            '
+
+      - name: Upload RPM
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: Nightcap-RPM
+          path: dist/rpm/*.rpm
+          if-no-files-found: error
+          retention-days: 14
+
+  arch:
+    name: Pacman package (Arch Linux)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Build pacman package
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          version="$(./scripts/package_version.sh)"
+          sed -i "s/^pkgver=.*/pkgver=${version}/" packaging/arch/PKGBUILD
+          docker run --rm \
+            --volume "$GITHUB_WORKSPACE:/workspace" \
+            --workdir /workspace \
+            ghcr.io/archlinux/archlinux:base-devel@sha256:c3953446016873a756fb7814f10087cac1634c127f7302e80c81c512da796d05 bash -Eeuo pipefail -c '
+              pacman -Syu --needed --noconfirm \
+                cmake git ninja pkgconf lld sdl3 sdl3_ttf curl openssl \
+                nlohmann-json libyaml libelf minizip capstone gtk4 \
+                libadwaita webkitgtk-6.0 libutf8proc fontconfig libpng \
+                libplacebo vulkan-headers vulkan-icd-loader libglvnd zlib
+              useradd --create-home builder
+              chown -R builder:builder /workspace
+              runuser -u builder -- env MOCKTAIL_SOURCE_DIR=/workspace \
+                makepkg --dir /workspace/packaging/arch \
+                  --noconfirm --cleanbuild --force
+              install -d dist/arch
+              cp packaging/arch/*.pkg.tar.zst dist/arch/
+              pacman -Qp dist/arch/*.pkg.tar.zst >/dev/null
+            '
+
+      - name: Upload pacman package
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: Nightcap-Arch
+          path: dist/arch/*.pkg.tar.zst
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    name: Publish GitHub release
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [appimage, deb, rpm, arch]
+    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 packages
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: 'Nightcap-*'
+          merge-multiple: true
+          path: release
+
+      - 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
+          # An unmatched glob would otherwise reach sha256sum and gh as its own
+          # literal text, so every package pattern has to match before upload.
+          shopt -s nullglob
+          assets=(Nightcap-x86_64.AppImage)
+          for glob in '*.deb' '*.rpm' '*.pkg.tar.zst'; do
+            matched=(release/$glob)
+            if [[ ${#matched[@]} -eq 0 ]]; then
+              echo "::error::no ${glob} package among the release artifacts"
+              exit 1
+            fi
+            assets+=("${matched[@]#release/}")
+          done
+          uploads=()
+          for asset in "${assets[@]}"; do
+            uploads+=("release/$asset" "release/$asset.sha256")
+          done
+          (
+            cd release
+            for asset in "${assets[@]}"; do
+              sha256sum "$asset" > "$asset.sha256"
+            done
+          )
+          ./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 \
+            "${uploads[@]}"
+
+  # nightcap-bin downloads the pacman package from the release page, so this
+  # waits for the upload.
+  aur:
+    name: Publish AUR packages
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: publish
+    uses: ./.github/workflows/aur-publish.yml
+    with:
+      tag: ${{ github.ref_name }}
+    secrets:
+      AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}

.gitignore

@@ -1,7 +1,9 @@
 # Build
 /build/
+/build-test/
 /build_*/
 /build-flatpak/
+/build-anylinux*/
 /.flatpak-builder/
 /cmake-build-*/
 /out/
@@ -20,6 +22,12 @@ Testing/
 CMakeUserPresets.json
 *.cmake.user
 
+# local direnv development shell cache
+.direnv/
+
+# clangd cache
+.cache
+
 *.o
 *.obj
 *.a
@@ -50,19 +58,7 @@ Makefile.cmake
 /cmake-build-release/
 
 # Roblox payload
-/rbx_bin/libroblox.so
-/rbx_bin/libroblox.so.*
-/rbx_bin/client_settings_android.json
-/rbx_bin/assets/
-/rbx_bin/android/
-/rbx_bin/sober_apk/
-/rbx_bin/versions/
-/rbx_bin/.payload-update.*/
-/rbx_bin/*.apk
-/rbx_bin/*.so
-/rbx_bin/*.so.*
-
-!/rbx_bin/.gitkeep
+/rbx_bin/
 
 # Runtime state
 /runtime/
@@ -181,3 +177,6 @@ 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/

.gitmodules

@@ -4,3 +4,9 @@
 [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
+[submodule "third_party/smaa"]
+	path = third_party/smaa
+	url = https://github.com/iryoku/smaa.git

CHANGELOG.md

@@ -0,0 +1,322 @@
+# 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]
+
+### Added
+
+- An asset overlay folder, `~/.local/share/mocktail/asset_overlay`. A file there replaces the file Roblox
+  ships at the same path, such as a cursor, a font or a sky texture, and it stays in place when Roblox
+  updates. The layout matches Sober's `asset_overlay` folder. `MOCKTAIL_ASSET_OVERLAY_DIR` moves it. Thanks to
+  @dim-ghub.
+- The asset overlay folder now also replaces files Roblox downloads and no longer ships, such as the shift
+  lock and text cursors. Put the file under `content/`, at the path Roblox uses. Thanks to @dim-ghub for the
+  idea.
+- `MOCKTAIL_ASSET_TRACE=1` now also prints the files Roblox asks for and does not get, as `[asset] miss`.
+- Arch Linux: `nightcap-git` is on the AUR and builds the current `main` branch. Thanks to @dim-ghub, who
+  maintains it.
+- `vr.mode` in `config.yaml`: `off` starts on the desktop, `on` starts in VR, and `auto` starts in VR only
+  when SteamVR is already running with a connected headset. `auto` never starts SteamVR. `vr.enabled` still
+  works.
+- Anti-aliasing in VR. Roblox draws the VR eyes without it, so edges were jagged in the headset. Each eye is
+  now filtered on its way to the headset. `vr.anti_aliasing` picks `fxaa` (the default), `smaa`, which finds
+  edges more precisely and keeps text sharper for a little more GPU time, or `off`.
+- The log now names each Roblox Java call that Nightcap has no handler for, once per call, as
+  `[JNI] no handler for <class>.<method><signature>`. This shows what a new Roblox version needs.
+- `--profile` traces now show how much GPU memory decoded ETC2 textures take, as the `emulated texture (MB)`
+  and `compressed texture (MB)` counters. `scripts/summarize_profile_trace.py` prints the peak of each.
+
+### Fixed
+
+- Joining a game from a website link while already in a game no longer freezes Nightcap. It leaves the
+  current game and joins the new one, and leaving that game returns to the home screen.
+
+### Changed
+
+- The home screen and avatar editor have fewer long frames. PC profiles compile the app's menu scripts to
+  native code and turn this off while you are in a game, so games run as before. Set
+  `FFlagDebugLuauCodegenAll` in `fflags.json` to choose it yourself.
+- Nightcap answers Roblox's Java calls with less work per call, and the audio thread no longer allocates
+  memory for each block of sound it plays.
+- VR on Vulkan no longer makes the CPU wait for the GPU each frame. The eye copies, the desktop mirror and
+  the `MOCKTAIL_VR_MIRROR_SHM` readback are ordered on the GPU, so Roblox prepares the next frame while the
+  last one renders. On a simulated 120 Hz headset this removed 2 to 5 ms of waiting per frame and steadied
+  the frame rate. The shared-memory mirror now shows each frame one frame later.
+- `MOCKTAIL_VR_PERF` also reports `desktop_mirror`, `present_prepare` and `present_interval`.
+
+## [0.3.4] - 2026-10-11
+
+### Added
+
+- The AppImage build now makes a `.zsync` file, so tools like `appimageupdatetool` can update the AppImage.
+- The desktop side panel menu now shows by default on PC profiles. Set `FIntFlyoutTestVariantRollout12` in
+  `fflags.json` to change it.
+
+### Changed
+
+- The Flatpak build asks for the X11 socket only when there is no Wayland session, as before 0.3.3.
+- Nightcap now uses Wayland on a Wayland session with NVIDIA drivers too, however it is started. It used to
+  fall back to X11 there when started from a terminal.
+- Building Nightcap no longer needs libexecinfo.
+
+### Fixed
+
+- Fixed Roblox 2.742 being rejected as an update, which left the game on the older version. Nightcap now
+  accepts Roblox versions that change the order of their start-up steps.
+- Fixed Nightcap reporting Mocktail's version number, 1.0.4, in session logs and support bundles. It now
+  reports its own version.
+- Fixed the old Roblox home screen showing instead of the new one with the Me tab and the "For you" and
+  "Charts" tabs. Nightcap now runs the Roblox start-up step that loads the new interface for your account.
+- Fixed anti-aliasing being forced off at every graphics quality level. Roblox now picks it, and a
+  `FIntDebugForceMSAASamples` value in `fflags.json` still applies. Thanks to @qutad.
+- Fixed the voice chat microphone only working on Roblox 2.738. It no longer depends on one Roblox version.
+- Fixed other players not hearing you in voice chat after a Roblox update. The updater now rebuilds the
+  audio device data when the previous version's profile has none.
+- Fixed frame hitches while textures load on graphics cards that need ETC2 textures decoded on the CPU.
+- Fixed problems on Chimera Linux and other musl systems, including error messages that differed from the
+  ones Roblox expects.
+- Fixed the nightly AppImage build failing when a bundled GTK 4 was older than the one libadwaita needs.
+- Fixed a random crash on Wayland with NVIDIA drivers, where the game window closed after you let go of the
+  camera or left mouse lock. The log showed `wp_linux_drm_syncobj_surface_v1` error 3.
+- Fixed some menu actions being ignored. The Chat button on a profile now opens the Party tab with that
+  player, and clicking a search suggestion now runs the search instead of closing the search menu.
+- Fixed possible crashes when the game calls an Android function Nightcap did not provide, or releases the
+  same reference twice.
+- Fixed a possible hang on close when a web view process stayed open. Nightcap now stops waiting for the log
+  writer after 2 seconds.
+- Fixed a possible missing picture on graphics drivers that reject the low-latency present mode. Nightcap now
+  retries with the game's own mode.
+- Fixed a possible Wayland crash when the window first appears on the OpenGL graphics path.
+- Fixed a missing picture on machines where the graphics card runs a different driver than the one Nightcap
+  picked, such as an NVIDIA card on nouveau or a laptop with an Intel chip and an older second card. Nightcap
+  now picks the Vulkan driver that matches the running kernel driver, and says so when no card can run Vulkan.
+
+## [0.3.3] - 2026-10-04
+
+### Added
+
+- Joining a friend from a Roblox "follow user" link now works. Nightcap looks up which game they are in and
+  joins it.
+- Nix users get a desktop entry for the app.
+
+### Changed
+
+- Roblox textures now decode about 3 times faster, which shortens the stalls when a place loads and when new
+  parts of the map stream in. Thanks to @glook9001.
+
+### Fixed
+
+- `make update-roblox` no longer deletes your previous Roblox install when an import fails partway through. If
+  a step fails, the old files are put back, or kept in a folder whose path is printed. Thanks to @kimlherme.
+- A failed Roblox update now restores your previous version's records instead of leaving them half switched. A
+  damaged version file is rejected instead of being half read, and a temporary failure to start the startup
+  check no longer marks a working Roblox build as broken for good. Thanks to @kimlherme.
+- Fixed a possible crash when Roblox clears its audio queue while sound is still playing, and a memory leak in
+  lists of objects passed to Roblox's Java code. Thanks to @kimlherme.
+- Fixed a possible crash when the text overlay shuts down, a freeze when Roblox releases the mouse lock while
+  another release is already in progress, and network lookups that misread Roblox's options. Thanks to
+  @kimlherme.
+- Fixed the sky sometimes rendering with the wrong textures in the Vulkan renderer.
+- Clicking while a Roblox text box has focus no longer closes it. Only Roblox decides when a click ends
+  typing.
+- Going to another page in the web view, such as Friends from a profile, no longer closes the web view. It
+  crashed on every page change on Wayland systems whose GL setup GTK could not use.
+- Fixed a crash when Roblox's saved dark or light theme setting was missing or damaged.
+
+## [0.3.2] - 2026-09-29
+
+### Added
+
+- Performance recordings made with `--profile` now show how busy the CPU was during each frame, which makes it
+  easier to tell what caused a stutter.
+- Experimental support for ARM64 (`aarch64`) Linux, running Roblox's Android `arm64-v8a` client.
+
+### Fixed
+
+- When Roblox asks for a Google Play device check during login, Nightcap now answers right away that it isn't
+  supported. Before, the "Verifying you're not a bot" screen waited about a minute for an answer and then sent
+  you back to the login screen.
+- Solving a login challenge now closes its window. Before, Roblox's "challenge completed" signal was ignored
+  and the window stayed open. Thanks to @glook9001.
+- Login no longer stalls after you pass a verification check. Before, Roblox only saw the page's "challenge
+  completed" signal after a one-minute timeout, so it gave up and the login failed. On a Roblox build Nightcap
+  can't handle this way, the log says "WebViewProtocol getter not recognized" and web pages behave as before.
+- Login check windows and other web pages get 5 seconds to start instead of 3, so a slow start no longer
+  closes them. The log says how long each one took to open.
+- Less stutter while joining a game and while textures load in. In Blade Ball, loading hitches dropped by
+  about half, and the worst one went from 0.8 seconds to 0.55 seconds.
+- Clicking Play on a private server now joins right away. Before, nothing happened until you clicked a sidebar
+  tab like Home.
+- Middle click now reaches Roblox as the middle mouse button.
+- Scrolling follows your system's natural scrolling setting.
+- Fixed a crash on some x86_64 hosts when Roblox asked about a thread other than the one making the call.
+- Roblox updates no longer mix up the ARM64 and x86_64 compatibility profiles for the same version.
+- A partial or out-of-range user id in `MOCKTAIL_ROBLOX_USER_ID` or `MOCKTAIL_LOCAL_STORAGE_CURRENT_USER_ID`
+  is now ignored instead of being partly read.
+
+### Changed
+
+- `make flatpak` and `scripts/build_flatpak.sh` now build with 2 jobs by default instead of 4, so a local
+  Flatpak build is less likely to run out of memory. Set `FLATPAK_JOBS` or `MOCKTAIL_FLATPAK_JOBS` to use
+  more. Thanks to @glook9001.
+
+## [0.3.1] - 2026-09-20
+
+### Added
+
+- Each release carries a DEB, an RPM, and a pacman package beside the AppImage, with a `.sha256` for every
+  file. They install `/usr/bin/mocktail` and conflict with each other and with upstream's `mocktail` package.
+  Nightcap is in no distribution repository or the AUR; the recipes under `packaging/aur/nightcap{,-bin,-git}`
+  build from this repository locally.
+- The AppStream metadata lists the Nightcap releases, so software centres show the release history instead of
+  upstream's.
+
+### Fixed
+
+- ETC2 texture decoding no longer blocks the thread that submits the frame. Uploads decode on a background
+  dispatcher and the submit carries a timeline semaphore wait, so the GPU waits for the texture instead of the
+  render thread. Reading the application's compressed bytes moves to that dispatcher too whenever they are
+  already mapped. In Blade Ball the worst `vkQueueSubmit` fell from 140ms to 1ms, its p99 from 4.9ms to
+  0.05ms, and the total time spent in submits from 2534ms to 309ms. Frame interval is unchanged: the remaining
+  tail is the engine's own main-thread step. A device without the `timelineSemaphore` feature decodes inline
+  as before, as does a submit whose `pNext` already sizes arrays by its semaphore counts.
+- The mouse pointer jumped when a right-click camera drag ended, and drifted to the viewport edge during one.
+  The input router inferred pointer capture from SDL reporting zero absolute coordinates, which holds on X11
+  but not on Wayland, where the reported position accumulates the relative deltas and leaves the window.
+  Motion, button, and wheel events now carry the window's relative mouse mode. The right-click camera fallback
+  also only captures inside an experience, so the cursor stays free over the app surface.
+- Shutting the window down while an experience was starting or leaving could free the pointer capture owner
+  underneath the thread using it. Callers off the SDL thread now hold a reference for the length of their
+  call.
+- The TextBox caret did not move when a trailing space was typed in a single-line field. The final cluster
+  rect SDL_ttf reports stops at the last inked glyph, so the laid-out width is used there instead. Wrapped
+  layouts keep the clamp, because their width is the widest line rather than the last.
+- Every TextBox keystroke re-ran `TTF_Init`, a fontconfig sort, six `TTF_OpenFont` calls, and `TTF_Quit` on
+  the render thread. The overlay holds its opened fonts and reopens them only when the Roblox font or the
+  point size changes, keeping the current set when a reopen fails. Measured over 100 rasters, 1.59ms to 0.12ms
+  per keystroke.
+- Staged ETC2 copies now carry an explicit host-write barrier. A queue submission only makes host writes from
+  before it visible to the device, and an asynchronous decode writes after the submit, so without the barrier
+  those texels were not guaranteed to reach the copy that reads them.
+
+### Changed
+
+- `docs/PERFORMANCE.md` documents the GameMode settings to run with. A `desiredgov=powersave` in
+  `~/.config/gamemode.ini` overrides the packaged `performance` default and clocks the CPU down for the whole
+  session while still reporting an active performance request.
+
+## [0.3.0] - 2026-09-18
+
+### Added
+
+- Custom Discord presence. `integrations.discord_rpc.text.title` replaces the name in "Playing Nightcap", and
+  `integrations.discord_rpc.images` sets the large and small icons and their hover text. Text and image fields
+  accept `{place_name}`, `{place_icon}`, and `{creator_name}`. A field that expands an empty placeholder is
+  left out, and `text.state: ""` hides the state line.
+- The default Discord card now matches Sober: the title is "Roblox", the details line is "Playing
+  <experience>", the state is "by <creator>", and the Roblox badge sits inside the experience icon. The
+  creator comes from the same Roblox games request that already fetches the experience name. With
+  `show_place_name: false` the creator is hidden too, so the card shows only the title and timer.
+- `--profile <file>` writes a Chrome-format trace of the Vulkan adapter's work: presents, GPU waits, submits,
+  ETC2 texture decode, and pipeline and shader creation. Open it in ui.perfetto.dev. `docs/BENCHMARKING.md`
+  describes the benchmark runs, and `scripts/summarize_profile_trace.py` turns traces into a before and after
+  table.
+
+### Fixed
+
+- Texture uploads stalled the frame they were submitted on. ETC2 batches decoded on worker threads but were
+  then resampled one upload at a time on the submitting thread, which at the default 4x upscale is sixteen
+  times the decoded texels. Resampling now runs on the same worker pool, in two passes so mip level 0 still
+  resolves before the mips built from it. In a 70k-part place the worst `vkQueueSubmit` fell from 167ms to
+  92ms.
+- Most ETC2 batches decoded on a single thread. Workers were created and joined per batch, so the parallel
+  floor had to cover that cost and sat at a 1024x1024 image; batches under it ran on the caller, which was 54%
+  of all decode time in a 70k-part place. Decode workers are now a persistent pool, and the floor drops to a
+  128x128 image. Mean decode time in that place fell from 8.2ms to 4.7ms, and 11.8ms before both texture
+  fixes.
+- On CPUs with a wide core-speed spread, Feral GameMode pinned the process to the few fastest cores,
+  concentrating Roblox's worker pool onto them instead of spreading it. With `performance.gamemode: auto`, a
+  request that narrows the CPU affinity is now released again, which releases the pin. Set `pin_cores=no` in
+  `~/.config/gamemode.ini` to keep GameMode without the pinning, or `performance.gamemode: on` to accept it.
+  See `docs/PERFORMANCE.md`.
+- With `show_place_name: false`, Discord no longer shows the experience thumbnail or its name on hover.
+- The host main thread no longer spins on the engine's message pump, which cost about half a core and 146,000
+  empty calls a second. It now rests 100 µs between polls: sleeping when the governor is `performance`,
+  parking the core with TPAUSE on CPUs that have it, spinning otherwise. With GameMode setting the governor,
+  process CPU in a 60k-part place fell from 216% to 107% at the same 120 fps. `MOCKTAIL_ENGINE_PUMP_REST`
+  forces a mode; see `docs/PERFORMANCE.md`.
+- ETC2 uploads with a `bufferRowLength` or `bufferImageHeight` larger than the image read the padded rows as
+  packed data and decoded garbage.
+- ETC2 resampling created and joined worker threads on every batch. It now runs on the persistent decode pool.
+- A failed trace write left the profile writer thread waking every 250 ms for the rest of the session. It now
+  exits.
+- The `--profile` trace gains a `pump` slice for the engine's main-thread step.
+
+## [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.3.4...HEAD
+[0.3.4]: https://github.com/CoderDayton/nightcap/releases/tag/v0.3.4
+[0.3.3]: https://github.com/CoderDayton/nightcap/releases/tag/v0.3.3
+[0.3.2]: https://github.com/CoderDayton/nightcap/releases/tag/v0.3.2
+[0.3.1]: https://github.com/CoderDayton/nightcap/releases/tag/v0.3.1
+[0.3.0]: https://github.com/CoderDayton/nightcap/releases/tag/v0.3.0
+[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

@@ -1,3 +1,4 @@
+# Modified by vii from komaruworld/mocktail. See README "About this fork".
 # Copyright 2026 Mocktail Project Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -8,8 +9,8 @@
 
 cmake_minimum_required(VERSION 3.20)
 project(Mocktail
-  VERSION 1.0.3
-  DESCRIPTION "Android x86-64 Roblox compatibility runtime for Linux"
+  VERSION 0.3.4
+  DESCRIPTION "Android Roblox compatibility runtime for Linux"
   LANGUAGES CXX
 )
 
@@ -60,7 +61,7 @@ set(MOCKTAIL_DEFAULT_SIGNING_TRUST_MANIFEST
   CACHE FILEPATH
   "Fallback signing trust manifest used outside an installed runtime"
 )
-set(MOCKTAIL_DISCORD_APPLICATION_ID "1537088975720812655" CACHE STRING
+set(MOCKTAIL_DISCORD_APPLICATION_ID "1549428231927500843" CACHE STRING
   "Discord application ID baked into Mocktail Rich Presence releases"
 )
 string(LENGTH "${MOCKTAIL_DISCORD_APPLICATION_ID}"
@@ -125,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.
@@ -138,12 +141,7 @@ if(BUILD_TESTING)
   FetchContent_MakeAvailable(googletest)
 endif()
 
-add_library(mocktail_crypto_foundation STATIC
-  src/foundation/sha256.cc
-)
-add_library(Mocktail::CryptoFoundation ALIAS mocktail_crypto_foundation)
-target_include_directories(mocktail_crypto_foundation PUBLIC include)
-mocktail_apply_compile_options(mocktail_crypto_foundation)
+find_package(OpenSSL REQUIRED)
 
 include(${CMAKE_SOURCE_DIR}/cmake/MocktailPlatformGraphics.cmake)
 foreach(foundation_target IN ITEMS
@@ -201,12 +199,12 @@ target_include_directories(mocktail_bionic_stdio_runtime PUBLIC include)
 mocktail_apply_compile_options(mocktail_bionic_stdio_runtime)
 
 find_package(CURL REQUIRED)
-find_package(OpenSSL REQUIRED)
 find_package(nlohmann_json CONFIG REQUIRED)
 find_package(PkgConfig REQUIRED)
 pkg_check_modules(LIBYAML REQUIRED IMPORTED_TARGET yaml-0.1)
 pkg_check_modules(MINIZIP REQUIRED IMPORTED_TARGET minizip)
 pkg_check_modules(CAPSTONE REQUIRED IMPORTED_TARGET capstone)
+pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
 pkg_check_modules(GTK4 REQUIRED IMPORTED_TARGET gtk4)
 pkg_check_modules(LIBADWAITA REQUIRED IMPORTED_TARGET "libadwaita-1>=1.6")
 pkg_check_modules(WEBKITGTK6 REQUIRED IMPORTED_TARGET webkitgtk-6.0)
@@ -214,6 +212,7 @@ pkg_check_modules(WEBKITGTK6 REQUIRED IMPORTED_TARGET webkitgtk-6.0)
 add_library(mocktail_update STATIC
   src/update/android_manifest.cc
   src/update/apk_bundle.cc
+  src/update/apk_provider.cc
   src/update/apk_signature.cc
   src/update/apkpure_provider.cc
   src/update/candidate_approval.cc
@@ -223,6 +222,7 @@ add_library(mocktail_update STATIC
   src/update/payload_integrity.cc
   src/update/payload_store.cc
   src/update/readiness_canary.cc
+  src/update/unsafe_latest_runner.cc
   src/update/update_config.cc
   src/update/update_coordinator.cc
   src/update/zip_archive.cc
@@ -231,7 +231,6 @@ add_library(Mocktail::Update ALIAS mocktail_update)
 target_include_directories(mocktail_update PUBLIC include)
 target_link_libraries(mocktail_update PUBLIC
   Mocktail::Compat
-  Mocktail::CryptoFoundation
   CURL::libcurl
   OpenSSL::Crypto
   PkgConfig::LIBYAML
@@ -252,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)
@@ -269,13 +272,16 @@ 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
+  src/runtime/fleasion.cc
   src/runtime/game_mode.cc
   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
@@ -286,9 +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
@@ -298,6 +313,9 @@ add_library(mocktail_runtime STATIC
   src/runtime/startup_state_machine.cc
   src/runtime/supported_launch_policy.cc
   src/runtime/support_bundle.cc
+  src/runtime/system_proxy.cc
+  src/runtime/texture_memory_policy.cc
+  src/runtime/device_memory_profile.cc
 )
 add_library(Mocktail::Runtime ALIAS mocktail_runtime)
 target_include_directories(mocktail_runtime PUBLIC include)
@@ -328,9 +346,10 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND
 endif()
 target_link_libraries(mocktail_runtime PUBLIC Threads::Threads)
 target_link_libraries(mocktail_runtime PRIVATE
-  Mocktail::CryptoFoundation
+  OpenSSL::Crypto
   CURL::libcurl
   nlohmann_json::nlohmann_json
+  PkgConfig::GIO
   PkgConfig::LIBYAML
   ${CMAKE_DL_LIBS}
 )
@@ -379,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
@@ -421,6 +441,7 @@ target_link_libraries(mocktail_linker PUBLIC
   linker
   mocktail_compat
   mocktail_bionic_stdio_runtime
+  mocktail_bionic_abi_exports
 )
 mocktail_apply_compile_options(mocktail_linker)
 target_compile_definitions(mocktail_linker PUBLIC MOCKTAIL_USE_BIONIC_LINKER=1)
@@ -449,6 +470,7 @@ add_library(mocktail_window STATIC
   src/window/roblox_fullscreen_menu_request_gate.cc
   src/window/video_driver_policy.cc
   src/window/window.cc
+  src/window/window_creation_policy.cc
   src/window/window_fullscreen_request_gate.cc
   src/window/window_game_surface_bridge.cc
   src/window/window_pointer_capture_owner.cc
@@ -461,9 +483,10 @@ target_include_directories(mocktail_window PUBLIC src)
 mocktail_apply_compile_options(mocktail_window)
 target_link_libraries(mocktail_window PUBLIC
   Mocktail::PlatformSdl
+  Mocktail::SdlVulkanWsi
   SDL3::SDL3
   ${CMAKE_DL_LIBS}
-  PRIVATE Mocktail::Runtime
+  PRIVATE Mocktail::Runtime Mocktail::GlesTextOverlay Mocktail::GraphicsFoundation
 )
 
 add_library(mocktail_roblox_output_device_runtime STATIC
@@ -525,56 +548,25 @@ target_include_directories(mocktail_bionic_abi_exports
   PRIVATE src
 )
 mocktail_apply_compile_options(mocktail_bionic_abi_exports)
+# These exported Bionic FORTIFY symbols intentionally overlap glibc's
+# __*_chk entry points.  When the bridge is visible to whole-program LTO,
+# GCC can fold a fortified host call back into its own compatibility wrapper
+# and turn the resulting tail recursion into an infinite loop.  Keep this
+# translation unit opaque to interprocedural optimization and make its calls
+# to the host C library explicit external calls.
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+  set_property(SOURCE src/compat/bionic_abi_exports.cc APPEND PROPERTY
+    COMPILE_OPTIONS
+      -fno-lto
+      -fno-builtin
+  )
+endif()
 target_link_libraries(mocktail_bionic_abi_exports PRIVATE
   mocktail_bionic_stdio_runtime
   mocktail_window
   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
@@ -599,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}\""
@@ -612,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
@@ -628,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)
@@ -705,13 +702,24 @@ install(FILES
     config/roblox_signing_certificates.json
   DESTINATION "${MOCKTAIL_INSTALL_DATA_DIR}/metadata"
 )
-install(FILES packaging/space.bigrat.mocktail.desktop
-  DESTINATION "${CMAKE_INSTALL_DATADIR}/applications"
-)
-install(FILES packaging/space.bigrat.mocktail.metainfo.xml
+# The installed desktop entry names the binary by its install path, so it
+# launches from sessions whose PATH lacks the install prefix. Uses the prefix
+# given at install time, not the configure-time one.
+install(CODE "
+  file(READ \"${CMAKE_SOURCE_DIR}/packaging/io.github.CoderDayton.nightcap.desktop\"
+       MOCKTAIL_DESKTOP_ENTRY)
+  string(REPLACE \"Exec=env SDL_VIDEODRIVER=wayland,x11 mocktail %u\"
+         \"Exec=env SDL_VIDEODRIVER=wayland,x11 \${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_BINDIR}/mocktail %u\"
+         MOCKTAIL_DESKTOP_ENTRY \"\${MOCKTAIL_DESKTOP_ENTRY}\")
+  file(WRITE \"${CMAKE_BINARY_DIR}/io.github.CoderDayton.nightcap.desktop\"
+       \"\${MOCKTAIL_DESKTOP_ENTRY}\")
+  file(INSTALL \"${CMAKE_BINARY_DIR}/io.github.CoderDayton.nightcap.desktop\"
+       DESTINATION \"\${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DATADIR}/applications\")
+")
+install(FILES packaging/io.github.CoderDayton.nightcap.metainfo.xml
   DESTINATION "${CMAKE_INSTALL_DATADIR}/metainfo"
 )
-install(FILES packaging/space.bigrat.mocktail.svg
+install(FILES packaging/io.github.CoderDayton.nightcap.svg
   DESTINATION "${CMAKE_INSTALL_DATADIR}/icons/hicolor/scalable/apps"
 )
 set(MOCKTAIL_HICOLOR_ICON_SIZES
@@ -720,7 +728,7 @@ set(MOCKTAIL_HICOLOR_ICON_SIZES
 # Generated icons are committed, so ImageMagick is not a build dependency.
 foreach(icon_size IN LISTS MOCKTAIL_HICOLOR_ICON_SIZES)
   install(FILES
-      "packaging/icons/hicolor/${icon_size}x${icon_size}/apps/space.bigrat.mocktail.png"
+      "packaging/icons/hicolor/${icon_size}x${icon_size}/apps/io.github.CoderDayton.nightcap.png"
     DESTINATION
       "${CMAKE_INSTALL_DATADIR}/icons/hicolor/${icon_size}x${icon_size}/apps"
   )
@@ -753,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)
@@ -789,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)

FAQ.md

@@ -0,0 +1,79 @@
+<!-- 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 run multiple Roblox instances?
+
+No. Nightcap won't add multi-instance launching. It would mean working around
+Roblox's restrictions on running several clients. The [Roblox Terms of Use](https://en.help.roblox.com/hc/en-us/articles/115004647846-Roblox-Terms-of-Use)
+prohibit bypassing technical protections, and violating the terms can get your
+account suspended.
+
+Bloxstrap brought the option back in [v2.9.0](https://github.com/bloxstraplabs/bloxstrap/releases/tag/v2.9.0)
+with a "use at your own risk" warning, then removed it in
+[v2.10.0](https://github.com/bloxstraplabs/bloxstrap/releases/tag/v2.10.0)
+after Roblox added measures against running multiple clients.
+
+## Can I play in VR?
+
+Yes, as an experiment. VR lives on Nightcap's `vr` branch and is not in the
+releases yet. It works on Roblox builds 2998, 3092 and 3222. Install the
+[build dependencies](README.md#building), then switch to that branch and
+build:
+
+```bash
+git fetch origin
+git switch 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
+```
+
+The [README](README.md#experimental-vr) and [docs/VR.md](docs/VR.md) have the
+details, including how to try it without a headset.

Makefile

@@ -1,3 +1,4 @@
+# Modified by vii from komaruworld/mocktail. See README "About this fork".
 .DEFAULT_GOAL := all
 .PHONY: all build release debug test apk install register-url-handler release-runtime portable portable-test standalone appimage flatpak run-flatpak run run-smoke run-unlimited run-game run-input run-resize run-network auto-run run-gles run-angle update-roblox update-auto update-auto-launch payload-status payload-rollback support-bundle clean submodules help
 
@@ -14,10 +15,13 @@ PORTABLE_MODE ?= standalone
 PORTABLE_CANONICAL_MODE := $(if $(filter dynamic minimal,$(PORTABLE_MODE)),thin,$(if $(filter full static,$(PORTABLE_MODE)),standalone,$(PORTABLE_MODE)))
 PORTABLE_DIR ?= dist/mocktail-linux-x86_64-glibc-$(PORTABLE_CANONICAL_MODE)
 APPIMAGE ?= dist/Mocktail-x86_64.AppImage
+APPIMAGE_FORMAT ?= classic
+ANYLINUX_PACKAGER ?= quick-sharun
+ANYLINUX_APPIMAGETOOL ?= appimagetool
 PREFIX ?= /usr
 FLATPAK_BUILD_DIR ?= build-flatpak
-FLATPAK_MANIFEST ?= packaging/flatpak/space.bigrat.mocktail.json
-FLATPAK_JOBS ?= 4
+FLATPAK_MANIFEST ?= packaging/flatpak/io.github.CoderDayton.nightcap.json
+FLATPAK_JOBS ?= 2
 
 define build_native_runtime
 	@git submodule update --init --recursive
@@ -52,7 +56,7 @@ install: ## Install an already-built dynamic runtime (use: sudo make install)
 register-url-handler: build ## Select this build for Roblox website links
 	@./scripts/register_url_handler.sh --set-default \
 		--executable "$(abspath $(BINARY))" \
-		--desktop-file "$(abspath packaging/space.bigrat.mocktail.desktop)"
+		--desktop-file "$(abspath packaging/io.github.CoderDayton.nightcap.desktop)"
 
 test: ## Build and run all unit tests
 	$(call build_native_runtime,Debug,ON)
@@ -73,13 +77,11 @@ portable-test: release-runtime ## Verify portable packaging and relocation
 
 standalone: appimage ## Build the standalone x86-64 AppImage
 
-appimage: release-runtime ## Build AppImage (requires appimagetool)
-	@command -v appimagetool >/dev/null 2>&1 || { \
-		echo "appimagetool is required for make appimage" >&2; \
-		echo "Install it, then rerun make appimage." >&2; \
-		exit 1; \
-	}
-	@./scripts/package_portable.sh --build-dir "$(BUILD_DIR)" \
+appimage: release-runtime ## Build AppImage (APPIMAGE_FORMAT=classic|anylinux)
+	@MOCKTAIL_APPIMAGE_FORMAT="$(APPIMAGE_FORMAT)" \
+		MOCKTAIL_ANYLINUX_PACKAGER="$(ANYLINUX_PACKAGER)" \
+		MOCKTAIL_ANYLINUX_APPIMAGETOOL="$(ANYLINUX_APPIMAGETOOL)" \
+		./scripts/package_portable.sh --build-dir "$(BUILD_DIR)" \
 		--libc glibc --output "$(PORTABLE_DIR)" --mode "$(PORTABLE_MODE)" \
 		--appimage "$(APPIMAGE)"
 
@@ -90,7 +92,7 @@ flatpak: ## Build and install the local x86-64 Flatpak
 		--jobs "$(FLATPAK_JOBS)"
 
 run-flatpak: ## Run the installed Flatpak
-	@flatpak run space.bigrat.mocktail
+	@flatpak run io.github.CoderDayton.nightcap
 
 run: export MOCKTAIL_AUTO_EXIT_AFTER_PRESENT_MS = 0
 run: build ## Run the native binary interactively until the window is closed
@@ -128,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,18 +1,104 @@
-# Mocktail
+<!-- Modified by vii from komaruworld/mocktail. See "About this fork" below. -->
+<div align="center">
+  <img src="https://raw.githubusercontent.com/CoderDayton/nightcap/main/packaging/io.github.CoderDayton.nightcap.svg" alt="Nightcap logo" width="128">
+  <h1 style="margin-top: 5px;">
+    Nightcap
+    <br>
+    <a href="https://github.com/CoderDayton/nightcap/actions/workflows/ci.yml"><img src="https://github.com/CoderDayton/nightcap/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://github.com/CoderDayton/nightcap/stargazers"><img src="https://img.shields.io/github/stars/CoderDayton/nightcap?style=flat&logo=github" alt="Stars"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
+    <a href="https://discord.gg/DbAUG9hBFU"><img alt="Discord" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FDbAUG9hBFU%3Fwith_counts%3Dtrue&query=%24.approximate_member_count&label=Discord&logo=discord&logoColor=white&color=5865F2&suffix=%20members"></a>
+  </h1>
+</div>
 
-[![CI](https://github.com/komaruworld/mocktail/actions/workflows/ci.yml/badge.svg)](https://github.com/komaruworld/mocktail/actions/workflows/ci.yml)
-[![Stars](https://img.shields.io/github/stars/komaruworld/mocktail?style=flat&logo=github)](https://github.com/komaruworld/mocktail/stargazers)
-[![Downloads](https://img.shields.io/github/downloads/komaruworld/mocktail/total?logo=github)](https://github.com/komaruworld/mocktail/releases/latest)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-
-Mocktail runs the Android `x86_64` Roblox client on Linux, including a Linux
+Nightcap is Roblox on Linux, tuned for desktop play. It is a Mocktail fork
+that keeps up with Roblox updates, with extra bug fixes, custom assets and
+more. 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.
 
-Mocktail is an independent community project. It is not affiliated with Roblox
+Nightcap is an independent community project. It is not affiliated with Roblox
 Corporation or VinegarHQ and does not distribute the Roblox client.
 
+## 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.
+
+- **Keeps up with Roblox.** New Roblox versions work soon after they come out.
+- **Plays more games.** Nightcap answers a server check that some experiences
+  use, so you can join and stay in those too.
+- **Voice chat that keeps working.** Your microphone still works after a
+  Roblox update.
+- **Logging in works.** Verification checks and captchas finish instead of
+  hanging.
+- **The current Roblox look.** The new home screen and side menu, like on
+  Windows.
+- **Your own cursors, fonts and skies.** Drop files in
+  `~/.local/share/mocktail/asset_overlay` and Nightcap uses them. The layout
+  matches Sober's `asset_overlay` folder.
+- **Smoother mouse and a cooler PC.** Optional raw mouse input, and less CPU
+  use while idle.
+
+Everything else works the same as upstream. See
+[`textures/`](textures/README.md) for custom textures, a ready-made crosshair
+and the asset overlay folder, the [roadmap](docs/ROADMAP.md) for what is
+coming next, the [changelog](CHANGELOG.md) for what each release changed,
+[performance](docs/PERFORMANCE.md) for CPU load, heat and the knobs that change
+them, 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
+```
+
+## Distribution packages
+
+Each release also carries a DEB, an RPM, and a pacman package, with a
+`.sha256` beside every file on the
+[releases page](https://github.com/CoderDayton/nightcap/releases/latest):
+
+```bash
+sudo apt install ./nightcap_<version>_amd64.deb
+sudo dnf install ./nightcap-<version>-1.x86_64.rpm
+sudo pacman -U nightcap-<version>-1-x86_64.pkg.tar.zst
+```
+
+They install `/usr/bin/mocktail`, so they conflict with upstream's `mocktail`
+package.
+
+On Arch Linux, [`nightcap-git`](https://aur.archlinux.org/packages/nightcap-git)
+is on the AUR. It builds the current `main` branch and is maintained by
+[@dim-ghub](https://github.com/dim-ghub):
+
+```bash
+yay -S nightcap-git
+```
+
+Nightcap is in no other distribution repository.
+
+Or build and install from source using the steps under
+[Building](#building).
+
 ## How it works
 
 ```
@@ -20,91 +106,40 @@ 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 Mocktail. The last working copy is kept in case
+launch and is not bundled with Nightcap. The last working copy is kept in case
 an update fails.
 
-## Install with Flatpak
-
-Install the stable release from Flathub:
-
-```bash
-flatpak install flathub space.bigrat.mocktail
-flatpak run space.bigrat.mocktail
-```
-
-Nightly builds are produced automatically from the latest `main` branch:
-
-```bash
-flatpak install --user https://mocktail.bigrat.space/mocktail.flatpakref
-flatpak run space.bigrat.mocktail
-```
-
-## Install from the AUR
-
-Arch Linux users can install either the pinned source release (`mocktail`) or
-the current development version (`mocktail-git`) with an AUR helper:
-
-```bash
-paru -S mocktail-git
-# or
-yay -S mocktail-git
-```
-
-Use `mocktail` instead of `mocktail-git` to build the pinned release from
-source, or install the stable prebuilt package with `paru -S mocktail-bin` or
-`yay -S mocktail-bin`.
-
-## Install with DNF
-
-Fedora 44 users can install either the stable `mocktail` package or the
-`mocktail-nightly` package built from `main`:
-
-```bash
-sudo curl -fsSL https://mocktail.bigrat.space/rpm/mocktail.repo \
-  -o /etc/yum.repos.d/mocktail.repo
-sudo dnf install mocktail
-# or
-sudo dnf install mocktail-nightly
-```
-
-## Install with APT
-
-Ubuntu 26.04 users can install either the stable `mocktail` package or the
-`mocktail-nightly` package built from `main`:
-
-```bash
-sudo install -d -m 0755 /etc/apt/keyrings
-sudo curl -fsSL https://mocktail.bigrat.space/mocktail-packages.gpg \
-  -o /etc/apt/keyrings/mocktail.gpg
-echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/mocktail.gpg] https://mocktail.bigrat.space/apt mocktail main" | \
-  sudo tee /etc/apt/sources.list.d/mocktail.list >/dev/null
-sudo apt update
-sudo apt install mocktail
-# or
-sudo apt install mocktail-nightly
-```
-
-## Direct downloads
-
-Direct AppImage, DEB, and RPM downloads are available from the
-[Website](https://mocktail.bigrat.space/) and
-[GitHub Releases](https://github.com/komaruworld/mocktail/releases).
+A leftover `.previous_good-recovery.json` in the payload store marks pending
+recovery after a publication or restoration failure and blocks further payload
+publication and garbage collection. Check `current.json` and `previous_good.json`
+against the saved recovery state and fix the underlying problem before manually
+removing the marker.
 
 <details>
 <summary>Screenshots</summary>
 
-![Roblox home in Mocktail](assets/screenshots/flatpak-home.png)
+![Roblox home in Nightcap](assets/screenshots/flatpak-home.png)
 
-![Roblox gameplay in Mocktail](assets/screenshots/flatpak-gameplay-tower.png)
-
-![Roblox experience in Mocktail](assets/screenshots/flatpak-gameplay-lobby.png)
+![Roblox gameplay in Nightcap](assets/screenshots/flatpak-gameplay-tower.png)
 
 </details>
 
 ## FFlag overrides
 
 Put a JSON object in `$XDG_CONFIG_HOME/mocktail/fflags.json` (usually
-`~/.config/mocktail/fflags.json`). Mocktail applies it on the next launch.
+`~/.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.
+
+PC profiles also set `FIntFlyoutTestVariantRollout12` to `2`, which shows the
+desktop side panel menu. An explicit override takes precedence.
+
+PC profiles compile the app's menus to native code with
+`FFlagDebugLuauCodegenAll`, and turn it off while you are in a game. Setting
+it yourself turns the switching off and your value applies everywhere. See
+[docs/PERFORMANCE.md](docs/PERFORMANCE.md#native-code-in-the-menus).
 
 ```json
 {
@@ -112,15 +147,25 @@ Put a JSON object in `$XDG_CONFIG_HOME/mocktail/fflags.json` (usually
   "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.
+- `vr.frame_rate_limit` sets the cap in VR. It defaults to `unlimited`, so the
+  headset's refresh rate paces frames; use `-1` for Roblox's 60 FPS cap.
+- `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, Mocktail runs
+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.
+Vulkan, EGL, libplacebo, fontconfig, libcurl, OpenSSL, libelf, libyaml, libpng,
+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.
 
@@ -131,7 +176,7 @@ See the [FreeBSD Guide](packaging/freebsd/README.md) for setup and launch instru
 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 \
+  nlohmann-json3-dev libyaml-dev libpng-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
@@ -143,7 +188,7 @@ sudo apt install build-essential cmake git ninja-build pkg-config lld \
 
 ```bash
 sudo pacman -S --needed base-devel cmake git ninja pkgconf lld sdl3 sdl3_ttf \
-  curl openssl nlohmann-json libyaml libelf minizip capstone gtk4 \
+  curl openssl nlohmann-json libyaml libpng libelf minizip capstone gtk4 \
   libadwaita webkitgtk-6.0 libutf8proc fontconfig libglvnd \
   libplacebo vulkan-headers vulkan-icd-loader zlib
 ```
@@ -155,7 +200,8 @@ sudo pacman -S --needed base-devel cmake git ninja pkgconf lld sdl3 sdl3_ttf \
 ```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 \
+  nlohmann-json-devel libyaml-devel libpng-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
@@ -163,19 +209,105 @@ sudo dnf install gcc-c++ cmake git ninja-build pkgconf-pkg-config lld \
 </details>
 
 ```bash
-git clone --recurse-submodules https://github.com/komaruworld/mocktail.git
-cd mocktail
+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 build and install the Flatpak from source, install `flatpak-builder` and run
+`make flatpak`. It builds with 2 parallel jobs to keep memory use low. Pass
+`FLATPAK_JOBS=N` to `make flatpak`, or set `MOCKTAIL_FLATPAK_JOBS=N` for
+`scripts/build_flatpak.sh`, to change that.
+
+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
+```
+
+## Experimental VR
+
+Experimental OpenXR VR support on Linux `x86_64` using WiVRn or SteamVR/ALVR.
+
+VR works on these Roblox builds. On any other build, `--vr` stops at start-up
+and names them:
+
+| Build | Roblox version |
+| --- | --- |
+| 2998 | 2.736.1408 |
+| 3092 | 2.738.1397 |
+| 3222 | 2.742.1059 |
+
+### Build with VR
+
+VR support is compiled in when the OpenXR SDK submodule is checked out
+(`MOCKTAIL_ENABLE_VR` defaults to `AUTO`). Without the submodule the build
+skips VR. Pass `-DMOCKTAIL_ENABLE_VR=ON` to make a missing submodule an error,
+or `OFF` to leave VR out:
+
+```bash
+git submodule update --init third_party/OpenXR-SDK
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j4
+```
+
+VR stays off at runtime until you pass `--vr` or set `vr.mode: on` in
+`config.yaml`. `vr.mode: auto` starts in VR only when SteamVR is running with a
+headset connected.
+
+### Run
+
+Start WiVRn or SteamVR/ALVR and connect your headset first:
+
+```bash
+./build/mocktail --vr
+```
+
+The OpenXR runtime is detected automatically. To pick one manually:
+
+```bash
+MOCKTAIL_VR_RUNTIME=wivrn ./build/mocktail --vr
+# or
+MOCKTAIL_VR_RUNTIME=alvr MOCKTAIL_GRAPHICS_BACKEND=direct-vulkan ./build/mocktail --vr
+```
+
+If you previously set `XR_RUNTIME_JSON`, unset it before switching runtimes.
+Use `--no-vr` for desktop mode.
+
+A keyboard opens in the headset when a text box takes focus. The rest is in
+[docs/VR.md](docs/VR.md): menus and typing, every VR environment variable,
+adding a Roblox build, and testing without a headset.
+
+## 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.
+
 ## License
 
 [Apache License 2.0](LICENSE). Third-party components keep their own licenses.
 
 ## Support
 
-You can support the project by giving it a star or with cryptocurrency:
+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`

cmake/MocktailAudio.cmake

@@ -24,6 +24,7 @@ set_target_properties(mocktail_audio_core PROPERTIES
 add_library(Mocktail::AudioCore ALIAS mocktail_audio_core)
 
 add_library(mocktail_audio_sdl SHARED
+  ${MOCKTAIL_AUDIO_ROOT}/src/audio/sdl_audio_capture.cc
   ${MOCKTAIL_AUDIO_ROOT}/src/audio/sdl_audio_sink.cc
 )
 target_include_directories(mocktail_audio_sdl PUBLIC
@@ -62,6 +63,7 @@ add_library(Mocktail::FmodJavaAudioRuntime ALIAS
 
 add_library(mocktail_fmod_jni_audio_bridge STATIC
   ${MOCKTAIL_AUDIO_ROOT}/src/audio/fmod_jni_audio_bridge.cc
+  ${MOCKTAIL_AUDIO_ROOT}/src/audio/webrtc_jni_audio_bridge.cc
 )
 target_include_directories(mocktail_fmod_jni_audio_bridge PUBLIC
   ${MOCKTAIL_AUDIO_ROOT}/include
@@ -199,10 +201,4 @@ if(BUILD_TESTING AND TARGET GTest::gtest_main)
   gtest_discover_tests(fmod_jni_audio_bridge_test
     PROPERTIES ENVIRONMENT "SDL_AUDIODRIVER=dummy"
   )
-
-  add_test(NAME audio_readiness_gate_test
-    COMMAND bash
-      ${MOCKTAIL_AUDIO_ROOT}/tests/audio_readiness_gate_test.sh
-      ${MOCKTAIL_AUDIO_ROOT}/scripts/audio_readiness_gate.sh
-  )
 endif()

cmake/MocktailElfCompatibility.cmake

@@ -44,7 +44,7 @@ target_link_libraries(mocktail_compat PUBLIC
   nlohmann_json::nlohmann_json
   Threads::Threads
 )
-target_link_libraries(mocktail_compat PRIVATE Mocktail::CryptoFoundation)
+target_link_libraries(mocktail_compat PRIVATE OpenSSL::Crypto)
 target_compile_features(mocktail_compat PUBLIC cxx_std_17)
 
 if(COMMAND mocktail_apply_compile_options)

cmake/MocktailInput.cmake

@@ -13,13 +13,16 @@ get_filename_component(MOCKTAIL_INPUT_ROOT "${CMAKE_CURRENT_LIST_DIR}/.."
 )
 
 add_library(mocktail_input_runtime STATIC
+  ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_gamepad_input.cc
   ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_input_native_adapter.cc
   ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_input_router.cc
   ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_native_text_box_info_reader.cc
   ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_text_display_state.cc
   ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_text_editor.cc
+  ${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
@@ -31,18 +34,23 @@ 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)
 
 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
@@ -68,6 +76,15 @@ if(BUILD_TESTING AND TARGET GTest::gtest_main)
   )
   mocktail_apply_compile_options(roblox_text_display_state_test)
 
+  add_executable(roblox_text_font_resolver_test
+    ${MOCKTAIL_INPUT_ROOT}/tests/roblox_text_font_resolver_test.cc
+  )
+  target_link_libraries(roblox_text_font_resolver_test PRIVATE
+    Mocktail::InputRuntime
+    GTest::gtest_main
+  )
+  mocktail_apply_compile_options(roblox_text_font_resolver_test)
+
   add_executable(roblox_input_native_adapter_test
     ${MOCKTAIL_INPUT_ROOT}/tests/roblox_input_native_adapter_test.cc
   )
@@ -92,9 +109,7 @@ if(BUILD_TESTING AND TARGET GTest::gtest_main)
   gtest_discover_tests(roblox_input_router_test)
   gtest_discover_tests(roblox_text_editor_test)
   gtest_discover_tests(roblox_text_display_state_test)
+  gtest_discover_tests(roblox_text_font_resolver_test)
   gtest_discover_tests(roblox_input_native_adapter_test)
   gtest_discover_tests(roblox_native_text_box_info_reader_test)
-  add_test(NAME input_readiness_gate_synthetic
-    COMMAND bash ${MOCKTAIL_INPUT_ROOT}/tests/input_readiness_gate_test.sh
-  )
 endif()

cmake/MocktailPlatformGraphics.cmake

@@ -1,3 +1,4 @@
+# Modified by vii from komaruworld/mocktail. See README "About this fork".
 # Copyright 2026 Mocktail Project Authors
 # Licensed under the Apache License, Version 2.0.
 
@@ -9,9 +10,10 @@ get_filename_component(MOCKTAIL_PLATFORM_GRAPHICS_ROOT
 
 find_package(SDL3 3.4 REQUIRED CONFIG)
 find_path(MOCKTAIL_EGL_INCLUDE_DIR EGL/egl.h REQUIRED)
+find_path(MOCKTAIL_GLES3_INCLUDE_DIR GLES3/gl3.h REQUIRED)
 
 set(MOCKTAIL_WINDOW_ICON_PNG
-  "${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/packaging/icons/hicolor/48x48/apps/space.bigrat.mocktail.png"
+  "${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/packaging/icons/hicolor/48x48/apps/io.github.CoderDayton.nightcap.png"
 )
 set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
   "${MOCKTAIL_WINDOW_ICON_PNG}"
@@ -69,6 +71,7 @@ add_library(mocktail_platform_sdl STATIC
   ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/platform/sdl_application_metadata.cc
   ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/platform/sdl_display_refresh_capabilities.cc
   ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/platform/sdl_event_converter.cc
+  ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/platform/sdl_gamepad_manager.cc
   ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/platform/sdl_platform_runtime.cc
   ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/platform/sdl_text_clipboard.cc
   ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/platform/sdl_window_icon.cc
@@ -102,6 +105,18 @@ target_link_libraries(mocktail_graphics_foundation PRIVATE
 target_compile_features(mocktail_graphics_foundation PUBLIC cxx_std_17)
 add_library(Mocktail::GraphicsFoundation ALIAS mocktail_graphics_foundation)
 
+add_library(mocktail_gles_text_overlay STATIC
+  ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/graphics/gles_text_overlay_compositor.cc
+)
+target_include_directories(mocktail_gles_text_overlay
+  PUBLIC ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/include
+  PRIVATE ${MOCKTAIL_GLES3_INCLUDE_DIR}
+)
+target_link_libraries(mocktail_gles_text_overlay PUBLIC SDL3::SDL3)
+target_compile_features(mocktail_gles_text_overlay PUBLIC cxx_std_17)
+mocktail_apply_compile_options(mocktail_gles_text_overlay)
+add_library(Mocktail::GlesTextOverlay ALIAS mocktail_gles_text_overlay)
+
 add_library(mocktail_sdl_vulkan_wsi STATIC
   ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/graphics/sdl_vulkan_wsi.cc
   ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/src/graphics/android_vulkan_wsi_adapter.cc
@@ -119,6 +134,16 @@ target_compile_features(mocktail_sdl_vulkan_wsi PUBLIC cxx_std_17)
 add_library(Mocktail::SdlVulkanWsi ALIAS mocktail_sdl_vulkan_wsi)
 
 if(BUILD_TESTING AND TARGET GTest::gtest_main)
+  add_executable(gles_text_overlay_compositor_test
+    ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/tests/gles_text_overlay_compositor_test.cc
+  )
+  target_include_directories(gles_text_overlay_compositor_test PRIVATE
+    ${MOCKTAIL_GLES3_INCLUDE_DIR}
+  )
+  target_link_libraries(gles_text_overlay_compositor_test PRIVATE
+    Mocktail::GlesTextOverlay
+    GTest::gtest_main
+  )
   add_executable(bionic_egl_bridge_test
     ${MOCKTAIL_PLATFORM_GRAPHICS_ROOT}/tests/bionic_egl_bridge_test.cc
   )
@@ -152,6 +177,7 @@ if(BUILD_TESTING AND TARGET GTest::gtest_main)
     GTest::gtest_main
   )
   include(GoogleTest)
+  gtest_discover_tests(gles_text_overlay_compositor_test)
   gtest_discover_tests(bionic_egl_bridge_test)
   gtest_discover_tests(platform_graphics_foundation_test)
   gtest_discover_tests(display_refresh_capabilities_test)

cmake/MocktailVR.cmake

@@ -0,0 +1,116 @@
+# Copyright 2026 Mocktail Project Authors
+# Licensed under the Apache License, Version 2.0.
+
+include_guard(GLOBAL)
+
+# 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/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()
+  target_sources(mocktail_vr PRIVATE src/vr/openxr_probe.cc src/vr/openxr_preview.cc
+    src/vr/openxr_backend.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
+    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})
+  # SMAA's area and search lookup textures for vr.anti_aliasing: smaa.
+  if(NOT EXISTS "${CMAKE_SOURCE_DIR}/third_party/smaa/Textures/AreaTex.h")
+    message(FATAL_ERROR
+      "Initialize SMAA: git submodule update --init third_party/smaa")
+  endif()
+  target_include_directories(mocktail_vr PRIVATE "${CMAKE_SOURCE_DIR}/third_party/smaa")
+  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)
+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

@@ -1,3 +1,4 @@
+# Modified by vii from komaruworld/mocktail. See README "About this fork".
 # Mocktail configuration.
 # The file is created once with mode 0600. Mocktail never replaces your edits.
 
@@ -31,17 +32,47 @@ runtime:
   # active verified payload.
   # roblox_library: /absolute/path/to/libroblox.so
 
+appearance:
+  # String (default: roblox): use Roblox's saved account theme. Supported
+  # overrides: dark, light, or system (follow the desktop color scheme).
+  theme: roblox
+
 graphics:
   # String (default: direct-vulkan): graphics backend. Use opengl on hardware
   # without a working Vulkan driver; OpenGL ES 3.0 or newer is required.
   # Recommended values: direct-vulkan, opengl, system, angle-vulkan.
   backend: direct-vulkan
-  # String or integer (default: display): requested frame-rate policy.
-  # Supported values: display, unlimited, 30, 60, 120, 144, 240. Unlimited
-  # selects Roblox's unmodified 240-FPS scheduler maximum.
-  frame_rate_limit: display
-  # String (default: auto): presentation synchronization: auto, on, or off.
-  vsync: auto
+  # Optional string or integer: Mocktail frame-rate override. Leave commented
+  # (or use -1) to let Roblox Basic Settings own the cap. Supported overrides:
+  # display, unlimited, or any positive integer; fixed values are forwarded to
+  # DFIntTaskSchedulerTargetFps without a whitelist.
+  # frame_rate_limit: -1
+  # Optional presentation synchronization override: auto, on, or off. auto
+  # presents through the lowest-latency synchronized mode the driver offers
+  # unless frame_rate_limit is unlimited.
+  # vsync: off
+
+# vr:
+  # String (default: off): experimental VR through OpenXR on supported Roblox
+  # builds. off always starts on the desktop. on always 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
+  # String (default: fxaa): smooth jagged edges in the headset. Roblox draws
+  # the VR eyes without anti-aliasing, so each eye is filtered on its way to
+  # the headset. fxaa is the cheapest. smaa finds edges more precisely and
+  # keeps text and fine detail sharper, at a little more GPU time. 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
@@ -63,12 +94,34 @@ audio:
   # String (default: default): `default` follows the host system output.
   # To pin output, copy an exact SDL device name printed during startup.
   output_device: default
+  # String (default: default): input device name, `id:<number>` printed during
+  # startup, or `disabled`. IDs disambiguate duplicate names but may change
+  # between boots; prefer the exact device name when it is unique.
+  input_device: default
+
+input:
+  # Boolean (default: false): send mouse look deltas in the host's own units.
+  # They are otherwise scaled by the window's pixel density divided by the
+  # desktop display scale, which cancels to 1.0 unless fractional scaling makes
+  # the two disagree. Turn this on when first-person aiming feels too slow or
+  # too fast under fractional scaling. The pointer position is unaffected.
+  raw_mouse: false
 
 integrations:
-  discord_rpc:
-    # Boolean (default: false): publish Mocktail activity to Discord Desktop.
-    # This never signs in to Discord and never reads an account token.
+  fleasion:
+    # Boolean (default: false): trust Fleasion's CA without editing Roblox files.
     enabled: false
+    # String: match Fleasion's routing mode: env or hosts.
+    proxy_mode: env
+    # Integer: Fleasion's local HTTP proxy port in env mode.
+    proxy_port: 58443
+    # Optional absolute public CA path. Default: $XDG_CONFIG_HOME/Fleasion/proxy_ca/ca.crt
+    # or ~/.config/Fleasion/proxy_ca/ca.crt. Never select ca.key.
+    # ca_certificate: /home/user/.config/Fleasion/proxy_ca/ca.crt
+  discord_rpc:
+    # Boolean (default: true): publish Nightcap activity to Discord Desktop.
+    # This never signs in to Discord and never reads an account token.
+    enabled: true
     # Boolean (default: true): show the current Roblox experience name.
     show_place_name: true
     # Boolean (default: true): show how long the current session has run.
@@ -81,30 +134,51 @@ 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
 
 window:
-  # Integer (default: 1280): initial window width in pixels.
+  # Integer (default: 1280): initial window width in logical desktop units.
   width: 1280
-  # Integer (default: 720): initial window height in pixels.
+  # Integer (default: 720): initial window height in logical desktop units.
   height: 720
   # String (default: Roblox): window title.
   title: Roblox
+  # Boolean (default: false): render at physical display-pixel density instead
+  # of the logical desktop resolution. Enable only for sharper high-DPI output.
+  high_dpi: false
 
-# Optional host HTTP proxy. Uncomment both values together. The host must not
-# contain a scheme such as http://.
-# network:
-#   # String (optional, default: disabled): proxy host name or IP address.
-#   proxy_host: 127.0.0.1
-#   # Integer (optional, default: disabled): proxy TCP port from 1 to 65535.
-#   proxy_port: 8080
+network:
+  # Boolean (default: false): follow the host HTTP/SOCKS5 proxy and
+  # automatically use its current port. Do not combine with a fixed proxy.
+  use_system_proxy: false
+  # Optional fixed HTTP proxy. Uncomment both values together. The host must
+  # not contain a scheme such as http://.
+  # String (optional, default: disabled): proxy host name or IP address.
+  # proxy_host: 127.0.0.1
+  # Integer (optional, default: disabled): proxy TCP port from 1 to 65535.
+  # proxy_port: 8080
+  # Absolute path (optional): custom PEM CA bundle. Mocktail reads this file
+  # directly and does not replace it during Roblox payload updates.
+  # ca_bundle: /home/user/.config/mocktail/cacert.pem
 
 updates:
   # Boolean (default: true): check the latest Roblox version, derive an exact
@@ -112,7 +186,9 @@ updates:
   # backend, and promote only on success. An existing current payload is
   # preserved when probation fails.
   automatic: true
-  # String (default: apk-pure): direct x86_64 APK provider.
+  # String (default: apk-pure): direct x86_64 APK provider selection. Both
+  # accepted values resolve the provider chain, which currently starts with
+  # APKPure. Supported values: auto, apk-pure.
   source: apk-pure
   # Reserved for desktop update integrations. `mocktail_updater` itself never
   # launches another process after changing the active payload.

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,
@@ -42,6 +45,103 @@
       "allow_host_abi_bridges": true,
       "allow_host_constructor_replay": true,
       "reason": "Verified 2026-07-16 on the current host: independently signature-matched native allocator and pre-JNI state, 3479 constructors replayed without recovery, JNI_OnLoad and ASMA/V2 startup, 2988 Vulkan shaders, a real vkQueuePresentKHR, and explicit lifecycle teardown to Stopped; legacy executable patches and signal recovery remain disabled."
+    },
+    {
+      "version_name": "2.734.917",
+      "version_code": 2908,
+      "abi": "x86_64",
+      "elf_build_id": "63c5109637b7d7b2bdb8ed8f858023ff5ef49326",
+      "status": "supported",
+      "default_allowed": true,
+      "allow_legacy_binary_patches": false,
+      "allow_host_abi_bridges": true,
+      "allow_host_constructor_replay": true,
+      "user_game_settings_fullscreen_setter_rva": "0x44fee64",
+      "fmod_output_device_bridge": {
+        "vtable_rva": "0x6b7eee8",
+        "string_constructor_rva": "0x1cfd5ec",
+        "count_method_rva": "0x32736d2",
+        "info_method_rva": "0x3273772",
+        "current_method_rva": "0x3273722",
+        "select_method_rva": "0x32734a6"
+      },
+      "reason": "Verified 2026-08-28 on the current host: the machine-derived exact-Build-ID profile passed two isolated no-recovery Tier C Vulkan canaries; fullscreen state synchronization and Build-ID-scoped FmodAudioDevice output interposition were re-derived for the current payload; legacy executable patches and signal recovery remain disabled."
+    },
+    {
+      "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."
+    },
+    {
+      "version_name": "2.736.1408",
+      "version_code": 2998,
+      "abi": "x86_64",
+      "elf_build_id": "ade08266c67aee88ec9c1d00902150e1684dad3a",
+      "status": "supported",
+      "default_allowed": true,
+      "allow_legacy_binary_patches": false,
+      "allow_host_abi_bridges": true,
+      "allow_host_constructor_replay": true,
+      "user_game_settings_fullscreen_setter_rva": "0x45ad8aa",
+      "fmod_output_device_bridge": {
+        "vtable_rva": "0x6c58040",
+        "string_constructor_rva": "0x1d32df8",
+        "count_method_rva": "0x32d0ee0",
+        "info_method_rva": "0x32d0f80",
+        "current_method_rva": "0x32d0f30",
+        "select_method_rva": "0x32d0cb4",
+        "input_count_method_rva": "0x32d12dc",
+        "input_info_method_rva": "0x32d12ea",
+        "input_current_method_rva": "0x32d13a6",
+        "input_select_method_rva": "0x32d0a56"
+      },
+      "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"
+      }
     }
   ]
 }

config/roblox_host_abi_reference.json

@@ -1,64 +1,64 @@
 {
   "schema_version": 1,
-  "elf_build_id": "1686400865ae0e408cd7bd67de7a439625c6fd13",
-  "payload_sha256": "3e9c26c81186f93458ff65d8a8bc240c220974db02b8388b91340b77b336997d",
-  "payload_id": "2628-1686400865ae0e408cd7bd67de7a439625c6fd13",
-  "payload_path": "payloads/2628-1686400865ae0e408cd7bd67de7a439625c6fd13",
+  "elf_build_id": "ade08266c67aee88ec9c1d00902150e1684dad3a",
+  "payload_sha256": "4343a6a900d1fca27ff8e10b9d9c86bee40a5d0ba547cb29903b7769f4f42a9d",
+  "payload_id": "2998-ade08266c67aee88ec9c1d00902150e1684dad3a",
+  "payload_path": "payloads/2998-ade08266c67aee88ec9c1d00902150e1684dad3a",
   "reference": {
-    "elf_build_id": "d0cb1fa0deb3d9161b4cd77530cbcd2e50de3a21",
-    "payload_sha256": "92ca0e4d8bc4e1c7a37fc2b52544869299ec8b9a40ea8da96ebac66660e0b1af"
+    "elf_build_id": "63c5109637b7d7b2bdb8ed8f858023ff5ef49326",
+    "payload_sha256": "72c3b1a5c151b5ac0bfc5394ce3a91775884fbd777589ccab8ac1c4f9885f739"
   },
   "profile": {
-    "elf_build_id": "1686400865ae0e408cd7bd67de7a439625c6fd13",
+    "elf_build_id": "ade08266c67aee88ec9c1d00902150e1684dad3a",
     "bridge_entries": [
       {
-        "rva": "0x1c39ea2",
+        "rva": "0x1d2c1e2",
         "kind": "allocate",
         "label": "small-allocate"
       },
       {
-        "rva": "0x1fe4c84",
+        "rva": "0x1d2f43a",
         "kind": "usable_size",
         "label": "usable-size"
       },
       {
-        "rva": "0x203daae",
+        "rva": "0x21e68bf",
         "kind": "reallocate",
         "label": "reallocate"
       },
       {
-        "rva": "0x1c39c3a",
+        "rva": "0x1d2bf82",
         "kind": "allocate",
         "label": "allocate"
       },
       {
-        "rva": "0x1c8dbf8",
+        "rva": "0x1d47a63",
         "kind": "aligned_allocate",
         "label": "aligned-allocate-direct"
       },
       {
-        "rva": "0x1c3eb72",
+        "rva": "0x1d2f9d9",
         "kind": "free",
         "label": "free"
       }
     ],
     "data_seeds": {
-      "allocator_object_slot": "0x7030ae0",
-      "empty_string_slot": "0x703a7e8",
-      "jni_singleton_slot": "0x72a16d0",
+      "allocator_object_slot": "0x7652e70",
+      "empty_string_slot": "0x775fd28",
+      "jni_singleton_slot": "0x7bb4340",
       "jni_singleton_bytes": 1024,
-      "arena_initializer": "0x1c39f1d",
-      "allocator_thread_initializer": "0x2040817",
-      "arena_guard_slot": "0x71e92f0",
-      "arena_table_slot": "0x71e9380",
+      "arena_initializer": "0x1d2c5f8",
+      "allocator_thread_initializer": "0x1db7b57",
+      "arena_guard_slot": "0x7af0430",
+      "arena_table_slot": "0x7af04c0",
       "arena_table_slot_count": 4194304
     },
     "native_allocator": {
-      "allocate": "0x1c39c3a",
-      "deallocate": "0x1c3eb72"
+      "allocate": "0x1d2bf82",
+      "deallocate": "0x1d2f9d9"
     },
-    "init_array_offset": "0x6c2c9b0",
-    "init_array_count": 3481,
+    "init_array_offset": "0x7057818",
+    "init_array_count": 3570,
     "constructor_run_ranges": [
       {
         "begin": 2,
@@ -66,32 +66,32 @@
       },
       {
         "begin": 5,
-        "end_exclusive": 3481
+        "end_exclusive": 3570
       }
     ],
     "native_mimalloc_constructor_run_ranges": [
       {
         "begin": 2,
-        "end_exclusive": 3481
+        "end_exclusive": 3570
       }
     ],
     "native_mimalloc_thread_initializer_after_constructor": 2,
     "native_pre_jni_bootstrap": {
-      "registry_initializer": "0x1fe72e5",
-      "registry_slot": "0x71ed428"
+      "registry_initializer": "0x21e8e09",
+      "registry_slot": "0x7af4598"
     },
     "default_allocator_strategy": "native_mimalloc"
   },
   "derivation_anchors": {
     "signature_version": 1,
-    "allocator_object_initializer_rva": "0x1fbf1de",
-    "empty_string_initializer_rva": "0x1fc82b0",
-    "jni_singleton_initializer_rva": "0x1c39a34",
+    "allocator_object_initializer_rva": "0x21bde7d",
+    "empty_string_initializer_rva": "0x21c9a86",
+    "jni_singleton_initializer_rva": "0x1d2aec0",
     "constructor_rvas": {
-      "2": "0x1c3c764",
-      "3": "0x1c38c00",
-      "4": "0x1c39884",
-      "5": "0x1c39a34"
+      "2": "0x1d2f731",
+      "3": "0x1d2af84",
+      "4": "0x1d2bc08",
+      "5": "0x1d2aec0"
     }
   }
 }

config/roblox_payload.json

@@ -1,23 +1,24 @@
 {
   "schema_version": 1,
   "package": "com.roblox.client",
-  "version_name": "2.725.1142",
-  "version_code": 2546,
+  "version_name": "2.736.1408",
+  "version_code": 2998,
   "abi": "x86_64",
-  "elf_build_id": "d0cb1fa0deb3d9161b4cd77530cbcd2e50de3a21",
+  "elf_build_id": "ade08266c67aee88ec9c1d00902150e1684dad3a",
   "sha256": {
-    "libroblox": "92ca0e4d8bc4e1c7a37fc2b52544869299ec8b9a40ea8da96ebac66660e0b1af",
-    "base_apk": "eba476fec3020eaceb28436c1d160eb35d6689d8ffb060e09678535584babc7a",
-    "x86_64_split_apk": "5c4193c9700481079cee958b38ba9cbb97768b0a130b7f704ed084753f01ce2b"
+    "libroblox": "4343a6a900d1fca27ff8e10b9d9c86bee40a5d0ba547cb29903b7769f4f42a9d",
+    "base_apk": "a4a71ec39df6619a56ab7adce0959d1d60354835485b53806f4026914287ea86",
+    "x86_64_split_apk": "a4a71ec39df6619a56ab7adce0959d1d60354835485b53806f4026914287ea86"
   },
   "signing_certificates_sha256": [
-    "2bebd189e8d3106401347056c93d045b61e20e22d0c3cbed85474aeb00a3d12a",
     "44932ea35a17a267372d71b54d1a0cb3da0dca5113e94406ae2fe18090ba1477"
   ],
   "assets": {
-    "file_count": 1837
+    "file_count": 1836,
+    "sha256_tree": "caee48e11c194bc11852493f53ff67d5e2bb233172f12b87ea5fca97c0c10840"
   },
-  "source": "sober-update-service",
-  "imported_at": "2026-07-09T19:12:54Z",
-  "compatibility_status": "supported"
+  "source": "apk-pure-native",
+  "imported_at": "2026-08-31T16:30:19Z",
+  "compatibility_status": "supported",
+  "apk_layout": "monolithic"
 }

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/BENCHMARKING.md

@@ -0,0 +1,129 @@
+# Benchmarking
+
+A pull request that claims a speedup shows before and after numbers taken
+the way this guide describes. Numbers from different machines are not
+compared with each other. Each run is compared with a run on the same
+machine.
+
+## Two layers, two tools
+
+Roblox measures its own work. Nightcap measures the layer between Roblox and
+your driver.
+
+| Layer | What it covers | Tool |
+| --- | --- | --- |
+| Roblox | Scripts, physics, rendering jobs, network | Roblox's stats overlays, Shift+F4 and Shift+F5 in game |
+| Nightcap | Vulkan adapter: present, swapchain and GPU waits, submits, ETC2 texture decode, pipeline and shader creation | `--profile` |
+
+A Nightcap change should move the `--profile` numbers. If it only moves the
+Roblox overlay numbers, say so in the pull request, since the cause is then
+less direct.
+
+## Recording a trace
+
+```sh
+mocktail --profile ~/nightcap-before.json
+```
+
+The Vulkan adapter writes a Chrome-format trace to that file, a few times a
+second. The file is valid JSON after every write, so a session that crashes
+or is killed still leaves a readable trace. Exit from the Roblox menu when you are done. Open the file
+in [ui.perfetto.dev](https://ui.perfetto.dev) or `chrome://tracing`.
+
+Expect about 130 bytes per event, around 15 MB per minute at 240 FPS.
+Profiling is off unless `--profile` is given, and `MOCKTAIL_PROFILE_TRACE`
+does the same thing as the flag.
+
+### What the trace contains
+
+Each slice is named after the call it times, on the thread that made it.
+
+| Category | Slices | Arguments |
+| --- | --- | --- |
+| `present` | `vkQueuePresentKHR`: the whole adapter present, including the text overlay | `result` |
+| `present` | `host present`: the host driver's present, nested inside the slice above | |
+| `wait` | `vkAcquireNextImageKHR`, `vkAcquireNextImage2KHR`, `vkWaitForFences`, `vkWaitSemaphores`, `vkWaitSemaphoresKHR`, `vkQueueWaitIdle`, `vkDeviceWaitIdle` | |
+| `submit` | `vkQueueSubmit`, `vkQueueSubmit2`, `vkQueueSubmit2KHR` | `submits` |
+| `texture` | `etc2 decode`: CPU decode of ETC2 textures. On a device with a timeline semaphore this runs on the decode dispatcher, not the submitting thread | `uploads`, `compressed_bytes`, `decoded_bytes` |
+| `texture` | `etc2 gather`: the part of an asynchronous upload that stays on the submitting thread. Absent when the decode ran inline | `uploads`, `compressed_bytes`, `decoded_bytes`, `ticket` |
+| `texture` | `etc2 staging create`: creating a staging block for ETC2 uploads, when no block has room left | `bytes` |
+| `texture` | `etc2 staging destroy`: destroying empty staging blocks beyond the four kept idle | `buffers` |
+| `texture` | `etc2 release wait`: a command buffer reset waiting for its uploads' decode. Only waits of 0.1 ms or more are recorded | `ticket` |
+| `memory` | `vkAllocateMemory` | `bytes`, `type` (memory type index), `result` |
+| `memory` | `vkFreeMemory`, `vkUnmapMemory`: both include waiting for ETC2 decodes that still read that memory | |
+| `memory` | `vkMapMemory`, `vkCreateImage`, `vkDestroyImage` | |
+| `pipeline` | `vkCreateGraphicsPipelines`, `vkCreateComputePipelines` | `count`, `cache` (1 when a pipeline cache was passed), `result` |
+| `pipeline` | `vkCreateShaderModule` | `bytes`, `result` |
+| `pipeline` | `vkCreatePipelineCache` | `initial_bytes`, `result` |
+| `pump` | `nativeCallMessagesFromMainThread`: the engine's main-thread step, on the host main thread. Only calls of 20 µs or more are recorded; the empty polls between them are not. | `cpu_us`: CPU time the main thread used during the call. Far below the slice's duration means the step spent it waiting |
+
+The `frame interval (ms)` counter is the time between successive adapter
+presents. `vkQueuePresentKHR` time minus `host present` time is the adapter's
+own cost per frame.
+
+Two more counters cover the same interval. `present thread cpu (ms)` is the
+CPU time the thread that presents used in it, and is absent for a frame
+presented from a different thread than the one before. `process cpu (ms)` is
+the CPU time of every thread together, so dividing it by the frame interval
+gives the number of cores busy. A long frame with little present-thread CPU
+was spent waiting.
+
+`emulated texture (MB)` is the VRAM held by the decoded images that stand in
+for live ETC2/EAC textures, over every mip level and layer, upscaled where
+small-texture upscale applies. `compressed texture (MB)` is the size the same
+textures would take as ETC2/EAC. Both change only when such an image is
+created or destroyed. `summarize_profile_trace.py` prints each one's peak.
+
+## The benchmark runs
+
+Run every scenario before and after the change, on the same build type
+(`make build`), with the same `config.yaml`. Close other GPU-heavy apps.
+Record `graphics.frame_rate_limit` and `graphics.vsync` in the pull request,
+because a frame cap hides frame time gains.
+
+Record `~/.config/gamemode.ini` too, and do not change it between the before
+and after runs. `desiredgov` there decides the CPU governor for the whole
+session and therefore which engine pump mode is chosen, which moves process
+CPU by more than most changes under test. See
+[PERFORMANCE.md](PERFORMANCE.md).
+
+Frame interval p99 varies by 2 ms or more between identical runs, so a
+difference that size is not a result. Three runs per scenario is the minimum
+for any frame-time claim; slice totals for a specific subsystem are far less
+noisy and can be read from fewer.
+
+| Scenario | How to start | What to do | What it shows |
+| --- | --- | --- | --- |
+| Home screen, cold | `mocktail --profile home-cold.json` with an empty shader cache (below) | Wait 30 s on the home screen, exit | First-load stutter: `pipeline` and `texture` slices |
+| Tower of Hell | `mocktail --profile toh.json --launch-uri "roblox://experiences/start?placeId=1962086868"` | Stand still at spawn for 60 s, exit | Steady-state frame time on a light scene |
+| Murder Mystery 2 | `mocktail --profile mm2.json --launch-uri "roblox://experiences/start?placeId=142823291"` | Stay in the lobby for 60 s, exit | Frame time with many players and a busier scene |
+
+For the cold run, point the driver's shader cache at an empty directory, so
+your normal cache is left alone:
+
+```sh
+cache=$(mktemp -d)
+MESA_SHADER_CACHE_DIR="$cache" __GL_SHADER_DISK_CACHE_PATH="$cache" \
+  mocktail --profile home-cold.json
+```
+
+`MESA_SHADER_CACHE_DIR` applies to Mesa drivers (AMD, Intel) and
+`__GL_SHADER_DISK_CACHE_PATH` to the NVIDIA driver.
+
+Run each scenario three times and keep the median run, since one run can
+catch a background stall.
+
+## Comparing runs
+
+```sh
+scripts/summarize_profile_trace.py toh-before.json toh-after.json
+```
+
+This prints a Markdown table with one column per trace: frame count, frame
+interval mean, p50, p95, p99 and max, then count, total, mean, p99 and max
+for every slice name, largest total first. Paste the table into the pull
+request and attach both traces.
+
+For frame time, compare p95 and p99 as well as the mean. Stutter shows up in
+the tail first. For first-load work, compare the `total (ms)` rows of the
+`pipeline` and `texture` slices from the cold run.

docs/PERFORMANCE.md

@@ -0,0 +1,258 @@
+# Performance and CPU load
+
+What Nightcap does to your CPU and GPU, which knobs change it, and how to
+measure rather than guess.
+
+## GameMode core pinning
+
+Nightcap asks Feral GameMode for a performance session at startup
+(`performance.gamemode`, default `auto`). GameMode raises the CPU governor and
+the process priority, which helps.
+
+On a CPU with a wide spread of per-core maximum frequencies — Intel P-core and
+E-core parts, AMD parts with preferred cores — GameMode also pins the process
+to the fastest cores. On a 32-thread host that can mean 4 usable threads out of
+32. Roblox spreads its work across a worker pool, so the pin concentrates that
+pool onto a couple of physical cores instead of spreading it. Those cores sit
+near their boost ceiling and run hot while the rest of the chip idles.
+
+GameMode re-applies the pin roughly every 5 seconds, so widening the mask from
+inside the process does not hold. Releasing the request does release the pin.
+
+Under `auto`, Nightcap therefore checks its CPU affinity immediately after the
+request. If GameMode narrowed it, Nightcap ends the request and prints:
+
+```
+  [gamemode] released: it pinned this process to a subset of the CPUs, ...
+```
+
+The trade is that GameMode's governor and priority boost go with it. To keep
+those and lose only the pinning, turn pinning off for every game on the host.
+
+These are the settings to run with:
+
+```ini
+# ~/.config/gamemode.ini
+[general]
+desiredgov=performance
+
+[cpu]
+pin_cores=no
+park_cores=no
+```
+
+`desiredgov` is the one to check first. The packaged default in
+`/usr/share/gamemode/gamemode.ini` is already `performance`, but a value in
+your own file replaces it, and `desiredgov=powersave` there means GameMode
+clocks the CPU **down** for the whole session while still reporting
+`[gamemode] performance request active`. The symptoms are a low CPU clock
+under load, a GPU that never leaves its lower SM clocks, and the engine pump
+falling back to `tpause` — which costs about 70% of a core instead of 3%,
+because `sleep` is only chosen when the governor reads `performance`. On one
+13900K host, correcting `powersave` to `performance` took the process from
+177% CPU to 42% and the package from 70°C to 53-63°C, at the same frame rate.
+
+GameMode reads `$XDG_CONFIG_HOME`, `/usr/share/gamemode` and `/etc`, in that
+order. It does not read anything under Nightcap's own config directory, so this
+file has to live in one of those three places. The daemon reads it when it
+starts, so restart it after editing: `systemctl --user restart gamemoded`.
+
+Restarting the daemon drops the session of any game already running; relaunch
+the game for new settings to apply to it.
+
+`gamemoded` is D-Bus activated through
+`com.feralinteractive.GameMode.service`, so `systemctl --user stop gamemoded`
+does not hold — the next client request starts it again within seconds. To
+measure with GameMode genuinely off, mask it:
+
+```bash
+systemctl --user mask gamemoded     # and --unmask afterwards
+```
+
+The governor switch runs through polkit. Debian and Ubuntu only allow it for
+members of the `gamemode` group; without that, the daemon's journal shows
+`cpugovctl set performance: Not authorized` and the governor stays put while
+the session is otherwise active. Add yourself and log in again:
+
+```bash
+sudo usermod -aG gamemode "$USER"
+```
+
+Fedora and Arch allow any logged-in local user.
+
+Setting `performance.gamemode: on` accepts the pinning instead: `on` is an
+explicit request for GameMode, and Nightcap keeps the session whatever it does
+to the affinity. `off` never contacts the daemon.
+
+To see which CPUs the process may use:
+
+```bash
+pid=$(pgrep -x Main)
+for t in /proc/$pid/task/*; do taskset -pc "${t##*/}"; done
+```
+
+Two traps here. The engine process reports its name as `Main`, not
+`mocktail`; `pgrep -x mocktail` finds only the launcher, which sits near 0%
+CPU and tells you nothing. And `taskset -p` reads one thread, not the whole
+process, so a single call reports the main thread's mask and says nothing
+about the workers — which is where the game's load actually is.
+
+For the same reason, `ps -L -o psr=` shows which core each thread is running
+on right now, not which cores it is allowed on. On a hybrid CPU the scheduler
+preferring P-cores for runnable work is normal and is not a mask.
+
+## The main-thread pump
+
+Roblox posts its per-frame main-thread step at a time of its own choosing,
+and nothing signals the host when it does. The host main thread therefore
+polls `nativeCallMessagesFromMainThread`, and a post that waits more than a
+fraction of a millisecond costs a whole frame. Between polls the thread rests
+for 100 µs, and how it rests decides the CPU clock:
+
+| Mode | When | What it costs |
+| --- | --- | --- |
+| `sleep` | The governor is `performance`, which GameMode sets | The thread idles at about 3% of a core. The governor holds the clock. |
+| `tpause` | Otherwise, on a CPU with WAITPKG (Intel 12th gen and newer) | The core stays awake in a light C0 state. Frame rate holds; the OS books the time as busy, so the thread shows around 70% of a core, at lower power than a spin. |
+| `spin` | Otherwise | The core stays awake at full power. |
+
+Under a power-saving governor the CPU clocks a bursty core down unless some
+core stays awake, and Roblox's render thread then runs slower and drops
+frames. That is why `sleep` is not the default there. Startup prints the
+chosen mode:
+
+```
+  [main] engine pump rest: tpause (MOCKTAIL_ENGINE_PUMP_REST=sleep|tpause|spin)
+```
+
+`MOCKTAIL_ENGINE_PUMP_REST` forces a mode. `sleep` without the governor's help
+runs cooler for a few frames per second less; measure before keeping it.
+
+## Small texture upscaling
+
+`MOCKTAIL_SMALL_TEXTURE_UPSCALE` (default `4`) stores ETC2 textures of 64px or
+smaller at N times their width and height. At the default that is 16 times the
+pixels per affected texture.
+
+Upscaling alone adds no detail. Each original pixel becomes an N×N block of the
+same colour, and the GPU's filtering already blends a small texture that much
+when it draws it. The extra size only shows when a replacement PNG in
+`~/.config/mocktail/textures` has more detail than the original.
+
+The cost lands in two places. Decoding and resampling is CPU work on up to 8
+threads while textures load, which shows up as a burst rather than a steady
+load. The enlarged textures then stay in GPU memory for the session and cost
+extra sampling bandwidth on every frame that uses them. In Blade Ball the
+memory share is small: decoded textures came to 5.1 times their ETC2 size both
+with the default and with upscaling off. The `emulated texture (MB)` and
+`compressed texture (MB)` counters in a `--profile` trace give the figures for
+any game.
+
+That decode does not run on the thread that submits the frame. On a device
+with a timeline semaphore, uploads decode on a background dispatcher and the
+submit carries a semaphore wait, so the GPU waits for the texture instead of
+the render thread. In the trace this is the `etc2 decode` slice on its own
+thread, with only a negligible `etc2 gather` left on the submitting one. A
+device without that feature decodes inline as before.
+
+Set it to `1` to turn upscaling off:
+
+```bash
+MOCKTAIL_SMALL_TEXTURE_UPSCALE=1 mocktail
+```
+
+## Native code in the menus
+
+The home screen and avatar editor run Roblox's Lua app in the Luau interpreter,
+and its long frames come from that thread. PC profiles set
+`FFlagDebugLuauCodegenAll`, which compiles every script to native code. That
+makes the menus' Lua about 2.5 times cheaper for about 56 MB of compiled code.
+
+In a game the same flag compiles every game script too: Blade Ball grew from 7
+MB to about 300 MB and hit Roblox's native code limit, which shows warnings in
+F9. So Nightcap turns the flag off when a game starts joining and back on when
+you return to the menus. Roblox reads the flag each time it compiles a script,
+and a game's compiled code is freed when you leave it. Games run with Roblox's
+own per-script choice, the same as without the flag.
+
+The log shows each switch:
+
+```text
+[luau-codegen] menus-only switch at +0x<offset in libroblox.so>
+[luau-codegen] native code for all scripts off
+[luau-codegen] native code for all scripts on
+```
+
+Setting `FFlagDebugLuauCodegenAll` in `fflags.json` turns the switching off
+and your value applies everywhere. To keep the interpreter in the menus too:
+
+```json
+{
+  "FFlagDebugLuauCodegenAll": false
+}
+```
+
+## Frame rate and present mode
+
+`graphics.frame_rate_limit` (default `-1`) leaves Roblox's own in-game
+framerate cap in charge; Nightcap sets no `DFIntTaskSchedulerTargetFps`
+override. A fixed value forwards that number to the scheduler.
+
+In VR, `vr.frame_rate_limit` (`MOCKTAIL_VR_FRAME_RATE_LIMIT`) replaces
+`graphics.frame_rate_limit` and takes the same values. Its default is
+`unlimited`: the scheduler target goes to 240 and `xrWaitFrame` holds each
+frame to the headset's refresh rate. Set `-1` to restore Roblox's own cap, or a
+number such as `90` to pin it.
+
+`MOCKTAIL_VR_RENDER_SCALE` (default `1.0`, range `0.25`–`2.0`) scales each
+axis of the OpenXR runtime's recommended eye size. SteamVR's recommendation
+already includes its own supersampling, so on a Quest 2 at 90 Hz it is about
+2244x2352 per eye. If a frame misses the 11.1 ms budget, the runtime halves
+the rate to 45 FPS; `0.75` renders about 56% of the pixels.
+
+`MOCKTAIL_VR_UNPACED=1` is a benchmark mode. Roblox no longer waits for the
+headset between frames; each XR frame stays open across several Roblox frames
+and is submitted with the newest eyes once per display period. Pair it with a
+fixed scheduler target above 240 and `MOCKTAIL_VSYNC=off` to find the
+maximum rate:
+
+```bash
+MOCKTAIL_VR_UNPACED=1 MOCKTAIL_VR_FRAME_RATE_LIMIT=9999 MOCKTAIL_VSYNC=off mocktail --vr
+```
+
+Frames beyond the headset refresh are never displayed, and they all reuse the
+open frame's head pose, so expect judder. Do not play in this mode.
+
+`graphics.vsync` (default `auto`) selects the presentation mode. `auto` and
+`on` both pick the lowest-latency synchronized mode the driver offers, in
+order: `FIFO_LATEST_READY`, `MAILBOX`, `FIFO_RELAXED`, `FIFO`. The first two do
+not block the render thread on the display refresh, so the frame rate is
+governed by the in-game cap rather than by presentation. `off` selects
+`IMMEDIATE` and does not synchronize at all.
+
+If the frame rate is higher than your refresh rate, the extra frames are work
+you cannot see. Lower the in-game cap to your refresh rate first.
+
+## Measuring
+
+Shift+F4 in game shows Roblox's own scheduler jobs, with a millisecond cost and
+a percentage for each. It does not show Nightcap's threads — the Vulkan
+adapter, the ETC2 decode workers, the libc shim — so it is a reading on the
+game, not on the process.
+
+For the whole process:
+
+```bash
+top -H -p $(pgrep -x mocktail)      # per-thread CPU, sorted
+ps -L -o psr=,pcpu=,comm= -p $(pgrep -x mocktail)   # which core each thread is on
+nvidia-smi --query-gpu=utilization.gpu,temperature.gpu,power.draw --format=csv
+```
+
+A thread pinned near 100% while the frame rate is steady is a busy-wait. The
+one exception is the host main thread in `tpause` mode, which the OS reports
+as busy while the core is parked (see above). Load spread across many
+`RBX Worker` threads is the game's own scheduler, and its cost tracks the
+place you are in — part count, moving parts and joints all show in the
+Shift+F4 World section.
+
+`--profile <file>` writes a Chrome trace of the Vulkan adapter's work for
+ui.perfetto.dev. See [BENCHMARKING.md](BENCHMARKING.md).

docs/ROADMAP.md

@@ -0,0 +1,67 @@
+# 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: every field in the `discord_rpc` block, so a friend can see
+what you are playing and you can switch it all off in one click.
+- 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.
+
+## 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, with the experience name, creator,
+elapsed time, the experience icon with a Roblox badge, and a join button
+when the server is public. See the [FAQ](../FAQ.md) to switch it off.
+- Custom Discord presence: title, details, state, and large and small icons
+from `config.yaml`, with `{place_name}`, `{place_icon}`, and
+`{creator_name}` placeholders.
+- `--profile` writes a Chrome-format trace of the Vulkan adapter's work,
+including shader and pipeline creation, readable in `ui.perfetto.dev`.
+[BENCHMARKING.md](BENCHMARKING.md) fixes the experiences to measure and
+`scripts/summarize_profile_trace.py` builds the before and after table.
+- Texture uploads no longer stall the frame they land on: ETC2 decode and
+resampling run on a persistent worker pool.
+- Less stutter while joining an experience and while textures load in. See
+the [changelog](../CHANGELOG.md) for the numbers.
+- The host main thread rests between engine polls instead of spinning, and
+GameMode's core pinning is released, so Roblox's workers spread across
+every core. See [PERFORMANCE.md](PERFORMANCE.md).
+- 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.
+

docs/VR.md

@@ -0,0 +1,135 @@
+# VR
+
+Experimental OpenXR VR is opt-in: launch with `--vr`, or set `vr.mode` in
+`config.yaml`:
+
+- `off` (default) always starts on the desktop.
+- `on` always starts in VR.
+- `auto` starts in VR when SteamVR is already running with a connected
+  headset, ALVR included, and on the desktop otherwise. It never starts
+  SteamVR, so start SteamVR and connect the headset first.
+
+`--vr` and `--no-vr` override `vr.mode` for one launch. The older
+`vr.enabled: true`/`false` still works as `on`/`off`. Everything here only
+applies while VR is active. The [README](../README.md#experimental-vr) covers
+building and running.
+
+## Menus and typing
+
+The home menu uses Roblox's `More` button. The desktop side panel is turned
+off in VR, because the VR pointer cannot click it.
+
+When a text box takes focus (chat, search), a keyboard opens in front of you,
+below eye level. It is a full US layout without the function row or
+Ctrl/Alt. Point at a key and pull the trigger. While you point at the keyboard,
+the trigger types and does not click the game behind it. Hold Backspace to
+delete repeatedly. Shift applies to the next key and selects its upper symbol;
+Caps Lock stays on until you tap it again. Close dismisses the keyboard and
+leaves the text box. Set `MOCKTAIL_VR_KEYBOARD=0` to turn the keyboard off.
+
+## Environment variables
+
+## Runtime and display
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MOCKTAIL_VR_ENABLED` | `0` | Same as `--vr` (`1`) or `--no-vr` (`0`). |
+| `MOCKTAIL_VR_RUNTIME` | `auto` | OpenXR runtime: `auto`, `system`, `wivrn`, `steamvr` or `alvr`. `XR_RUNTIME_JSON` overrides it. |
+| `MOCKTAIL_VR_BACKEND` | `xr` | `native` keeps Roblox's stereo rendering without an OpenXR runtime, for debugging. |
+| `MOCKTAIL_VR_FRAME_RATE_LIMIT` | `unlimited` | Frame-rate cap in VR, same values as `graphics.frame_rate_limit` (also `vr.frame_rate_limit`). With `unlimited` the headset's refresh rate paces frames. |
+| `MOCKTAIL_VR_ANTI_ALIASING` | `fxaa` | Same as `vr.anti_aliasing`. Roblox draws the VR eyes without anti-aliasing, so each eye is filtered on its way to the headset (Vulkan only). `fxaa` is the cheapest; `smaa` finds edges more precisely and keeps text sharper; `off` sends them as rendered. |
+| `MOCKTAIL_VR_RENDER_SCALE` | `1.0` | Scales each axis of the runtime's recommended eye size, `0.25` to `2.0`. |
+| `MOCKTAIL_VR_UNPACED` | `0` | `1` stops waiting for the headset between frames, to measure the maximum frame rate. Frames past the headset refresh are not shown. Not for playing. |
+| `MOCKTAIL_VR_DESKTOP_MIRROR` | `1` | `0` stops copying the left eye to the desktop window. |
+| `MOCKTAIL_VR_MIRROR_SHM` | unset | A shared-memory name such as `/nightcap-mirror` publishes both eyes for an external viewer. The segment is private to your user. |
+| `MOCKTAIL_VR_KEYBOARD` | `1` | `0` turns off the in-headset keyboard. |
+
+## Hands and scale
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MOCKTAIL_VR_HAND_POSE_SOURCE` | `aim` | `grip` orients hands from the controller grip pose instead of the aim pose. |
+| `MOCKTAIL_VR_HAND_PITCH_OFFSET` | `-20` | Degrees added to Roblox's own hand pitch. |
+| `MOCKTAIL_VR_HAND_PITCH` | unset | Replaces the total hand pitch, in degrees. |
+| `MOCKTAIL_VR_WORLD_SCALE` | `1.0` | Scales head, hand and eye offsets. `MOCKTAIL_VR_EYE_OFFSET_SCALE` is an older name for it. |
+
+## Performance tracing
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MOCKTAIL_VR_PERF` | unset | `1` logs per-stage frame timings and counters once a second. `present_interval` is the frame time; `desktop_mirror`, `copy_record` and `copy_fence_wait` show time the CPU spent on VR copies. |
+| `MOCKTAIL_VR_MEASURE_START_NS`, `MOCKTAIL_VR_MEASURE_END_NS` | unset | Limit `MOCKTAIL_VR_PERF` to a `CLOCK_MONOTONIC` window. |
+| `MOCKTAIL_VR_POSE_LOG_INTERVAL` | `240` | Frames between head-pose log lines. |
+
+## Diagnostics builds
+
+These only work in builds configured with `-DMOCKTAIL_VR_DIAGNOSTICS=ON`.
+Release builds ignore them.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MOCKTAIL_VR_POSE_SOURCE` | `runtime` | `script` drives the head from a scripted motion instead of the headset, for testing without wearing it. |
+| `MOCKTAIL_VR_POSE_AMPLITUDE_POSITION`, `_YAW`, `_PITCH` | `0.25`, `0.5`, `0.17` | Scripted motion size, in metres and radians. |
+| `MOCKTAIL_VR_POSE_PERIOD_POSITION`, `_ROTATION` | `240`, `360` | Scripted motion period, in frames. |
+| `MOCKTAIL_VR_XR_EVIDENCE_DIR` | unset | Writes submitted eye images to this directory. |
+| `MOCKTAIL_VR_XR_EVIDENCE_INTERVAL` | `20` | Frames between evidence images. |
+
+## Adding a Roblox build
+
+VR needs addresses that are specific to each Roblox build. To use a supported
+build that is not the active one, point `--roblox-lib` at its `libroblox.so`.
+
+To add a build, run the offset finder on its library:
+
+```bash
+python3 scripts/find_roblox_vr_offsets.py --elf <libroblox.so> --output offsets.json
+```
+
+It needs the `capstone` Python package. Add its values to `kContracts` in
+`src/vr/roblox_vr_device_bridge.cc`. Nightcap checks those addresses against
+Roblox's code before it hooks anything, and leaves VR off if they do not
+match. To run the same checks on real libraries, set
+`MOCKTAIL_TEST_VR_PAYLOADS` to a folder of `<build>-<build id>/libroblox.so`
+payloads and run `ctest -R VrSupportedBuilds`.
+
+For a second opinion, solve the new build from the previous one and compare
+the two answers. It needs the previous build's HostAbi profile and
+compatibility manifest:
+
+```bash
+python3 scripts/roblox_abi_check.py --reference-lib <old libroblox.so> \
+  --reference-profile <old profile.json> \
+  --reference-compatibility config/roblox_compatibility.json \
+  --candidate-lib <new libroblox.so> --vr
+```
+
+It lists every field where the finder and the solver disagree and exits 0
+when they agree on all of them.
+
+## Testing without a headset
+
+[Monado](https://monado.freedesktop.org) can stand in for a headset. Its
+`qwerty` driver gives a head and two controllers that you move with the
+keyboard and mouse:
+
+```bash
+QWERTY_ENABLE=1 XRT_DEBUG_GUI=1 monado-service
+```
+
+Then, in another terminal:
+
+```bash
+XR_RUNTIME_JSON=/usr/share/openxr/1/openxr_monado.json ./build/mocktail --vr
+```
+
+The keys work while Monado's debug window has focus. The simulated display is
+small, so text in the headset view looks coarse.
+
+Two tests need an OpenXR runtime and skip without one. To run them, start
+Monado with no window and opt in:
+
+```bash
+XRT_COMPOSITOR_NULL=1 monado-service &
+XR_RUNTIME_JSON=/usr/share/openxr/1/openxr_monado.json MOCKTAIL_TEST_XR_GLES=1 \
+  ctest --test-dir build -R GlesVrTransportTest.OpenXr
+```

flake.lock

@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1785627969,
+        "narHash": "sha256-4dtXQk/NMePegK/nWp5NSeuZKLATItOq61lpEvmXqGw=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "427bf4bd9435fdf21321c8cc628c24efc14c0f7a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1787135253,
+        "narHash": "sha256-RD2kNWCG+Bjo6h+JVjWVNntZs2GtRoeY2xHjts/FNkA=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "ffb3c9b700e759be2ef13237c9d8f953b32a1e46",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "lastModified": 1785031560,
+        "narHash": "sha256-OmshNvn2vupOFpYinLUu+1Dnpu4n7Q5N3ggGVNHpkUI=",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "rev": "0e79af5e3d4dcfcd676ab5ba3f95d2e3352e078c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,73 @@
+{
+  description = "Experimental Roblox compatibility runtime for Linux and FreeBSD";
+
+  inputs = {
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs =
+    inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [
+
+      ];
+      systems = [
+        "x86_64-linux"
+        # "aarch64-linux"
+        # "aarch64-darwin"
+        # "x86_64-darwin"
+      ];
+      perSystem =
+        {
+          pkgs,
+          ...
+        }:
+        let
+          package = pkgs.callPackage ./packaging/nix/package.nix { };
+        in
+        {
+          packages.default = package;
+          devShells.default = pkgs.mkShell {
+            inputsFrom = [ package ];
+
+            # nixpkgs installs the header we need under include/libutf8proc
+            NIX_CFLAGS_COMPILE = "-I${pkgs.libutf8proc}/include/libutf8proc";
+
+            nativeBuildInputs = with pkgs; [
+              cmake
+              git
+              lld
+              ninja
+              pkg-config
+              vulkan-headers
+
+              llvmPackages_22.clang-tools
+              llvmPackages_22.libclang
+
+              # debugging
+              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}"
+
+              # nix packages graphics drivers differently, and mocktail will still work if it cannot guarantee symbols
+              export MOCKTAIL_REQUIRE_REAL_GRAPHICS=0
+            '';
+          };
+        };
+      flake = { };
+    };
+}

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);
@@ -71,6 +88,31 @@ int mocktail_pthread_mutex_destroy(pthread_mutex_t* mutex);
 int mocktail_pthread_mutex_lock(pthread_mutex_t* mutex);
 int mocktail_pthread_mutex_trylock(pthread_mutex_t* mutex);
 int mocktail_pthread_mutex_unlock(pthread_mutex_t* mutex);
+int mocktail_pthread_once(pthread_once_t* once_control,
+                          void (*init_routine)(void));
+int mocktail_pthread_spin_init(pthread_spinlock_t* lock, int pshared);
+int mocktail_pthread_spin_destroy(pthread_spinlock_t* lock);
+int mocktail_pthread_spin_lock(pthread_spinlock_t* lock);
+int mocktail_pthread_spin_trylock(pthread_spinlock_t* lock);
+int mocktail_pthread_spin_unlock(pthread_spinlock_t* lock);
+int mocktail_pthread_barrier_init(pthread_barrier_t* barrier,
+                                  const pthread_barrierattr_t* attr,
+                                  unsigned count);
+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;

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

@@ -2,6 +2,8 @@
 #define MOCKTAIL_COMPAT_BIONIC_PTHREAD_CREATE_RUNTIME_H_
 
 #include <pthread.h>
+#include <sched.h>
+#include <sys/types.h>
 
 #include <cstddef>
 
@@ -23,10 +25,17 @@ 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(
+    pthread_t thread, int policy, const struct sched_param* parameters);
+extern "C" int mocktail_bionic_sched_setscheduler(
+    pid_t tid, int policy, const struct sched_param* parameters);
 
 #endif  // MOCKTAIL_COMPAT_BIONIC_PTHREAD_CREATE_RUNTIME_H_

include/compat/bionic_rwlock_runtime.h

@@ -3,8 +3,9 @@
 
 #include <pthread.h>
 
-// Bionic and glibc pthread_rwlock_t storage is not ABI-compatible. The guest
-// address is an opaque key; the host object lives entirely in this runtime.
+// Bionic pthread_rwlock_t is a state word in guest storage. rdlock/wrlock/
+// unlock use __atomic_* and futex on that word. Zero-initialized storage
+// still locks.
 extern "C" {
 
 int mocktail_bionic_pthread_rwlock_init(pthread_rwlock_t* rwlock,

include/compat/bionic_semaphore_runtime.h

@@ -3,8 +3,9 @@
 
 #include <semaphore.h>
 
-// Bionic and glibc use different sem_t representations. These exports keep
-// host semaphore objects out of guest storage and key them by guest address.
+// Bionic sem_t is a count word in guest storage (value << 1, shared bit 0).
+// Wait/post use __atomic_* and futex on that word so inlined guest futex
+// waiters wake. Process-shared semaphores are rejected.
 extern "C" {
 
 int mocktail_bionic_sem_init(sem_t* semaphore, int process_shared,

include/compat/bionic_stdio_runtime.h

@@ -5,6 +5,7 @@
 
 #include <cstdarg>
 #include <cstddef>
+#include <cstdint>
 #include <cstdio>
 #include <cwchar>
 
@@ -17,12 +18,6 @@ namespace mocktail::compat {
 constexpr size_t kBionicFileSize = 152;
 constexpr size_t kBionicStandardStreamCount = 3;
 
-FILE* TranslateBionicFile(FILE* stream) noexcept;
-void* BionicFileArraySymbolAddress() noexcept;
-void* BionicStdinSymbolAddress() noexcept;
-void* BionicStdoutSymbolAddress() noexcept;
-void* BionicStderrSymbolAddress() noexcept;
-
 }  // namespace mocktail::compat
 
 extern "C" {
@@ -31,8 +26,31 @@ alignas(sizeof(void*)) extern unsigned char
     __sF[mocktail::compat::kBionicStandardStreamCount]
         [mocktail::compat::kBionicFileSize];
 
+}  // extern "C"
+
+namespace mocktail::compat {
+
+inline FILE* TranslateBionicFile(FILE* stream) noexcept {
+  const uintptr_t address = reinterpret_cast<uintptr_t>(stream);
+  if (__builtin_expect(address == reinterpret_cast<uintptr_t>(&__sF[0]), 0)) {
+    return stdin;
+  }
+  if (__builtin_expect(address == reinterpret_cast<uintptr_t>(&__sF[1]), 0)) {
+    return stdout;
+  }
+  if (__builtin_expect(address == reinterpret_cast<uintptr_t>(&__sF[2]), 0)) {
+    return stderr;
+  }
+  return stream;
 }
 
+void* BionicFileArraySymbolAddress() noexcept;
+void* BionicStdinSymbolAddress() noexcept;
+void* BionicStdoutSymbolAddress() noexcept;
+void* BionicStderrSymbolAddress() noexcept;
+
+}  // namespace mocktail::compat
+
 // FILE values returned by host fopen/fdopen pass through unchanged. Pointers
 // into Bionic's ABI-sized __sF array are translated to the corresponding host
 // standard stream at this single boundary.

include/compat/build_profile.h

@@ -1,6 +1,9 @@
 #ifndef MOCKTAIL_COMPAT_BUILD_PROFILE_H_
 #define MOCKTAIL_COMPAT_BUILD_PROFILE_H_
 
+#include <array>
+
+#include <cstddef>
 #include <cstdint>
 #include <optional>
 #include <string>
@@ -22,6 +25,45 @@ struct FmodOutputDeviceBridgeProfile {
   std::uintptr_t info_method_rva = 0;
   std::uintptr_t current_method_rva = 0;
   std::uintptr_t select_method_rva = 0;
+  // Roblox 2.738 inserted device-list methods before the current/select slots.
+  int vtable_layout_version = 1;
+
+  // Optional exact-build input count/info/current/select methods.
+  std::array<std::uintptr_t, 4> input_method_rvas{};
+  bool has_input_devices() const { return input_method_rvas[0] != 0; }
+  std::array<std::size_t, 4> input_vtable_indexes() const {
+    return vtable_layout_version == 2
+               ? 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;
+  }
+  std::size_t current_vtable_index() const {
+    return vtable_layout_version == 2 ? 8 : 7;
+  }
+  std::size_t select_vtable_index() const {
+    return vtable_layout_version == 2 ? 19 : 17;
+  }
+};
+
+// 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 {
@@ -41,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/fmod_output_device_contract.h

@@ -0,0 +1,42 @@
+#ifndef MOCKTAIL_COMPAT_FMOD_OUTPUT_DEVICE_CONTRACT_H_
+#define MOCKTAIL_COMPAT_FMOD_OUTPUT_DEVICE_CONTRACT_H_
+
+#include <cstddef>
+#include <initializer_list>
+#include <string_view>
+
+namespace mocktail::compat {
+
+// The 2.738 integer-index selector adds a feature-flag dispatch before the
+// count/clamp/setDriver path. Keep the calling convention, count slot (5),
+// object offset (0x28), and branch into that path exact. Only relocated
+// addresses and non-local branch/call targets vary between builds.
+inline constexpr char kFmodDeviceListsSelectContract[] =
+    "\x55\x48\x89\xe5\x41\x57\x41\x56\x41\x54\x53\x48\x83\xec\x50\x41"
+    "\x89\xf7\x49\x89\xfe\x4c\x8b\x25\x00\x00\x00\x00\x49\x8b\x04\x24"
+    "\x48\x89\x45\xd8\x80\x3d\x00\x00\x00\x00\x00\x74\x25\x49\x8b\x04"
+    "\x24\x48\x3b\x45\xd8\x0f\x85\x00\x00\x00\x00\x4c\x89\xf7\x44\x89"
+    "\xfe\x48\x83\xc4\x50\x5b\x41\x5c\x41\x5e\x41\x5f\x5d\xe9\x00\x00"
+    "\x00\x00\x49\x8b\x06\x4c\x89\xf7\xff\x50\x28\x44\x39\xf8\x0f\x8e"
+    "\x00\x00\x00\x00\x31\xdb\x45\x85\xff\x41\x0f\x4f\xdf\x49\x8b\x7e"
+    "\x28\x89\xde\xe8\x00\x00\x00\x00";
+inline constexpr std::size_t kFmodDeviceListsSelectContractSize =
+    sizeof(kFmodDeviceListsSelectContract) - 1;
+
+inline bool HasFmodDeviceListsSelectContract(std::string_view code) {
+  if (code.size() < kFmodDeviceListsSelectContractSize) return false;
+  for (std::size_t index = 0; index < kFmodDeviceListsSelectContractSize;
+       ++index) {
+    bool relocated = false;
+    for (const std::size_t start : {24, 38, 55, 78, 96, 116}) {
+      if (index >= start && index < start + 4) relocated = true;
+    }
+    if (!relocated && code[index] != kFmodDeviceListsSelectContract[index])
+      return false;
+  }
+  return true;
+}
+
+}  // namespace mocktail::compat
+
+#endif  // MOCKTAIL_COMPAT_FMOD_OUTPUT_DEVICE_CONTRACT_H_

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/host_abi_profile_loader.h

@@ -54,6 +54,8 @@ ExternalHostAbiProfileResult InitializeHostAbiProfileFromEnvironment(
 const HostAbiProfile* FindLoadedExternalHostAbiProfile(
     std::string_view build_id) noexcept;
 
+void SetHostAbiProfileHashingFaultForTesting(bool enabled) noexcept;
+
 }  // namespace mocktail::compat
 
 #endif  // MOCKTAIL_COMPAT_HOST_ABI_PROFILE_LOADER_H_

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 {
@@ -59,6 +65,8 @@ struct RobloxCredentialView {
 };
 
 using RobloxCredentialProvider = RobloxCredentialView (*)(const void *context);
+using RobloxCookieGetter = jstring (*)(JNIEnv* env, jclass clazz,
+                                       jstring domain);
 
 jobject CreateAndroidConfiguration(JNIEnv *env);
 
@@ -80,6 +88,67 @@ struct FmodAudioDeviceCallbacks {
   void (*shutdown)(void *context) = nullptr;
 };
 
+// Parameters passed by WebRtcAudioManager's constructor to the guest's
+// nativeCacheAudioParameters(IIIZZZZZZZIIJ)V. Buffer sizes are PCM frames,
+// not bytes. Querying them must not open a microphone.
+struct WebRtcAudioManagerParameters {
+  int sample_rate_hz = 0;
+  int output_channels = 0;
+  int input_channels = 0;
+  bool hardware_aec = false;
+  bool hardware_agc = false;
+  bool hardware_ns = false;
+  bool low_latency_output = false;
+  bool low_latency_input = false;
+  bool pro_audio = false;
+  bool aaudio = false;
+  int output_buffer_size_frames = 0;
+  int input_buffer_size_frames = 0;
+};
+
+struct WebRtcAudioManagerCallbacks {
+  bool (*get_parameters)(void* context,
+                         WebRtcAudioManagerParameters* parameters) = nullptr;
+  bool (*init)(void* context, const void* identity) = nullptr;
+  void (*dispose)(void* context, const void* identity) = nullptr;
+  void (*set_microphone_mute)(void* context, bool muted) = nullptr;
+};
+
+using WebRtcAudioRecordDataCallback = void (*)(void *context,
+                                               const void *identity,
+                                               std::size_t size_bytes);
+
+// Host implementation of org/webrtc/voiceengine/WebRtcAudioRecord. Init
+// returns the number of PCM frames in the stable direct buffer, or -1.
+struct WebRtcAudioRecordCallbacks {
+  int (*init)(void *context, const void *identity, int sample_rate_hz,
+              int channels, WebRtcAudioRecordDataCallback data_callback,
+              void *data_context, void **direct_buffer,
+              std::size_t *direct_buffer_capacity) = nullptr;
+  bool (*start)(void *context, const void *identity) = nullptr;
+  bool (*stop)(void *context, const void *identity) = nullptr;
+  void (*close)(void *context, const void *identity) = nullptr;
+  void (*shutdown)(void *context) = nullptr;
+};
+
+using WebRtcAudioTrackDataCallback = void (*)(void *context,
+                                              const void *identity,
+                                              std::size_t size_bytes);
+
+// Host implementation of org/webrtc/voiceengine/WebRtcAudioTrack. Init
+// returns the emulated Android AudioTrack buffer size in bytes, or -1.
+struct WebRtcAudioTrackCallbacks {
+  int (*init)(void *context, const void *identity, int sample_rate_hz,
+              int channels, double buffer_size_factor,
+              WebRtcAudioTrackDataCallback data_callback, void *data_context,
+              void **direct_buffer,
+              std::size_t *direct_buffer_capacity) = nullptr;
+  int (*buffer_size_frames)(void *context, const void *identity) = nullptr;
+  bool (*start)(void *context, const void *identity) = nullptr;
+  bool (*stop)(void *context, const void *identity) = nullptr;
+  void (*close)(void *context, const void *identity) = nullptr;
+};
+
 // Guest JNI threads only publish Android window flags. The host callback must
 // marshal SDL work onto the main thread.
 struct AndroidWindowCallbacks {
@@ -130,6 +199,11 @@ struct MessageBusRequestHandlerCallbacks {
   std::string (*run)(void *context, JNIEnv *env, jstring message) = nullptr;
 };
 
+struct MessageBusAsyncRequestHandlerCallbacks {
+  void (*run)(void* context, JNIEnv* env, jstring message,
+              jstring response_id) = nullptr;
+};
+
 // Dispatch accepts Callback.onItemSet(String) only on a receiver created by
 // this VM. The context stays alive while the callback runs.
 struct MemStorageCallbackCallbacks {
@@ -194,10 +268,12 @@ public:
 
   JavaVM *GetJavaVM() { return java_vm_; }
 
-  // Resolves the process pseudo-VM that owns an exact JavaVM pointer. Returns
+  // Resolves the live pseudo-VM that owns an exact JavaVM pointer. Returns
   // null for foreign VMs and after the owner is destroyed.
   static VM *FromJavaVM(JavaVM *java_vm);
 
+  // Binds this thread's JNI environment to this VM. Switching owners must
+  // not reuse the previous VM's native function table.
   JNIEnv *GetJNIEnv();
 
   std::size_t GetClassCount() const { return class_registry_.size(); }
@@ -228,6 +304,9 @@ public:
   // retained privately and returned instead until the provider is cleared.
   bool CopyRobloxCredentialFromProvider(std::string *credential) const;
 
+  void SetRobloxCookieGetter(RobloxCookieGetter getter);
+  bool RefreshRobloxCredentialFromEngine(JNIEnv* env);
+
   void SetRobloxCredentialSink(std::shared_ptr<void> context,
                                const RobloxCredentialSinkCallbacks &callbacks);
   void ClearRobloxCredentialSink();
@@ -250,6 +329,55 @@ public:
                                     const std::uint8_t *data, std::size_t size);
   bool DispatchFmodAudioDeviceClose(const void *identity);
 
+  void SetWebRtcAudioManagerCallbacks(
+      std::shared_ptr<void> context,
+      const WebRtcAudioManagerCallbacks& callbacks);
+  void ClearWebRtcAudioManagerCallbacks();
+  void RegisterWebRtcAudioManagerNative(const char* name, const char* signature,
+                                        void* function);
+  bool DispatchWebRtcAudioManagerConstruct(jobject manager,
+                                           jlong native_audio_manager);
+  bool DispatchWebRtcAudioManagerInit(jobject manager);
+  void DispatchWebRtcAudioManagerDispose(jobject manager);
+  void DispatchWebRtcAudioManagerMicrophoneMute(jobject manager, bool muted);
+
+  void
+  SetWebRtcAudioRecordCallbacks(std::shared_ptr<void> context,
+                                const WebRtcAudioRecordCallbacks &callbacks);
+  void ClearWebRtcAudioRecordCallbacks();
+  int DispatchWebRtcAudioRecordInit(const void *identity, int sample_rate_hz,
+                                    int channels, void **direct_buffer,
+                                    std::size_t *direct_buffer_capacity);
+  bool DispatchWebRtcAudioRecordStart(const void *identity);
+  bool DispatchWebRtcAudioRecordStop(const void *identity);
+  void DispatchWebRtcAudioRecordClose(const void *identity);
+  void DispatchWebRtcAudioRecordData(const void *identity,
+                                     std::size_t size_bytes);
+
+  // RegisterNatives stores these exact WebRTC callbacks so the host capture
+  // thread can emulate the Java AudioRecord thread.
+  void RegisterWebRtcAudioRecordNative(const char *name, const char *signature,
+                                       void *function);
+
+  void SetWebRtcAudioTrackCallbacks(std::shared_ptr<void> context,
+                                    const WebRtcAudioTrackCallbacks &callbacks);
+  void ClearWebRtcAudioTrackCallbacks();
+  int DispatchWebRtcAudioTrackInit(const void *identity, int sample_rate_hz,
+                                   int channels, double buffer_size_factor,
+                                   void **direct_buffer,
+                                   std::size_t *direct_buffer_capacity);
+  int DispatchWebRtcAudioTrackBufferSizeFrames(const void *identity);
+  bool DispatchWebRtcAudioTrackStart(const void *identity);
+  bool DispatchWebRtcAudioTrackStop(const void *identity);
+  void DispatchWebRtcAudioTrackClose(const void *identity);
+  void DispatchWebRtcAudioTrackData(const void *identity,
+                                    std::size_t size_bytes);
+
+  // RegisterNatives stores the exact WebRTC playout callbacks so the host
+  // thread can emulate AudioTrackJavaThread.
+  void RegisterWebRtcAudioTrackNative(const char *name, const char *signature,
+                                      void *function);
+
   void SetAndroidWindowCallbacks(std::shared_ptr<void> context,
                                  const AndroidWindowCallbacks &callbacks);
   void ClearAndroidWindowCallbacks();
@@ -278,6 +406,16 @@ public:
   jstring DispatchMessageBusRequestHandler(jobject handler, JNIEnv *env,
                                            jstring message);
 
+  // Exact RequestHandlerAsyncRaw.run(String, String) receiver. Clearing stops
+  // new calls; an in-flight call retains the host context until it returns.
+  jobject CreateMessageBusAsyncRequestHandler(
+      std::shared_ptr<void> context,
+      const MessageBusAsyncRequestHandlerCallbacks& callbacks);
+  void ClearMessageBusAsyncRequestHandler(jobject handler);
+  bool DispatchMessageBusAsyncRequestHandler(jobject handler, JNIEnv* env,
+                                             jstring message,
+                                             jstring response_id);
+
   // Creates the exact com.roblox.engine.jni.memstorage.Callback receiver used
   // by MemStorage.bind. Clear prevents future dispatch while an in-flight call
   // retains its shared context until the callback returns.
@@ -338,6 +476,9 @@ private:
   RobloxCredentialProvider roblox_credential_provider_ = nullptr;
   std::string roblox_credential_override_;
 
+  mutable std::mutex roblox_cookie_getter_mutex_;
+  RobloxCookieGetter roblox_cookie_getter_ = nullptr;
+
   struct RobloxCredentialSinkBinding {
     std::shared_ptr<void> context;
     RobloxCredentialSinkCallbacks callbacks;
@@ -352,6 +493,36 @@ private:
   mutable std::mutex fmod_audio_device_mutex_;
   FmodAudioDeviceBinding fmod_audio_device_binding_;
 
+  struct WebRtcAudioManagerBinding {
+    std::shared_ptr<void> context;
+    WebRtcAudioManagerCallbacks callbacks;
+  };
+  mutable std::mutex webrtc_audio_manager_mutex_;
+  WebRtcAudioManagerBinding webrtc_audio_manager_binding_;
+  void* webrtc_cache_audio_parameters_native_ = nullptr;
+
+  struct WebRtcAudioRecordBinding {
+    std::shared_ptr<void> context;
+    WebRtcAudioRecordCallbacks callbacks;
+  };
+  mutable std::mutex webrtc_audio_record_mutex_;
+  WebRtcAudioRecordBinding webrtc_audio_record_binding_;
+
+  mutable std::mutex webrtc_audio_record_native_mutex_;
+  void *webrtc_cache_direct_buffer_native_ = nullptr;
+  void *webrtc_data_is_recorded_native_ = nullptr;
+
+  struct WebRtcAudioTrackBinding {
+    std::shared_ptr<void> context;
+    WebRtcAudioTrackCallbacks callbacks;
+  };
+  mutable std::mutex webrtc_audio_track_mutex_;
+  WebRtcAudioTrackBinding webrtc_audio_track_binding_;
+
+  mutable std::mutex webrtc_audio_track_native_mutex_;
+  void *webrtc_track_cache_direct_buffer_native_ = nullptr;
+  void *webrtc_get_playout_data_native_ = nullptr;
+
   struct AndroidWindowBinding {
     std::shared_ptr<void> context;
     AndroidWindowCallbacks callbacks;
@@ -379,6 +550,15 @@ private:
   std::unordered_map<jobject, std::shared_ptr<MessageBusRequestHandlerBinding>>
       message_bus_request_handler_bindings_;
 
+  struct MessageBusAsyncRequestHandlerBinding {
+    std::shared_ptr<void> context;
+    MessageBusAsyncRequestHandlerCallbacks callbacks;
+  };
+  mutable std::mutex message_bus_async_request_handler_mutex_;
+  std::unordered_map<jobject,
+                     std::shared_ptr<MessageBusAsyncRequestHandlerBinding>>
+      message_bus_async_request_handler_bindings_;
+
   struct MemStorageCallbackBinding {
     std::shared_ptr<void> context;
     MemStorageCallbackCallbacks callbacks;

include/libc_shim/vulkan_etc1_sky_transcoder.h

@@ -0,0 +1,17 @@
+#ifndef MOCKTAIL_LIBC_SHIM_VULKAN_ETC1_SKY_TRANSCODER_H_
+#define MOCKTAIL_LIBC_SHIM_VULKAN_ETC1_SKY_TRANSCODER_H_
+
+#include <cstdint>
+#include <vector>
+
+namespace libc_shim {
+
+// Converts one opaque ETC1 RGB block to an opaque BC1 RGB block.
+void ConvertEtc1RgbBlockToBc1(const uint8_t *etc1, uint8_t *bc1);
+
+bool TranscodeEtc1SkyTextureForVulkan(const char *path,
+                                      std::vector<unsigned char> *data);
+
+} // namespace libc_shim
+
+#endif // MOCKTAIL_LIBC_SHIM_VULKAN_ETC1_SKY_TRANSCODER_H_

include/mocktail/audio/fmod_thread_floating_point.h

@@ -0,0 +1,88 @@
+#ifndef MOCKTAIL_AUDIO_FMOD_THREAD_FLOATING_POINT_H_
+#define MOCKTAIL_AUDIO_FMOD_THREAD_FLOATING_POINT_H_
+
+#include <string_view>
+
+#if defined(__x86_64__)
+#include <xmmintrin.h>
+#endif
+#if defined(__aarch64__)
+#include <cstdint>
+#endif
+
+namespace mocktail::audio {
+
+// FMOD's Android threads identify themselves through JavaVMAttachArgs before
+// entering their mix loop. Voice DSP filters can accumulate subnormal values
+// and spend an entire x86 core on floating-point assists (issue #128).
+// Limit FTZ/DAZ to these audio threads; retain the caller's other FP controls.
+class FmodThreadFloatingPointMode final {
+ public:
+  FmodThreadFloatingPointMode() = default;
+  ~FmodThreadFloatingPointMode() { Restore(); }
+  FmodThreadFloatingPointMode(const FmodThreadFloatingPointMode&) = delete;
+  FmodThreadFloatingPointMode& operator=(const FmodThreadFloatingPointMode&) =
+      delete;
+
+  bool Enable(const char* thread_name) noexcept {
+#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
+    (void)thread_name;
+    return false;
+#endif
+  }
+
+  void Restore() noexcept {
+#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
+  }
+
+ private:
+#if defined(__x86_64__)
+  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
+};
+
+}  // namespace mocktail::audio
+
+#endif  // MOCKTAIL_AUDIO_FMOD_THREAD_FLOATING_POINT_H_

include/mocktail/audio/roblox_output_device_bridge.h

@@ -4,6 +4,7 @@
 #include <array>
 #include <cstdint>
 #include <mutex>
+#include <memory>
 #include <string>
 #include <string_view>
 #include <vector>
@@ -13,13 +14,15 @@
 
 namespace mocktail::audio {
 
-// Replaces only the output-device query/select slots of the exact
+class NativeInputCapture;
+
+// Replaces the profiled input/output-device query/select slots of the exact
 // Build-ID-scoped FmodAudioDevice vtable. Roblox keeps owning its FMOD engine,
 // while the existing settings UI sees and selects the SDL host routes that
 // consume Android AudioTrack PCM.
 class RobloxOutputDeviceBridge final {
  public:
-  RobloxOutputDeviceBridge() = default;
+  RobloxOutputDeviceBridge();
   ~RobloxOutputDeviceBridge();
 
   RobloxOutputDeviceBridge(const RobloxOutputDeviceBridge&) = delete;
@@ -48,16 +51,24 @@ class RobloxOutputDeviceBridge final {
   Status Activate(std::uintptr_t image_base);
   Status PatchVtableLocked();
   bool RestoreVtableLocked();
-  int DeviceCount();
-  void* DeviceInfo(void* result, int index);
-  int CurrentDevice();
-  void SelectDevice(int index);
+  static int GetInputDeviceCount(void *self);
+  static void *GetInputDeviceInfo(void *result, void *self, int index);
+  static int GetCurrentInputDevice(void *self);
+  static void SetCurrentInputDevice(void *self, int index);
+  int DeviceCount(bool input = false);
+  void *DeviceInfo(void *result, int index, bool input = false);
+  int CurrentDevice(bool input = false);
+  void SelectDevice(int index, bool input = false);
   void ConstructGuestString(void* destination, std::string_view value) const;
 
+  std::shared_ptr<NativeInputCapture> capture_;
+  std::array<std::uintptr_t, 6> original_capture_methods_{};
   mutable std::mutex mutex_;
   compat::FmodOutputDeviceBridgeProfile profile_;
   std::vector<MenuDevice> devices_;
-  std::array<std::uintptr_t, 4> original_methods_{};
+  std::vector<MenuDevice> input_devices_;
+  int selected_input_index_ = 0;
+  std::array<std::uintptr_t, 8> original_methods_{};
   std::uintptr_t library_base_ = 0;
   std::uintptr_t* vtable_ = nullptr;
   void* string_constructor_ = nullptr;

include/mocktail/audio/sdl_audio_capture.h

@@ -0,0 +1,80 @@
+#ifndef MOCKTAIL_AUDIO_SDL_AUDIO_CAPTURE_H_
+#define MOCKTAIL_AUDIO_SDL_AUDIO_CAPTURE_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "mocktail/audio/audio_sink.h"
+
+namespace mocktail::audio {
+
+struct SdlRecordingDevice {
+  std::uint32_t id = 0;
+  std::string name;
+};
+
+// The virtual `default` target is not returned. Device IDs are process-local;
+// names are the stable configuration choice, while `id:<number>` disambiguates
+// duplicate names for the current host session.
+Status ListSdlRecordingDevices(std::vector<SdlRecordingDevice>* devices);
+
+Status ResolveSdlRecordingDevice(
+    std::string_view requested,
+    const std::vector<SdlRecordingDevice>& available_devices,
+    std::uint32_t* recording_device_id, std::string* resolved_name);
+
+// Must run after SDL audio initialization and before the first capture opens.
+Status ConfigureSdlRecordingDevice(
+    std::string_view requested,
+    std::vector<SdlRecordingDevice>* available_devices,
+    std::string* resolved_name);
+
+Status GetConfiguredSdlRecordingDevice(std::uint32_t* recording_device_id,
+                                       std::string* resolved_name);
+
+// Migrates live captures without changing their format or callback buffers.
+Status SwitchSdlRecordingDevice(std::uint32_t recording_device_id,
+                                std::string *resolved_name);
+
+using AudioCaptureDataCallback = void (*)(void* context,
+                                          std::size_t size_bytes);
+
+class AudioCapture {
+ public:
+  virtual ~AudioCapture() = default;
+
+  virtual const PcmSpec& output_spec() const = 0;
+  virtual void* buffer_data() = 0;
+  virtual std::size_t buffer_size_bytes() const = 0;
+  virtual std::size_t frames_per_buffer() const = 0;
+  virtual Status Start() = 0;
+  virtual Status Stop() = 0;
+  virtual void Shutdown() = 0;
+};
+
+struct SdlAudioCaptureOptions {
+  PcmSpec output_spec;
+
+  // Zero selects the configured process target.
+  std::uint32_t recording_device_id = 0;
+  std::uint32_t frame_duration_ms = 10;
+  AudioCaptureDataCallback data_callback = nullptr;
+  void* data_context = nullptr;
+};
+
+// SDL converts the host input to output_spec and delivers fixed-duration
+// frames through one stable buffer. The callback runs synchronously on SDL's
+// recording thread after that buffer has been filled.
+Status CreateSdlAudioCapture(const SdlAudioCaptureOptions& options,
+                             std::unique_ptr<AudioCapture>* capture);
+
+// Called by the SDL subsystem owner before SDL_QuitSubSystem.
+Status PrepareSdlAudioCaptureSubsystemShutdown();
+
+}  // namespace mocktail::audio
+
+#endif  // MOCKTAIL_AUDIO_SDL_AUDIO_CAPTURE_H_

include/mocktail/audio/sdl_audio_sink.h

@@ -48,6 +48,13 @@ struct SdlAudioSinkOptions {
   // Zero selects the configured process target.
   std::uint32_t playback_device_id = 0;
   bool start_paused = true;
+
+  // Optional pull provider for the host device. Each call fills one source
+  // buffer whose address remains valid until the next provider call. SDL
+  // copies as many buffers as the current device request needs.
+  bool (*data_needed_callback)(void *context, const void **data,
+                               std::size_t *size_bytes) = nullptr;
+  void *data_needed_context = nullptr;
 };
 
 // SDL owns conversion, resampling, and borrowed-buffer consumption.

include/mocktail/audio/webrtc_jni_audio_bridge.h

@@ -0,0 +1,21 @@
+#ifndef MOCKTAIL_AUDIO_WEBRTC_JNI_AUDIO_BRIDGE_H_
+#define MOCKTAIL_AUDIO_WEBRTC_JNI_AUDIO_BRIDGE_H_
+
+#include "mocktail/status.h"
+
+namespace jnivm {
+class VM;
+}
+
+namespace mocktail::audio {
+
+// Installs WebRtcAudioManager, WebRtcAudioRecord and WebRtcAudioTrack. The
+// manager only advertises the host PCM contract; capture opens on recording
+// init, never on manager construction. SDL's audio subsystem must remain alive
+// until ShutdownWebRtcJniAudioBridge.
+Status InstallWebRtcJniAudioBridge(jnivm::VM* vm);
+Status ShutdownWebRtcJniAudioBridge(jnivm::VM* vm);
+
+}  // namespace mocktail::audio
+
+#endif  // MOCKTAIL_AUDIO_WEBRTC_JNI_AUDIO_BRIDGE_H_

include/mocktail/graphics/android_vulkan_wsi_adapter.h

@@ -19,30 +19,14 @@ inline constexpr AndroidVulkanResult kAndroidVulkanSuccess =
     static_cast<AndroidVulkanResult>(0);
 inline constexpr AndroidVulkanResult kAndroidVulkanErrorInitializationFailed =
     static_cast<AndroidVulkanResult>(-3);
-inline constexpr std::uint64_t kHostInfiniteWaitDiagnosticSliceNs =
-    1000000000ULL;
-inline constexpr std::uint64_t kHostImageAcquireWatchdogTimeoutNs =
-    kHostInfiniteWaitDiagnosticSliceNs;
 
 inline constexpr char kAndroidSurfaceExtension[] =
     "VK_KHR_android_surface";
 
-// Roblox treats VK_SUBOPTIMAL_KHR as a hard error, so expose it as success.
+// VK_SUBOPTIMAL_KHR still returns a usable image. Roblox handles it as a fatal
+// error, so accept it until the host reports a real out-of-date surface.
 VkResult NormalizeAndroidSwapchainResult(VkResult result);
 
-// Bounds only infinite acquire waits so a lost compositor wakeup cannot hang.
-std::uint64_t BoundHostImageAcquireTimeout(std::uint64_t requested_timeout);
-bool IsHostImageAcquireWatchdogTimeout(std::uint64_t requested_timeout,
-                                       VkResult host_result);
-VkResult NormalizeHostImageAcquireResult(std::uint64_t requested_timeout,
-                                         VkResult host_result);
-
-// Infinite guest waits use finite host slices without exposing slice timeouts.
-std::uint64_t BoundHostSynchronizationWaitTimeout(
-    std::uint64_t requested_timeout);
-bool ShouldContinueHostSynchronizationWait(std::uint64_t requested_timeout,
-                                           VkResult host_result);
-
 // Returned storage owns the translated extension names.
 Status TranslateAndroidVulkanInstanceExtensions(
     const std::vector<std::string>& android_extensions,

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

@@ -0,0 +1,79 @@
+#ifndef MOCKTAIL_GRAPHICS_ETC2_DECODER_H_
+#define MOCKTAIL_GRAPHICS_ETC2_DECODER_H_
+
+#include <cstddef>
+#include <cstdint>
+
+namespace mocktail::graphics {
+
+// ETC2 and EAC block encodings from the OpenGL ES 3.0 / Vulkan core formats.
+// sRGB variants share the unorm encoding; the colour space belongs to the
+// destination format.
+enum class EtcFormat {
+  kEtc2Rgb8,
+  kEtc2Rgb8A1,
+  kEtc2Rgba8,
+  kEacR11,
+  kEacR11Signed,
+  kEacRg11,
+  kEacRg11Signed,
+};
+
+// Compressed bytes per 4x4 block.
+std::size_t EtcBlockBytes(EtcFormat format);
+
+// Decoded bytes per texel: 4 (RGBA8) for ETC2 formats, 2 per channel
+// (16-bit, little-endian) for EAC formats.
+std::size_t EtcDecodedTexelBytes(EtcFormat format);
+
+// Decodes a width x height image stored as ceil(width/4) x ceil(height/4)
+// blocks into row-major texels. Returns false, writing nothing, when a buffer
+// is smaller than the image requires.
+bool DecodeEtcImage(EtcFormat format, const std::uint8_t* source,
+                    std::size_t source_bytes, std::uint32_t width,
+                    std::uint32_t height, std::uint8_t* destination,
+                    std::size_t destination_bytes);
+
+// Decodes block rows [first_block_row, first_block_row + block_row_count) of
+// the image DecodeEtcImage describes, writing only the texel rows those blocks
+// cover. Bands that together cover every block row produce DecodeEtcImage's
+// output. Returns false, writing nothing, when a buffer is too small or the
+// rows lie outside the image.
+bool DecodeEtcImageBlockRows(EtcFormat format, const std::uint8_t* source,
+                             std::size_t source_bytes, std::uint32_t width,
+                             std::uint32_t height,
+                             std::uint32_t first_block_row,
+                             std::uint32_t block_row_count,
+                             std::uint8_t* destination,
+                             std::size_t destination_bytes);
+
+// One DecodeEtcImage call. Jobs must not share destination bytes.
+struct EtcDecodeJob {
+  EtcFormat format = EtcFormat::kEtc2Rgb8;
+  const std::uint8_t* source = nullptr;
+  std::size_t source_bytes = 0;
+  std::uint32_t width = 0;
+  std::uint32_t height = 0;
+  std::uint8_t* destination = nullptr;
+  std::size_t destination_bytes = 0;
+  // Set to DecodeEtcImage's result.
+  bool ok = false;
+};
+
+// Decodes every job before returning. Large batches are split into block-row
+// bands decoded on up to worker_count threads, the caller included; small
+// batches decode on the caller only.
+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/gles_text_overlay_compositor.h

@@ -0,0 +1,36 @@
+#ifndef MOCKTAIL_GRAPHICS_GLES_TEXT_OVERLAY_COMPOSITOR_H_
+#define MOCKTAIL_GRAPHICS_GLES_TEXT_OVERLAY_COMPOSITOR_H_
+
+#include <memory>
+
+#include "mocktail/graphics/text_overlay_frame.h"
+
+struct SDL_Window;
+
+namespace mocktail::graphics {
+
+struct GlesTextOverlaySource {
+  bool (*may_present)() = nullptr;
+  bool (*query)(MocktailTextOverlayFrameInfo *) = nullptr;
+  bool (*copy)(std::uint64_t, void *, std::size_t) = nullptr;
+};
+
+// Composites the host text editor before SDL swaps the game's GLES backbuffer.
+// Draw and destruction use the owning GL context when it is current. If that
+// context is no longer current at destruction, its destruction frees the GL
+// resources. Create a new compositor when creating a new context.
+class GlesTextOverlayCompositor {
+public:
+  explicit GlesTextOverlayCompositor(GlesTextOverlaySource source);
+  ~GlesTextOverlayCompositor();
+
+  bool Draw(SDL_Window *window);
+
+private:
+  struct Impl;
+  std::unique_ptr<Impl> impl_;
+};
+
+} // namespace mocktail::graphics
+
+#endif // MOCKTAIL_GRAPHICS_GLES_TEXT_OVERLAY_COMPOSITOR_H_

include/mocktail/graphics/present_mode_policy.h

@@ -1,6 +1,8 @@
 #ifndef MOCKTAIL_GRAPHICS_PRESENT_MODE_POLICY_H_
 #define MOCKTAIL_GRAPHICS_PRESENT_MODE_POLICY_H_
 
+#include <cstdint>
+#include <cstdio>
 #include <string_view>
 #include <vector>
 
@@ -17,10 +19,52 @@ enum class PresentModePolicy {
 
 PresentModePolicy ResolvePresentModePolicy(std::string_view vsync_value,
                                            std::string_view frame_rate_value);
+
+// Reads MOCKTAIL_VSYNC / MOCKTAIL_FRAME_RATE_LIMIT once. Window pacing and
+// the Vulkan adapter must use this instead of getenv'ing the same keys.
+PresentModePolicy CachedPresentModePolicy();
+
 std::vector<VkPresentModeKHR>
 FilterPresentModes(PresentModePolicy policy,
                    const std::vector<VkPresentModeKHR> &host_modes);
 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,
+                                           std::uint32_t min_images,
+                                           std::uint32_t max_images);
 
 } // namespace graphics
 } // namespace mocktail

include/mocktail/graphics/text_overlay_frame.h

@@ -4,7 +4,7 @@
 #include <cstddef>
 #include <cstdint>
 
-// Process-local ABI with libvulkan.so. Pixels are RGBA8; consumers must copy a
+// Process-local ABI for host compositors. Pixels are RGBA8; consumers must copy a
 // matching revision before the producer clears its storage.
 struct MocktailTextOverlayFrameInfo {
   static constexpr std::uint32_t kAbiVersion = 2;

include/mocktail/graphics/texture_override.h

@@ -0,0 +1,72 @@
+#ifndef MOCKTAIL_GRAPHICS_TEXTURE_OVERRIDE_H_
+#define MOCKTAIL_GRAPHICS_TEXTURE_OVERRIDE_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <vector>
+
+namespace mocktail::graphics {
+
+// Tightly packed RGBA8 pixels, row-major, top row first.
+struct RgbaImage {
+  std::uint32_t width = 0;
+  std::uint32_t height = 0;
+  std::vector<std::uint8_t> pixels;
+};
+
+// FNV-1a over the bytes; the texture identity used for dump and override
+// file names.
+std::uint64_t HashBytes(const std::uint8_t* data, std::size_t size);
+// 16 lowercase hex digits.
+std::string HashName(std::uint64_t hash);
+
+bool ReadPngRgba(const std::string& path, RgbaImage* image);
+bool WritePngRgba(const std::string& path, const RgbaImage& image);
+
+// Writes width x height RGBA8 pixels to destination, each destination pixel
+// the average of the source box it covers. Growing repeats source pixels.
+void ResampleRgba(const RgbaImage& source, 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::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
+// directory, every level-0 texture seen is written once as
+// <dump_dir>/<hash>_<width>x<height>.png so the hash can be found.
+// Thread-safe.
+class TextureOverrides {
+ public:
+  TextureOverrides(std::string override_dir, std::string dump_dir);
+  // MOCKTAIL_TEXTURE_OVERRIDE_DIR and MOCKTAIL_TEXTURE_DUMP_DIR.
+  static TextureOverrides FromEnvironment();
+
+  bool enabled() const { return !override_dir_.empty() || !dump_dir_.empty(); }
+  bool dumping() const { return !dump_dir_.empty(); }
+
+  // Null when no override file exists; lookups are cached either way.
+  std::shared_ptr<const RgbaImage> Lookup(std::uint64_t hash);
+  void Dump(std::uint64_t hash, std::uint32_t width, std::uint32_t height,
+            const std::uint8_t* rgba);
+
+ private:
+  std::string override_dir_;
+  std::string dump_dir_;
+  std::mutex mutex_;
+  std::unordered_map<std::uint64_t, std::shared_ptr<const RgbaImage>> cache_;
+  std::unordered_set<std::uint64_t> dumped_;
+};
+
+}  // namespace mocktail::graphics
+
+#endif  // MOCKTAIL_GRAPHICS_TEXTURE_OVERRIDE_H_

include/mocktail/graphics/vulkan_etc2_emulation.h

@@ -0,0 +1,179 @@
+#ifndef MOCKTAIL_GRAPHICS_VULKAN_ETC2_EMULATION_H_
+#define MOCKTAIL_GRAPHICS_VULKAN_ETC2_EMULATION_H_
+
+#include <vulkan/vulkan.h>
+
+#include <cstdint>
+
+#include "mocktail/graphics/etc2_decoder.h"
+
+namespace mocktail::graphics {
+
+// Host format that stores a decoded ETC2/EAC image, with its block encoding.
+struct Etc2EmulatedFormat {
+  VkFormat host_format = VK_FORMAT_UNDEFINED;
+  EtcFormat etc_format = EtcFormat::kEtc2Rgb8;
+};
+
+// Maps an ETC2/EAC Vulkan format to its decoded host format. Returns false for
+// every other format.
+bool LookupEmulatedEtc2Format(VkFormat format, Etc2EmulatedFormat* out);
+
+// Format features reported for an emulated ETC2/EAC format: the host format's
+// sampling and transfer features only, as for a native compressed format.
+VkFormatFeatureFlags EmulatedEtc2FormatFeatures(
+    VkFormatFeatureFlags host_features);
+
+// Staging bytes consumed and decoded bytes produced by one 2D upload region.
+// Returns false for an empty extent, a depth other than 1, or no layers.
+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
+// application creates; it only steers the application toward other formats.
+bool Etc2SupportAdvertised(const char* value);
+bool Etc2SupportAdvertised();
+
+// Factor applied to emulated ETC2 colour images no larger than
+// kSmallTextureMaxExtent, from the MOCKTAIL_SMALL_TEXTURE_UPSCALE value:
+// 1 leaves them alone; 2..8 create them that many times larger and resample
+// every upload, so a texture override can carry more detail than the
+// original. Unset or non-numeric values use kDefaultSmallTextureUpscale;
+// numeric values out of range are clamped.
+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 ranges live until their command buffer is begun, reset or freed.
+// MOCKTAIL_DISABLE_ETC2_EMULATION=1 turns the emulation off.
+class VulkanEtc2Emulation final {
+ public:
+  explicit VulkanEtc2Emulation(
+      VkDeviceSize staging_block_bytes = kEtc2StagingBlockBytes);
+  ~VulkanEtc2Emulation();
+  VulkanEtc2Emulation(const VulkanEtc2Emulation&) = delete;
+  VulkanEtc2Emulation& operator=(const VulkanEtc2Emulation&) = delete;
+
+  // True when this physical device lacks native ETC2 and emulation is on.
+  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,
+                      bool timeline_semaphore = false);
+  void DestroyDevice(VkDevice device);
+
+  VkResult CreateImage(VkDevice device, const VkImageCreateInfo* create_info,
+                       const VkAllocationCallbacks* allocator, VkImage* image);
+  void DestroyImage(VkDevice device, VkImage image,
+                    const VkAllocationCallbacks* allocator);
+  VkResult CreateImageView(VkDevice device,
+                           const VkImageViewCreateInfo* create_info,
+                           const VkAllocationCallbacks* allocator,
+                           VkImageView* view);
+  VkResult BindBufferMemory(VkDevice device, VkBuffer buffer,
+                            VkDeviceMemory memory, VkDeviceSize offset);
+  VkResult BindBufferMemory2(VkDevice device, std::uint32_t count,
+                             const VkBindBufferMemoryInfo* infos);
+  VkResult MapMemory(VkDevice device, VkDeviceMemory memory,
+                     VkDeviceSize offset, VkDeviceSize size,
+                     VkMemoryMapFlags flags, void** data);
+  VkResult MapMemory2(VkDevice device, const VkMemoryMapInfo* info,
+                      void** data);
+  void UnmapMemory(VkDevice device, VkDeviceMemory memory);
+  VkResult UnmapMemory2(VkDevice device, const VkMemoryUnmapInfo* info);
+  void FreeMemory(VkDevice device, VkDeviceMemory memory,
+                  const VkAllocationCallbacks* allocator);
+  void DestroyBuffer(VkDevice device, VkBuffer buffer,
+                     const VkAllocationCallbacks* allocator);
+  void CmdCopyBufferToImage(VkDevice device, VkCommandBuffer command_buffer,
+                            VkBuffer source, VkImage destination,
+                            VkImageLayout layout, std::uint32_t region_count,
+                            const VkBufferImageCopy* regions);
+  void CmdCopyBufferToImage2(VkDevice device, VkCommandBuffer command_buffer,
+                             const VkCopyBufferToImageInfo2* info);
+  void CmdCopyImage(VkDevice device, VkCommandBuffer command_buffer,
+                    VkImage source, VkImageLayout source_layout,
+                    VkImage destination, VkImageLayout destination_layout,
+                    std::uint32_t region_count, const VkImageCopy* regions);
+  void CmdCopyImage2(VkDevice device, VkCommandBuffer command_buffer,
+                     const VkCopyImageInfo2* info);
+  void CmdExecuteCommands(VkDevice device, VkCommandBuffer command_buffer,
+                          std::uint32_t count,
+                          const VkCommandBuffer* secondaries);
+
+  // Decodes every upload recorded into these command buffers and the
+  // 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, 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:
+  State* state_;
+};
+
+}  // namespace mocktail::graphics
+
+#endif  // MOCKTAIL_GRAPHICS_VULKAN_ETC2_EMULATION_H_

include/mocktail/platform/platform_runtime.h

@@ -1,6 +1,7 @@
 #ifndef MOCKTAIL_PLATFORM_PLATFORM_RUNTIME_H_
 #define MOCKTAIL_PLATFORM_PLATFORM_RUNTIME_H_
 
+#include <cmath>
 #include <cstdint>
 #include <string>
 #include <variant>
@@ -26,7 +27,7 @@ struct WindowOptions {
   int height = 720;
   std::string title = "Roblox";
   WindowSurfaceApi surface_api = WindowSurfaceApi::kAngleEgl;
-  bool high_pixel_density = true;
+  bool high_pixel_density = false;
   bool initially_hidden = true;
 
   // Production callers should keep this true. Tests using SDL's dummy driver
@@ -58,11 +59,69 @@ struct NativeWindowDescriptor {
 
 struct QuitEvent {};
 
+// Android exposes pointer and TextBox geometry in density-independent surface
+// coordinates. SDL exposes pointer positions in logical window coordinates,
+// while Vulkan presents to the pixel-sized drawable. Keep all three spaces in
+// one value so input, IME placement and same-surface overlays use exact inverse
+// transforms.
+struct SurfaceCoordinateTransform {
+  int32_t logical_width = 0;
+  int32_t logical_height = 0;
+  int32_t pixel_width = 0;
+  int32_t pixel_height = 0;
+  float density_scale = 1.0F;
+
+  bool valid() const {
+    return logical_width > 0 && logical_height > 0 && pixel_width > 0 &&
+           pixel_height > 0 && std::isfinite(density_scale) &&
+           density_scale > 0.0F;
+  }
+
+  float guest_width() const {
+    return valid() ? static_cast<float>(pixel_width) / density_scale : 0.0F;
+  }
+  float guest_height() const {
+    return valid() ? static_cast<float>(pixel_height) / density_scale : 0.0F;
+  }
+  int32_t rounded_guest_width() const {
+    return valid() ? static_cast<int32_t>(std::lround(guest_width())) : 0;
+  }
+  int32_t rounded_guest_height() const {
+    return valid() ? static_cast<int32_t>(std::lround(guest_height())) : 0;
+  }
+
+  float HostLogicalToGuestX(float coordinate) const {
+    return valid() ? coordinate * static_cast<float>(pixel_width) /
+                         static_cast<float>(logical_width) / density_scale
+                   : coordinate;
+  }
+  float HostLogicalToGuestY(float coordinate) const {
+    return valid() ? coordinate * static_cast<float>(pixel_height) /
+                         static_cast<float>(logical_height) / density_scale
+                   : coordinate;
+  }
+  float GuestToHostLogicalX(float coordinate) const {
+    return valid() ? coordinate * density_scale *
+                         static_cast<float>(logical_width) /
+                         static_cast<float>(pixel_width)
+                   : coordinate;
+  }
+  float GuestToHostLogicalY(float coordinate) const {
+    return valid() ? coordinate * density_scale *
+                         static_cast<float>(logical_height) /
+                         static_cast<float>(pixel_height)
+                   : coordinate;
+  }
+};
+
 struct WindowResizedEvent {
   int logical_width = 0;
   int logical_height = 0;
   int pixel_width = 0;
   int pixel_height = 0;
+  // Android DisplayMetrics.density equivalent. This is independent of the
+  // logical-to-pixel drawable ratio on X11/XWayland.
+  float density_scale = 1.0F;
 };
 
 struct WindowFocusEvent {
@@ -93,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 {
@@ -101,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 {
@@ -108,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 {
@@ -128,9 +195,27 @@ struct TouchEvent {
   float pressure = 0.0f;
 };
 
+enum class GamepadFamily {
+  kUnknown,
+  kXbox,
+  kPlayStation4,
+  kPlayStation5,
+};
+
+struct GamepadDescriptor {
+  GamepadFamily family = GamepadFamily::kUnknown;
+  std::string name;
+  // Bit positions are SDL's standardized gamepad buttons and axes, not raw
+  // joystick indices or Android key codes.
+  std::uint32_t buttons = 0;
+  std::uint32_t axes = 0;
+};
+
 struct GamepadConnectionEvent {
   std::int64_t instance_id = 0;
   bool connected = false;
+  GamepadDescriptor descriptor{};
+  bool remapped = false;
 };
 
 struct GamepadAxisEvent {

include/mocktail/platform/sdl_application_metadata.h

@@ -1,3 +1,4 @@
+// Modified by vii from komaruworld/mocktail. See README "About this fork".
 #ifndef MOCKTAIL_PLATFORM_SDL_APPLICATION_METADATA_H_
 #define MOCKTAIL_PLATFORM_SDL_APPLICATION_METADATA_H_
 
@@ -6,9 +7,9 @@
 namespace mocktail {
 namespace platform {
 
-inline constexpr char kMocktailApplicationName[] = "Mocktail";
+inline constexpr char kMocktailApplicationName[] = "Nightcap";
 inline constexpr char kMocktailApplicationIdentifier[] =
-    "space.bigrat.mocktail";
+    "io.github.CoderDayton.nightcap";
 
 // Configures the stable compositor identity before SDL initializes. The
 // identifier matches the installed desktop file and icon name so Wayland and

include/mocktail/platform/sdl_gamepad_manager.h

@@ -0,0 +1,45 @@
+#ifndef MOCKTAIL_PLATFORM_SDL_GAMEPAD_MANAGER_H_
+#define MOCKTAIL_PLATFORM_SDL_GAMEPAD_MANAGER_H_
+
+#include <SDL3/SDL_gamepad.h>
+
+#include <map>
+
+#include "mocktail/platform/platform_runtime.h"
+
+namespace mocktail {
+namespace platform {
+
+// Main-thread owner. Consumes events from the existing SDL pump; it never
+// creates another event loop or consumes keyboard/window events.
+class SdlGamepadManager final {
+ public:
+  using EventFn = void (*)(void*, const PlatformEvent&);
+
+  ~SdlGamepadManager();
+  SdlGamepadManager() = default;
+  SdlGamepadManager(const SdlGamepadManager&) = delete;
+  SdlGamepadManager& operator=(const SdlGamepadManager&) = delete;
+
+  Status Initialize(void* context, EventFn emit);
+  void Shutdown();
+  bool HandleEvent(const PlatformEvent& event);
+  void ResendState();
+
+ private:
+  SDL_Gamepad* Open(SDL_JoystickID id);
+  void Remove(SDL_JoystickID id);
+  void Describe(SDL_JoystickID id, SDL_Gamepad* gamepad, bool remapped);
+  void EmitState(SDL_JoystickID id, SDL_Gamepad* gamepad);
+  void Emit(PlatformEventPayload payload);
+
+  std::map<SDL_JoystickID, SDL_Gamepad*> gamepads_;
+  void* context_ = nullptr;
+  EventFn emit_ = nullptr;
+  bool initialized_ = false;
+};
+
+}  // namespace platform
+}  // namespace mocktail
+
+#endif  // MOCKTAIL_PLATFORM_SDL_GAMEPAD_MANAGER_H_

include/mocktail/sha256.h

@@ -1,45 +0,0 @@
-#ifndef MOCKTAIL_MOCKTAIL_SHA256_H_
-#define MOCKTAIL_MOCKTAIL_SHA256_H_
-
-#include <array>
-#include <cstddef>
-#include <cstdint>
-#include <string>
-#include <string_view>
-
-namespace mocktail {
-namespace foundation {
-
-class Sha256 final {
- public:
-  Sha256() = default;
-  ~Sha256();
-
-  Sha256(const Sha256&) = delete;
-  Sha256& operator=(const Sha256&) = delete;
-
-  void Update(const unsigned char* bytes, std::size_t size);
-  void Update(std::string_view bytes);
-  std::string FinalHex();
-
- private:
-  void Transform(const unsigned char* block);
-
-  std::array<std::uint32_t, 8> state_ = {
-      0x6a09e667U, 0xbb67ae85U, 0x3c6ef372U, 0xa54ff53aU,
-      0x510e527fU, 0x9b05688cU, 0x1f83d9abU, 0x5be0cd19U,
-  };
-  std::array<unsigned char, 64> block_{};
-  std::size_t block_bytes_ = 0;
-  std::uint64_t total_bytes_ = 0;
-  bool finalized_ = false;
-};
-
-// Returns the lowercase SHA-256 digest of the exact byte sequence, including
-// embedded NUL bytes.
-std::string ComputeSha256Hex(std::string_view bytes);
-
-}  // namespace foundation
-}  // namespace mocktail
-
-#endif  // MOCKTAIL_MOCKTAIL_SHA256_H_

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/openxr_backend.h

@@ -0,0 +1,665 @@
+#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 <unordered_map>
+#include <vector>
+
+#include <memory>
+
+#include "mocktail/status.h"
+#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 {
+// 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
+  // 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);
+  void NoteDeviceDestroyed(VkDevice device);
+  void 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);
+
+  // 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;
+  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:
+  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;
+    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 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 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();
+  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 RecordFilteredEyesLocked(VkCommandBuffer command, bool smaa);
+  // 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;
+    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;
+  };
+  // vr.anti_aliasing. SMAA shares FXAA's final pass, targets and eye views.
+  enum class AntiAliasing { kOff, kFxaa, kSmaa };
+  AntiAliasing AntiAliasingMode() const;
+  // Pipeline, targets and eye bindings for this frame; false means copy.
+  bool PrepareFxaaLocked();
+  bool CreateFxaaPipelineLocked(VkFormat target_format);
+  bool CreateFullscreenPipelineLocked(VkShaderModule vertex,
+                                      VkShaderModule fragment,
+                                      VkPipelineLayout layout,
+                                      VkRenderPass render_pass,
+                                      VkPipeline* pipeline);
+  void DestroyFxaaTargetsLocked();
+  void ForgetFxaaSourceLocked(VkImage image);
+  void DestroyFxaaLocked();
+  // SMAA: edge detection and blending weights into per-eye images, then
+  // neighborhood blending into FXAA's swapchain targets.
+  struct SmaaPass {
+    VkDescriptorSetLayout set_layout = VK_NULL_HANDLE;
+    VkPipelineLayout layout = VK_NULL_HANDLE;
+    VkRenderPass render_pass = VK_NULL_HANDLE;
+    VkPipeline pipeline = VK_NULL_HANDLE;
+    VkDescriptorSet sets[2] = {};
+  };
+  struct SmaaImage {
+    VkImage image = VK_NULL_HANDLE;
+    VkDeviceMemory memory = VK_NULL_HANDLE;
+    VkImageView view = VK_NULL_HANDLE;
+  };
+  struct SmaaState {
+    std::vector<VkShaderModule> modules;
+    VkDescriptorPool pool = VK_NULL_HANDLE;
+    SmaaPass edges, weights, blend;
+    SmaaImage area, search;
+    // Per eye, at the eye's extent.
+    SmaaImage edge_images[2], weight_images[2];
+    VkFramebuffer edge_framebuffers[2] = {};
+    VkFramebuffer weight_framebuffers[2] = {};
+    std::uint32_t width = 0, height = 0;
+    VkFormat target_format = VK_FORMAT_UNDEFINED;
+    // The eye views the edge and blend sets were written with.
+    VkImageView bound_sources[2] = {};
+    bool failed = false;
+  };
+  bool PrepareSmaaLocked();
+  bool CreateSmaaPipelinesLocked();
+  bool CreateSmaaImageLocked(VkFormat format, std::uint32_t width,
+                             std::uint32_t height, VkImageUsageFlags usage,
+                             SmaaImage* out);
+  bool UploadSmaaLookupLocked(SmaaImage* image, std::uint32_t width,
+                              std::uint32_t height, const void* bytes,
+                              std::size_t size);
+  void DestroySmaaImageLocked(SmaaImage* image);
+  void DestroySmaaTargetsLocked();
+  void DestroySmaaLocked();
+  // 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);
+  // 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] = {};
+  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;
+  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_;
+  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_{};
+  SmaaState smaa_{};
+  // 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;
+  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/roblox_vr_device_bridge.h

@@ -0,0 +1,130 @@
+#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"
+
+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 = void *(*)(void *result_buffer, void *device_object);
+  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/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,102 @@
+#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,
+  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,101 @@
+#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);
+
+  // 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];
+  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/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/auth_runtime_composition.h

@@ -1,6 +1,7 @@
 #ifndef MOCKTAIL_RUNTIME_AUTH_RUNTIME_COMPOSITION_H_
 #define MOCKTAIL_RUNTIME_AUTH_RUNTIME_COMPOSITION_H_
 
+#include <filesystem>
 #include <memory>
 #include <string>
 #include <string_view>
@@ -98,6 +99,10 @@ AuthRuntimeComposition ComposeAuthRuntime(
     services::AuthService& auth_service,
     std::shared_ptr<services::HttpClient> live_auth_http_client);
 
+// Persists a raw or prefixed Roblox credential to the given cookie file atomically.
+bool PersistRobloxCookie(const std::filesystem::path& path,
+                         std::string_view cookie_value);
+
 }  // namespace runtime
 }  // namespace mocktail
 

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;
@@ -30,6 +32,11 @@ struct CommandLineOptions {
   std::string launch_request_json;
   int launch_argument_index = -1;
   bool allow_unverified_build = false;
+  // 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/device_memory_profile.h

@@ -0,0 +1,28 @@
+#ifndef MOCKTAIL_RUNTIME_DEVICE_MEMORY_PROFILE_H_
+#define MOCKTAIL_RUNTIME_DEVICE_MEMORY_PROFILE_H_
+
+#include <cstdint>
+
+namespace mocktail {
+namespace runtime {
+
+// Android ActivityManager memory values published through DeviceParams.
+// Roblox derives its device RAM tier, and tiered render budgets, from them.
+struct DeviceMemoryProfile {
+  std::int32_t total_memory_mb = 0;
+  std::int32_t memory_class_mb = 0;
+  std::int32_t large_memory_class_mb = 0;
+  std::int64_t low_memory_killer_background_threshold = 0;
+  std::int64_t low_memory_killer_foreground_threshold = 0;
+  bool low_ram_device = false;
+};
+
+// Hosts with at least 4 GiB report their real total memory as a normal-RAM
+// device. Smaller hosts, or an unreadable total (0), keep the 2 GiB low-RAM
+// profile.
+DeviceMemoryProfile BuildDeviceMemoryProfile(std::uint64_t host_memory_bytes);
+
+}  // namespace runtime
+}  // namespace mocktail
+
+#endif  // MOCKTAIL_RUNTIME_DEVICE_MEMORY_PROFILE_H_

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/display_size.h

@@ -0,0 +1,73 @@
+#ifndef MOCKTAIL_RUNTIME_DISPLAY_SIZE_H_
+#define MOCKTAIL_RUNTIME_DISPLAY_SIZE_H_
+
+#include <cstdint>
+#include <limits>
+
+namespace mocktail {
+namespace runtime {
+
+// Host display or window size in physical pixels, published to the Android
+// guest. Header-only so the JNI VM can use it without link dependencies.
+struct DisplaySize {
+  std::int32_t width = 1920;
+  std::int32_t height = 1080;
+};
+
+// Environment handoffs written after the host window exists, as
+// "WIDTHxHEIGHT": the window's display mode and the window's initial pixels.
+inline constexpr const char* kDisplaySizeEnvironment =
+    "MOCKTAIL_DISPLAY_SIZE_INTERNAL";
+inline constexpr const char* kWindowSizeEnvironment =
+    "MOCKTAIL_WINDOW_SIZE_INTERNAL";
+
+// Parses "WIDTHxHEIGHT". A null, malformed or non-positive value, or one that
+// does not fit a Java int, yields the 1920x1080 fallback.
+inline DisplaySize ParseDisplaySize(const char* value) {
+  const DisplaySize fallback;
+  if (value == nullptr) {
+    return fallback;
+  }
+  std::int64_t parts[2] = {0, 0};
+  const char* cursor = value;
+  for (int index = 0; index < 2; ++index) {
+    if (*cursor < '0' || *cursor > '9') {
+      return fallback;
+    }
+    std::int64_t parsed = 0;
+    while (*cursor >= '0' && *cursor <= '9') {
+      parsed = parsed * 10 + (*cursor - '0');
+      if (parsed > std::numeric_limits<std::int32_t>::max()) {
+        return fallback;
+      }
+      ++cursor;
+    }
+    if (parsed == 0) {
+      return fallback;
+    }
+    parts[index] = parsed;
+    if (index == 0) {
+      if (*cursor != 'x') {
+        return fallback;
+      }
+      ++cursor;
+    }
+  }
+  if (*cursor != '\0') {
+    return fallback;
+  }
+  return {static_cast<std::int32_t>(parts[0]),
+          static_cast<std::int32_t>(parts[1])};
+}
+
+// Physical length of a pixel span at the guest's fixed 160 dpi, rounded down
+// to whole millimetres.
+inline std::int32_t PixelsToMillimetersAt160Dpi(std::int32_t pixels) {
+  return static_cast<std::int32_t>(static_cast<std::int64_t>(pixels) * 254 /
+                                   1600);
+}
+
+}  // namespace runtime
+}  // namespace mocktail
+
+#endif  // MOCKTAIL_RUNTIME_DISPLAY_SIZE_H_

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/fleasion.h

@@ -0,0 +1,28 @@
+#ifndef MOCKTAIL_RUNTIME_FLEASION_H_
+#define MOCKTAIL_RUNTIME_FLEASION_H_
+
+#include <filesystem>
+#include <string>
+
+#include "runtime/runtime_config.h"
+#include "runtime/runtime_paths.h"
+
+namespace mocktail::runtime {
+
+struct FleasionPreparation {
+  std::filesystem::path certificate;
+  std::filesystem::path base_bundle;
+  std::filesystem::path bundle;
+  std::string error;
+  explicit operator bool() const { return error.empty(); }
+};
+
+// Generates a private, replaceable trust bundle outside the managed payload.
+// Reads certificates only; never reads Fleasion's private key or changes it.
+FleasionPreparation PrepareFleasion(const RuntimeConfig& config,
+                                   const Environment& environment,
+                                   const RuntimePaths& paths);
+
+}  // namespace mocktail::runtime
+
+#endif

include/runtime/frame_rate_policy.h

@@ -10,6 +10,7 @@ namespace runtime {
 inline constexpr int kMaximumSupportedRobloxSchedulerFps = 240;
 
 enum class FrameRateLimitMode {
+  kUnmanaged,
   kDisplay,
   kFixed,
   kUnlimited,
@@ -17,7 +18,7 @@ enum class FrameRateLimitMode {
 };
 
 struct FrameRatePolicy {
-  FrameRateLimitMode mode = FrameRateLimitMode::kDisplay;
+  FrameRateLimitMode mode = FrameRateLimitMode::kUnmanaged;
   int fixed_fps = 0;
 
   bool valid() const { return mode != FrameRateLimitMode::kInvalid; }
@@ -25,7 +26,11 @@ struct FrameRatePolicy {
 
 FrameRatePolicy ParseFrameRatePolicy(std::string_view value);
 
-// Merges the scheduler policy into Roblox's supported client-settings ingress.
+// Enables Roblox's Basic Settings frame-rate control and, when explicitly
+// requested, merges a Mocktail scheduler policy into client settings.
+// Unmanaged (-1) does not add a scheduler target, so Roblox owns the cap.
+// Every positive fixed value is forwarded verbatim to
+// DFIntTaskSchedulerTargetFps; it is not restricted to common refresh rates.
 // Unlimited selects the unmodified payload's maximum scheduler target (240).
 // With VSync auto/off, graphics policy separately requests an unthrottled
 // Vulkan present mode when the host exposes one.

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/game_session_coordinator.h

@@ -41,6 +41,9 @@ struct GameSurface {
   uintptr_t native_window = 0;
   uint32_t width = 0;
   uint32_t height = 0;
+  // Host content scale for Android PlatformParams.dpiScale. Zero means the
+  // producer has no scale information and the JNI configuration is used.
+  float dpi_scale = 0.0f;
 };
 
 enum class GamePresentBackend {

include/runtime/graphics_launch_policy.h

@@ -1,13 +1,43 @@
 #ifndef MOCKTAIL_RUNTIME_GRAPHICS_LAUNCH_POLICY_H_
 #define MOCKTAIL_RUNTIME_GRAPHICS_LAUNCH_POLICY_H_
 
+#include <filesystem>
 #include <string>
+#include <string_view>
+#include <vector>
 
 #include "runtime/runtime_config.h"
 
 namespace mocktail {
 namespace runtime {
 
+// Readable ICD manifest for `vendor` that this build can actually load, or an
+// empty path. Directories are searched in order; a manifest built for another
+// architecture is never selected.
+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,68 @@
+#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 {
+
+// Nightcap defaults this on and keeps it on only outside games; a user value
+// set in fflags.json or the overrides environment disables the switching.
+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 on the first notification; a byte that is not 0 or 1 is
+// left alone.
+class LuauCodegenMenuSwitch {
+ public:
+  using LocateFlagFn = std::function<std::uint8_t*()>;
+
+  LuauCodegenMenuSwitch(LocateFlagFn locate_flag,
+                        RobloxExperiencePresenceObserver next);
+
+  RobloxExperiencePresenceObserver observer();
+  void OnPhase(RobloxExperiencePresencePhase phase,
+               const RobloxExperienceLaunchRequest* request);
+
+ private:
+  static void Notify(void* context, RobloxExperiencePresencePhase phase,
+                     const RobloxExperienceLaunchRequest* request);
+
+  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/payload_update_preflight.h

@@ -12,12 +12,16 @@ namespace runtime {
 struct PayloadUpdatePreflightResult {
   bool attempted = false;
   std::string error;
+  // Last failure the updater reported on its own stderr. Empty when the
+  // updater never ran or never explained itself.
+  std::string details;
 
   explicit operator bool() const { return error.empty(); }
 };
 
 PayloadUpdatePreflightResult RunPayloadUpdatePreflight(
-    const Environment& environment, const RuntimePaths& paths);
+    const Environment& environment, const RuntimePaths& paths,
+    bool force_run_latest = false);
 
 }  // namespace runtime
 }  // namespace mocktail

include/runtime/performance_policy.h

@@ -1,9 +1,11 @@
+// Modified by vii from komaruworld/mocktail. See README "About this fork".
 #ifndef MOCKTAIL_RUNTIME_PERFORMANCE_POLICY_H_
 #define MOCKTAIL_RUNTIME_PERFORMANCE_POLICY_H_
 
 #include <cstdint>
 #include <string>
 #include <string_view>
+#include <vector>
 
 #include "runtime/frame_rate_policy.h"
 #include "runtime/game_mode.h"
@@ -49,18 +51,35 @@ PerformancePolicy ParsePerformancePolicy(
 // Respects CPU affinity and falls back to the available logical count.
 int DetectAvailablePhysicalCoreCount();
 
-// Disabled policy preserves overrides; conflicting values fail.
-bool MergePerformanceClientSettingsOverrides(const PerformancePolicy& policy,
-                                             std::string_view base_json,
-                                             std::string* merged_json,
-                                             std::string* error);
+// Disabled policy preserves overrides. A base_json value that differs from
+// the preset is kept as-is and its key is appended to kept_overrides.
+bool MergePerformanceClientSettingsOverrides(
+    const PerformancePolicy& policy, std::string_view base_json,
+    std::string* merged_json, std::string* error,
+    std::vector<std::string>* kept_overrides = nullptr);
 
 // Applies mandatory HTTP and crash policies after caller settings.
-bool MergeRuntimeClientSettingsOverrides(const FrameRatePolicy& frame_rate,
-                                         const PerformancePolicy& performance,
-                                         std::string_view base_json,
-                                         std::string* merged_json,
-                                         std::string* error);
+bool MergeRuntimeClientSettingsOverrides(
+    const FrameRatePolicy& frame_rate, const PerformancePolicy& performance,
+    std::string_view base_json, std::string* merged_json, std::string* error,
+    std::vector<std::string>* kept_overrides = nullptr);
+
+// The resolved VR mode owns this flag in both client-settings channels.
+bool MergeVrClientSettingsOverrides(bool enabled, std::string_view base_json,
+                                    std::string* merged_json,
+                                    std::string* error);
+
+// Keeps the legacy test bypass disabled. The host PermissionsProtocol now
+// answers microphone authorization from capture configuration. No permission
+// query opens a recording device.
+bool MergeAudioDeviceMenuClientSettingsOverrides(std::string_view base_json,
+                                                 std::string *merged_json,
+                                                 std::string *error);
+
+bool MergeAudioCaptureClientSettingsOverrides(bool microphone_enabled,
+                                              std::string_view base_json,
+                                              std::string* merged_json,
+                                              std::string* error);
 
 }  // namespace runtime
 }  // namespace mocktail

include/runtime/platform_cache_migration.h

@@ -1,7 +1,9 @@
 #ifndef MOCKTAIL_RUNTIME_PLATFORM_CACHE_MIGRATION_H_
 #define MOCKTAIL_RUNTIME_PLATFORM_CACHE_MIGRATION_H_
 
+#include <cstdint>
 #include <filesystem>
+#include <optional>
 #include <string>
 #include <string_view>
 
@@ -37,6 +39,25 @@ PlatformCacheMigrationResult MigratePlatformProfileCaches(
     const Environment& environment, const RuntimePaths& paths,
     std::string_view desired_revision);
 
+struct RobloxThemeCacheResult {
+  std::optional<bool> dark_theme;
+  std::string error;
+
+  explicit operator bool() const { return error.empty(); }
+};
+
+// Reads the current account's Roblox theme without changing appStorage. A
+// missing or unrecognized value falls back to AuthenticatedTheme, then the
+// caller's startup default.
+RobloxThemeCacheResult ReadRobloxThemeCache(
+    const std::filesystem::path& app_storage_file,
+    std::int64_t authenticated_user_id);
+
+// Synchronizes only Roblox's local theme keys with the resolved host theme.
+bool ApplyRobloxThemeCacheOverride(
+    const std::filesystem::path& app_storage_file,
+    std::int64_t authenticated_user_id, bool dark_theme, std::string* error);
+
 }  // namespace runtime
 }  // namespace mocktail
 

include/runtime/process_diagnostics.h

@@ -0,0 +1,15 @@
+#ifndef MOCKTAIL_RUNTIME_PROCESS_DIAGNOSTICS_H_
+#define MOCKTAIL_RUNTIME_PROCESS_DIAGNOSTICS_H_
+
+namespace mocktail::runtime {
+
+enum class ProcessDiagnosticStage { kStartup, kNativeRuntime, kShutdown };
+
+// Installs a diagnostic handler only if SIGXCPU still has its default action.
+// The handler logs to stderr and re-delivers SIGXCPU with the default action.
+void InstallCpuLimitDiagnostics();
+void LogProcessDiagnostics(ProcessDiagnosticStage stage);
+
+}  // namespace mocktail::runtime
+
+#endif  // MOCKTAIL_RUNTIME_PROCESS_DIAGNOSTICS_H_

include/runtime/process_launch_policy.h

@@ -0,0 +1,16 @@
+#ifndef MOCKTAIL_RUNTIME_PROCESS_LAUNCH_POLICY_H_
+#define MOCKTAIL_RUNTIME_PROCESS_LAUNCH_POLICY_H_
+
+#include <string>
+
+namespace mocktail::runtime {
+
+// Call only for interactive launches, before creating any threads. Removes an
+// inherited soft CPU limit when the hard limit is unlimited and demotes the
+// calling thread from FIFO/RR scheduling. Returns diagnostics for the session
+// log, including failures; never changes hard limits or signal dispositions.
+std::string ApplyInteractiveProcessLaunchPolicy();
+
+}  // namespace mocktail::runtime
+
+#endif  // MOCKTAIL_RUNTIME_PROCESS_LAUNCH_POLICY_H_