Bibliotheca/PLAN.md

Bibliotheca Development Plan

Overview

Bibliotheca is a GTK4-based desktop ebook library manager written in C++17. This plan documents existing issues to fix and new features to implement.

Current Version: 0.1.0 Technology Stack: GTK4/gtkmm-4, SQLite3, OpenSSL, libzip, tinyxml2, poppler-glib

---

Phase 1: Critical Bug Fixes

1.1 Complete BookDetails Tag Implementation

Files: src/BookDetails.cpp, src/BookDetails.hpp Status: COMPLETED

Implemented:

• Add tag removal buttons (X icons) to each tag in FlowBox
• Create on_remove_tag_clicked(tag_name) handler
• Call m_db.remove_tag_from_book() and update UI
• Handle edge cases (empty tag name validation)
• Store book_id instead of relying solely on pointer
• Use refresh_tags() to reload from DB (efficient, no full list reload)
• Escape markup in title/author to prevent injection

Remaining (moved to Phase 2):

• Add visual feedback (toast/notification) for tag operations

1.2 Fix Null Pointer Safety in BookDetails

Files: src/BookDetails.cpp Status: Not Started Location: src/BookDetails.cpp:57-89

Current behavior:

• on_open_button_clicked() already has if (m_book) check (line 58)
• on_add_tag_button_clicked() already has if (m_book) check (line 81)
• BUT: m_book pointer could become dangling if book is deleted from list

Tasks:

• Handle case where book is deleted while details view is open
• Subscribe to BookList signals to detect book removal
• Clear details view or navigate back when displayed book is removed
• Consider storing book ID instead of pointer and looking up fresh data

1.3 Fix Const-Correctness in DatabaseManager

Files: src/DatabaseManager.cpp, src/DatabaseManager.hpp Status: Review Needed

Current state:

• Header declares get_book() and load_all_books() as non-const (correct)
• Methods need mutex lock, so non-const is acceptable
• This may actually be correctly designed - needs review

Tasks:

• Review if const-correctness is actually an issue
• If needed: use mutable keyword for mutex to allow const methods
• Document thread-safety guarantees in header comments

1.4 Fix Inefficient Tag Updates

Files: src/BookDetails.cpp, src/BookList.cpp Status: Not Started Location: src/BookDetails.cpp:85

Current behavior:

• on_add_tag_button_clicked() calls m_book_list.loadAll() after adding tag
• This reloads ALL books from database, losing selection/scroll state
• Very inefficient for large libraries

Tasks:

• Add BookList::updateBookTags(book_id) method for incremental update
• Or: Directly update the Book object's tags and emit signalBookUpdated
• Refresh only the displayed BookDetails, not entire list
• Preserve scroll position and selection state in BookShelf

---

Phase 2: Core Feature Improvements

2.1 Implement Tag-Based Search

Files: src/BookShelf.cpp Status: Not Started Location: src/BookShelf.cpp:67-76 (book_score() function)

Current behavior:

• book_score() searches: title, author, filePath, id
• Tags are NOT searched despite being loaded into Book objects

Tasks:

• [ ] Add tag matching loop in book_score():

  for (const auto& tag : book.tags())
  best = std::max(best, field_score(tag, pattern));
  

• [ ] Support tag:tagname search syntax for exact tag filtering

• [ ] Consider tag chips as quick filters in search UI (Phase 3)

2.2 Add Error Handling and User Feedback

Files: src/BibliothecaWindow.cpp, src/BookDetails.cpp, src/BookImport.cpp Status: Not Started

• Add toast notifications for import success/failure
• Show dialog when book file is missing/deleted
• Display metadata extraction warnings
• Add loading indicator during import

2.3 Preserve Search State Across Views

Files: src/BibliothecaWindow.cpp Status: Not Started

• Save search query when switching to details view
• Restore search query when returning to shelf
• Maintain filter state across navigation

2.4 Improve Cover Handling

Files: src/BookImport.cpp, src/BookTile.cpp Status: Not Started

• Validate cover image format before saving
• Add cache clearing mechanism for placeholder textures
• Handle missing/corrupted cover files gracefully

---

Phase 3: New Features

3.1 Duplicate Book Detection

Files: src/BookList.cpp, src/BibliothecaWindow.cpp Status: Not Started

• Detect re-import of same file (by hash)
• Prompt user: update existing or skip
• Show notification for already-imported books

3.2 Batch Operations

Files: New files required Status: Not Started

• Multi-select mode in BookShelf
• Batch tag assignment
• Batch delete
• Batch metadata edit

3.3 Tag Management UI

Files: New files required Status: Not Started

• Dedicated tag browser/manager panel
• Rename tags
• Merge duplicate tags
• Delete unused tags
• Tag usage statistics

3.4 Settings Panel

Files: New files required Status: Not Started

• Grid tile size adjustment
• Default import folder
• Cover quality settings
• Theme selection (if GTK allows)

3.5 File Change Detection

Files: src/DatabaseManager.cpp, src/BookList.cpp Status: Not Started

• Track file modification time (already in schema)
• Detect moved/renamed files
• Option to re-scan library
• Remove entries for deleted files

---

Phase 4: Polish and Accessibility

4.1 Keyboard Navigation

Files: src/BibliothecaWindow.cpp, src/BookShelf.cpp Status: Not Started

• Arrow key navigation in grid
• Enter to open selected book
• Escape to clear selection/search
• Tab navigation through UI elements

4.2 Accessibility Labels

Files: All UI files Status: Not Started

• Add ARIA labels to all buttons
• Screen reader support for book tiles
• High contrast mode support
• Focus indicators

4.3 Documentation Updates

Files: docs/*.md Status: Not Started

• Update README with current features
• Document BookDetails component
• Add user guide/manual
• Update architecture diagrams

---

Phase 5: Advanced Features (Future)

5.1 Built-in Reader

• Embedded EPUB/PDF viewer
• Reading progress tracking
• Annotations and bookmarks

5.2 Full-Text Search

• Index book contents
• Search within books
• Highlight search results

5.3 Cloud Sync

• Sync library across devices
• Backup to cloud storage

5.4 Folder Watching

• Auto-import from watched folders
• Background monitoring daemon

---

Implementation Priority

Priority	Task	Estimated Complexity
P0	1.1 Complete tag removal UI	Low
P0	1.2 Fix null pointer safety	Low
P0	1.4 Fix inefficient tag updates	Medium
P1	1.3 Fix const-correctness	Low
P1	2.1 Tag-based search	Medium
P1	2.2 Error handling/feedback	Medium
P2	2.3 Preserve search state	Low
P2	2.4 Cover handling improvements	Medium
P2	3.1 Duplicate detection	Medium
P3	3.2-3.5 New features	High
P4	4.1-4.3 Polish	Medium

---

Current Working Files

Modified (uncommitted)

• meson.build - Added BookDetails.cpp
• src/BibliothecaWindow.cpp - Added details view
• src/BibliothecaWindow.hpp - Added members
• src/Book.hpp - Added tags vector
• src/DatabaseManager.cpp - Added tag tables/methods
• src/DatabaseManager.hpp - Added tag signatures
• src/main.cpp - Pass DB to window

New (untracked)

• src/BookDetails.cpp - Details pane (incomplete)
• src/BookDetails.hpp - Details pane header
• docs/Feature-Tagging.md - Tagging design doc

---

Notes

• All changes should maintain thread safety (mutex usage)
• Follow existing code style (GTK4 patterns, RAII)
• Test on both X11 and Wayland
• Flatpak manifest may need updates for new dependencies