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

.gitattributes

@@ -1,3 +1,4 @@
 # Preserve exact upstream whitespace in the provenance-locked Android core
 # snapshot. Local Mocktail sources remain subject to git diff --check.
 third_party/mcpelauncher-linker/core/** -whitespace
+packaging/freebsd/*.patch -whitespace

.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

@@ -0,0 +1,56 @@
+name: Check AUR packages
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: aur-packages
+  cancel-in-progress: true
+
+jobs:
+  metadata:
+    name: Refresh AUR metadata
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Prepare AUR metadata
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          package_dir="$GITHUB_WORKSPACE/packaging/aur/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"
+
+          docker run --rm \
+            --volume "$package_dir:/pkg" \
+            archlinux:base-devel bash -Eeuo pipefail -c '
+              useradd --create-home builder
+              install -d -o builder -g builder /tmp/nightcap-git
+              install -o builder -g builder -m 0644 \
+                /pkg/PKGBUILD /tmp/nightcap-git/PKGBUILD
+              runuser -u builder -- bash -c \
+                "cd /tmp/nightcap-git && makepkg --printsrcinfo" \
+                > /pkg/.SRCINFO
+            '
+
+          grep -Fqx "pkgver=${pkgver}" "$package_dir/PKGBUILD"
+          grep -Fqx $'\tpkgver = '"${pkgver}" "$package_dir/.SRCINFO"
+
+      - 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

@@ -3,7 +3,37 @@ name: CI
 on:
   push:
     branches: [main]
+    paths:
+      - '.github/workflows/**'
+      - '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:
@@ -32,124 +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 .
 
-  flatpak:
-    name: Flatpak build
-    runs-on: ubuntu-24.04
-    timeout-minutes: 120
+  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:
-          fetch-depth: 0
           submodules: recursive
 
-      - name: Install Flatpak builder
+      - name: Install build dependencies
         shell: bash
         run: |
           sudo apt-get update
-          sudo apt-get install --yes flatpak flatpak-builder gnupg
-          flatpak remote-add --user --if-not-exists flathub \
-            https://dl.flathub.org/repo/flathub.flatpakrepo
+          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 Flatpak repository and bundle
+      - 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:
-          FLATPAK_GPG_PRIVATE_KEY: ${{ secrets.FLATPAK_GPG_PRIVATE_KEY }}
-          FLATPAK_GPG_KEY_ID: ${{ secrets.FLATPAK_GPG_KEY_ID }}
+          SDL_AUDIODRIVER: dummy
+          SDL_VIDEODRIVER: x11
+          LIBGL_ALWAYS_SOFTWARE: '1'
         run: |
-          set -Eeuo pipefail
-          git update-ref refs/heads/main "$GITHUB_SHA"
-          builder_signing=()
-          bundle_keys=()
-          publish=false
-          if [[ "$GITHUB_REF" == refs/heads/main && \
-                "$GITHUB_EVENT_NAME" != pull_request ]]; then
-            publish=true
-            [[ -n "$FLATPAK_GPG_PRIVATE_KEY" && \
-               -n "$FLATPAK_GPG_KEY_ID" ]]
-            install -d -m 0700 "$RUNNER_TEMP/mocktail-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
-            builder_signing=(
-              "--gpg-sign=$FLATPAK_GPG_KEY_ID"
-              "--gpg-homedir=$RUNNER_TEMP/mocktail-gnupg"
-            )
-            bundle_keys=(--gpg-keys=mocktail-flatpak.gpg)
-          fi
-          flatpak-builder \
-            --arch=x86_64 \
-            --jobs=4 \
-            --user \
-            --install-deps-from=flathub \
-            --disable-rofiles-fuse \
-            --force-clean \
-            --default-branch=stable \
-            --repo=repo \
-            "${builder_signing[@]}" \
-            build-flatpak-ci \
-            packaging/flatpak/space.bigrat.mocktail.json
-          if [[ "$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" \
-              repo
-          fi
-          flatpak build-bundle \
-            --arch=x86_64 \
-            "${bundle_keys[@]}" \
-            repo \
-            Mocktail-x86_64.flatpak \
-            space.bigrat.mocktail \
-            stable
-          if [[ "$publish" == true ]]; then
-            ./scripts/assemble_flatpak_pages.sh \
-              repo Mocktail-x86_64.flatpak mocktail-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
-          if-no-files-found: error
-          retention-days: 14
-
-      - name: Configure GitHub Pages
-        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
-        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
-
-      - name: Upload GitHub Pages repository
-        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
-        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
-        with:
-          path: public
-
-  deploy-pages:
-    name: Publish Flatpak repository
-    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
-    needs: flatpak
-    runs-on: ubuntu-24.04
-    timeout-minutes: 10
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+          xvfb-run -a ctest --test-dir build-ci --output-on-failure \
+            --parallel 4 --timeout 120

.github/workflows/flatpak.yml

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

.github/workflows/packages.yml

@@ -1,23 +1,51 @@
-name: Native packages
+name: Nightly AppImage
 
 on:
-  push:
-    branches: [main]
-  pull_request:
+  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
@@ -27,199 +55,117 @@ 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 \
-                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: |
-          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 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 \
-                -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: |
-          docker run --rm \
-            --volume "$GITHUB_WORKSPACE:/workspace" \
-            --workdir /workspace \
-            fedora:44 bash -Eeuo pipefail -c '
-              dnf install --assumeyes \
-                gcc-c++ cmake git ninja-build pkgconf-pkg-config 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 \
-                -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 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: 15
+    timeout-minutes: 30
     permissions:
       contents: write
     steps:
@@ -228,12 +174,23 @@ 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: Checksum the nightly build
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          # 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: Update continuous release
         shell: bash
@@ -241,15 +198,26 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           set -Eeuo pipefail
-          find release -maxdepth 1 -type f -print
-          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
+              Nightcap-nightly-x86_64.AppImage|Nightcap-nightly-x86_64.AppImage.zsync|Nightcap-nightly-x86_64.AppImage.sha256)
+                ;;
+              *)
+                gh release delete-asset continuous "$asset" --yes
+                ;;
+            esac
+          done < <(gh release view continuous --json assets --jq '.assets[].name')

.github/workflows/release.yml

@@ -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,14 +9,48 @@
 
 cmake_minimum_required(VERSION 3.20)
 project(Mocktail
-  VERSION 0.1.0
-  DESCRIPTION "Android x86-64 Roblox compatibility runtime for Linux"
+  VERSION 0.3.4
+  DESCRIPTION "Android Roblox compatibility runtime for Linux"
   LANGUAGES CXX
 )
 
 include(GNUInstallDirs)
 find_package(Threads REQUIRED)
 
+set(MOCKTAIL_BUILD_GIT_COMMIT "unknown")
+set(MOCKTAIL_BUILD_GIT_DIRTY "unknown")
+find_package(Git QUIET)
+if(Git_FOUND AND EXISTS "${CMAKE_SOURCE_DIR}/.git")
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" rev-parse --short=12 HEAD
+    WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+    RESULT_VARIABLE MOCKTAIL_GIT_REV_PARSE_RESULT
+    OUTPUT_VARIABLE MOCKTAIL_GIT_REV_PARSE_OUTPUT
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET
+  )
+  if(MOCKTAIL_GIT_REV_PARSE_RESULT EQUAL 0 AND
+     MOCKTAIL_GIT_REV_PARSE_OUTPUT MATCHES "^[0-9a-fA-F]+$")
+    string(TOLOWER "${MOCKTAIL_GIT_REV_PARSE_OUTPUT}"
+      MOCKTAIL_BUILD_GIT_COMMIT)
+    execute_process(
+      COMMAND "${GIT_EXECUTABLE}" status --porcelain --untracked-files=normal
+      WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+      RESULT_VARIABLE MOCKTAIL_GIT_STATUS_RESULT
+      OUTPUT_VARIABLE MOCKTAIL_GIT_STATUS_OUTPUT
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+      ERROR_QUIET
+    )
+    if(MOCKTAIL_GIT_STATUS_RESULT EQUAL 0)
+      if(MOCKTAIL_GIT_STATUS_OUTPUT STREQUAL "")
+        set(MOCKTAIL_BUILD_GIT_DIRTY "false")
+      else()
+        set(MOCKTAIL_BUILD_GIT_DIRTY "true")
+      endif()
+    endif()
+  endif()
+endif()
+
 set(MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST
   "${CMAKE_SOURCE_DIR}/config/roblox_compatibility.json"
   CACHE FILEPATH
@@ -26,6 +61,18 @@ set(MOCKTAIL_DEFAULT_SIGNING_TRUST_MANIFEST
   CACHE FILEPATH
   "Fallback signing trust manifest used outside an installed runtime"
 )
+set(MOCKTAIL_DISCORD_APPLICATION_ID "1549428231927500843" CACHE STRING
+  "Discord application ID baked into Mocktail Rich Presence releases"
+)
+string(LENGTH "${MOCKTAIL_DISCORD_APPLICATION_ID}"
+  MOCKTAIL_DISCORD_APPLICATION_ID_LENGTH)
+if(NOT MOCKTAIL_DISCORD_APPLICATION_ID STREQUAL "" AND
+   (NOT MOCKTAIL_DISCORD_APPLICATION_ID MATCHES "^[0-9]+$" OR
+    MOCKTAIL_DISCORD_APPLICATION_ID_LENGTH LESS 17 OR
+    MOCKTAIL_DISCORD_APPLICATION_ID_LENGTH GREATER 20))
+  message(FATAL_ERROR
+    "MOCKTAIL_DISCORD_APPLICATION_ID must be empty or a Discord snowflake")
+endif()
 
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -79,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.
@@ -92,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
@@ -155,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)
@@ -168,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
@@ -177,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
@@ -185,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
@@ -206,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)
@@ -221,14 +270,18 @@ target_include_directories(mocktail_legacy_jnivm PUBLIC
 add_library(mocktail_runtime STATIC
   src/runtime/command_line.cc
   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
@@ -239,23 +292,50 @@ 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
   src/runtime/runtime_paths.cc
+  src/runtime/session_log.cc
   src/runtime/single_instance_lock.cc
   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)
 target_include_directories(mocktail_runtime PUBLIC
   ${MOCKTAIL_JNI_INCLUDE_DIRS}
 )
+target_compile_definitions(mocktail_runtime PRIVATE
+  "MOCKTAIL_DISCORD_APPLICATION_ID=\"${MOCKTAIL_DISCORD_APPLICATION_ID}\""
+)
+set_property(SOURCE src/runtime/session_log.cc APPEND PROPERTY
+  COMPILE_DEFINITIONS
+  "MOCKTAIL_PROJECT_VERSION=\"${PROJECT_VERSION}\""
+  "MOCKTAIL_BUILD_GIT_COMMIT=\"${MOCKTAIL_BUILD_GIT_COMMIT}\""
+  "MOCKTAIL_BUILD_GIT_DIRTY=\"${MOCKTAIL_BUILD_GIT_DIRTY}\""
+  "MOCKTAIL_BUILD_TYPE=\"$<CONFIG>\""
+  "MOCKTAIL_BUILD_COMPILER_ID=\"${CMAKE_CXX_COMPILER_ID}\""
+  "MOCKTAIL_BUILD_COMPILER_VERSION=\"${CMAKE_CXX_COMPILER_VERSION}\""
+  "MOCKTAIL_BUILD_TARGET_SYSTEM=\"${CMAKE_SYSTEM_NAME}\""
+  "MOCKTAIL_BUILD_TARGET_PROCESSOR=\"${CMAKE_SYSTEM_PROCESSOR}\""
+)
 mocktail_apply_compile_options(mocktail_runtime)
 if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND
    CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 16)
@@ -266,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}
 )
@@ -317,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
@@ -348,9 +430,6 @@ target_link_libraries(mocktail_auth_runtime_composition PUBLIC
   mocktail_runtime
   mocktail_services
 )
-target_link_libraries(mocktail_auth_runtime_composition PRIVATE
-  Mocktail::CryptoFoundation
-)
 mocktail_apply_compile_options(mocktail_auth_runtime_composition)
 
 add_library(mocktail_linker STATIC
@@ -362,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)
@@ -390,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
@@ -402,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
@@ -466,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
@@ -540,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}\""
@@ -553,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
@@ -568,6 +619,45 @@ target_link_options(mocktail PRIVATE
   -Wl,--export-dynamic
 )
 
+# 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)
+find_program(MOCKTAIL_LLD_EXECUTABLE NAMES ld.lld REQUIRED)
+find_program(MOCKTAIL_ELFEDIT_EXECUTABLE NAMES elfedit REQUIRED)
+get_filename_component(MOCKTAIL_LLD_DIRECTORY
+  "${MOCKTAIL_LLD_EXECUTABLE}" DIRECTORY)
+set(MOCKTAIL_FREEBSD_SOCKET_HELPER
+  "${CMAKE_BINARY_DIR}/mocktail_freebsd_socket_helper")
+add_custom_command(
+  OUTPUT "${MOCKTAIL_FREEBSD_SOCKET_HELPER}"
+  COMMAND "${CMAKE_CXX_COMPILER}"
+    -x assembler-with-cpp
+    -nostdlib
+    -static
+    -no-pie
+    "-B${MOCKTAIL_LLD_DIRECTORY}/"
+    -fuse-ld=lld
+    -Wl,-e,_start,--build-id=none,-z,noexecstack
+    -o "${MOCKTAIL_FREEBSD_SOCKET_HELPER}"
+    "${CMAKE_SOURCE_DIR}/src/compat/freebsd_socket_helper.S"
+  COMMAND "${MOCKTAIL_ELFEDIT_EXECUTABLE}"
+    --output-osabi FreeBSD "${MOCKTAIL_FREEBSD_SOCKET_HELPER}"
+  DEPENDS "${CMAKE_SOURCE_DIR}/src/compat/freebsd_socket_helper.S"
+  COMMENT "Building native FreeBSD Linuxulator socket helper"
+  VERBATIM
+)
+add_custom_target(mocktail_freebsd_socket_helper_build ALL
+  DEPENDS "${MOCKTAIL_FREEBSD_SOCKET_HELPER}"
+)
+add_dependencies(mocktail mocktail_freebsd_socket_helper_build)
+endif()
+
 set_target_properties(mocktail PROPERTIES
   BUILD_RPATH   "\$ORIGIN"
   INSTALL_RPATH "\$ORIGIN;\$ORIGIN/../${CMAKE_INSTALL_LIBDIR}/mocktail"
@@ -600,6 +690,11 @@ install(TARGETS
   RUNTIME DESTINATION "${MOCKTAIL_INSTALL_RUNTIME_DIR}"
   LIBRARY DESTINATION "${MOCKTAIL_INSTALL_RUNTIME_DIR}"
 )
+if(MOCKTAIL_BUILD_FREEBSD_SOCKET_HELPER)
+install(PROGRAMS "${MOCKTAIL_FREEBSD_SOCKET_HELPER}"
+  DESTINATION "${MOCKTAIL_INSTALL_RUNTIME_DIR}"
+)
+endif()
 install(FILES
     config/roblox_compatibility.json
     config/roblox_bootstrap_sources.json
@@ -607,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
@@ -622,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"
   )
@@ -655,20 +761,39 @@ install(CODE "
   endif()
 ")
 
-set(CPACK_PACKAGE_NAME "mocktail")
-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(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 IN_LIST MOCKTAIL_PACKAGE_NAMES)
+  string(JOIN ", " MOCKTAIL_PACKAGE_NAMES_TEXT ${MOCKTAIL_PACKAGE_NAMES})
+  message(FATAL_ERROR
+    "MOCKTAIL_PACKAGE_NAME must be one of ${MOCKTAIL_PACKAGE_NAMES_TEXT}")
+endif()
+
+set(CPACK_PACKAGE_NAME "${MOCKTAIL_PACKAGE_NAME}")
+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)
@@ -677,6 +802,15 @@ set(CPACK_RPM_FILE_NAME RPM-DEFAULT)
 set(CPACK_RPM_PACKAGE_LICENSE "Apache-2.0")
 set(CPACK_RPM_PACKAGE_GROUP "Amusements/Games")
 set(CPACK_RPM_PACKAGE_AUTOREQPROV ON)
+
+# 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.

LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 komaruworld
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

Makefile

@@ -1,5 +1,6 @@
+# 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 install-updater payload-status payload-rollback support-bundle clean submodules help
+.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
 
 BUILD_DIR  := build
 BINARY     := $(BUILD_DIR)/mocktail
@@ -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,22 +130,19 @@ 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
 
-update-auto: build ## Download latest Roblox, derive its ABI, canary twice and activate safely
+update-auto: build ## Download latest Roblox, derive its ABI, run two canaries, then activate
 	@./$(BUILD_DIR)/mocktail_updater update
 
 update-auto-launch: build ## Update Roblox and launch the verified current payload
 	@./$(BUILD_DIR)/mocktail_updater update
 	@./$(BINARY)
 
-install-updater: ## Install and enable the six-hour systemd user update timer
-	@./scripts/install_user_updater.sh
-
 payload-status: build ## Show current and previous-good immutable payloads
 	@./$(BUILD_DIR)/mocktail_updater status
 

README.md

@@ -1,16 +1,103 @@
-# 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)
+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 runs the Android `x86_64` Roblox client on Linux. It provides the
-Android ABI and JNI pieces the client expects, then uses SDL3 and Vulkan or
-OpenGL for the Linux side.
+Nightcap is an independent community project. It is not affiliated with Roblox
+Corporation or VinegarHQ and does not distribute the Roblox client.
 
-Mocktail is still experimental and may break after a Roblox update. It is not
-affiliated with Roblox Corporation or VinegarHQ.
+## 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
 
@@ -19,79 +106,77 @@ 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
-
-```bash
-flatpak install --user https://komaruworld.github.io/mocktail/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`.
-
-## Screenshots
+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>Flatpak build</summary>
+<summary>Screenshots</summary>
 
-![Roblox home in Mocktail](docs/screenshots/flatpak-home.png)
+![Roblox home in Nightcap](assets/screenshots/flatpak-home.png)
 
-![Roblox gameplay in Mocktail](docs/screenshots/flatpak-gameplay-tower.png)
-
-![Roblox experience in Mocktail](docs/screenshots/flatpak-gameplay-lobby.png)
+![Roblox gameplay in Nightcap](assets/screenshots/flatpak-gameplay-tower.png)
 
 </details>
 
-## Other Linux packages
+## FFlag overrides
 
-The latest AppImage, DEB, RPM, and Arch packages are attached to the
-[continuous release](https://github.com/komaruworld/mocktail/releases/tag/continuous).
+Put a JSON object in `$XDG_CONFIG_HOME/mocktail/fflags.json` (usually
+`~/.config/mocktail/fflags.json`). Nightcap applies it on the next launch.
 
-```bash
-# AppImage
-chmod +x Mocktail-x86_64.AppImage
-./Mocktail-x86_64.AppImage
+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.
 
-# Ubuntu/Debian
-sudo apt install ./mocktail_*_amd64.deb
+PC profiles also set `FIntFlyoutTestVariantRollout12` to `2`, which shows the
+desktop side panel menu. An explicit override takes precedence.
 
-# Fedora
-sudo dnf install ./mocktail-*.x86_64.rpm
+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).
 
-# Arch Linux
-sudo pacman -U ./mocktail-*-x86_64.pkg.tar.zst
+```json
+{
+  "FFlagExample": "True",
+  "DFIntExample": "120"
+}
 ```
+## Settings
+
+Edit `~/.config/mocktail/config.yaml`. Useful options:
+
+- `graphics.frame_rate_limit: display` to unlock FPS to your monitor's rate.
+- `graphics.vsync: off` for the lowest lag, at the cost of tearing.
+- `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
 
-Only Linux `x86_64` is supported. Building requires CMake 3.20+, Git,
-pkg-config, 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.
+Linux `x86_64` is supported. Experimental FreeBSD 15.1 Linuxulator support has
+been tested with an `x86_64` Fedora 44 userspace. On FreeBSD, Nightcap runs
+inside Linuxulator; it is not a native FreeBSD binary. Building requires CMake
+3.20+, Git, pkg-config, LLD, binutils, a C++17 compiler, SDL 3.4+, SDL3_ttf,
+Vulkan, EGL, libplacebo, fontconfig, libcurl, OpenSSL, libelf, libyaml, 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.
 
 <details>
 <summary>Ubuntu 26.04+</summary>
 
 ```bash
 sudo apt update
-sudo apt install build-essential cmake git ninja-build pkg-config \
+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
@@ -102,8 +187,8 @@ sudo apt install build-essential cmake git ninja-build pkg-config \
 <summary>Arch Linux</summary>
 
 ```bash
-sudo pacman -S --needed base-devel cmake git ninja pkgconf sdl3 sdl3_ttf \
-  curl openssl nlohmann-json libyaml libelf minizip capstone gtk4 \
+sudo pacman -S --needed base-devel cmake git ninja pkgconf lld sdl3 sdl3_ttf \
+  curl openssl nlohmann-json libyaml libpng libelf minizip capstone gtk4 \
   libadwaita webkitgtk-6.0 libutf8proc fontconfig libglvnd \
   libplacebo vulkan-headers vulkan-icd-loader zlib
 ```
@@ -113,9 +198,10 @@ sudo pacman -S --needed base-devel cmake git ninja pkgconf sdl3 sdl3_ttf \
 <summary>Fedora 44+</summary>
 
 ```bash
-sudo dnf install gcc-c++ cmake git ninja-build pkgconf-pkg-config \
+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
@@ -123,19 +209,105 @@ sudo dnf install gcc-c++ cmake git ninja-build pkgconf-pkg-config \
 </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

@@ -16,8 +16,10 @@ add_library(mocktail_compat STATIC
   ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_dns_runtime.cc
   ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_host_libc_runtime.cc
   ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_large_file_runtime.cc
+  ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_prctl_runtime.cc
   ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_rwlock_runtime.cc
   ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_signal_runtime.cc
+  ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_socket_runtime.cc
   ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_semaphore_runtime.cc
   ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_pthread_create_runtime.cc
   ${MOCKTAIL_ELF_COMPAT_ROOT}/src/compat/bionic_pthread_key_runtime.cc
@@ -34,12 +36,15 @@ add_library(Mocktail::Compat ALIAS mocktail_compat)
 target_include_directories(mocktail_compat PUBLIC
   ${MOCKTAIL_ELF_COMPAT_ROOT}/include
 )
+target_compile_definitions(mocktail_compat PRIVATE
+  "MOCKTAIL_INSTALL_LIBDIR=\"${CMAKE_INSTALL_LIBDIR}\""
+)
 target_link_libraries(mocktail_compat PUBLIC
   PkgConfig::LIBELF
   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

@@ -5,7 +5,7 @@ include_guard(GLOBAL)
 
 find_package(PkgConfig REQUIRED)
 pkg_check_modules(UTF8PROC REQUIRED IMPORTED_TARGET libutf8proc)
-pkg_check_modules(SDL3_TTF REQUIRED IMPORTED_TARGET sdl3-ttf)
+find_package(SDL3_ttf REQUIRED CONFIG)
 pkg_check_modules(FONTCONFIG REQUIRED IMPORTED_TARGET fontconfig)
 
 get_filename_component(MOCKTAIL_INPUT_ROOT "${CMAKE_CURRENT_LIST_DIR}/.."
@@ -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
-    PkgConfig::SDL3_TTF
+    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()

cmake/templates/sdl_window_icon_data.h.in

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_PLATFORM_SDL_WINDOW_ICON_DATA_H_
 #define MOCKTAIL_PLATFORM_SDL_WINDOW_ICON_DATA_H_
 

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,22 +94,91 @@ 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:
+  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.
+    show_elapsed_time: true
+    join:
+      # Boolean (default: true): let friends open the current experience. When
+      # Roblox provides a public server ID, the button targets that server.
+      enabled: true
+      # Boolean (default: true): never expose private or reserved joins.
+      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: "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
@@ -86,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/systemd/mocktail-update.service

@@ -1,15 +0,0 @@
-[Unit]
-Description=Check, canary, and install the latest working Roblox for Mocktail
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=oneshot
-EnvironmentFile=%h/.config/mocktail/updater.env
-ExecStart=/usr/bin/env ${MOCKTAIL_UPDATE_HELPER} update
-Nice=10
-IOSchedulingClass=best-effort
-IOSchedulingPriority=7
-
-[Install]
-WantedBy=default.target

config/systemd/mocktail-update.timer

@@ -1,12 +0,0 @@
-[Unit]
-Description=Periodically check Roblox updates for Mocktail
-
-[Timer]
-OnBootSec=5m
-OnUnitActiveSec=6h
-RandomizedDelaySec=15m
-Persistent=true
-Unit=mocktail-update.service
-
-[Install]
-WantedBy=timers.target

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

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_ABI_EXPORTS_H_
 #define MOCKTAIL_COMPAT_BIONIC_ABI_EXPORTS_H_
 
@@ -47,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);
@@ -85,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_atfork_runtime.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_ATFORK_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_ATFORK_RUNTIME_H_
 
@@ -19,16 +5,8 @@ namespace mocktail::compat {
 
 using BionicAtForkCallback = void (*)(void);
 
-// Registers Android's __register_atfork callback contract with the host
-// pthread runtime. Bionic associates registrations with dso_handle and
-// removes them when that DSO unloads. POSIX pthread_atfork has no matching
-// unregister operation, so the host bridge accepts dso_handle for ABI
-// compatibility but cannot use it for cleanup.
-//
-// Callback code must remain mapped for every later fork. In practice, a guest
-// DSO that has registered callbacks must stay loaded until process exit;
-// unloading is safe only when the process guarantees that it will never fork
-// again.
+// POSIX cannot unregister by dso_handle, so registered guest callbacks must
+// remain mapped for every later fork.
 int RegisterBionicAtFork(BionicAtForkCallback prepare,
                          BionicAtForkCallback parent,
                          BionicAtForkCallback child, void* dso_handle) noexcept;
@@ -37,8 +15,6 @@ int RegisterBionicAtFork(BionicAtForkCallback prepare,
 
 extern "C" {
 
-// Exact LP64 Android/Bionic __register_atfork signature. The prefixed host
-// symbol is exported to the guest as "__register_atfork" by synthetic libc.so.
 int mocktail_bionic_register_atfork(
     mocktail::compat::BionicAtForkCallback prepare,
     mocktail::compat::BionicAtForkCallback parent,

include/compat/bionic_dns_runtime.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_DNS_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_DNS_RUNTIME_H_
 

include/compat/bionic_host_libc_runtime.h

@@ -1,53 +1,44 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_HOST_LIBC_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_HOST_LIBC_RUNTIME_H_
 
+#include <sys/sysinfo.h>
+#include <sys/types.h>
 #include <sys/uio.h>
+#include <sys/utsname.h>
 
 #include <cstddef>
 #include <cstdint>
 
 namespace mocktail::compat {
 
-// Android x86-64's malloc.h declares ten size_t fields in this order. This is
-// not the host's struct mallinfo: glibc's legacy type uses int,
-// and musl exposes no allocator-telemetry API. On hosts without a compatible
-// size_t-based telemetry API, BionicMallinfo returns an all-zero "unknown"
-// snapshot. Callers must not interpret that fallback as proof of zero usage.
+// 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;
 using BionicLocale = BionicLocaleState*;
 using BionicThreadDestructor = void (*)(void*);
 
-// Do not use the host socket structs here. Although glibc happens to match
-// Android LP64, musl declares cmsg_len and msg_controllen as 32-bit socklen_t.
-// Bionic x86-64 uses size_t for both, as audited from the vendored
-// bionic/libc/include/sys/socket.h.
+// Bionic uses size_t where musl uses 32-bit socklen_t.
 struct BionicMessageHeader {
   void* msg_name = nullptr;
   uint32_t msg_namelen = 0;
@@ -64,35 +55,33 @@ struct BionicControlMessageHeader {
   int cmsg_type = 0;
 };
 
-// Implements Android's exported CMSG_NXTHDR helper over the explicit Bionic
-// x86-64 msghdr/cmsghdr layout above. Malformed or truncated control buffers
-// fail closed with nullptr.
+// Malformed or truncated control buffers return nullptr.
 BionicControlMessageHeader* BionicCmsgNextHeader(
     BionicMessageHeader* message, BionicControlMessageHeader* current) noexcept;
 
-// Registers one destructor for the current thread using libstdc++'s Itanium
-// C++ ABI implementation. That implementation is present on both supported
-// glibc and musl toolchains and preserves destructor execution at thread exit.
+// Uses libstdc++'s Itanium ABI on both supported libc implementations.
 int BionicCxaThreadAtExit(BionicThreadDestructor destructor, void* argument,
                           void* dso_handle) noexcept;
 
-// Fills the complete buffer from the Linux kernel RNG. The implementation
-// falls back to /dev/urandom only when getrandom is unavailable or blocked and
-// aborts rather than returning predictable or partially initialized bytes.
+// Falls back to /dev/urandom; never returns partial or predictable bytes.
 void BionicArc4RandomBuffer(void* buffer, size_t size) noexcept;
 
 BionicMallinfoSnapshot BionicMallinfo() noexcept;
 bool BionicMallinfoHasHostTelemetry() noexcept;
 
-// Formats one Linux errno value using Bionic's POSIX strerror_r contract.
-// Unlike glibc's GNU variant, success is reported as zero; truncation returns
-// -1 and sets errno to ERANGE while preserving the caller's errno on success.
+void NormalizeBionicSysInfo(struct sysinfo* info) noexcept;
+int BionicSysInfo(struct sysinfo* info) noexcept;
+bool NormalizeLinuxulatorUnameVersion(struct utsname* name,
+                                      const char* linux_version) noexcept;
+int BionicUname(struct utsname* name) noexcept;
+uid_t NormalizeBionicApplicationUid(uid_t host_uid) noexcept;
+uid_t BionicGetUid() noexcept;
+uid_t BionicGetEffectiveUid() noexcept;
+
+// POSIX strerror_r contract: zero on success, -1/ERANGE on truncation.
 int BionicStrError(int error_number, char* buffer, size_t buffer_size) noexcept;
 
-// Bionic supports only C and C.UTF-8, whose integer parsing is identical. A
-// host C locale is installed only for the duration of each call, so ambient
-// process locale cannot change guest parsing and a Bionic locale pointer is
-// never mistaken for an incompatible host locale_t.
+// Parses under host C locale without passing an incompatible Bionic locale_t.
 long long BionicStrToLongLongLocale(const char* text, char** end, int base,
                                     BionicLocale locale) noexcept;
 unsigned long long BionicStrToUnsignedLongLongLocale(
@@ -109,7 +98,12 @@ 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);
+uid_t mocktail_bionic_getuid();
+uid_t mocktail_bionic_geteuid();
 int mocktail_bionic_strerror_r(int error_number, char* buffer,
                                size_t buffer_size);
 long long mocktail_bionic_strtoll_l(const char* text, char** end, int base,

include/compat/bionic_large_file_runtime.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_LARGE_FILE_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_LARGE_FILE_RUNTIME_H_
 

include/compat/bionic_prctl_runtime.h

@@ -0,0 +1,12 @@
+#ifndef MOCKTAIL_COMPAT_BIONIC_PRCTL_RUNTIME_H_
+#define MOCKTAIL_COMPAT_BIONIC_PRCTL_RUNTIME_H_
+
+extern "C" {
+
+int mocktail_bionic_prctl(int option, unsigned long argument2,
+                          unsigned long argument3, unsigned long argument4,
+                          unsigned long argument5);
+
+}  // extern "C"
+
+#endif  // MOCKTAIL_COMPAT_BIONIC_PRCTL_RUNTIME_H_

include/compat/bionic_pthread_create_runtime.h

@@ -1,21 +1,9 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_PTHREAD_CREATE_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_PTHREAD_CREATE_RUNTIME_H_
 
 #include <pthread.h>
+#include <sched.h>
+#include <sys/types.h>
 
 #include <cstddef>
 
@@ -23,33 +11,31 @@ namespace mocktail::compat {
 
 using NativeThreadInitializer = void (*)();
 
-// Pinned Bionic LP64 pthread_internal.h keeps total per-thread reservation
-// near 1 MiB by subtracting its 32 KiB alternate signal stack from the normal
-// thread stack. Host defaults are not ABI substitutes: musl's default is only
-// 128 KiB on the supported Void runtime.
+// Bionic reserves 32 KiB of its 1 MiB thread allocation for the signal stack.
 inline constexpr size_t kBionicLp64DefaultThreadStackSize =
     (1U * 1024U * 1024U) - (32U * 1024U);
 static_assert(kBionicLp64DefaultThreadStackSize == 1015808U);
 
-// Used only after a Bionic-sized stack is rejected by the host at thread
-// creation time. The retry takes the largest of this floor, the requested
-// guest size, and the host default. That retains enough stack on musl without
-// shrinking glibc's default.
+// Retry floor when the host rejects the Bionic-sized stack.
 inline constexpr size_t kBionicLp64FallbackThreadStackSize = 2U * 1024U * 1024U;
 
-// Installs the payload-owned per-thread initializer used by subsequently
-// created guest threads. Passing nullptr restores ordinary host behavior.
+// nullptr restores host behavior.
 void ConfigureBionicPthreadThreadInitializer(
     NativeThreadInitializer initializer) noexcept;
 
 }  // namespace mocktail::compat
 
-// Creates a host thread after rebuilding the supported POSIX attributes.
-// Rebuilding avoids passing ABI-private pthread_attr_t state from the Android
-// payload directly into glibc.
-extern "C" int mocktail_bionic_pthread_create(pthread_t* thread,
-                                               const pthread_attr_t* attr,
-                                               void* (*start_routine)(void*),
-                                               void* argument);
+struct MocktailBionicPthreadAttr;
+
+// Rebuilds attributes instead of passing Android pthread_attr_t to glibc.
+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_pthread_key_runtime.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_PTHREAD_KEY_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_PTHREAD_KEY_RUNTIME_H_
 
@@ -31,9 +17,8 @@ constexpr uint32_t kBionicPthreadKeyValidFlag = uint32_t{1} << 31;
 
 using BionicPthreadKeyDestructor = void (*)(void*);
 
-// implementation of Bionic's pthread_key_* ABI. It owns only guest
-// keys registered through the synthetic Android libc.so, while ordinary host
-// code continues to use glibc pthread keys.
+// Implements Bionic's pthread_key_* ABI for keys registered through the
+// synthetic libc.so. Host code continues to use glibc pthread keys.
 class BionicPthreadKeyRuntime {
  public:
   static BionicPthreadKeyRuntime& Instance() noexcept;

include/compat/bionic_rwlock_runtime.h

@@ -1,24 +1,11 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_RWLOCK_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_RWLOCK_RUNTIME_H_
 
 #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

@@ -1,24 +1,11 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_SEMAPHORE_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_SEMAPHORE_RUNTIME_H_
 
 #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_signal_runtime.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_SIGNAL_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_SIGNAL_RUNTIME_H_
 

include/compat/bionic_socket_runtime.h

@@ -0,0 +1,17 @@
+#ifndef MOCKTAIL_COMPAT_BIONIC_SOCKET_RUNTIME_H_
+#define MOCKTAIL_COMPAT_BIONIC_SOCKET_RUNTIME_H_
+
+#include <sys/socket.h>
+
+extern "C" {
+
+int mocktail_bionic_setsockopt(int socket, int level, int option_name,
+                               const void *option_value,
+                               socklen_t option_length);
+
+ssize_t mocktail_bionic_sendmsg(int socket, const struct msghdr *message,
+                                int flags);
+
+}  // extern "C"
+
+#endif  // MOCKTAIL_COMPAT_BIONIC_SOCKET_RUNTIME_H_

include/compat/bionic_stdio_runtime.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_STDIO_RUNTIME_H_
 #define MOCKTAIL_COMPAT_BIONIC_STDIO_RUNTIME_H_
 
@@ -19,6 +5,7 @@
 
 #include <cstdarg>
 #include <cstddef>
+#include <cstdint>
 #include <cstdio>
 #include <cwchar>
 
@@ -31,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" {
@@ -45,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/bionic_sysconf.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_BIONIC_SYSCONF_H_
 #define MOCKTAIL_COMPAT_BIONIC_SYSCONF_H_
 

include/compat/build_profile.h

@@ -1,14 +1,9 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-
 #ifndef MOCKTAIL_COMPAT_BUILD_PROFILE_H_
 #define MOCKTAIL_COMPAT_BUILD_PROFILE_H_
 
+#include <array>
+
+#include <cstddef>
 #include <cstdint>
 #include <optional>
 #include <string>
@@ -30,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 {
@@ -49,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/elf_build_id.h

@@ -1,11 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-
 #ifndef MOCKTAIL_COMPAT_ELF_BUILD_ID_H_
 #define MOCKTAIL_COMPAT_ELF_BUILD_ID_H_
 

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_experiment.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_HOST_ABI_EXPERIMENT_H_
 #define MOCKTAIL_COMPAT_HOST_ABI_EXPERIMENT_H_
 
@@ -62,7 +48,7 @@ enum class NativePreJniBootstrapStatus {
   kFailed,
 };
 
-// Installs one exact-Build-ID experiment before libroblox constructors run.
+// Installs one exact-Build-ID profile before libroblox constructors run.
 // The caller owns policy: this function never enables itself from environment
 // variables and must only receive a profile selected from the loaded ELF ID.
 HostAbiExperimentResult

include/compat/host_abi_profile.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_HOST_ABI_PROFILE_H_
 #define MOCKTAIL_COMPAT_HOST_ABI_PROFILE_H_
 
@@ -81,7 +67,7 @@ struct NativeAllocatorProfile {
 inline constexpr size_t kMaxHostBridgeEntries = 8;
 inline constexpr size_t kMaxConstructorRunRanges = 26;
 
-// Build-ID-scoped native ABI knowledge for supported and experimental payload
+// Build-ID-scoped native ABI knowledge for supported and candidate payload
 // profiles. Keeping these addresses outside the legacy startup graph makes the
 // version boundary reviewable and independently testable.
 struct HostAbiProfile {
@@ -123,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

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_HOST_ABI_PROFILE_LOADER_H_
 #define MOCKTAIL_COMPAT_HOST_ABI_PROFILE_LOADER_H_
 
@@ -28,11 +14,8 @@ struct FileSha256Result {
   explicit operator bool() const noexcept { return error.empty(); }
 };
 
-// Computes a lowercase SHA-256 digest without invoking a shell or an external
-// utility. The external ABI approval receipt binds exact profile,
-// compatibility-manifest, and payload bytes through this implementation; the
-// runtime itself is bound by its stable GNU Build ID because installation may
-// rewrite RPATH bytes.
+// Approval receipts bind the profile, manifest, and payload to this digest.
+// Runtime identity uses its Build ID because installation may rewrite RPATH.
 FileSha256Result ComputeFileSha256(const std::string& path);
 
 struct ExternalHostAbiProfileRequest {
@@ -55,30 +38,24 @@ struct ExternalHostAbiProfileResult {
   explicit operator bool() const noexcept { return error.empty(); }
 };
 
-// Loads one exact, payload-bound ABI profile into the process registry. A
-// candidate is accepted only by an explicitly authorized canary process. A
-// normal launch instead requires a separate approval receipt produced after
-// repeated Tier C readiness. Built-in profiles are immutable and always win.
+// Candidates require canary authorization; normal launches require an
+// approval receipt. Built-in profiles always win.
 ExternalHostAbiProfileResult LoadExternalHostAbiProfile(
     const ExternalHostAbiProfileRequest& request);
 
-// Environment integration used by the pre-native compatibility gate. An
-// unset MOCKTAIL_HOST_ABI_PROFILE_FILE is a successful no-op. If it is set,
-// candidate authorization requires MOCKTAIL_HOST_ABI_CANARY=1,
-// MOCKTAIL_ALLOW_CANDIDATE_HOST_ABI=1, and the explicit research command-line
-// marker. Approved profiles require MOCKTAIL_HOST_ABI_APPROVAL_RECEIPT and
-// neither canary environment marker.
+// An unset profile is a no-op. Candidates require both canary flags and the
+// research CLI marker; approved profiles require a receipt and no canary flag.
 ExternalHostAbiProfileResult InitializeHostAbiProfileFromEnvironment(
     const std::string& payload_path,
     const std::string& compatibility_manifest_path,
     const std::string& expected_build_id,
     bool explicit_unverified_authorization);
 
-// Registry lookup used by FindHostAbiProfile after its immutable built-in
-// table. Callers should use FindHostAbiProfile rather than this function.
 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/host_allocator_bridge.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_HOST_ALLOCATOR_BRIDGE_H_
 #define MOCKTAIL_COMPAT_HOST_ALLOCATOR_BRIDGE_H_
 

include/compat/http_client_spin_guard.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_HTTP_CLIENT_SPIN_GUARD_H_
 #define MOCKTAIL_COMPAT_HTTP_CLIENT_SPIN_GUARD_H_
 

include/compat/payload_compatibility.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_COMPAT_PAYLOAD_COMPATIBILITY_H_
 #define MOCKTAIL_COMPAT_PAYLOAD_COMPATIBILITY_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

@@ -1,33 +1,5 @@
-// Copyright 2026 Sober Test Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// jnivm/jnivm.h — Pseudo Java Native Interface Virtual Machine.
-//
-// Provides a lightweight C++ implementation of a JVM stub for use with
-// Android-native shared libraries (e.g., libroblox.so) running on Linux.
-// No real Java bytecode is executed; instead, all JNI calls are intercepted
-// and dispatched to registered C++ callbacks.
-//
-// Usage:
-//   auto vm = std::make_shared<jnivm::VM>();
-//   auto cls = vm->RegisterClass("android/content/Context");
-//   cls->RegisterMethod("getSystemService",
-//   "(Ljava/lang/String;)Ljava/lang/Object;",
-//                       [](JNIEnv*, jobject, ...) { return nullptr; });
-
-#ifndef SOBER_TEST_JNIVM_JNIVM_H_
-#define SOBER_TEST_JNIVM_JNIVM_H_
+#ifndef MOCKTAIL_JNIVM_JNIVM_H_
+#define MOCKTAIL_JNIVM_JNIVM_H_
 
 #include <jni.h>
 
@@ -42,29 +14,20 @@
 
 namespace jnivm {
 
-// Forward declarations
-
 class VM;
 class Class;
 
-// Object — base type for all pseudo-Java objects managed by the pseudo-JVM.
-// Analogous to java.lang.Object in the real JVM.
-
 class Object {
 public:
   explicit Object(std::shared_ptr<Class> klass) : klass_(std::move(klass)) {}
   virtual ~Object() = default;
 
-  // Returns the pseudo-class descriptor of this object.
   std::shared_ptr<Class> GetClass() const { return klass_; }
 
 private:
   std::shared_ptr<Class> klass_;
 };
 
-// MethodCallback — signature for registered JNI method stubs.
-// The callback receives the raw JNIEnv pointer and the receiver jobject.
-
 using MethodCallback = std::function<void(JNIEnv *, jobject)>;
 
 // Resolved Roblox account identity supplied by the host runtime. This
@@ -75,8 +38,6 @@ struct RobloxAuthIdentity {
   std::string display_name;
 };
 
-// Host device capabilities exposed through the pseudo Android framework.
-// The guest ABI remains Android, while the default profile // describes a Linux desktop with physical mouse and keyboard input.
 struct PlatformIdentity {
   bool touch_enabled = false;
   bool mouse_enabled = true;
@@ -87,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 {
@@ -98,24 +65,19 @@ struct RobloxCredentialView {
 };
 
 using RobloxCredentialProvider = RobloxCredentialView (*)(const void *context);
+using RobloxCookieGetter = jstring (*)(JNIEnv* env, jclass clazz,
+                                       jstring domain);
 
-// Creates a Configuration object consistent with the VM's immutable platform
-// identity snapshot. This is the replacement for legacy construction of
-// contradictory Android keyboard/touch fields.
 jobject CreateAndroidConfiguration(JNIEnv *env);
 
-// Narrow write-only boundary for credentials produced by Roblox after the
-// native runtime has started. A successfully persisted value supersedes the
-// bound provider for the remainder of the current VM lifetime so native sign-in
-// can become authoritative without reopening an untrusted credential source.
+// A stored credential replaces the bound provider for the rest of this VM's
+// lifetime.
 struct RobloxCredentialSinkCallbacks {
   bool (*store)(void *context, const char *data, std::size_t size) = nullptr;
 };
 
-// Narrow host callback boundary for org/fmod/AudioDevice. The pseudo-JVM owns
-// only an opaque shared context and never depends on the SDL audio runtime.
-// Each Java receiver is passed as a stable identity so the host can keep
-// independent device lifecycles without retaining a JNI local reference.
+// The VM keeps the host context opaque. Receiver identities let the backend
+// track devices without retaining JNI local references.
 struct FmodAudioDeviceCallbacks {
   bool (*init)(void *context, const void *identity, int channels,
                int sample_rate_hz, int block_size_frames,
@@ -126,17 +88,73 @@ struct FmodAudioDeviceCallbacks {
   void (*shutdown)(void *context) = nullptr;
 };
 
-// Narrow host callback boundary for the activity.setWindowFlags(II)V contract.
-// Production LuaApp retains its activity through the android.app.Activity
-// interface, while GameActivity startup uses the concrete subclass. Guest JNI
-// threads only publish Android flags; the platform callback must marshal any
-// SDL work onto the SDL main thread.
+// 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 {
   bool (*set_flags)(void *context, int flags, int mask) = nullptr;
 };
 
-// Immutable snapshot of the Android NativeTextBoxInfo payload supplied by
-// Roblox when a native text field receives focus.
 struct RobloxTextBoxInfo {
   float x = 0.0f;
   float y = 0.0f;
@@ -161,8 +179,7 @@ struct RobloxTextInputShowRequest {
   RobloxTextBoxInfo info;
 };
 
-// Narrow callback boundary for the Roblox native text-input callbacks. The
-// pseudo-JVM snapshots all JNI-owned arguments before entering this boundary.
+// JNI-owned arguments are copied before the host callback runs.
 struct RobloxTextInputCallbacks {
   void (*show)(void *context,
                const RobloxTextInputShowRequest &request) = nullptr;
@@ -172,9 +189,8 @@ struct RobloxTextInputCallbacks {
   void (*shutdown)(void *context) = nullptr;
 };
 
-// Narrow boundary for a native MessageBus RawCallback object. The VM
-// retains context while a callback is in flight and dispatches only the exact
-// run(Ljava/lang/String;)V method on the exact created receiver.
+// Dispatch accepts run(String) only on a receiver created by this VM. The
+// context stays alive while the callback runs.
 struct MessageBusRawCallbacks {
   void (*run)(void *context, JNIEnv *env, jstring message) = nullptr;
 };
@@ -183,18 +199,19 @@ struct MessageBusRequestHandlerCallbacks {
   std::string (*run)(void *context, JNIEnv *env, jstring message) = nullptr;
 };
 
-// Narrow boundary for the current APK's legacy BrowserService transport.
-// Dispatch accepts only Callback.onItemSet(Ljava/lang/String;)V on the exact
-// pseudo receiver created by CreateMemStorageCallback.
+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 {
   void (*on_item_set)(void *context, JNIEnv *env, jstring value) = nullptr;
 };
 
-// Narrow boundary for the exact APK callbacks that update host web
-// state: NativeGLJavaInterface notifications, web activities, cookie sync,
-// and JNICookieProtocol.OnSetCookieHandler. The VM retains the shared callback
-// context while a callback is in flight; consumers must copy JNI strings
-// before returning.
+// Web callbacks share a retained context while in flight. Consumers must copy
+// JNI strings before returning.
 struct RobloxDataModelNotificationCallbacks {
   void (*on_notification)(void *context, JNIEnv *env, jstring type,
                           jstring data) = nullptr;
@@ -209,37 +226,22 @@ struct RobloxDataModelNotificationCallbacks {
                         jstring url) = nullptr;
 };
 
-// Narrow boundary for the exact NativeHelper lifecycle notification
-// emitted when Roblox returns from an experience to LuaApp.
 struct RobloxExperienceLifecycleCallbacks {
   void (*on_lua_app_did_return)(void *context) = nullptr;
 };
 
-// Class — represents a pseudo Java class registered in the pseudo-JVM.
-// Stores the class name (JNI descriptor format) and a map of method stubs.
-
 class Class {
 public:
   explicit Class(std::string name) : name_(std::move(name)) {}
 
-  // Returns the JNI-style class descriptor, e.g. "android/content/Context".
   const std::string &GetName() const { return name_; }
 
-  // Registers a JNI method stub.
-  //
-  // Args:
-  //   method_name: Simple method name (e.g. "getSystemService").
-  //   signature:   JNI type descriptor (e.g. "(Ljava/lang/String;)V").
-  //   callback:    C++ lambda invoked when the method is called via JNI.
   void RegisterMethod(const std::string &method_name,
                       const std::string &signature, MethodCallback callback);
 
-  // Looks up a method stub by name and signature.
-  // Returns nullptr if not found.
   const MethodCallback *FindMethod(const std::string &method_name,
                                    const std::string &signature) const;
 
-  // Returns all registered methods (name → callback).
   const std::unordered_map<std::string, MethodCallback> &GetMethods() const {
     return methods_;
   }
@@ -247,57 +249,39 @@ public:
 private:
   std::string name_;
 
-  // Key format: "methodName:descriptor"
   std::unordered_map<std::string, MethodCallback> methods_;
 };
 
-// VM — the top-level pseudo Java Virtual Machine.
-//
-// Owns a registry of pseudo-classes and exposes a JavaVM* compatible
-// pointer for passing to JNI_OnLoad in the loaded shared library.
-
 class VM {
 public:
   VM();
   ~VM();
 
-  // Disallow copy and assign.
   VM(const VM &) = delete;
   VM &operator=(const VM &) = delete;
 
-  // Registers a new pseudo-class by its JNI descriptor.
-  // Repeated registration returns the existing instance.
-  //
-  // Args:
-  //   class_name: JNI-style descriptor, e.g.
-  //   "com/roblox/client/RobloxActivity".
-  //
-  // Returns:
-  //   Shared pointer to the registered (or pre-existing) Class object.
+  // Repeated registration returns the existing class.
   std::shared_ptr<Class> RegisterClass(const std::string &class_name);
 
-  // Finds a previously registered class.
   // Returns nullptr if the class has not been registered.
   std::shared_ptr<Class> FindClass(const std::string &class_name) const;
 
-  // Returns the raw JavaVM pointer compatible with JNI_OnLoad signature.
   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);
 
-  // Returns the attached JNIEnv pointer for the current host thread.
+  // Binds this thread's JNI environment to this VM. Switching owners must
+  // not reuse the previous VM's native function table.
   JNIEnv *GetJNIEnv();
 
-  // Returns the number of registered classes.
   std::size_t GetClassCount() const { return class_registry_.size(); }
 
   // Replaces the resolved account identity with an independent copy. Invalid
   // (non-positive) identities are normalized to the unresolved state.
   void SetRobloxAuthIdentity(const RobloxAuthIdentity &identity);
 
-  // Returns the VM to its unresolved account state.
   void ClearRobloxAuthIdentity();
 
   // Returns an immutable-by-value snapshot safe for use by JNI callbacks on
@@ -320,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();
@@ -342,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();
@@ -370,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.
@@ -405,12 +451,10 @@ public:
   void ClearRobloxExperienceLifecycleCallbacks();
   bool DispatchRobloxExperienceLuaAppDidReturn();
 
-  // Restores env->functions to &native_interface_ in case libroblox replaced
-  // it.
+  // Restores the pseudo-JNI table after guest code replaces env->functions.
   void RestoreFunctions();
 
 private:
-  // Internal JNI function tables populated with stub implementations.
   JNIInvokeInterface_ invoke_interface_ = {};
   JavaVM java_vm_storage_ = {};
   JavaVM *java_vm_ = nullptr;
@@ -419,7 +463,6 @@ private:
   JNIEnv jni_env_storage_ = {};
   JNIEnv *jni_env_ = nullptr;
 
-  // Registry of pseudo-classes indexed by their JNI descriptor.
   std::unordered_map<std::string, std::shared_ptr<Class>> class_registry_;
 
   mutable std::mutex roblox_auth_identity_mutex_;
@@ -433,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;
@@ -447,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;
@@ -474,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;
@@ -498,11 +583,9 @@ private:
   std::shared_ptr<RobloxExperienceLifecycleBinding>
       roblox_experience_lifecycle_binding_;
 
-  // Initialises the JNIInvokeInterface_ and JNINativeInterface_ function tables
-  // with stub implementations that forward calls to this VM instance.
   void InitJNIFunctionTables();
 };
 
 } // namespace jnivm
 
-#endif // SOBER_TEST_JNIVM_JNIVM_H_
+#endif  // MOCKTAIL_JNIVM_JNIVM_H_

include/legacy/legacy_runtime.h

@@ -1,11 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-
 #ifndef MOCKTAIL_LEGACY_LEGACY_RUNTIME_H_
 #define MOCKTAIL_LEGACY_LEGACY_RUNTIME_H_
 
@@ -33,6 +25,8 @@ class RuntimeDependencies final {
       : jni_vm_(std::move(composition.jni_vm)),
         account_identity_(std::move(composition.account_identity)),
         roblox_credential_(std::move(composition.credential)),
+        clear_persisted_web_view_cookie_(
+            composition.rejected_credential_retired),
         shutdown_before_platform_(shutdown_before_platform) {}
   ~RuntimeDependencies() {
     if (jni_vm_ != nullptr && shutdown_before_platform_ != nullptr) {
@@ -46,6 +40,8 @@ class RuntimeDependencies final {
       : jni_vm_(std::move(other.jni_vm_)),
         account_identity_(std::move(other.account_identity_)),
         roblox_credential_(std::move(other.roblox_credential_)),
+        clear_persisted_web_view_cookie_(std::exchange(
+            other.clear_persisted_web_view_cookie_, false)),
         shutdown_before_platform_(
             std::exchange(other.shutdown_before_platform_, nullptr)) {}
   RuntimeDependencies& operator=(RuntimeDependencies&& other) noexcept {
@@ -58,6 +54,8 @@ class RuntimeDependencies final {
     jni_vm_ = std::move(other.jni_vm_);
     account_identity_ = std::move(other.account_identity_);
     roblox_credential_ = std::move(other.roblox_credential_);
+    clear_persisted_web_view_cookie_ =
+        std::exchange(other.clear_persisted_web_view_cookie_, false);
     shutdown_before_platform_ =
         std::exchange(other.shutdown_before_platform_, nullptr);
     return *this;
@@ -70,6 +68,9 @@ class RuntimeDependencies final {
   const runtime::SecureRobloxCredential& roblox_credential() const {
     return roblox_credential_;
   }
+  bool clear_persisted_web_view_cookie() const {
+    return clear_persisted_web_view_cookie_;
+  }
 
   // Transitional teardown boundary. Runtime-owned subsystems release
   // SDL resources here after guest workers stop and before window shutdown.
@@ -83,10 +84,11 @@ class RuntimeDependencies final {
   std::shared_ptr<jnivm::VM> jni_vm_;
   jnivm::RobloxAuthIdentity account_identity_;
   runtime::SecureRobloxCredential roblox_credential_;
+  bool clear_persisted_web_view_cookie_ = false;
   ShutdownBeforePlatformCallback shutdown_before_platform_ = nullptr;
 };
 
-// Transitional reverse-engineering runtime. New subsystems must expose // interfaces and be composed outside this implementation.
+// Transitional runtime kept for the reverse-engineered startup path.
 int Run(const runtime::CommandLineOptions& options,
         RuntimeDependencies dependencies);
 

include/libc_shim/libc_shim.h

@@ -1,30 +1,5 @@
-// Copyright 2026 Sober Test Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// libc_shim/libc_shim.h — Bionic libc → Glibc call translation layer.
-//
-// Intercepts calls made by Bionic-compiled code (libroblox.so) to
-// Bionic-specific libc functions and forwards them to their Glibc equivalents
-// on the host Linux system.
-//
-// Key responsibilities:
-//   - pthread_mutex_t size/layout differences between Bionic and Glibc.
-//   - Virtual filesystem path mapping (APK sandbox → Flatpak paths).
-//   - Bionic-only syscall wrappers missing in Glibc.
-
-#ifndef SOBER_TEST_LIBC_SHIM_LIBC_SHIM_H_
-#define SOBER_TEST_LIBC_SHIM_LIBC_SHIM_H_
+#ifndef MOCKTAIL_LIBC_SHIM_LIBC_SHIM_H_
+#define MOCKTAIL_LIBC_SHIM_LIBC_SHIM_H_
 
 #include <cstdio>
 #include <dirent.h>
@@ -57,10 +32,8 @@ struct HostCaBundleResolution {
 // boundary as the caller that will later free them.
 void ConfigureGuestAllocator(GuestAllocator allocator) noexcept;
 
-// Installs all shim hooks. Must be called before the target .so is loaded.
-//
-// After this call, dlopen(3) symbol resolution for known Bionic symbols will
-// be intercepted and redirected to the shim implementations.
+// Must run before loading the target library so its Bionic imports resolve to
+// these shims.
 void Install();
 
 // Resolves the host TLS trust bundle without weakening certificate
@@ -76,29 +49,13 @@ HostCaBundleResolution ConfigureHostCaBundlePathMappings();
 
 const char* HostCaBundleStatusName(HostCaBundleStatus status);
 
-// Maps an Android-style virtual path to its Flatpak sandbox equivalent.
-//
-// Example:
-//   "/data/user/0/com.roblox.client/files/logs" →
-//   "/home/user/.var/app/org.vinegarhq.Sober/data/sober/logs"
-//
-// Args:
-//   android_path: Absolute path as seen by the Bionic library.
-//
-// Returns:
-//   Translated host path. Returns android_path unchanged if no mapping
-//   is registered for it.
+// Applies the longest matching Android-to-host path prefix. Unmapped paths are
+// returned unchanged.
 std::string TranslatePath(const std::string& android_path);
 
-// Registers a path prefix mapping used by TranslatePath.
-//
-// Args:
-//   android_prefix: Android path prefix to intercept.
-//   host_prefix:    Replacement prefix on the host filesystem.
 void RegisterPathMapping(const std::string& android_prefix,
                          const std::string& host_prefix);
 
-// Removes all registered path mappings. Primarily for use in tests.
 void ClearPathMappings();
 
 }  // namespace libc_shim
@@ -123,4 +80,4 @@ ssize_t mocktail___readlink_chk(const char* path, char* buf, size_t len,
                                 size_t buf_len);
 }
 
-#endif  // SOBER_TEST_LIBC_SHIM_LIBC_SHIM_H_
+#endif  // MOCKTAIL_LIBC_SHIM_LIBC_SHIM_H_

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

@@ -1,29 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// linker/linker.h — ELF Bionic-compatible shared library loader.
-//
-// Provides a minimal interface for loading Android ELF shared libraries
-// (.so files compiled for Bionic libc / Android ABI) into a Linux process
-// address space, resolving dependencies and exporting a symbol table.
-//
-// Design notes:
-//   - Uses dlopen(3) under the hood for system libraries.
-//   - For Bionic-ABI libraries (libroblox.so), manual ELF parsing and
-//     mmap(2)-based loading is required; this header exposes that interface.
-//   - All paths follow POSIX conventions.
-
 #ifndef MOCKTAIL_LINKER_LINKER_H_
 #define MOCKTAIL_LINKER_LINKER_H_
 
@@ -34,9 +8,7 @@
 
 namespace linker {
 
-// Opaque handle returned by LoadLibrary. Callers must not interpret the
-// pointer value; it is only valid as an argument to ResolveSymbol or
-// UnloadLibrary.
+// Opaque; valid only with this linker's resolve/unload functions.
 using LibraryHandle = void*;
 using SymbolMap = std::unordered_map<std::string, void*>;
 using AndroidLibraryLoadObserver = bool (*)(void* context,
@@ -50,59 +22,27 @@ struct ProgramHeaderValidation {
   explicit operator bool() const noexcept { return valid; }
 };
 
-// AddSyntheticLibrary — registers one Android SONAME and only the exports
-// owned by that library. Dependencies of subsequently loaded Android ELF
-// files resolve these symbols through mcpelauncher-linker.
 LibraryHandle AddSyntheticLibrary(const std::string& soname,
                                   const SymbolMap& exports);
 
-// RegisterSyntheticSymbol — stages or adds one export to a specific Android
-// SONAME. If the synthetic library is already loaded, its symbol table is
-// updated in place.
+// Updates an already loaded library in place.
 void RegisterSyntheticSymbol(const std::string& soname,
                              const std::string& name, void* address);
 
-// Registers Android Bionic thread-local and synchronization ABIs only
-// for synthetic libc.so. Host code keeps its glibc implementations.
+// These adapters belong to their synthetic SONAME, never the host namespace.
 void RegisterBionicPthreadKeyRuntimeForLibc();
-
-// Registers Android's DSO-aware __register_atfork entrypoint only for
-// synthetic libc.so. The host pthread bridge preserves callback order but
-// cannot unregister callbacks when a guest DSO unloads.
 void RegisterBionicAtForkRuntimeForLibc();
-
-// Registers Android LP64 positioned I/O and seek entrypoints only for
-// synthetic libc.so. The bridge relies on the x86-64 host's 64-bit
-// off_t contract and never exposes host large-file feature-macro aliases.
 void RegisterBionicLargeFileRuntimeForLibc();
-
-// Registers host-independent implementations of Android libc exports that
-// are not uniformly supplied by glibc and musl. Every symbol remains owned by
-// synthetic libc.so and preserves the Android x86-64 ABI.
 void RegisterBionicHostLibcRuntimeForLibc();
-
-// Registers Bionic sysconf name translation only for synthetic libc.so.
-// Bionic and glibc use different integer values for sysconf names.
 void RegisterBionicSysconfRuntimeForLibc();
-
-// Registers the Android LP64 sigaction layout adapter only for libc.so.
 void RegisterBionicSignalRuntimeForLibc();
-
-// Registers the LP64 Bionic FILE/__sF ABI and host stdio translation only for
-// synthetic libc.so.
 void RegisterBionicStdioRuntimeForLibc();
 
-// Restores mcpelauncher-linker's own libdl exports after legacy host-symbol
-// discovery. Android dlopen/dlsym must never escape into glibc.
+// Android dlopen/dlsym must not escape into glibc.
 void RegisterBionicDynamicLoaderForLibdl();
 
-// GetSyntheticLibrarySymbols — returns a snapshot of one SONAME's exports.
-// The copy is safe to inspect while other libraries are being registered.
 SymbolMap GetSyntheticLibrarySymbols(const std::string& soname);
 
-// UpdateAndroidLibraryPath — configures the Bionic linker's dependency search
-// path. Multiple directories use the same colon-separated syntax as
-// LD_LIBRARY_PATH.
 void UpdateAndroidLibraryPath(const std::string& search_path);
 
 // Installs the single process owner that validates or adapts a real Android
@@ -112,18 +52,12 @@ bool SetAndroidLibraryLoadObserver(AndroidLibraryLoadObserver observer,
                                    void* context);
 void ClearAndroidLibraryLoadObserver(void* context);
 
-// OpenAndroidLibrary — loads a real Android ELF and registers its handle under
-// logical_name. The containing directory is added to the Bionic dependency
-// search path before loading.
 LibraryHandle OpenAndroidLibrary(const std::string& real_path,
                                  const std::string& logical_name);
 
-// Legacy compatibility bridge. New code should use AddSyntheticLibrary or
-// OpenAndroidLibrary so real files and synthetic SONAMEs cannot be confused.
 LibraryHandle LoadLibrary(const std::string& real_path,
                           const std::string& host_alias);
 
-// ResolveSymbol — looks up an exported symbol in a loaded library.
 void* ResolveSymbol(LibraryHandle handle, const std::string& symbol_name);
 
 // Crashpad execution is intentionally outside Mocktail's supported JNI
@@ -132,24 +66,15 @@ void* ResolveSymbol(LibraryHandle handle, const std::string& symbol_name);
 bool IsBlockedRobloxCrashReportNativeSymbol(
     std::string_view symbol_name) noexcept;
 
-// UnloadLibrary — releases resources associated with a loaded library.
 void UnloadLibrary(LibraryHandle handle);
 
-// Legacy compatibility bridge used by the current monolithic startup path.
-// New code should use RegisterSyntheticSymbol and assign every export to its
-// owning SONAME.
 void RegisterSymbol(const std::string& name, void* addr);
 
-// Returns the legacy accumulated symbol table. It remains available until the
-// existing startup path is migrated to per-SONAME maps.
 const SymbolMap& GetBionicSymbols();
 
-// Returns mcpelauncher-linker's Bionic dl_iterate_phdr entrypoint. Android
-// unwinders must not receive glibc's host implementation/layout.
+// Android unwinders must not receive glibc's implementation or layout.
 void* BionicDlIteratePhdrAddress();
 
-// Confirms that the Bionic program-header iterator can see a manually loaded
-// Android ELF, including the unwind metadata needed for C++ exceptions.
 ProgramHeaderValidation ValidateBionicProgramHeaders(LibraryHandle handle);
 
 // Returns the mapped ELF base for a loaded Android library alias. The lookup
@@ -157,7 +82,6 @@ ProgramHeaderValidation ValidateBionicProgramHeaders(LibraryHandle handle);
 // alias or a host-dlopen library without Bionic image metadata.
 std::uintptr_t FindLoadedAndroidLibraryBase(const std::string& logical_name);
 
-// SymbolTable — global registry of alias → handle mappings.
 const std::unordered_map<std::string, LibraryHandle>& GetSymbolTable();
 
 }  // namespace linker

include/mocktail/audio/audio_sink.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_AUDIO_SINK_H_
 #define MOCKTAIL_AUDIO_AUDIO_SINK_H_
 
@@ -22,9 +8,7 @@
 
 namespace mocktail::audio {
 
-// Interleaved PCM formats accepted at the host audio boundary. Endianness is
-// explicit because Android x86-64 producers use little-endian PCM regardless
-// of the host implementation chosen by SDL.
+// Android producers supply little-endian interleaved PCM.
 enum class PcmSampleFormat {
   kUnsigned8,
   kSigned16LittleEndian,
@@ -41,11 +25,9 @@ struct PcmSpec {
 using AudioBufferReleaseCallback = void (*)(void* context, const void* data,
                                             std::size_t size_bytes);
 
-// A PCM submission. With no release callback, Enqueue() copies the bytes
-// before returning. With a release callback, the sink may borrow the buffer;
-// the caller must keep it valid until the callback runs. A successful
-// submission invokes the callback exactly once, including when Clear() or
-// Shutdown() discards queued audio. A failed submission never invokes it.
+// Without a callback Enqueue copies the bytes. With one, a successful Enqueue
+// borrows them until exactly one release callback, including on Clear or
+// Shutdown. On failure the callback is not invoked.
 struct PcmBuffer {
   const void* data = nullptr;
   std::size_t size_bytes = 0;
@@ -57,9 +39,7 @@ Status ValidatePcmSpec(const PcmSpec& spec);
 std::size_t BytesPerSample(PcmSampleFormat format);
 std::size_t BytesPerFrame(const PcmSpec& spec);
 
-// Thread-safe PCM playback contract. Implementations perform device format
-// conversion and resampling through their host audio library; callers always
-// submit data in source_spec().
+// Thread-safe; callers submit source_spec(), and the backend converts it.
 class AudioSink {
  public:
   virtual ~AudioSink() = default;
@@ -68,15 +48,14 @@ class AudioSink {
   virtual Status Enqueue(const PcmBuffer& buffer) = 0;
   virtual Status Pause() = 0;
   virtual Status Resume() = 0;
-  // Linear gain is delegated to the host audio library. Zero mutes, one is
-  // unity gain, and negative or non-finite values are rejected.
+  // Zero mutes; one is unity; negative and non-finite values are invalid.
   virtual Status SetGain(float linear_gain) = 0;
   virtual Status Flush() = 0;
   virtual Status Clear() = 0;
   virtual Status GetQueuedBytes(std::size_t* size_bytes) const = 0;
 
-  // Idempotent. It waits for in-flight API calls and releases all borrowed
-  // buffers before returning. Calls started after shutdown fail closed.
+  // Idempotent. Waits for in-flight calls and borrowed buffers; later calls
+  // fail closed.
   virtual void Shutdown() = 0;
 };
 

include/mocktail/audio/fmod_java_audio_runtime.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_FMOD_JAVA_AUDIO_RUNTIME_H_
 #define MOCKTAIL_AUDIO_FMOD_JAVA_AUDIO_RUNTIME_H_
 
@@ -23,14 +9,10 @@
 
 namespace mocktail::audio {
 
-// org.fmod.AudioDevice is an ordinary Java object. The JNI boundary passes
-// its jobject value through this opaque key without making the audio layer
-// depend on JNI headers or retain a JNI reference.
+// Opaque jobject identity; the audio layer never retains a JNI reference.
 using FmodJavaAudioDeviceIdentity = const void*;
 
-// A factory returns a paused sink with exactly source_spec. Production uses
-// SDL3; tests can inject a deterministic sink without opening a host device.
-// factory_context must remain valid until the runtime is shut down.
+// Returns a paused sink. factory_context must outlive the runtime.
 using FmodJavaAudioSinkFactory = Status (*)(
     void* factory_context, const PcmSpec& source_spec,
     std::unique_ptr<AudioSink>* sink);
@@ -44,8 +26,7 @@ struct FmodJavaAudioRuntimeOptions {
   std::size_t max_buffer_bytes_per_device = 64U * 1024U * 1024U;
 };
 
-// Content-free counters suitable for readiness logs. They never expose PCM,
-// JNI identities, or guest pointers.
+// Contains no PCM, JNI identities, or guest pointers.
 struct FmodJavaAudioRuntimeStats {
   std::uint64_t init_attempts = 0;
   std::uint64_t initialized_devices = 0;
@@ -65,18 +46,9 @@ struct FmodJavaAudioRuntimeStats {
   std::size_t pending_bytes = 0;
 };
 
-// Thread-safe implementation of the APK's exact Java playback contract:
-//
-//   AudioDevice.init(channels, sampleRate, blockSize, blockCount)Z
-//   AudioDevice.write(byte[], length)V
-//   AudioDevice.close()V
-//
-// Init() allocates blockCount fixed slots of blockSize frames. Every successful
-// Write() copies guest bytes synchronously into one slot, then lends that stable
-// storage to AudioSink without a second PCM copy. FmodJavaAudioRuntime performs
-// no per-write allocation for buffer storage or release ownership. A producer
-// waits with AudioTrack-style blocking backpressure when all slots are borrowed
-// instead of growing memory or dropping a block.
+// Fixed slots avoid per-write allocation. Write copies into a slot, then lends
+// it to AudioSink; a full pool applies blocking backpressure instead of
+// growing memory or dropping audio.
 class FmodJavaAudioRuntime final {
  public:
   explicit FmodJavaAudioRuntime(
@@ -94,8 +66,7 @@ class FmodJavaAudioRuntime final {
 
   FmodJavaAudioRuntimeStats GetStats() const;
 
-  // Idempotent. Prevents new devices/writes, shuts down every sink, and waits
-  // for every borrowed owned buffer to be released before returning.
+  // Waits for every borrowed buffer to be released.
   void Shutdown();
 
  private:

include/mocktail/audio/fmod_jni_audio_bridge.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_FMOD_JNI_AUDIO_BRIDGE_H_
 #define MOCKTAIL_AUDIO_FMOD_JNI_AUDIO_BRIDGE_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/opensl_abi.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_OPENSL_ABI_H_
 #define MOCKTAIL_AUDIO_OPENSL_ABI_H_
 

include/mocktail/audio/opensl_playback_runtime.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_OPENSL_PLAYBACK_RUNTIME_H_
 #define MOCKTAIL_AUDIO_OPENSL_PLAYBACK_RUNTIME_H_
 

include/mocktail/audio/opensl_runtime_abi.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_OPENSL_RUNTIME_ABI_H_
 #define MOCKTAIL_AUDIO_OPENSL_RUNTIME_ABI_H_
 

include/mocktail/audio/opensl_simple_buffer_queue.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_OPENSL_SIMPLE_BUFFER_QUEUE_H_
 #define MOCKTAIL_AUDIO_OPENSL_SIMPLE_BUFFER_QUEUE_H_
 

include/mocktail/audio/roblox_output_device_bridge.h

@@ -1,23 +1,10 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_ROBLOX_OUTPUT_DEVICE_BRIDGE_H_
 #define MOCKTAIL_AUDIO_ROBLOX_OUTPUT_DEVICE_BRIDGE_H_
 
 #include <array>
 #include <cstdint>
 #include <mutex>
+#include <memory>
 #include <string>
 #include <string_view>
 #include <vector>
@@ -27,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;
@@ -62,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

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_AUDIO_SDL_AUDIO_SINK_H_
 #define MOCKTAIL_AUDIO_SDL_AUDIO_SINK_H_
 
@@ -25,9 +11,7 @@
 
 namespace mocktail::audio {
 
-// SDL documents subsystem initialization and shutdown as main-thread-only.
-// The process composition root owns this lifetime; audio workers only create
-// streams while the subsystem is active.
+// SDL requires subsystem startup and shutdown on the main thread.
 Status InitializeSdlAudioSubsystem();
 Status ShutdownSdlAudioSubsystem();
 
@@ -36,50 +20,44 @@ struct SdlPlaybackDevice {
   std::string name;
 };
 
-// Lists physical SDL playback devices. The abstract `default` target is not a
-// physical entry and is therefore intentionally absent from this vector.
+// The virtual `default` target is not returned.
 Status ListSdlPlaybackDevices(std::vector<SdlPlaybackDevice>* devices);
 
-// Resolves `default` or one exact physical device name. This pure selection
-// step is separate from SDL enumeration so configuration behavior is directly
-// testable.
 Status ResolveSdlPlaybackDevice(
     std::string_view requested,
     const std::vector<SdlPlaybackDevice>& available_devices,
     std::uint32_t* playback_device_id, std::string* resolved_name);
 
-// Sets the process playback target used by every subsequently created FMOD
-// Java and OpenSL sink. It must run after SDL audio initialization and before
-// the first sink is opened.
+// Must run after SDL audio initialization and before the first sink opens.
 Status ConfigureSdlPlaybackDevice(
     std::string_view requested,
     std::vector<SdlPlaybackDevice>* available_devices,
     std::string* resolved_name);
 
-// Returns the process playback target currently used by new sinks. The
-// physical ID is zero for SDL's system-default route.
+// Device ID zero means the system default.
 Status GetConfiguredSdlPlaybackDevice(std::uint32_t* playback_device_id,
                                       std::string* resolved_name);
 
-// Atomically migrates every live FMOD Java and OpenSL stream to one physical
-// SDL device, or to the system default when playback_device_id is zero. New
-// sinks inherit the same target. Existing queued PCM stays in its stream.
+// Migrates live streams without dropping queued PCM. New sinks inherit it.
 Status SwitchSdlPlaybackDevice(std::uint32_t playback_device_id,
                                std::string* resolved_name);
 
 struct SdlAudioSinkOptions {
   PcmSpec source_spec;
 
-  // Zero selects the process playback target configured above (the SDL
-  // default until explicitly configured). A nonzero ID bypasses that target.
+  // 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;
 };
 
-// Opens a real SDL 3.4+ playback device and its bound SDL_AudioStream. The SDL
-// audio subsystem must already be owned by InitializeSdlAudioSubsystem(). SDL
-// owns all format conversion, resampling, and borrowed-buffer consumption.
-// On failure, *sink remains null.
+// SDL owns conversion, resampling, and borrowed-buffer consumption.
 Status CreateSdlAudioSink(const SdlAudioSinkOptions& options,
                           std::unique_ptr<AudioSink>* sink);
 

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

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_GRAPHICS_ANDROID_VULKAN_WSI_ADAPTER_H_
 #define MOCKTAIL_GRAPHICS_ANDROID_VULKAN_WSI_ADAPTER_H_
 
@@ -26,60 +12,28 @@
 namespace mocktail {
 namespace graphics {
 
-// Vulkan VkResult values are a stable signed 32-bit ABI. Keeping the Android
-// boundary independent of the optional Vulkan SDK lets capability-only builds
-// continue to compile with SDL's opaque Vulkan handles.
+// Stable signed 32-bit ABI, independent of the optional Vulkan SDK.
 using AndroidVulkanResult = VkResult;
 
 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";
 
-// Desktop compositors can report a valid acquired/presented image as
-// suboptimal while a fullscreen configure settles. The Android client path
-// used by Roblox treats that positive success code as a hard error, so the
-// compatibility boundary exposes it as the equivalent VK_SUCCESS result.
+// 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);
 
-// Android requests an infinite image-acquire wait, but a lost Wayland/X11
-// compositor wakeup would then block Roblox's RenderJob forever. Only the
-// infinite guest request is bounded; explicit finite Vulkan timeouts retain
-// their original contract.
-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 fence/timeline waits retain their guest-visible semantics, but are
-// issued to the host in finite slices so a stalled renderer produces evidence
-// while it remains blocked. VK_TIMEOUT from a slice is never returned to the
-// Android client as a completed wait.
-std::uint64_t BoundHostSynchronizationWaitTimeout(
-    std::uint64_t requested_timeout);
-bool ShouldContinueHostSynchronizationWait(std::uint64_t requested_timeout,
-                                           VkResult host_result);
-
-// Rewrites an Android VkInstance extension request for the host WSI. The
-// returned storage owns its strings and can be used to build the
-// ppEnabledExtensionNames array passed to the host vkCreateInstance call.
+// Returned storage owns the translated extension names.
 Status TranslateAndroidVulkanInstanceExtensions(
     const std::vector<std::string>& android_extensions,
     const std::vector<std::string>& host_wsi_extensions,
     std::vector<std::string>* host_extensions);
 
-// Android WSI boundary. vkCreateAndroidSurfaceKHR-compatible exports can
-// delegate here after vkCreateInstance has used the translated extension list.
-// The Android native-window member is intentionally ignored: SDL owns the real
-// host window and is the only component allowed to create its VkSurfaceKHR.
+// Ignores the guest native-window field; SDL alone creates the host surface.
 class AndroidVulkanWsiAdapter final {
  public:
   using PresentCallback = void (*)(void* user_data);

include/mocktail/graphics/angle_probe.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_GRAPHICS_ANGLE_PROBE_H_
 #define MOCKTAIL_GRAPHICS_ANGLE_PROBE_H_
 
@@ -30,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/bionic_egl_bridge.h

@@ -1,25 +1,5 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// Exact-path loader for Mocktail's Bionic libEGL adapter.
-//
-// A host EGL implementation may have the Android SONAME "libEGL.so" too
-// (Chromium ANGLE does). Loading by SONAME after SDL/ANGLE starts can then
-// return the host implementation and make Android code create a second EGL
-// surface for one native window. This adapter opens the Mocktail
-// bridge beside the executable and exposes only its EGL exports for the
-// synthetic Bionic libEGL.so dependency.
+// Loading by SONAME can select host ANGLE instead of the Bionic adapter. This
+// bridge therefore opens the library beside the executable by exact path.
 
 #ifndef MOCKTAIL_GRAPHICS_BIONIC_EGL_BRIDGE_H_
 #define MOCKTAIL_GRAPHICS_BIONIC_EGL_BRIDGE_H_
@@ -37,9 +17,7 @@ public:
   BionicEglBridge(const BionicEglBridge &) = delete;
   BionicEglBridge &operator=(const BionicEglBridge &) = delete;
 
-  // Loads $ORIGIN/libEGL.so by its exact absolute path. On success, the
-  // handle intentionally remains live for the process lifetime because the
-  // Bionic linker retains the exported function addresses.
+  // The handle stays live because the Bionic linker retains its exports.
   bool Load();
 
   bool IsLoaded() const { return handle_ != nullptr; }

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

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_GRAPHICS_GRAPHICS_BACKEND_H_
 #define MOCKTAIL_GRAPHICS_GRAPHICS_BACKEND_H_
 

include/mocktail/graphics/present_mode_policy.h

@@ -1,20 +1,8 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_GRAPHICS_PRESENT_MODE_POLICY_H_
 #define MOCKTAIL_GRAPHICS_PRESENT_MODE_POLICY_H_
 
+#include <cstdint>
+#include <cstdio>
 #include <string_view>
 #include <vector>
 
@@ -31,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/sdl_vulkan_wsi.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_GRAPHICS_SDL_VULKAN_WSI_H_
 #define MOCKTAIL_GRAPHICS_SDL_VULKAN_WSI_H_
 
@@ -30,9 +16,8 @@
 namespace mocktail {
 namespace graphics {
 
-// Thin host WSI scaffold. It does not create a VkInstance, device, swapchain,
-// renderer, or allocator. A future Android Vulkan adapter may translate
-// vkCreateAndroidSurfaceKHR into CreateSurface after rewriting extensions.
+// Provides SDL's host WSI entry points. Instance, device, swapchain, renderer,
+// and allocator ownership stays with the caller.
 class SdlVulkanWsi final {
  public:
   SdlVulkanWsi() = default;

include/mocktail/graphics/text_overlay_frame.h

@@ -1,36 +1,18 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_GRAPHICS_TEXT_OVERLAY_FRAME_H_
 #define MOCKTAIL_GRAPHICS_TEXT_OVERLAY_FRAME_H_
 
 #include <cstddef>
 #include <cstdint>
 
-// Stable process-local ABI between the host input runtime in the executable
-// and libvulkan.so, which is loaded as a separate Android compatibility DSO.
-// Pixels are tightly packed RGBA8. The producer owns and securely clears its
-// storage; consumers must copy a matching revision before returning.
+// 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;
 
   std::uint32_t abi_version = kAbiVersion;
   std::uint32_t visible = 0;
   std::uint64_t revision = 0;
-  // x/y/width/height use the host's logical input coordinate space. These
-  // dimensions let a Vulkan consumer map that space to the swapchain's pixel
-  // extent without assuming a 1:1 high-DPI scale.
+  // Coordinates are logical, not swapchain pixels.
   std::uint32_t coordinate_width = 0;
   std::uint32_t coordinate_height = 0;
   std::int32_t x = 0;
@@ -43,9 +25,7 @@ struct MocktailTextOverlayFrameInfo {
 
 extern "C" {
 
-// Lock-free conservative hint for the Vulkan present fast path. A false
-// result guarantees that no drawable overlay is currently published. A true
-// result only means that the synchronized query/copy path must decide.
+// false guarantees no overlay; true still requires a synchronized query.
 bool mocktail_text_overlay_may_present();
 bool mocktail_text_overlay_query(MocktailTextOverlayFrameInfo* frame);
 bool mocktail_text_overlay_copy(std::uint64_t revision, void* rgba,

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_abi.h

@@ -1,6 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-// Licensed under the Apache License, Version 2.0.
-
 #ifndef MOCKTAIL_GRAPHICS_VULKAN_ABI_H_
 #define MOCKTAIL_GRAPHICS_VULKAN_ABI_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/graphics/vulkan_text_overlay_compositor.h

@@ -1,17 +1,3 @@
-// Copyright 2026 Mocktail Project Authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 #ifndef MOCKTAIL_GRAPHICS_VULKAN_TEXT_OVERLAY_COMPOSITOR_H_
 #define MOCKTAIL_GRAPHICS_VULKAN_TEXT_OVERLAY_COMPOSITOR_H_
 
@@ -22,13 +8,8 @@
 namespace mocktail {
 namespace graphics {
 
-// Composites the process-local RGBA text surface into application-owned
-// swapchain images. The adapter retains ownership of every Vulkan object it
-// registers. DestroySwapchain and DestroyDevice must be called before the
-// corresponding host Vulkan destroy function.
-//
-// An unsupported device or swapchain remains a valid registration failure:
-// QueuePresent then forwards the unmodified VkPresentInfoKHR to fallback.
+// Registered Vulkan objects remain caller-owned and must be unregistered
+// before host destruction. Unsupported registrations fall back cleanly.
 class VulkanTextOverlayCompositor final {
  public:
   VulkanTextOverlayCompositor();
@@ -38,10 +19,8 @@ class VulkanTextOverlayCompositor final {
   VulkanTextOverlayCompositor& operator=(const VulkanTextOverlayCompositor&) =
       delete;
 
-  // enabled_features describes the features actually enabled by
-  // vkCreateDevice, not merely the features supported by the physical device.
-  // The supplied proc-address callbacks must bypass the Android-facing Vulkan
-  // adapter and resolve host functions directly.
+  // enabled_features must match vkCreateDevice. Proc callbacks resolve host
+  // functions directly, bypassing the Android adapter.
   bool RegisterDevice(VkInstance instance, VkPhysicalDevice physical_device,
                       VkDevice device, std::uint32_t api_version,
                       const char* const* enabled_extensions,
@@ -61,10 +40,7 @@ class VulkanTextOverlayCompositor final {
                          const VkImage* images, std::uint32_t image_count);
   void DestroySwapchain(VkDevice device, VkSwapchainKHR swapchain);
 
-  // Serializes adapter-mediated submit, sparse-bind, present, and idle
-  // operations on the exact queue range imported by libplacebo. Other
-  // VkQueues remain independent, including the inactive-overlay fast path on
-  // a non-imported queue.
+  // Adapter operations serialize only queues imported by libplacebo.
   VkResult QueueSubmit(VkQueue queue, std::uint32_t submit_count,
                        const VkSubmitInfo* submits, VkFence fence,
                        PFN_vkQueueSubmit fallback);
@@ -77,10 +53,7 @@ class VulkanTextOverlayCompositor final {
   VkResult QueueWaitIdle(VkQueue queue, PFN_vkQueueWaitIdle fallback);
   VkResult DeviceWaitIdle(VkDevice device, PFN_vkDeviceWaitIdle fallback);
 
-  // Always invokes fallback when it is non-null. The original wait semaphores
-  // are forwarded unchanged until the compositor successfully submits the
-  // wait-collapse bridge; after that point only compositor-owned semaphores
-  // are passed to fallback.
+  // After wait collapse, fallback receives only compositor-owned semaphores.
   VkResult QueuePresent(VkQueue queue, const VkPresentInfoKHR* present_info,
                         PFN_vkQueuePresentKHR fallback);