tui: async storage operations — don't block event loop on gallery/entity loads #125

New issue

Closed

opened 2026-04-12 22:03:06 +00:00 by claude-desktop · 0 comments

claude-desktop commented

2026-04-12 22:03:06 +00:00

Collaborator

User story

As a user with a large gallery (1000+ items), I want the TUI to stay responsive while loading data, so that navigation and input aren't frozen during storage reads.

Problem

Several screens perform synchronous SQLite reads inside handle() or render():

gallery.rs load_from_storage() — calls guard.list(&filter) synchronously
entities.rs load_from_storage() — calls guard.list_entities() synchronously
presets.rs load_from_storage() — calls guard.list_presets() synchronously

These hold a std::sync::Mutex lock on GalleryStorage and block the tokio event loop. For small datasets this is fine, but with large galleries the UI freezes.

Acceptance criteria

Gallery load_from_storage() spawns a tokio::spawn_blocking task instead of blocking inline
Results are routed back via AppAction::GalleryLoaded(Vec<GalleryItem>) or similar
A loading indicator is shown while data is in flight ("Loading..." placeholder)
Entity and Preset screens follow the same async pattern
Multiple rapid loads are debounced (only the latest result is applied)
Storage mutex is held only for the duration of the query, not across await points

Out of scope

Pagination / virtual scrolling (separate optimization)
Background indexing

References

crates/loom-tui/src/screens/gallery.rs — load_from_storage()
crates/loom-tui/src/screens/entities.rs — load_from_storage()
crates/loom-tui/src/screens/presets.rs — load_from_storage()
tokio::task::spawn_blocking for CPU-bound / mutex-holding work

## User story As a user with a large gallery (1000+ items), I want the TUI to stay responsive while loading data, so that navigation and input aren't frozen during storage reads. ## Problem Several screens perform synchronous SQLite reads inside `handle()` or `render()`: - `gallery.rs` `load_from_storage()` — calls `guard.list(&filter)` synchronously - `entities.rs` `load_from_storage()` — calls `guard.list_entities()` synchronously - `presets.rs` `load_from_storage()` — calls `guard.list_presets()` synchronously These hold a `std::sync::Mutex` lock on `GalleryStorage` and block the tokio event loop. For small datasets this is fine, but with large galleries the UI freezes. ## Acceptance criteria - [ ] Gallery `load_from_storage()` spawns a `tokio::spawn_blocking` task instead of blocking inline - [ ] Results are routed back via `AppAction::GalleryLoaded(Vec<GalleryItem>)` or similar - [ ] A loading indicator is shown while data is in flight ("Loading..." placeholder) - [ ] Entity and Preset screens follow the same async pattern - [ ] Multiple rapid loads are debounced (only the latest result is applied) - [ ] Storage mutex is held only for the duration of the query, not across await points ## Out of scope - Pagination / virtual scrolling (separate optimization) - Background indexing ## References - `crates/loom-tui/src/screens/gallery.rs` — `load_from_storage()` - `crates/loom-tui/src/screens/entities.rs` — `load_from_storage()` - `crates/loom-tui/src/screens/presets.rs` — `load_from_storage()` - `tokio::task::spawn_blocking` for CPU-bound / mutex-holding work

claude-desktop added this to the loom-tui v0.1.0 milestone

2026-04-12 22:03:06 +00:00

claude-desktop added the

area:gallery

area:infra

type:user-story

labels

2026-04-12 22:03:06 +00:00

claude-desktop referenced this issue

2026-04-14 19:24:22 +00:00

tui: tracking — loom-tui v0.1.0 roadmap & implementation order #47