feat(ui): add persisted sound sorting (#211)

* feat(ui): add persisted sound sorting

Add reusable list sort controls, tolerant per-view preferences, and deterministic ordering for the main sound grid.

Co-Authored-By: Codex <noreply@openai.com>

* fix(state): tolerate malformed sort preferences

Deserialize sort preferences independently so malformed future entries fall back without invalidating otherwise usable application settings.

Co-Authored-By: Codex <noreply@openai.com>

* fix(ui): cache sorted sound indices

Move sound filtering and sorting to update-side invalidation boundaries so Iced view construction only indexes cached results. Project only the active sort key and keep render benchmarks on the production cached-index API.

Co-Authored-By: Codex <noreply@openai.com>

* fix(ui): address sound sorting review findings

Keep grid rows aligned when cached indices no longer resolve and consolidate config loading through the explicit-path implementation.

Co-Authored-By: Codex <noreply@openai.com>

---------

Co-authored-by: Codex <noreply@openai.com>

Author: thewrz

benches/grid_render.rs

@@ -8,9 +8,7 @@ mod support;
 
 use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main};
 
-use support::{
-    GridFixture, init_wgpu, make_sounds, render_tiny_skia, self_check, sound_refs, try_render_wgpu,
-};
+use support::{GridFixture, init_wgpu, make_sounds, render_tiny_skia, self_check, try_render_wgpu};
 
 /// Tile counts ADR-009 anchors the baseline against.
 const SIZES: [usize; 3] = [50, 200, 500];
