feat: page the library UI through the backend book query (#117)

The cover grid no longer loads every book at startup. The library store
now keeps a paged query cache keyed by the serialized filter combination
(text, author_id, series_id, hide_read, sort): each entry holds the
filtered total plus a sparse map of 100-book pages, fetched on demand via
clbQueryBooks as the virtualized grid scrolls (ensureBookRange, with
in-flight de-dupe and generation stamps so stale fetches never land).
Mutations stop refetching the whole library; they invalidate the cache so
visible pages reload lazily. Search text debounces ~200ms before becoming
a new cache key; sorting and hide-read now run in SQL via the query params.

Deep links carry ids instead of names: the Authors page and book-detail
author links pass author_id, and series links pass series_id, resolved
through a new minimal clb_query_list_series command (the only way to map
series names to the ids LibraryBookQuery filters on; it also lets the
Series page drop its full-book-list dependency). A series filter fetches
the whole series unpaged and sorts by series_index client-side, since the
backend only sorts by title/author.

clb_query_list_all_books stays for the Authors page (per-author book
counts need every book-author link) and the book detail route (tag
autocomplete needs the full tag vocabulary; no fetch-one-book command),
both now loaded lazily on first use via useAllBooks.

The pure cache logic lives in src/lib/book-page-cache.ts with vitest
coverage for key serialization, page math, range-to-pages, sparse
flattening, and generation invalidation.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: phildenhoff

crates/libcalibre/src/lib.rs

@@ -19,7 +19,7 @@ pub use custom_columns::{CustomColumn, CustomColumnKind, CustomColumnSpec, Custo
 pub use error::CalibreError;
 pub use library::{
     Author as LibraryAuthor, AuthorAdd, AuthorUpdate, Book as LibraryBook, BookAdd, BookFileInfo,
-    BookIdentifier, BookPage, BookQuery, BookSortOrder, BookUpdate, Library,
+    BookIdentifier, BookPage, BookQuery, BookSortOrder, BookUpdate, Library, SeriesSummary,
 };
 pub use types::{AuthorId, BookFileId, BookId};
 

crates/libcalibre/src/library.rs

@@ -173,6 +173,16 @@ pub struct BookPage {
     pub total: i64,
 }
 
+/// One series in the library, with its linked-book count. Returned by
+/// [`Library::list_series`]; series ids are what [`BookQuery::series_id`]
+/// filters on.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SeriesSummary {
+    pub id: i32,
+    pub name: String,
+    pub book_count: i64,
+}
+
 impl Library {
     pub fn new(db_path: ValidDbPath) -> Result<Self, CalibreError> {
         let conn = establish_connection(&db_path.database_path)
@@ -757,6 +767,12 @@ impl Library {
         Ok(BookPage { items, total })
     }
 
+    /// List every series in the library with its linked-book count, sorted
+    /// by name. The returned ids feed [`BookQuery::series_id`].
+    pub fn list_series(&mut self) -> Result<Vec<SeriesSummary>, CalibreError> {
+        crate::queries::series::list_with_book_counts(&mut self.conn)
+    }
+
     pub fn search_books(&mut self, query: &str) -> Result<Vec<Book>, CalibreError> {
         let query = query.trim();
         if query.is_empty() {

crates/libcalibre/src/queries/series.rs

@@ -2,13 +2,47 @@ use std::collections::HashMap;
 
 use diesel::prelude::*;
 use diesel::sql_query;
-use diesel::sql_types::{Integer, Text};
+use diesel::sql_types::{BigInt, Integer, Text};
 use diesel::{QueryDsl, RunQueryDsl, SqliteConnection};
 
 use crate::entities::series::{NewSeries, Series};
+use crate::library::SeriesSummary;
 use crate::types::BookId;
 use crate::CalibreError;
 
+pub(crate) fn list_with_book_counts(
+    conn: &mut SqliteConnection,
+) -> Result<Vec<SeriesSummary>, CalibreError> {
+    #[derive(QueryableByName)]
+    struct SeriesCountRow {
+        #[diesel(sql_type = Integer)]
+        id: i32,
+        #[diesel(sql_type = Text)]
+        name: String,
+        #[diesel(sql_type = BigInt)]
+        book_count: i64,
+    }
+
+    let rows: Vec<SeriesCountRow> = sql_query(
+        "SELECT s.id AS id, s.name AS name, COUNT(bsl.book) AS book_count
+         FROM series s
+         LEFT JOIN books_series_link bsl ON bsl.series = s.id
+         GROUP BY s.id, s.name
+         ORDER BY s.name COLLATE NOCASE, s.id",
+    )
+    .load(conn)
+    .map_err(CalibreError::from)?;
+
+    Ok(rows
+        .into_iter()
+        .map(|row| SeriesSummary {
+            id: row.id,
+            name: row.name,
+            book_count: row.book_count,
+        })
+        .collect())
+}
+
 pub(crate) fn find_by_name_case_insensitive(
     conn: &mut SqliteConnection,
     series_name: &str,

crates/libcalibre/tests/query_test.rs

@@ -530,3 +530,39 @@ fn test_page_items_are_hydrated() {
     assert_eq!(item.tags, ["fantasy"]);
     assert!(item.is_read);
 }
+
+// =============================================================================
+// Series listing
+// =============================================================================
+
+#[test]
+fn test_list_series_returns_counts_sorted_by_name() {
+    let (_temp, mut lib) = setup_with_library();
+
+    for n in 1u8..=2 {
+        lib.add_book(BookAdd {
+            series: Some("Earthsea".to_string()),
+            series_index: Some(f32::from(n)),
+            ..book(&format!("Earthsea {n}"), &["Ursula K. Le Guin"])
+        })
+        .unwrap();
+    }
+    lib.add_book(BookAdd {
+        series: Some("Culture".to_string()),
+        series_index: Some(1.0),
+        ..book("Consider Phlebas", &["Iain M. Banks"])
+    })
+    .unwrap();
+    lib.add_book(book("Standalone", &["Nobody"])).unwrap();
+
+    let series = lib.list_series().unwrap();
+    let names: Vec<&str> = series.iter().map(|s| s.name.as_str()).collect();
+    assert_eq!(names, ["Culture", "Earthsea"]);
+
+    let counts: Vec<i64> = series.iter().map(|s| s.book_count).collect();
+    assert_eq!(counts, [1, 2]);
+
+    // The listed ids are the ones BookQuery::series_id filters on.
+    let earthsea = series.iter().find(|s| s.name == "Earthsea").unwrap();
+    assert_eq!(earthsea.id, series_id_by_name(&mut lib, "Earthsea"));
+}

src-tauri/src/libs/calibre/query.rs

@@ -116,6 +116,34 @@ pub fn clb_query_books(
     })
 }
 
+/// One series in the library. `id` is what [`LibraryBookQuery::series_id`]
+/// filters on; the frontend otherwise only ever sees series names.
+#[derive(Serialize, Deserialize, specta::Type, Clone)]
+pub struct LibrarySeries {
+    pub id: i32,
+    pub name: String,
+    pub book_count: u32,
+}
+
+#[tauri::command]
+#[specta::specta]
+pub fn clb_query_list_series(
+    state: tauri::State<CitadelState>,
+) -> Result<Vec<LibrarySeries>, String> {
+    let summaries = state
+        .with_library(|lib| lib.list_series())?
+        .map_err(|e| e.to_string())?;
+
+    Ok(summaries
+        .into_iter()
+        .map(|series| LibrarySeries {
+            id: series.id,
+            name: series.name,
+            book_count: u32::try_from(series.book_count).unwrap_or(u32::MAX),
+        })
+        .collect())
+}
+
 #[tauri::command]
 #[specta::specta]
 pub fn clb_query_list_all_authors(

src-tauri/src/main.rs

@@ -31,6 +31,8 @@ fn run_tauri_backend() -> std::io::Result<()> {
         calibre::query::clb_query_is_file_importable,
         calibre::query::clb_query_importable_file_metadata,
         calibre::query::clb_query_list_all_filetypes,
+        // Series query commands
+        calibre::query::clb_query_list_series,
         // Book manipulation commands
         calibre::command::clb_cmd_create_book,
         calibre::command::clb_cmd_update_book,

src/BookView.ts

@@ -2,7 +2,12 @@ import type { LibraryBook } from "./bindings";
 
 export interface BookView {
 	loading: boolean;
-	bookList: LibraryBook[];
+	/**
+	 * Indexed array of the filtered library: length is the total match
+	 * count, `undefined` entries are books whose page has not been fetched
+	 * yet (they render as placeholders).
+	 */
+	bookList: (LibraryBook | undefined)[];
 	onBookOpen: (bookId: LibraryBook["id"]) => void;
 	selectedBookId?: LibraryBook["id"] | null;
 }

src/bindings.ts

@@ -57,6 +57,14 @@ async clbQueryImportableFileMetadata(file: ImportableFile) : Promise<ImportableB
 async clbQueryListAllFiletypes() : Promise<([string, string])[]> {
     return await TAURI_INVOKE("clb_query_list_all_filetypes");
 },
+async clbQueryListSeries() : Promise<Result<LibrarySeries[], string>> {
+    try {
+    return { status: "ok", data: await TAURI_INVOKE("clb_query_list_series") };
+} catch (e) {
+    if(e instanceof Error) throw e;
+    else return { status: "error", error: e  as any };
+}
+},
 async clbCmdCreateBook(md: ImportableBookMetadata) : Promise<Result<string, string>> {
     try {
     return { status: "ok", data: await TAURI_INVOKE("clb_cmd_create_book", { md }) };
@@ -313,6 +321,11 @@ text: string | null; author_id: string | null; series_id: number | null; hide_re
  * Page size. `None` returns all matches.
  */
 limit: number | null; offset: number }
+/**
+ * One series in the library. `id` is what [`LibraryBookQuery::series_id`]
+ * filters on; the frontend otherwise only ever sees series names.
+ */
+export type LibrarySeries = { id: number; name: string; book_count: number }
 export type LocalFile = { 
 /**
  * The absolute path to the file, including extension.

src/components/atoms/BookCard.module.css

@@ -33,3 +33,17 @@
 	outline-offset: 2px;
 	box-shadow: 0 0 0 7px var(--ctd-focus-ring);
 }
+
+/* Cover-shaped stand-in for a book whose page has not been fetched yet
+ * (BookGrid placeholder cells). Sized like a typical cover (2:3, capped at
+ * the shelf height) so rows hold steady while real books stream in. */
+.coverPlaceholder {
+	display: block;
+	width: 100%;
+	max-width: 150px;
+	aspect-ratio: 2 / 3;
+	max-height: 230px;
+	border-radius: 4px;
+	background: var(--ctd-surface-muted);
+	border: 1px solid var(--ctd-border);
+}

src/components/molecules/BookGrid.tsx

@@ -20,6 +20,7 @@ import {
 	rowSlice,
 } from "@/lib/grid-virtual";
 import { BookCard } from "../atoms/BookCard";
+import cardClasses from "../atoms/BookCard.module.css";
 
 /**
  * Shelf-grid layout constants. The per-row tracks mirror the old
@@ -37,6 +38,9 @@ const OVERSCAN_ROWS = 4;
 /** Scrolls the shelf row containing the given flat book index into view. */
 export type ScrollToBookIndex = (index: number) => void;
 
+/** The inclusive flat-index range of books near the viewport. */
+export type VisibleRangeChange = (startIndex: number, endIndex: number) => void;
+
 interface BookGridProps extends BookView {
 	/** The page-owned scroll region the virtualizer windows against. */
 	scrollElementRef: RefObject<HTMLElement>;
@@ -45,6 +49,11 @@ interface BookGridProps extends BookView {
 	 * reach rows that are not currently mounted (use-library-keymap).
 	 */
 	scrollToBookIndexRef?: MutableRefObject<ScrollToBookIndex | null>;
+	/**
+	 * Fires when the rendered (viewport + overscan) flat-index range moves,
+	 * so the owner can page the covered books in (ensureBookRange).
+	 */
+	onVisibleRangeChange?: VisibleRangeChange;
 }
 
 export const BookGrid = ({
@@ -54,6 +63,7 @@ export const BookGrid = ({
 	selectedBookId,
 	scrollElementRef,
 	scrollToBookIndexRef,
+	onVisibleRangeChange,
 }: BookGridProps) => {
 	const actionsContext = useMemo(() => {
 		return {
@@ -69,6 +79,7 @@ export const BookGrid = ({
 				selectedBookId={selectedBookId}
 				scrollElementRef={scrollElementRef}
 				scrollToBookIndexRef={scrollToBookIndexRef}
+				onVisibleRangeChange={onVisibleRangeChange}
 			/>
 		</bookActionsContext.Provider>
 	);
@@ -80,12 +91,14 @@ const BookGridPure = ({
 	selectedBookId,
 	scrollElementRef,
 	scrollToBookIndexRef,
+	onVisibleRangeChange,
 }: {
 	loading: boolean;
-	bookList: LibraryBook[];
+	bookList: (LibraryBook | undefined)[];
 	selectedBookId?: LibraryBook["id"] | null;
 	scrollElementRef: RefObject<HTMLElement>;
 	scrollToBookIndexRef?: MutableRefObject<ScrollToBookIndex | null>;
+	onVisibleRangeChange?: VisibleRangeChange;
 }) => {
 	const actions = useContext(bookActionsContext);
 
@@ -136,6 +149,20 @@ const BookGridPure = ({
 		};
 	}, [scrollToBookIndexRef, virtualizer, columns]);
 
+	// Report the rendered row window (includes overscan) as a flat-index
+	// range so unfetched pages covering it can load.
+	const virtualRows = virtualizer.getVirtualItems();
+	const firstRow = virtualRows[0]?.index;
+	const lastRow = virtualRows[virtualRows.length - 1]?.index;
+	useEffect(() => {
+		if (!onVisibleRangeChange) return;
+		if (firstRow === undefined || lastRow === undefined) return;
+		const start = rowSlice(firstRow, columns, books.length).start;
+		const end = rowSlice(lastRow, columns, books.length).end - 1;
+		if (end < start) return;
+		onVisibleRangeChange(start, end);
+	}, [onVisibleRangeChange, firstRow, lastRow, columns, books.length]);
+
 	return (
 		<div
 			ref={wrapperRef}
@@ -159,7 +186,7 @@ const BookGridPure = ({
 				 * bottom-aligns its book (see BookCard.module.css) so the bases
 				 * sit on one line.
 				 */}
-				{virtualizer.getVirtualItems().map((virtualRow) => {
+				{virtualRows.map((virtualRow) => {
 					const { start, end } = rowSlice(
 						virtualRow.index,
 						columns,
@@ -182,14 +209,19 @@ const BookGridPure = ({
 								columnGap: COLUMN_GAP,
 							}}
 						>
-							{books.slice(start, end).map((book) => (
-								<BookCard
-									key={book.id}
-									book={book}
-									actions={actions}
-									selected={book.id === selectedBookId}
-								/>
-							))}
+							{books.slice(start, end).map((book, offset) =>
+								book !== undefined ? (
+									<BookCard
+										key={book.id}
+										book={book}
+										actions={actions}
+										selected={book.id === selectedBookId}
+									/>
+								) : (
+									// biome-ignore lint/suspicious/noArrayIndexKey: an unfetched slot has no id; its flat grid index IS its identity until the book arrives (and then the keyed BookCard replaces it).
+									<BookCardPlaceholder key={`placeholder-${start + offset}`} />
+								),
+							)}
 						</div>
 					);
 				})}
@@ -198,6 +230,17 @@ const BookGridPure = ({
 	);
 };
 
+/**
+ * Stand-in cell for a book whose page has not been fetched yet: the same
+ * shelf-cell layout as BookCard with a quiet cover-shaped block, so rows
+ * keep their height and books pop in without the shelf reflowing.
+ */
+const BookCardPlaceholder = () => (
+	<div className={cardClasses.cell} aria-hidden>
+		<span className={cardClasses.coverPlaceholder} />
+	</div>
+);
+
 type BookAction = (bookId: LibraryBook["id"]) => void;
 interface BookActionsContext {
 	onViewBook: BookAction;