Fix installation recovery and publish frame-beta-4 notes

Merge pull request #14 from mitch030504/claude/docs-and-credits-41qj9z
README: list the disc formats the installer accepts
2026-10-17 19:01:07 +02:00 · 2026-10-08 15:45:59 +02:00 · 2026-10-05 18:57:24 +02:00 · 2026-10-05 16:55:44 +00:00 · 2026-10-05 18:54:20 +02:00 · 2026-10-05 16:47:23 +00:00
30 changed files with 2046 additions and 418 deletions
@@ -2,7 +2,7 @@ name: Build

 on:
  push:
-    branches: [main]
+    branches: [main, openxr-work]
  pull_request:
  workflow_dispatch:

@@ -46,3 +46,20 @@ jobs:

      - name: Test
        run: dotnet test translator/Translator.sln -c Release --no-build --verbosity normal
+
+  linux-setup:
+    name: Linux setup and Frame installer
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: '8.0.x'
+      - name: Test disc staging, validation and cancellation
+        run: dotnet test translator/Translator.sln -c Release --filter FullyQualifiedName~LinuxDiscExtractionTests
+      - name: Test Frame installation and update file operations
+        run: python3 -m unittest discover -s Launcher/tests -v
+      - name: Check installer shell syntax
+        run: bash -n Launcher/steam-frame-install.sh Launcher/local-build.sh
@@ -12,7 +12,7 @@ on:
      tag:
        description: Release tag, frame-<something>; docs/releases/<tag>.md holds its notes
        required: true
-        default: frame-beta-2
+        default: frame-beta-4
 permissions:
  contents: write
 jobs:
