From 314fedb9dbd854b5a02015491f0fe9d66b0aa0e9 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 19:17:58 +0100
Subject: [PATCH 01/25] feat: add version source and package installer seams
 for the version switcher

---
 src/php/Settings/Package_Installer.php        |  27 +++
 .../Settings/Upgrader_Package_Installer.php   | 120 +++++++++++++
 src/php/Settings/Version_Source.php           | 110 ++++++++++++
 .../Settings/WordPress_Org_Version_Source.php | 157 ++++++++++++++++++
 4 files changed, 414 insertions(+)
 create mode 100644 src/php/Settings/Package_Installer.php
 create mode 100644 src/php/Settings/Upgrader_Package_Installer.php
 create mode 100644 src/php/Settings/Version_Source.php
 create mode 100644 src/php/Settings/WordPress_Org_Version_Source.php

diff --git a/src/php/Settings/Package_Installer.php b/src/php/Settings/Package_Installer.php
new file mode 100644
index 000000000..197f33828
--- /dev/null
+++ b/src/php/Settings/Package_Installer.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace Code_Snippets\Settings;
+
+use WP_Error;
+
+/**
+ * Installs a plugin package over the currently installed plugin.
+ *
+ * Register an implementation on the `code_snippets_package_installer` filter to
+ * replace how the version switcher writes a package to disk.
+ *
+ * @package    Code_Snippets
+ * @subpackage Settings
+ */
+interface Package_Installer {
+
+	/**
+	 * Install a plugin package.
+	 *
+	 * @param string $package Local path to a package, or a download URL.
+	 *
+	 * @return array{version: string}|WP_Error Version installed, or '' when the
+	 *                                         installer cannot determine it.
+	 */
+	public function install( string $package );
+}
diff --git a/src/php/Settings/Upgrader_Package_Installer.php b/src/php/Settings/Upgrader_Package_Installer.php
new file mode 100644
index 000000000..974a44837
--- /dev/null
+++ b/src/php/Settings/Upgrader_Package_Installer.php
@@ -0,0 +1,120 @@
+<?php
+
+namespace Code_Snippets\Settings;
+
+use Plugin_Upgrader;
+use WP_Ajax_Upgrader_Skin;
+use WP_Error;
+use WP_Upgrader_Skin;
+
+/**
+ * Installs a package with WordPress's own plugin upgrader.
+ *
+ * This is the switcher's default installer. `Plugin_Upgrader::install()` accepts
+ * a local path as readily as a URL: `WP_Upgrader::download_package()` returns
+ * its argument unchanged when it is not an http(s) or FTP URL and the file
+ * exists.
+ *
+ * @package    Code_Snippets
+ * @subpackage Settings
+ */
+class Upgrader_Package_Installer implements Package_Installer {
+
+	/**
+	 * Install a plugin package.
+	 *
+	 * @param string $package Local path to a package, or a download URL.
+	 *
+	 * @return array{version: string}|WP_Error
+	 */
+	public function install( string $package ) {
+		if ( ! function_exists( 'wp_update_plugins' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/update.php';
+		}
+		if ( ! function_exists( 'show_message' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/misc.php';
+		}
+		if ( ! class_exists( 'Plugin_Upgrader' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/class-wp-upgrader.php';
+		}
+
+		$update_handler = new WP_Ajax_Upgrader_Skin();
+		$upgrader = new Plugin_Upgrader( $update_handler );
+
+		$result = $upgrader->install(
+			$package,
+			[
+				'overwrite_package'  => true,
+				'clear_update_cache' => true,
+			]
+		);
+
+		if ( is_wp_error( $result ) ) {
+			return $result;
+		}
+
+		if ( ! $result ) {
+			$messages = $this->extract_handler_messages( $update_handler, $upgrader );
+
+			return new WP_Error(
+				'package_install_failed',
+				$messages
+					? wp_trim_words( wp_strip_all_tags( $messages ), 40 )
+					: __( 'The package could not be installed.', 'code-snippets' )
+			);
+		}
+
+		// The upgrader reports nothing about what it wrote, so the caller falls
+		// back to the version it asked for.
+		return [ 'version' => '' ];
+	}
+
+	/**
+	 * Extract error messages from an upgrade handler.
+	 *
+	 * @param WP_Upgrader_Skin|null $update_handler Update handler.
+	 * @param Plugin_Upgrader|null  $upgrader       Plugin upgrader.
+	 *
+	 * @return string
+	 *
+	 * phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_print_r
+	 */
+	public function extract_handler_messages( ?WP_Upgrader_Skin $update_handler, ?Plugin_Upgrader $upgrader ): string {
+		$handler_messages = '';
+
+		if ( isset( $update_handler ) ) {
+			if ( method_exists( $update_handler, 'get_errors' ) ) {
+				$errs = $update_handler->get_errors();
+				if ( $errs instanceof WP_Error && $errs->has_errors() ) {
+					$handler_messages .= implode( "\n", $errs->get_error_messages() );
+				}
+			}
+			if ( method_exists( $update_handler, 'get_error_messages' ) ) {
+				$em = $update_handler->get_error_messages();
+				if ( $em ) {
+					$handler_messages .= "\n" . $em;
+				}
+			}
+			if ( method_exists( $update_handler, 'get_upgrade_messages' ) ) {
+				$upgrade_msgs = $update_handler->get_upgrade_messages();
+				if ( is_array( $upgrade_msgs ) ) {
+					$handler_messages .= "\n" . implode( "\n", $upgrade_msgs );
+				} elseif ( $upgrade_msgs ) {
+					$handler_messages .= "\n" . $upgrade_msgs;
+				}
+			}
+		}
+
+		if ( empty( $handler_messages ) && isset( $upgrader->result ) ) {
+			if ( is_wp_error( $upgrader->result ) ) {
+				$handler_messages = implode( "\n", $upgrader->result->get_error_messages() );
+			} else {
+				$handler_messages = is_scalar( $upgrader->result )
+					? (string) $upgrader->result
+					: print_r( $upgrader->result, true );
+			}
+		}
+
+		return trim( $handler_messages );
+	}
+}
diff --git a/src/php/Settings/Version_Source.php b/src/php/Settings/Version_Source.php
new file mode 100644
index 000000000..62c0bb4a4
--- /dev/null
+++ b/src/php/Settings/Version_Source.php
@@ -0,0 +1,110 @@
+<?php
+
+namespace Code_Snippets\Settings;
+
+use WP_Error;
+
+/**
+ * Supplies the plugin versions the version switcher may install, and the
+ * packages for them.
+ *
+ * The edition decides where versions come from: the free plugin lists builds
+ * published on WordPress.org, while Code Snippets Pro lists the builds its
+ * cloud account is licensed to install. Everything else about the switcher —
+ * caching, the progress marker, capability and nonce checks, and rendering — is
+ * shared, so an implementation of this interface is the only thing an edition
+ * needs to replace.
+ *
+ * Register an implementation on the `code_snippets_version_source` filter.
+ *
+ * @package    Code_Snippets
+ * @subpackage Settings
+ */
+interface Version_Source {
+
+	/**
+	 * Transient key under which this source's catalogue is cached.
+	 *
+	 * Every source must use its own key. A site that changes edition, or whose
+	 * source is replaced, must not go on serving a catalogue the previous source
+	 * cached — that would offer packages the new source cannot install.
+	 *
+	 * @return string
+	 */
+	public function get_cache_key(): string;
+
+	/**
+	 * Determine whether this source can currently be reached.
+	 *
+	 * @return bool
+	 */
+	public function is_available(): bool;
+
+	/**
+	 * Explain an unavailable source to the user, and offer a way to resolve it.
+	 *
+	 * Only consulted when is_available() is false. An empty `action_url` renders
+	 * the message with no call to action.
+	 *
+	 * @return array{message: string, action_url: string, action_label: string}
+	 */
+	public function get_unavailable_notice(): array;
+
+	/**
+	 * Describe where versions are fetched from, shown under the refresh button.
+	 *
+	 * @return string
+	 */
+	public function get_refresh_description(): string;
+
+	/**
+	 * Retrieve the versions available to install, ordered newest first.
+	 *
+	 * Each entry must carry a `version` key, and may carry `release_mode`
+	 * (`latest`, `released`, `beta` or `rc`), `tested_up_to` and `is_latest`,
+	 * which the switcher renders when present. A source may include any further
+	 * keys it needs; the entry is handed back to fetch_package() unchanged.
+	 *
+	 * An empty version list is a valid catalogue, not an error. `floor` names the
+	 * oldest installable version, or is empty when there is no such limit.
+	 *
+	 * @return array{versions: array<int, array<string, mixed>>, floor: string}|WP_Error
+	 */
+	public function fetch_catalogue();
+
+	/**
+	 * Explain why the catalogue stops at the floor it reported.
+	 *
+	 * Only consulted when fetch_catalogue() returned a non-empty `floor`.
+	 *
+	 * @param string $floor Oldest installable version.
+	 *
+	 * @return string
+	 */
+	public function get_floor_notice( string $floor ): string;
+
+	/**
+	 * Obtain the package for a version.
+	 *
+	 * `package` is either a local file path or a download URL — the installer
+	 * accepts both. Set `cleanup` when the switcher should delete the package
+	 * once the install has finished, as it must for a temporary download.
+	 *
+	 * @param array<string, mixed> $version_info Catalogue entry for the version.
+	 *
+	 * @return array{package: string, cleanup: bool}|WP_Error
+	 */
+	public function fetch_package( array $version_info );
+
+	/**
+	 * Record a completed switch with whatever service tracks this site.
+	 *
+	 * Best-effort: an implementation must never turn a successful switch into a
+	 * reported failure.
+	 *
+	 * @param string $version Version now installed.
+	 *
+	 * @return void
+	 */
+	public function report_installed_version( string $version ): void;
+}
diff --git a/src/php/Settings/WordPress_Org_Version_Source.php b/src/php/Settings/WordPress_Org_Version_Source.php
new file mode 100644
index 000000000..f6351c1e9
--- /dev/null
+++ b/src/php/Settings/WordPress_Org_Version_Source.php
@@ -0,0 +1,157 @@
+<?php
+
+namespace Code_Snippets\Settings;
+
+use WP_Error;
+
+/**
+ * Lists the plugin builds published on WordPress.org.
+ *
+ * This is the switcher's default source. It needs no credentials and is always
+ * available, so the unavailable notice it returns is never rendered.
+ *
+ * @package    Code_Snippets
+ * @subpackage Settings
+ */
+class WordPress_Org_Version_Source implements Version_Source {
+
+	/**
+	 * Endpoint listing the released versions of a plugin.
+	 */
+	private const API_ENDPOINT = 'https://api.wordpress.org/plugins/info/1.2/?action=plugin_information&slug=code-snippets';
+
+	/**
+	 * Transient key under which this source's catalogue is cached.
+	 *
+	 * @return string
+	 */
+	public function get_cache_key(): string {
+		return 'code_snippets_available_versions';
+	}
+
+	/**
+	 * Determine whether this source can currently be reached.
+	 *
+	 * @return bool
+	 */
+	public function is_available(): bool {
+		return true;
+	}
+
+	/**
+	 * Explain an unavailable source to the user.
+	 *
+	 * @return array{message: string, action_url: string, action_label: string}
+	 */
+	public function get_unavailable_notice(): array {
+		return [
+			'message'      => __( 'The list of available versions could not be retrieved.', 'code-snippets' ),
+			'action_url'   => '',
+			'action_label' => '',
+		];
+	}
+
+	/**
+	 * Describe where versions are fetched from.
+	 *
+	 * @return string
+	 */
+	public function get_refresh_description(): string {
+		return __( 'Check for the latest available plugin versions from WordPress.org.', 'code-snippets' );
+	}
+
+	/**
+	 * Retrieve the versions available to install, ordered newest first.
+	 *
+	 * @return array{versions: array<int, array<string, mixed>>, floor: string}|WP_Error
+	 */
+	public function fetch_catalogue() {
+		$response = wp_remote_get( self::API_ENDPOINT );
+
+		if ( is_wp_error( $response ) ) {
+			return new WP_Error(
+				'version_source_request_error',
+				__( 'Failed to retrieve the list of available versions from WordPress.org.', 'code-snippets' )
+			);
+		}
+
+		$data = json_decode( wp_remote_retrieve_body( $response ), true );
+
+		if ( ! is_array( $data ) || ! isset( $data['versions'] ) || ! is_array( $data['versions'] ) ) {
+			return new WP_Error(
+				'version_source_response_error',
+				__( 'Did not receive a valid version list from WordPress.org.', 'code-snippets' )
+			);
+		}
+
+		$versions = [];
+
+		foreach ( $data['versions'] as $version => $download_url ) {
+			if ( 'trunk' !== $version ) {
+				$versions[] = [
+					'version' => (string) $version,
+					'url'     => (string) $download_url,
+				];
+			}
+		}
+
+		usort(
+			$versions,
+			function ( array $a, array $b ) {
+				return version_compare( $b['version'], $a['version'] );
+			}
+		);
+
+		return [
+			'versions' => $versions,
+			'floor'    => '',
+		];
+	}
+
+	/**
+	 * Explain why the catalogue stops at the floor it reported. WordPress.org
+	 * lists every released build, so this source reports no floor.
+	 *
+	 * @param string $floor Oldest installable version.
+	 *
+	 * @return string
+	 */
+	public function get_floor_notice( string $floor ): string {
+		return '';
+	}
+
+	/**
+	 * Obtain the package for a version.
+	 *
+	 * The catalogue entry already carries the download URL, which the installer
+	 * fetches itself, so there is nothing to clean up afterwards.
+	 *
+	 * @param array<string, mixed> $version_info Catalogue entry for the version.
+	 *
+	 * @return array{package: string, cleanup: bool}|WP_Error
+	 */
+	public function fetch_package( array $version_info ) {
+		if ( empty( $version_info['url'] ) ) {
+			return new WP_Error(
+				'version_source_package_error',
+				__( 'No download is available for that version.', 'code-snippets' )
+			);
+		}
+
+		return [
+			'package' => (string) $version_info['url'],
+			'cleanup' => false,
+		];
+	}
+
+	/**
+	 * Record a completed switch. WordPress.org tracks nothing on this site's
+	 * behalf, so there is nothing to report.
+	 *
+	 * @param string $version Version now installed.
+	 *
+	 * @return void
+	 */
+	public function report_installed_version( string $version ): void {
+	}
+}

From a59178d892af97cba5efe7dfa29db8fcea0c38e7 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 19:18:14 +0100
Subject: [PATCH 02/25] refactor: resolve the version switcher source and
 installer through filters

---
 src/php/Settings/Version_Switch.php | 552 +++++++++++++++++-----------
 1 file changed, 336 insertions(+), 216 deletions(-)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index 786a14a4c..9c665b5d9 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -2,44 +2,54 @@
 
 namespace Code_Snippets\Settings;
 
-use Plugin_Upgrader;
-use WP_Ajax_Upgrader_Skin;
 use WP_Error;
-use WP_Upgrader_Skin;
 use function Code_Snippets\code_snippets;
 
 /**
  * Version switching functionality for the Code Snippets plugin.
  *
+ * This class owns the parts of switching that do not vary: the caches, the
+ * progress marker, the capability and nonce checks, and the rendering. Where
+ * versions come from, and how a package is written to disk, are supplied by a
+ * Version_Source and a Package_Installer, which an edition replaces through the
+ * `code_snippets_version_source` and `code_snippets_package_installer` filters.
+ *
  * @package    Code_Snippets
  * @subpackage Settings
  */
 class Version_Switch {
 
 	/**
-	 * Transient key where the available version data is cached.
+	 * Transient key used to indicate when a version switch is currently taking place.
 	 */
-	private const CACHE_KEY = 'code_snippets_available_versions';
+	private const PROGRESS_KEY = 'code_snippets_version_switch_progress';
 
 	/**
-	 * Transient key used to indicate when a version switch is currently taking place.
+	 * Transient key holding the reason the last catalogue request failed.
 	 */
-	private const PROGRESS_KEY = 'code_snippets_version_switch_progress';
+	private const ERROR_KEY = 'code_snippets_version_switch_error';
 
 	/**
 	 * Duration of the version cache transient.
 	 */
 	private const VERSION_CACHE_DURATION = HOUR_IN_SECONDS;
 
+	/**
+	 * Duration of the last-error transient.
+	 */
+	private const ERROR_CACHE_DURATION = 5 * MINUTE_IN_SECONDS;
+
 	/**
 	 * Duration of the 'in progress' transient.
 	 */
 	private const PROGRESS_TIMEOUT = 5 * MINUTE_IN_SECONDS;
 
 	/**
-	 * API endpoint for checking for available plugin versions.
+	 * Source supplying the available versions.
+	 *
+	 * @var Version_Source|null
 	 */
-	private const WORDPRESS_API_ENDPOINT = 'https://api.wordpress.org/plugins/info/1.2/?action=plugin_information&slug=code-snippets';
+	private static ?Version_Source $source = null;
 
 	/**
 	 * Initialise class.
@@ -52,51 +62,152 @@ public static function init(): void {
 	}
 
 	/**
-	 * Retrieve a list of plugin versions available for switching.
+	 * Retrieve the source supplying available versions.
 	 *
-	 * @return array
+	 * @return Version_Source
 	 */
-	public static function get_available_versions(): array {
-		$versions = get_transient( self::CACHE_KEY );
+	public static function get_source(): Version_Source {
+		if ( null === self::$source ) {
+			/**
+			 * Filters the source the version switcher lists versions from.
+			 *
+			 * @param Version_Source $source Default source.
+			 */
+			$source = apply_filters( 'code_snippets_version_source', new WordPress_Org_Version_Source() );
+
+			self::$source = $source instanceof Version_Source ? $source : new WordPress_Org_Version_Source();
+		}
 
-		if ( false === $versions ) {
-			$response = wp_remote_get( self::WORDPRESS_API_ENDPOINT );
+		return self::$source;
+	}
 
-			if ( is_wp_error( $response ) ) {
-				return [];
-			}
+	/**
+	 * Retrieve the installer that writes a package to disk.
+	 *
+	 * @return Package_Installer
+	 */
+	public static function get_installer(): Package_Installer {
+		/**
+		 * Filters the installer the version switcher writes packages with.
+		 *
+		 * @param Package_Installer $installer Default installer.
+		 */
+		$installer = apply_filters( 'code_snippets_package_installer', new Upgrader_Package_Installer() );
+
+		return $installer instanceof Package_Installer ? $installer : new Upgrader_Package_Installer();
+	}
 
-			$body = wp_remote_retrieve_body( $response );
-			$data = json_decode( $body, true );
+	/**
+	 * Discard the memoised source, so the next call resolves the filter again.
+	 *
+	 * @return void
+	 */
+	public static function reset_source(): void {
+		self::$source = null;
+	}
 
-			if ( ! $data || ! isset( $data['versions'] ) ) {
-				return [];
-			}
+	/**
+	 * Determine whether versions can currently be listed.
+	 *
+	 * @return bool
+	 */
+	public static function is_available(): bool {
+		return self::get_source()->is_available();
+	}
 
-			// Filter out 'trunk' and sort versions.
-			$versions = [];
-			foreach ( $data['versions'] as $version => $download_url ) {
-				if ( 'trunk' !== $version ) {
-					$versions[] = [
-						'version' => $version,
-						'url'     => $download_url,
-					];
-				}
-			}
+	/**
+	 * Explain why the switcher is unavailable.
+	 *
+	 * @return array{message: string, action_url: string, action_label: string}
+	 */
+	public static function get_unavailable_notice(): array {
+		return self::get_source()->get_unavailable_notice();
+	}
 
-			// Sort versions in descending order.
-			usort(
-				$versions,
-				function ( $a, $b ) {
-					return version_compare( $b['version'], $a['version'] );
-				}
-			);
+	/**
+	 * Retrieve the cached catalogue, fetching it from the source when the cache
+	 * is cold.
+	 *
+	 * A failed request is not cached: a transient outage must not blank the
+	 * switcher for the full cache duration.
+	 *
+	 * @return array{versions: array<int, array<string, mixed>>, floor: string}
+	 */
+	private static function get_catalogue(): array {
+		$source = self::get_source();
+		$cached = get_transient( $source->get_cache_key() );
+
+		if ( is_array( $cached ) && isset( $cached['versions'] ) ) {
+			return $cached;
+		}
+
+		$empty = [
+			'versions' => [],
+			'floor'    => '',
+		];
 
-			// Cache for configured duration.
-			set_transient( self::CACHE_KEY, $versions, self::VERSION_CACHE_DURATION );
+		if ( ! $source->is_available() ) {
+			return $empty;
 		}
 
-		return $versions;
+		$result = $source->fetch_catalogue();
+
+		if ( is_wp_error( $result ) ) {
+			set_transient( self::ERROR_KEY, $result->get_error_code(), self::ERROR_CACHE_DURATION );
+			return $empty;
+		}
+
+		$catalogue = [
+			'versions' => $result['versions'],
+			'floor'    => $result['floor'],
+		];
+
+		delete_transient( self::ERROR_KEY );
+		set_transient( $source->get_cache_key(), $catalogue, self::VERSION_CACHE_DURATION );
+
+		return $catalogue;
+	}
+
+	/**
+	 * Retrieve a list of plugin versions available for switching.
+	 *
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function get_available_versions(): array {
+		return self::get_catalogue()['versions'];
+	}
+
+	/**
+	 * Retrieve the oldest installable version, if the source reported one.
+	 *
+	 * @return string
+	 */
+	public static function get_version_floor(): string {
+		return self::get_catalogue()['floor'];
+	}
+
+	/**
+	 * Retrieve the code of the last catalogue request failure.
+	 *
+	 * @return string
+	 */
+	public static function get_last_error_code(): string {
+		return (string) get_transient( self::ERROR_KEY );
+	}
+
+	/**
+	 * Discard the cached catalogue and fetch a fresh one from the source.
+	 *
+	 * Used by the maintenance tools, where the point of clearing caches is to see
+	 * what the source is serving right now rather than what it served an hour ago.
+	 *
+	 * @return array<int, array<string, mixed>> The freshly fetched versions.
+	 */
+	public static function refresh_available_versions(): array {
+		delete_transient( self::get_source()->get_cache_key() );
+		delete_transient( self::ERROR_KEY );
+
+		return self::get_available_versions();
 	}
 
 	/**
@@ -123,41 +234,58 @@ public static function is_version_switch_in_progress(): bool {
 	 * @return void
 	 */
 	public static function clear_version_caches(): void {
-		delete_transient( self::CACHE_KEY );
+		delete_transient( self::get_source()->get_cache_key() );
 		delete_transient( self::PROGRESS_KEY );
+		delete_transient( self::ERROR_KEY );
+	}
+
+	/**
+	 * Locate a version in a catalogue.
+	 *
+	 * @param string                           $target_version     Version to find.
+	 * @param array<int, array<string, mixed>> $available_versions Catalogue entries.
+	 *
+	 * @return array<string, mixed>|null
+	 */
+	private static function find_version( string $target_version, array $available_versions ): ?array {
+		foreach ( $available_versions as $version_info ) {
+			if ( isset( $version_info['version'] ) && $version_info['version'] === $target_version ) {
+				return $version_info;
+			}
+		}
+
+		return null;
 	}
 
 	/**
 	 * Validate that a target version is valid.
 	 *
-	 * @param string $target_version     Target version for switching.
-	 * @param array  $available_versions List of available versions.
+	 * This is a usability guard rather than a security boundary: a source is
+	 * free to refuse the version again when the package is requested.
 	 *
-	 * @return array
+	 * @param string                           $target_version     Target version for switching.
+	 * @param array<int, array<string, mixed>> $available_versions List of available versions.
+	 *
+	 * @return array{success: bool, message: string}
 	 */
 	public static function validate_target_version( string $target_version, array $available_versions ): array {
 		if ( empty( $target_version ) ) {
 			return [
-				'success'      => false,
-				'message'      => __( 'No target version specified.', 'code-snippets' ),
-				'download_url' => '',
+				'success' => false,
+				'message' => __( 'No target version specified.', 'code-snippets' ),
 			];
 		}
 
-		foreach ( $available_versions as $version_info ) {
-			if ( $version_info['version'] === $target_version ) {
-				return [
-					'success'      => true,
-					'message'      => '',
-					'download_url' => $version_info['url'],
-				];
-			}
+		if ( null === self::find_version( $target_version, $available_versions ) ) {
+			return [
+				'success' => false,
+				'message' => __( 'Invalid version specified.', 'code-snippets' ),
+			];
 		}
 
 		return [
-			'success'      => false,
-			'message'      => __( 'Invalid version specified.', 'code-snippets' ),
-			'download_url' => '',
+			'success' => true,
+			'message' => '',
 		];
 	}
 
@@ -185,131 +313,14 @@ public static function create_error_response( string $message, string $technical
 	}
 
 	/**
-	 * Install a plugin version from a URL.
+	 * Install a plugin version from a package.
 	 *
-	 * @param string $download_url Download URL.
+	 * @param string $package Local path to a package, or a download URL.
 	 *
-	 * @return array|bool|WP_Error
+	 * @return array{version: string}|WP_Error
 	 */
-	public static function perform_version_install( string $download_url ) {
-		if ( ! function_exists( 'wp_update_plugins' ) ) {
-			require_once ABSPATH . 'wp-admin/includes/update.php';
-		}
-		if ( ! function_exists( 'show_message' ) ) {
-			require_once ABSPATH . 'wp-admin/includes/misc.php';
-		}
-		if ( ! class_exists( 'Plugin_Upgrader' ) ) {
-			require_once ABSPATH . 'wp-admin/includes/class-wp-upgrader.php';
-		}
-
-		$update_handler = new WP_Ajax_Upgrader_Skin();
-		$upgrader = new Plugin_Upgrader( $update_handler );
-
-		global $code_snippets_last_update_handler, $code_snippets_last_upgrader;
-		$code_snippets_last_update_handler = $update_handler;
-		$code_snippets_last_upgrader = $upgrader;
-
-		return $upgrader->install(
-			$download_url,
-			[
-				'overwrite_package'  => true,
-				'clear_update_cache' => true,
-			]
-		);
-	}
-
-	/**
-	 * Extract error message from an upgrade handler.
-	 *
-	 * @param WP_Upgrader_Skin|null $update_handler Update handler.
-	 * @param Plugin_Upgrader|null  $upgrader       Plugin upgrader.
-	 *
-	 * @return string
-	 *
-	 * phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_print_r
-	 */
-	public static function extract_handler_messages( ?WP_Upgrader_Skin $update_handler, ?Plugin_Upgrader $upgrader ): string {
-		$handler_messages = '';
-
-		if ( isset( $update_handler ) ) {
-			if ( method_exists( $update_handler, 'get_errors' ) ) {
-				$errs = $update_handler->get_errors();
-				if ( $errs instanceof WP_Error && $errs->has_errors() ) {
-					$handler_messages .= implode( "\n", $errs->get_error_messages() );
-				}
-			}
-			if ( method_exists( $update_handler, 'get_error_messages' ) ) {
-				$em = $update_handler->get_error_messages();
-				if ( $em ) {
-					$handler_messages .= "\n" . $em;
-				}
-			}
-			if ( method_exists( $update_handler, 'get_upgrade_messages' ) ) {
-				$upgrade_msgs = $update_handler->get_upgrade_messages();
-				if ( is_array( $upgrade_msgs ) ) {
-					$handler_messages .= "\n" . implode( "\n", $upgrade_msgs );
-				} elseif ( $upgrade_msgs ) {
-					$handler_messages .= "\n" . $upgrade_msgs;
-				}
-			}
-		}
-
-		if ( empty( $handler_messages ) && isset( $upgrader->result ) ) {
-			if ( is_wp_error( $upgrader->result ) ) {
-				$handler_messages = implode( "\n", $upgrader->result->get_error_messages() );
-			} else {
-				$handler_messages = is_scalar( $upgrader->result )
-					? (string) $upgrader->result
-					: print_r( $upgrader->result, true );
-			}
-		}
-
-		return trim( $handler_messages );
-	}
-
-	/**
-	 * Report the failure of a version switch attempt.
-	 *
-	 * @param string $target_version Version number of attempted upgrade.
-	 * @param mixed  $result         Result of upgrade.
-	 * @param string $details        Additional details.
-	 *
-	 * @return void
-	 *
-	 * phpcs:disable WordPress.PHP.DevelopmentFunctions
-	 */
-	private static function log_version_switch_attempt( string $target_version, $result, string $details = '' ): void {
-		if ( function_exists( 'error_log' ) ) {
-			error_log( sprintf( 'Code Snippets version switch failed. target=%s, result=%s, details=%s', $target_version, var_export( $result, true ), $details ) );
-		}
-	}
-
-	/**
-	 * Handle the failure to install a new version.
-	 *
-	 * @param string $target_version Version used for attempted installation.
-	 * @param string $download_url   URL used for downloading new version.
-	 * @param mixed  $install_result Result of installation attempt.
-	 *
-	 * @return array
-	 */
-	private static function handle_installation_failure( string $target_version, string $download_url, $install_result ): array {
-		global $code_snippets_last_update_handler, $code_snippets_last_upgrader;
-
-		$handler_messages = self::extract_handler_messages( $code_snippets_last_update_handler, $code_snippets_last_upgrader );
-		self::log_version_switch_attempt( $target_version, $install_result, "URL: $download_url, Messages: $handler_messages" );
-
-		$fallback_message = __( 'Failed to switch versions. Please try again.', 'code-snippets' );
-
-		if ( ! empty( $handler_messages ) ) {
-			$short = wp_trim_words( wp_strip_all_tags( $handler_messages ), 40 );
-			$fallback_message = sprintf( '%s %s', $fallback_message, $short );
-		}
-
-		return [
-			'success' => false,
-			'message' => $fallback_message,
-		];
+	public static function perform_version_install( string $package ) {
+		return self::get_installer()->install( $package );
 	}
 
 	/**
@@ -324,6 +335,12 @@ public static function handle_version_switch( string $target_version ): array {
 			return self::create_error_response( __( 'You do not have permission to update plugins.', 'code-snippets' ) );
 		}
 
+		$source = self::get_source();
+
+		if ( ! $source->is_available() ) {
+			return self::create_error_response( $source->get_unavailable_notice()['message'] );
+		}
+
 		$available_versions = self::get_available_versions();
 		$validation = self::validate_target_version( $target_version, $available_versions );
 
@@ -337,27 +354,53 @@ public static function handle_version_switch( string $target_version ): array {
 
 		set_transient( self::PROGRESS_KEY, $target_version, self::PROGRESS_TIMEOUT );
 
-		$install_result = self::perform_version_install( $validation['download_url'] );
+		$package = $source->fetch_package( self::find_version( $target_version, $available_versions ) );
 
-		delete_transient( self::PROGRESS_KEY );
+		if ( is_wp_error( $package ) ) {
+			delete_transient( self::PROGRESS_KEY );
 
-		if ( is_wp_error( $install_result ) ) {
-			return self::create_error_response( $install_result->get_error_message() );
+			// The cached catalogue is stale when the source no longer recognises a
+			// version it listed, so discard it and let the next render refetch.
+			delete_transient( $source->get_cache_key() );
+
+			return self::create_error_response( $package->get_error_message() );
 		}
 
-		if ( $install_result ) {
-			delete_transient( self::CACHE_KEY );
+		try {
+			$install_result = self::perform_version_install( $package['package'] );
+		} finally {
+			if ( $package['cleanup'] ) {
+				wp_delete_file( $package['package'] );
+			}
 
-			// translators: %s: new version number.
-			$message = esc_html__( 'Successfully switched to version %s. Please refresh the page to see changes.', 'code-snippets' );
+			delete_transient( self::PROGRESS_KEY );
+		}
 
-			return [
-				'success' => true,
-				'message' => sprintf( $message, $target_version ),
-			];
-		} else {
-			return self::handle_installation_failure( $target_version, $validation['download_url'], $install_result );
+		if ( is_wp_error( $install_result ) ) {
+			return self::create_error_response(
+				sprintf(
+					// translators: %s: reason the installation failed.
+					__( 'Failed to switch versions: %s', 'code-snippets' ),
+					$install_result->get_error_message()
+				)
+			);
 		}
+
+		// The version on disk is the authoritative one when the installer can read
+		// it, since the package decides what was actually written.
+		$installed_version = $install_result['version'] ? $install_result['version'] : $target_version;
+
+		delete_transient( $source->get_cache_key() );
+		$source->report_installed_version( $installed_version );
+
+		return [
+			'success' => true,
+			'message' => sprintf(
+				// translators: %s: new version number.
+				__( 'Successfully switched to version %s. Please refresh the page to see changes.', 'code-snippets' ),
+				$installed_version
+			),
+		];
 	}
 
 	/**
@@ -367,8 +410,6 @@ public static function handle_version_switch( string $target_version ): array {
 	 */
 	public static function render_version_switch_field(): void {
 		$current_version = self::get_current_version();
-		$available_versions = self::get_available_versions();
-		$is_switching = self::is_version_switch_in_progress();
 
 		?>
 		<div class="code-snippets-version-switch">
@@ -377,11 +418,30 @@ public static function render_version_switch_field(): void {
 			<span class="current-version"><?php echo esc_html( $current_version ); ?></span>
 		</p>
 
-		<?php if ( $is_switching ) : ?>
+		<?php
+
+		if ( self::is_version_switch_in_progress() ) {
+			?>
 			<div class="notice code-snippets-notice notice-info inline">
 				<p><?php esc_html_e( 'Version switch in progress. Please wait…', 'code-snippets' ); ?></p>
 			</div>
-		<?php else : ?>
+			</div>
+			<?php
+			return;
+		}
+
+		if ( ! self::is_available() ) {
+			self::render_unavailable_notice();
+			?>
+			</div>
+			<?php
+			return;
+		}
+
+		$available_versions = self::get_available_versions();
+		$floor_notice = self::get_source()->get_floor_notice( self::get_version_floor() );
+
+		?>
 			<p>
 				<label for="target_version">
 					<?php esc_html_e( 'Switch to Version:', 'code-snippets' ); ?>
@@ -391,20 +451,16 @@ public static function render_version_switch_field(): void {
 					<?php foreach ( $available_versions as $version_info ) { ?>
 						<option value="<?php echo esc_attr( $version_info['version'] ); ?>"
 							<?php selected( $version_info['version'], $current_version ); ?>>
-							<?php
-
-							echo esc_html( $version_info['version'] );
-
-							if ( $version_info['version'] === $current_version ) {
-								esc_html_e( ' (Current)', 'code-snippets' );
-							}
-
-							?>
+							<?php echo esc_html( self::describe_version( $version_info, $current_version ) ); ?>
 						</option>
 					<?php } ?>
 				</select>
 			</p>
 
+			<?php if ( $floor_notice ) { ?>
+				<p class="description"><?php echo esc_html( $floor_notice ); ?></p>
+			<?php } ?>
+
 			<p>
 				<button type="button" id="switch-version-btn" class="button button-secondary" disabled
 					<?php disabled( empty( $available_versions ) ); ?>>
@@ -413,8 +469,72 @@ public static function render_version_switch_field(): void {
 			</p>
 
 			<div id="version-switch-result" class="notice code-snippets-notice" style="display: none;"></div>
-		<?php endif; ?>
-		</div><?php
+		</div>
+		<?php
+	}
+
+	/**
+	 * Build the label shown for a single version in the dropdown.
+	 *
+	 * @param array<string, mixed> $version_info    Catalogue entry.
+	 * @param string               $current_version Version currently installed.
+	 *
+	 * @return string
+	 */
+	private static function describe_version( array $version_info, string $current_version ): string {
+		$version = (string) $version_info['version'];
+		$release_mode = isset( $version_info['release_mode'] ) ? (string) $version_info['release_mode'] : '';
+		$tested_up_to = isset( $version_info['tested_up_to'] ) ? (string) $version_info['tested_up_to'] : '';
+
+		if ( $version === $current_version ) {
+			// translators: %s: plugin version number.
+			$label = sprintf( __( '%s (current)', 'code-snippets' ), $version );
+		} elseif ( 'beta' === $release_mode ) {
+			// translators: %s: plugin version number.
+			$label = sprintf( __( '%s (beta)', 'code-snippets' ), $version );
+		} elseif ( 'rc' === $release_mode ) {
+			// translators: %s: plugin version number.
+			$label = sprintf( __( '%s (release candidate)', 'code-snippets' ), $version );
+		} elseif ( ! empty( $version_info['is_latest'] ) ) {
+			// translators: %s: plugin version number.
+			$label = sprintf( __( '%s (latest)', 'code-snippets' ), $version );
+		} else {
+			$label = $version;
+		}
+
+		if ( ! $tested_up_to ) {
+			return $label;
+		}
+
+		return sprintf(
+			// translators: 1: labelled plugin version, 2: WordPress version number.
+			__( '%1$s — tested up to WordPress %2$s', 'code-snippets' ),
+			$label,
+			$tested_up_to
+		);
+	}
+
+	/**
+	 * Render the notice shown in place of the switcher when versions cannot be
+	 * listed for this site.
+	 *
+	 * @return void
+	 */
+	private static function render_unavailable_notice(): void {
+		$notice = self::get_unavailable_notice();
+
+		?>
+		<div class="notice code-snippets-notice notice-warning inline">
+			<p><?php echo esc_html( $notice['message'] ); ?></p>
+			<?php if ( $notice['action_url'] && $notice['action_label'] ) { ?>
+				<p>
+					<a href="<?php echo esc_url( $notice['action_url'] ); ?>" class="button button-primary">
+						<?php echo esc_html( $notice['action_label'] ); ?>
+					</a>
+				</p>
+			<?php } ?>
+		</div>
+		<?php
 	}
 
 	/**
@@ -457,12 +577,12 @@ public static function render_refresh_versions_field(): void {
 
 		printf(
 			'<p class="description">%s</p>',
-			esc_html__( 'Check for the latest available plugin versions from WordPress.org.', 'code-snippets' )
+			esc_html( self::get_source()->get_refresh_description() )
 		);
 	}
 
 	/**
-	 * AJAX handler for refreshing the installed version.
+	 * AJAX handler for refreshing the list of available versions.
 	 *
 	 * @return void
 	 */
@@ -473,8 +593,7 @@ public static function ajax_refresh_versions(): void {
 			wp_send_json_error( [ 'message' => __( 'You do not have permission to manage options.', 'code-snippets' ) ] );
 		}
 
-		delete_transient( self::CACHE_KEY );
-		self::get_available_versions();
+		self::refresh_available_versions();
 
 		wp_send_json_success( [ 'message' => __( 'Available versions updated successfully.', 'code-snippets' ) ] );
 	}
@@ -491,6 +610,7 @@ public static function render_version_switch_warning(): void {
 				<strong><?php esc_html_e( 'Warning:', 'code-snippets' ); ?></strong>
 				<?php esc_html_e( 'Switching versions may cause compatibility issues. Always backup your site before switching versions.', 'code-snippets' ); ?>
 			</p>
+			<p><?php esc_html_e( 'Beta and release candidate builds are not recommended for production sites.', 'code-snippets' ); ?></p>
 		</div>
 		<?php
 	}

From 561c7c681c424e33b84a2f720847fe6bc2db195f Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 19:18:36 +0100
Subject: [PATCH 03/25] feat: refetch the available plugin versions when
 resetting caches

---
 src/php/Settings/Settings_Fields.php |  2 +-
 src/php/Settings/Settings_Layout.php |  2 +-
 src/php/Settings/settings.php        | 17 ++++++++++++++++-
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/php/Settings/Settings_Fields.php b/src/php/Settings/Settings_Fields.php
index 8333c343c..29db33bcb 100644
--- a/src/php/Settings/Settings_Fields.php
+++ b/src/php/Settings/Settings_Fields.php
@@ -137,7 +137,7 @@ private function init_fields() {
 			'reset_caches'    => [
 				'name' => __( 'Reset Caches', 'code-snippets' ),
 				'type' => 'action',
-				'desc' => __( 'Use this button to manually clear snippets caches. Worth doing before switching to an older version of the plugin, if your site uses a persistent object cache.', 'code-snippets' ),
+				'desc' => __( 'Use this button to manually clear snippets caches and refetch the list of plugin versions available to install. Worth doing before switching to an older version of the plugin, if your site uses a persistent object cache.', 'code-snippets' ),
 			],
 		];
 
diff --git a/src/php/Settings/Settings_Layout.php b/src/php/Settings/Settings_Layout.php
index caa2e1205..88bf77337 100644
--- a/src/php/Settings/Settings_Layout.php
+++ b/src/php/Settings/Settings_Layout.php
@@ -210,7 +210,7 @@ public static function get_descriptions(): array {
 			'max_revisions'              => __( 'Saves a copy each time a snippet changes, so you can compare versions and roll back a bad edit.', 'code-snippets' ),
 			'preserve_on_delete'         => __( 'Keep the revision history after a snippet is deleted, so it can still be recovered.', 'code-snippets' ),
 			'enable_admin_bar'           => __( 'Jump to any snippet from anywhere in the admin, and see which ones ran on the page you are looking at.', 'code-snippets' ),
-			'reset_caches'               => __( 'Clears stored snippet data. Worth doing before switching to an older version of the plugin.', 'code-snippets' ),
+			'reset_caches'               => __( 'Clears stored snippet data and refetches the list of plugin versions available to install. Worth doing before switching to an older version of the plugin.', 'code-snippets' ),
 		];
 	}
 }
diff --git a/src/php/Settings/settings.php b/src/php/Settings/settings.php
index 069d1f9eb..96f4a0a7f 100644
--- a/src/php/Settings/settings.php
+++ b/src/php/Settings/settings.php
@@ -401,10 +401,25 @@ function process_settings_actions( array $input ): ?array {
 		// versioned groups (current, previous and legacy) all go too.
 		flush_versioned_cache_groups( (string) get_option( 'code_snippets_cache_version', '' ) );
 
+		// Refetched rather than merely discarded: resetting caches before a
+		// rollback is also how an administrator checks what the version source is
+		// serving right now, which a cleared cache alone would not show until the
+		// switcher was next rendered.
+		$available_versions = Version_Switch::refresh_available_versions();
+
 		add_settings_error(
 			OPTION_NAME,
 			'snippet_caches_reset',
-			__( 'Successfully reset snippets caches.', 'code-snippets' ),
+			sprintf(
+				/* translators: %d: number of plugin versions available to install. */
+				_n(
+					'Successfully reset snippets caches. %d plugin version is available to install.',
+					'Successfully reset snippets caches. %d plugin versions are available to install.',
+					count( $available_versions ),
+					'code-snippets'
+				),
+				count( $available_versions )
+			),
 			'updated'
 		);
 	}

From a5866c5c3828e84a16451a40d36f68fa3a3e3ba2 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 19:18:54 +0100
Subject: [PATCH 04/25] fix: discard the cached version catalogue on upgrade

---
 src/php/Core/Upgrader.php | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/php/Core/Upgrader.php b/src/php/Core/Upgrader.php
index 817e2ac12..ca355af36 100644
--- a/src/php/Core/Upgrader.php
+++ b/src/php/Core/Upgrader.php
@@ -134,6 +134,13 @@ private function do_site_upgrades() {
 			$role->remove_cap( apply_filters( 'code_snippets_cap', 'manage_snippets' ) );
 		}
 
+		// The version switcher caches its catalogue under a key belonging to the
+		// source that produced it. A site whose source changed across this upgrade
+		// would otherwise keep serving the previous source's list until it expired.
+		if ( version_compare( $prev_version, '4.0.0', '<' ) ) {
+			delete_transient( 'code_snippets_available_versions' );
+		}
+
 		if ( false === $prev_version ) {
 			add_action( 'init', [ $this, 'create_sample_content' ] );
 		}

From 03640e11e2bc866e398150260b63ded597efcc8a Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 19:20:20 +0100
Subject: [PATCH 05/25] fix: render the version switcher notice when no
 switcher config is present

---
 src/js/services/settings/version.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/js/services/settings/version.ts b/src/js/services/settings/version.ts
index a8082da25..b5b8514a5 100644
--- a/src/js/services/settings/version.ts
+++ b/src/js/services/settings/version.ts
@@ -168,8 +168,10 @@ export const initVersionSwitch = (): void => {
 	const currentVersion = getCurrentVersion()
 	const config = window.code_snippets_version_switch
 
+	// The switcher renders as a notice with no controls when the site cannot list
+	// versions, and the script is still enqueued.
 	if (!config) {
-		throw Error('version switch config missing')
+		return
 	}
 
 	const button = <HTMLButtonElement | null> document.getElementById('switch-version-btn')

From 711b76b186d5d24c9b94fb0969e2c11723840555 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 19:23:26 +0100
Subject: [PATCH 06/25] chore: add tests for the version switcher seams

---
 .../Settings/Recording_Package_Installer.php  |  37 +
 .../Settings/Recording_Version_Source.php     | 142 ++++
 tests/unit/Settings/Version_Switch_Test.php   | 659 ++++++++++++++++++
 3 files changed, 838 insertions(+)
 create mode 100644 tests/unit/Settings/Recording_Package_Installer.php
 create mode 100644 tests/unit/Settings/Recording_Version_Source.php
 create mode 100644 tests/unit/Settings/Version_Switch_Test.php

diff --git a/tests/unit/Settings/Recording_Package_Installer.php b/tests/unit/Settings/Recording_Package_Installer.php
new file mode 100644
index 000000000..4551deda0
--- /dev/null
+++ b/tests/unit/Settings/Recording_Package_Installer.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace Code_Snippets\Settings;
+
+use WP_Error;
+
+/**
+ * Package installer that records the packages it was handed.
+ */
+class Recording_Package_Installer implements Package_Installer {
+
+	/**
+	 * Packages this installer was asked to install.
+	 *
+	 * @var array<int, string>
+	 */
+	public array $installed = [];
+
+	/**
+	 * Result handed back to the switcher.
+	 *
+	 * @var array<string, mixed>|WP_Error
+	 */
+	public $result = [ 'version' => '' ];
+
+	/**
+	 * Install a plugin package.
+	 *
+	 * @param string $package Local path to a package, or a download URL.
+	 *
+	 * @return array{version: string}|WP_Error
+	 */
+	public function install( string $package ) {
+		$this->installed[] = $package;
+		return $this->result;
+	}
+}
diff --git a/tests/unit/Settings/Recording_Version_Source.php b/tests/unit/Settings/Recording_Version_Source.php
new file mode 100644
index 000000000..8788041b0
--- /dev/null
+++ b/tests/unit/Settings/Recording_Version_Source.php
@@ -0,0 +1,142 @@
+<?php
+
+namespace Code_Snippets\Settings;
+
+use WP_Error;
+
+/**
+ * Version source that records what the switcher asked it for.
+ */
+class Recording_Version_Source implements Version_Source {
+
+	/**
+	 * Transient key this source caches its catalogue under.
+	 *
+	 * @var string
+	 */
+	public string $cache_key = 'code_snippets_test_available_versions';
+
+	/**
+	 * Whether this source reports itself as reachable.
+	 *
+	 * @var bool
+	 */
+	public bool $available = true;
+
+	/**
+	 * Catalogue, or error, handed back to the switcher.
+	 *
+	 * @var array<string, mixed>|WP_Error
+	 */
+	public $catalogue = [
+		'versions' => [],
+		'floor'    => '',
+	];
+
+	/**
+	 * Package, or error, handed back to the switcher.
+	 *
+	 * @var array<string, mixed>|WP_Error
+	 */
+	public $package = [
+		'package' => '',
+		'cleanup' => false,
+	];
+
+	/**
+	 * Number of times the catalogue was fetched.
+	 *
+	 * @var int
+	 */
+	public int $fetch_catalogue_count = 0;
+
+	/**
+	 * Versions reported as installed.
+	 *
+	 * @var array<int, string>
+	 */
+	public array $reported = [];
+
+	/**
+	 * Transient key under which this source's catalogue is cached.
+	 *
+	 * @return string
+	 */
+	public function get_cache_key(): string {
+		return $this->cache_key;
+	}
+
+	/**
+	 * Determine whether this source can currently be reached.
+	 *
+	 * @return bool
+	 */
+	public function is_available(): bool {
+		return $this->available;
+	}
+
+	/**
+	 * Explain an unavailable source to the user.
+	 *
+	 * @return array{message: string, action_url: string, action_label: string}
+	 */
+	public function get_unavailable_notice(): array {
+		return [
+			'message'      => 'The test source is unavailable.',
+			'action_url'   => 'https://example.org/account',
+			'action_label' => 'Manage account',
+		];
+	}
+
+	/**
+	 * Describe where versions are fetched from.
+	 *
+	 * @return string
+	 */
+	public function get_refresh_description(): string {
+		return 'Check the test source for available versions.';
+	}
+
+	/**
+	 * Retrieve the versions available to install.
+	 *
+	 * @return array{versions: array<int, array<string, mixed>>, floor: string}|WP_Error
+	 */
+	public function fetch_catalogue() {
+		++$this->fetch_catalogue_count;
+		return $this->catalogue;
+	}
+
+	/**
+	 * Explain why the catalogue stops at the floor it reported.
+	 *
+	 * @param string $floor Oldest installable version.
+	 *
+	 * @return string
+	 */
+	public function get_floor_notice( string $floor ): string {
+		return 'Versions before ' . $floor . ' are not installable.';
+	}
+
+	/**
+	 * Obtain the package for a version.
+	 *
+	 * @param array<string, mixed> $version_info Catalogue entry for the version.
+	 *
+	 * @return array{package: string, cleanup: bool}|WP_Error
+	 */
+	public function fetch_package( array $version_info ) {
+		return $this->package;
+	}
+
+	/**
+	 * Record a completed switch.
+	 *
+	 * @param string $version Version now installed.
+	 *
+	 * @return void
+	 */
+	public function report_installed_version( string $version ): void {
+		$this->reported[] = $version;
+	}
+}
diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
new file mode 100644
index 000000000..4fd8c1ac9
--- /dev/null
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -0,0 +1,659 @@
+<?php
+
+namespace Code_Snippets\Settings;
+
+use Code_Snippets\UnitTestCase;
+use WP_Error;
+
+require_once __DIR__ . '/Recording_Version_Source.php';
+require_once __DIR__ . '/Recording_Package_Installer.php';
+
+/**
+ * Tests for the version switcher on the maintenance settings screen.
+ *
+ * @group version-switch
+ */
+class Version_Switch_Test extends UnitTestCase {
+
+	/**
+	 * Transient key the WordPress.org source caches its catalogue under.
+	 */
+	private const WP_ORG_CACHE_KEY = 'code_snippets_available_versions';
+
+	/**
+	 * Transient key holding the in-progress marker.
+	 */
+	private const PROGRESS_KEY = 'code_snippets_version_switch_progress';
+
+	/**
+	 * Source registered on the seam filter for the duration of a test.
+	 *
+	 * @var Recording_Version_Source|null
+	 */
+	private ?Recording_Version_Source $source = null;
+
+	/**
+	 * Installer registered on the seam filter for the duration of a test.
+	 *
+	 * @var Recording_Package_Installer|null
+	 */
+	private ?Recording_Package_Installer $installer = null;
+
+	/**
+	 * Callbacks to detach from the seam filters during tear-down.
+	 *
+	 * @var array<int, array{string, callable}>
+	 */
+	private array $registered_filters = [];
+
+	/**
+	 * Response the next outbound request will be answered with.
+	 *
+	 * @var array<string, mixed>|WP_Error
+	 */
+	private $next_response = [];
+
+	/**
+	 * URLs of every outbound request made during a test.
+	 *
+	 * @var array<int, string>
+	 */
+	private array $request_urls = [];
+
+	/**
+	 * Set up before each test.
+	 *
+	 * @return void
+	 */
+	public function set_up() {
+		parent::set_up();
+
+		Version_Switch::reset_source();
+		Version_Switch::clear_version_caches();
+		delete_transient( self::WP_ORG_CACHE_KEY );
+
+		$this->next_response = $this->build_response( 200, wp_json_encode( [ 'versions' => [] ] ) );
+		$this->request_urls = [];
+
+		add_filter( 'pre_http_request', [ $this, 'answer_http_request' ], 10, 3 );
+	}
+
+	/**
+	 * Clean up after each test.
+	 *
+	 * @return void
+	 */
+	public function tear_down() {
+		remove_filter( 'pre_http_request', [ $this, 'answer_http_request' ] );
+
+		Version_Switch::clear_version_caches();
+
+		foreach ( $this->registered_filters as list( $hook, $callback ) ) {
+			remove_filter( $hook, $callback );
+		}
+
+		$this->registered_filters = [];
+		$this->source = null;
+		$this->installer = null;
+
+		delete_transient( self::WP_ORG_CACHE_KEY );
+		Version_Switch::reset_source();
+
+		parent::tear_down();
+	}
+
+	/**
+	 * Answer an outbound request without touching the network.
+	 *
+	 * @param mixed                $preempt     Existing preempted value.
+	 * @param array<string, mixed> $parsed_args Request arguments.
+	 * @param string               $url         Request URL.
+	 *
+	 * @return array<string, mixed>|WP_Error
+	 */
+	public function answer_http_request( $preempt, array $parsed_args, string $url ) {
+		$this->request_urls[] = $url;
+		return $this->next_response;
+	}
+
+	/**
+	 * Assemble a fake HTTP response.
+	 *
+	 * @param int    $status Status code.
+	 * @param string $body   Response body.
+	 *
+	 * @return array<string, mixed>
+	 */
+	private function build_response( int $status, string $body ): array {
+		return [
+			'headers'  => [],
+			'body'     => $body,
+			'response' => [
+				'code'    => $status,
+				'message' => 'OK',
+			],
+			'cookies'  => [],
+		];
+	}
+
+	/**
+	 * Put a recording source and installer behind the seam filters.
+	 *
+	 * @return void
+	 */
+	private function register_test_services(): void {
+		$this->source = new Recording_Version_Source();
+		$this->installer = new Recording_Package_Installer();
+
+		$source = $this->source;
+		$installer = $this->installer;
+
+		$supply_source = function () use ( $source ) {
+			return $source;
+		};
+
+		$supply_installer = function () use ( $installer ) {
+			return $installer;
+		};
+
+		add_filter( 'code_snippets_version_source', $supply_source );
+		add_filter( 'code_snippets_package_installer', $supply_installer );
+
+		$this->registered_filters[] = [ 'code_snippets_version_source', $supply_source ];
+		$this->registered_filters[] = [ 'code_snippets_package_installer', $supply_installer ];
+
+		Version_Switch::reset_source();
+	}
+
+	/**
+	 * Seed the recording source's cache with a single-entry catalogue.
+	 *
+	 * @param string $version Version to list.
+	 *
+	 * @return void
+	 */
+	private function seed_catalogue( string $version ): void {
+		set_transient(
+			$this->source->get_cache_key(),
+			[
+				'versions' => [
+					[
+						'version' => $version,
+						'url'     => 'https://example.org/code-snippets.' . $version . '.zip',
+					],
+				],
+				'floor'    => '',
+			],
+			HOUR_IN_SECONDS
+		);
+	}
+
+	/**
+	 * Sign in as a user who may update plugins.
+	 *
+	 * @return void
+	 */
+	private function authorise(): void {
+		wp_set_current_user( self::factory()->user->create( [ 'role' => 'administrator' ] ) );
+	}
+
+	/**
+	 * Create a throwaway file standing in for a downloaded package.
+	 *
+	 * @return string
+	 */
+	private function create_package_file(): string {
+		return tempnam( get_temp_dir(), 'cs-pkg' );
+	}
+
+	/**
+	 * With nothing registered on the seam filters, the switcher lists builds from
+	 * WordPress.org and installs them with the WordPress plugin upgrader.
+	 *
+	 * @return void
+	 */
+	public function test_defaults_are_the_wordpress_org_source_and_upgrader_installer(): void {
+		$this->assertInstanceOf( WordPress_Org_Version_Source::class, Version_Switch::get_source() );
+		$this->assertInstanceOf( Upgrader_Package_Installer::class, Version_Switch::get_installer() );
+	}
+
+	/**
+	 * The seam filters replace both services, and removing them restores the
+	 * defaults the plugin ships with.
+	 *
+	 * @return void
+	 */
+	public function test_filters_replace_the_source_and_installer(): void {
+		$this->register_test_services();
+
+		$this->assertSame( $this->source, Version_Switch::get_source() );
+		$this->assertSame( $this->installer, Version_Switch::get_installer() );
+
+		foreach ( $this->registered_filters as list( $hook, $callback ) ) {
+			remove_filter( $hook, $callback );
+		}
+
+		$this->registered_filters = [];
+		Version_Switch::reset_source();
+
+		$this->assertInstanceOf( WordPress_Org_Version_Source::class, Version_Switch::get_source() );
+		$this->assertInstanceOf( Upgrader_Package_Installer::class, Version_Switch::get_installer() );
+	}
+
+	/**
+	 * A source that returns something other than a Version_Source is ignored, so
+	 * a misbehaving filter cannot leave the switcher without one.
+	 *
+	 * @return void
+	 */
+	public function test_an_invalid_filter_return_falls_back_to_the_default(): void {
+		$strip = function () {
+			return null;
+		};
+
+		add_filter( 'code_snippets_version_source', $strip, 99 );
+		add_filter( 'code_snippets_package_installer', $strip, 99 );
+		$this->registered_filters[] = [ 'code_snippets_version_source', $strip ];
+		$this->registered_filters[] = [ 'code_snippets_package_installer', $strip ];
+		Version_Switch::reset_source();
+
+		$this->assertInstanceOf( WordPress_Org_Version_Source::class, Version_Switch::get_source() );
+		$this->assertInstanceOf( Upgrader_Package_Installer::class, Version_Switch::get_installer() );
+	}
+
+	/**
+	 * The catalogue is cached under the key the source names, and a catalogue
+	 * left behind under another source's key is neither read nor overwritten.
+	 *
+	 * @return void
+	 */
+	public function test_catalogue_is_cached_under_the_source_cache_key(): void {
+		$this->register_test_services();
+
+		$stale = [
+			'versions' => [
+				[
+					'version' => '3.6.5',
+					'url'     => 'https://downloads.wordpress.org/plugin/code-snippets.3.6.5.zip',
+				],
+			],
+			'floor'    => '',
+		];
+
+		set_transient( self::WP_ORG_CACHE_KEY, $stale, HOUR_IN_SECONDS );
+
+		$this->source->catalogue = [
+			'versions' => [
+				[
+					'version' => '3.9.2',
+					'url'     => 'https://example.org/code-snippets.3.9.2.zip',
+				],
+			],
+			'floor'    => '3.6.0',
+		];
+
+		$versions = Version_Switch::get_available_versions();
+
+		$this->assertSame( [ '3.9.2' ], wp_list_pluck( $versions, 'version' ) );
+		$this->assertSame( '3.6.0', Version_Switch::get_version_floor() );
+		$this->assertIsArray( get_transient( $this->source->get_cache_key() ) );
+		$this->assertSame( $stale, get_transient( self::WP_ORG_CACHE_KEY ) );
+	}
+
+	/**
+	 * A cached catalogue answers without troubling the source again.
+	 *
+	 * @return void
+	 */
+	public function test_cached_catalogue_is_not_refetched(): void {
+		$this->register_test_services();
+		$this->seed_catalogue( '3.9.2' );
+
+		$this->assertSame( [ '3.9.2' ], wp_list_pluck( Version_Switch::get_available_versions(), 'version' ) );
+		$this->assertSame( 0, $this->source->fetch_catalogue_count );
+	}
+
+	/**
+	 * A failed request must not be cached: a transient outage would otherwise
+	 * blank the switcher for the full cache duration.
+	 *
+	 * @return void
+	 */
+	public function test_source_error_is_not_cached(): void {
+		$this->register_test_services();
+		$this->source->catalogue = new WP_Error( 'version_source_request_error', 'Request failed.' );
+
+		$this->assertSame( [], Version_Switch::get_available_versions() );
+		$this->assertFalse( get_transient( $this->source->get_cache_key() ) );
+		$this->assertSame( 'version_source_request_error', Version_Switch::get_last_error_code() );
+	}
+
+	/**
+	 * An unavailable source is not asked for a catalogue at all.
+	 *
+	 * @return void
+	 */
+	public function test_unavailable_source_is_never_fetched_from(): void {
+		$this->register_test_services();
+		$this->source->available = false;
+
+		$this->assertFalse( Version_Switch::is_available() );
+		$this->assertSame( [], Version_Switch::get_available_versions() );
+		$this->assertSame( 0, $this->source->fetch_catalogue_count );
+		$this->assertNotEmpty( Version_Switch::get_unavailable_notice()['message'] );
+	}
+
+	/**
+	 * Refreshing discards the cached catalogue and fetches a current one, so a
+	 * build published moments ago shows up straight away.
+	 *
+	 * @return void
+	 */
+	public function test_refresh_refetches_the_catalogue_from_the_source(): void {
+		$this->register_test_services();
+		$this->seed_catalogue( '3.9.2' );
+
+		$this->source->catalogue = [
+			'versions' => [
+				[
+					'version' => '4.0.0',
+					'url'     => 'https://example.org/code-snippets.4.0.0.zip',
+				],
+			],
+			'floor'    => '',
+		];
+
+		// The cached catalogue would still answer this without a refetch.
+		$this->assertSame( [ '3.9.2' ], wp_list_pluck( Version_Switch::get_available_versions(), 'version' ) );
+
+		$refreshed = Version_Switch::refresh_available_versions();
+
+		$this->assertSame( [ '4.0.0' ], wp_list_pluck( $refreshed, 'version' ) );
+		$this->assertSame( 1, $this->source->fetch_catalogue_count );
+	}
+
+	/**
+	 * A version absent from the catalogue is rejected before anything is fetched.
+	 *
+	 * @return void
+	 */
+	public function test_validate_target_version_rejects_an_unlisted_version(): void {
+		$available = [
+			[
+				'version' => '3.9.2',
+				'url'     => 'https://example.org/code-snippets.3.9.2.zip',
+			],
+		];
+
+		$rejected = Version_Switch::validate_target_version( '3.0.0', $available );
+		$empty = Version_Switch::validate_target_version( '', $available );
+		$accepted = Version_Switch::validate_target_version( '3.9.2', $available );
+
+		$this->assertFalse( $rejected['success'] );
+		$this->assertNotEmpty( $rejected['message'] );
+		$this->assertFalse( $empty['success'] );
+		$this->assertTrue( $accepted['success'] );
+		$this->assertArrayNotHasKey( 'download_url', $accepted );
+	}
+
+	/**
+	 * A user without the plugin update capability cannot switch versions.
+	 *
+	 * @return void
+	 */
+	public function test_switch_requires_the_update_plugins_capability(): void {
+		$this->register_test_services();
+		$this->seed_catalogue( '3.9.2' );
+		wp_set_current_user( self::factory()->user->create( [ 'role' => 'editor' ] ) );
+
+		$result = Version_Switch::handle_version_switch( '3.9.2' );
+
+		$this->assertFalse( $result['success'] );
+		$this->assertSame( [], $this->installer->installed );
+	}
+
+	/**
+	 * A site whose source cannot be reached cannot start a switch at all.
+	 *
+	 * @return void
+	 */
+	public function test_switch_is_refused_when_the_source_is_unavailable(): void {
+		$this->register_test_services();
+		$this->authorise();
+		$this->source->available = false;
+
+		$result = Version_Switch::handle_version_switch( '3.9.2' );
+
+		$this->assertFalse( $result['success'] );
+		$this->assertSame( [], $this->installer->installed );
+		$this->assertFalse( get_transient( self::PROGRESS_KEY ) );
+	}
+
+	/**
+	 * Switching to the version already installed is a no-op.
+	 *
+	 * @return void
+	 */
+	public function test_switching_to_the_current_version_is_refused(): void {
+		$this->register_test_services();
+		$this->authorise();
+		$this->seed_catalogue( Version_Switch::get_current_version() );
+
+		$result = Version_Switch::handle_version_switch( Version_Switch::get_current_version() );
+
+		$this->assertFalse( $result['success'] );
+		$this->assertSame( [], $this->installer->installed );
+	}
+
+	/**
+	 * A package the source cannot supply must never reach the installer, and must
+	 * leave neither a wedged progress marker nor a catalogue known to be stale.
+	 *
+	 * @return void
+	 */
+	public function test_failed_package_fetch_never_reaches_the_installer(): void {
+		$this->register_test_services();
+		$this->authorise();
+		$this->seed_catalogue( '3.9.2' );
+
+		$this->source->package = new WP_Error( 'version_source_package_error', 'No download is available.' );
+
+		$result = Version_Switch::handle_version_switch( '3.9.2' );
+
+		$this->assertFalse( $result['success'] );
+		$this->assertSame( [], $this->installer->installed );
+		$this->assertFalse( get_transient( self::PROGRESS_KEY ) );
+		$this->assertFalse( get_transient( $this->source->get_cache_key() ) );
+	}
+
+	/**
+	 * A failed install clears the progress marker and deletes the package it was
+	 * handed, rather than leaving the switcher wedged until the marker expires.
+	 *
+	 * @return void
+	 */
+	public function test_failed_install_clears_the_progress_marker_and_package(): void {
+		$this->register_test_services();
+		$this->authorise();
+		$this->seed_catalogue( '3.9.2' );
+
+		$package_path = $this->create_package_file();
+
+		$this->source->package = [
+			'package' => $package_path,
+			'cleanup' => true,
+		];
+
+		$this->installer->result = new WP_Error( 'package_install_failed', 'The package could not be installed.' );
+
+		$result = Version_Switch::handle_version_switch( '3.9.2' );
+
+		$this->assertFalse( $result['success'] );
+		$this->assertSame( [ $package_path ], $this->installer->installed );
+		$this->assertFileDoesNotExist( $package_path );
+		$this->assertFalse( get_transient( self::PROGRESS_KEY ) );
+		$this->assertSame( [], $this->source->reported );
+	}
+
+	/**
+	 * A completed switch deletes the package, clears the progress marker and the
+	 * now-outdated catalogue, and tells the source what landed on disk.
+	 *
+	 * @return void
+	 */
+	public function test_successful_switch_cleans_up_and_reports_the_installed_version(): void {
+		$this->register_test_services();
+		$this->authorise();
+		$this->seed_catalogue( '3.9.2' );
+
+		$package_path = $this->create_package_file();
+
+		$this->source->package = [
+			'package' => $package_path,
+			'cleanup' => true,
+		];
+
+		$this->installer->result = [ 'version' => '' ];
+
+		$result = Version_Switch::handle_version_switch( '3.9.2' );
+
+		$this->assertTrue( $result['success'], $result['message'] );
+		$this->assertStringContainsString( '3.9.2', $result['message'] );
+		$this->assertSame( [ $package_path ], $this->installer->installed );
+		$this->assertFileDoesNotExist( $package_path );
+		$this->assertFalse( get_transient( self::PROGRESS_KEY ) );
+		$this->assertFalse( get_transient( $this->source->get_cache_key() ) );
+		$this->assertSame( [ '3.9.2' ], $this->source->reported );
+	}
+
+	/**
+	 * An installer that can read the version it wrote is believed over the one the
+	 * switch asked for, since the package decides what actually landed.
+	 *
+	 * @return void
+	 */
+	public function test_installer_reported_version_wins_over_the_requested_one(): void {
+		$this->register_test_services();
+		$this->authorise();
+		$this->seed_catalogue( '3.9.2' );
+
+		$this->source->package = [
+			'package' => 'https://example.org/code-snippets.3.9.2.zip',
+			'cleanup' => false,
+		];
+
+		$this->installer->result = [ 'version' => '3.9.3' ];
+
+		$result = Version_Switch::handle_version_switch( '3.9.2' );
+
+		$this->assertTrue( $result['success'], $result['message'] );
+		$this->assertSame( [ '3.9.3' ], $this->source->reported );
+	}
+
+	/**
+	 * A package the source did not ask to have cleaned up is left alone.
+	 *
+	 * @return void
+	 */
+	public function test_package_is_kept_when_cleanup_is_not_requested(): void {
+		$this->register_test_services();
+		$this->authorise();
+		$this->seed_catalogue( '3.9.2' );
+
+		$package_path = $this->create_package_file();
+
+		$this->source->package = [
+			'package' => $package_path,
+			'cleanup' => false,
+		];
+
+		$this->installer->result = [ 'version' => '' ];
+
+		try {
+			$result = Version_Switch::handle_version_switch( '3.9.2' );
+
+			$this->assertTrue( $result['success'], $result['message'] );
+			$this->assertFileExists( $package_path );
+		} finally {
+			wp_delete_file( $package_path );
+		}
+	}
+
+	/**
+	 * The WordPress.org source drops the trunk entry and lists releases newest
+	 * first, and reports no floor because every release remains installable.
+	 *
+	 * @return void
+	 */
+	public function test_wordpress_org_source_orders_releases_and_drops_trunk(): void {
+		$this->next_response = $this->build_response(
+			200,
+			wp_json_encode(
+				[
+					'versions' => [
+						'3.6.5' => 'https://downloads.wordpress.org/plugin/code-snippets.3.6.5.zip',
+						'trunk' => 'https://downloads.wordpress.org/plugin/code-snippets.zip',
+						'3.9.2' => 'https://downloads.wordpress.org/plugin/code-snippets.3.9.2.zip',
+						'3.7.0' => 'https://downloads.wordpress.org/plugin/code-snippets.3.7.0.zip',
+					],
+				]
+			)
+		);
+
+		$catalogue = ( new WordPress_Org_Version_Source() )->fetch_catalogue();
+
+		$this->assertSame( [ '3.9.2', '3.7.0', '3.6.5' ], wp_list_pluck( $catalogue['versions'], 'version' ) );
+		$this->assertSame( '', $catalogue['floor'] );
+		$this->assertStringContainsString( 'api.wordpress.org', $this->request_urls[0] );
+	}
+
+	/**
+	 * A malformed response is an error rather than an empty catalogue, so it is
+	 * not cached in place of the real list.
+	 *
+	 * @return void
+	 */
+	public function test_wordpress_org_source_rejects_a_malformed_response(): void {
+		$this->next_response = $this->build_response( 200, 'not json' );
+
+		$this->assertWPError( ( new WordPress_Org_Version_Source() )->fetch_catalogue() );
+	}
+
+	/**
+	 * The catalogue entry already carries the download URL, which the installer
+	 * fetches itself, so nothing is left to clean up.
+	 *
+	 * @return void
+	 */
+	public function test_wordpress_org_source_hands_over_the_download_url(): void {
+		$source = new WordPress_Org_Version_Source();
+
+		$package = $source->fetch_package(
+			[
+				'version' => '3.9.2',
+				'url'     => 'https://downloads.wordpress.org/plugin/code-snippets.3.9.2.zip',
+			]
+		);
+
+		$this->assertSame( 'https://downloads.wordpress.org/plugin/code-snippets.3.9.2.zip', $package['package'] );
+		$this->assertFalse( $package['cleanup'] );
+		$this->assertWPError( $source->fetch_package( [ 'version' => '3.9.2' ] ) );
+	}
+
+	/**
+	 * WordPress.org is always reachable and tracks nothing on this site's behalf.
+	 *
+	 * @return void
+	 */
+	public function test_wordpress_org_source_is_always_available_and_reports_nothing(): void {
+		$source = new WordPress_Org_Version_Source();
+
+		$this->assertTrue( $source->is_available() );
+		$this->assertSame( self::WP_ORG_CACHE_KEY, $source->get_cache_key() );
+		$this->assertSame( '', $source->get_floor_notice( '3.6.0' ) );
+
+		$source->report_installed_version( '3.9.2' );
+
+		$this->assertSame( [], $this->request_urls );
+	}
+}

From 9dd96a2f16de5e6614df73cd295f19360dec431b Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 19:34:03 +0100
Subject: [PATCH 07/25] fix: remove the version switcher transients on complete
 uninstall

---
 src/php/Core/Uninstaller.php         |  5 ++++
 tests/unit/Core/Uninstaller_Test.php | 36 ++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/src/php/Core/Uninstaller.php b/src/php/Core/Uninstaller.php
index cd59ed9de..a53749ace 100644
--- a/src/php/Core/Uninstaller.php
+++ b/src/php/Core/Uninstaller.php
@@ -12,6 +12,7 @@
 use Code_Snippets\Admin\Feedback_Panel;
 use Code_Snippets\Client\Feedback_Client;
 use Code_Snippets\Model\Feedback_Connection;
+use Code_Snippets\Settings\Version_Switch;
 use function Code_Snippets\flush_versioned_cache_groups;
 
 /**
@@ -91,6 +92,10 @@ private function uninstall_current_site() {
 		delete_option( Feedback_Connection::CREDENTIALS_OPTION );
 		delete_transient( Feedback_Panel::SUMMARY_TRANSIENT );
 		delete_transient( Feedback_Client::REGISTRATION_FAILURE_TRANSIENT );
+
+		// The switcher caches under a key belonging to whichever source is in
+		// force, so it has to do its own clearing rather than name the keys here.
+		Version_Switch::clear_version_caches();
 	}
 
 	/**
diff --git a/tests/unit/Core/Uninstaller_Test.php b/tests/unit/Core/Uninstaller_Test.php
index ed0f2e3ea..c686d2b13 100644
--- a/tests/unit/Core/Uninstaller_Test.php
+++ b/tests/unit/Core/Uninstaller_Test.php
@@ -4,6 +4,7 @@
 
 use Code_Snippets\REST_API\Preferences\Insights_View_Rest_Controller;
 use Code_Snippets\REST_API\Preferences\Snippet_View_REST_Controller;
+use Code_Snippets\Settings\Version_Switch;
 use Code_Snippets\UnitTestCase;
 use function Code_Snippets\code_snippets;
 
@@ -19,6 +20,7 @@ class Uninstaller_Test extends UnitTestCase {
 	 */
 	public function tear_down() {
 		code_snippets()->db->create_or_upgrade_tables();
+		Version_Switch::clear_version_caches();
 		delete_option( Snippet_View_REST_Controller::OPTION_NAME );
 		delete_option( Insights_View_Rest_Controller::OPTION_NAME );
 		delete_option( 'code_snippets_settings' );
@@ -52,4 +54,38 @@ public function test_complete_uninstall_removes_insights_chart_view_preferences(
 
 		$this->assertFalse( get_option( Insights_View_Rest_Controller::OPTION_NAME ) );
 	}
+
+	/**
+	 * Complete uninstall takes the version switcher's transients with it, whichever
+	 * source cached them.
+	 *
+	 * @return void
+	 */
+	public function test_complete_uninstall_removes_version_switcher_transients(): void {
+		update_option(
+			'code_snippets_settings',
+			[
+				'general' => [ 'complete_uninstall' => true ],
+			]
+		);
+
+		$cache_key = Version_Switch::get_source()->get_cache_key();
+
+		set_transient(
+			$cache_key,
+			[
+				'versions' => [],
+				'floor'    => '',
+			],
+			HOUR_IN_SECONDS
+		);
+		set_transient( 'code_snippets_version_switch_progress', '3.9.2', HOUR_IN_SECONDS );
+		set_transient( 'code_snippets_version_switch_error', 'version_source_request_error', HOUR_IN_SECONDS );
+
+		( new Uninstaller() )->uninstall_plugin();
+
+		$this->assertFalse( get_transient( $cache_key ) );
+		$this->assertFalse( get_transient( 'code_snippets_version_switch_progress' ) );
+		$this->assertFalse( get_transient( 'code_snippets_version_switch_error' ) );
+	}
 }

From ac268c522386f933a2f8bfc2f734c088ad5ad80a Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 19:34:49 +0100
Subject: [PATCH 08/25] docs: note the version switcher seams and cache changes
 in the changelog

---
 CHANGELOG.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e94b17f42..83e09d400 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,6 +36,9 @@
   upload controls. (PRO)
 * Feedback reporter for sending bug reports, feature requests and general feedback from the plugin screens, with an
   optional summary of the site environment so the team can reproduce the problem. (PRO)
+* New `code_snippets_version_source` and `code_snippets_package_installer` filters, for replacing where the version
+  switcher lists plugin versions from and how it installs them. A source may mark a version as the latest, beta or
+  release candidate build, and name the WordPress version it was tested up to.
 
 ### Changed
 * Redesigned the main snippets table with improved search, filtering, sorting, pagination, row actions, and bulk
@@ -52,6 +55,9 @@
   toolbar, dialogs, tooltips, and code editor. (PRO)
 * Improved colour contrast and reduced-motion support across admin screens. (PRO)
 * Faster loading of large code vaults, which are now fetched a page at a time instead of all at once. (PRO)
+* The version switching warning now notes that beta and release candidate builds are not recommended for production
+  sites.
+* Resetting caches now refetches the list of plugin versions available to install, and reports how many were found.
 
 ### Fixed
 * Fixed AI conversations from one connected site being visible from another. (PRO)
@@ -67,6 +73,7 @@
 * Fixed featured Community Cloud snippets failing to load with some cloud API responses. (PRO)
 * Fixed bulk actions in Community Cloud running against an empty selection, so selected snippets were never downloaded.
   (PRO)
+* Fixed the version switcher's cached data being left behind after a complete uninstall.
 
 ## [3.10.2] (2026-09-01)
 

From e2e6e9301ef72eb163a1e56e65cdb46421b6666d Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 20:42:22 +0100
Subject: [PATCH 09/25] fix: keep the message behind a failed version catalogue
 request

---
 src/php/Settings/Version_Switch.php | 34 ++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index 9c665b5d9..a73f61fe3 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -25,7 +25,8 @@ class Version_Switch {
 	private const PROGRESS_KEY = 'code_snippets_version_switch_progress';
 
 	/**
-	 * Transient key holding the reason the last catalogue request failed.
+	 * Transient key holding the code and message of the last failed catalogue
+	 * request.
 	 */
 	private const ERROR_KEY = 'code_snippets_version_switch_error';
 
@@ -153,7 +154,14 @@ private static function get_catalogue(): array {
 		$result = $source->fetch_catalogue();
 
 		if ( is_wp_error( $result ) ) {
-			set_transient( self::ERROR_KEY, $result->get_error_code(), self::ERROR_CACHE_DURATION );
+			set_transient(
+				self::ERROR_KEY,
+				[
+					'code'    => $result->get_error_code(),
+					'message' => $result->get_error_message(),
+				],
+				self::ERROR_CACHE_DURATION
+			);
 			return $empty;
 		}
 
@@ -189,10 +197,30 @@ public static function get_version_floor(): string {
 	/**
 	 * Retrieve the code of the last catalogue request failure.
 	 *
+	 * Sites upgrading mid-cache still hold the previous shape — a bare code —
+	 * for up to ERROR_CACHE_DURATION.
+	 *
 	 * @return string
 	 */
 	public static function get_last_error_code(): string {
-		return (string) get_transient( self::ERROR_KEY );
+		$error = get_transient( self::ERROR_KEY );
+
+		if ( is_array( $error ) ) {
+			return isset( $error['code'] ) ? (string) $error['code'] : '';
+		}
+
+		return is_string( $error ) ? $error : '';
+	}
+
+	/**
+	 * Retrieve the message explaining the last catalogue request failure.
+	 *
+	 * @return string
+	 */
+	public static function get_last_error_message(): string {
+		$error = get_transient( self::ERROR_KEY );
+
+		return is_array( $error ) && isset( $error['message'] ) ? (string) $error['message'] : '';
 	}
 
 	/**

From a87da722c203058a19eed775816c1cff3e60f9c3 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 20:43:09 +0100
Subject: [PATCH 10/25] fix: explain an empty version catalogue instead of
 disabling the switcher

---
 src/php/Settings/Version_Switch.php         |  42 +++++++-
 tests/unit/Settings/Version_Switch_Test.php | 114 ++++++++++++++++++++
 2 files changed, 153 insertions(+), 3 deletions(-)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index a73f61fe3..a53242d38 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -467,6 +467,15 @@ public static function render_version_switch_field(): void {
 		}
 
 		$available_versions = self::get_available_versions();
+
+		if ( ! $available_versions ) {
+			self::render_empty_catalogue_notice();
+			?>
+			</div>
+			<?php
+			return;
+		}
+
 		$floor_notice = self::get_source()->get_floor_notice( self::get_version_floor() );
 
 		?>
@@ -474,7 +483,7 @@ public static function render_version_switch_field(): void {
 				<label for="target_version">
 					<?php esc_html_e( 'Switch to Version:', 'code-snippets' ); ?>
 				</label>
-				<select id="target_version" name="target_version" <?php disabled( empty( $available_versions ) ); ?>>
+				<select id="target_version" name="target_version">
 					<option value=""><?php esc_html_e( 'Select a version…', 'code-snippets' ); ?></option>
 					<?php foreach ( $available_versions as $version_info ) { ?>
 						<option value="<?php echo esc_attr( $version_info['version'] ); ?>"
@@ -490,8 +499,7 @@ public static function render_version_switch_field(): void {
 			<?php } ?>
 
 			<p>
-				<button type="button" id="switch-version-btn" class="button button-secondary" disabled
-					<?php disabled( empty( $available_versions ) ); ?>>
+				<button type="button" id="switch-version-btn" class="button button-secondary" disabled>
 					<?php esc_html_e( 'Switch Version', 'code-snippets' ); ?>
 				</button>
 			</p>
@@ -542,6 +550,34 @@ private static function describe_version( array $version_info, string $current_v
 		);
 	}
 
+	/**
+	 * Render the explanation shown in place of the switcher when the catalogue
+	 * holds no versions.
+	 *
+	 * The list is empty both when the request for it failed and when the source
+	 * answered with nothing to install, which are not the same thing to the user.
+	 *
+	 * @return void
+	 */
+	private static function render_empty_catalogue_notice(): void {
+		$error_message = self::get_last_error_message();
+
+		if ( $error_message ) {
+			?>
+			<div class="notice code-snippets-notice notice-warning inline">
+				<p><?php echo esc_html( $error_message ); ?></p>
+			</div>
+			<?php
+			return;
+		}
+
+		?>
+		<p class="description">
+			<?php esc_html_e( 'There are no versions available to install.', 'code-snippets' ); ?>
+		</p>
+		<?php
+	}
+
 	/**
 	 * Render the notice shown in place of the switcher when versions cannot be
 	 * listed for this site.
diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
index 4fd8c1ac9..51f267c2f 100644
--- a/tests/unit/Settings/Version_Switch_Test.php
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -25,6 +25,11 @@ class Version_Switch_Test extends UnitTestCase {
 	 */
 	private const PROGRESS_KEY = 'code_snippets_version_switch_progress';
 
+	/**
+	 * Transient key holding the reason the last catalogue request failed.
+	 */
+	private const ERROR_KEY = 'code_snippets_version_switch_error';
+
 	/**
 	 * Source registered on the seam filter for the duration of a test.
 	 *
@@ -206,6 +211,17 @@ private function create_package_file(): string {
 		return tempnam( get_temp_dir(), 'cs-pkg' );
 	}
 
+	/**
+	 * Capture the markup the version switcher field renders.
+	 *
+	 * @return string
+	 */
+	private function render_version_switch_field(): string {
+		ob_start();
+		Version_Switch::render_version_switch_field();
+		return (string) ob_get_clean();
+	}
+
 	/**
 	 * With nothing registered on the seam filters, the switcher lists builds from
 	 * WordPress.org and installs them with the WordPress plugin upgrader.
@@ -579,6 +595,104 @@ public function test_package_is_kept_when_cleanup_is_not_requested(): void {
 		}
 	}
 
+	/**
+	 * A catalogue request that failed is explained in the field itself, rather
+	 * than leaving a dead control with nothing to act on.
+	 *
+	 * @return void
+	 */
+	public function test_failed_catalogue_request_renders_its_message_instead_of_the_switcher(): void {
+		$this->register_test_services();
+		$this->source->catalogue = new WP_Error( 'version_source_request_error', 'The version list could not be retrieved.' );
+
+		$output = $this->render_version_switch_field();
+
+		$this->assertStringContainsString( 'The version list could not be retrieved.', $output );
+		$this->assertStringContainsString( 'notice-warning', $output );
+		$this->assertStringNotContainsString( '<select', $output );
+		$this->assertStringContainsString( 'Current Version:', $output );
+	}
+
+	/**
+	 * A source that answered with nothing to install says so, instead of
+	 * presenting the same dead control a failed request would.
+	 *
+	 * @return void
+	 */
+	public function test_empty_catalogue_renders_an_explicit_nothing_to_install_line(): void {
+		$this->register_test_services();
+
+		$output = $this->render_version_switch_field();
+
+		$this->assertStringContainsString( 'no versions available to install', $output );
+		$this->assertStringNotContainsString( '<select', $output );
+		$this->assertStringContainsString( 'Current Version:', $output );
+	}
+
+	/**
+	 * A catalogue with versions in it still renders the dropdown, with an entry
+	 * for each version.
+	 *
+	 * @return void
+	 */
+	public function test_populated_catalogue_renders_the_version_dropdown(): void {
+		$this->register_test_services();
+		$this->seed_catalogue( '3.9.2' );
+
+		$output = $this->render_version_switch_field();
+
+		$this->assertStringContainsString( '<select', $output );
+		$this->assertStringContainsString( 'value="3.9.2"', $output );
+		$this->assertStringNotContainsString( 'no versions available to install', $output );
+	}
+
+	/**
+	 * The message behind a failed request is kept alongside its code, and a
+	 * successful fetch clears both.
+	 *
+	 * @return void
+	 */
+	public function test_last_error_message_is_stored_and_cleared_with_the_code(): void {
+		$this->register_test_services();
+
+		$this->assertSame( '', Version_Switch::get_last_error_message() );
+
+		$this->source->catalogue = new WP_Error( 'version_source_request_error', 'The version list could not be retrieved.' );
+
+		Version_Switch::get_available_versions();
+
+		$this->assertSame( 'version_source_request_error', Version_Switch::get_last_error_code() );
+		$this->assertSame( 'The version list could not be retrieved.', Version_Switch::get_last_error_message() );
+
+		$this->source->catalogue = [
+			'versions' => [
+				[
+					'version' => '3.9.2',
+					'url'     => 'https://example.org/code-snippets.3.9.2.zip',
+				],
+			],
+			'floor'    => '',
+		];
+
+		Version_Switch::refresh_available_versions();
+
+		$this->assertSame( '', Version_Switch::get_last_error_code() );
+		$this->assertSame( '', Version_Switch::get_last_error_message() );
+	}
+
+	/**
+	 * A site still holding the previous transient shape — a bare error code —
+	 * reports that code rather than a mangled one.
+	 *
+	 * @return void
+	 */
+	public function test_last_error_code_tolerates_the_previous_transient_shape(): void {
+		set_transient( self::ERROR_KEY, 'version_source_request_error', MINUTE_IN_SECONDS );
+
+		$this->assertSame( 'version_source_request_error', Version_Switch::get_last_error_code() );
+		$this->assertSame( '', Version_Switch::get_last_error_message() );
+	}
+
 	/**
 	 * The WordPress.org source drops the trunk entry and lists releases newest
 	 * first, and reports no floor because every release remains installable.

From 97d7174da919b91c098a7e608579aa6b54bd519b Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Tue, 22 Sep 2026 21:16:27 +0100
Subject: [PATCH 11/25] fix: only render the version floor notice when the
 source reports a floor

---
 src/php/Settings/Version_Switch.php         |  3 +-
 tests/unit/Settings/Version_Switch_Test.php | 43 +++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index a53242d38..db28615c0 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -476,7 +476,8 @@ public static function render_version_switch_field(): void {
 			return;
 		}
 
-		$floor_notice = self::get_source()->get_floor_notice( self::get_version_floor() );
+		$floor = self::get_version_floor();
+		$floor_notice = $floor ? self::get_source()->get_floor_notice( $floor ) : '';
 
 		?>
 			<p>
diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
index 51f267c2f..6a09bc90e 100644
--- a/tests/unit/Settings/Version_Switch_Test.php
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -693,6 +693,49 @@ public function test_last_error_code_tolerates_the_previous_transient_shape(): v
 		$this->assertSame( '', Version_Switch::get_last_error_message() );
 	}
 
+	/**
+	 * A source that reports no floor has nothing to explain, so the floor notice
+	 * is not rendered at all.
+	 *
+	 * @return void
+	 */
+	public function test_floor_notice_is_omitted_when_the_source_reports_no_floor(): void {
+		$this->register_test_services();
+		$this->seed_catalogue( '3.9.2' );
+
+		$output = $this->render_version_switch_field();
+
+		$this->assertStringContainsString( '<select', $output );
+		$this->assertStringNotContainsString( 'are not installable', $output );
+	}
+
+	/**
+	 * A source that reports a floor explains where the catalogue stops.
+	 *
+	 * @return void
+	 */
+	public function test_floor_notice_is_rendered_when_the_source_reports_a_floor(): void {
+		$this->register_test_services();
+
+		set_transient(
+			$this->source->get_cache_key(),
+			[
+				'versions' => [
+					[
+						'version' => '3.9.2',
+						'url'     => 'https://example.org/code-snippets.3.9.2.zip',
+					],
+				],
+				'floor'    => '3.6.0',
+			],
+			HOUR_IN_SECONDS
+		);
+
+		$output = $this->render_version_switch_field();
+
+		$this->assertStringContainsString( 'Versions before 3.6.0 are not installable.', $output );
+	}
+
 	/**
 	 * The WordPress.org source drops the trunk entry and lists releases newest
 	 * first, and reports no floor because every release remains installable.

From 1685b60194d903a2bd28309563bf0ae2ec970356 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Wed, 14 Oct 2026 23:11:10 +0100
Subject: [PATCH 12/25] fix: record a refused package request the same way as a
 refused catalogue request

---
 src/php/Settings/Version_Switch.php | 32 +++++++++++++++++++++--------
 1 file changed, 24 insertions(+), 8 deletions(-)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index db28615c0..42a558f17 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -154,14 +154,7 @@ private static function get_catalogue(): array {
 		$result = $source->fetch_catalogue();
 
 		if ( is_wp_error( $result ) ) {
-			set_transient(
-				self::ERROR_KEY,
-				[
-					'code'    => $result->get_error_code(),
-					'message' => $result->get_error_message(),
-				],
-				self::ERROR_CACHE_DURATION
-			);
+			self::record_error( $result );
 			return $empty;
 		}
 
@@ -176,6 +169,28 @@ private static function get_catalogue(): array {
 		return $catalogue;
 	}
 
+	/**
+	 * Remember why the last request to the source failed.
+	 *
+	 * A source reads the code back through get_last_error_code() to decide
+	 * whether it is still available, so a package request refused for the same
+	 * reason as a catalogue request has to be recorded the same way.
+	 *
+	 * @param WP_Error $error Failure returned by the source.
+	 *
+	 * @return void
+	 */
+	private static function record_error( WP_Error $error ): void {
+		set_transient(
+			self::ERROR_KEY,
+			[
+				'code'    => $error->get_error_code(),
+				'message' => $error->get_error_message(),
+			],
+			self::ERROR_CACHE_DURATION
+		);
+	}
+
 	/**
 	 * Retrieve a list of plugin versions available for switching.
 	 *
@@ -386,6 +401,7 @@ public static function handle_version_switch( string $target_version ): array {
 
 		if ( is_wp_error( $package ) ) {
 			delete_transient( self::PROGRESS_KEY );
+			self::record_error( $package );
 
 			// The cached catalogue is stale when the source no longer recognises a
 			// version it listed, so discard it and let the next render refetch.

From 1bf8716379b2a09034d7e952e0c8db3e3599f6df Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Wed, 14 Oct 2026 23:11:20 +0100
Subject: [PATCH 13/25] feat: hide the refresh versions button while versions
 cannot be listed

---
 src/php/Settings/Version_Switch.php | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index 42a558f17..ec16e7f93 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -60,6 +60,32 @@ class Version_Switch {
 	public static function init(): void {
 		add_action( 'wp_ajax_code_snippets_switch_version', [ __CLASS__, 'ajax_switch_version' ] );
 		add_action( 'wp_ajax_code_snippets_refresh_versions', [ __CLASS__, 'ajax_refresh_versions' ] );
+		add_filter( 'code_snippets_settings_tab_contents', [ __CLASS__, 'hide_refresh_when_unavailable' ] );
+	}
+
+	/**
+	 * Drop the refresh button from the settings screen while versions cannot be
+	 * listed, since the unavailable notice already says what to do instead.
+	 *
+	 * @param array<string, array<int, array{0: string, 1: string}>> $contents Settings tab contents.
+	 *
+	 * @return array<string, array<int, array{0: string, 1: string}>>
+	 */
+	public static function hide_refresh_when_unavailable( array $contents ): array {
+		if ( empty( $contents['advanced'] ) || self::is_available() ) {
+			return $contents;
+		}
+
+		$contents['advanced'] = array_values(
+			array_filter(
+				$contents['advanced'],
+				function ( array $entry ): bool {
+					return [ 'version-switch', 'refresh_versions' ] !== $entry;
+				}
+			)
+		);
+
+		return $contents;
 	}
 
 	/**

From 1cb5819ac62d1f0f43a98c6916af6158dd4cfd3e Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Wed, 14 Oct 2026 23:11:31 +0100
Subject: [PATCH 14/25] fix: render the version switch warning inside the
 switcher instead of at the top of the screen

---
 src/js/services/settings/tabs.ts     |  4 ----
 src/php/Settings/Settings_Fields.php |  5 -----
 src/php/Settings/Settings_Layout.php |  1 -
 src/php/Settings/Version_Switch.php  | 11 ++++++++---
 4 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/src/js/services/settings/tabs.ts b/src/js/services/settings/tabs.ts
index a1c135456..5d4eb2351 100644
--- a/src/js/services/settings/tabs.ts
+++ b/src/js/services/settings/tabs.ts
@@ -13,10 +13,6 @@ const selectTab = (tabsWrapper: Element, tab: Element, section: string) => {
 	document.querySelectorAll('.cloud-message').forEach(element => {
 		element.classList.add('hidden')
 	})
-
-	if ('version-switch' !== section) {
-		document.getElementById('version-switch-warning')?.classList.add('hidden')
-	}
 }
 
 // Refresh the editor preview whenever tabs change. CodeMirror measures itself
diff --git a/src/php/Settings/Settings_Fields.php b/src/php/Settings/Settings_Fields.php
index 29db33bcb..08ab8e084 100644
--- a/src/php/Settings/Settings_Fields.php
+++ b/src/php/Settings/Settings_Fields.php
@@ -152,11 +152,6 @@ private function init_fields() {
 				'type'            => 'callback',
 				'render_callback' => [ '\\Code_Snippets\\Settings\\Version_Switch', 'render_refresh_versions_field' ],
 			],
-			'version_warning'  => [
-				'name'            => '',
-				'type'            => 'callback',
-				'render_callback' => [ '\\Code_Snippets\\Settings\\Version_Switch', 'render_version_switch_warning' ],
-			],
 		];
 
 		$this->fields['general'] = [
diff --git a/src/php/Settings/Settings_Layout.php b/src/php/Settings/Settings_Layout.php
index 88bf77337..05d866c72 100644
--- a/src/php/Settings/Settings_Layout.php
+++ b/src/php/Settings/Settings_Layout.php
@@ -94,7 +94,6 @@ public static function get_tab_contents(): array {
 				[ 'permissions', 'role_capabilities' ],
 				[ 'version-switch', 'version_switcher' ],
 				[ 'version-switch', 'refresh_versions' ],
-				[ 'version-switch', 'version_warning' ],
 				[ 'debug', 'reset_caches' ],
 				[ 'debug', 'database_update' ],
 				[ 'general', 'complete_uninstall' ],
diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index ec16e7f93..acbfc220e 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -541,6 +541,8 @@ public static function render_version_switch_field(): void {
 				<p class="description"><?php echo esc_html( $floor_notice ); ?></p>
 			<?php } ?>
 
+			<?php self::render_version_switch_warning(); ?>
+
 			<p>
 				<button type="button" id="switch-version-btn" class="button button-secondary" disabled>
 					<?php esc_html_e( 'Switch Version', 'code-snippets' ); ?>
@@ -706,13 +708,16 @@ public static function ajax_refresh_versions(): void {
 	}
 
 	/**
-	 * Render warning notice.
+	 * Render the warning shown once a different version is selected.
+	 *
+	 * The `inline` class keeps WordPress from moving the notice to the top of the
+	 * screen, away from the switcher it refers to.
 	 *
 	 * @return void
 	 */
-	public static function render_version_switch_warning(): void {
+	private static function render_version_switch_warning(): void {
 		?>
-		<div id="version-switch-warning" class="notice code-snippets-notice notice-warning hidden" role="region">
+		<div id="version-switch-warning" class="notice code-snippets-notice notice-warning inline hidden" role="region">
 			<p>
 				<strong><?php esc_html_e( 'Warning:', 'code-snippets' ); ?></strong>
 				<?php esc_html_e( 'Switching versions may cause compatibility issues. Always backup your site before switching versions.', 'code-snippets' ); ?>

From 3220e2c07982859453980921211f135203535681 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Wed, 14 Oct 2026 23:11:40 +0100
Subject: [PATCH 15/25] feat: let a version source attach a warning to a
 version

---
 src/js/services/settings/version.ts            |  8 ++++++++
 src/php/Settings/Version_Source.php            | 12 ++++++++++++
 src/php/Settings/Version_Switch.php            |  9 ++++++++-
 .../Settings/WordPress_Org_Version_Source.php  | 12 ++++++++++++
 .../unit/Settings/Recording_Version_Source.php | 18 ++++++++++++++++++
 5 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/src/js/services/settings/version.ts b/src/js/services/settings/version.ts
index b5b8514a5..5b7e7287b 100644
--- a/src/js/services/settings/version.ts
+++ b/src/js/services/settings/version.ts
@@ -42,9 +42,17 @@ const bindDropdown = (
 	currentVersion: string
 ): void => {
 	const warningNotice = document.getElementById('version-switch-warning')
+	const targetWarning = document.getElementById('version-switch-target-warning')
 
 	dropdown.addEventListener('change', () => {
 		const selectedVersion = dropdown.value
+		const selectedWarning = dropdown.selectedOptions.item(0)?.dataset.warning ?? ''
+
+		if (targetWarning) {
+			targetWarning.textContent = selectedWarning
+			targetWarning.hidden = !selectedWarning
+		}
+
 		if (!button) {
 			return
 		}
diff --git a/src/php/Settings/Version_Source.php b/src/php/Settings/Version_Source.php
index 62c0bb4a4..e690f8ac5 100644
--- a/src/php/Settings/Version_Source.php
+++ b/src/php/Settings/Version_Source.php
@@ -83,6 +83,18 @@ public function fetch_catalogue();
 	 */
 	public function get_floor_notice( string $floor ): string;
 
+	/**
+	 * Warn about a consequence of switching to a particular version, beyond the
+	 * general warning every switch carries.
+	 *
+	 * Shown when the version is selected. An empty string shows nothing extra.
+	 *
+	 * @param array<string, mixed> $version_info Catalogue entry for the version.
+	 *
+	 * @return string
+	 */
+	public function get_switch_warning( array $version_info ): string;
+
 	/**
 	 * Obtain the package for a version.
 	 *
diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index acbfc220e..8bd00bfe8 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -528,8 +528,14 @@ public static function render_version_switch_field(): void {
 				</label>
 				<select id="target_version" name="target_version">
 					<option value=""><?php esc_html_e( 'Select a version…', 'code-snippets' ); ?></option>
-					<?php foreach ( $available_versions as $version_info ) { ?>
+					<?php
+					foreach ( $available_versions as $version_info ) {
+						$switch_warning = self::get_source()->get_switch_warning( $version_info );
+						?>
 						<option value="<?php echo esc_attr( $version_info['version'] ); ?>"
+							<?php if ( $switch_warning ) { ?>
+								data-warning="<?php echo esc_attr( $switch_warning ); ?>"
+							<?php } ?>
 							<?php selected( $version_info['version'], $current_version ); ?>>
 							<?php echo esc_html( self::describe_version( $version_info, $current_version ) ); ?>
 						</option>
@@ -723,6 +729,7 @@ private static function render_version_switch_warning(): void {
 				<?php esc_html_e( 'Switching versions may cause compatibility issues. Always backup your site before switching versions.', 'code-snippets' ); ?>
 			</p>
 			<p><?php esc_html_e( 'Beta and release candidate builds are not recommended for production sites.', 'code-snippets' ); ?></p>
+			<p id="version-switch-target-warning" hidden></p>
 		</div>
 		<?php
 	}
diff --git a/src/php/Settings/WordPress_Org_Version_Source.php b/src/php/Settings/WordPress_Org_Version_Source.php
index f6351c1e9..3759b7302 100644
--- a/src/php/Settings/WordPress_Org_Version_Source.php
+++ b/src/php/Settings/WordPress_Org_Version_Source.php
@@ -120,6 +120,18 @@ public function get_floor_notice( string $floor ): string {
 		return '';
 	}
 
+	/**
+	 * Warn about switching to a particular version. Every WordPress.org build can
+	 * switch versions from this screen, so none needs a warning of its own.
+	 *
+	 * @param array<string, mixed> $version_info Catalogue entry for the version.
+	 *
+	 * @return string
+	 */
+	public function get_switch_warning( array $version_info ): string {
+		return '';
+	}
+
 	/**
 	 * Obtain the package for a version.
 	 *
diff --git a/tests/unit/Settings/Recording_Version_Source.php b/tests/unit/Settings/Recording_Version_Source.php
index 8788041b0..ca455ab30 100644
--- a/tests/unit/Settings/Recording_Version_Source.php
+++ b/tests/unit/Settings/Recording_Version_Source.php
@@ -43,6 +43,13 @@ class Recording_Version_Source implements Version_Source {
 		'cleanup' => false,
 	];
 
+	/**
+	 * Switch warnings keyed by the version they are shown for.
+	 *
+	 * @var array<string, string>
+	 */
+	public array $switch_warnings = [];
+
 	/**
 	 * Number of times the catalogue was fetched.
 	 *
@@ -118,6 +125,17 @@ public function get_floor_notice( string $floor ): string {
 		return 'Versions before ' . $floor . ' are not installable.';
 	}
 
+	/**
+	 * Warn about switching to a particular version.
+	 *
+	 * @param array<string, mixed> $version_info Catalogue entry for the version.
+	 *
+	 * @return string
+	 */
+	public function get_switch_warning( array $version_info ): string {
+		return $this->switch_warnings[ (string) $version_info['version'] ] ?? '';
+	}
+
 	/**
 	 * Obtain the package for a version.
 	 *

From 56163c881a5477d5217575bcb54f609024dbb15e Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Wed, 14 Oct 2026 23:11:54 +0100
Subject: [PATCH 16/25] fix: show the refreshing label while the version list
 refreshes

---
 src/js/services/settings/version.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/js/services/settings/version.ts b/src/js/services/settings/version.ts
index 5b7e7287b..f98ead3da 100644
--- a/src/js/services/settings/version.ts
+++ b/src/js/services/settings/version.ts
@@ -150,7 +150,7 @@ const bindRefresh = (
 		void (async (): Promise<void> => {
 			const original = btn.textContent ?? ''
 			btn.disabled = true
-			btn.textContent = i18n?.error ?? ''
+			btn.textContent = i18n?.refreshing ?? ''
 
 			try {
 				await postForm({

From dd109641f274320016e7a55d06bcaa3c205528bc Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Wed, 14 Oct 2026 23:12:02 +0100
Subject: [PATCH 17/25] chore: drop an inaccurate comment from the version
 switch script

---
 src/js/services/settings/version.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/js/services/settings/version.ts b/src/js/services/settings/version.ts
index f98ead3da..8f07f9d66 100644
--- a/src/js/services/settings/version.ts
+++ b/src/js/services/settings/version.ts
@@ -176,8 +176,6 @@ export const initVersionSwitch = (): void => {
 	const currentVersion = getCurrentVersion()
 	const config = window.code_snippets_version_switch
 
-	// The switcher renders as a notice with no controls when the site cannot list
-	// versions, and the script is still enqueued.
 	if (!config) {
 		return
 	}

From 8fdc77c756b54314f64d461529cefa88497b913c Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Wed, 14 Oct 2026 23:12:11 +0100
Subject: [PATCH 18/25] feat: give the version switch warning a yellow
 background

---
 src/css/common/_theme.scss | 1 +
 src/css/settings.scss      | 8 ++------
 2 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/src/css/common/_theme.scss b/src/css/common/_theme.scss
index 1ead0310f..440c59f06 100644
--- a/src/css/common/_theme.scss
+++ b/src/css/common/_theme.scss
@@ -14,6 +14,7 @@
 	--cs-color-surface-subtle: #f6f7f7;
 	--cs-color-surface-muted: #f0f0f1;
 	--cs-color-surface-info: #f0f6fc;
+	--cs-color-surface-warning: #f2ebc3;
 	--cs-color-border: #c3c4c7;
 	--cs-color-border-subtle: #dcdcde;
 	--cs-color-info: #72aee6;
diff --git a/src/css/settings.scss b/src/css/settings.scss
index 6abc544a3..f84bbdbd0 100644
--- a/src/css/settings.scss
+++ b/src/css/settings.scss
@@ -196,15 +196,11 @@ body.js {
 		margin-block-start: 20px !important;
 		padding: 12px 16px;
 		border-inline-start: 4px solid var(--cs-color-warning);
-		background: var(--cs-color-surface-subtle);
+		background: var(--cs-color-surface-warning);
 
 		p {
 			margin: 0;
-			color: #8f6914;
-
-			strong {
-				color: #8f6914;
-			}
+			color: var(--cs-color-text);
 		}
 	}
 

From 7be664ef821566530449e018aa7b38033274d8c9 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Wed, 14 Oct 2026 23:12:13 +0100
Subject: [PATCH 19/25] chore: add tests for version warnings and the refresh
 button

---
 tests/unit/Settings/Version_Switch_Test.php | 59 +++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
index 6a09bc90e..7e7e447c5 100644
--- a/tests/unit/Settings/Version_Switch_Test.php
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -480,6 +480,7 @@ public function test_failed_package_fetch_never_reaches_the_installer(): void {
 		$this->assertSame( [], $this->installer->installed );
 		$this->assertFalse( get_transient( self::PROGRESS_KEY ) );
 		$this->assertFalse( get_transient( $this->source->get_cache_key() ) );
+		$this->assertSame( 'version_source_package_error', Version_Switch::get_last_error_code() );
 	}
 
 	/**
@@ -646,6 +647,63 @@ public function test_populated_catalogue_renders_the_version_dropdown(): void {
 		$this->assertStringNotContainsString( 'no versions available to install', $output );
 	}
 
+	/**
+	 * The warning sits inside the switcher, above the button, and is marked
+	 * inline so WordPress does not move it to the top of the screen.
+	 *
+	 * @return void
+	 */
+	public function test_warning_renders_inline_above_the_switch_button(): void {
+		$this->register_test_services();
+		$this->seed_catalogue( '3.9.2' );
+
+		$output = $this->render_version_switch_field();
+
+		$this->assertMatchesRegularExpression( '/id="version-switch-warning" class="[^"]*\\binline\\b/', $output );
+		$this->assertLessThan( strpos( $output, 'id="switch-version-btn"' ), strpos( $output, 'id="version-switch-warning"' ) );
+	}
+
+	/**
+	 * A version the source warns about carries that warning on its option, and
+	 * other versions carry none.
+	 *
+	 * @return void
+	 */
+	public function test_source_switch_warning_is_attached_to_its_version(): void {
+		$this->register_test_services();
+		$this->seed_catalogue( '3.9.2' );
+		$this->source->switch_warnings = [ '3.9.2' => 'Switching back needs another route.' ];
+
+		$this->assertMatchesRegularExpression(
+			'/value="3\\.9\\.2"\\s+data-warning="Switching back needs another route\\."/',
+			$this->render_version_switch_field()
+		);
+
+		$this->source->switch_warnings = [];
+		$this->assertStringNotContainsString( 'data-warning=', $this->render_version_switch_field() );
+	}
+
+	/**
+	 * The refresh button is dropped while the source is unavailable, and kept
+	 * otherwise.
+	 *
+	 * @return void
+	 */
+	public function test_refresh_button_is_hidden_while_the_source_is_unavailable(): void {
+		$this->register_test_services();
+
+		$contents = [ 'advanced' => [ [ 'version-switch', 'version_switcher' ], [ 'version-switch', 'refresh_versions' ] ] ];
+
+		$this->assertSame( $contents, Version_Switch::hide_refresh_when_unavailable( $contents ) );
+
+		$this->source->available = false;
+
+		$this->assertSame(
+			[ [ 'version-switch', 'version_switcher' ] ],
+			Version_Switch::hide_refresh_when_unavailable( $contents )['advanced']
+		);
+	}
+
 	/**
 	 * The message behind a failed request is kept alongside its code, and a
 	 * successful fetch clears both.
@@ -808,6 +866,7 @@ public function test_wordpress_org_source_is_always_available_and_reports_nothin
 		$this->assertTrue( $source->is_available() );
 		$this->assertSame( self::WP_ORG_CACHE_KEY, $source->get_cache_key() );
 		$this->assertSame( '', $source->get_floor_notice( '3.6.0' ) );
+		$this->assertSame( '', $source->get_switch_warning( [ 'version' => '3.0.0' ] ) );
 
 		$source->report_installed_version( '3.9.2' );
 

From 809691d9c1a1b35b49b18f41fb7ca66bead75b52 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Mon, 19 Oct 2026 15:30:41 +0100
Subject: [PATCH 20/25] fix: resolve the version switcher source each time it
 is used

---
 src/php/Settings/Version_Switch.php         | 34 +++++----------------
 tests/unit/Settings/Version_Switch_Test.php | 27 +++++++++++-----
 2 files changed, 27 insertions(+), 34 deletions(-)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index 8bd00bfe8..d19b611f5 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -45,13 +45,6 @@ class Version_Switch {
 	 */
 	private const PROGRESS_TIMEOUT = 5 * MINUTE_IN_SECONDS;
 
-	/**
-	 * Source supplying the available versions.
-	 *
-	 * @var Version_Source|null
-	 */
-	private static ?Version_Source $source = null;
-
 	/**
 	 * Initialise class.
 	 *
@@ -94,18 +87,14 @@ function ( array $entry ): bool {
 	 * @return Version_Source
 	 */
 	public static function get_source(): Version_Source {
-		if ( null === self::$source ) {
-			/**
-			 * Filters the source the version switcher lists versions from.
-			 *
-			 * @param Version_Source $source Default source.
-			 */
-			$source = apply_filters( 'code_snippets_version_source', new WordPress_Org_Version_Source() );
-
-			self::$source = $source instanceof Version_Source ? $source : new WordPress_Org_Version_Source();
-		}
+		/**
+		 * Filters the source the version switcher lists versions from.
+		 *
+		 * @param Version_Source $source Default source.
+		 */
+		$source = apply_filters( 'code_snippets_version_source', new WordPress_Org_Version_Source() );
 
-		return self::$source;
+		return $source instanceof Version_Source ? $source : new WordPress_Org_Version_Source();
 	}
 
 	/**
@@ -124,15 +113,6 @@ public static function get_installer(): Package_Installer {
 		return $installer instanceof Package_Installer ? $installer : new Upgrader_Package_Installer();
 	}
 
-	/**
-	 * Discard the memoised source, so the next call resolves the filter again.
-	 *
-	 * @return void
-	 */
-	public static function reset_source(): void {
-		self::$source = null;
-	}
-
 	/**
 	 * Determine whether versions can currently be listed.
 	 *
diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
index 7e7e447c5..e7085c5d8 100644
--- a/tests/unit/Settings/Version_Switch_Test.php
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -72,8 +72,6 @@ class Version_Switch_Test extends UnitTestCase {
 	 */
 	public function set_up() {
 		parent::set_up();
-
-		Version_Switch::reset_source();
 		Version_Switch::clear_version_caches();
 		delete_transient( self::WP_ORG_CACHE_KEY );
 
@@ -102,7 +100,6 @@ public function tear_down() {
 		$this->installer = null;
 
 		delete_transient( self::WP_ORG_CACHE_KEY );
-		Version_Switch::reset_source();
 
 		parent::tear_down();
 	}
@@ -166,8 +163,6 @@ private function register_test_services(): void {
 
 		$this->registered_filters[] = [ 'code_snippets_version_source', $supply_source ];
 		$this->registered_filters[] = [ 'code_snippets_package_installer', $supply_installer ];
-
-		Version_Switch::reset_source();
 	}
 
 	/**
@@ -250,12 +245,31 @@ public function test_filters_replace_the_source_and_installer(): void {
 		}
 
 		$this->registered_filters = [];
-		Version_Switch::reset_source();
 
 		$this->assertInstanceOf( WordPress_Org_Version_Source::class, Version_Switch::get_source() );
 		$this->assertInstanceOf( Upgrader_Package_Installer::class, Version_Switch::get_installer() );
 	}
 
+	/**
+	 * A source registered after the switcher was first used still takes effect,
+	 * as an edition may add its filter later in the request than the first lookup.
+	 *
+	 * @return void
+	 */
+	public function test_a_source_registered_after_first_use_is_honoured(): void {
+		$this->assertInstanceOf( WordPress_Org_Version_Source::class, Version_Switch::get_source() );
+
+		$source = new Recording_Version_Source();
+		$supply_source = function () use ( $source ) {
+			return $source;
+		};
+
+		add_filter( 'code_snippets_version_source', $supply_source );
+		$this->registered_filters[] = [ 'code_snippets_version_source', $supply_source ];
+
+		$this->assertSame( $source, Version_Switch::get_source() );
+	}
+
 	/**
 	 * A source that returns something other than a Version_Source is ignored, so
 	 * a misbehaving filter cannot leave the switcher without one.
@@ -271,7 +285,6 @@ public function test_an_invalid_filter_return_falls_back_to_the_default(): void
 		add_filter( 'code_snippets_package_installer', $strip, 99 );
 		$this->registered_filters[] = [ 'code_snippets_version_source', $strip ];
 		$this->registered_filters[] = [ 'code_snippets_package_installer', $strip ];
-		Version_Switch::reset_source();
 
 		$this->assertInstanceOf( WordPress_Org_Version_Source::class, Version_Switch::get_source() );
 		$this->assertInstanceOf( Upgrader_Package_Installer::class, Version_Switch::get_installer() );

From 2e2b55d47239027a3692819ef9d27fe794d4d21f Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Mon, 19 Oct 2026 15:30:47 +0100
Subject: [PATCH 21/25] fix: log why a version switch install failed

---
 src/php/Settings/Version_Switch.php         |  6 +++
 tests/unit/Settings/Version_Switch_Test.php | 55 ++++++++++++++++++++-
 2 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index d19b611f5..973f98c09 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -432,6 +432,12 @@ public static function handle_version_switch( string $target_version ): array {
 					// translators: %s: reason the installation failed.
 					__( 'Failed to switch versions: %s', 'code-snippets' ),
 					$install_result->get_error_message()
+				),
+				sprintf(
+					'target=%s, code=%s, messages=%s',
+					$target_version,
+					$install_result->get_error_code(),
+					implode( ' | ', $install_result->get_error_messages() )
 				)
 			);
 		}
diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
index e7085c5d8..3008f1758 100644
--- a/tests/unit/Settings/Version_Switch_Test.php
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -206,6 +206,26 @@ private function create_package_file(): string {
 		return tempnam( get_temp_dir(), 'cs-pkg' );
 	}
 
+	/**
+	 * Run a callback with the PHP error log written to a temporary file.
+	 *
+	 * @param callable $callback Code that may write to the error log.
+	 *
+	 * @return string What was written to the log.
+	 */
+	private function capture_error_log( callable $callback ): string {
+		$log_file = tempnam( get_temp_dir(), 'cs-log' );
+		$previous_log = ini_set( 'error_log', $log_file ); // phpcs:ignore WordPress.PHP.IniSet.Risky
+
+		try {
+			$callback();
+			return (string) file_get_contents( $log_file ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
+		} finally {
+			ini_set( 'error_log', (string) $previous_log ); // phpcs:ignore WordPress.PHP.IniSet.Risky
+			wp_delete_file( $log_file );
+		}
+	}
+
 	/**
 	 * Capture the markup the version switcher field renders.
 	 *
@@ -516,7 +536,12 @@ public function test_failed_install_clears_the_progress_marker_and_package(): vo
 
 		$this->installer->result = new WP_Error( 'package_install_failed', 'The package could not be installed.' );
 
-		$result = Version_Switch::handle_version_switch( '3.9.2' );
+		$result = [];
+		$this->capture_error_log(
+			function () use ( &$result ) {
+				$result = Version_Switch::handle_version_switch( '3.9.2' );
+			}
+		);
 
 		$this->assertFalse( $result['success'] );
 		$this->assertSame( [ $package_path ], $this->installer->installed );
@@ -525,6 +550,34 @@ public function test_failed_install_clears_the_progress_marker_and_package(): vo
 		$this->assertSame( [], $this->source->reported );
 	}
 
+	/**
+	 * A failed install is written to the server log with the version and the
+	 * installer's reason, so it can be diagnosed after the browser message is gone.
+	 *
+	 * @return void
+	 */
+	public function test_failed_install_is_logged_with_its_reason(): void {
+		$this->register_test_services();
+		$this->authorise();
+		$this->seed_catalogue( '3.9.2' );
+
+		$this->source->package = [
+			'package' => 'https://example.org/code-snippets.3.9.2.zip',
+			'cleanup' => false,
+		];
+
+		$this->installer->result = new WP_Error( 'package_install_failed', 'Could not create the plugin directory.' );
+
+		$logged = $this->capture_error_log(
+			function () {
+				Version_Switch::handle_version_switch( '3.9.2' );
+			}
+		);
+
+		$this->assertStringContainsString( '3.9.2', $logged );
+		$this->assertStringContainsString( 'Could not create the plugin directory.', $logged );
+	}
+
 	/**
 	 * A completed switch deletes the package, clears the progress marker and the
 	 * now-outdated catalogue, and tells the source what landed on disk.

From e8ad7044fdc8d63af184a11068be786ca9f86947 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Mon, 19 Oct 2026 15:30:52 +0100
Subject: [PATCH 22/25] fix: clear the WordPress.org version list along with
 the active source's

---
 src/php/Settings/Version_Switch.php         |  1 +
 tests/unit/Settings/Version_Switch_Test.php | 24 +++++++++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index 973f98c09..57f8715bb 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -284,6 +284,7 @@ public static function is_version_switch_in_progress(): bool {
 	 */
 	public static function clear_version_caches(): void {
 		delete_transient( self::get_source()->get_cache_key() );
+		delete_transient( ( new WordPress_Org_Version_Source() )->get_cache_key() );
 		delete_transient( self::PROGRESS_KEY );
 		delete_transient( self::ERROR_KEY );
 	}
diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
index 3008f1758..095e2d4cc 100644
--- a/tests/unit/Settings/Version_Switch_Test.php
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -817,6 +817,30 @@ public function test_last_error_code_tolerates_the_previous_transient_shape(): v
 		$this->assertSame( '', Version_Switch::get_last_error_message() );
 	}
 
+	/**
+	 * Clearing the caches also removes a catalogue cached by the default source,
+	 * which a site keeps after another source takes over.
+	 *
+	 * @return void
+	 */
+	public function test_clearing_caches_removes_the_default_source_catalogue(): void {
+		$this->register_test_services();
+		$this->seed_catalogue( '3.9.2' );
+		set_transient(
+			self::WP_ORG_CACHE_KEY,
+			[
+				'versions' => [],
+				'floor'    => '',
+			],
+			HOUR_IN_SECONDS
+		);
+
+		Version_Switch::clear_version_caches();
+
+		$this->assertFalse( get_transient( $this->source->get_cache_key() ) );
+		$this->assertFalse( get_transient( self::WP_ORG_CACHE_KEY ) );
+	}
+
 	/**
 	 * A source that reports no floor has nothing to explain, so the floor notice
 	 * is not rendered at all.

From 9423e971c7ed288f67c75a89161c37fb1b4e5940 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Mon, 19 Oct 2026 15:30:57 +0100
Subject: [PATCH 23/25] fix: report a failed version list refresh instead of
 success

---
 src/php/Settings/Version_Switch.php           |  16 +++
 src/php/Settings/settings.php                 |  49 ++++----
 .../Settings/Version_Switch_Ajax_Test.php     | 107 ++++++++++++++++++
 tests/unit/Settings/Version_Switch_Test.php   |  47 ++++++++
 4 files changed, 200 insertions(+), 19 deletions(-)
 create mode 100644 tests/unit/Settings/Version_Switch_Ajax_Test.php

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index 57f8715bb..9e99d9de7 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -259,6 +259,17 @@ public static function refresh_available_versions(): array {
 		return self::get_available_versions();
 	}
 
+	/**
+	 * Explain why versions could not be listed after a refresh.
+	 *
+	 * @return string Reason the source is unavailable or its request failed, or an empty string when neither.
+	 */
+	public static function get_refresh_failure(): string {
+		$source = self::get_source();
+
+		return $source->is_available() ? self::get_last_error_message() : $source->get_unavailable_notice()['message'];
+	}
+
 	/**
 	 * Retrieve the current plugin version.
 	 *
@@ -696,6 +707,11 @@ public static function ajax_refresh_versions(): void {
 		}
 
 		self::refresh_available_versions();
+		$failure = self::get_refresh_failure();
+
+		if ( $failure ) {
+			wp_send_json_error( [ 'message' => $failure ] );
+		}
 
 		wp_send_json_success( [ 'message' => __( 'Available versions updated successfully.', 'code-snippets' ) ] );
 	}
diff --git a/src/php/Settings/settings.php b/src/php/Settings/settings.php
index bb659a777..6f9a77c72 100644
--- a/src/php/Settings/settings.php
+++ b/src/php/Settings/settings.php
@@ -407,27 +407,38 @@ function process_settings_actions( array $input ): ?array {
 		// versioned groups (current, previous and legacy) all go too.
 		flush_versioned_cache_groups( (string) get_option( 'code_snippets_cache_version', '' ) );
 
-		// Refetched rather than merely discarded: resetting caches before a
-		// rollback is also how an administrator checks what the version source is
-		// serving right now, which a cleared cache alone would not show until the
-		// switcher was next rendered.
+		// Resetting caches before a rollback is also how an administrator checks
+		// what the version source is serving now, so the versions are fetched again.
 		$available_versions = Version_Switch::refresh_available_versions();
-
-		add_settings_error(
-			OPTION_NAME,
-			'snippet_caches_reset',
-			sprintf(
-				/* translators: %d: number of plugin versions available to install. */
-				_n(
-					'Successfully reset snippets caches. %d plugin version is available to install.',
-					'Successfully reset snippets caches. %d plugin versions are available to install.',
-					count( $available_versions ),
-					'code-snippets'
+		$refresh_failure = Version_Switch::get_refresh_failure();
+
+		if ( $refresh_failure ) {
+			add_settings_error(
+				OPTION_NAME,
+				'snippet_caches_reset',
+				sprintf(
+					/* translators: %s: reason the plugin versions could not be listed. */
+					__( 'Successfully reset snippets caches, but the available plugin versions could not be listed: %s', 'code-snippets' ),
+					$refresh_failure
+				)
+			);
+		} else {
+			add_settings_error(
+				OPTION_NAME,
+				'snippet_caches_reset',
+				sprintf(
+					/* translators: %d: number of plugin versions available to install. */
+					_n(
+						'Successfully reset snippets caches. %d plugin version is available to install.',
+						'Successfully reset snippets caches. %d plugin versions are available to install.',
+						count( $available_versions ),
+						'code-snippets'
+					),
+					count( $available_versions )
 				),
-				count( $available_versions )
-			),
-			'updated'
-		);
+				'updated'
+			);
+		}
 	}
 
 	return null;
diff --git a/tests/unit/Settings/Version_Switch_Ajax_Test.php b/tests/unit/Settings/Version_Switch_Ajax_Test.php
new file mode 100644
index 000000000..0fbcd506b
--- /dev/null
+++ b/tests/unit/Settings/Version_Switch_Ajax_Test.php
@@ -0,0 +1,107 @@
+<?php
+
+namespace Code_Snippets\Settings;
+
+use WP_Ajax_UnitTestCase;
+use WPAjaxDieContinueException;
+use WP_Error;
+
+require_once __DIR__ . '/Recording_Version_Source.php';
+
+/**
+ * Tests for the version switcher's AJAX handlers.
+ *
+ * @group version-switch
+ * @group ajax
+ */
+class Version_Switch_Ajax_Test extends WP_Ajax_UnitTestCase {
+
+	/**
+	 * Source registered on the seam filter for the duration of a test.
+	 *
+	 * @var Recording_Version_Source
+	 */
+	private Recording_Version_Source $source;
+
+	/**
+	 * Callback supplying the recording source.
+	 *
+	 * @var callable
+	 */
+	private $supply_source;
+
+	/**
+	 * Set up before each test.
+	 *
+	 * @return void
+	 */
+	public function set_up() {
+		parent::set_up();
+
+		$this->source = new Recording_Version_Source();
+		$source = $this->source;
+		$this->supply_source = function () use ( $source ) {
+			return $source;
+		};
+
+		add_filter( 'code_snippets_version_source', $this->supply_source );
+		Version_Switch::init();
+		Version_Switch::clear_version_caches();
+
+		$this->_setRole( 'administrator' );
+	}
+
+	/**
+	 * Clean up after each test.
+	 *
+	 * @return void
+	 */
+	public function tear_down() {
+		Version_Switch::clear_version_caches();
+		remove_filter( 'code_snippets_version_source', $this->supply_source );
+
+		parent::tear_down();
+	}
+
+	/**
+	 * Run the refresh handler and decode the JSON it sent.
+	 *
+	 * @return array<string, mixed>
+	 */
+	private function refresh_versions(): array {
+		$_POST['nonce'] = wp_create_nonce( 'code_snippets_refresh_versions' );
+
+		try {
+			$this->_handleAjax( 'code_snippets_refresh_versions' );
+		} catch ( WPAjaxDieContinueException $exception ) {
+			unset( $exception );
+		}
+
+		return json_decode( $this->_last_response, true );
+	}
+
+	/**
+	 * A refresh whose request fails reports the failure instead of success.
+	 *
+	 * @return void
+	 */
+	public function test_failed_refresh_is_reported_as_an_error(): void {
+		$this->source->catalogue = new WP_Error( 'version_source_request_error', 'The version service is down.' );
+
+		$response = $this->refresh_versions();
+
+		$this->assertFalse( $response['success'] );
+		$this->assertSame( 'The version service is down.', $response['data']['message'] );
+	}
+
+	/**
+	 * A refresh that fetches a catalogue reports success.
+	 *
+	 * @return void
+	 */
+	public function test_successful_refresh_is_reported_as_success(): void {
+		$response = $this->refresh_versions();
+
+		$this->assertTrue( $response['success'] );
+	}
+}
diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
index 095e2d4cc..92ce524d1 100644
--- a/tests/unit/Settings/Version_Switch_Test.php
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -226,6 +226,19 @@ private function capture_error_log( callable $callback ): string {
 		}
 	}
 
+	/**
+	 * Retrieve the notice added by the most recent cache reset.
+	 *
+	 * @return array{type: string, message: string}
+	 */
+	private function get_reset_caches_notice(): array {
+		$notices = wp_list_filter( get_settings_errors( OPTION_NAME ), [ 'code' => 'snippet_caches_reset' ] );
+
+		$this->assertNotEmpty( $notices, 'resetting caches should add a notice' );
+
+		return end( $notices );
+	}
+
 	/**
 	 * Capture the markup the version switcher field renders.
 	 *
@@ -841,6 +854,40 @@ public function test_clearing_caches_removes_the_default_source_catalogue(): voi
 		$this->assertFalse( get_transient( self::WP_ORG_CACHE_KEY ) );
 	}
 
+	/**
+	 * Resetting the caches reports why versions could not be fetched again,
+	 * rather than reporting success with none available.
+	 *
+	 * @return void
+	 */
+	public function test_reset_caches_reports_a_failed_refresh(): void {
+		$this->register_test_services();
+		$this->source->catalogue = new WP_Error( 'version_source_request_error', 'The version service is down.' );
+
+		process_settings_actions( [ 'debug' => [ 'reset_caches' => '1' ] ] );
+
+		$notice = $this->get_reset_caches_notice();
+		$this->assertSame( 'error', $notice['type'] );
+		$this->assertStringContainsString( 'The version service is down.', $notice['message'] );
+	}
+
+	/**
+	 * Resetting the caches with no source available explains why rather than
+	 * reporting none to install.
+	 *
+	 * @return void
+	 */
+	public function test_reset_caches_reports_an_unavailable_source(): void {
+		$this->register_test_services();
+		$this->source->available = false;
+
+		process_settings_actions( [ 'debug' => [ 'reset_caches' => '1' ] ] );
+
+		$notice = $this->get_reset_caches_notice();
+		$this->assertSame( 'error', $notice['type'] );
+		$this->assertStringContainsString( Version_Switch::get_unavailable_notice()['message'], $notice['message'] );
+	}
+
 	/**
 	 * A source that reports no floor has nothing to explain, so the floor notice
 	 * is not rendered at all.

From 05865095d652c17e8fefd80a38dc9382521eaae6 Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Mon, 19 Oct 2026 15:31:03 +0100
Subject: [PATCH 24/25] chore: drop support for an error transient shape that
 was never stored

---
 src/php/Settings/Version_Switch.php         |  9 +--------
 tests/unit/Settings/Version_Switch_Test.php | 13 -------------
 2 files changed, 1 insertion(+), 21 deletions(-)

diff --git a/src/php/Settings/Version_Switch.php b/src/php/Settings/Version_Switch.php
index 9e99d9de7..c743e9f9d 100644
--- a/src/php/Settings/Version_Switch.php
+++ b/src/php/Settings/Version_Switch.php
@@ -218,19 +218,12 @@ public static function get_version_floor(): string {
 	/**
 	 * Retrieve the code of the last catalogue request failure.
 	 *
-	 * Sites upgrading mid-cache still hold the previous shape — a bare code —
-	 * for up to ERROR_CACHE_DURATION.
-	 *
 	 * @return string
 	 */
 	public static function get_last_error_code(): string {
 		$error = get_transient( self::ERROR_KEY );
 
-		if ( is_array( $error ) ) {
-			return isset( $error['code'] ) ? (string) $error['code'] : '';
-		}
-
-		return is_string( $error ) ? $error : '';
+		return is_array( $error ) && isset( $error['code'] ) ? (string) $error['code'] : '';
 	}
 
 	/**
diff --git a/tests/unit/Settings/Version_Switch_Test.php b/tests/unit/Settings/Version_Switch_Test.php
index 92ce524d1..49be9d714 100644
--- a/tests/unit/Settings/Version_Switch_Test.php
+++ b/tests/unit/Settings/Version_Switch_Test.php
@@ -817,19 +817,6 @@ public function test_last_error_message_is_stored_and_cleared_with_the_code(): v
 		$this->assertSame( '', Version_Switch::get_last_error_message() );
 	}
 
-	/**
-	 * A site still holding the previous transient shape — a bare error code —
-	 * reports that code rather than a mangled one.
-	 *
-	 * @return void
-	 */
-	public function test_last_error_code_tolerates_the_previous_transient_shape(): void {
-		set_transient( self::ERROR_KEY, 'version_source_request_error', MINUTE_IN_SECONDS );
-
-		$this->assertSame( 'version_source_request_error', Version_Switch::get_last_error_code() );
-		$this->assertSame( '', Version_Switch::get_last_error_message() );
-	}
-
 	/**
 	 * Clearing the caches also removes a catalogue cached by the default source,
 	 * which a site keeps after another source takes over.

From d610baed87250b394c0632fa5f9220291bdec52e Mon Sep 17 00:00:00 2001
From: lightbulbman <atif@lightbulb.studio>
Date: Mon, 19 Oct 2026 15:31:07 +0100
Subject: [PATCH 25/25] fix: show version switch messages as text and keep them
 visible

---
 src/js/services/settings/version.ts | 27 +++++++++++++++------------
 tests/e2e/version-switch.spec.ts    | 26 ++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 12 deletions(-)
 create mode 100644 tests/e2e/version-switch.spec.ts

diff --git a/src/js/services/settings/version.ts b/src/js/services/settings/version.ts
index 8f07f9d66..7e1f70e6a 100644
--- a/src/js/services/settings/version.ts
+++ b/src/js/services/settings/version.ts
@@ -69,6 +69,16 @@ const bindDropdown = (
 
 const SUCCESS_RELOAD_MS = 3000
 
+const showResult = (result: HTMLElement, type: 'warning' | 'info' | 'success' | 'error', message = ''): void => {
+	const paragraph = document.createElement('p')
+	paragraph.textContent = message
+
+	// Admin notices without the plugin's own class are hidden on its screens.
+	result.className = `notice notice-${type} code-snippets-notice`
+	result.replaceChildren(paragraph)
+	result.style.display = ''
+}
+
 const postForm = async (data: Record<string, string>, config: VersionConfig): Promise<AjaxResponse> => {
 	const body = new URLSearchParams()
 	Object.keys(data).forEach(k => body.append(k, data[k]))
@@ -98,9 +108,7 @@ const bindSwitch = (
 		void (async (): Promise<void> => {
 			const targetVersion = dropdown.value
 			if (!targetVersion || targetVersion === currentVersion) {
-				result.className = 'notice notice-warning'
-				result.innerHTML = `<p>${i18n?.selectDifferent}</p>`
-				result.style.display = ''
+				showResult(result, 'warning', i18n?.selectDifferent)
 				return
 			}
 
@@ -108,9 +116,7 @@ const bindSwitch = (
 			const originalText = button.textContent ?? ''
 			button.textContent = i18n?.switching ?? ''
 
-			result.className = 'notice notice-info'
-			result.innerHTML = `<p>${i18n?.processing}</p>`
-			result.style.display = ''
+			showResult(result, 'info', i18n?.processing)
 
 			try {
 				const response = await postForm({
@@ -120,19 +126,16 @@ const bindSwitch = (
 				}, cfg)
 
 				if (response.success) {
-					result.className = 'notice notice-success'
-					result.innerHTML = `<p>${response.data?.message ?? ''}</p>`
+					showResult(result, 'success', response.data?.message ?? '')
 					setTimeout(() => window.location.reload(), SUCCESS_RELOAD_MS)
 					return
 				}
 
-				result.className = 'notice notice-error'
-				result.innerHTML = `<p>${response.data?.message ?? i18n?.error}</p>`
+				showResult(result, 'error', response.data?.message ?? i18n?.error)
 				button.disabled = false
 				button.textContent = originalText
 			} catch (_err) {
-				result.className = 'notice notice-error'
-				result.innerHTML = `<p>${i18n?.errorSwitch}</p>`
+				showResult(result, 'error', i18n?.errorSwitch)
 				button.disabled = false
 				button.textContent = originalText
 			}
diff --git a/tests/e2e/version-switch.spec.ts b/tests/e2e/version-switch.spec.ts
new file mode 100644
index 000000000..2f360ca95
--- /dev/null
+++ b/tests/e2e/version-switch.spec.ts
@@ -0,0 +1,26 @@
+import { expect, test } from '@playwright/test'
+import { URLS } from './helpers/constants'
+
+const MARKUP_MESSAGE = '<img id="injected-markup" src="x"> Could not switch versions.'
+
+test.describe('Version switcher', () => {
+	test('shows the message returned for a switch as text', async ({ page }) => {
+		await page.route('**/wp-admin/admin-ajax.php', route =>
+			route.request().postData()?.includes('action=code_snippets_switch_version')
+				? route.fulfill({
+					contentType: 'application/json',
+					body: JSON.stringify({ success: false, data: { message: MARKUP_MESSAGE } })
+				})
+				: route.continue())
+
+		await page.goto(`${URLS.SETTINGS_ADMIN}&section=advanced`)
+
+		const versions = page.getByLabel('Switch to Version:')
+		const oldestVersion = await versions.locator('option').last().getAttribute('value')
+		await versions.selectOption(oldestVersion ?? '')
+		await page.getByRole('button', { name: 'Switch Version' }).click()
+
+		await expect(page.getByText(MARKUP_MESSAGE)).toBeVisible()
+		await expect(page.locator('#injected-markup')).toHaveCount(0)
+	})
+})