feat(library): add strategy parameter for item fetching and update filter preview

k-tv-backend/Cargo.lock

@@ -80,6 +80,7 @@ dependencies = [
  "dotenvy",
  "infra",
  "k-core",
+ "rand 0.8.5",
  "serde",
  "serde_json",
  "serde_qs",

k-tv-backend/api/Cargo.toml

@@ -35,6 +35,7 @@ tokio = { version = "1.48.0", features = ["full"] }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0"
 serde_qs = "0.13"
+rand = "0.8"
 
 # Error handling
 thiserror = "2.0.17"

k-tv-backend/api/src/routes/library.rs

@@ -114,13 +114,17 @@ struct ItemsQuery {
     #[serde(rename = "type")]
     content_type: Option<String>,
     /// Filter episodes by series name. Repeat the param for multiple series:
-    /// `?series=iCarly&series=Victorious`
+    /// `?series[]=iCarly&series[]=Victorious`
     #[serde(default)]
     series: Vec<String>,
     /// Scope to a provider collection ID.
     collection: Option<String>,
     /// Maximum number of results (default: 50, max: 200).
     limit: Option<usize>,
+    /// Fill strategy to simulate: "random" | "sequential" | "best_fit".
+    /// Applies the same ordering the schedule engine would use so the preview
+    /// reflects what will actually be scheduled.
+    strategy: Option<String>,
 }
 
 // ============================================================================
@@ -187,7 +191,21 @@ async fn search_items(
         ..Default::default()
     };
 
-    let items = state.media_provider.fetch_items(&filter).await?;
+    let mut items = state.media_provider.fetch_items(&filter).await?;
+
+    // Apply the same ordering the schedule engine uses so the preview reflects
+    // what will actually be scheduled rather than raw provider order.
+    match params.strategy.as_deref() {
+        Some("random") => {
+            use rand::seq::SliceRandom;
+            items.shuffle(&mut rand::thread_rng());
+        }
+        Some("best_fit") => {
+            // Mirror the greedy bin-packing: longest items first.
+            items.sort_by(|a, b| b.duration_secs.cmp(&a.duration_secs));
+        }
+        _ => {} // "sequential" / unset: keep provider order (episode order per series)
+    }
 
     let response: Vec<LibraryItemResponse> = items
         .into_iter()