@@ -84,3 +84,6 @@ output.txt
 /android/app/.cxx/
 /android/app/libs/*.aar
 /android/.runs/
+
+# Python regression checks
+__pycache__/
@@ -39,9 +39,19 @@ That's ok, but rules apply:
  game (hardware comparison, logs, whatever fits).
 - Review feedback. It's about the code, not about you ;).

+## Porting from other projects
+
+This fork takes fixes from upstream WiiCompiled and other forks. When you port one:
+
+- name the source repository and commit in the commit message ("Ported from owner/repo abc1234");
+- keep the original author on the commit when the change is taken as is, and say what you changed
+  when it is adapted;
+- add a line to [`CREDITS.md`](CREDITS.md), and check the source's license is compatible with
+  GPL v3.0.
+
 ## Bug reports

-See the FAQ in the [README](README.md)
+See [Reporting problems](README.md#reporting-problems) in the README.

 ## A note on related projects

@@ -0,0 +1,79 @@
+# Credits
+
+WiiCompiled VR for the Steam Frame is the work of many people. This fork adds the SteamOS build,
+the install and diagnostics scripts and the Frame-specific rendering, but most of what you play
+was written elsewhere, and a good part of this fork's own fixes were ported from other people's
+projects. This page lists where everything came from.
+
+Every project below is GPL-3.0 licensed like this one unless it says otherwise. Ported commits name
+their source repository and commit in their messages, and keep the original author where the
+change was taken as is, so `git log` is the full record. Bundled libraries and their licenses are
+in [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).
+
+## The projects this fork is built on
+
+- **[WiiCompiled](https://github.com/patchzyy/Wiicompiled)** by patchzyy and its contributors: the
+  static recompilation of Mario Kart Wii itself, the translator, the runtime and the Aurora-based
+  renderer.
+- **[WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR)** by iChris4: the OpenXR VR
+  renderer, the Quest app, the headset settings panel, foveation and the first-person cockpit. This
+  fork contains all of its `openxr-work` branch up to 2026-10-01.
+- **[mario-kart-wii-VR-port](https://github.com/heurazy/mario-kart-wii-VR-port)** by heurazy: the
+  cockpit's turning steering wheel, hand steering and USB wheel support, which came in through
+  WiiCompiled OpenXR VR.
+- **[DolphinXR](https://github.com/iChris4/dolphinXR)**: the OpenXR Wii Remote input design and its
+  default button profile, which the controller code (`runtime/src/vr/openxr_input.cpp`) and the
+  Steam Frame controller profile's input paths are adapted from.
+
+## Ported into this fork
+
+### From WiiCompiled (upstream)
+
+Cherry-picked or adapted from [patchzyy/Wiicompiled](https://github.com/patchzyy/Wiicompiled) after
+this fork's line split from it:
+
+| Change | Author | Upstream |
+| --- | --- | --- |
+| TLS through mbed TLS on Linux and Android, which online play (Retro Rewind WFC) needs there | dorPXP, with patchzyy | #144 |
+| NAND moves across mount points on Linux (saves on a different drive or the SD card) | Daan Vervacke | #212 |
+| Controller mapping platform, player index sync, and socket send errors | Michael G ([DarthMDev](https://github.com/DarthMDev)) | #251 |
+| `bltl` translation | patchzyy | #254 |
+| The KartPad batch: KD and NCD kept while offline, RFL alarm interrupt context, shared LR continuation dispatch, pipeline cache size checks, pipeline waiter wake-ups, packed three-byte vertex reads, draw merging bounds, GEN_MODE decode, EFB copy and readback fixes, graphics startup errors, and the staging buffer wait | patchzyy, adapting Chris Sotraidis's [KartPad](https://github.com/chrissotraidis/wiicompiled) fixes | #244 |
+
+### From other WiiCompiled forks
+
+| Change | Author | Source |
+| --- | --- | --- |
+| Scene-load crash fix (`GXClearVtxDesc` keeps the position descriptor) | heurazy | [Wiicompiled_VR-PLUS](https://github.com/heurazy/Wiicompiled_VR-PLUS) c2b2500 |
+| `[vr] adaptive_resolution` | heurazy | Wiicompiled_VR-PLUS, adapted |
+| Building and installing Retro Rewind from its own update server (`steam-frame-install.sh --retro-rewind`) | heurazy | Wiicompiled_VR-PLUS, adapted |
+| Faster disc reads: bulk DVD DMA copies, Yaz0 (SZS) decoding through host buffers, per-thread disc file handles | Chris Sotraidis | [KartPad](https://github.com/chrissotraidis/wiicompiled) ec14a0d, 97cdc9a, affabbd |
+| No debug labels in the ImGui passes in normal builds (an Adreno driver crash) | Chris Sotraidis | KartPad 420b828, extended to this fork's extra passes |
+| A TLS session that failed a write is kept instead of its socket being deleted | Michael G ([DarthMDev](https://github.com/DarthMDev)) | [DarthMDev/Wiicompiled](https://github.com/DarthMDev/Wiicompiled) a2ecc0f, fcf8646 (upstream PR #258) |
+| `Config.toml` saved through a temporary file and a rename | BlackAndBlue95 | [Strikers-WiiCompiled](https://github.com/BlackAndBlue95/Strikers-WiiCompiled) 435daf3 |
+| No depth writes while the Z compare is off (the Stormship lightning) | BlackAndBlue95 | Strikers-WiiCompiled 369ec99 |
+| NEON forms of the AX audio mix kernels | rooklz | [rooklz/Wiicompiled](https://github.com/rooklz/Wiicompiled) 4346362 |
+| Emptied WC24 bootstrap files are refilled | nx-mod | [wiicompiled-nx](https://github.com/nx-mod/wiicompiled-nx) d0149e6, adapted |
+| Guest memory access checks folded away on 4 KiB-page builds | nx-mod's finding | wiicompiled-nx 18ef16f, done here as a compile-time constant |
+
+## Tools and references
+
+- **[aurora](https://github.com/encounter/aurora)** by Luke Street: the GX rendering and windowing
+  backend the whole graphics layer sits on (MIT).
+- **[Dawn](https://dawn.googlesource.com/dawn)**: Google's WebGPU implementation, under Aurora.
+- **[OpenXR](https://www.khronos.org/openxr/)** by Khronos: the VR API.
+- **[Mbed TLS](https://github.com/Mbed-TLS/mbedtls)**: TLS for online play on Linux and Android.
+- **[Dolphin Emulator](https://github.com/dolphin-emu/dolphin)**: a reference for Wii hardware
+  behaviour, and the source of the DSP coefficient ROM, the WiiConnect24 bootstrap tree and the
+  Riivolution parser bundled with the runtime.
+- **[nod](https://github.com/encounter/nod)** by Luke Street: `nodtool`, the disc image extractor.
+- **[Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind)** by ZPL and team: the mod
+  distribution this project supports.
+- **[Wheel Wizard](https://github.com/TeamWheelWizard/WheelWizard)**: the mod manager the PC build
+  integrates with, and the model for how the install script fetches Retro Rewind.
+- **[Frame Control](https://github.com/saphid/frame-control)** by saphid: installing the game into
+  the Frame's Steam library, and its notes on how the Frame's software fits together.
+- **Inkwreck**: the logo.
+- Everyone in the static recompilation community.
+
+If something of yours is in this fork and missing here, or credited wrongly, please open an issue.
@@ -1,5 +1,9 @@
 # Windows VR distribution

+This page covers upstream's Windows releases, kept for the PC build. The Steam Frame releases
+(`frame-*` tags) are source only and are published by `.github/workflows/frame-release.yml` with
+the notes in `docs/releases/<tag>.md`; see the [README](README.md#quick-start).
+
 Distribute only `WiiCompiled-Setup.exe` and its checksum from
 [iChris4/Wiicompiled_VR](https://github.com/iChris4/Wiicompiled_VR/releases), and
 `WheelWizardVRWindows.exe` from [iChris4/WheelWizard_VR](https://github.com/iChris4/WheelWizard_VR/releases).
@@ -30,37 +30,58 @@ internal static class DiscTool
                "Only your own legally-owned copy of that exact game/region can be used.");
        }

-        // Extracted straight into Assets/DATA (kept, not a scratch dir) - the runtime reads course/
-        // texture/audio data from this directory live via [paths] dvd_root, not just at translation
-        // time, so it has to survive past this install (see Program.cs, which points dvd_root here).
        reporter.Progress(InstallStages.ExtractDisc, "Extracting the disc image", 4);
-        var dataDir = Path.Combine(assetsDirectory, "DATA");
-        if (Directory.Exists(dataDir)) Directory.Delete(dataDir, recursive: true);
-        await RunExtractAsync(nodTool, isoPath, dataDir, cancellationToken);
-
-        var dolPath = Path.Combine(dataDir, "sys", "main.dol");
-        var relPath = Path.Combine(dataDir, "files", "rel", "StaticR.rel");
-        if (!File.Exists(dolPath)) throw new FileNotFoundException("nodtool did not produce main.dol", dolPath);
-        if (!File.Exists(relPath)) throw new FileNotFoundException("nodtool did not produce StaticR.rel", relPath);
-
-        var dolSha = Sha256Of(dolPath);
-        var relSha = Sha256Of(relPath);
-        if (!string.Equals(dolSha, manifest.DolSha256, StringComparison.Ordinal))
-        {
-            throw new InvalidOperationException(
-                $"main.dol sha256 mismatch: expected {manifest.DolSha256}, got {dolSha}. " +
-                "This disc revision does not match what this project's manifest is pinned to.");
-        }
-        if (!string.Equals(relSha, manifest.RelSha256, StringComparison.Ordinal))
-        {
-            throw new InvalidOperationException(
-                $"StaticR.rel sha256 mismatch: expected {manifest.RelSha256}, got {relSha}. " +
-                "This disc revision does not match what this project's manifest is pinned to.");
-        }
-
        Directory.CreateDirectory(assetsDirectory);
-        File.Copy(dolPath, Path.Combine(assetsDirectory, "main.dol"), overwrite: true);
-        File.Copy(relPath, Path.Combine(assetsDirectory, "StaticR.rel"), overwrite: true);
+        var dataDir = Path.Combine(assetsDirectory, "DATA");
+        var backup = dataDir + ".replaced";
+        if (!Directory.Exists(dataDir) && Directory.Exists(backup)) Directory.Move(backup, dataDir);
+        if (Directory.Exists(backup)) Directory.Delete(backup, recursive: true);
+        var staging = dataDir + ".extracting";
+        if (Directory.Exists(staging)) Directory.Delete(staging, recursive: true);
+        try
+        {
+            await RunExtractAsync(nodTool, isoPath, staging, cancellationToken);
+            var dolPath = Path.Combine(staging, "sys", "main.dol");
+            var relPath = Path.Combine(staging, "files", "rel", "StaticR.rel");
+            if (!File.Exists(dolPath)) throw new FileNotFoundException("nodtool did not produce main.dol", dolPath);
+            if (!File.Exists(relPath)) throw new FileNotFoundException("nodtool did not produce StaticR.rel", relPath);
+
+            var dolSha = Sha256Of(dolPath);
+            var relSha = Sha256Of(relPath);
+            if (!string.Equals(dolSha, manifest.DolSha256, StringComparison.Ordinal))
+            {
+                throw new InvalidOperationException(
+                    $"main.dol sha256 mismatch: expected {manifest.DolSha256}, got {dolSha}. " +
+                    "This disc revision does not match what this project's manifest is pinned to.");
+            }
+            if (!string.Equals(relSha, manifest.RelSha256, StringComparison.Ordinal))
+            {
+                throw new InvalidOperationException(
+                    $"StaticR.rel sha256 mismatch: expected {manifest.RelSha256}, got {relSha}. " +
+                    "This disc revision does not match what this project's manifest is pinned to.");
+            }
+
+            cancellationToken.ThrowIfCancellationRequested();
+            if (Directory.Exists(dataDir)) Directory.Move(dataDir, backup);
+            try
+            {
+                Directory.Move(staging, dataDir);
+            }
+            catch
+            {
+                if (Directory.Exists(backup)) Directory.Move(backup, dataDir);
+                throw;
+            }
+            FileSystemUtilities.WriteAtomic(Path.Combine(assetsDirectory, "main.dol"),
+                File.ReadAllBytes(Path.Combine(dataDir, "sys", "main.dol")));
+            FileSystemUtilities.WriteAtomic(Path.Combine(assetsDirectory, "StaticR.rel"),
+                File.ReadAllBytes(Path.Combine(dataDir, "files", "rel", "StaticR.rel")));
+        }
+        finally
+        {
+            if (Directory.Exists(staging)) Directory.Delete(staging, recursive: true);
+        }
+        if (Directory.Exists(backup)) Directory.Delete(backup, recursive: true);
        reporter.Progress(InstallStages.ExtractDisc, "Disc validated and extracted", 6);
    }

@@ -75,9 +96,20 @@ internal static class DiscTool
        };
        using var process = System.Diagnostics.Process.Start(startInfo)
            ?? throw new InvalidOperationException($"Failed to start {nodTool}.");
-        var stdout = await process.StandardOutput.ReadToEndAsync(cancellationToken);
-        var stderr = await process.StandardError.ReadToEndAsync(cancellationToken);
-        await process.WaitForExitAsync(cancellationToken);
+        var stdoutTask = process.StandardOutput.ReadToEndAsync();
+        var stderrTask = process.StandardError.ReadToEndAsync();
+        try
+        {
+            await process.WaitForExitAsync(cancellationToken);
+        }
+        catch (OperationCanceledException)
+        {
+            if (!process.HasExited) process.Kill(entireProcessTree: true);
+            await process.WaitForExitAsync(CancellationToken.None);
+            throw;
+        }
+        var stdout = await stdoutTask;
+        var stderr = await stderrTask;
        if (process.ExitCode != 0)
        {
            throw new InvalidOperationException(
@@ -104,9 +136,20 @@ internal static class DiscTool

        using var process = System.Diagnostics.Process.Start(startInfo)
            ?? throw new InvalidOperationException($"Failed to start {nodTool}.");
-        var stdout = await process.StandardOutput.ReadToEndAsync(cancellationToken);
-        var stderr = await process.StandardError.ReadToEndAsync(cancellationToken);
-        await process.WaitForExitAsync(cancellationToken);
+        var stdoutTask = process.StandardOutput.ReadToEndAsync();
+        var stderrTask = process.StandardError.ReadToEndAsync();
+        try
+        {
+            await process.WaitForExitAsync(cancellationToken);
+        }
+        catch (OperationCanceledException)
+        {
+            if (!process.HasExited) process.Kill(entireProcessTree: true);
+            await process.WaitForExitAsync(CancellationToken.None);
+            throw;
+        }
+        var stdout = await stdoutTask;
+        var stderr = await stderrTask;
        if (process.ExitCode != 0)
        {
            throw new InvalidOperationException(
@@ -15,6 +15,7 @@
    <InvariantGlobalization>true</InvariantGlobalization>
  </PropertyGroup>
  <ItemGroup>
+    <InternalsVisibleTo Include="Translator.Tests" />
    <ProjectReference Include="..\WiiCompiled.Setup.Common\WiiCompiled.Setup.Common.csproj" />
  </ItemGroup>
 </Project>
@@ -244,6 +244,10 @@ else
    translator() { "$dotnet_bin" "$translator_dll" "$@"; }
 fi

+if (( builds_retro && !skip_retro_wfc_payload )); then
+    translator validate-retro-wfc-payload --directory "$retro_wfc_offline_dir"
+fi
+
 # ---------------------------------------------------------------------------
 # Parallelism: three independent knobs, same reasoning as LocalBuild.ps1 -
 # translator_threads (translation's own worker threads), translated_jobs (the real RAM guard,
@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 # Builds WiiCompiled VR for the Steam Frame from a release and your own disc, and installs it on the
-# Frame. Run it again to update: it fetches the newest release and rebuilds only what changed.
+# Frame. Run it again with --update to update: it fetches the newest release and rebuilds only what
+# changed, with the options it was installed with.
 #
 #   Launcher/steam-frame-install.sh --disc PATH [--frame HOST] [options]
+#   Launcher/steam-frame-install.sh --update
 #
 # Or without downloading anything first:
 #
@@ -36,32 +38,89 @@
 #   --retro-rewind-pack DIR
 #                     use this RetroRewind6 folder instead of downloading one (implies
 #                     --retro-rewind); it is copied into the work dir and never changed
+#   --update          update an earlier install: its options are reused (any given here win), and
+#                     nothing is built when the Frame already has the newest release and Retro
+#                     Rewind pack. Follows releases unless it was installed with --source.
+#   --check           only say whether an update is available; nothing is changed
 #   -h, --help
+#
+# Installed with --frame local, the game can update itself: Settings > Updates in the game checks
+# for a new release, and its Update button runs this script with --update in the background,
+# through a systemd user service this script sets up. The tab shows the update's progress while the
+# game stays open, and a game closed meanwhile is opened again when the update is done.
 set -euo pipefail

 # Everything is in main, so bash has read the whole script before running any of it: when it comes
 # through curl | bash, a step that reads stdin cannot eat the rest. (Not indented, for the heredocs.)
 main() {
-trap 'printf "\nsteam-frame-install.sh: stopped by a failed step (line %s); the output above says why.\n" "$LINENO" >&2' ERR
+# What the error path below reads, set before anything can fail into it.
+mode=install
+steam_game_id=""
+trap 'on_error "$LINENO"' ERR

 repo=mitch030504/Wiicompiled_VR_Frame
 game_id=WiiCompiled
 image=docker.io/library/debian:trixie
 container=wiicompiled-frame-build
 nodtool_version=v2.0.0-alpha.10
+# Where the game keeps its settings, and where an update it starts reports back to it. Resolved as
+# the game resolves it (RuntimeConfigFile::ApplicationDataDirectory).
+game_data="${XDG_DATA_HOME:-$HOME/.local/share}/$game_id"

-say() { printf '\n\033[1m==> %s\033[0m\n' "$*"; }
+say() {
+    printf '\n\033[1m==> %s\033[0m\n' "$*"
+    status running "$*"
+}
 note() { printf '    %s\n' "$*"; }
 fail() {
    printf '\nsteam-frame-install.sh: error: %s\n' "$*" >&2
+    finish_failed "${1%%$'\n'*}"
+}
+on_error() {
+    printf '\nsteam-frame-install.sh: stopped by a failed step (line %s); the output above says why.\n' "$1" >&2
+    finish_failed "a step failed (line $1)"
+}
+finish_failed() {
+    trap - ERR
+    status failed "$1"
+    relaunch
    exit 1
 }
 usage() { awk 'NR == 1 { next } /^#/ { sub(/^# ?/, ""); print; next } { exit }' "$script_path"; }

+# The game's Updates tab reads this: "<state>\t<unix time>\t<text>", state running, available,
+# uptodate, done or failed. Written only when the game asked for this run
+# (WIICOMPILED_UPDATE_STATUS names the file).
+status() {
+    local file=${WIICOMPILED_UPDATE_STATUS:-}
+    [[ -n "$file" ]] || return 0
+    { printf '%s\t%s\t%s\n' "$1" "$(date +%s)" "$2" > "$file.new" && mv -f "$file.new" "$file"; } 2>/dev/null || true
+}
+
+# Progress goes to that file rather than to Steam notifications: on the Frame, SteamOS's
+# steam_notif_daemon accepts a notify-send and Steam then shows nothing, even when given the
+# notification directly with steam -ifrunning (tried on a Frame, 2026-10).
+# An update the game started ends by opening the game again if it was closed meanwhile, which is
+# how its result gets seen; a game still open shows the result in its Updates tab.
+game_running() { pgrep -f "devkit-game/($game_id|RetroRewind)/" >/dev/null 2>&1; }
+relaunch() {
+    if [[ -n "${install_lock:-}" ]]; then
+        flock -u "$install_lock"
+        exec {install_lock}>&-
+        unset install_lock
+    fi
+    [[ -n "$steam_game_id" ]] || return 0
+    command -v steam >/dev/null 2>&1 || return 0
+    if game_running; then return 0; fi
+    note "opening $game_id again"
+    timeout 60 steam "steam://rungameid/$steam_game_id" >/dev/null 2>&1 || true
+}
+
 script_path=${BASH_SOURCE[0]:-}
 script_dir=""
 if [[ -n "$script_path" && -f "$script_path" ]]; then
    script_dir=$(cd "$(dirname "$script_path")" && pwd)
+    script_path="$script_dir/$(basename "$script_path")"
 fi

 disc=""
@@ -85,15 +144,253 @@ while [[ $# -gt 0 ]]; do
        --frame-disc) frame_disc=$2; shift 2 ;;
        --retro-rewind) retro_rewind=1; shift ;;
        --retro-rewind-pack) retro_rewind=1; retro_pack=$2; shift 2 ;;
+        --update) mode=update; shift ;;
+        --check) mode=check; shift ;;
        -h|--help)
            if [[ -n "$script_dir" ]]; then usage; else echo "See the comment at the top of the script."; fi
            exit 0 ;;
        *) fail "unknown argument: $1 (see --help)" ;;
    esac
 done
+# What --update reuses: the options given, before defaults fill the rest in.
+jobs_given=$jobs
+source_given=$source_dir

 mkdir -p "$work_dir"
 work_dir=$(cd "$work_dir" && pwd)
+
+command -v flock >/dev/null || fail "flock is required (install util-linux)."
+exec {install_lock}>"$work_dir/.install.lock"
+flock -n "$install_lock" || fail "Another install or update is using $work_dir. Wait for it to finish."
+command -v python3 >/dev/null || fail "Python 3 is required for installation."
+
+# The game's Update button leaves a request file; the service that runs this script moves it here.
+if [[ -n "${WIICOMPILED_UPDATE_REQUEST:-}" && -f "$WIICOMPILED_UPDATE_REQUEST" ]]; then
+    steam_game_id=$(sed -n 's/^steam_game_id=\([0-9]*\)$/\1/p' "$WIICOMPILED_UPDATE_REQUEST" | head -n 1)
+    rm -f "$WIICOMPILED_UPDATE_REQUEST"
+fi
+
+if [[ "$mode" != install && -f "$work_dir/install.conf" ]]; then
+    while IFS='=' read -r key value; do
+        case "$key" in
+            frame) [[ -n "$frame" ]] || frame=$value ;;
+            frame_disc) [[ -n "$frame_disc" ]] || frame_disc=$value ;;
+            jobs) [[ -n "$jobs" ]] || jobs=$value ;;
+            source) [[ -n "$source_dir" ]] || source_dir=$value ;;
+            retro_rewind) if [[ "$value" == 1 ]]; then retro_rewind=1; fi ;;
+            retro_rewind_pack) [[ -n "$retro_pack" ]] || retro_pack=$value ;;
+        esac
+    done < "$work_dir/install.conf"
+    jobs_given=$jobs
+    source_given=$source_dir
+fi
+frame_files() {
+    python3 - "$@" <<'FRAME_FILES_PY'
+import filecmp
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import sys
+import tempfile
+
+
+def atomic_write(path, text):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=path.name + '.', dir=path.parent)
+    try:
+        with os.fdopen(descriptor, 'w', encoding='utf-8') as output:
+            output.write(text)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def set_path(key, value):
+    if key not in ('dvd_root', 'retro_rewind_root'):
+        raise ValueError('Unknown runtime path key')
+    config = Path.home() / '.local/share/WiiCompiled/Config.toml'
+    value = os.path.expanduser(value)
+    if not os.path.isabs(value):
+        value = str(Path.home() / value)
+    lines = config.read_text(encoding='utf-8').splitlines(keepends=True) if config.exists() else []
+    # JSON strings use the escaping needed by TOML basic strings for filesystem paths.
+    setting = key + ' = ' + json.dumps(value, ensure_ascii=False) + '\n'
+    start = next((i for i, line in enumerate(lines) if re.fullmatch(r"\s*\[\s*[\"']?paths[\"']?\s*\]\s*(?:#.*)?", line.strip())), None)
+    if start is None:
+        lines += ['\n[paths]\n', setting]
+    else:
+        end = next((i for i in range(start + 1, len(lines)) if lines[i].lstrip().startswith('[')), len(lines))
+        matches = [i for i in range(start + 1, end) if re.match(r"\s*[\"']?" + key + r"[\"']?\s*=", lines[i])]
+        for i in reversed(matches):
+            del lines[i]
+        lines.insert(start + 1, setting)
+    atomic_write(config, ''.join(line if line.endswith('\n') else line + '\n' for line in lines))
+
+
+def sync_source(source, destination):
+    source, destination = Path(source), Path(destination)
+    manifest = destination / '.release-files'
+    old = manifest.read_text(encoding='utf-8').splitlines() if manifest.exists() else []
+    current = sorted(str(path.relative_to(source)) for path in source.rglob('*') if path.is_file() or path.is_symlink())
+    current_set = set(current)
+    for name in old:
+        relative = Path(name)
+        if relative.is_absolute() or '..' in relative.parts or not relative.parts:
+            raise ValueError('Invalid release-owned path: ' + name)
+        if name not in current_set:
+            target = destination / relative
+            if target.is_symlink() or target.is_file():
+                target.unlink()
+    for name in current:
+        incoming, target = source / name, destination / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if incoming.is_symlink():
+            if target.is_symlink() and os.readlink(target) == os.readlink(incoming):
+                continue
+            if target.exists() or target.is_symlink():
+                target.unlink()
+            target.symlink_to(os.readlink(incoming))
+        elif target.is_symlink() or not target.is_file() or not filecmp.cmp(incoming, target, shallow=False):
+            if target.is_symlink():
+                target.unlink()
+            shutil.copyfile(incoming, target)
+            shutil.copymode(incoming, target)
+        else:
+            shutil.copymode(incoming, target)
+    atomic_write(manifest, '\n'.join(current) + '\n')
+
+
+if __name__ == '__main__':
+    if sys.argv[1] == 'config':
+        set_path(*sys.argv[2:])
+    elif sys.argv[1] == 'sync':
+        sync_source(*sys.argv[2:])
+    else:
+        raise ValueError('Unknown file operation')
+FRAME_FILES_PY
+}
+
+save_settings() {
+    cat > "$work_dir/install.conf" <<EOF
+# Written by steam-frame-install.sh after each install: the options --update reuses.
+frame=$frame
+frame_disc=$frame_disc
+jobs=$jobs_given
+source=$source_given
+retro_rewind=$retro_rewind
+retro_rewind_pack=$retro_pack
+EOF
+}
+
+# ---------------------------------------------------------------------------------------------
+# Talking to the Frame, and the versions involved. Up here because --update and --check read them
+# before anything is built.
+# One SSH connection for every step, so a password is asked for once.
+ssh_opts=(-o ControlMaster=auto -o "ControlPath=${XDG_RUNTIME_DIR:-/tmp}/wiicompiled-ssh-%C" -o ControlPersist=600)
+on_frame() {
+    # Runs a bash script, given on stdin, on the Frame; its arguments follow.
+    if [[ "$frame" == local ]]; then
+        bash -s -- "$@"
+    else
+        local arguments
+        printf -v arguments ' %q' "$@"
+        ssh "${ssh_opts[@]}" "$frame" "bash -s --$arguments"
+    fi
+}
+read_on_frame() {
+    # Prints the contents of $1 on the Frame, with its whitespace removed, or nothing.
+    on_frame "$1" <<'EOF'
+[[ "$1" = /* ]] && f=$1 || f="$HOME/$1"
+tr -d '[:space:]' 2>/dev/null < "$f" || true
+EOF
+}
+frame_game_dir="devkit-game/$game_id"
+
+newest_release() {
+    curl -fsSL "https://api.github.com/repos/$repo/releases?per_page=1" |
+        sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p' | head -n 1
+}
+
+# Retro Rewind's own versioning, as its update server publishes it.
+rr_server=https://update.rwfc.net/RetroRewind/
+rr_version_ok() { [[ "$1" =~ ^[0-9]+(\.[0-9]+)+$ ]]; }
+rr_newer() {
+    # True when version $1 is newer than $2 (dotted numbers, as 6.12.7).
+    [[ "$1" != "$2" && "$(printf '%s\n%s\n' "$1" "$2" | sort -V | tail -n 1)" == "$1" ]]
+}
+rr_fetch() { curl -fsSL --retry 2 "$1"; }
+rr_published_version() {
+    rr_fetch "${rr_server}RetroRewindVersion.txt" |
+        awk 'NF >= 4 && $1 ~ /^[0-9]+(\.[0-9]+)+$/ { print $1 }' | sort -V | tail -n 1
+}
+# Where the pack sits on the Frame: beside the disc, as the install below puts it.
+frame_pack_path_for() {
+    local disc=${1#\~/}
+    [[ -n "$disc" ]] || disc=wiicompiled/disc
+    if [[ "$disc" == */* ]]; then printf '%s/RetroRewind6\n' "$(dirname "$disc")"; else printf 'RetroRewind6\n'; fi
+}
+
+# ---------------------------------------------------------------------------------------------
+# --update and --check: what the Frame has against what is published. Nothing is built when the
+# Frame is already current, so an update that has nothing to do costs one web request.
+if [[ "$mode" != install ]]; then
+    [[ -n "$frame" ]] || fail "--$mode updates an install made by this script, and there is none in
+    $work_dir. Install first (see --help), or pass --work-dir and --frame."
+    say "Checking for an update"
+    reasons=()
+    if [[ -n "$source_dir" ]]; then
+        # A source install has no published version to compare against; it rebuilds what changed.
+        reasons+=("it was installed from the source tree in $source_dir, which is rebuilt as it is")
+    else
+        if [[ -z "$release" ]]; then
+            release=$(newest_release) ||
+                fail "could not reach github.com to ask for the newest release. Check this machine's
+    internet connection, then try again."
+            [[ -n "$release" ]] || fail "could not find the newest release on github.com/$repo"
+        fi
+        frame_installed_release=$(read_on_frame "$frame_game_dir/.release-tag") ||
+            fail "cannot reach $frame over SSH to ask which release it has."
+        if [[ "$frame_installed_release" == "$release" ]]; then
+            note "the Frame has release $release"
+        elif [[ -z "$frame_installed_release" ]]; then
+            reasons+=("the Frame does not say which release it has; release $release would be installed")
+        else
+            reasons+=("release $release (the Frame has $frame_installed_release)")
+        fi
+    fi
+    if (( retro_rewind )) && [[ -z "$retro_pack" ]]; then
+        rr_published=$(rr_published_version) ||
+            fail "could not reach Retro Rewind's update server (${rr_server})"
+        rr_installed=$(read_on_frame "$(frame_pack_path_for "$frame_disc")/version.txt")
+        if ! rr_version_ok "$rr_installed"; then
+            reasons+=("the Frame does not say which Retro Rewind pack it has")
+        elif rr_newer "$rr_published" "$rr_installed"; then
+            reasons+=("Retro Rewind $rr_published (the Frame has $rr_installed)")
+        else
+            note "the Frame has Retro Rewind $rr_installed"
+        fi
+    fi
+
+    if (( ${#reasons[@]} == 0 )); then
+        say "Up to date"
+        status uptodate "Up to date${release:+ (}${release}${release:+)}"
+        relaunch
+        exit 0
+    fi
+    note "an update is available:"
+    for line in "${reasons[@]}"; do note "  $line"; done
+    if [[ "$mode" == check ]]; then
+        status available "${reasons[0]}"
+        exit 0
+    fi
+    status running "Starting the update${release:+ to }$release"
+fi
+
 host_arch=$(uname -m)
 case "$host_arch" in
    x86_64|aarch64) ;;
@@ -174,20 +471,14 @@ else
        curl -fL --progress-bar "https://github.com/$repo/archive/refs/tags/$release.tar.gz" |
            tar -xz --strip-components=1 -C "$work_dir/source-new" ||
            fail "could not download release $release; the Releases page on github.com/$repo lists them"
-        # Only files whose content changed are copied, stamped with the current time, so the build
-        # recompiles exactly those; the release's own file dates can be older than the last build.
-        if command -v rsync >/dev/null 2>&1; then
-            rsync -rcE "$work_dir/source-new/" "$source_dir/"
-        else
-            (cd "$work_dir/source-new" && find . -type f -print0) |
-                while IFS= read -r -d '' file; do
-                    if ! cmp -s "$work_dir/source-new/$file" "$source_dir/$file"; then
-                        mkdir -p "$source_dir/$(dirname "$file")"
-                        cp "$work_dir/source-new/$file" "$source_dir/$file"
-                        touch "$source_dir/$file"
-                    fi
-                done
+        # Old installs have no ownership manifest; recover it from their exact release.
+        if [[ ! -f "$source_dir/.release-files" && -n "$have" ]]; then
+            curl -fL --progress-bar "https://github.com/$repo/archive/refs/tags/$have.tar.gz" |
+                tar -tz | sed -e 's@^[^/]*/@@' -e '/\/$/d' -e '/^$/d' > "$source_dir/.release-files.partial" ||
+                fail "could not recover the previous release's file list; keeping the source untouched"
+            mv "$source_dir/.release-files.partial" "$source_dir/.release-files"
        fi
+        frame_files sync "$work_dir/source-new" "$source_dir"
        rm -rf "$work_dir/source-new"
        printf '%s\n' "$release" > "$source_dir/.release-tag"
    fi
@@ -344,16 +635,10 @@ fi
 # ---------------------------------------------------------------------------------------------
 # Retro Rewind: its pack, as its update server publishes it, and the Retro-WFC payload its online
 # play runs. Same steps as the Quest app (android/.../RetroRewindPack.kt and GameBuild.kt).
-rr_server=https://update.rwfc.net/RetroRewind/
+# Its server, versions and comparisons are up with the other version helpers.
 rr_pack="$work_dir/RetroRewind6"
 rr_payload="$work_dir/retro-wfc/binary/payload.RMCPD00.bin"

-rr_version_ok() { [[ "$1" =~ ^[0-9]+(\.[0-9]+)+$ ]]; }
-rr_newer() {
-    # True when version $1 is newer than $2 (dotted numbers, as 6.12.7).
-    [[ "$1" != "$2" && "$(printf '%s\n%s\n' "$1" "$2" | sort -V | tail -n 1)" == "$1" ]]
-}
-rr_fetch() { curl -fsSL --retry 2 "$1"; }
 rr_unpack_update() {
    # rr_unpack_update URL DEST: downloads a published zip and lays its RetroRewind6/ tree over DEST.
    # Only that tree is kept; the Riivolution XML beside it belongs to a Wii setup.
@@ -499,8 +784,31 @@ fi
 "$runtime" start "$container" >/dev/null
 note "container $container (mounts ${want_mounts//;/ })"

+build_progress() {
+    # Passes the build's output on, and keeps the game's status file at the stage it is on and how
+    # far through it ninja is, from the "[done/total]" lines it prints.
+    local line stage=Building percent last=-1
+    while IFS= read -r line; do
+        printf '%s\n' "$line"
+        [[ -n "${WIICOMPILED_UPDATE_STATUS:-}" ]] || continue
+        if [[ "$line" == "== "* ]]; then
+            stage=${line#== }
+            stage=${stage%% (*}
+            last=-1
+            status running "$stage"
+        elif [[ "$line" =~ ^\[([0-9]+)/([0-9]+)\] ]] && (( BASH_REMATCH[2] > 0 )); then
+            percent=$(( BASH_REMATCH[1] * 100 / BASH_REMATCH[2] ))
+            if (( percent != last )); then
+                last=$percent
+                status running "$stage, $percent% built"
+            fi
+        fi
+    done
+}
+
 say "Building (the first time takes hours under emulation; a log is in $work_dir/build.log)"
-if ! "$runtime" exec -e JOBS="$jobs" -e RETRO_REWIND="$retro_rewind" "$container" bash /work/container-build.sh 2>&1 | tee "$work_dir/build.log"; then
+if ! "$runtime" exec -e JOBS="$jobs" -e RETRO_REWIND="$retro_rewind" "$container" bash /work/container-build.sh 2>&1 |
+    tee "$work_dir/build.log" | build_progress; then
    fail "the build stopped; the end of $work_dir/build.log says why. Run the script again to resume.
    A machine that froze ran out of memory: pass a lower --jobs."
 fi
@@ -520,12 +828,7 @@ if [[ -z "$frame" ]]; then
 fi

 say "Installing on the Frame"
-# One SSH connection for every step, so a password is asked for once.
-ssh_opts=(-o ControlMaster=auto -o "ControlPath=${XDG_RUNTIME_DIR:-/tmp}/wiicompiled-ssh-%C" -o ControlPersist=600)
-on_frame() {
-    # Runs a bash script, given on stdin, on the Frame; its arguments follow.
-    if [[ "$frame" == local ]]; then bash -s -- "$@"; else ssh "${ssh_opts[@]}" "$frame" bash -s -- "$@"; fi
-}
+# on_frame and the SSH options it uses are up with the version helpers.
 copy_to_frame() {
    # copy_to_frame SOURCE DEST: DEST is absolute or relative to the Frame's home. A DEST ending in
    # / is an existing folder SOURCE goes into; otherwise SOURCE is copied to that new name.
@@ -563,6 +866,11 @@ EOF
    copy_to_frame "$out/$id" "$dir/$id.new"
    on_frame "$dir" "$id" <<'EOF'
 cd "$HOME/$1" && mv -f "$2.new" "$2" && chmod -R u=rwX,go=rX . && chmod 755 "$2"
+EOF
+    # Which release is on the Frame, for --check and the game's Updates tab. A source build has no
+    # release to name, and the stamp is removed so neither claims a release this is not.
+    on_frame "$dir" "$release" <<'EOF'
+cd "$HOME/$1" && if [[ -n "$2" ]]; then printf '%s\n' "$2" > .release-tag; else rm -f .release-tag; fi
 EOF
 }
 install_game "$game_id" "$work_dir/out"
@@ -594,13 +902,8 @@ fi

 if (( retro_rewind )); then
    # The pack goes beside the disc; copied again only when its version changed.
-    frame_pack_path="$(dirname "$frame_disc_path")/RetroRewind6"
-    [[ "$frame_disc_path" == */* ]] || frame_pack_path=RetroRewind6
-    frame_pack_version=$(on_frame "$frame_pack_path" <<'EOF'
-[[ "$1" = /* ]] && d=$1 || d="$HOME/$1"
-tr -d '[:space:]' 2>/dev/null < "$d/version.txt" || true
-EOF
-)
+    frame_pack_path=$(frame_pack_path_for "$frame_disc_path")
+    frame_pack_version=$(read_on_frame "$frame_pack_path/version.txt")
    local_pack_version=$(tr -d '[:space:]' 2>/dev/null < "$rr_pack/version.txt" || true)
    if [[ -z "$frame_pack_version" || "$frame_pack_version" != "$local_pack_version" ]]; then
        note "copying the Retro Rewind pack to $frame_pack_path (about 4 GB)"
@@ -614,38 +917,18 @@ EOF
 rm -rf "$d" && mv "$d.partial" "$d"
 EOF
    fi
-    note "pointing Retro Rewind at its pack"
-    on_frame "$frame_pack_path" <<'EOF'
-[[ "$1" = /* ]] && d=$1 || d="$HOME/$1"
-config="$HOME/.local/share/WiiCompiled/Config.toml"
-mkdir -p "$(dirname "$config")"
-if [[ ! -f "$config" ]]; then
-    printf '[paths]\nretro_rewind_root = "%s"\n' "$d" > "$config"
-elif ! grep -q '^retro_rewind_root *=' "$config"; then
-    if grep -q '^\[paths\]' "$config"; then
-        sed -i "/^\[paths\]/a retro_rewind_root = \"$d\"" "$config"
-    else
-        printf '\n[paths]\nretro_rewind_root = "%s"\n' "$d" >> "$config"
-    fi
-fi
-EOF
 fi

-note "pointing the game at the disc"
-on_frame "$frame_disc_path" <<'EOF'
-[[ "$1" = /* ]] && d=$1 || d="$HOME/$1"
-config="$HOME/.local/share/WiiCompiled/Config.toml"
-mkdir -p "$(dirname "$config")"
-if [[ ! -f "$config" ]]; then
-    printf '[paths]\ndvd_root = "%s"\n' "$d" > "$config"
-elif ! grep -q '^dvd_root *=' "$config"; then
-    if grep -q '^\[paths\]' "$config"; then
-        sed -i "/^\[paths\]/a dvd_root = \"$d\"" "$config"
-    else
-        printf '\n[paths]\ndvd_root = "%s"\n' "$d" >> "$config"
-    fi
+set_frame_path() {
+    { declare -f frame_files; printf '%s\n' 'frame_files "$@"'; } | on_frame config "$1" "$2"
+}
+
+if (( retro_rewind )); then
+    note "pointing Retro Rewind at its pack"
+    set_frame_path retro_rewind_root "$frame_pack_path"
 fi
-EOF
+note "pointing the game at the disc"
+set_frame_path dvd_root "$frame_disc_path"

 # Steam's library: through Valve's devkit tools when Frame Control or the Devkit Client put them on
 # the Frame, as a Steam Linux Runtime ARM64 title (Steam starts an ARM64 program natively).
@@ -672,9 +955,53 @@ esac
 register_game "$game_id" "$work_dir/out"
 if (( retro_rewind )); then register_game RetroRewind "$work_dir/out-retro-rewind"; fi

+# ---------------------------------------------------------------------------------------------
+# Updating from inside the game. Only an install on the Frame itself can do it, since that is the
+# only one with the build here; installed from a PC, the game's Updates tab says to update there.
+if [[ "$frame" == local ]]; then
+    note "setting up the game's Update button"
+    update_script="$work_dir/steam-frame-install.sh"
+    # A copy, so an update never runs from the source tree it is about to overwrite.
+    cp -f "$source_dir/Launcher/steam-frame-install.sh" "$update_script"
+    chmod +x "$update_script"
+    mkdir -p "$game_data" "$HOME/.config/systemd/user"
+    cat > "$game_data/update.conf" <<EOF
+# Written by steam-frame-install.sh: what the game's Updates tab runs. Remove this file to take the
+# Update button away, and the tab goes back to saying how to update from a PC.
+script=$update_script
+work_dir=$work_dir
+service=wiicompiled-update.service
+EOF
+    # Its own service, so the update outlives the game that started it: Steam stops the game's own
+    # process group when the game closes.
+    cat > "$HOME/.config/systemd/user/wiicompiled-update.service" <<EOF
+[Unit]
+Description=WiiCompiled VR update
+
+[Service]
+Type=oneshot
+Environment=WIICOMPILED_UPDATE_STATUS=$game_data/update-status
+Environment=WIICOMPILED_UPDATE_REQUEST=$game_data/update-request
+# Below the game in line for the processor and the storage, so it can keep running meanwhile.
+Nice=19
+IOSchedulingClass=idle
+ExecStart=$update_script --update --work-dir "$work_dir"
+EOF
+    systemctl --user daemon-reload >/dev/null 2>&1 ||
+        note "(systemd did not reload, so the Update button will not work until the Frame restarts)"
+fi
+
+save_settings
+
 say "Done"
-note "Start $game_id from your library in the headset. Settings: left shoulder button, VR tab."
+status done "Updated${release:+ to }${release}"
+if [[ "$mode" == update ]]; then
+    note "Updated${release:+ to }$release."
+else
+    note "Start $game_id from your library in the headset. Settings: left shoulder button, VR tab."
+fi
 if (( retro_rewind )); then note "RetroRewind is beside it, and shares its settings."; fi
+relaunch
 }

 main "$@" </dev/null
@@ -0,0 +1,92 @@
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import tomllib
+import unittest
+from unittest.mock import patch
+
+SCRIPT = Path(__file__).resolve().parents[1] / 'steam-frame-install.sh'
+TEXT = SCRIPT.read_text()
+CODE = TEXT.split("<<'FRAME_FILES_PY'\n", 1)[1].split('\nFRAME_FILES_PY', 1)[0]
+OPERATIONS = {'__name__': 'frame_tests'}
+exec(compile(CODE, str(SCRIPT), 'exec'), OPERATIONS)
+
+
+class FrameInstallerTests(unittest.TestCase):
+    def test_source_membership_preserves_user_data_and_unchanged_timestamps(self):
+        with tempfile.TemporaryDirectory() as root:
+            root = Path(root)
+            source, live = root / 'source', root / 'live'
+            source.mkdir()
+            live.mkdir()
+            (source / 'keep.cpp').write_text('same')
+            (live / 'keep.cpp').write_text('same')
+            os.utime(live / 'keep.cpp', (100, 100))
+            (live / 'removed.cpp').write_text('old')
+            (live / '.release-files').write_text('keep.cpp\nremoved.cpp\n')
+            (live / 'Assets').mkdir()
+            (live / 'Assets/main.dol').write_text('disc')
+            (live / 'native-build').mkdir()
+            (live / 'native-build/cache').write_text('cache')
+            OPERATIONS['sync_source'](source, live)
+            self.assertFalse((live / 'removed.cpp').exists())
+            self.assertEqual(100, (live / 'keep.cpp').stat().st_mtime)
+            self.assertEqual('disc', (live / 'Assets/main.dol').read_text())
+            self.assertEqual('cache', (live / 'native-build/cache').read_text())
+
+    def test_paths_replace_only_the_right_section_and_escape_values(self):
+        with tempfile.TemporaryDirectory() as home, patch.dict(os.environ, HOME=home):
+            config = Path(home) / '.local/share/WiiCompiled/Config.toml'
+            config.parent.mkdir(parents=True)
+            config.write_text('[other]\ndvd_root = "untouched"\n[ "paths" ] # paths\n"dvd_root" = "old"\n[video]\nscale = 2')
+            value = '/media/My Games/a"b\\c\nfolder'
+            OPERATIONS['set_path']('dvd_root', value)
+            parsed = tomllib.loads(config.read_text())
+            self.assertEqual(value, parsed['paths']['dvd_root'])
+            self.assertEqual('untouched', parsed['other']['dvd_root'])
+            self.assertEqual(2, parsed['video']['scale'])
+            OPERATIONS['set_path']('retro_rewind_root', 'packs/My Pack')
+            self.assertEqual(str(Path(home) / 'packs/My Pack'), tomllib.loads(config.read_text())['paths']['retro_rewind_root'])
+
+    def test_ssh_keeps_argument_boundaries(self):
+        function = TEXT.split('on_frame() {', 1)[1].split('\n}\n', 1)[0]
+        script = 'ssh_opts=(); frame=remote\nssh() { bash -c "${@: -1}"; }\non_frame() {' + function + '\n}\non_frame "$@"'
+        arguments = ['/media/My Games/disc', "quote'and$characters", '']
+        result = subprocess.run(['bash', '-c', script, 'test', *arguments], input='printf "%s\\0" "$@"\n', capture_output=True, text=True, check=True)
+        self.assertEqual('\0'.join(arguments) + '\0', result.stdout)
+
+    def test_lock_blocks_a_second_installer(self):
+        locking = TEXT.split('command -v flock >/dev/null || fail', 1)[1].split('\n', 1)[1].split('command -v python3', 1)[0]
+        setup = 'work_dir=$1; fail() { echo "$*" >&2; exit 1; }\n'
+        with tempfile.TemporaryDirectory() as root:
+            holder = subprocess.Popen(['bash', '-c', setup + locking + '\necho ready; read -r', 'test', root], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
+            try:
+                self.assertEqual('ready\n', holder.stdout.readline())
+                contender = subprocess.run(['bash', '-c', setup + locking, 'test', root], capture_output=True, text=True)
+                self.assertEqual(1, contender.returncode)
+                self.assertIn('Another install or update', contender.stderr)
+            finally:
+                holder.communicate('\n')
+            self.assertEqual(0, subprocess.run(['bash', '-c', setup + locking, 'test', root]).returncode)
+
+    def test_unsigned_payload_stops_before_translation(self):
+        build = SCRIPT.with_name('local-build.sh').read_text()
+        block = build.split('if (( builds_retro && !skip_retro_wfc_payload )); then', 1)[1].split('\nfi', 1)[0]
+        setup = 'builds_retro=1; skip_retro_wfc_payload=0; retro_wfc_offline_dir="/payload folder"\n'
+        check = 'translator() { [[ "$1" == validate-retro-wfc-payload && "$2" == --directory && "$3" == "/payload folder" ]] || exit 99; return 23; }\n'
+        result = subprocess.run(['bash', '-e', '-c', setup + check + block + '\necho translated'], capture_output=True, text=True)
+        self.assertEqual(23, result.returncode)
+        self.assertNotIn('translated', result.stdout)
+
+    def test_config_function_can_be_sent_to_remote_bash(self):
+        function = TEXT.split('frame_files() {', 1)[1].split('\n}\n', 1)[0]
+        with tempfile.TemporaryDirectory() as home:
+            result = subprocess.run(['bash', '-s', '--', 'config', 'dvd_root', '/new disc'], input='frame_files() {' + function + '\n}\nframe_files "$@"\n', text=True, capture_output=True, env={**os.environ, 'HOME': home})
+            self.assertEqual(0, result.returncode, result.stderr)
+            config = Path(home) / '.local/share/WiiCompiled/Config.toml'
+            self.assertEqual('/new disc', tomllib.loads(config.read_text())['paths']['dvd_root'])
+
+
+if __name__ == '__main__':
+    unittest.main()
@@ -147,6 +147,15 @@ headroom. It is live: **F10 → VR → Render resolution** (also on the headset
 in percent, applies it when the slider is let go, and saves it. Below the slider, *Each eye* gives
 the left eye's size now and, while they differ, the size the slider's value gives.

+`adaptive_resolution` (default off; *Adaptive resolution (experimental)* on the VR tab) lowers the
+race's eye resolution in 10% steps, down to 70% of `render_scale`, while new eye frames fall below
+85% of the game's 60 FPS, and raises it again after three seconds on time. The eyes render into the
+top-left corner of the full swapchain image and the projection layer shows only that corner, so the
+compositor scales them up and no swapchain is rebuilt; each step does rebuild the foveation maps.
+`console.log` records every change as `OpenXR: adaptive resolution`. It is offered on the Quest and
+the Linux (Steam Frame) build, not on Windows, whose bridges copy whole eyes. Adapted from
+heurazy's [Wiicompiled_VR-PLUS](https://github.com/heurazy/Wiicompiled_VR-PLUS).
+
 A new scale never interrupts the picture. Each backend keeps two swapchain pairs, one on display and
 one Aurora writes next, and rebuilds only the second, at the start of the frame that writes it; the
 other follows a frame later, once it is the one written. The new swapchains are created before the
@@ -1282,7 +1291,7 @@ custom DLL's ABI through three borrowed-image copy/readback cycles; run it with
 | Windows D3D12 | Implemented: same-adapter, same-device asynchronous OpenXR submission. |
 | Windows Vulkan | Implemented, opt-in (`video.graphics_api = "vulkan"`): the runtime creates Dawn's Vulkan instance and device through `XR_KHR_vulkan_enable2`, eyes are copied on the same queue, and Dawn's device guard is held around the four queue-touching OpenXR calls. Needs the custom Dawn from `Launcher/Build-DawnVulkan.ps1`. Raced on SteamVR/PSVR2 at the headset's full rate; other runtimes unexercised. See [Windows Vulkan](#windows-vulkan). |
 | Android Vulkan (Meta Quest) | Implemented and running on a Quest 3: the OpenXR side owns its own Vulkan device (`XR_KHR_vulkan_enable2`, `XR_KHR_vulkan_enable` fallback) and shares eyes with Dawn through `AHardwareBuffer`s ordered by sync-fd fences. Controllers arrive through OpenXR actions as a virtual SDL gamepad. See `docs/quest-port.md`. |
-| Android Vulkan (Steam Frame) | The same backend in the `steamFrame` flavour, for SteamVR's Android runtime under Lepton: Frame controller profile, 120 Hz request, eye-tracked foveation. Blocked on the headset: Lepton's Turnip exposes no AHardwareBuffer or fd external memory, so the eyes cannot cross devices. The native build below is the supported route. See the README, The Android flavour. |
+| Android Vulkan (Steam Frame) | The same backend in the `steamFrame` flavour, for SteamVR's Android runtime under Lepton: Frame controller profile, 120 Hz request, eye-tracked foveation. Blocked on the headset: Lepton's Turnip exposes no AHardwareBuffer or fd external memory, so the eyes cannot cross devices. The native build below is the supported route. See the README, How it works. |
 | Linux Vulkan (Steam Frame, SteamOS) | Implemented and played on a Steam Frame (beta): the Windows Vulkan design compiled for Linux, so the runtime creates Dawn's own instance and device and the eyes are copied on Dawn's queue with no sharing. Adds the Frame controller profile, 120 Hz and gaze-centred foveation. Needs a Dawn built with Aurora's patches (`Launcher/build-dawn-linux.sh`), then `Launcher/local-build.sh --openxr --dawn-package <dir> --headset steam_frame`. See the README, Quick start. |
 | Other platforms | Not wired yet. |

@@ -9,50 +9,65 @@
  <a href="LICENSE"><img alt="License: GPLv3" src="https://img.shields.io/badge/license-GPLv3-2EA44F?logo=gnu&amp;logoColor=white"></a>
 </p>

-Mario Kart Wii in VR on Valve's Steam Frame, running natively on SteamOS: a fork of
-[WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR) (itself built on
-[WiiCompiled](https://github.com/patchzyy/Wiicompiled)), the static recompilation of Mario Kart Wii
-to native code. There is no emulator, interpreter or JIT at runtime: your own disc is translated to
-C++ and compiled for the Frame's ARM64 CPU, and it renders through SteamVR's OpenXR runtime.
+Mario Kart Wii in VR on Valve's Steam Frame, running natively on SteamOS. It is built on
+[WiiCompiled](https://github.com/patchzyy/Wiicompiled), the static recompilation of Mario Kart Wii
+to native code, and its VR fork [WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR).
+Nothing is emulated: your own disc is translated to C++, compiled for the Frame's ARM64 processor,
+and drawn through SteamVR.

 > [!IMPORTANT]
-> There is no Nintendo code, no assets and no game data anywhere in this project. You need your
-> own legally dumped copy of the PAL version of the game; the translation runs on your machine
-> against your disc image, and nothing is uploaded.
+> This project contains no Nintendo code, assets or game data. You need your own dump of the PAL
+> disc. The game is built from it on your own machine, and nothing is uploaded or shared.

 > [!WARNING]
-> **Beta.** It runs on a Steam Frame: SteamVR, both eyes at the panels' 2160x2160, the Frame's
-> controllers, 120 Hz with every game frame shown, and foveation that follows your eyes. It is not
-> finished: images still double in races and on the HUD, and the foveation tracks the right eye
-> less well than the left (see [Known issues](#known-issues)). Reports with the run log move it
-> forward (see [Reporting problems](#reporting-problems)).
+> **Beta.** It plays on the Steam Frame at the panels' full 2160x2160 per eye, at 120 Hz, with the
+> Frame's controllers and foveation that follows your eyes. Some images still double in races and
+> on the HUD (see [Known issues](#known-issues)).
+
+**Contents:** [Quick start](#quick-start) · [Updating](#updating) ·
+[Recommended settings](#recommended-settings) · [Controls](#controls) ·
+[Known issues](#known-issues) · [Troubleshooting](#troubleshooting) ·
+[Other ways to build](#other-ways-to-build) · [How it works](#how-it-works) · [FAQ](#faq) ·
+[Credits](#credits)

 ---

 ## Quick start

-This is the whole way from your disc to playing in the headset. An install script does the work: it
-downloads the newest [release](https://github.com/mitch030504/Wiicompiled_VR_Frame/releases),
-extracts your disc, builds the game in an ARM64 container on your PC, copies it and the disc to the
-Frame, and adds it to your Steam library. Releases are source only: the game is always built from
-your own disc, so there is nothing ready-built to download. The first build takes a few hours, most
-of it compiling Dawn under emulation; later builds reuse it.
+One script takes you from your disc to the game in your Steam library. It downloads the newest
+[release](https://github.com/mitch030504/Wiicompiled_VR_Frame/releases) (currently `frame-beta-4`),
+extracts your disc, builds the game in an ARM64 container, installs it on the Frame and adds it to
+Steam. Releases hold only source code: the game is always built from your own disc.
+
+### Where to build
+
+You can run the script on a Linux PC or on the Frame itself:
+
+| | On a Linux PC | On the Frame |
+| --- | --- | --- |
+| First build | A few hours on an x86_64 PC (ARM64 is emulated), mostly building Dawn | Slower, and the Frame needs to stay on its charger |
+| Updates | Run from the PC | Also from the **Updates** tab inside the game |
+| Install option | `--frame steamos@<frame-ip>` | `--frame local` |
+
+Later builds reuse what the first one built, so updates usually take minutes.
+
+### You need

-**You need:**
 - a Steam Frame with Developer Mode on (Steam Settings → System → Enable Developer Mode, then set a
-  user password), on the same network as your PC;
- your own clean PAL `RMCP01` disc of Mario Kart Wii: an ISO, WBFS or RVZ image (WIA, CISO, GCZ
-  and NFS work too), as is or in a `.zip` or `.7z`, or a folder you extracted it to;
- an x86_64 Linux PC with about 20 GB free and 16 GB of memory or more.
-
-The PC commands below work in bash, zsh and fish.
+  user password);
+- your own clean PAL `RMCP01` disc of Mario Kart Wii, as an ISO, WBFS, RVZ, WIA, CISO, GCZ or NFS
+  image, inside a `.zip` or `.7z` if you like, or as an extracted folder;
+- about 20 GB free where the build goes (`~/wiicompiled-frame`, or another folder with
+  `--work-dir`);
+- to build on a PC: Linux on x86_64 or ARM64 with 16 GB of memory or more, Python 3 and
+  `flock` (from util-linux), on the same network as the Frame.

 > [!NOTE]
-> Nobody here will tell you where to get the game. Dumping your own disc is on you, and links to
-> game files won't be provided or tolerated. For the same reason there is no ready-built game to
-> download: releases hold the source, and the game is always built from your own disc.
+> Nobody here will tell you where to get the game, and links to game files are not tolerated.

-### 1. Set up ARM64 emulation on the PC
+### 1. Set up the container (PC only)
+
+The build runs in a Debian ARM64 container. On an x86_64 PC, set up podman with ARM64 emulation:

 ```bash
 sudo pacman -S --needed podman qemu-user-static qemu-user-static-binfmt   # Arch, CachyOS
@@ -60,77 +75,128 @@ sudo systemctl restart systemd-binfmt
 podman run --rm --platform linux/arm64 docker.io/library/debian:trixie uname -m
 ```

-The last command must print `aarch64`. On Debian or Ubuntu install `podman qemu-user-static
+The last command must print `aarch64`. On Debian or Ubuntu, install `podman qemu-user-static
 binfmt-support` instead. If podman complains about subordinate ids, run
 `sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER` and log in again.
-Docker works too, in place of podman.
+Docker works in place of podman. An ARM64 PC needs only podman or Docker, and the Frame already
+has podman.

 ### 2. Run the installer

-With the path to your disc image and your Frame's address:
+From a PC, with your disc image and the Frame's address:

 ```bash
 curl -fsSL https://raw.githubusercontent.com/mitch030504/Wiicompiled_VR_Frame/openxr-work/Launcher/steam-frame-install.sh \
    | bash -s -- --disc "/path/to/Mario Kart Wii.wbfs" --frame steamos@<frame-ip>
 ```

- `--disc` takes the image whatever its name or extension; the format is read from the file
-  itself. A `.zip` or `.7z` is unpacked first (with 7-Zip, bsdtar or unzip if you have one, in a
-  container otherwise), and the disc image inside it is found and used. It checks the game ID
-  before building and stops on any disc other than PAL `RMCP01`.
- It asks for the Frame's password when it gets there. If you use
-  [Frame Control](https://github.com/saphid/frame-control), pass `--frame frame` instead: its SSH
-  key answers to that name.
- Everything it builds lives in `~/wiicompiled-frame` (`--work-dir` to change that): the toolchain,
-  Dawn, the source, the extracted disc and the build log, `build.log`.
- It runs as many compiles at once as fit in memory (a quarter of your memory in GB). If the machine
-  still freezes, run it again with a lower `--jobs`, such as `--jobs 2`.
- If it stops for any reason, the same command picks up where it left off.
- On the Frame, the game goes to `~/devkit-game/WiiCompiled/` and the disc to `~/wiicompiled/disc`.
-  It is added to your Steam library through Valve's devkit tools in `~/devkit-utils`, which Frame
-  Control and Valve's Devkit Client put there. Without them, the script says how to add it once
-  yourself. Steam must be running on the Frame for this step.
- Add `--retro-rewind` to also build [Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind).
-  The script downloads its pack (about 4 GB) from Retro Rewind's own update server, as Wheel Wizard
-  does, and later runs apply only the updates published since. It also fetches the Retro-WFC
-  payload online play needs. On the Frame, Retro Rewind goes to `~/devkit-game/RetroRewind/` and
-  its pack to `~/wiicompiled/RetroRewind6`, and it shares WiiCompiled's settings.
-  `--retro-rewind-pack DIR` uses a RetroRewind6 folder you already have instead.
- `--help` lists every option. From a downloaded release, run `Launcher/steam-frame-install.sh`
-  with the same options: it then builds that release's source.
+Or on the Frame, over SSH (`ssh steamos@<frame-ip>`) or in a Desktop Mode terminal:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mitch030504/Wiicompiled_VR_Frame/openxr-work/Launcher/steam-frame-install.sh \
+    | bash -s -- --disc "/path/to/Mario Kart Wii.wbfs" --frame local
+```
+
+`--disc` accepts any of these:
+
+| Extension | What it is |
+| --- | --- |
+| `.iso` | A plain disc image |
+| `.wbfs` | Wii Backup File System image |
+| `.rvz` | Dolphin's compressed image |
+| `.wia` | Wii ISO Archive |
+| `.ciso` | Compact ISO |
+| `.gcz` | Dolphin's older compressed image |
+| `.nfs` | A Wii game image from a Wii U |
+| `.zip`, `.7z` | An archive holding one of the images above |
+| a folder | An extracted disc, holding `sys/` and `files/` |
+
+The script reads the format from the file's contents, so a renamed file works too.
+
+The script checks that the disc is PAL `RMCP01` before building, and stops on any other. If it
+stops for any reason, the same command picks up where it left off. From a PC, it asks for the
+Frame's password when it gets there. Steam must be running on the Frame for the last step, adding
+the game to the library.
+
+Useful options (`--help` lists them all):
+
+| Option | What it does |
+| --- | --- |
+| `--retro-rewind` | Also builds [Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind) and adds it to Steam as **RetroRewind**. Its pack (about 4 GB) comes from Retro Rewind's own update server, as Wheel Wizard fetches it, along with the Retro-WFC payload online play needs. It shares WiiCompiled's settings. |
+| `--retro-rewind-pack DIR` | Uses a RetroRewind6 folder you already have instead of downloading one. |
+| `--work-dir DIR` | Where the build lives instead of `~/wiicompiled-frame`, such as a folder on the Frame's SD card. |
+| `--jobs N` | How many files compile at once. It defaults to a quarter of your memory in GB; lower it, to `--jobs 2` for example, if the machine freezes. |
+| `--frame frame` | With [Frame Control](https://github.com/saphid/frame-control) set up, its SSH key answers to `frame`, so no password is asked. |
+| `--release TAG` | Builds a given release instead of the newest. |
+
+Leaving out `--frame` only builds the game, into `out` in the work dir.
+
+On the Frame the game goes to `~/devkit-game/WiiCompiled/`. Installed from a PC, the disc goes to
+`~/wiicompiled/disc`; with `--frame local` it stays in the work dir. Adding the game to Steam uses
+Valve's devkit tools in `~/devkit-utils`, which Frame Control and Valve's Devkit Client put there;
+without them, the script says how to add it yourself.

 ### 3. Play

-Start **WiiCompiled** from the library in the headset. Open the settings panel with the left
-shoulder button, go to the **VR** tab and set the [recommended settings](#recommended-settings).
+Start **WiiCompiled** from your library in the headset. Press the left shoulder button for the
+settings panel, and set the [recommended settings](#recommended-settings) on its **VR** tab.

-### Updating
+## Updating

-Run the same command again; you can leave out `--disc`. The script downloads the newest release,
-puts only the files that changed over the old source, rebuilds what they touch, and replaces the
-game on the Frame. Dawn is only rebuilt when a release changes its patches (the release notes say
-so), so an update usually takes minutes. `--release <tag>` builds a given release instead.
+### From the machine you installed from
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mitch030504/Wiicompiled_VR_Frame/openxr-work/Launcher/steam-frame-install.sh \
+    | bash -s -- --update
+```
+
+`--update` reuses the options you installed with, which the install saved in `install.conf` in the
+work dir. Add `--work-dir` if you used one; any option you pass wins over the saved one. It
+downloads the newest release, rebuilds only what changed and replaces the game on the Frame. When
+the Frame already has the newest release (and the newest Retro Rewind pack, if you use it), it says
+so and builds nothing. `--check` only says whether an update is available.
+
+An install made with `--frame local` keeps a copy of the script in its work dir, so on the Frame
+`~/wiicompiled-frame/steam-frame-install.sh --update` works too.
+
+### From inside the game
+
+An install made on the Frame with `--frame local` adds an **Updates** tab to the settings panel. It
+shows the release you are running; **Check for updates** looks for a new one, and **Update now**
+builds it in the background while you keep playing (the game can stutter while it compiles). The
+tab shows each step and how far the build is, and tells you when to restart the game. If you close
+the game meanwhile, the update carries on and opens the game again when it is done. Keep the Frame
+on its charger while it runs.
+
+The update runs as the systemd user service `wiicompiled-update.service`, at low priority so the
+game comes first. Installed from a PC, the tab says to update from the PC instead. Progress is not
+shown as Steam notifications, because Steam on the Frame does not display them.
+
+### Coming from frame-beta-2 or earlier
+
+Older installs saved no options for `--update` to reuse. Update once with the full install command
+from [step 2](#2-run-the-installer) (you can leave out `--disc`); from then on `--update` works. To
+get the in-game Updates tab, make that install on the Frame with `--frame local`.

 ## Recommended settings

-All of these are in the headset's settings panel (left shoulder button, **VR** tab) and in
-`~/.local/share/WiiCompiled/Config.toml`. Quit the game before editing the file; it writes its
-settings back when it closes.
+All of these are on the settings panel's **VR** tab and in `~/.local/share/WiiCompiled/Config.toml`
+on the Frame. Quit the game before editing the file, since the game saves its settings to it.

 | Setting | Value | Why |
 | --- | --- | --- |
-| `[vr] render_scale` | `1.25` | Scales SteamVR's recommended eye size, 1728x1728 on the Frame: 1.25 is the panels' native 2160x2160, which the Frame renders in 9 to 11 ms a frame with medium foveation. |
-| `[vr] foveation` | `medium` | `off` shades every pixel and costs the most. See [Known issues](#known-issues) if images double. |
-| `[vr] repeat_frames` | `true` (default) | Without it SteamVR halves the game's rate and fills refreshes itself. |
-| `[vr] frame_interpolation_fps` | `0` | Rendering in-between frames needs 120 eye pairs a second, which made things worse on the Frame. |
-| `[vr] adaptive_resolution` | `false` (default) | Experimental and untested on the Frame. When on, races drop to as little as 70% of `render_scale` while new frames fall behind 60 FPS, and climb back once they keep up. Each step rebuilds the foveation maps; `console.log` records every change as `OpenXR: adaptive resolution`. |
+| `[vr] render_scale` | `1.25` | 1.25 times SteamVR's recommended 1728x1728 is the panels' native 2160x2160, which the Frame renders in 9 to 11 ms a frame with medium foveation. |
+| `[vr] foveation` | `medium` (default) | `off` shades every pixel and costs the most. See [Known issues](#known-issues) if images double. |
+| `[vr] repeat_frames` | `true` (default) | Without it SteamVR halves the game's rate and fills in refreshes itself. |
+| `[vr] frame_interpolation_fps` | `0` (default) | In-between frames need 120 eye pairs a second, which made things worse on the Frame. |
+| `[vr] adaptive_resolution` | `false` (default) | Experimental and not yet tried in a race on the Frame. When on, races drop to as little as 70% of `render_scale` while frames fall behind 60 FPS, and climb back once they keep up. |
 | `[video] resolution_multiplier` | `2` | The game's own frame, which the eyes are made from. 4x is far too heavy for the Frame's GPU. |

-Keep SteamVR's refresh rate at 120 Hz. Motion Smoothing makes no difference to this game.
+Keep SteamVR at 120 Hz. Motion Smoothing makes no difference to this game.

 ## Controls

-The Frame's controllers are bound through their own profile, so the left D-pad works:
+The Frame's controllers have their own bindings, so the left D-pad works:

 | Frame controller | Wii Remote mode | Gamepad mode |
 | --- | --- | --- |
@@ -147,26 +213,25 @@ The Frame's controllers are bound through their own profile, so the left D-pad w

 ## Known issues

- **Doubled images** in races and on the HUD, worst while racing, sometimes in the right eye only.
-  Both eyes get the same frames, so a doubling in one eye points at foveation: the Frame's driver
-  (Turnip) draws a foveated screen tile at lower resolution and scales it back up, and each eye's
-  density maps change with its gaze. Try foveation **Off** if it bothers you, and report whether it
-  helped.
- **Foveation follows the right eye less well** than the left. Convergence on near content (the HUD
-  screen at 2 m, the cockpit) is not yet corrected for.
+- **Doubled images** in races and on the HUD, worst while racing and sometimes in one eye only.
+  Foveation is the main suspect: the Frame's graphics driver draws the outer areas at lower
+  resolution and scales them up, and each eye's foveation follows its own gaze. Try foveation
+  **Off** if it bothers you, and report whether it helped.
+- **Foveation follows the right eye less well** than the left. Eyes converging on near things (the
+  HUD screen, the cockpit) are not yet corrected for.
 - **VR frame interpolation** is not recommended on the Frame.
- **The Quest app's `steamFrame` flavour** cannot show a picture in the Frame's Android layer
-  ([below](#the-android-flavour)). Use the native build.
+- **The Quest app's Steam Frame version** shows no picture in the Frame's Android layer (see
+  [How it works](#how-it-works)). Use this native build.

 ## Troubleshooting

-**Everything at once.** From the PC, `Launcher/frame-diagnostics.sh --frame steamos@<frame-ip>` (or
-`--frame frame` with Frame Control) gathers the newest runs' logs and crash files, `Config.toml`,
-SteamVR's logs, the GPU and Vulkan driver, and the system's state into one `.tar.gz`. Its
-`summary.txt`, also printed at the end, gives the startup steps below that the newest run reached.
-`--help` lists the options.
+**Collect everything at once.** From a PC, run
+`Launcher/frame-diagnostics.sh --frame steamos@<frame-ip>` from the source
+(`~/wiicompiled-frame/source` after an install). It gathers the newest runs' logs and crash files,
+`Config.toml`, SteamVR's logs, the GPU driver and the system's state into one `.tar.gz`, and its
+`summary.txt` says how far the newest run got through the startup steps below.

-**Logs.** Each run gets a folder under `~/.local/share/WiiCompiled/Logs/` on the Frame, holding
+**Logs.** Each run gets a folder under `~/.local/share/WiiCompiled/Logs/` on the Frame, with
 `console.log` and, after a crash, `crash_sigsegv.txt`. A working start logs, in order:

 1. `OpenXR initialized: runtime 'SteamVR/OpenXR'`;
@@ -178,41 +243,80 @@ SteamVR's logs, the GPU and Vulkan driver, and the system's state into one `.tar
 7. `OpenXR eye gaze: available`, then `tracking`.

 The first one missing says where it stopped. `Linux Vulkan OpenXR requires a Dawn built with
-Aurora's patches` means the game was built without `--dawn-package`.
+Aurora's patches` means the game was built by hand without `--dawn-package`.

-**Smoothness.** With `[diagnostics] openxr_logging = true`, the log gets a pacing line every second:
+**Smoothness.** With `[diagnostics] openxr_logging = true` in `Config.toml`, the log gets a pacing
+line every second. On the Frame:

 ```bash
-ssh frame 'cd ~/.local/share/WiiCompiled/Logs && d=$(ls -t | head -1) && grep -h "xr-diag\] 1.0" "$d/console.log" | tail -5'
+cd ~/.local/share/WiiCompiled/Logs && grep -h "xr-diag\] 1.0" "$(ls -t | head -1)/console.log" | tail -5
 ```

-A healthy race reads `predicted-rate=120.0Hz`, `new=60 repeat=60` and `late=0`. Fewer than 60 `new`
+A smooth race reads `predicted-rate=120.0Hz`, `new=60 repeat=60` and `late=0`. Fewer than 60 `new`
 frames means the GPU is over budget: lower `render_scale` or `resolution_multiplier`.

-**Crashes.** `console.log` then names the faulting thread and gives its pc and a backtrace as
-`module+offset`. On the build machine,
-`addr2line -f -C -e ~/wiicompiled-frame/source/native-build/WiiCompiled 0x<offset>` turns an offset
-in `WiiCompiled` into a function: the executable is not stripped. (Built by hand, the executable is
-in `~/wiicompiled/Wiicompiled_VR_Frame/native-build/`.)
+**Crashes.** `console.log` names the crashed thread and gives a backtrace as `module+offset`. On the
+build machine, `addr2line -f -C -e ~/wiicompiled-frame/source/native-build/WiiCompiled 0x<offset>`
+turns an offset in `WiiCompiled` into a function name.

-**Building.** The install script's log is `~/wiicompiled-frame/build.log`; its end says why a build
-stopped. A build that freezes the machine has run out of memory: lower `--jobs` (or, by hand,
-`--parallel`). A missing CMake package means installing its `-dev` package in the container and
-running the same command again.
+**Builds.** The log is `build.log` in the work dir, and its end says why a build stopped. A build
+that freezes the machine has run out of memory: run it again with a lower `--jobs`.

-## Building by hand
+**In-game updates.** The Updates tab shows the step that failed. The full output is in the Frame's
+journal, `journalctl --user -u wiicompiled-update.service`, and the build's in `build.log` in the
+work dir.

-These are the steps the install script runs, for when you want to see or change each one. Set up
-emulation as in [Quick start](#quick-start) step 1 first.
+### Reporting problems

-### 1. Download the release and extract your disc
+Open an [issue](https://github.com/mitch030504/Wiicompiled_VR_Frame/issues) saying what you did and
+what you saw (which eye, where in the picture, racing or in menus). Attach the diagnostics archive,
+or at least the run's `console.log`; for a build problem, the end of `build.log`. Problems that also
+happen on a PC or a Quest belong upstream, in
+[WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR).

-Take the newest release from the [Releases](https://github.com/mitch030504/Wiicompiled_VR_Frame/releases)
-page; the commands use `frame-beta-1`, so put the newest release's tag in its place:
+## Other ways to build
+
+### On a server
+
+The script runs with Docker as well as podman, and much faster with more cores and memory. A
+machine that can't reach the Frame builds without `--frame`; give it more compiles at once if it has
+the memory, such as `--jobs 8` for 32 GB:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mitch030504/Wiicompiled_VR_Frame/openxr-work/Launcher/steam-frame-install.sh \
+    | bash -s -- --disc "/path/to/Mario Kart Wii.wbfs" --jobs 8
+```
+
+Run it in `tmux` or `screen` so a closed SSH session doesn't stop it. Then copy
+`~/wiicompiled-frame/out` and `~/wiicompiled-frame/disc` to the Frame as in
+[By hand, step 3](#3-install-on-the-frame).
+
+On some hosts, such as Unraid 7 with kernel 6.18, `binfmt_misc` registrations are per container:
+`tonistiigi/binfmt --install arm64` reports success, but Debian answers `exec format error`.
+Register qemu on the host instead, with the `P` flag the tonistiigi build of qemu expects (without
+it every program loses its first argument, and `uname -m` prints `Linux`):
+
+```bash
+docker create --name qemu-src tonistiigi/binfmt
+docker cp qemu-src:/usr/bin/qemu-aarch64 /usr/local/bin/qemu-aarch64
+docker rm qemu-src
+echo ':qemu-aarch64:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\xb7\x00:\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/usr/local/bin/qemu-aarch64:POCF' > /proc/sys/fs/binfmt_misc/register
+docker run --rm --platform linux/arm64 debian:trixie uname -m   # aarch64
+```
+
+Unraid keeps `/usr/local/bin` in memory, so repeat this after a reboot.
+
+### By hand
+
+These are the steps the install script runs, for when you want to see or change one. Set up the
+container as in [Quick start](#1-set-up-the-container-pc-only) first. The commands use
+`frame-beta-4`; put the newest release's tag in its place.
+
+#### 1. Download the release and extract your disc

 ```bash
 mkdir -p ~/wiicompiled/Wiicompiled_VR_Frame; cd ~/wiicompiled
-curl -fL https://github.com/mitch030504/Wiicompiled_VR_Frame/archive/refs/tags/frame-beta-1.tar.gz \
+curl -fL https://github.com/mitch030504/Wiicompiled_VR_Frame/archive/refs/tags/frame-beta-4.tar.gz \
    | tar -xz --strip-components=1 -C Wiicompiled_VR_Frame
 curl -fL -o nodtool https://github.com/encounter/nod/releases/download/v2.0.0-alpha.10/nodtool-linux-x86_64
 chmod +x nodtool
@@ -221,15 +325,16 @@ mkdir -p Wiicompiled_VR_Frame/Assets
 cp disc-extract/sys/main.dol disc-extract/files/rel/StaticR.rel Wiicompiled_VR_Frame/Assets/
 ```

-`disc-extract` must hold `sys/` and `files/` directly; keep it, the game reads it when it runs.
+`disc-extract` must hold `sys/` and `files/` directly. Keep it: the game reads it while it runs. On
+an ARM64 machine, download `nodtool-linux-aarch64` instead.

-### 2. Build, inside an ARM64 container
+#### 2. Build, inside an ARM64 container

 ```bash
 podman run -it --name wiicompiled-frame --platform linux/arm64 -v ~/wiicompiled:/work docker.io/library/debian:trixie bash
 ```

-Then, in the container's bash prompt:
+Then, at the container's prompt:

 ```bash
 apt-get update && apt-get install -y --no-install-recommends \
@@ -252,20 +357,21 @@ exit

 - Dawn is done when it prints `Patched Dawn for Linux ready`, the game when it prints
  `MKWCBUILD:OUTPUT=/work/out`.
- `--jobs 4` and `--parallel 4` suit 16 GB of memory. Compiles take more memory under emulation, and
-  16 at once froze a 16 GB laptop. Use 8 with 32 GB.
- If it stops, `podman start -ai wiicompiled-frame` gets you back in. Run `cd /work/Wiicompiled_VR_Frame;
-  T=/work/tools/toolchain-aarch64/bin`, then the step that stopped: both scripts resume.
+- `--jobs 4` and `--parallel 4` suit 16 GB of memory, since compiles take more memory under
+  emulation. Use 8 with 32 GB.
+- If it stops, `podman start -ai wiicompiled-frame` gets you back in. Run
+  `cd /work/Wiicompiled_VR_Frame; T=/work/tools/toolchain-aarch64/bin`, then the step that stopped:
+  both scripts resume.
+- On the Frame or another ARM64 machine, start the container without `--platform linux/arm64`.

-### 3. Install on the Frame
+#### 3. Install on the Frame

-The easiest way is [Frame Control](https://github.com/saphid/frame-control): set up its connection
-to the Frame, then drag `~/wiicompiled/out` onto **Send to Frame**. Name it `WiiCompiled` and keep
-**Launches** on `WiiCompiled`. It adds the game to your Steam library, in `~/devkit-game/WiiCompiled/`
-on the Frame.
+With [Frame Control](https://github.com/saphid/frame-control), drag `~/wiicompiled/out` onto
+**Send to Frame**, name it `WiiCompiled` and keep **Launches** on `WiiCompiled`. That adds it to
+your Steam library, in `~/devkit-game/WiiCompiled/` on the Frame.

-Then copy the disc over and, on a first install, tell the game where it is (Frame Control's SSH
-key answers to `frame`; use `steamos@<frame-ip>` otherwise):
+Then copy the disc over and tell the game where it is (Frame Control's SSH key answers to `frame`;
+use `steamos@<frame-ip>` otherwise):

 ```bash
 ssh frame mkdir -p wiicompiled
@@ -273,205 +379,132 @@ scp -r ~/wiicompiled/disc-extract frame:wiicompiled/disc
 ssh frame 'mkdir -p ~/.local/share/WiiCompiled && printf "[paths]\ndvd_root = \"/home/steamos/wiicompiled/disc\"\n" > ~/.local/share/WiiCompiled/Config.toml'
 ```

-Without Frame Control, `scp -r ~/wiicompiled/out frame:wiicompiled/` and start
-`~/wiicompiled/out/WiiCompiled` from a terminal in the Frame's Desktop Mode, with SteamVR running.
+The last line replaces `Config.toml`, so run it on a first install only. Without Frame Control,
+`scp -r ~/wiicompiled/out frame:wiicompiled/` and start `~/wiicompiled/out/WiiCompiled` from a
+terminal in the Frame's Desktop Mode, with SteamVR running.

-### Updating by hand
+#### Updating by hand

-When a new release comes out, put its changed files over the old source, rebuild, and replace only
-the executable. `rsync -c` copies just the files whose content changed and stamps them with the
-current time, so the build recompiles exactly those. Unpacking over the source would restore each
-file's commit date, which can be older than the last build, and changes would be skipped. Your
-`Assets/` and build folders stay. Install `rsync` if your system lacks it, and put the new release's
-tag in place of `frame-beta-2`:
+Copy the new release's changed files over the old source, rebuild, and replace only the executable.
+`rsync -c` copies just the files whose content changed and stamps them with the current time, so
+the build recompiles exactly those; unpacking straight over the source would keep each file's
+older commit date, and changes could be skipped. Your `Assets/` and build folders stay.

 ```bash
 cd ~/wiicompiled
 mkdir -p release-new
-curl -fL https://github.com/mitch030504/Wiicompiled_VR_Frame/archive/refs/tags/frame-beta-2.tar.gz \
+curl -fL https://github.com/mitch030504/Wiicompiled_VR_Frame/archive/refs/tags/frame-beta-4.tar.gz \
    | tar -xz --strip-components=1 -C release-new
 rsync -rcE release-new/ Wiicompiled_VR_Frame/
 rm -rf release-new
 podman start -ai wiicompiled-frame
 # in the container: cd /work/Wiicompiled_VR_Frame; T=/work/tools/toolchain-aarch64/bin, then the
-# build-dawn-linux.sh and local-build.sh lines from step 2, then exit. Dawn only rebuilds when the
-# release changed its patches (the release notes say so); otherwise both finish quickly.
+# build-dawn-linux.sh and local-build.sh lines from step 2, then exit. Dawn is only rebuilt when the
+# release changed its patches (the release notes say so).
 scp ~/wiicompiled/out/WiiCompiled frame:devkit-game/WiiCompiled/WiiCompiled.new
 ssh frame 'cd ~/devkit-game/WiiCompiled && chmod 755 WiiCompiled.new && mv -f WiiCompiled.new WiiCompiled'
 ```

-The executable is copied under a new name and moved into place, which works even while an old copy
-is open.
-
-## Other ways to build
-
-**On the Frame itself.** SteamOS's root file system is read-only, but it ships podman, and the
-install script runs there too. Over SSH (`ssh steamos@<frame-ip>`), or in a Desktop Mode terminal:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/mitch030504/Wiicompiled_VR_Frame/openxr-work/Launcher/steam-frame-install.sh \
-    | bash -s -- --disc "/path/to/Mario Kart Wii.wbfs" --frame local
-```
-
-It is native ARM64, so no emulation, but the Frame has less memory and cooling than a PC; keep it
-on its charger. The game then reads the disc straight from `~/wiicompiled-frame/disc`. By hand, the
-steps under [Building by hand](#building-by-hand) work the same in a container started without
-`--platform linux/arm64`, with `nodtool-linux-aarch64` in place of `nodtool-linux-x86_64`.
-
-**On a stronger machine** (a server, for example). The script works with Docker as well as podman,
-and runs much faster with more cores and memory. A machine that cannot reach the Frame builds
-without `--frame`; give it more compiles at once if it has the memory, `--jobs 8` for 32 GB:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/mitch030504/Wiicompiled_VR_Frame/openxr-work/Launcher/steam-frame-install.sh \
-    | bash -s -- --disc "/path/to/Mario Kart Wii.wbfs" --jobs 8
-```
-
-Run it in `tmux` or `screen` so a closed SSH session does not stop it. Copy `~/wiicompiled-frame/out`
-and `~/wiicompiled-frame/disc` back to the PC, send `out` to the Frame with Frame Control and copy
-the disc over as in [Install on the Frame](#3-install-on-the-frame).
-
-On some hosts, for example Unraid 7 with kernel 6.18, `binfmt_misc` registrations are per container.
-`tonistiigi/binfmt --install arm64` then reports success, but Debian answers `exec format error`.
-Register qemu on the host instead, with the `P` flag the tonistiigi build of qemu expects. Without it,
-every program loses its first argument, and `uname -m` prints `Linux`:
-
-```bash
-docker create --name qemu-src tonistiigi/binfmt
-docker cp qemu-src:/usr/bin/qemu-aarch64 /usr/local/bin/qemu-aarch64
-docker rm qemu-src
-echo ':qemu-aarch64:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\xb7\x00:\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/usr/local/bin/qemu-aarch64:POCF' > /proc/sys/fs/binfmt_misc/register
-docker run --rm --platform linux/arm64 debian:trixie uname -m   # aarch64
-```
-
-Unraid keeps `/usr/local/bin` in memory, so repeat this after a reboot.
+Copying under a new name and moving it into place works even while the game is open.

 ## How it works

- **Same-device rendering.** SteamVR's OpenXR runtime creates the Vulkan instance and device that
-  Dawn (Aurora's WebGPU layer) renders with, through Aurora's patches to Dawn
+- **One GPU device.** SteamVR's OpenXR runtime creates the Vulkan device that Dawn (the WebGPU
+  layer under Aurora, the game's renderer) draws with, through Aurora's patches to Dawn
  (`aurora-main/patches/dawn`). Each eye is copied into SteamVR's swapchain on Dawn's own queue, so
-  nothing is shared between GPU devices. This is the PC's Vulkan backend
-  (`runtime/src/vr/openxr_vulkan_win32.cpp`), compiled for Linux. Dawn links statically, so the
-  patched Dawn is built once (`Launcher/build-dawn-linux.sh`). Its `aurora-dawn.json` declares the
-  Vulkan hook and density map ABIs that Aurora compiles against.
- **Headset only.** The game neither shows nor finishes rendering a desktop window, and is compiled
-  for the Frame's Cortex-X4 cores (`-mcpu=cortex-x4`, overridable with `--cpu`).
- **Every refresh from the game.** The game draws 60 frames a second. When it handed SteamVR only
-  those, SteamVR ran it at half rate and made up every other refresh itself, even with Motion
-  Smoothing off. With `[vr] repeat_frames`, the pacing thread waits for the next frame until 1.5 ms
-  before SteamVR's next wake, then resubmits the last frame at the pose it was rendered for.
-  SteamVR turns that to the current head pose.
- **Eye-tracked foveation.** `XR_EXT_eye_gaze_interaction` gives the gaze, which
-  `runtime/include/vr/eye_gaze.h` turns into each eye's view. Aurora picks a fragment density map
-  centred on the gaze, snapped to cells of about 3 degrees (`aurora-main/lib/gfx/foveation.hpp`),
-  and keeps up to 128 per eye. Each map has a memory block of its own: Turnip reads a map through a
-  host mapping, and Dawn's buffer uploads unmap the shared blocks they sub-allocate from. That
-  crashed the game when a race restarted, until each map got its own block.
- **120 Hz.** `[vr] refresh_rate` (default 120 on the Frame, `0` keeps the headset's own) is asked of
-  SteamVR through `XR_FB_display_refresh_rate`. SteamVR only offers the rate set in its own settings.
+  nothing has to be shared between devices. This is the PC's Vulkan backend
+  (`runtime/src/vr/openxr_vulkan_win32.cpp`) compiled for Linux. Dawn is linked in statically,
+  which is why the patched Dawn is built once on your machine (`Launcher/build-dawn-linux.sh`).
+- **Headset only.** The game draws no desktop window, and is compiled for the Frame's Cortex-X4
+  cores (`-mcpu=cortex-x4`).
+- **Tuned for ARM64.** The Frame's kernel uses 4 KiB memory pages, so the Steam Frame build skips
+  the page-size check on every translated memory access; it checks once at startup and refuses to
+  start if the size is ever different. Audio mixing uses NEON.
+- **Every refresh from the game.** The game draws 60 frames a second. Given only those, SteamVR
+  ran it at half rate and filled every other refresh itself, even with Motion Smoothing off. With
+  `[vr] repeat_frames`, the pacing thread waits for the next frame until 1.5 ms before SteamVR's
+  next wake, then submits the last frame again with the head pose it was drawn for, and SteamVR
+  turns it to the current pose.
+- **Eye-tracked foveation.** `XR_EXT_eye_gaze_interaction` gives the gaze, and Aurora picks a
+  fragment density map centred on it, snapped to cells of about 3 degrees
+  (`aurora-main/lib/gfx/foveation.hpp`), keeping up to 128 per eye. Each map has its own memory
+  block, since sharing blocks crashed the game when a race restarted.
+- **120 Hz.** `[vr] refresh_rate` (120 on the Frame by default, `0` keeps the headset's own) is
+  requested through `XR_FB_display_refresh_rate`. SteamVR only offers the rate set in its own
+  settings.
+- **The Android version.** The Quest app has a `steamFrame` flavour
+  (`android/Build-Quest.ps1 -Headset frame`) for the Frame's Android layer, Lepton. It starts in VR
+  there but shows no picture: the Android backend passes each eye between two GPU devices, and
+  Lepton's graphics driver supports none of the ways to share images between them. The native build
+  uses one device, which is why it is the one to play. [`docs/quest-port.md`](docs/quest-port.md)
+  covers the Android build.

-### The Android flavour
+[`OPENXR.md`](OPENXR.md) documents every VR setting and the renderer in full.

-The Quest app also has a `steamFrame` flavour (`android/Build-Quest.ps1 -Headset frame`), for the
-Frame's Android layer, Lepton. It builds and starts in VR there, but cannot show a picture. The
-Android backend hands each eye from Dawn's device to its own OpenXR device through
-`VK_ANDROID_external_memory_android_hardware_buffer` and sync fds, and Lepton's Turnip has neither,
-nor `VK_KHR_external_memory_fd`. The native build needs no sharing, which is why it is the one to
-play. [`docs/quest-port.md`](docs/quest-port.md) covers the Android build.
+## What comes from where

-## Reporting problems
+This fork keeps everything [WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR) has:
+menus on a virtual screen and races in stereo, a first-person cockpit with a steering wheel you can
+grab and turn, the settings panel in the headset, and Retro Rewind as its own translated game. The
+physics are identical to the original game, proven by ghosts that sync across the Wii, Dolphin and
+WiiCompiled.

-Open an issue on this repository with:
- what you did and what you saw (which eye, where in the picture, racing or menus);
- the run's `console.log` (and `crash_sigsegv.txt` after a crash) from
-  `~/.local/share/WiiCompiled/Logs/` on the Frame;
- or, for a build problem, the last lines of the failing step.
+On top of that it adds the SteamOS build, the install, update and diagnostics scripts and the
+Frame-specific rendering, and it carries fixes taken from WiiCompiled itself and from other forks:
+Linux TLS for online play, faster disc reads, safer settings saves, NEON audio mixing and more.
+[`CREDITS.md`](CREDITS.md) lists each with its author.

-Problems that also happen on a PC or a Quest belong upstream, in
-[WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR).
-
-## From upstream
-
-The fork keeps everything [WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR) does;
-its README covers it in full. In the headset that means:
-
- Menus and unsupported scenes on a head-locked virtual screen, and races in immersive stereo.
- A first-person cockpit whose steering wheel or handlebar turns with your steering, and hand
-  steering by heurazy: grab the wheel with the tracked controllers and turn it.
- The settings panel in the headset (render scale, foveation, refresh rate, controls), saved to
-  `Config.toml` on the spot.
- Physics identical to the original game, proven by ghosts that sync across Wii, Dolphin and
-  WiiCompiled.
- [Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind) as its own statically translated
-  profile.
-
-The PC (Windows D3D12 and Vulkan) and Meta Quest builds are still here and unchanged; see
-[`OPENXR.md`](OPENXR.md) and [`docs/quest-port.md`](docs/quest-port.md). For those, use upstream's
-[WheelWizard VR](https://github.com/iChris4/WheelWizard_VR/releases/latest) instead of this fork.
-
-## A note on related projects
+The PC (Windows) and Meta Quest builds are still in the source and unchanged; see
+[`OPENXR.md`](OPENXR.md) and [`docs/quest-port.md`](docs/quest-port.md). To play on those, use
+upstream's [WheelWizard VR](https://github.com/iChris4/WheelWizard_VR/releases/latest) rather than
+this fork.

 WiiCompiled, WiiCompiled OpenXR VR, Wheel Wizard, Retro Rewind and this fork are developed
-**independently**, each with its **own** rules. What applies here does not automatically apply
-there, and vice versa. Check each project's own CONTRIBUTING and README files.
+independently, each with its own rules. Check each project's own README and CONTRIBUTING files.

 ## FAQ

 **Is this an emulator?**
-No. Everything is compiled to native ARM64 code before you press play. At runtime nothing emulates
-a Wii CPU or GPU.
+No. Everything is compiled to native ARM64 code before you press play. Nothing emulates a Wii
+processor or GPU while you play.

-**Do you provide the game, or a ready-built binary?**
-No. Nothing in this repo contains Nintendo code or assets, and the translated game is never
-shipped: it is built from your own disc, a one-time cost on your machine.
+**Can I download a ready-built game?**
+No. The game is built from your own disc, and anything built from it can't be shared. The build
+is a one-time cost on your machine, and updates only rebuild what changed.

-**Which game version works?**
-Clean PAL `RMCP01`. Other regions and modified executables are **rejected**.
+**Which version of the game works?**
+Clean PAL `RMCP01` only. Other regions and modified discs are rejected.

-**Why not install the Quest APK on the Frame?**
-The Frame runs it in Lepton, whose graphics driver cannot share images between the two GPU devices
-the Android backend uses, so it shows nothing. The native build uses one device and needs no
-sharing.
+**Why not install the Quest app on the Frame?**
+The Frame runs Android apps in Lepton, whose graphics driver can't pass images between the two GPU
+devices the Android version uses, so it shows nothing. The native build uses one device.

-**Can it run on other SteamOS or Linux ARM64 devices?**
-Leave out `--headset steam_frame` and pass `--cpu` for your CPU to get a generic Linux VR build;
-it needs an OpenXR runtime with `XR_KHR_vulkan_enable2`. Untested.
-
-## AI usage
-AI coding tools were used during development of this project. 
-All translated output is verified against real hardware behavior and most importantly, physics accuracy is proven synced across Wii, Dolphin, and WiiCompiled (see FAQ). 
+**Can it run on other Linux ARM64 devices?**
+Untested. Build by hand without `--headset steam_frame` and with `--cpu` for your processor to get a
+generic Linux VR build; it needs an OpenXR runtime with `XR_KHR_vulkan_enable2`. Unlike the Steam
+Frame build, it also works with memory pages larger than 4 KiB.

 ## Credits
- **inkwreck** - making the logo
- **[aurora](https://github.com/encounter/aurora)** - the GX rendering/windowing backend this
-  project's whole graphics layer sits on. MIT licensed.
- **[Dawn](https://dawn.googlesource.com/dawn)** - Google's WebGPU implementation, powering
-  aurora's Direct3D, Vulkan and OpenGL backends.
- **[OpenXR](https://www.khronos.org/openxr/)** - the Khronos cross-platform API used by the
-  experimental VR renderer.
- **[WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR)** by iChris4 and
-  **[WiiCompiled](https://github.com/patchzyy/Wiicompiled)** by patchzyy - the projects this fork
-  is built on.
- **heurazy** - the VR cockpit's turning steering wheel and hand steering, ported from
-  **[mario-kart-wii-VR-port](https://github.com/heurazy/mario-kart-wii-VR-port)** (GPL-3.0).
- **[Dolphin Emulator](https://github.com/dolphin-emu/dolphin)** - an invaluable reference for Wii
-  hardware behavior during development, plus the source of the free DSP coefficient ROM and the
-  unmodified default WiiConnect24 bootstrap tree bundled with the runtime.
- **[Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind)** by ZPL and team - the mod
-  distribution this project supports.
- **[Wheel Wizard](https://github.com/TeamWheelWizard/WheelWizard)** - the mod manager this
-  project integrates with as a launch backend.
- **[nod](https://github.com/encounter/nod)** - nodtool, the disc image extractor.
- **[DolphinXR](https://github.com/iChris4/dolphinXR)** - the Steam Frame controller profile's
-  input paths.
- **[Frame Control](https://github.com/saphid/frame-control)** by saphid - installing the game into
-  the Frame's Steam library, and its notes on how the Frame's software fits together.
- Everyone in the static recompilation community.

-Bundled third-party components and their licenses live in
+This fork stands on other people's work: WiiCompiled by patchzyy, WiiCompiled OpenXR VR by iChris4,
+the steering wheel and hand steering by heurazy, and fixes from heurazy's Wiicompiled_VR-PLUS,
+Chris Sotraidis's KartPad, DarthMDev, BlackAndBlue95's Strikers-WiiCompiled, rooklz and nx-mod's
+wiicompiled-nx. [`CREDITS.md`](CREDITS.md) says what came from whom, along with the tools and
+references used: [aurora](https://github.com/encounter/aurora),
+[Dawn](https://dawn.googlesource.com/dawn), [OpenXR](https://www.khronos.org/openxr/),
+[Dolphin](https://github.com/dolphin-emu/dolphin), [DolphinXR](https://github.com/iChris4/dolphinXR),
+[nod](https://github.com/encounter/nod), [Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind),
+[Wheel Wizard](https://github.com/TeamWheelWizard/WheelWizard) and
+[Frame Control](https://github.com/saphid/frame-control). The logo is by Inkwreck.
+
+Bundled third-party components and their licenses are in
 [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).

+## AI usage
+
+AI coding tools were used to develop WiiCompiled and this fork. Translated output is checked
+against real hardware behaviour, and physics accuracy is proven by ghosts that sync across the Wii,
+Dolphin and WiiCompiled.

 ## License

@@ -88,6 +88,19 @@ wheel geometry and guest reads in `runtime/src/vr/mkw_vr_first_person.cpp` and
 (`runtime/include/physical_wheel.h`, `runtime/src/physical_wheel.cpp` and their test). The files
 carry that attribution in their headers.

+### Mozilla CA certificate bundle - MPL-2.0
+
+The root certificates Mbed TLS verifies servers against on Linux, macOS and Android
+(`runtime/assets/certs/cacert.pem`), copied next to the built game. Extracted from Mozilla's
+`certdata.txt` and redistributed unmodified as curl's CA bundle.
+Source: <https://curl.se/docs/caextract.html>
+
+### Code ported from other WiiCompiled forks - GPL-3.0-or-later
+
+Fixes taken from other GPL-3.0 forks of WiiCompiled (heurazy's Wiicompiled_VR-PLUS, KartPad,
+DarthMDev, Strikers-WiiCompiled, rooklz and wiicompiled-nx) are listed with their authors and
+source commits in [`CREDITS.md`](CREDITS.md).
+
 ### pugixml - MIT

 Copyright (c) 2006-2025 Arseny Kapoulkine.
@@ -2,7 +2,7 @@

 Standalone Android/OpenXR build of the Mario Kart Wii recompilation for Quest 1,
 Quest 2, Quest 3, Quest 3S and Quest Pro, and, as the `steamFrame` flavour, for Valve's Steam
-Frame under Lepton (the [README](../README.md#the-android-flavour); the Frame is played with the native SteamOS build). The full design, build
+Frame under Lepton (the [README](../README.md#how-it-works); the Frame is played with the native SteamOS build). The full design, build
 walkthrough and current status live in [docs/quest-port.md](../docs/quest-port.md); this directory only
 holds the Gradle project, its helper scripts, the game kit tooling
 (`QuestGameKit.psm1`, `Build-QuestGame.ps1`), the on-headset build toolchain
@@ -46,6 +46,13 @@ object GameLibrary {
    }

    fun status(context: Context, profile: GameProfile = GameProfile.selected(context)): Status {
+        // A killed publication must be recovered by setup before either process loads the game.
+        val games = File(context.filesDir, "game")
+        if (File(games, ".import-transaction").exists() ||
+            File(games, ".${profile.id}.replacement").exists() ||
+            File(GameStorage.gameRoot(context), ".${GameStorage.DISC_DIRECTORY}.replacement").exists() ||
+            profile.modPack && File(GameStorage.gameRoot(context), ".${GameStorage.MOD_DIRECTORY}.replacement").exists()
+        ) return Status.Missing
        val manifest = manifest(context, profile)
        if (manifest == null || !library(context, profile).isFile) {
            return Status.Missing
@@ -0,0 +1,88 @@
+package org.wiicompiled.quest.launcher
+
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import java.util.Properties
+
+/** A persisted commit decision keeps all old folders until every new folder is installed. */
+object DirectoryReplacement {
+    private fun backup(destination: File) = File(destination.parentFile, "${destination.name}.replaced")
+
+    fun recover(journal: File) {
+        if (!journal.exists()) return
+        val state = Properties().apply { journal.inputStream().use { load(it) } }
+        val committed = state.getProperty("committed") == "true"
+        val count = state.getProperty("count").toInt()
+        for (i in count - 1 downTo 0) {
+            val destination = File(state.getProperty("destination.$i"))
+            val staging = File(state.getProperty("staging.$i"))
+            val old = backup(destination)
+            if (committed) {
+                if (old.exists() && !old.deleteRecursively()) throw IOException("Cannot remove $old")
+            } else if (old.exists()) {
+                if (destination.exists() && !destination.deleteRecursively()) throw IOException("Cannot remove $destination during rollback")
+                if (!old.renameTo(destination)) throw IOException("Cannot restore $destination; recovery copy remains at $old")
+            } else if (state.getProperty("existed.$i") == "false" && !staging.exists()) {
+                if (destination.exists() && !destination.deleteRecursively()) throw IOException("Cannot roll back $destination")
+            }
+        }
+        if (!journal.delete()) throw IOException("Cannot remove transaction journal $journal")
+    }
+
+    fun replaceAll(replacements: List<Pair<File, File>>, journal: File): String? {
+        try {
+            recover(journal)
+            val state = Properties()
+            state.setProperty("count", replacements.size.toString())
+            replacements.forEachIndexed { i, (destination, staging) ->
+                val singleJournal = File(destination.parentFile, ".${destination.name}.replacement")
+                if (singleJournal != journal) recover(singleJournal)
+                val old = backup(destination)
+                // Recover installs made before transaction journals existed.
+                if (!destination.exists() && old.exists() && !old.renameTo(destination)) throw IOException("Cannot restore $destination from $old")
+                if (old.exists() && !old.deleteRecursively()) throw IOException("Cannot remove $old")
+                if (!staging.isDirectory) throw IOException("Missing staged folder $staging")
+                state.setProperty("destination.$i", destination.absolutePath)
+                state.setProperty("staging.$i", staging.absolutePath)
+                state.setProperty("existed.$i", destination.exists().toString())
+            }
+            writeJournal(journal, state)
+            try {
+                for ((destination, staging) in replacements) {
+                    val old = backup(destination)
+                    if (destination.exists() && !destination.renameTo(old)) throw IOException("Cannot replace $destination")
+                    if (!staging.renameTo(destination)) throw IOException("Cannot install $destination")
+                }
+                state.setProperty("committed", "true")
+                writeJournal(journal, state)
+            } catch (failure: Exception) {
+                try {
+                    recover(journal)
+                } catch (rollback: Exception) {
+                    throw IOException("${failure.message}; rollback failed: ${rollback.message}. Keep $journal and the .replaced folders for recovery.", failure)
+                }
+                throw failure
+            }
+            // A committed journal makes cleanup retryable without undoing a successful install.
+            try {
+                recover(journal)
+            } catch (cleanup: Exception) {
+                return "The new files are installed, but cleanup must be retried: ${cleanup.message}"
+            }
+            return null
+        } catch (failure: Exception) {
+            return failure.message ?: "Could not replace the installed folders."
+        }
+    }
+
+    private fun writeJournal(journal: File, state: Properties) {
+        journal.parentFile?.mkdirs()
+        val temporary = File(journal.parentFile, "${journal.name}.tmp")
+        FileOutputStream(temporary).use { output ->
+            state.store(output, null)
+            output.fd.sync()
+        }
+        if (!temporary.renameTo(journal)) throw IOException("Cannot write transaction journal $journal")
+    }
+}
@@ -1,14 +1,13 @@
 package org.wiicompiled.quest.launcher

-import android.util.Log
+import android.content.Context
 import java.io.File
+import org.wiicompiled.quest.GameStorage
 import org.wiicompiled.quest.BuildConfig

 /** Checks and swaps shared by every [GameSetup] task. */
 object GameFiles {

-    private const val TAG = "WiiCompiledLauncher"
-
    val checks = DiscChecks(BuildConfig.DISC_GAME_ID, BuildConfig.DISC_DOL_SHA256, BuildConfig.DISC_REL_SHA256)

    /**
@@ -28,22 +27,17 @@ object GameFiles {
     * Moves [staging] to [destination], keeping the old destination until the new one is in
     * place. Null on success, otherwise the message to show.
     */
-    fun replace(destination: File, staging: File): String? {
-        val replaced = File(destination.parentFile, "${destination.name}.replaced")
-        replaced.deleteRecursively()
-        if (destination.exists() && !destination.renameTo(replaced)) {
-            return "The existing ${destination.name} folder could not be replaced. Remove it, for example with " +
-                "adb shell rm -r ${destination.absolutePath}, and try again."
+    fun replace(destination: File, staging: File): String? = DirectoryReplacement.replaceAll(
+        listOf(destination to staging), File(destination.parentFile, ".${destination.name}.replacement"),
+    )
+
+    fun recover(context: Context) {
+        val games = File(context.filesDir, "game")
+        DirectoryReplacement.recover(File(games, ".import-transaction"))
+        for (parent in listOf(games, GameStorage.gameRoot(context))) {
+            parent.listFiles { file -> file.name.startsWith(".") && file.name.endsWith(".replacement") }
+                ?.forEach { DirectoryReplacement.recover(it) }
        }
-        if (!staging.renameTo(destination)) {
-            replaced.renameTo(destination)
-            return "The new files could not be moved into ${destination.absolutePath}."
-        }
-        // The new copy is in place; an old one that will not delete only costs space.
-        if (replaced.exists() && !replaced.deleteRecursively()) {
-            Log.w(TAG, "Could not remove ${replaced.absolutePath}")
-        }
-        return null
    }

    fun gigabytes(bytes: Long) = "%.1f GB".format(bytes / 1_000_000_000.0)
@@ -50,6 +50,12 @@ object GamePackageImport {
        val libraryStaging = File(context.filesDir, "game/.importing")
        val dataStaging = File(gameRoot, "DATA.importing")
        val modStaging = File(gameRoot, "${GameStorage.MOD_DIRECTORY}.importing")
+        val journal = File(libraryStaging.parentFile, ".import-transaction")
+        try {
+            DirectoryReplacement.recover(journal)
+        } catch (failure: Exception) {
+            return "Cannot recover the previous import: ${failure.message}"
+        }
        for (staging in listOf(libraryStaging, dataStaging, modStaging)) staging.deleteRecursively()
        try {
            libraryStaging.mkdirs()
@@ -127,20 +133,21 @@ object GamePackageImport {
            }

            File(libraryStaging, GameLibrary.MANIFEST_NAME).writeText(manifestText!!)
-            if (hasData) {
-                GameFiles.replace(GameStorage.discDirectory(context), dataStaging)?.let { return it }
-            }
-            if (hasMod) {
-                GameFiles.replace(GameStorage.modDirectory(context), modStaging)?.let { return it }
-            }
            val libraryDir = GameLibrary.directory(context, profile)
            libraryDir.parentFile?.mkdirs()
-            GameFiles.replace(libraryDir, libraryStaging)?.let { return it }
+            val replacements = buildList {
+                if (hasData) add(GameStorage.discDirectory(context) to dataStaging)
+                if (hasMod) add(GameStorage.modDirectory(context) to modStaging)
+                add(libraryDir to libraryStaging)
+            }
+            DirectoryReplacement.replaceAll(replacements, journal)?.let { return it }
            Log.i(TAG, "Imported ${profile.id} built by ${manifestJson.optString("builtBy")} at ${manifestJson.optString("builtAt")}")
            GameProfile.select(context, profile)
            return null
        } finally {
-            for (staging in listOf(libraryStaging, dataStaging, modStaging)) staging.deleteRecursively()
+            if (!journal.exists()) {
+                for (staging in listOf(libraryStaging, dataStaging, modStaging)) staging.deleteRecursively()
+            }
        }
    }

@@ -107,6 +107,7 @@ object GameSetup {
        }
        val finishing = { publish(State.Finishing(task)) }
        try {
+            GameFiles.recover(context)
            val failure = if (task == Task.BuildGame) {
                val reporter = GameBuild.Reporter { permille, step, done, total ->
                    publish(State.Working(task, permille.toLong(), 1000, step, done, total))
@@ -0,0 +1,128 @@
+package org.wiicompiled.quest.launcher
+
+import java.io.File
+import java.nio.file.Files
+import java.util.Properties
+import org.junit.Assert.*
+import org.junit.Test
+
+class DirectoryReplacementTest {
+    private fun tree(parent: File, name: String, contents: String): File = File(parent, name).apply {
+        mkdirs()
+        File(this, "contents").writeText(contents)
+    }
+
+    private fun interrupted(journal: File, pairs: List<Pair<File, File>>, existed: List<Boolean>, committed: Boolean = false) {
+        val state = Properties().apply {
+            setProperty("count", pairs.size.toString())
+            setProperty("committed", committed.toString())
+            pairs.forEachIndexed { i, (destination, staging) ->
+                setProperty("destination.$i", destination.absolutePath)
+                setProperty("staging.$i", staging.absolutePath)
+                setProperty("existed.$i", existed[i].toString())
+            }
+        }
+        journal.outputStream().use { state.store(it, null) }
+    }
+
+    @Test fun restoresLegacyBackupBeforeAnotherAttempt() {
+        val root = Files.createTempDirectory("replacement").toFile()
+        try {
+            val destination = File(root, "DATA")
+            tree(root, "DATA.replaced", "old")
+            val result = DirectoryReplacement.replaceAll(listOf(destination to File(root, "missing")), File(root, "journal"))
+            assertNotNull(result)
+            assertEquals("old", File(destination, "contents").readText())
+        } finally { root.deleteRecursively() }
+    }
+
+    @Test fun rollsBackEveryFolderWhenALaterMoveFails() {
+        val root = Files.createTempDirectory("replacement").toFile()
+        try {
+            val data = tree(root, "DATA", "old data")
+            val pack = tree(root, "pack", "old pack")
+            val stagedData = tree(root, "new-data", "new data")
+            // The nested staging folder is moved away with pack, forcing the second install to fail.
+            val stagedPack = tree(pack, "new-pack", "new pack")
+            val journal = File(root, "journal")
+            assertNotNull(DirectoryReplacement.replaceAll(listOf(data to stagedData, pack to stagedPack), journal))
+            assertEquals("old data", File(data, "contents").readText())
+            assertEquals("old pack", File(pack, "contents").readText())
+            assertFalse(journal.exists())
+        } finally { root.deleteRecursively() }
+    }
+
+    @Test fun interruptedImportRestoresAllOldFolders() {
+        val root = Files.createTempDirectory("replacement").toFile()
+        try {
+            val data = tree(root, "DATA", "new data")
+            tree(root, "DATA.replaced", "old data")
+            val pack = File(root, "pack")
+            tree(root, "pack.replaced", "old pack")
+            val stagedPack = tree(root, "new-pack", "new pack")
+            val journal = File(root, "journal")
+            interrupted(journal, listOf(data to File(root, "new-data"), pack to stagedPack), listOf(true, true))
+            DirectoryReplacement.recover(journal)
+            assertEquals("old data", File(data, "contents").readText())
+            assertEquals("old pack", File(pack, "contents").readText())
+            assertTrue(stagedPack.exists())
+            assertFalse(journal.exists())
+        } finally { root.deleteRecursively() }
+    }
+
+    @Test fun interruptedFirstInstallRemovesOnlyPublishedFolders() {
+        val root = Files.createTempDirectory("replacement").toFile()
+        try {
+            val data = tree(root, "DATA", "new data")
+            val journal = File(root, "journal")
+            interrupted(journal, listOf(data to File(root, "new-data")), listOf(false))
+            DirectoryReplacement.recover(journal)
+            assertFalse(data.exists())
+        } finally { root.deleteRecursively() }
+    }
+
+    @Test fun committedImportKeepsNewFoldersAndFinishesCleanup() {
+        val root = Files.createTempDirectory("replacement").toFile()
+        try {
+            val data = tree(root, "DATA", "new data")
+            val old = tree(root, "DATA.replaced", "old data")
+            val journal = File(root, "journal")
+            interrupted(journal, listOf(data to File(root, "new-data")), listOf(true), committed = true)
+            DirectoryReplacement.recover(journal)
+            assertEquals("new data", File(data, "contents").readText())
+            assertFalse(old.exists())
+            assertFalse(journal.exists())
+        } finally { root.deleteRecursively() }
+    }
+
+    @Test fun importRecoversAnEarlierSingleFolderTransaction() {
+        val root = Files.createTempDirectory("replacement").toFile()
+        try {
+            val data = tree(root, "DATA", "unfinished new data")
+            tree(root, "DATA.replaced", "old data")
+            val single = File(root, ".DATA.replacement")
+            interrupted(single, listOf(data to File(root, "previous-stage")), listOf(true))
+            val journal = File(root, "import-journal")
+            assertNotNull(DirectoryReplacement.replaceAll(listOf(data to File(root, "missing")), journal))
+            assertEquals("old data", File(data, "contents").readText())
+            assertFalse(single.exists())
+            assertFalse(journal.exists())
+        } finally { root.deleteRecursively() }
+    }
+
+    @Test fun successfulImportPublishesEverything() {
+        val root = Files.createTempDirectory("replacement").toFile()
+        try {
+            val data = tree(root, "DATA", "old data")
+            val library = tree(root, "library", "old library")
+            val stagedData = tree(root, "new-data", "new data")
+            val stagedLibrary = tree(root, "new-library", "new library")
+            val journal = File(root, "journal")
+            assertNull(DirectoryReplacement.replaceAll(listOf(data to stagedData, library to stagedLibrary), journal))
+            assertEquals("new data", File(data, "contents").readText())
+            assertEquals("new library", File(library, "contents").readText())
+            assertFalse(journal.exists())
+            assertFalse(File(root, "DATA.replaced").exists())
+        } finally { root.deleteRecursively() }
+    }
+}
@@ -823,7 +823,7 @@ Android facts this design rests on, all measured on a Quest 3:
  application ID and storage, but select the appropriate CPU baseline (one
  `headsetCpus` map in `app/build.gradle.kts`), manifest and launcher
  behavior. `steamFrame` is Valve's Steam Frame under Lepton, SteamOS's
-  Android layer, where it cannot show a picture; see the README, The Android flavour.
+  Android layer, where it cannot show a picture; see the README, How it works.
  `app/src/main/cpp/CMakeLists.txt` adds the repository's `runtime/` as a
  subdirectory with those Android choices and builds both game kit probes
  (the Retro Rewind one only when the translation includes the mod), which
@@ -852,7 +852,7 @@ powershell -ExecutionPolicy Bypass -File android/Build-Quest.ps1 -Headset quest1
 powershell -ExecutionPolicy Bypass -File android/Build-QuestGame.ps1 -Install         # your game, against that kit, into Import (or WheelWizard VR's Build for Quest)
 powershell -ExecutionPolicy Bypass -File android/Build-QuestGame.ps1 -Product retro_rewind -Mod <RetroRewind6> -Install  # the mod and its pack (needs translate-mod output with --retro-wfc-payload)
 powershell -ExecutionPolicy Bypass -File android/Build-QuestGame.ps1 -Headset quest1 -Install  # game package from the Quest 1 kit
-powershell -ExecutionPolicy Bypass -File android/Build-Quest.ps1 -Headset frame       # Steam Frame flavour (README, The Android flavour)
+powershell -ExecutionPolicy Bypass -File android/Build-Quest.ps1 -Headset frame       # Steam Frame flavour (README, How it works)
 adb push MarioKart.iso /sdcard/Download/                                               # then Select disc image in the launcher
 ```

@@ -0,0 +1,81 @@
+The third beta of WiiCompiled VR for the Steam Frame: Mario Kart Wii, statically recompiled to
+native ARM64 code, running in VR on SteamOS through SteamVR. This one brings in fixes from upstream
+WiiCompiled and from other WiiCompiled forks, Retro Rewind in the installer, and a diagnostics
+script. Thanks to everyone whose work is in it; [`CREDITS.md`](https://github.com/mitch030504/Wiicompiled_VR_Frame/blob/openxr-work/CREDITS.md) lists who wrote
+what.
+
+**This release is source only.** The game is always built from your own clean PAL `RMCP01` disc,
+and nothing built from it may be distributed, so there is no ready-built game here.
+
+## New
+
+- **Retro Rewind in the installer.** `steam-frame-install.sh --retro-rewind` downloads the Retro
+  Rewind pack from its own update server, builds Retro Rewind beside the base game and adds it to
+  your Steam library. `--retro-rewind-pack DIR` uses a pack you already have. Online play works on
+  Linux now that TLS does (below). From heurazy's Wiicompiled_VR-PLUS.
+- **Adaptive resolution** (`[vr] adaptive_resolution`, off by default): lowers the race's eye
+  resolution down to 70% while frames fall behind, and raises it again once they keep up.
+  Experimental and not yet tried in a race on the Frame. From Wiicompiled_VR-PLUS.
+- **Updating, from the PC or from inside the game.** `steam-frame-install.sh --update` reuses the
+  options the install was made with and builds nothing when the Frame already has the newest
+  release (and Retro Rewind pack); `--check` only reports. An install built on the Frame itself
+  (`--frame local`) gets an **Updates** tab in the settings panel: it checks for a new release and
+  builds it in the background while the game stays open, showing each step and how far the build
+  is. Close the game meanwhile and the update reopens it when done. Steam notifications were tried
+  for this and do not show on the Frame.
+- **`Launcher/frame-diagnostics.sh`** gathers the logs, crash files, settings, SteamVR logs and
+  system state from the Frame into one archive, with a summary of how far startup got. Attach it
+  to bug reports.
+
+## Fixed
+
+- A crash while a scene loads (`GXClearVtxDesc`). From Wiicompiled_VR-PLUS.
+- TLS on Linux, through Mbed TLS, so online services can connect at all (upstream #144), and a
+  timed-out TLS write no longer frees a session the game still holds (DarthMDev).
+- Saves on a different drive or the SD card can be moved (upstream #212); the game keeps its local
+  Wii identity services while offline, and emptied WiiConnect24 files are refilled, so it no longer
+  reports a save error for them (upstream #244, nx-mod).
+- `Config.toml` is saved through a temporary file, so a crash mid-save can't empty it
+  (BlackAndBlue95).
+- Renderer fixes from upstream's KartPad batch (#244): draws no longer read past their own vertices,
+  three-byte vertex attributes, GEN_MODE, EFB copies and readback, pipeline cache rows and pipeline
+  compile wake-ups. Waiting on the GPU now sleeps instead of holding a CPU core busy.
+- Effects no longer vanish while the world is darkened, such as Stormship's lightning
+  (BlackAndBlue95).
+- Controller player indices and socket errors (upstream #251), and a `bltl` translation (#254).
+
+## Faster
+
+- Disc reads and SZS decompression take bulk copies and keep file handles open per thread
+  (KartPad).
+- Audio mixing uses NEON (rooklz).
+- Translated memory accesses no longer check the page size each time, since the Frame uses 4 KiB
+  pages; the game checks once at startup (from nx-mod's finding).
+
+## Updating from frame-beta-2
+
+Run the install command again; you can leave out `--disc`. Dawn's patches did not change, so it is
+not rebuilt. Most of the game is, since the translator changed as well as the runtime and renderer,
+so expect a longer update than usual. The build now also downloads Mbed TLS. Add `--retro-rewind` to get Retro Rewind too.
+
+frame-beta-2's script has no `--update`, so this one update is the full install command; it saves
+its options, and from then on `steam-frame-install.sh --update` is enough. To update from inside
+the game later, make this install on the Frame itself with `--frame local`.
+
+## Known issues
+
+Unchanged from frame-beta-2:
+
+- Images double in races and on the HUD, sometimes in the right eye only. Foveation is the main
+  suspect; try foveation Off if it bothers you, and report the result.
+- Foveation follows the right eye less well than the left.
+- VR frame interpolation is not recommended on the Frame.
+- The Android (`steamFrame`) flavour cannot show a picture in Lepton; use the native build.
+
+## Recommended settings
+
+`render_scale = 1.25`, `foveation = "medium"`, `repeat_frames = true`, `frame_interpolation_fps = 0`
+under `[vr]`, and `resolution_multiplier = 2` under `[video]`. SteamVR at 120 Hz.
+
+Reports with the run log from `~/.local/share/WiiCompiled/Logs/`, or the archive
+`frame-diagnostics.sh` makes, are welcome as issues.
@@ -0,0 +1,59 @@
+The fourth beta of WiiCompiled VR for the Steam Frame focuses on safer installs and updates.
+It preserves working disc data when extraction fails, fixes moving an installation to a different
+path, and makes release updates remove obsolete source files without deleting disc data or build
+caches.
+
+**This release is source only.** Build the game from your own clean PAL `RMCP01` disc. No compiled
+game or disc assets are included.
+
+## Fixed
+
+- Linux setup extracts and validates disc data in staging before replacing the working copy.
+  Failed validation or cancellation leaves the previous disc data intact, and cancellation stops
+  the extraction process before its scratch directory is removed.
+- Frame installations keep remote paths with spaces and shell characters as single arguments.
+- Changing the disc or Retro Rewind location updates the corresponding `Config.toml` setting
+  while preserving other settings.
+- Release updates remove files owned by the previous release that no longer exist in the new
+  one. Disc assets, generated output and build caches remain in place.
+- A work-directory lock prevents overlapping manual installs and in-game updates.
+- Linux and Frame Retro Rewind builds verify the Retro-WFC payload signature before translation.
+  Android already performed this verification.
+- Android folder replacements keep recovery copies until the full import commits. Interrupted
+  imports can roll back disc data, the mod pack and the compiled library together. Play is blocked
+  while a replacement journal is pending, and setup recovers it before another task starts.
+
+## Updating from frame-beta-3
+
+Fetch the new installer so this update uses the fixes:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mitch030504/Wiicompiled_VR_Frame/openxr-work/Launcher/steam-frame-install.sh \
+    | bash -s -- --update
+```
+
+Add `--work-dir DIR` if the original install used a different work directory. The installer now
+requires Python 3 and `flock` from util-linux on the build machine. Both are normally available on
+the Frame.
+
+The first update of an older installation downloads its previous release's archive once to recover
+which source files it owned. This extra download prevents cleanup from deleting user data or build
+caches. Later updates reuse the saved file list.
+
+## Validation
+
+- 664 .NET tests passed locally using .NET 10 major-version roll-forward; CI uses .NET 8.
+- Seven Android directory-transaction tests and six Frame installer regression checks passed.
+- Linux setup built successfully, and installer shell syntax checks passed.
+- New Linux CI checks cover extraction failure, cancellation, recovery and Frame file operations.
+
+A full APK build and real-headset installation were not tested for this release.
+
+## Known issues
+
+The VR rendering issues from frame-beta-3 remain: doubled images in races and on the HUD, weaker
+right-eye foveation tracking, and unrecommended frame interpolation. The Android Steam Frame flavour
+still does not show a picture in Lepton; use the native build.
+
+Recommended settings remain `render_scale = 1.25`, `foveation = "medium"`, `repeat_frames = true`,
+`frame_interpolation_fps = 0`, and `resolution_multiplier = 2`, with SteamVR at 120 Hz.
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#pragma once
+
+#include <string>
+
+// Settings > Updates: whether a newer release of the game exists, and, on a Frame that holds its own
+// build, updating to it without leaving the headset.
+//
+// Both answers come from Launcher/steam-frame-install.sh, which already knows how to compare
+// versions and how to build: `--check` reports, `--update` installs. The update reports its progress
+// through a status file rather than Steam notifications, which the Frame's Steam does not show.
+// The install writes update.conf beside the player's configuration when it put a build on this
+// machine, so the Update button appears only where it can actually work; installed from a PC, the
+// tab says to update there.
+namespace update_check {
+
+enum class State {
+    // This install cannot update itself: it was built on a PC, which is where updates are run.
+    PcInstall,
+    // It can, and nothing has been asked of it yet this session.
+    Idle,
+    Checking,
+    UpToDate,
+    Available,
+    // An update is running beside the game, as a service of its own: it carries on if the game is
+    // closed, and then opens it again when it is done.
+    Updating,
+    Failed,
+};
+
+struct Status {
+    State state = State::PcInstall;
+    // The release this build came from, or empty when it was built from a source tree.
+    std::string installedRelease;
+    // One line under the state: which release is available, what failed, or what step is running.
+    std::string detail;
+    // An update has installed a different build since this one started: it takes effect when the
+    // game is started again.
+    bool restartNeeded = false;
+};
+
+// What the Updates tab draws. Cheap enough to call every frame: a check or update in flight is
+// answered from memory, and otherwise the files behind it are re-read at most once a second.
+Status Current();
+
+// Whether there is an Updates tab to show at all: this install can update itself, or it at least
+// knows which release it is running. Neither is true of a build that came from somewhere else.
+inline bool Relevant(const Status& status) {
+    return status.state != State::PcInstall || !status.installedRelease.empty();
+}
+
+// Asks the install script whether a newer release exists, in the background. Returns at once.
+void StartCheck();
+
+// Starts the update in the background: its own systemd user service runs the install script, which
+// reports each step to the file Current() reads, so the game can stay open and show the progress.
+// On false, `error` says why, for display.
+bool StartUpdate(std::string& error);
+
+} // namespace update_check
@@ -11,6 +11,7 @@
 #include "music_attenuation.h"
 #include "runtime_config.h"
 #include "runtime_log.h"
+#include "update_check.h"
 #include "vr/camera_toggle.h"
 #include "vr/mkw_vr_culling.h"
 #include "vr/mkw_vr_first_person.h"
@@ -2094,6 +2095,107 @@ void DrawDiagnosticsSettings() {
    }
 }

+bool g_updatePromptOpen = false;
+std::string g_updateError;
+
+void DrawUpdatePrompt() {
+    constexpr const char* kTitle = "Update";
+    if (g_updatePromptOpen && !ImGui::IsPopupOpen(kTitle)) ImGui::OpenPopup(kTitle);
+    if (!ImGui::BeginPopupModal(kTitle, &g_updatePromptOpen, ImGuiWindowFlags_AlwaysAutoResize)) return;
+    ImGui::PushTextWrapPos(ImGui::GetCursorPosX() + Scaled(380.0f));
+    ImGui::TextUnformatted("The update is built here on the Frame, in the background, which takes a "
+                           "while: keep the Frame on its charger. You can keep playing meanwhile, "
+                           "though the game may stutter while it compiles. Close the game whenever "
+                           "you like: the update carries on and opens it again when it is done.");
+    ImGui::PopTextWrapPos();
+    if (ImGui::Button("Start the update", ImVec2(Scaled(180.0f), 0.0f))) {
+        update_check::StartUpdate(g_updateError);
+        g_updatePromptOpen = false;
+    }
+    ImGui::SameLine();
+    if (ImGui::Button("Cancel", ImVec2(Scaled(120.0f), 0.0f))) g_updatePromptOpen = false;
+    if (!g_updatePromptOpen) ImGui::CloseCurrentPopup();
+    ImGui::EndPopup();
+}
+
+void DrawUpdateSettings() {
+    const update_check::Status status = update_check::Current();
+    ImGui::PushTextWrapPos(ImGui::GetCursorPosX() + Scaled(380.0f));
+    if (status.installedRelease.empty()) {
+        ImGui::TextUnformatted("This build came from a source tree rather than a release.");
+    } else {
+        ImGui::Text("Release %s", status.installedRelease.c_str());
+    }
+
+    const bool busy = status.state == update_check::State::Checking ||
+                      status.state == update_check::State::Updating;
+    switch (status.state) {
+    case update_check::State::PcInstall:
+        ImGui::TextDisabled("The PC that built this installs its updates. Run the installer there "
+                            "again with --update.");
+        break;
+    case update_check::State::Idle:
+        break;
+    case update_check::State::Checking:
+        ImGui::TextDisabled("Looking for a newer release...");
+        break;
+    case update_check::State::UpToDate:
+        ImGui::TextDisabled("%s", status.detail.c_str());
+        break;
+    case update_check::State::Available:
+        ImGui::TextUnformatted(status.detail.c_str());
+        break;
+    case update_check::State::Updating:
+        ImGui::Text("Updating: %s", status.detail.c_str());
+        ImGui::TextDisabled("Keep playing, or close the game: the update carries on and opens it "
+                            "again when it is done.");
+        break;
+    case update_check::State::Failed:
+        ImGui::TextColored(ImVec4(1.0f, 0.45f, 0.35f, 1.0f), "%s", status.detail.c_str());
+        break;
+    }
+    if (!g_updateError.empty()) {
+        ImGui::TextColored(ImVec4(1.0f, 0.45f, 0.35f, 1.0f), "%s", g_updateError.c_str());
+    }
+    if (status.restartNeeded && status.state != update_check::State::Updating) {
+        // The update replaced the build on disk; this process is still the old one.
+        ImGui::TextUnformatted("The update is installed. Quit and start the game again to use it.");
+    }
+    ImGui::PopTextWrapPos();
+
+    if (status.state == update_check::State::PcInstall) {
+        return;
+    }
+    if (status.restartNeeded && status.state != update_check::State::Updating) {
+        if (ImGui::Button("Quit")) g_exitPromptOpen = true;
+        ImGui::SameLine();
+    }
+    ImGui::BeginDisabled(busy);
+    if (ImGui::Button(status.state == update_check::State::Idle ? "Check for updates" : "Check again")) {
+        g_updateError.clear();
+        update_check::StartCheck();
+    }
+    if (ImGui::IsItemHovered()) {
+        ImGui::SetTooltip("Asks github.com for the newest release, and Retro Rewind's server for\n"
+                          "its newest pack when this install has one. Nothing is downloaded\n"
+                          "until you choose to update.");
+    }
+    if (status.state == update_check::State::Available) {
+        ImGui::SameLine();
+        if (ImGui::Button("Update now")) {
+            g_updateError.clear();
+            g_updatePromptOpen = true;
+        }
+        if (ImGui::IsItemHovered()) {
+            ImGui::SetTooltip("Builds the update here on the Frame, in the background. The game\n"
+                              "can stay open and shows the progress here.");
+        }
+    }
+    ImGui::EndDisabled();
+    // The prompt itself is drawn at the top level, as the exit prompt is: the tab lives both in the
+    // headset's panel and in a desktop menu, and a modal must outlive whichever opened it.
+}
+
 void DrawFpsOverlay() {
    AuroraPresentTiming presentTiming{};
    aurora_get_present_timing(&presentTiming);
@@ -2291,6 +2393,11 @@ void DrawTopBar() {
        ImGui::EndMenu();
    }

+    if (update_check::Relevant(update_check::Current()) && ImGui::BeginMenu("Updates")) {
+        DrawUpdateSettings();
+        ImGui::EndMenu();
+    }
+
    const ImGuiStyle& style = ImGui::GetStyle();
    const float hideWidth = ImGui::CalcTextSize("Hide (F10)").x + style.FramePadding.x * 2.0f;
    const float exitWidth = ImGui::CalcTextSize("X").x + style.FramePadding.x * 2.0f;
@@ -2479,6 +2586,9 @@ void DrawVrSettingsPanelWindow() {
            tab("Controllers", DrawControllerSettings);
            tab("Audio", DrawAudioSettings);
            tab("Diagnostics", DrawDiagnosticsSettings);
+            if (update_check::Relevant(update_check::Current())) {
+                tab("Updates", DrawUpdateSettings);
+            }
            ImGui::EndTabBar();
        }
    }
@@ -2687,6 +2797,7 @@ void Draw() noexcept {
    DrawFpsOverlay();
    DrawTopBar();
    DrawExitPrompt();
+    DrawUpdatePrompt();
    controller_mapping_wizard::Draw();
    // The wizard captures raw presses; keep them out of the game.
    const bool inputBlocked = controller_mapping_wizard::IsActive() || g_rebind.active;
@@ -0,0 +1,368 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#include "update_check.h"
+
+#include "runtime_config.h"
+
+#include <array>
+#include <charconv>
+#include <chrono>
+#include <cstdio>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <mutex>
+#include <string>
+#include <string_view>
+#include <system_error>
+#include <thread>
+
+// Updating itself is the Frame's build, installed by Launcher/steam-frame-install.sh: a desktop
+// Linux game that holds its own build directory. Everywhere else the tab only reports the release
+// it is running, which needs none of the machinery below.
+#if defined(__linux__) && !defined(__ANDROID__)
+#define MKW_UPDATE_CHECK_SUPPORTED 1
+#include <sys/wait.h>
+#else
+#define MKW_UPDATE_CHECK_SUPPORTED 0
+#endif
+
+namespace update_check {
+namespace {
+
+// Written by Launcher/steam-frame-install.sh when it built on this machine, naming itself and the
+// service that runs it. Its absence is what tells the tab this install is updated from a PC.
+constexpr std::string_view kConfigFileName = "update.conf";
+// An update's progress, and a check's answer. Separate files, so a check never overwrites the
+// result of the update that opened the game.
+constexpr std::string_view kStatusFileName = "update-status";
+constexpr std::string_view kCheckStatusFileName = "update-status-check";
+// What the Update button leaves for the update to pick up.
+constexpr std::string_view kRequestFileName = "update-request";
+// Stamped beside the executable by the install; absent for a build from a source tree.
+constexpr std::string_view kReleaseTagFileName = ".release-tag";
+
+// A finished update's status belongs on screen when the game opens right afterwards, which is what
+// the update does. Older than this it is history, and the tab starts clean.
+constexpr auto kStatusLifetime = std::chrono::hours(1);
+// A running update rewrites its status at every step and every percent of its build, so one that
+// has said nothing for this long was stopped without a chance to say so (the Frame lost power).
+constexpr auto kRunningStatusLifetime = std::chrono::hours(2);
+// The tab is drawn every frame; the files behind it are not read anywhere near that often.
+constexpr auto kReadInterval = std::chrono::seconds(1);
+
+std::string Trimmed(std::string_view text) {
+    const auto first = text.find_first_not_of(" \t\r\n");
+    if (first == std::string_view::npos) {
+        return {};
+    }
+    return std::string(text.substr(first, text.find_last_not_of(" \t\r\n") - first + 1));
+}
+
+std::string ReadFirstLine(const std::filesystem::path& file) {
+    std::ifstream stream(file);
+    std::string line;
+    if (!stream || !std::getline(stream, line)) {
+        return {};
+    }
+    return Trimmed(line);
+}
+
+struct Config {
+    std::filesystem::path script;
+    // The install's work directory, which holds the build the update reuses. The script defaults to
+    // the same place, but an install given --work-dir does not live there.
+    std::filesystem::path workDir;
+    std::string service;
+
+    bool Usable() const { return !script.empty() && !service.empty(); }
+};
+
+Config ReadConfig() {
+    Config config;
+#if !MKW_UPDATE_CHECK_SUPPORTED
+    return config;
+#else
+    std::ifstream stream(RuntimeConfigFile::ApplicationDataDirectory() / kConfigFileName);
+    if (!stream) {
+        return config;
+    }
+    std::string line;
+    while (std::getline(stream, line)) {
+        const auto separator = line.find('=');
+        if (line.empty() || line.front() == '#' || separator == std::string::npos) {
+            continue;
+        }
+        const std::string key = Trimmed(std::string_view(line).substr(0, separator));
+        const std::string value = Trimmed(std::string_view(line).substr(separator + 1));
+        if (key == "script") {
+            config.script = value;
+        } else if (key == "work_dir") {
+            config.workDir = value;
+        } else if (key == "service") {
+            config.service = value;
+        }
+    }
+    std::error_code ec;
+    if (!config.script.empty() && !std::filesystem::is_regular_file(config.script, ec)) {
+        // The work directory was removed, so there is nothing here to update from any more.
+        config.script.clear();
+    }
+    return config;
+#endif
+}
+
+std::string InstalledRelease() {
+    if (const auto executableDirectory = RuntimeConfigFile::ExecutableDirectory()) {
+        return ReadFirstLine(*executableDirectory / kReleaseTagFileName);
+    }
+    return {};
+}
+
+// What this session has been told, which outranks the files until the game is next started: a check
+// or update it asked for, and what came back.
+std::mutex g_mutex;
+bool g_sessionStateSet = false;
+State g_sessionState = State::Idle;
+std::string g_sessionDetail;
+// What was last read from disk, and when, so drawing the tab does not re-read it every frame.
+std::chrono::steady_clock::time_point g_lastRead;
+bool g_haveRead = false;
+bool g_haveFileState = false;
+State g_fileState = State::Idle;
+std::string g_fileDetail;
+bool g_canUpdate = false;
+// The release this process was started from, read once: an update replaces the stamp on disk while
+// the old build is still the one running. The stamp as it is now tells whether that has happened.
+std::string g_runningRelease;
+bool g_haveRunningRelease = false;
+std::string g_releaseOnDisk;
+
+void SetSessionState(State state, std::string detail) {
+    const std::lock_guard<std::mutex> lock(g_mutex);
+    g_sessionStateSet = true;
+    g_sessionState = state;
+    g_sessionDetail = std::move(detail);
+}
+
+std::string ShellQuoted(const std::string& text) {
+    std::string quoted = "'";
+    for (const char character : text) {
+        if (character == '\'') {
+            quoted += "'\\''";
+        } else {
+            quoted += character;
+        }
+    }
+    quoted += '\'';
+    return quoted;
+}
+
+// Runs `command`, returning its exit status and keeping the last line of its output for a message.
+int Run(const std::string& command, std::string& lastLine) {
+    lastLine.clear();
+#if !MKW_UPDATE_CHECK_SUPPORTED
+    (void)command;
+    return -1;
+#else
+    FILE* pipe = popen(command.c_str(), "r");
+    if (pipe == nullptr) {
+        return -1;
+    }
+    std::array<char, 512> buffer{};
+    while (std::fgets(buffer.data(), static_cast<int>(buffer.size()), pipe) != nullptr) {
+        if (const std::string line = Trimmed(buffer.data()); !line.empty()) {
+            lastLine = line;
+        }
+    }
+    const int status = pclose(pipe);
+    if (status == -1 || !WIFEXITED(status)) {
+        return -1;
+    }
+    return WEXITSTATUS(status);
+#endif
+}
+
+// Reads a "<state>\t<unix time>\t<text>" line the script wrote. False when there is none, it is too
+// old to be about now, or it cannot be understood.
+bool ReadStatusFile(const std::filesystem::path& file, State& state, std::string& detail) {
+    const std::string line = ReadFirstLine(file);
+    if (line.empty()) {
+        return false;
+    }
+    const auto firstTab = line.find('\t');
+    const auto secondTab = line.find('\t', firstTab + 1);
+    if (firstTab == std::string::npos || secondTab == std::string::npos) {
+        return false;
+    }
+    const std::string written = line.substr(0, firstTab);
+    long long seconds = 0;
+    const char* const secondsBegin = line.data() + firstTab + 1;
+    if (std::from_chars(secondsBegin, line.data() + secondTab, seconds).ec != std::errc{}) {
+        return false;
+    }
+    const auto age = std::chrono::system_clock::now() -
+                     std::chrono::system_clock::time_point(std::chrono::seconds(seconds));
+    const auto lifetime = written == "running" ? kRunningStatusLifetime : kStatusLifetime;
+    if (age > lifetime || age < -lifetime) {
+        return false;
+    }
+    if (written == "running") {
+        state = State::Updating;
+    } else if (written == "available") {
+        state = State::Available;
+    } else if (written == "uptodate" || written == "done") {
+        state = State::UpToDate;
+    } else if (written == "failed") {
+        state = State::Failed;
+    } else {
+        return false;
+    }
+    detail = line.substr(secondTab + 1);
+    return true;
+}
+
+} // namespace
+
+Status Current() {
+    const std::lock_guard<std::mutex> lock(g_mutex);
+    // Drawn every frame, so the files behind it are read on a timer instead.
+    const auto now = std::chrono::steady_clock::now();
+    if (!g_haveRead || now - g_lastRead > kReadInterval) {
+        g_releaseOnDisk = InstalledRelease();
+        if (!g_haveRunningRelease) {
+            g_runningRelease = g_releaseOnDisk;
+            g_haveRunningRelease = true;
+        }
+        g_lastRead = now;
+        g_haveRead = true;
+        g_canUpdate = ReadConfig().Usable();
+        g_fileState = State::Idle;
+        g_fileDetail.clear();
+        g_haveFileState = ReadStatusFile(RuntimeConfigFile::ApplicationDataDirectory() / kStatusFileName,
+                                         g_fileState, g_fileDetail);
+    }
+
+    Status status;
+    status.installedRelease = g_runningRelease;
+    status.restartNeeded = g_releaseOnDisk != g_runningRelease;
+    if (!g_canUpdate) {
+        status.state = State::PcInstall;
+        return status;
+    }
+    // An update's own reports outrank what this session last said: one started here (the session
+    // says Updating until the update writes its first step), or one this game was reopened after.
+    const bool followUpdate = !g_sessionStateSet || g_sessionState == State::Updating;
+    if (followUpdate && g_haveFileState) {
+        status.state = g_fileState;
+        status.detail = g_fileDetail;
+    } else if (g_sessionStateSet) {
+        status.state = g_sessionState;
+        status.detail = g_sessionDetail;
+    } else {
+        status.state = State::Idle;
+    }
+    return status;
+}
+
+void StartCheck() {
+    {
+        const std::lock_guard<std::mutex> lock(g_mutex);
+        if (g_sessionStateSet && (g_sessionState == State::Checking || g_sessionState == State::Updating)) {
+            return;
+        }
+    }
+    const Config config = ReadConfig();
+    if (!config.Usable()) {
+        return;
+    }
+    SetSessionState(State::Checking, "Asking github.com for the newest release");
+
+    // Detached: it talks to the network and must not hold up a frame, and there is no shutdown
+    // ordering to manage because it touches nothing the game owns.
+    std::thread([config] {
+        const auto statusFile = RuntimeConfigFile::ApplicationDataDirectory() / kCheckStatusFileName;
+        std::error_code ec;
+        std::filesystem::remove(statusFile, ec);
+        std::string command = "WIICOMPILED_UPDATE_STATUS=" + ShellQuoted(statusFile.string()) + ' ' +
+                              ShellQuoted(config.script.string()) + " --check";
+        if (!config.workDir.empty()) {
+            command += " --work-dir " + ShellQuoted(config.workDir.string());
+        }
+        command += " 2>&1";
+        std::string lastLine;
+        const int exitStatus = Run(command, lastLine);
+
+        State state = State::Failed;
+        std::string detail;
+        if (ReadStatusFile(statusFile, state, detail)) {
+            SetSessionState(state, detail);
+        } else if (exitStatus == 0) {
+            // It ran and said nothing this can read, which is still an answer: ask again later.
+            SetSessionState(State::Idle, "The check said nothing this version understands");
+        } else {
+            std::cerr << "[update] the check failed (exit " << exitStatus << "): " << lastLine << std::endl;
+            SetSessionState(State::Failed,
+                            lastLine.empty() ? "The check could not be run" : lastLine);
+        }
+        std::filesystem::remove(statusFile, ec);
+    }).detach();
+}
+
+bool StartUpdate(std::string& error) {
+    error.clear();
+    const Config config = ReadConfig();
+    if (!config.Usable()) {
+        error = "This build was installed from a PC, so the update is run there.";
+        return false;
+    }
+
+    const auto dataDirectory = RuntimeConfigFile::ApplicationDataDirectory();
+    std::error_code ec;
+    std::filesystem::create_directories(dataDirectory, ec);
+    // How the update opens the game again when it is done. Steam names the running title; without
+    // one (a build started from a terminal) the update still runs and the game is started by hand.
+    std::string steamGameId;
+    for (const char* variable : {"SteamGameId", "SteamAppId"}) {
+        if (const char* value = std::getenv(variable); value != nullptr && *value != '\0') {
+            steamGameId = value;
+            break;
+        }
+    }
+    {
+        std::ofstream request(dataDirectory / kRequestFileName, std::ios::trunc);
+        if (!request) {
+            error = "Could not write to " + dataDirectory.string();
+            return false;
+        }
+        request << "# Written by the game's Update button; the update removes it.\n";
+        if (!steamGameId.empty()) {
+            request << "steam_game_id=" << steamGameId << '\n';
+        }
+    }
+    // The previous update's result must not be read as this one's before it has written anything.
+    std::filesystem::remove(dataDirectory / kStatusFileName, ec);
+    // The update must outlive the game if the player closes it meanwhile, and Steam ends the game's
+    // own processes when it closes, so it runs as a service of its own. --no-block: started, not
+    // waited for.
+    std::string lastLine;
+    const std::string command =
+        "systemctl --user start --no-block " + ShellQuoted(config.service) + " 2>&1";
+    if (const int exitStatus = Run(command, lastLine); exitStatus != 0) {
+        std::filesystem::remove(dataDirectory / kRequestFileName, ec);
+        std::cerr << "[update] could not start " << config.service << " (exit " << exitStatus
+                  << "): " << lastLine << std::endl;
+        error = lastLine.empty() ? "Could not start the update service" : lastLine;
+        return false;
+    }
+    SetSessionState(State::Updating, "Starting the update");
+    // Read the files again at once, rather than show the removed status for up to a second.
+    const std::lock_guard<std::mutex> lock(g_mutex);
+    g_haveRead = false;
+    return true;
+}
+
+} // namespace update_check
+
+#undef MKW_UPDATE_CHECK_SUPPORTED
@@ -0,0 +1,70 @@
+using System.Security.Cryptography;
+using WiiCompiled.Setup.Linux;
+using Xunit;
+
+namespace Translator.Tests;
+
+public sealed class LinuxDiscExtractionTests
+{
+    private sealed class Reporter : IInstallReporter
+    {
+        public void Progress(string stage, string message, int percent) { }
+        public void Diagnostic(string line) { }
+    }
+
+    [Theory]
+    [InlineData("valid")]
+    [InlineData("wrong-hash")]
+    [InlineData("failed")]
+    [InlineData("cancelled")]
+    [InlineData("recovery")]
+    public async Task ExtractionPreservesLiveDataUntilValidationSucceeds(string mode)
+    {
+        if (!OperatingSystem.IsLinux()) return;
+        var root = Path.Combine(Path.GetTempPath(), "linux-disc-test-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+        try
+        {
+            var assets = Path.Combine(root, "Assets");
+            var data = Path.Combine(assets, "DATA");
+            Directory.CreateDirectory(data);
+            File.WriteAllText(Path.Combine(data, "old"), "working install");
+            if (mode == "recovery") Directory.Move(data, data + ".replaced");
+            var tool = Path.Combine(root, "nodtool");
+            File.WriteAllText(tool, """
+                #!/bin/bash
+                if [[ "$1" == info ]]; then echo 'Game ID: RMCP01'; exit 0; fi
+                mkdir -p "$3/sys" "$3/files/rel"
+                printf dol > "$3/sys/main.dol"
+                printf rel > "$3/files/rel/StaticR.rel"
+                """ + "\n" + (mode is "failed" or "recovery" ? "exit 1\n" : mode == "cancelled" ? "sleep 30\n" : "exit 0\n"));
+            File.SetUnixFileMode(tool, UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute);
+            var manifest = new ProjectManifest
+            {
+                GameId = "RMCP01", Region = "P",
+                DolSha256 = mode == "wrong-hash" ? new string('0', 64) : Hash("dol"),
+                RelSha256 = Hash("rel")
+            };
+            using var cancellation = new CancellationTokenSource();
+            if (mode == "cancelled") cancellation.CancelAfter(TimeSpan.FromMilliseconds(200));
+            var task = DiscTool.ValidateAndExtractAsync("disc.iso", manifest, assets, root, tool, new Reporter(), cancellation.Token);
+            if (mode == "valid")
+            {
+                await task;
+                Assert.False(File.Exists(Path.Combine(data, "old")));
+                Assert.Equal("dol", File.ReadAllText(Path.Combine(data, "sys", "main.dol")));
+                Assert.Equal("rel", File.ReadAllText(Path.Combine(assets, "StaticR.rel")));
+            }
+            else
+            {
+                await Assert.ThrowsAnyAsync<Exception>(() => task);
+                Assert.Equal("working install", File.ReadAllText(Path.Combine(data, "old")));
+            }
+            Assert.False(Directory.Exists(data + ".extracting"));
+            Assert.False(Directory.Exists(data + ".replaced"));
+        }
+        finally { Directory.Delete(root, recursive: true); }
+    }
+
+    private static string Hash(string text) => Convert.ToHexString(SHA256.HashData(System.Text.Encoding.UTF8.GetBytes(text))).ToLowerInvariant();
+}
@@ -35,6 +35,23 @@ public class RetroWfcPayloadLoweringTests
        Assert.Equal("moduleFunction", pointer.TargetKind);
    }

+    [Fact]
+    public void AlteredProductionPayloadFailsSignatureValidation()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "payload-validation-" + Guid.NewGuid().ToString("N"));
+        try
+        {
+            var payload = File.ReadAllBytes(Path.Combine(AppContext.BaseDirectory,
+                "TestAssets", "RetroWfcPayload", "binary", "payload.RMCPD00.bin"));
+            payload[^1] ^= 1;
+            Directory.CreateDirectory(Path.Combine(root, "binary"));
+            File.WriteAllBytes(Path.Combine(root, "binary", "payload.RMCPD00.bin"), payload);
+            Assert.Throws<InvalidDataException>(() =>
+                WiiCompiled.Setup.Common.RetroWfcPayload.ValidateStagedRetroWfcPayloadDirectory(root));
+        }
+        finally { Directory.Delete(root, recursive: true); }
+    }
+
    [Fact]
    public void ProductionPayloadValidatesAndTranslatesEverySupportedPatch()
    {
@@ -27,6 +27,7 @@
    <ProjectReference Include="..\..\src\Translator.Core\Translator.Core.csproj" />
    <ProjectReference Include="..\..\src\Translator.Cli\Translator.Cli.csproj" />
    <ProjectReference Include="..\..\..\Launcher\WiiCompiled.Setup.Common\WiiCompiled.Setup.Common.csproj" />
+    <ProjectReference Include="../../../Launcher/WiiCompiled.Setup.Linux/WiiCompiled.Setup.Linux.csproj" />
  </ItemGroup>

  <ItemGroup>
Author	SHA1	Message	Date
DieMitchell	53e20f4feb	Fix installation recovery and publish frame-beta-4 notes	2026-10-08 15:45:59 +02:00
mitch030504	d97f789dce	Merge pull request #14 from mitch030504/claude/docs-and-credits-41qj9z README: list the disc formats the installer accepts	2026-10-05 18:57:24 +02:00
Claude	4b5fe132bf	README: list the disc formats --disc accepts Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Axv1Y43Lu5a5rSSLUyU5BB	2026-10-05 16:55:44 +00:00
mitch030504	568166c163	Merge pull request #13 from mitch030504/claude/docs-and-credits-41qj9z Rewrite the README for frame-beta-3 and the update modes	2026-10-05 18:54:20 +02:00
Claude	5e055dde13	README: rewrite for frame-beta-3 and the update modes Restructure the README around what a player does: choose where to build (PC or the Frame), install, update, play, then settings, controls, known issues and troubleshooting. Building on a server and by hand move under "Other ways to build", and the upstream and credits notes are merged into "What comes from where" and a short Credits section that points at CREDITS.md. Updating now shows the curl form of --update, which works without a local copy of the script; the in-game Updates tab; and the one full install needed when coming from frame-beta-2. Manual steps use the frame-beta-3 tag, the install options are a table, and the Troubleshooting section covers in-game update failures. Links to the old "The Android flavour" section now point at "How it works". Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Axv1Y43Lu5a5rSSLUyU5BB	2026-10-05 16:47:23 +00:00
mitch030504	b35243244f	Merge pull request #12 from mitch030504/claude/install-update-mode-wm4qyu Update the Frame install with --update, or from an Updates tab in the game	2026-10-05 18:37:58 +02:00
Claude	55d921a118	Add --update and --check to the install script, and an Updates tab in the game --update reuses the options an install was made with (saved to install.conf in the work dir) and builds nothing when the Frame already has the newest release and Retro Rewind pack; --check only reports. The installed release is stamped as .release-tag beside the game on the Frame. An install built on the Frame itself (--frame local) also gets a systemd user service the game's new Updates tab starts: the update runs in the background at low priority, writes each step and the build percentage to a status file the tab shows, and reopens the game at the end if it was closed. Progress does not go through Steam notifications: on the Frame, Steam receives them from steam_notif_daemon but does not display them. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UyuWx5hNrMpf9R78FZFcbA	2026-10-05 16:27:15 +00:00
mitch030504	9be271d49a	Merge pull request #11 from mitch030504/claude/docs-and-credits-41qj9z Credit ported work and document today's merged changes	2026-10-05 18:24:31 +02:00
Claude	6a3441b616	Docs: credit ported work and cover today's merged changes Add CREDITS.md, listing the projects the fork is built on and every change ported from upstream WiiCompiled and other forks, with author and source commit, taken from the commit messages. Link it from the README, THIRD-PARTY-NOTICES.md and a new porting note in CONTRIBUTING.md. Document adaptive_resolution in OPENXR.md, the 4 KiB page constant and NEON mixing in the README, the Mozilla CA bundle in the notices, and draft the frame-beta-3 release notes for what PRs #5 to #10 merged. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Axv1Y43Lu5a5rSSLUyU5BB	2026-10-05 16:22:20 +00:00
mitch030504	58b6d81ed1	Merge pull request #10 from mitch030504/claude/project-thread-4jegmq Port three small fixes from the DarthMDev and KartPad forks	2026-10-05 18:15:11 +02:00