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, src/BookDetails.hpp, src/BibliothecaWindow.cpp Status: COMPLETED

Implemented:

• Removed raw Book pointer storage - now only stores m_book_id
• All operations look up fresh book data via m_book_list.findById()
• Subscribe to BookList signals (signalBookRemoved, signalBookUpdated, signalReset)
• Emit signalBookRemoved() when displayed book is deleted
• BibliothecaWindow navigates back to shelf when book is removed
• Added clear() method and proper destructor with signal disconnection
• refresh_display() method for safe re-rendering from current 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 Status: COMPLETED

Previous behavior:

• on_add_tag_button_clicked() called m_book_list.loadAll() after adding tag
• This reloaded ALL books from database, losing selection/scroll state

Implemented:

• refresh_tags() now only queries tags for the specific book
• No full list reload - only the tag FlowBox is refreshed
• Selection and scroll state in BookShelf are preserved

---

Phase 2: Core Feature Improvements

2.1 Implement Tag-Based Search

Files: src/BookShelf.cpp Status: COMPLETED Location: src/BookShelf.cpp:67-107

Implemented:

• Tags are now included in fuzzy search scoring
• tag:tagname prefix syntax for exact tag filtering
• Case-insensitive tag matching
• Substring matching within tags for tag: syntax

Remaining (moved to Phase 3):

• Consider tag chips as quick filters in search UI

2.2 Add Error Handling and User Feedback

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

Implemented:

• Toast notification system with Gtk::Revealer overlay
• Success toast for book import ("Added N books")
• Error toast for failed imports ("Failed to import N files")
• Mixed results toast ("Added N, failed M")
• Auto-hide after 4 seconds with manual close button
• Error/success styling with CSS classes

Remaining for future:

• Show dialog when book file is missing/deleted (currently just logs)
• 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