refactor(explore): rename misnamed "tag cloud" to "visual clusters"

The visual k-means cluster feature was confusingly named tag_cloud / tagCloud /
TagCloud across the whole stack, while the actual tag list is explore_tags — the
two were trivially easy to mix up (and did cause confusion). Rename the cluster
side to visual_cluster / visualCluster / VisualCluster everywhere: command
get_tag_cloud -> get_visual_clusters (+ lib.rs registration and the invoke
string), VisualClusterEntry, the store fields/actions/tokens, and the mock
backend. Old names are retired rather than reused, so any missed reference fails
loudly instead of silently resolving to the wrong concept.

The tags side keeps its accurate explore_tags naming, and the user-facing
"Tag Cloud" UI label is unchanged.

Also rename the SQLite tag_cloud_cache table -> visual_cluster_cache (the old
table is dropped during schema setup — it is a disposable cache already
invalidated by the clustering version bump) and the TagCloud.tsx component file
-> ExploreView.tsx, since it is the Explore container hosting both the cluster
and tag views.

src-tauri/src/commands.rs

@@ -1161,7 +1161,7 @@ pub async fn reset_generated_captions(
 }
 
 #[derive(Serialize, Deserialize)]
-pub struct TagCloudEntry {
+pub struct VisualClusterEntry {
     pub count: usize,
     pub representative_image_id: i64,
     pub thumbnail_path: Option<String>,
@@ -1174,10 +1174,10 @@ pub struct TagCloudEntry {
 /// Results are cached in SQLite keyed by a hash of the embedded image IDs, so repeated
 /// calls (including across app restarts) return instantly when the library hasn't changed.
 #[tauri::command]
-pub async fn get_tag_cloud(
+pub async fn get_visual_clusters(
     db: State<'_, DbState>,
     folder_id: Option<i64>,
-) -> Result<Vec<TagCloudEntry>, String> {
+) -> Result<Vec<VisualClusterEntry>, String> {
     let folder_scope = match folder_id {
         Some(id) => format!("folder_{id}"),
         None => "all".to_string(),
@@ -1214,10 +1214,10 @@ pub async fn get_tag_cloud(
     // Try to return a valid SQLite cache before loading any embeddings.
     {
         let conn = db.get().map_err(|e| e.to_string())?;
-        if let Some(json) = db::get_tag_cloud_cache(&conn, &folder_scope, current_hash)
+        if let Some(json) = db::get_visual_cluster_cache(&conn, &folder_scope, current_hash)
             .map_err(|e| e.to_string())?
         {
-            if let Ok(entries) = serde_json::from_str::<Vec<TagCloudEntry>>(&json) {
+            if let Ok(entries) = serde_json::from_str::<Vec<VisualClusterEntry>>(&json) {
                 // Reject cache entries written before image_ids were tracked — they all
                 // have empty image_ids which causes "No media found" when a cluster is opened.
                 if entries.iter().all(|e| !e.image_ids.is_empty()) {
@@ -1247,12 +1247,12 @@ pub async fn get_tag_cloud(
     let kmeans_start = std::time::Instant::now();
     let (centroids, cluster_counts, assignments) = kmeans_cosine(&points, k, 40);
     log::debug!(
-        "tag-cloud clustering: {n} embeddings, k={k}, sampled={} → {:.2?}",
+        "visual-cluster clustering: {n} embeddings, k={k}, sampled={} → {:.2?}",
         n > MAX_KMEANS_SAMPLE,
         kmeans_start.elapsed(),
     );
 
-    let mut entries: Vec<TagCloudEntry> = Vec::new();
+    let mut entries: Vec<VisualClusterEntry> = Vec::new();
     let mut order: Vec<usize> = (0..k).collect();
     order.sort_unstable_by(|&a, &b| cluster_counts[b].cmp(&cluster_counts[a]));
 
@@ -1285,7 +1285,7 @@ pub async fn get_tag_cloud(
             .ok()
             .and_then(|img| img.thumbnail_path);
 
-        entries.push(TagCloudEntry {
+        entries.push(VisualClusterEntry {
             count,
             representative_image_id: best_id,
             thumbnail_path,
@@ -1296,8 +1296,8 @@ pub async fn get_tag_cloud(
     // Persist to SQLite. The cache is best-effort, but a silent write failure here
     // would defeat the whole optimization (every visit would recompute), so log it.
     if let Ok(json) = serde_json::to_string(&entries) {
-        if let Err(e) = db::set_tag_cloud_cache(&conn, &folder_scope, current_hash, &json) {
-            log::warn!("failed to persist tag-cloud cache for {folder_scope}: {e}");
+        if let Err(e) = db::set_visual_cluster_cache(&conn, &folder_scope, current_hash, &json) {
+            log::warn!("failed to persist visual-cluster cache for {folder_scope}: {e}");
         }
     }
 
@@ -1861,7 +1861,7 @@ fn normalize(v: &mut [f32]) {
 /// large libraries while the full assignment still places every image.
 const MAX_KMEANS_SAMPLE: usize = 3000;
 
-/// Bumped whenever the clustering algorithm changes so persisted tag-cloud caches
+/// Bumped whenever the clustering algorithm changes so persisted visual-cluster caches
 /// computed by an older algorithm are invalidated and recomputed on next view.
 const CLUSTER_CACHE_VERSION: &str = "sampled-v2";
 

src-tauri/src/db.rs

@@ -267,12 +267,16 @@ pub fn migrate(conn: &Connection) -> Result<()> {
             UNIQUE(image_id, tag)
         );
 
-        CREATE TABLE IF NOT EXISTS tag_cloud_cache (
+        CREATE TABLE IF NOT EXISTS visual_cluster_cache (
             folder_scope    TEXT PRIMARY KEY,
             image_ids_hash  INTEGER NOT NULL,
             entries_json    TEXT NOT NULL,
             created_at      TEXT NOT NULL DEFAULT (datetime('now'))
         );
+        -- Renamed from the misnamed tag_cloud_cache (it caches visual clusters,
+        -- not tags). The cache is disposable and was already invalidated by a
+        -- cluster-algorithm version bump, so the old table is simply dropped.
+        DROP TABLE IF EXISTS tag_cloud_cache;
 
         CREATE TABLE IF NOT EXISTS duplicate_scan_cache (
             folder_scope    TEXT PRIMARY KEY,
@@ -407,7 +411,7 @@ fn remove_filtered_ai_tags(conn: &Connection) -> Result<()> {
             delete_stmt.execute([id])?;
         }
     }
-    tx.execute("DELETE FROM tag_cloud_cache", [])?;
+    tx.execute("DELETE FROM visual_cluster_cache", [])?;
     tx.commit()?;
 
     log::info!(
@@ -2799,9 +2803,9 @@ pub fn rename_tag(conn: &Connection, from: &str, to: &str) -> Result<()> {
     )?;
     // …then drop the now-duplicate leftovers still under the old name.
     tx.execute("DELETE FROM image_tags WHERE tag = ?1", params![from])?;
-    // The tag-cloud cache keys on image-id hashes, not tag text, so a rename
+    // The visual-cluster cache keys on image-id hashes, not tag text, so a rename
     // wouldn't invalidate it automatically — clear it.
-    tx.execute("DELETE FROM tag_cloud_cache", [])?;
+    tx.execute("DELETE FROM visual_cluster_cache", [])?;
     tx.commit()?;
     Ok(())
 }
@@ -2810,7 +2814,7 @@ pub fn rename_tag(conn: &Connection, from: &str, to: &str) -> Result<()> {
 pub fn delete_tag(conn: &Connection, name: &str) -> Result<i64> {
     let tx = conn.unchecked_transaction()?;
     let removed = tx.execute("DELETE FROM image_tags WHERE tag = ?1", params![name])? as i64;
-    tx.execute("DELETE FROM tag_cloud_cache", [])?;
+    tx.execute("DELETE FROM visual_cluster_cache", [])?;
     tx.commit()?;
     Ok(removed)
 }
@@ -2983,14 +2987,14 @@ fn map_image_row(row: &Row<'_>) -> rusqlite::Result<ImageRecord> {
     })
 }
 
-/// Returns cached tag-cloud entries if the stored hash matches `current_hash`.
-pub fn get_tag_cloud_cache(
+/// Returns cached visual-cluster entries if the stored hash matches `current_hash`.
+pub fn get_visual_cluster_cache(
     conn: &Connection,
     folder_scope: &str,
     current_hash: u64,
 ) -> Result<Option<String>> {
     let result: rusqlite::Result<(i64, String)> = conn.query_row(
-        "SELECT image_ids_hash, entries_json FROM tag_cloud_cache WHERE folder_scope = ?1",
+        "SELECT image_ids_hash, entries_json FROM visual_cluster_cache WHERE folder_scope = ?1",
         params![folder_scope],
         |row| Ok((row.get(0)?, row.get(1)?)),
     );
@@ -3002,15 +3006,15 @@ pub fn get_tag_cloud_cache(
     }
 }
 
-/// Upserts the tag-cloud cache for the given scope.
-pub fn set_tag_cloud_cache(
+/// Upserts the visual-cluster cache for the given scope.
+pub fn set_visual_cluster_cache(
     conn: &Connection,
     folder_scope: &str,
     image_ids_hash: u64,
     entries_json: &str,
 ) -> Result<()> {
     conn.execute(
-        "INSERT INTO tag_cloud_cache (folder_scope, image_ids_hash, entries_json, created_at)
+        "INSERT INTO visual_cluster_cache (folder_scope, image_ids_hash, entries_json, created_at)
          VALUES (?1, ?2, ?3, datetime('now'))
          ON CONFLICT(folder_scope) DO UPDATE SET
              image_ids_hash = excluded.image_ids_hash,

src-tauri/src/lib.rs

@@ -198,7 +198,7 @@ pub fn run() {
             commands::get_worker_states,
             commands::get_worker_pauses_persist,
             commands::set_worker_pauses_persist,
-            commands::get_tag_cloud,
+            commands::get_visual_clusters,
             commands::get_explore_tags,
             commands::get_related_tags,
             commands::get_images_by_ids,

src-tauri/src/vector.rs

@@ -268,7 +268,7 @@ pub fn get_embedding_revision(conn: &Connection) -> Result<String> {
 /// exact set of IDs, so it is membership-sensitive: adding, removing, or moving an
 /// image between folders changes it even when the count happens to stay the same.
 /// Used (together with the embedding revision, which catches an image being
-/// re-embedded in place) as the cheap tag-cloud cache key so a cache hit doesn't
+/// re-embedded in place) as the cheap visual-cluster cache key so a cache hit doesn't
 /// have to read and unpack hundreds of MB of embeddings just to validate freshness.
 pub fn embedding_ids_signature(conn: &Connection, folder_id: Option<i64>) -> Result<(i64, u64)> {
     use xxhash_rust::xxh3::Xxh3;