Add manifest upload to release workflow

Reviewed-on: #1

.gitea/workflows/build.yml

@@ -1,75 +0,0 @@
-name: build
-
-on:
-  # Manual only for now. Select the branch to build when dispatching:
-  #   main -> APP_VERSION is the current git tag
-  #   dev  -> APP_VERSION is the current commit hash
-  workflow_dispatch:
-
-jobs:
-  nix-build:
-    runs-on: build-server
-    steps:
-      # actions/checkout@v4 is unreliable on host-mode runners (its files are
-      # copied into the workspace instead of the repo), so clone explicitly.
-      # A full clone (no --depth) is required so `git describe --tags` on main
-      # resolves the real nearest tag instead of falling back to a hash.
-      - name: Checkout
-        run: |
-          rm -rf ./* ./.[!.]* 2>/dev/null || true
-          git config --global http.extraheader "Authorization: token ${{ github.token }}"
-          git clone --branch "${{ gitea.ref_name }}" \
-            "${{ gitea.server_url }}/${{ gitea.repository }}.git" .
-          test -f flake.nix
-          git log --oneline -1
-
-      - name: Inspect workspace
-        run: |
-          pwd
-          ls -la
-          git rev-parse --show-toplevel 2>&1 || true
-          git remote -v 2>&1 || true
-          git describe --tags --always 2>&1 || true
-          test -f flake.nix && echo "flake.nix present" || echo "NO flake.nix"
-
-      # Compute the version string baked into the binary's Home footer:
-      # main reports the git tag, dev reports the commit hash fingerprint.
-      # The key stays in the build step's environment (never echoed).
-      - name: Compute version
-        id: version
-        run: |
-          if [ "${{ gitea.ref_name }}" = "main" ]; then
-            APP_VERSION="$(git describe --tags --always)"
-          else
-            APP_VERSION="$(git rev-parse --short HEAD)"
-          fi
-          echo "Branch: ${{ gitea.ref_name }} -> APP_VERSION=$APP_VERSION"
-
-      # checks is keyed per-system (checks.<system>.default); nix build's
-      # #attr shorthand can't resolve it, so resolve the current system inline.
-      # --impure lets the flake read APP_VERSION via builtins.getEnv
-      # (pure evals always get the package defaults). The offline test suite
-      # runs in the package's checkPhase.
-      - name: Build + offline test suite
-        run: nix build -L ".#checks.$(nix eval --impure --raw --expr 'builtins.currentSystem').default" --impure
-
-      - name: Live portal tests
-        env:
-          RWT_LIVE_ACCOUNT_EMAIL: ${{ secrets.RWT_LIVE_ACCOUNT_EMAIL }}
-          RWT_LIVE_LICENSE_EMAIL: ${{ secrets.RWT_LIVE_LICENSE_EMAIL }}
-          RWT_LIVE_LICENSE_KEY: ${{ secrets.RWT_LIVE_LICENSE_KEY }}
-        run: |
-          nix develop --command bash -c '
-            cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
-            cmake --build build --target test_api_client test_license_service
-            ./build/test_api_client
-            ./build/test_license_service
-          '
-
-      - name: Push to Attic cache
-        run: |
-          nix profile install github:zhaofengli/attic#attic-client \
-          --extra-experimental-features "nix-command flakes"
-
-          attic login radiantwave https://attic.radiantwavetech.com "${{ secrets.ATTIC_TOKEN }}"
-          attic push radiantwave ./result-kiosk ./result-android ./result-commercial

.gitea/workflows/dev.yml

@@ -0,0 +1,82 @@
+name: build-dev
+on:
+  # Every push to dev: build, run the offline test suite, publish to the
+  # dev Attic cache.
+  push:
+    branches: [dev]
+jobs:
+  nix-build:
+    runs-on: build-server
+    steps:
+      # actions/checkout@v4 is unreliable on host-mode runners (its files are
+      # copied into the workspace instead of the repo), so clone explicitly.
+      - name: Checkout
+        run: |
+          rm -rf ./* ./.[!.]* 2>/dev/null || true
+          git config --global http.extraheader "Authorization: token ${{ github.token }}"
+          git clone --branch "${{ gitea.ref_name }}" \
+            "${{ gitea.server_url }}/${{ gitea.repository }}.git" .
+          test -f flake.nix
+          git log --oneline -1
+      - name: Inspect workspace
+        run: |
+          pwd
+          ls -la
+          git rev-parse --show-toplevel 2>&1 || true
+          git remote -v 2>&1 || true
+          git describe --tags --always 2>&1 || true
+          test -f flake.nix && echo "flake.nix present" || echo "NO flake.nix"
+      # Dev builds fingerprint as the short commit hash.
+      # Persisted via GITHUB_ENV so the impure nix eval below reads it via
+      # builtins.getEnv.
+      - name: Compute version
+        run: |
+          echo "APP_VERSION=$(git rev-parse --short HEAD)" >> "$GITHUB_ENV"
+      # checks is keyed per-system (checks.<system>.default); nix build's
+      # #attr shorthand can't resolve it, so resolve the current system inline.
+      # --impure lets the flake read APP_VERSION via builtins.getEnv
+      # (pure evals always get the package defaults).
+      - name: Build package
+        run: |
+          nix build -L ".#packages.$(nix eval --impure --raw --expr 'builtins.currentSystem').default" \
+            --impure --out-link result-pkg
+      # The offline test suite runs in the check derivation's checkPhase.
+      # This is a separate build/output from the package itself.
+      - name: Build + offline test suite
+        run: |
+          nix build -L ".#checks.$(nix eval --impure --raw --expr 'builtins.currentSystem').default" \
+            --impure --out-link result-checks
+      - name: Live portal tests
+        env:
+          RWT_LIVE_ACCOUNT_EMAIL: ${{ secrets.RWT_LIVE_ACCOUNT_EMAIL }}
+          RWT_LIVE_LICENSE_EMAIL: ${{ secrets.RWT_LIVE_LICENSE_EMAIL }}
+          RWT_LIVE_LICENSE_KEY: ${{ secrets.RWT_LIVE_LICENSE_KEY }}
+        run: |
+          nix develop --command bash -c '
+            cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
+            cmake --build build --target test_api_client test_license_service
+            ./build/test_api_client
+            ./build/test_license_service
+          '
+      # Dev closure (the actual package, not the check output) lands in the
+      # dev cache.
+      - name: Push to Attic dev cache
+        env:
+          ATTIC_TOKEN: ${{ secrets.ATTIC_TOKEN_DEV }}
+        run: |
+          attic login radiantwave https://attic.radiantwavetech.com "$ATTIC_TOKEN"
+          attic push radiantwave:radiantwave-dev ./result-pkg
+
+      # Publish the manifest kiosks poll for live app updates. `storePath`
+      # must match exactly the closure pushed to the dev Attic cache above
+      # (readlink resolves the result-pkg out-link symlink to its real
+      # /nix/store path), so a kiosk can `nix copy --from` it without ever
+      # building from source. Upload mirrors the ISO scp pattern to the
+      # fileserver via the build-server's `radiantwave-infra` SSH alias.
+      - name: Publish manifest
+        run: |
+          STOREPATH=$(readlink -f ./result-pkg)
+          printf '{"version":"%s","storePath":"%s"}\n' "${{ env.APP_VERSION }}" "$STOREPATH" > manifest.json
+          cat manifest.json
+          scp manifest.json \
+            radiantwave-infra:/mnt/infrastructure_data/files/radiantwave-dev/manifest.json

.gitea/workflows/main.yml

@@ -0,0 +1,90 @@
+name: build-main
+
+on:
+  # Manual only. Dispatch against main: build, run the offline test suite,
+  # publish to the release Attic cache and live-update manifest.
+  workflow_dispatch:
+
+jobs:
+  nix-build:
+    runs-on: build-server
+    steps:
+      # actions/checkout@v4 is unreliable on host-mode runners (its files are
+      # copied into the workspace instead of the repo), so clone explicitly.
+      # A full clone (no --depth) is required so `git describe --tags` resolves
+      # the real nearest tag instead of falling back to a hash.
+      - name: Checkout
+        run: |
+          rm -rf ./* ./.[!.]* 2>/dev/null || true
+          git config --global http.extraheader "Authorization: token ${{ github.token }}"
+          git clone --branch "${{ gitea.ref_name }}" \
+            "${{ gitea.server_url }}/${{ gitea.repository }}.git" .
+          test -f flake.nix
+          git log --oneline -1
+
+      - name: Inspect workspace
+        run: |
+          pwd
+          ls -la
+          git rev-parse --show-toplevel 2>&1 || true
+          git remote -v 2>&1 || true
+          git describe --tags --always 2>&1 || true
+          test -f flake.nix && echo "flake.nix present" || echo "NO flake.nix"
+
+      # Release builds report the current git tag.
+      # Persisted via GITHUB_ENV so the impure nix eval below reads it via
+      # builtins.getEnv.
+      - name: Compute version
+        run: |
+          echo "APP_VERSION=$(git describe --tags --always)" >> "$GITHUB_ENV"
+
+      # checks is keyed per-system (checks.<system>.default); nix build's
+      # #attr shorthand can't resolve it, so resolve the current system inline.
+      # --impure lets the flake read APP_VERSION via builtins.getEnv
+      # (pure evals always get the package defaults).
+      - name: Build package
+        run: |
+          nix build -L ".#packages.$(nix eval --impure --raw --expr 'builtins.currentSystem').default" \
+            --impure --out-link result-pkg
+      # The offline test suite runs in the check derivation's checkPhase.
+      # This is a separate build/output from the package itself.
+      - name: Build + offline test suite
+        run: |
+          nix build -L ".#checks.$(nix eval --impure --raw --expr 'builtins.currentSystem').default" \
+            --impure --out-link result-checks
+
+      - name: Live portal tests
+        env:
+          RWT_LIVE_ACCOUNT_EMAIL: ${{ secrets.RWT_LIVE_ACCOUNT_EMAIL }}
+          RWT_LIVE_LICENSE_EMAIL: ${{ secrets.RWT_LIVE_LICENSE_EMAIL }}
+          RWT_LIVE_LICENSE_KEY: ${{ secrets.RWT_LIVE_LICENSE_KEY }}
+        run: |
+          nix develop --command bash -c '
+            cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
+            cmake --build build --target test_api_client test_license_service
+            ./build/test_api_client
+            ./build/test_license_service
+          '
+
+      # Release closure (the actual package, not the check output) lands in the
+      # release cache.
+      - name: Push to Attic release cache
+        env:
+          ATTIC_TOKEN: ${{ secrets.ATTIC_TOKEN_PROD }}
+        run: |
+          attic login radiantwave https://attic.radiantwavetech.com "$ATTIC_TOKEN"
+          attic push radiantwave:radiantwave ./result-pkg
+
+      # Publish the manifest production kiosks poll for live app updates.
+      # `storePath` must match exactly the closure pushed to the release Attic
+      # cache above (readlink resolves the result-pkg out-link symlink to its
+      # real /nix/store path), so a kiosk can `nix copy --from` it without ever
+      # building from source. Upload mirrors the ISO scp pattern to the
+      # fileserver via the build-server's `radiantwave-infra` SSH alias.
+      - name: Publish manifest
+        run: |
+          STOREPATH=$(readlink -f ./result-pkg)
+          printf '{"version":"%s","storePath":"%s"}\n' "${{ env.APP_VERSION }}" "$STOREPATH" > manifest.json
+          cat manifest.json
+          scp manifest.json \
+            radiantwave-infra:/mnt/infrastructure_data/files/radiantwave/manifest.json

CMakeLists.txt

@@ -112,7 +112,14 @@ add_executable(test_provisioning
     tests/test_provisioning.cpp
 )
 target_include_directories(test_provisioning PRIVATE src)
-target_link_libraries(test_provisioning PRIVATE SDL3::SDL3)
+# provisioning.h pulls in app_state.h, so the test compiles against the SDL3,
+# SDL3_mixer, and SQLite headers transitively (app_state.h -> audio_manager.h ->
+# SDL3_mixer; app_state.h -> database_manager.h -> sqlite3.h).
+target_link_libraries(test_provisioning PRIVATE
+    SDL3::SDL3
+    SDL3_mixer::SDL3_mixer
+    SQLite3::SQLite3
+)
 
 add_executable(test_assets
     tests/test_assets.cpp

nixos/vm.nix

@@ -112,6 +112,18 @@ in
       export WLR_RENDERER=pixman
       export WLR_NO_HARDWARE_CURSORS=1
 
+      # Prefer the PipeWire audio backend so SDL enumerates every sink
+      # (built-in analog, HDMI, and the loopback virtual speaker) instead of
+      # silently falling back to an ALSA-only device view that hides the
+      # PipeWire sinks and makes the device selector show a single entry.
+      export SDL_AUDIODRIVER=pipewire
+      if [ -n "$${XDG_RUNTIME_DIR:-}" ]; then
+        for i in {1..20}; do
+          [ -S "$XDG_RUNTIME_DIR/pipewire-0" ] && break
+          sleep 0.5
+        done
+      fi
+
       cage -- ${radiantWaveApp}/bin/radiantwave > /tmp/kiosk.log 2>&1
     fi
   '';

src/audio/audio_downloader.h

@@ -37,7 +37,7 @@ struct AudioManifestEntry {
 // and keeps the database's audio_files table in sync with what is actually
 // on disk.
 //
-// Fetches new_checksums.md5, compares each entry against the local file's MD5,
+// Fetches checksums.md5, compares each entry against the local file's MD5,
 // and re-downloads anything that is missing or whose checksum differs.
 // Files present on disk but absent from the manifest are deleted, and the
 // audio_files table is reconciled on every pass (and after each individual
@@ -68,7 +68,7 @@ public:
 
 	static constexpr const char *AUDIO_BASE_URL =
 		"https://files.radiantwavetech.com/audio/";
-	static constexpr const char *MANIFEST_FILENAME = "new_checksums.md5";
+	static constexpr const char *MANIFEST_FILENAME = "checksums.md5";
 
 private:
 	void run();
@@ -88,7 +88,7 @@ private:
 	db::DatabaseManager *db_ = nullptr;
 };
 
-// Parses new_checksums.md5 manifest text into entries. Blank lines and lines
+// Parses checksums.md5 manifest text into entries. Blank lines and lines
 // starting with '#' are ignored. Lines that don't match a known format are
 // skipped. Returns false if no valid entries were found.
 bool parseManifest(const std::string &text,

src/audio/audio_manager.cpp

@@ -32,6 +32,7 @@ namespace radiantwave::audio
         if (lower.find("analog") != std::string::npos ||
             lower.find("built-in") != std::string::npos ||
             lower.find("builtin") != std::string::npos ||
+            lower.find("virtual") != std::string::npos ||
             lower.find("realtek") != std::string::npos ||
             lower.find("hda") != std::string::npos ||
             lower.find("speaker") != std::string::npos ||
@@ -76,7 +77,6 @@ namespace radiantwave::audio
         enabled_ = cfg.audio.enabled;
         currentDevice_ = cfg.audio.output_device;
         currentTrack_ = cfg.audio.current_track;
-
         if (!MIX_Init())
         {
             std::string err = SDL_GetError();
@@ -86,17 +86,68 @@ namespace radiantwave::audio
             return false;
         }
 
-        // Create mixer device with default audio device
-        mixer_ = MIX_CreateMixerDevice(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, nullptr);
+        // Startup diagnostics: which audio backend SDL picked (PipeWire, ALSA,
+        // Pulse, dummy, ...) and what playback devices it actually sees. This is
+        // the first place a "only the built-in speakers show up" report points;
+        // a single device here means SDL itself never enumerated the HDMI sink.
+        const char *driver = SDL_GetCurrentAudioDriver();
+        std::string driverName = driver ? driver : "(none)";
+        int deviceCount = 0;
+        SDL_AudioDeviceID *devices = SDL_GetAudioPlaybackDevices(&deviceCount);
+        std::string deviceNames;
+        if (devices)
+        {
+            for (int i = 0; i < deviceCount; ++i)
+            {
+                if (i)
+                {
+                    deviceNames += ", ";
+                }
+                const char *n = SDL_GetAudioDeviceName(devices[i]);
+                deviceNames += n ? n : "(unnamed)";
+            }
+            SDL_free(devices);
+        }
+        logger::Logger::instance().info(
+            "Audio",
+            "SDL audio driver: " + driverName + "; " +
+                std::to_string(deviceCount) + " playback device(s) [" +
+                (deviceNames.empty() ? "(none)" : deviceNames) + "]");
+
+        // Try to open the mixer on the device previously persisted in config;
+        // fall back to the system default when the configured device is gone.
+        SDL_AudioDeviceID targetId = SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK;
+        if (!currentDevice_.empty())
+        {
+            int count = 0;
+            SDL_AudioDeviceID *devices = SDL_GetAudioPlaybackDevices(&count);
+            if (devices)
+            {
+                for (int i = 0; i < count; ++i)
+                {
+                    const char *name = SDL_GetAudioDeviceName(devices[i]);
+                    if (name && currentDevice_ == name)
+                    {
+                        targetId = devices[i];
+                        break;
+                    }
+                }
+                SDL_free(devices);
+            }
+        }
+
+        mixer_ = MIX_CreateMixerDevice(targetId, nullptr);
         if (!mixer_)
         {
             std::string err = SDL_GetError();
             logger::Logger::instance().warning("Audio",
-                                               "Could not open default audio playback device. Check speaker connections (MIX_CreateMixerDevice error: " + err + ")");
+                                               "Could not open audio playback device. Check speaker connections (MIX_CreateMixerDevice error: " + err + ")");
             initialized_ = false;
             return false;
         }
 
+        currentDeviceId_ = targetId;
+
         slots_[0].track = MIX_CreateTrack(mixer_);
         slots_[1].track = MIX_CreateTrack(mixer_);
         initialized_ = true;
@@ -135,6 +186,40 @@ namespace radiantwave::audio
         return enabled_ ? (volume_ / 100.0f) : 0.0f;
     }
 
+    SDL_PropertiesID AudioManager::createInfiniteLoopOptions()
+    {
+        // MIX_PlayTrack()'s options default to a single pass; requesting
+        // infinite loops is what keeps a track going until it is explicitly
+        // faded out or the app shuts down.
+        SDL_PropertiesID props = SDL_CreateProperties();
+        if (props)
+        {
+            SDL_SetNumberProperty(props, MIX_PROP_PLAY_LOOPS_NUMBER, -1);
+        }
+        return props;
+    }
+
+    bool AudioManager::playTrackLooping(int slotIndex)
+    {
+        if (!initialized_ || !mixer_ || slotIndex < 0 || slotIndex >= 2 ||
+            !slots_[slotIndex].track)
+        {
+            return false;
+        }
+
+        SDL_PropertiesID props = createInfiniteLoopOptions();
+        if (!props)
+        {
+            logger::Logger::instance().error(
+                "Audio", "Failed to create playback options for " +
+                             displayNameFor(currentTrack_));
+            return false;
+        }
+        bool ok = MIX_PlayTrack(slots_[slotIndex].track, props);
+        SDL_DestroyProperties(props);
+        return ok;
+    }
+
     void AudioManager::shutdown()
     {
         std::lock_guard<std::mutex> lock(mutex_);
@@ -181,18 +266,62 @@ namespace radiantwave::audio
             {
                 const char *name = SDL_GetAudioDeviceName(devices[i]);
                 std::string raw = name ? name : "";
-                list.push_back({raw, mapToFriendlyDeviceName(raw)});
+                AudioDeviceItem item;
+                item.raw_name = raw;
+                item.friendly_name = mapToFriendlyDeviceName(raw);
+                item.id = devices[i];
+                list.push_back(item);
             }
             SDL_free(devices);
         }
         else
         {
-            list.push_back({"", "Built-In Speakers"});
+            if (devices)
+            {
+                SDL_free(devices);
+            }
+            const char *driver = SDL_GetCurrentAudioDriver();
+            // Zero enumerated devices is a symptom, not a real output. Surface
+            // the truth (a single "System Default" entry that still routes to
+            // whatever the OS default is) instead of pretending a fabricated
+            // device, and say which backend was active so kiosk logs show why.
+            logger::Logger::instance().debug(
+                "Audio",
+                "No playback devices enumerated (audio driver: " +
+                    std::string(driver ? driver : "none") +
+                    "); falling back to the system default");
+            list.push_back({"", "System Default", 0});
         }
 
         return list;
     }
 
+    std::string AudioManager::resolvePlaybackDeviceName(SDL_AudioDeviceID id)
+    {
+        if (id == 0 || id == SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK)
+        {
+            return "";
+        }
+
+        int count = 0;
+        SDL_AudioDeviceID *devices = SDL_GetAudioPlaybackDevices(&count);
+        std::string found;
+        if (devices)
+        {
+            for (int i = 0; i < count; ++i)
+            {
+                if (devices[i] == id)
+                {
+                    const char *name = SDL_GetAudioDeviceName(devices[i]);
+                    found = name ? name : "";
+                    break;
+                }
+            }
+            SDL_free(devices);
+        }
+        return found;
+    }
+
     void AudioManager::setVolume(int volume_0_to_100)
     {
         std::lock_guard<std::mutex> lock(mutex_);
@@ -253,14 +382,76 @@ namespace radiantwave::audio
     bool AudioManager::switchDevice(const std::string &raw_device_name)
     {
         std::lock_guard<std::mutex> lock(mutex_);
-        currentDevice_ = raw_device_name;
 
-        logger::Logger::instance().debug("Audio", "Switched audio output device to: " + mapToFriendlyDeviceName(raw_device_name));
+        // Resolve the config's raw name to an SDL device id so the mixer is
+        // actually reopened on the requested device (""/unresolvable = default).
+        SDL_AudioDeviceID targetId = SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK;
+        if (!raw_device_name.empty())
+        {
+            int count = 0;
+            SDL_AudioDeviceID *devices = SDL_GetAudioPlaybackDevices(&count);
+            if (devices)
+            {
+                for (int i = 0; i < count; ++i)
+                {
+                    const char *name = SDL_GetAudioDeviceName(devices[i]);
+                    if (name && raw_device_name == name)
+                    {
+                        targetId = devices[i];
+                        break;
+                    }
+                }
+                SDL_free(devices);
+            }
+        }
+
+        return switchDeviceById(targetId);
+    }
+
+    bool AudioManager::switchDeviceById(SDL_AudioDeviceID id)
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+
+        // 0 is the synthetic "default / built-in" entry from getPlaybackDevices().
+        if (id == 0)
+        {
+            id = SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK;
+        }
+
+        // No mixer yet: just record the choice for initialize().
+        if (!mixer_ || !initialized_)
+        {
+            currentDeviceId_ = id;
+            currentDevice_ = resolvePlaybackDeviceName(id);
+            if (configManager_)
+            {
+                configManager_->update([name = currentDevice_](config::AppConfig &cfg)
+                                       { cfg.audio.output_device = name; });
+            }
+            return true;
+        }
+
+        if (!recreateMixerOnDevice(id))
+        {
+            logger::Logger::instance().error("Audio",
+                                             "Failed to switch audio output device to: " + mapToFriendlyDeviceName(resolvePlaybackDeviceName(id)));
+            return false;
+        }
+
+        currentDeviceId_ = id;
+        // After recreation SDL may have normalized the id (e.g. default).
+        if (SDL_GetAudioDeviceName(id) == nullptr && id != SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK)
+        {
+            currentDeviceId_ = SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK;
+        }
+        currentDevice_ = resolvePlaybackDeviceName(currentDeviceId_);
+
+        logger::Logger::instance().info("Audio", "Switched audio output device to: " + mapToFriendlyDeviceName(currentDevice_));
 
         if (configManager_)
         {
-            configManager_->update([raw_device_name](config::AppConfig &cfg)
-                                   { cfg.audio.output_device = raw_device_name; });
+            configManager_->update([name = currentDevice_](config::AppConfig &cfg)
+                                   { cfg.audio.output_device = name; });
         }
 
         return true;
@@ -272,6 +463,150 @@ namespace radiantwave::audio
         return currentDevice_;
     }
 
+    SDL_AudioDeviceID AudioManager::getCurrentDeviceId() const
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        return currentDeviceId_;
+    }
+
+    bool AudioManager::handleDeviceEvent(const SDL_Event &event)
+    {
+        if (event.type != SDL_EVENT_AUDIO_DEVICE_ADDED &&
+            event.type != SDL_EVENT_AUDIO_DEVICE_REMOVED)
+        {
+            return false;
+        }
+
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (!mixer_ || !initialized_)
+        {
+            return false;
+        }
+
+        // Only playback device events are relevant to the active output.
+        if (event.adevice.recording)
+        {
+            return false;
+        }
+
+        const SDL_AudioDeviceID changedId = event.adevice.which;
+
+        // If a specific device (not the default) was removed, fail over to the
+        // system default so playback keeps going on whatever remains.
+        if (event.type == SDL_EVENT_AUDIO_DEVICE_REMOVED &&
+            currentDeviceId_ != SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK &&
+            changedId == currentDeviceId_)
+        {
+            logger::Logger::instance().warning("Audio",
+                                               "Active audio output device removed; failing over to the system default");
+            if (recreateMixerOnDevice(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK))
+            {
+                currentDeviceId_ = SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK;
+                currentDevice_ = "";
+            }
+            return true;
+        }
+
+        // A device arrived or a non-active device left: nothing to remap, but
+        // the audio settings page refreshes its list on its own timer.
+        return false;
+    }
+
+    // Must be called with mutex_ held. Creates a fresh mixer on the given
+    // device, recreating the two track slots and resuming the active track if
+    // one was playing.
+    //
+    // The new mixer is created BEFORE the current one is destroyed. Reversing
+    // the order (destroy-then-reopen) quits the whole SDL audio subsystem the
+    // moment the last device closes: MIX_DestroyMixer() follows up with
+    // SDL_QuitSubSystem(SDL_INIT_AUDIO), which tears down SDL's device registry
+    // and renumbers every enumerated device id on the way back up. The id this
+    // switch was asked to open is then stale and the reopen fails with
+    // "Invalid audio device instance ID". Keeping the current device open while
+    // the replacement opens also means a failed switch leaves the current
+    // output playing instead of going permanently mute.
+    bool AudioManager::recreateMixerOnDevice(SDL_AudioDeviceID targetId)
+    {
+        // Capture the playback state we want to preserve across the switch.
+        std::string resumeTrack = currentTrack_;
+        float fadeSeconds = slots_[activeSlot_].fadeInDuration > 0.0f
+                                ? slots_[activeSlot_].fadeInDuration
+                                : 0.0f;
+
+        // Open the replacement mixer on the target device first, while the
+        // current device (and SDL's device registry) is still alive.
+        MIX_Mixer *newMixer = MIX_CreateMixerDevice(targetId, nullptr);
+        if (!newMixer)
+        {
+            std::string err = SDL_GetError();
+            logger::Logger::instance().error(
+                "Audio",
+                "Could not open audio output device "
+                + mapToFriendlyDeviceName(resolvePlaybackDeviceName(targetId))
+                + "; keeping the current device (MIX_CreateMixerDevice error: "
+                + err + ")");
+            return false;
+        }
+
+        MIX_Track *newTracks[2];
+        for (int i = 0; i < 2; ++i)
+        {
+            newTracks[i] = MIX_CreateTrack(newMixer);
+        }
+        if (!newTracks[0] || !newTracks[1])
+        {
+            MIX_DestroyMixer(newMixer);
+            logger::Logger::instance().error(
+                "Audio", "Could not create mixer tracks; keeping the current device (SDL error: "
+                             + std::string(SDL_GetError()) + ")");
+            return false;
+        }
+
+        // Tear down the existing mixer (its tracks die with it) and adopt the
+        // new one.
+        for (int i = 0; i < 2; ++i)
+        {
+            slots_[i].track = nullptr;
+            if (slots_[i].audio)
+            {
+                MIX_DestroyAudio(slots_[i].audio);
+                slots_[i].audio = nullptr;
+            }
+        }
+        if (mixer_)
+        {
+            MIX_DestroyMixer(mixer_);
+            mixer_ = nullptr;
+        }
+
+        mixer_ = newMixer;
+        slots_[0].track = newTracks[0];
+        slots_[1].track = newTracks[1];
+
+        float gain = enabled_ ? (volume_ / 100.0f) : 0.0f;
+        MIX_SetMixerGain(mixer_, gain);
+
+        // Resume the previously active track at full gain (or restart its
+        // fade-in if it was still ramping).
+        if (!resumeTrack.empty())
+        {
+            if (loadTrackInto(activeSlot_, resumeTrack))
+            {
+                if (fadeSeconds > 0.0f)
+                {
+                    startFadeIn(activeSlot_, fadeSeconds);
+                }
+                else
+                {
+                    MIX_SetTrackGain(slots_[activeSlot_].track, 1.0f);
+                    playTrackLooping(activeSlot_); // Loop playback
+                }
+            }
+        }
+
+        return true;
+    }
+
     bool AudioManager::loadTrackInto(int slotIndex, const std::string &wav_filename)
     {
         if (!initialized_ || !mixer_ || !slots_[slotIndex].track)
@@ -322,7 +657,7 @@ namespace radiantwave::audio
         slot.fadeInDuration = seconds;
         slot.fadeInElapsed = 0.0f;
         MIX_SetTrackGain(slot.track, 0.0f);
-        MIX_PlayTrack(slot.track, 0); // Loop playback
+        playTrackLooping(slotIndex); // Loop playback
         logger::Logger::instance().info("Audio", "Started playback of " + displayNameFor(currentTrack_) + " (fade-in)");
     }
 
@@ -336,7 +671,7 @@ namespace radiantwave::audio
             return false;
 
         MIX_SetTrackGain(slots_[activeSlot_].track, 1.0f);
-        MIX_PlayTrack(slots_[activeSlot_].track, 0); // Loop playback
+        playTrackLooping(activeSlot_); // Loop playback
 
         // Explicit user selection: persist the manual track so it survives a
         // restart and is used whenever dynamic audio is turned off. Dynamic
@@ -373,10 +708,11 @@ namespace radiantwave::audio
             slot.fadeInElapsed = 0.0f;
             slot.fadeOutRemaining = 0.0f;
             MIX_SetTrackGain(slot.track, 1.0f);
-            if (!MIX_TrackPlaying(slot.track))
-            {
-                MIX_PlayTrack(slot.track, 0); // Loop playback
-            }
+            // Always restart: MIX_PlayTrack() re-starts a playing track too, so
+            // this cancels any in-flight stop-fade inherited from a quick
+            // pop->push within the fade window. Gating on MIX_TrackPlaying()
+            // left a fading track to finish its fade and go silently stopped.
+            playTrackLooping(activeSlot_); // Loop playback
             return true;
         }
 
@@ -411,10 +747,14 @@ namespace radiantwave::audio
         if (!loadTrackInto(otherSlot, wav_filename))
             return false;
 
-        // Fade out whatever is currently playing on the active slot.
+        // Fade out whatever is currently playing on the active slot. Clear any
+        // in-flight fade-in bookkeeping first so update() stops ramping this
+        // slot's gain up while the mixer fades it down.
         TrackSlot &active = slots_[activeSlot_];
         if (active.audio)
         {
+            active.fadeInDuration = 0.0f;
+            active.fadeInElapsed = 0.0f;
             MIX_StopTrack(active.track, MIX_TrackMSToFrames(active.track, static_cast<Sint64>(fade * 1000.0)));
             active.fadeOutRemaining = fade;
         }
@@ -442,6 +782,10 @@ namespace radiantwave::audio
             {
                 continue;
             }
+            // The mixer owns the ramp now; drop any pending fade-in so the
+            // per-frame update() cannot fight the fade-out.
+            slot.fadeInDuration = 0.0f;
+            slot.fadeInElapsed = 0.0f;
             MIX_StopTrack(slot.track, MIX_TrackMSToFrames(slot.track, static_cast<Sint64>(fade * 1000.0)));
             slot.fadeOutRemaining = fade;
             faded = true;
@@ -476,7 +820,29 @@ namespace radiantwave::audio
         {
             TrackSlot &slot = slots_[i];
             if (!slot.track)
+            {
                 continue;
+            }
+
+            // A slot mid stop-fade belongs to the mixer: skip both the fade-in
+            // ramp and the active-gain pin so nothing drives its gain up while
+            // the mixer ramps it down (this also keeps a quit/pop fade clean).
+            if (slot.fadeOutRemaining > 0.0f)
+            {
+                slot.fadeOutRemaining -= dt;
+                if (slot.fadeOutRemaining <= 0.0f)
+                {
+                    slot.fadeOutRemaining = 0.0f;
+                    // Free the audio once the fade-out has finished; the track
+                    // object itself is reused.
+                    if (slot.audio)
+                    {
+                        MIX_DestroyAudio(slot.audio);
+                        slot.audio = nullptr;
+                    }
+                }
+                continue;
+            }
 
             if (slot.fadeInDuration > 0.0f)
             {
@@ -493,21 +859,12 @@ namespace radiantwave::audio
                 // Keep the active track at full per-track gain; the mixer gain
                 // carries the user's volume / mute state.
                 MIX_SetTrackGain(slot.track, 1.0f);
-            }
-
-            if (slot.fadeOutRemaining > 0.0f)
-            {
-                slot.fadeOutRemaining -= dt;
-                if (slot.fadeOutRemaining <= 0.0f)
+                // Self-heal: playback must continue indefinitely, so restart a
+                // track that stopped unexpectedly (there is no pause state and
+                // nothing else should legitimately stop the active track).
+                if (slot.audio && enabled_ && !MIX_TrackPlaying(slot.track))
                 {
-                    slot.fadeOutRemaining = 0.0f;
-                    // Free the audio once the fade-out has finished; the track
-                    // object itself is reused.
-                    if (slot.audio)
-                    {
-                        MIX_DestroyAudio(slot.audio);
-                        slot.audio = nullptr;
-                    }
+                    playTrackLooping(i);
                 }
             }
         }

src/audio/audio_manager.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "config/config_manager.h"
+#include <SDL3/SDL.h>
 #include <SDL3_mixer/SDL_mixer.h>
 #include <mutex>
 #include <string>
@@ -15,6 +16,7 @@ namespace radiantwave::audio {
 struct AudioDeviceItem {
     std::string raw_name;      // e.g. alsa_output.pci-0000_00_1f.3.analog-stereo
     std::string friendly_name; // e.g. "Built-In Speakers"
+    SDL_AudioDeviceID id = 0;  // SDL playback device id (0 = synthetic fallback)
 };
 
 // Maps raw technical audio device strings to user-friendly labels
@@ -51,7 +53,24 @@ public:
 
     // Audio device selection
     bool switchDevice(const std::string& raw_device_name);
+    bool switchDeviceById(SDL_AudioDeviceID id);
     std::string getCurrentDevice() const;
+    SDL_AudioDeviceID getCurrentDeviceId() const;
+
+    // Handle an SDL audio device event (SDL_EVENT_AUDIO_DEVICE_ADDED / REMOVED).
+    // Returns true if the active device was affected and the mixer was recreated.
+    bool handleDeviceEvent(const SDL_Event& event);
+
+    // Pure helper (no SDL audio open): find the playback device with the given
+    // SDL id, returning its raw name ("" when not found / id invalid). Exposed
+    // for tests; the real lookup is through getPlaybackDevices().
+    static std::string resolvePlaybackDeviceName(SDL_AudioDeviceID id);
+
+    // Builds the SDL_PropertiesID passed to MIX_PlayTrack() for tracks that
+    // loop forever (MIX_PROP_PLAY_LOOPS_NUMBER = -1). Exposed for tests; no
+    // mixer, track, or audio device is required. The caller owns the property
+    // set and must release it with SDL_DestroyProperties().
+    static SDL_PropertiesID createInfiniteLoopOptions();
 
     // Playback control
     bool playTrack(const std::string& wav_filename);
@@ -84,6 +103,21 @@ private:
     void startFadeIn(int slotIndex, float seconds);
     std::string displayNameFor(const std::string& wav_filename) const;
 
+    // Starts the track on the given slot with infinite looping. The track must
+    // already be loaded on the slot. Calling this on a playing/stopped/fading
+    // track restarts it (cancelling any in-flight stop-fade).
+    bool playTrackLooping(int slotIndex);
+
+    // Recreates the mixer on the given playback device id (0 = system default).
+    // Called with mutex_ held. Preserves playback state: whichever track was
+    // playing on the active slot is reloaded and resumed at full gain, an
+    // in-progress fade is restarted. The replacement mixer is opened before the
+    // current one is destroyed so SDL's device ids stay valid (destroy-first
+    // quits the whole audio subsystem and orphans the id being opened).
+    // Returns false on failure without touching the current mixer, so the
+    // existing output keeps playing.
+    bool recreateMixerOnDevice(SDL_AudioDeviceID targetId);
+
     config::ConfigManager* configManager_ = nullptr;
     db::DatabaseManager* db_ = nullptr;
 
@@ -91,6 +125,7 @@ private:
     bool enabled_ = true;
     int volume_ = 80; // 0 - 100
     std::string currentDevice_ = "";
+    SDL_AudioDeviceID currentDeviceId_ = SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK;
     std::string currentTrack_ = "";
 
     MIX_Mixer* mixer_ = nullptr;

src/audio_settings_page.cpp

@@ -77,7 +77,7 @@ void AudioSettingsPage::onPush(AppState& state) {
         } else if (modalState_ == ModalState::DeviceSelector) {
             if (!devices_.empty()) {
                 currentDeviceIndex_ = modalSelectedIndex_;
-                state_->audio.switchDevice(devices_[currentDeviceIndex_].raw_name);
+                applyDeviceSelection();
             }
             modalState_ = ModalState::None;
         } else if (modalState_ == ModalState::TrackSelector) {
@@ -156,7 +156,7 @@ void AudioSettingsPage::onResume(AppState& state) {
         } else if (modalState_ == ModalState::DeviceSelector) {
             if (!devices_.empty()) {
                 currentDeviceIndex_ = modalSelectedIndex_;
-                state_->audio.switchDevice(devices_[currentDeviceIndex_].raw_name);
+                applyDeviceSelection();
             }
             modalState_ = ModalState::None;
         } else if (modalState_ == ModalState::TrackSelector) {
@@ -280,6 +280,19 @@ void AudioSettingsPage::refreshDeviceAndTrackLists() {
     }
 }
 
+void AudioSettingsPage::applyDeviceSelection() {
+    if (!state_) return;
+    if (currentDeviceIndex_ < 0 || currentDeviceIndex_ >= static_cast<int>(devices_.size())) return;
+
+    const bool ok = state_->audio.switchDeviceById(devices_[currentDeviceIndex_].id);
+    if (ok) {
+        statusMessage_ = "Switched to " + devices_[currentDeviceIndex_].friendly_name;
+    } else {
+        statusMessage_ = "Device unavailable - kept the current output";
+    }
+    refreshDeviceAndTrackLists();
+}
+
 void AudioSettingsPage::enableDynamicAudio() {
     if (!state_) return;
     state_->config.update([](radiantwave::config::AppConfig& cfg) {
@@ -324,7 +337,7 @@ void AudioSettingsPage::handleEvent(const SDL_Event& event) {
                 if (modalState_ == ModalState::DeviceSelector) {
                     if (!devices_.empty()) {
                         currentDeviceIndex_ = modalSelectedIndex_;
-                        state_->audio.switchDevice(devices_[currentDeviceIndex_].raw_name);
+                        applyDeviceSelection();
                     }
                 } else if (modalState_ == ModalState::TrackSelector) {
                     if (modalSelectedIndex_ == 0) {
@@ -518,7 +531,7 @@ void AudioSettingsPage::render(SDL_Renderer* renderer) {
     }
 
     std::string devName = (currentDeviceIndex_ >= 0 && currentDeviceIndex_ < static_cast<int>(devices_.size()))
-        ? devices_[currentDeviceIndex_].friendly_name : "Built-In Speakers";
+        ? devices_[currentDeviceIndex_].friendly_name : "System Default";
     deviceText_.ensure(renderer, fontHeader_, "Device: " + devName, white);
     if (deviceText_.texture) {
         SDL_FRect dst{500.0f, currentY, deviceText_.width, deviceText_.height};

src/audio_settings_page.h

@@ -36,6 +36,10 @@ private:
     void enableDynamicAudio();
     void selectTrack(int trackIdx);
 
+    // Applies the currently selected device (devices_[currentDeviceIndex_]) via
+    // the audio manager and records user-facing success/failure feedback.
+    void applyDeviceSelection();
+
     AppState* state_ = nullptr;
     int selectedItem_ = 0; // 0 = Volume, 1 = Device, 2 = Track, 3 = Status, 4 = Back
 

src/home.cpp

@@ -180,6 +180,16 @@ void Home::render(SDL_Renderer *renderer)
         SDL_RenderFillRect(renderer, &line);
     }
 
+    // Large bold reminder to connect WiFi, drawn below the menu while no
+    // network is joined (refreshed every 5s in update()).
+    if (wifiNote_.texture && ssid_.empty())
+    {
+        float noteX = (fw - wifiNote_.width) / 2.0f;
+        float noteY = settingsY_ + settings_.height + 40.0f;
+        SDL_FRect noteDst{noteX, noteY, wifiNote_.width, wifiNote_.height};
+        SDL_RenderTexture(renderer, wifiNote_.texture, nullptr, &noteDst);
+    }
+
     // Bottom-right status footer (20pt, aligned to a virtual rectangle:
     // names left-aligned at the rect's left edge, values right-aligned at
     // the rect's right edge; the longest name's colon sits 4 spaces from its
@@ -281,10 +291,10 @@ void Home::render(SDL_Renderer *renderer)
         fourSpaces.destroy();
 
         const float margin = 20.0f;
-        float rectRight = fw - margin;
+        float rectRight = fw - margin - 50.0f;
         float rectLeft = rectRight - (maxNameW + spaceW4 + maxValueW);
 
-        float lineY = fh - margin;
+        float lineY = fh - margin - 50.0f;
         const float lineGap = 6.0f;
         for (size_t i = footerNames_.size(); i-- > 0;)
         {
@@ -352,6 +362,15 @@ void Home::createTextures(AppState &state)
 
     TTF_CloseFont(font);
 
+    font = TTF_OpenFont("assets/fonts/Roboto-Regular.ttf", 48);
+    if (font)
+    {
+        TTF_SetFontStyle(font, TTF_STYLE_BOLD);
+        wifiNote_ = renderText(state.renderer, font, "Please connect to WiFi", white);
+        TTF_SetFontStyle(font, TTF_STYLE_NORMAL);
+        TTF_CloseFont(font);
+    }
+
     SDL_Surface *bgSurface = IMG_Load("assets/images/RWT-Circular-Color-ForOnDark-NoText.png");
     if (bgSurface)
     {
@@ -410,6 +429,11 @@ void Home::destroyTextures()
         SDL_DestroyTexture(settings_.texture);
         settings_.texture = nullptr;
     }
+    if (wifiNote_.texture)
+    {
+        SDL_DestroyTexture(wifiNote_.texture);
+        wifiNote_.texture = nullptr;
+    }
     for (auto &t : footerNames_)
         t.destroy();
     for (auto &t : footerValues_)

src/home.h

@@ -34,6 +34,7 @@ private:
     TextLine play_;
     TextLine settings_;
     TextLine bg_;
+    TextLine wifiNote_;
 
     AppState* state_ = nullptr;
     float playY_ = 0;

src/logical_size.h

@@ -4,14 +4,48 @@
 
 namespace radiantwave {
 
-inline void getLayoutSize(SDL_Renderer* renderer, int* w, int* h)
+// Design resolution every page lays out against. The renderer's logical
+// presentation (LETTERBOX) scales this fixed space onto whatever
+// window/backbuffer the display actually provides.
+inline constexpr int kDesignWidth = 1920;
+inline constexpr int kDesignHeight = 1080;
+
+// Returns the size pages should lay out against: the renderer's logical size
+// when presentation is active, otherwise the real window size. The output
+// params are always written — design constants are the last-resort fallback.
+inline void getLayoutSize(SDL_Renderer *renderer, int *w, int *h)
 {
-    SDL_RendererLogicalPresentation mode = SDL_LOGICAL_PRESENTATION_DISABLED;
-    if (!SDL_GetRenderLogicalPresentation(renderer, w, h, &mode) ||
-        mode == SDL_LOGICAL_PRESENTATION_DISABLED || *w <= 0 || *h <= 0)
-    {
-        SDL_GetWindowSize(SDL_GetRenderWindow(renderer), w, h);
-    }
+	if (!w || !h)
+		return;
+	*w = kDesignWidth;
+	*h = kDesignHeight;
+
+	if (!renderer)
+		return;
+
+	SDL_RendererLogicalPresentation mode = SDL_LOGICAL_PRESENTATION_DISABLED;
+	int logicalW = 0;
+	int logicalH = 0;
+	if (SDL_GetRenderLogicalPresentation(renderer, &logicalW, &logicalH,
+										 &mode) &&
+		mode != SDL_LOGICAL_PRESENTATION_DISABLED && logicalW > 0 &&
+		logicalH > 0) {
+		*w = logicalW;
+		*h = logicalH;
+		return;
+	}
+
+	SDL_Window *window = SDL_GetRenderWindow(renderer);
+	if (!window)
+		return;
+
+	int windowW = 0;
+	int windowH = 0;
+	SDL_GetWindowSize(window, &windowW, &windowH);
+	if (windowW > 0 && windowH > 0) {
+		*w = windowW;
+		*h = windowH;
+	}
 }
 
 } // namespace radiantwave

src/main.cpp

@@ -4,8 +4,10 @@
 
 #include "app_state.h"
 #include "home.h"
+#include "logical_size.h"
 #include "logger/logger.h"
 #include "provisioning.h"
+#include "scroller_page.h"
 
 namespace {
 // How long audio fades out before the app tears down on quit. Only applied
@@ -32,11 +34,26 @@ SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv[]) {
 
 	auto *state = new AppState{};
 
-	// SDL_WINDOW_FULLSCREEN fills the desktop's native resolution, so the
-	// compositor never has to scale the moving scroller (scaling moving text
-	// causes flicker).
-	state->window =
-		SDL_CreateWindow("RadiantWave", 1920, 1080, SDL_WINDOW_FULLSCREEN);
+	// Size the fullscreen window from the display's actual mode so the very
+	// first buffer commit already matches what the compositor scanouts 1:1.
+	// Requesting a hardcoded size left the backbuffer at that size on
+	// displays running a different mode, and frames reached the panel
+	// unscaled (quarter-size on 4K, cropped on smaller panels).
+	const SDL_DisplayMode *displayMode =
+		SDL_GetCurrentDisplayMode(SDL_GetPrimaryDisplay());
+	int windowWidth =
+		(displayMode && displayMode->w > 0) ? displayMode->w
+											: radiantwave::kDesignWidth;
+	int windowHeight =
+		(displayMode && displayMode->h > 0) ? displayMode->h
+											: radiantwave::kDesignHeight;
+
+	// Borderless desktop fullscreen: the compositor never has to scale the
+	// moving scroller (scaling moving text causes flicker). Deliberately no
+	// SDL_WINDOW_HIGH_PIXEL_DENSITY — kiosk panels are not HiDPI, so keeping
+	// the pixel buffer equal to the display mode keeps scanout 1:1.
+	state->window = SDL_CreateWindow("RadiantWave", windowWidth, windowHeight,
+									 SDL_WINDOW_FULLSCREEN);
 	if (!state->window) {
 		SDL_Log("Failed to create window: %s", SDL_GetError());
 		delete state;
@@ -59,16 +76,38 @@ SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv[]) {
 							std::string(SDL_GetError()) + ")");
 	}
 
-	// Lock the renderer to a 1920x1080 logical coordinate space.  All page
-	// layout code already targets this resolution, so everything renders at
-	// the correct size on any display — the GPU scales to native pixels.
-	if (!SDL_SetRenderLogicalPresentation(state->renderer, 1920, 1080,
-										  SDL_LOGICAL_PRESENTATION_STRETCH)) {
+	// All page layout targets the fixed design resolution; LETTERBOX maps it
+	// onto the real window with aspect preserved (bars on non-16:9 panels).
+	if (!SDL_SetRenderLogicalPresentation(state->renderer,
+										  radiantwave::kDesignWidth,
+										  radiantwave::kDesignHeight,
+										  SDL_LOGICAL_PRESENTATION_LETTERBOX)) {
 		radiantwave::logger::Logger::instance().warning(
 			"Graphics", "Could not set logical render size; layout may be "
 						"wrong on HiDPI displays");
 	}
 
+	{
+		// Record how the requested mode, window, pixel buffer, and render
+		// output actually compare — this is the evidence trail for
+		// display-scaling problems on field units.
+		int windowW = 0, windowH = 0;
+		SDL_GetWindowSize(state->window, &windowW, &windowH);
+		int pixelW = 0, pixelH = 0;
+		SDL_GetWindowSizeInPixels(state->window, &pixelW, &pixelH);
+		int outputW = 0, outputH = 0;
+		SDL_GetRenderOutputSize(state->renderer, &outputW, &outputH);
+		radiantwave::logger::Logger::instance().info(
+			"Graphics",
+			"Requested " + std::to_string(windowWidth) + "x" +
+				std::to_string(windowHeight) + ", window " +
+				std::to_string(windowW) + "x" + std::to_string(windowH) +
+				", pixels " + std::to_string(pixelW) + "x" +
+				std::to_string(pixelH) + ", render output " +
+				std::to_string(outputW) + "x" + std::to_string(outputH) +
+				", presentation LETTERBOX");
+	}
+
 	SDL_HideCursor();
 
 	// Initialize configuration, database, and network manager
@@ -157,6 +196,30 @@ SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event) {
 		state.quitRequested = true;
 	}
 
+	if (event->type == SDL_EVENT_AUDIO_DEVICE_ADDED ||
+		event->type == SDL_EVENT_AUDIO_DEVICE_REMOVED) {
+		// Route device hotplug to the audio manager so an active device that
+		// disappears is failed over to the system default automatically.
+		state.audio.handleDeviceEvent(*event);
+	}
+
+	if (event->type == SDL_EVENT_WINDOW_RESIZED) {
+		radiantwave::logger::Logger::instance().info(
+			"Graphics", "Window resized to " +
+							std::to_string(event->window.data1) + "x" +
+							std::to_string(event->window.data2));
+		// Logical presentation persists across resizes; re-apply defensively
+		// in case backend state was reset underneath us.  Skip while the
+		// scroller is active — it owns its own presentation (NONE, full
+		// window) and restores LETTERBOX in onPop.
+		if (!dynamic_cast<ScrollerPage *>(state.pages.current())) {
+			SDL_SetRenderLogicalPresentation(state.renderer,
+											 radiantwave::kDesignWidth,
+											 radiantwave::kDesignHeight,
+											 SDL_LOGICAL_PRESENTATION_LETTERBOX);
+		}
+	}
+
 	if (!state.keybinds.handleEvent(*event)) {
 		state.pages.handleEvent(*event);
 	}

src/proclamation_options_page.cpp

@@ -198,7 +198,7 @@ void ProclamationOptionsPage::rebuildItems()
                 FlatItem::Type::SubCategory,
                 std::to_string(sub.id),
                 sub.name,
-                1, false, false, false,
+                1, true, false, false,
             });
 
             for (const auto& p : proclamations_) {
@@ -268,7 +268,7 @@ void ProclamationOptionsPage::rebuildVisible()
             parentVisible = true; // the always-on top-level proclamation
         } else if (currentRoot >= 0 && items_[currentRoot].expanded) {
             parentVisible = (item.depth == 1) ||
-                            (item.depth == 2 && currentSub >= 0 && items_[currentSub].expanded);
+                            (item.depth == 2 && currentSub >= 0);
         }
         if (parentVisible) visible_.push_back(i);
     }
@@ -283,7 +283,7 @@ void ProclamationOptionsPage::toggleItem()
     if (visible_.empty()) return;
     FlatItem& item = items_[visible_[highlightIndex_]];
 
-    if (item.type == FlatItem::Type::RootCategory || item.type == FlatItem::Type::SubCategory) {
+    if (item.type == FlatItem::Type::RootCategory) {
         item.expanded = !item.expanded;
         rebuildVisible();
         return;
@@ -388,7 +388,7 @@ void ProclamationOptionsPage::collapseCurrent()
 {
     if (visible_.empty()) return;
     FlatItem& item = items_[visible_[highlightIndex_]];
-    if (item.type == FlatItem::Type::RootCategory || item.type == FlatItem::Type::SubCategory) {
+    if (item.type == FlatItem::Type::RootCategory) {
         if (item.expanded) {
             item.expanded = false;
             rebuildVisible();
@@ -400,7 +400,7 @@ void ProclamationOptionsPage::expandCurrent()
 {
     if (visible_.empty()) return;
     FlatItem& item = items_[visible_[highlightIndex_]];
-    if (item.type == FlatItem::Type::RootCategory || item.type == FlatItem::Type::SubCategory) {
+    if (item.type == FlatItem::Type::RootCategory) {
         if (!item.expanded) {
             item.expanded = true;
             rebuildVisible();
@@ -526,8 +526,7 @@ void ProclamationOptionsPage::handleEvent(const SDL_Event& event)
         if (searchActive_) return;
         if (!visible_.empty()) {
             const FlatItem& item = items_[visible_[highlightIndex_]];
-            if ((item.type == FlatItem::Type::RootCategory ||
-                 item.type == FlatItem::Type::SubCategory) && item.expanded) {
+            if (item.type == FlatItem::Type::RootCategory && item.expanded) {
                 collapseCurrent();
             } else {
                 moveToParent();
@@ -655,14 +654,18 @@ void ProclamationOptionsPage::render(SDL_Renderer* renderer)
                     SDL_RenderTexture(renderer, emptyHintText_.texture, nullptr, &dst);
                 }
             } else {
-                // Compute the widest row so the block can be centered.
+                // Stable width: compute from every result so the list doesn't shift.
                 float maxTotalWidth = 0.0f;
+                for (const auto& r : searchResults_) {
+                    int w = 0, h = 0;
+                    TTF_GetStringSize(fontItem_, proclamations_[r].title.c_str(), 0, &w, &h);
+                    maxTotalWidth = std::max(maxTotalWidth, static_cast<float>(w));
+                }
+
                 std::vector<float> textWidths(static_cast<size_t>(listSize));
                 for (int i = scrollOffset_; i < scrollOffset_ + visibleCount_ && i < listSize; ++i) {
-                    const std::string& label = proclamations_[searchResults_[i]].title;
                     int w = 0, h = 0;
-                    TTF_GetStringSize(fontItem_, label.c_str(), 0, &w, &h);
-                    maxTotalWidth = std::max(maxTotalWidth, static_cast<float>(w));
+                    TTF_GetStringSize(fontItem_, proclamations_[searchResults_[i]].title.c_str(), 0, &w, &h);
                     textWidths[i] = static_cast<float>(w);
                 }
                 float sharedX = (fw - maxTotalWidth) / 2.0f;
@@ -695,19 +698,29 @@ void ProclamationOptionsPage::render(SDL_Renderer* renderer)
             }
         } else {
             // --- Browse tree ---
-            // Compute the widest row so the block can be centered.
+            // Stable width: compute from every item so the list doesn't
+            // shift left/right when groups expand or collapse.
             float maxTotalWidth = 0.0f;
-            std::vector<float> textWidths(visible_.size());
-            for (int i = scrollOffset_; i < scrollOffset_ + visibleCount_ && i < static_cast<int>(visible_.size()); ++i) {
-                const FlatItem& item = items_[visible_[i]];
+            for (const auto& item : items_) {
                 std::string label = item.label;
-                if (item.type == FlatItem::Type::RootCategory || item.type == FlatItem::Type::SubCategory) {
+                if (item.type == FlatItem::Type::RootCategory) {
                     label = (item.expanded ? "[-] " : "[+] ") + label;
                 }
                 int w = 0, h = 0;
                 TTF_GetStringSize(fontItem_, label.c_str(), 0, &w, &h);
                 float total = item.depth * indent + static_cast<float>(w);
                 maxTotalWidth = std::max(maxTotalWidth, total);
+            }
+
+            std::vector<float> textWidths(visible_.size());
+            for (int i = scrollOffset_; i < scrollOffset_ + visibleCount_ && i < static_cast<int>(visible_.size()); ++i) {
+                const FlatItem& item = items_[visible_[i]];
+                std::string label = item.label;
+                if (item.type == FlatItem::Type::RootCategory) {
+                    label = (item.expanded ? "[-] " : "[+] ") + label;
+                }
+                int w = 0, h = 0;
+                TTF_GetStringSize(fontItem_, label.c_str(), 0, &w, &h);
                 textWidths[i] = static_cast<float>(w);
             }
 
@@ -721,7 +734,7 @@ void ProclamationOptionsPage::render(SDL_Renderer* renderer)
                 float y = listTop + rowIndex * rowPitch;
 
                 std::string label = item.label;
-                if (item.type == FlatItem::Type::RootCategory || item.type == FlatItem::Type::SubCategory) {
+                if (item.type == FlatItem::Type::RootCategory) {
                     label = (item.expanded ? "[-] " : "[+] ") + label;
                 }
 

src/scroller_page.h

@@ -115,4 +115,8 @@ private:
     float velocityDelay_ = 2.5f;
     int velocityState_ = 0;
     float velocityTimer_ = 0.0f;
+
+    int savedLogicalW_ = 0;
+    int savedLogicalH_ = 0;
+    SDL_RendererLogicalPresentation savedMode_ = SDL_LOGICAL_PRESENTATION_DISABLED;
 };

src/settings.cpp

@@ -19,18 +19,18 @@ namespace
 {
 
     constexpr int MENU_ITEM_COUNT = 9;
-    // 0 = WiFi Setup, 1 = Audio Options, 2 = Time Zone Setup, 3 = Proclamations,
-    // 4 = Email Address, 5 = License Key, 6 = Date Format,
-    // 7 = View System Logs, 8 = Back
+    // 0 = Proclamations, 1 = Audio Options, 2 = Email Address, 3 = License Key,
+    // 4 = WiFi Setup, 5 = Time Zone Setup, 6 = Date Format,
+    // 7 = System Logs, 8 = Back
     constexpr const char *MENU_LABELS[MENU_ITEM_COUNT] = {
-        "WiFi Setup",
-        "Audio Options",
-        "Time Zone Setup",
         "Proclamations",
+        "Audio Options",
         "Email Address",
         "License Key",
+        "WiFi Setup",
+        "Time Zone Setup",
         "Date Format",
-        "View System Logs",
+        "System Logs",
         "Back to Home",
     };
 
@@ -78,15 +78,6 @@ void Settings::handleEvent(const SDL_Event &event)
         switch (selectedItem_)
         {
         case 0:
-            state_->pages.push(*state_, std::make_unique<WiFiSetupPage>());
-            break;
-        case 1:
-            state_->pages.push(*state_, std::make_unique<AudioSettingsPage>());
-            break;
-        case 2:
-            state_->pages.push(*state_, std::make_unique<TimeZonePage>());
-            break;
-        case 3:
             // The Proclamation list is license-gated like Play.
             if (state_->licenseTracker.isValid())
             {
@@ -97,12 +88,21 @@ void Settings::handleEvent(const SDL_Event &event)
                 state_->pages.push(*state_, std::make_unique<LicenseBlockedPage>());
             }
             break;
-        case 4:
+        case 1:
+            state_->pages.push(*state_, std::make_unique<AudioSettingsPage>());
+            break;
+        case 2:
             state_->pages.push(*state_, std::make_unique<EmailAddressPage>());
             break;
-        case 5:
+        case 3:
             state_->pages.push(*state_, std::make_unique<LicenseKeyPage>());
             break;
+        case 4:
+            state_->pages.push(*state_, std::make_unique<WiFiSetupPage>());
+            break;
+        case 5:
+            state_->pages.push(*state_, std::make_unique<TimeZonePage>());
+            break;
         case 6:
             state_->pages.push(*state_, std::make_unique<DateFormatPage>());
             break;

tests/test_audio.cpp

@@ -8,9 +8,34 @@ TEST(AudioTest, FriendlyDeviceNameMapping) {
     EXPECT_EQ(mapToFriendlyDeviceName("AMD Radeon HD Audio Controller HDMI"), "TV / HDMI Monitor");
     EXPECT_EQ(mapToFriendlyDeviceName("USB Audio Headset Dongle"), "USB Audio Device");
     EXPECT_EQ(mapToFriendlyDeviceName("bluez_sink.00_11_22_33_44_55"), "Bluetooth Audio");
+    EXPECT_EQ(mapToFriendlyDeviceName("Virtual Speaker"), "Built-In Speakers");
     EXPECT_EQ(mapToFriendlyDeviceName(""), "Default Audio Output");
 }
 
+TEST(AudioTest, ResolvePlaybackDeviceNameHandlesSentinels) {
+    // The sentinel and 0 mean "system default" and never correspond to a real
+    // enumerated playback device, so they resolve to the empty (default) name.
+    EXPECT_EQ(AudioManager::resolvePlaybackDeviceName(0), "");
+    EXPECT_EQ(AudioManager::resolvePlaybackDeviceName(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK), "");
+}
+
+TEST(AudioTest, GetPlaybackDevicesFallsBackWithIdZeroWhenNone) {
+    AudioManager am;
+    auto devices = am.getPlaybackDevices();
+    // Headless hosts (CI) expose no playback devices, so expect the synthetic
+    // fallback entry that carries id 0 (the "system default" marker).
+    if (devices.empty()) {
+        // No devices and no fallback would be a contract violation.
+        FAIL() << "getPlaybackDevices() returned an empty list without fallback";
+    }
+    for (const auto& d : devices) {
+        if (d.raw_name.empty()) {
+            EXPECT_EQ(d.id, 0u);
+            EXPECT_EQ(d.friendly_name, "System Default");
+        }
+    }
+}
+
 TEST(AudioTest, AudioManagerVolumeClamping) {
     radiantwave::config::ConfigManager config;
     std::string temp_path = (std::filesystem::temp_directory_path() / "test_rw_audio_cfg.yaml").string();
@@ -36,3 +61,14 @@ TEST(AudioTest, AudioManagerVolumeClamping) {
     am.shutdown();
     std::filesystem::remove(temp_path);
 }
+
+TEST(AudioTest, PlayOptionsLoopInfinite) {
+    // Regression: MIX_PlayTrack() must not default to a single pass. Tracks
+    // have to loop forever so playback never runs out mid-scroll; a track that
+    // stops (rather than attenuates) also can't be revived by raising app
+    // volume. Assert the options request infinite looping (-1).
+    SDL_PropertiesID props = AudioManager::createInfiniteLoopOptions();
+    ASSERT_NE(props, 0u);
+    EXPECT_EQ(SDL_GetNumberProperty(props, MIX_PROP_PLAY_LOOPS_NUMBER, 0), -1);
+    SDL_DestroyProperties(props);
+}

tests/test_scroller_streams.cpp

@@ -94,6 +94,62 @@ TEST(ScrollerStreamsTest, InterleavesSelectedWithDefault)
     EXPECT_EQ(streams[3].audioFilename, "OriginalAudio.wav");
 }
 
+TEST(ScrollerStreamsTest, InterleavedListCyclesBackToFirstSelected)
+{
+    // Three selected proclamations: the built list must be
+    // [S1, Default, S2, Default, S3, Default]. ScrollerPage advances through
+    // this list with a modulo, so once the trailing default finishes the cycle
+    // restarts at the FIRST selected proclamation — the "always on" default
+    // must never accumulate or take over the queue.
+    ProclamationRecord b;
+    b.id = "B";
+    b.title = "B";
+    b.content = "bbbb";
+    b.selected = true;
+    b.solfeggio_frequency_id = 2;
+
+    ProclamationRecord c;
+    c.id = "C";
+    c.title = "C";
+    c.content = "cccc";
+    c.selected = true;
+    c.solfeggio_frequency_id = 3;
+
+    ProclamationRecord d;
+    d.id = "D";
+    d.title = "D";
+    d.content = "dddd";
+    d.selected = true;
+    d.solfeggio_frequency_id = 4;
+
+    ProclamationRecord def;
+    def.id = kDefaultId;
+    def.title = "Default";
+    def.content = "dddddddddd";
+    def.selected = true;
+    def.solfeggio_frequency_id = 5;
+
+    auto streams = buildStreams({b, def, c, d}, {}, palette(), {}, kDefaultId);
+
+    ASSERT_EQ(streams.size(), 6u);
+    EXPECT_EQ(streams[0].name, "B");
+    EXPECT_EQ(streams[1].name, "Default");
+    EXPECT_EQ(streams[2].name, "C");
+    EXPECT_EQ(streams[3].name, "Default");
+    EXPECT_EQ(streams[4].name, "D");
+    EXPECT_EQ(streams[5].name, "Default");
+
+    // Every default copy is independent playback state (fresh counters), so a
+    // copy finishing its passes advances to the next stream rather than
+    // restarting "the default" forever.
+    for (size_t i = 1; i < streams.size(); i += 2) {
+        EXPECT_EQ(streams[i].name, "Default");
+        EXPECT_EQ(streams[i].completed, 0) << "default copy " << i;
+        EXPECT_EQ(streams[i].wordsPlaced, 0) << "default copy " << i;
+        EXPECT_EQ(streams[i].repeat, kDefaultRepeatCount) << "default copy " << i;
+    }
+}
+
 TEST(ScrollerStreamsTest, DefaultOnlyWhenNothingSelected)
 {
     ProclamationRecord p1;