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: COMPLETED

Implemented:

• Search query preserved in m_lastQuery when navigating to details
• Restore filter when returning from details via back button
• Only clear search when explicitly closing search bar on shelf/noresults views
• Search entry text preserved across view transitions

2.4 Improve Cover Handling

Files: src/Book.cpp, src/BookTile.cpp Status: COMPLETED

Implemented:

• Limit placeholder texture cache to 8 entries (prevents unbounded growth)
• Skip cover loading if already loaded (avoid redundant disk I/O)
• Check file existence before attempting texture load
• Graceful fallback to placeholder for missing/corrupted covers

Note: Format validation deferred - GTK handles format detection internally

---

Phase 3: New Features

3.1 Duplicate Book Detection

Files: src/BibliothecaWindow.cpp Status: COMPLETED

Implemented:

• Detect re-import of same file by SHA-256 hash lookup
• Track new vs duplicate books during import
• Show appropriate toast messages:
  • "Added N books" for all new
  • "N books already in library" for all duplicates
  • "Added N new, M duplicates" for mixed
• Duplicates are silently updated (metadata refresh)

Note: Skipped prompt dialog - auto-update is simpler and non-destructive

3.2 Batch Operations

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

Implemented:

• Multi-select mode in BookShelf (Gtk::MultiSelection + rubberband)
• Batch action bar (appears when books selected)
• Batch tag assignment via popover
• Batch delete
• Select All / Clear selection buttons
• Selection count display

Not implemented (deferred):

• Batch metadata edit (complex UI, lower priority)

3.3 Tag Management UI

Files: src/TagManagerDialog.cpp, src/TagManagerDialog.hpp, src/DatabaseManager.cpp, src/DatabaseManager.hpp Status: COMPLETED

Implemented:

• Tag manager dialog accessible via Tags button in header bar
• Display all tags with usage counts
• Rename tags (with automatic merge if target exists)
• Delete individual tags
• Delete unused tags (cleanup button)
• DatabaseManager methods: get_all_tags(), rename_tag(), delete_tag(), delete_unused_tags()

3.4 Settings Panel

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

Implemented:

• Grid tile size adjustment (80-300 pixels, with live reload)
• Default import folder selection
• Settings stored in SQLite via DatabaseManager
• Settings button in header bar

Note: Cover quality and theme selection deferred - GTK handles theme system-wide.

3.5 File Change Detection

Files: src/DatabaseManager.cpp, src/DatabaseManager.hpp, src/BookList.cpp, src/BookList.hpp, src/SettingsDialog.cpp Status: COMPLETED

Implemented:

• Track file modification time (already in schema: mtime_unix, size_bytes)
• DatabaseManager::get_all_book_files() to retrieve file info
• DatabaseManager::remove_books_by_ids() for batch removal
• BookList::findMissingBooks() to scan for missing files
• BookList::removeMissingBooks() to clean up library
• "Remove Missing Files" button in Settings dialog
• Toast notification showing results of scan

Note: Moved/renamed file detection deferred - would require fuzzy matching by size/hash.

---

Phase 4: Polish and Accessibility

4.1 Keyboard Navigation

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

Implemented:

• Enter/Return to open selected book from shelf view
• Escape to: go back from details, close search bar, or clear selection
• Backspace to go back from details view
• Added getSelectedBook() and clearSelection() to BookShelf

Note: Arrow key navigation in grid is handled by GTK's GridView natively. Tab navigation works through GTK's focus system.

4.2 Accessibility Labels

Files: src/BibliothecaWindow.cpp, src/BookTile.cpp, src/BookDetails.cpp, src/SettingsDialog.cpp Status: COMPLETED

Implemented:

• Header bar buttons: descriptive tooltips (back, search, tags, settings, add)
• Book tiles: tooltip with title and author for screen readers
• Batch action bar: tooltips for Select All, Clear, Add Tag, Delete
• BookDetails: tooltips for Open Book and Add Tag buttons
• SettingsDialog: tooltips for Save, Cancel, scan button
• TagManagerDialog: tooltips for rename and delete buttons (already had)

Note: GTK4 uses tooltips as accessible names for icon-only buttons. High contrast mode and focus indicators are handled by the GTK theme system. ARIA is a web standard; GTK uses the ATK/AT-SPI accessibility framework natively.

4.3 Documentation Updates

Files: docs/*.md Status: COMPLETED

Implemented:

• Update README with current features (added BookDetails, tagging, toasts)
• Document BookDetails component (new docs/bookdetails.md)
• Update bibliotheca_window.md (toast overlay, keyboard nav, details view)
• Update bookshelf.md (tag search, selection API)
• Update database_manager.md (tag tables and methods)
• Update Feature-Tagging.md (marked as implemented)

Remaining for future:

• Add user guide/manual
• Add screenshots or diagrams

---

Phase 5: Advanced Features

5.1 Built-in Reader

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

Implemented:

• PDF viewer using Poppler/Cairo
• EPUB viewer using libzip/tinyxml2/Pango
• Page/chapter navigation (next/prev)
• Reading progress tracking (saved per book)
• Keyboard navigation (Left/Right, PageUp/PageDown, Escape to close)
• "Read" button in BookDetails to open built-in reader
• Fallback to external reader for unsupported formats

EPUB Implementation Details:

• Parses container.xml to find OPF file
• Extracts spine order from OPF manifest
• Renders text content using Pango for proper layout
• Chapters loaded lazily for performance
• Text extracted from XHTML with proper paragraph handling

Remaining for future:

• Annotations and bookmarks
• Night/dark mode for reading
• Font size adjustment
• Table of contents navigation

5.2 Full-Text Search (Future)

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

5.3 Cloud Sync (Future)

• Sync library across devices
• Backup to cloud storage

5.4 Folder Watching

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

Implemented:

• FolderScanner class for recursive folder scanning
• Support for EPUB and PDF file detection
• Watched folder setting in Settings dialog
• Auto-import on application startup
• Duplicate detection (by SHA-256 hash)

Remaining for future:

• Real-time file monitoring (inotify/fswatch)
• Background monitoring daemon

5.5 Metadata Editing

Files: src/BookDetails.cpp, src/BookDetails.hpp, src/Book.hpp, src/BookList.cpp, src/BookList.hpp, src/DatabaseManager.cpp, src/DatabaseManager.hpp Status: COMPLETED

Implemented:

• Edit button in BookDetails to enter edit mode
• Editable fields for title, author, and description
• Save/Cancel buttons for confirming or discarding changes
• Description field added to database schema (with migration for existing databases)
• BookList.updateMetadata() method for efficient metadata updates
• Auto-refresh of display after save via signalBookUpdated

---

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

---

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