@@ -24,9 +22,9 @@ fn bench_tiny_skia(c: &mut Criterion) {
     for &n in &SIZES {
         let sounds = make_sounds(n);
         let fx = GridFixture::new();
-        let refs = sound_refs(&sounds);
+        let visible_indices = (0..sounds.len()).collect::<Vec<_>>();
         group.bench_with_input(BenchmarkId::from_parameter(n), &n, |b, _| {
-            b.iter(|| render_tiny_skia(&refs, fx.grid_ctx(COLUMNS)));
+            b.iter(|| render_tiny_skia(&sounds, &visible_indices, fx.grid_ctx(COLUMNS)));
         });
     }
     group.finish();
@@ -45,9 +43,9 @@ fn bench_wgpu(c: &mut Criterion) {
     for &n in &SIZES {
         let sounds = make_sounds(n);
         let fx = GridFixture::new();
-        let refs = sound_refs(&sounds);
+        let visible_indices = (0..sounds.len()).collect::<Vec<_>>();
         group.bench_with_input(BenchmarkId::from_parameter(n), &n, |b, _| {
-            b.iter(|| try_render_wgpu(&refs, fx.grid_ctx(COLUMNS), &gpu));
+            b.iter(|| try_render_wgpu(&sounds, &visible_indices, fx.grid_ctx(COLUMNS), &gpu));
         });
     }
     group.finish();

benches/support/mod.rs

@@ -66,11 +66,6 @@ pub fn make_sounds(n: usize) -> Vec<SoundEntry> {
         .collect()
 }
 
-/// Borrows entries into the `&[&SoundEntry]` slice `view_grid` expects.
-pub fn sound_refs(sounds: &[SoundEntry]) -> Vec<&SoundEntry> {
-    sounds.iter().collect()
-}
-
 /// Owns the per-grid context state (`SlotMap`, trigger labels, meta store) so a
 /// `GridCtx` can borrow from it for the duration of a bench iteration. Empty /
 /// default state represents the common case (no slots bound, no favorites).
@@ -111,8 +106,13 @@ impl Default for GridFixture {
 /// Builds the grid `Element` and runs Iced's layout + draw passes against the
 /// provided renderer. This is the `view()`-construction + tessellation work
 /// ADR-009 cares about. Rasterization is renderer-specific (done by callers).
-fn layout_and_draw(sounds: &[&SoundEntry], grid: GridCtx, renderer: &mut iced::Renderer) {
-    let element: Element<'_, Message> = view_grid(sounds.to_vec(), None, grid);
+fn layout_and_draw(
+    sounds: &[SoundEntry],
+    visible_indices: &[usize],
+    grid: GridCtx,
+    renderer: &mut iced::Renderer,
+) {
+    let element: Element<'_, Message> = view_grid(sounds, visible_indices, None, grid);
     let bounds = Size::new(VIEW_W as f32, VIEW_H as f32);
     let mut ui = UserInterface::build(element, bounds, Cache::new(), renderer);
     let theme = Theme::Dark;
@@ -138,12 +138,12 @@ fn full_damage() -> [Rectangle; 1] {
 /// Full tiny-skia render: layout + draw + CPU rasterization into a `Pixmap`.
 /// This is the `HONKHONK_RENDERER=software` path. Returns the top-left pixel so
 /// the optimizer cannot elide the raster. Always available (pure CPU).
-pub fn render_tiny_skia(sounds: &[&SoundEntry], grid: GridCtx) -> u32 {
+pub fn render_tiny_skia(sounds: &[SoundEntry], visible_indices: &[usize], grid: GridCtx) -> u32 {
     // The `Element` is generic over `iced::Renderer` (the fallback enum); its
     // `Secondary` arm *is* the tiny-skia renderer, so draw lands in its layers.
     let mut renderer =
         iced::Renderer::Secondary(iced_tiny_skia::Renderer::new(Font::DEFAULT, text_size()));
-    layout_and_draw(sounds, grid, &mut renderer);
+    layout_and_draw(sounds, visible_indices, grid, &mut renderer);
 
     let iced::Renderer::Secondary(ts) = &mut renderer else {
         unreachable!("constructed Secondary");
@@ -235,13 +235,18 @@ pub fn init_wgpu() -> Option<WgpuCtx> {
 /// Full wgpu render: layout + draw + present to the reusable offscreen target.
 /// Returns a token so the work cannot be optimized away. Requires an
 /// initialized context.
-pub fn try_render_wgpu(sounds: &[&SoundEntry], grid: GridCtx, gpu: &WgpuCtx) -> u32 {
+pub fn try_render_wgpu(
+    sounds: &[SoundEntry],
+    visible_indices: &[usize],
+    grid: GridCtx,
+    gpu: &WgpuCtx,
+) -> u32 {
     let mut renderer = iced::Renderer::Primary(iced_wgpu::Renderer::new(
         gpu.engine.clone(),
         Font::DEFAULT,
         text_size(),
     ));
-    layout_and_draw(sounds, grid, &mut renderer);
+    layout_and_draw(sounds, visible_indices, grid, &mut renderer);
 
     let iced::Renderer::Primary(wr) = &mut renderer else {
         unreachable!("constructed Primary");
@@ -272,7 +277,7 @@ pub fn self_check() {
         u64::from_str_radix(head, 16).expect("fixture id head parses as hex");
     }
     let sounds = make_sounds(50);
-    let refs = sound_refs(&sounds);
+    let visible_indices = (0..sounds.len()).collect::<Vec<_>>();
     let fx = GridFixture::new();
-    let _ = render_tiny_skia(&refs, fx.grid_ctx(5));
+    let _ = render_tiny_skia(&sounds, &visible_indices, fx.grid_ctx(5));
 }

docs/superpowers/specs/2026-07-23-issue-197-design.md

@@ -0,0 +1,105 @@
+# Issue #197 — Persisted Sound-Tile Sorting
+
+Date: 2026-07-23 · Status: approved
+
+## Why
+
+The main sound grid needs predictable, user-selectable ordering without coupling sorting to its
+session-only filter. The first consumer establishes reusable list-control state and widgets for
+later slot, shortcut, and macro views while keeping grouping out of scope until user-defined tags
+exist.
+
+The current folder-derived category is presented as **Folder**. “Tag” remains reserved for #201.
+
+## Data Shapes
+
+- `ui::list_controls::sort::Direction::{Ascending, Descending}` controls display order.
+- `ui::list_controls::sort::SortState<K> { key, direction }` owns one view's active ordering.
+- `ui::list_controls::sort::SortKey<T>` supplies a label, primary comparison, and an optional
+  unknown-value predicate. `SortState` applies direction only within known/unknown buckets so
+  unknown values remain last in both directions.
+- `app::sorting::SoundSortKey::{Name, Length, Folder, Modified, Added}` implements the sound-grid
+  ordering contract. The view default is Name ascending.
+- `state::config::SortPref` is a persistence DTO containing string key and direction values.
+  `AppConfig.sort_prefs` stores these by view ID; the main grid uses `"tiles"`.
+- The sort menu anchor is transient app state. It is never persisted.
+
+Keeping the persisted DTO separate from the runtime enums lets old or future config values load
+without making the whole config unreadable. A missing or unrecognized preference resolves to that
+view's complete default.
+
+## Interfaces and Touch Map
+
+- `src/ui/list_controls/sort.rs`
+  - pure generic sort controller and direction handling;
+  - `view_sort_chip` with separate label and chevron actions;
+  - `view_sort_menu_overlay` with option selection and a full-window dismiss backdrop.
+- `src/state/config/sort.rs`
+  - tolerant persistence DTO.
+- `src/state/config.rs`
+  - extract the existing test module first so the production file is below 400 lines;
+  - add `sort_prefs` with a Serde default.
+- `src/app/sorting.rs`
+  - preference conversion, sound comparison, app update helpers, and boundary tests.
+- `src/app/header.rs`
+  - extract the existing header from oversized `app/mod.rs` and place the sort chip directly beside
+    the main search input.
+- `src/app/filtering.rs`
+  - compose category/query filtering with sound ordering and give an open sort menu Escape priority.
+- `src/app/mod.rs`
+  - declarations and narrow delegation only; the extracted header ensures the already-oversized
+    file shrinks overall.
+
+No dependency is added.
+
+## Ordering Contract
+
+1. Name compares the customized display name when present, otherwise the scanned name.
+2. Name and Folder comparisons are Unicode-lowercased before comparison.
+3. Every primary-key tie is resolved by path and then sound ID, producing deterministic output.
+4. Length compares milliseconds; Folder compares the current folder-derived category; Modified
+   uses the scan timestamp; Added uses the persisted first-seen timestamp.
+5. Missing Length, Modified, or Added values form an unknown bucket after all known values.
+   Descending reverses ordering within each bucket, never the bucket placement.
+6. Filtering and category selection happen before sorting and do not alter the persisted
+   preference.
+
+## Interaction Contract
+
+- Clicking the chip label toggles the options menu.
+- Clicking only the chevron toggles direction and persists immediately.
+- Choosing a key persists it and closes the menu.
+- Clicking outside the menu or pressing Escape closes it without changing the preference.
+- Filter text remains session-only.
+- The menu exposes sorting as its own section/function so a later grouping section can be appended
+  without changing `SortState`; grouping itself is not implemented.
+
+## Iced API Finding
+
+No throwaway spike is required. `sound_grid::context_menu_overlay` already demonstrates the exact
+Iced 0.14 API needed here: a stable window-level `Stack`, a full-size `mouse_area` dismiss layer,
+and the interactive menu above it. The sort menu reuses this proven pattern and clamps its captured
+cursor anchor to the window bounds.
+
+## Invariants
+
+1. Name ascending is the default for missing, malformed, or unknown tile preferences.
+2. A valid preference survives `AppConfig` serialization and reload.
+3. Unknown persisted keys or directions never fail config deserialization and never partially
+   influence runtime state.
+4. Unknown dates always sort last for both ascending and descending directions.
+5. Case-insensitive name ties are deterministic by path and ID.
+6. Changing direction or key never mutates the sound library or metadata.
+7. Opening or dismissing the menu never changes the active ordering.
+8. The main filter query is never written to config.
+
+## TDD Sequence
+
+1. Add failing pure tests for per-key ordering, case-insensitive ties, direction, and unknown values.
+2. Add failing config tests for preference round trips and tolerant unknown data.
+3. Implement runtime/persistence types and the pure sound sorter.
+4. Add app-boundary tests proving preference load, selection, toggle, dismissal, and ordered
+   filtered results.
+5. Wire the chip and overlay using the established Iced stack pattern.
+6. Format, run focused tests, the complete test suite, Clippy with warnings denied, and review the
+   complete branch diff.