# 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:
- [x] Add tag removal buttons (X icons) to each tag in FlowBox
- [x] Create `on_remove_tag_clicked(tag_name)` handler
- [x] Call `m_db.remove_tag_from_book()` and update UI
- [x] Handle edge cases (empty tag name validation)
- [x] Store book_id instead of relying solely on pointer
- [x] Use `refresh_tags()` to reload from DB (efficient, no full list reload)
- [x] 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:
- [x] Removed raw Book pointer storage - now only stores `m_book_id`
- [x] All operations look up fresh book data via `m_book_list.findById()`
- [x] Subscribe to BookList signals (signalBookRemoved, signalBookUpdated, signalReset)
- [x] Emit `signalBookRemoved()` when displayed book is deleted
- [x] BibliothecaWindow navigates back to shelf when book is removed
- [x] Added `clear()` method and proper destructor with signal disconnection
- [x] `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:
- [x] `refresh_tags()` now only queries tags for the specific book
- [x] No full list reload - only the tag FlowBox is refreshed
- [x] 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:
- [x] Tags are now included in fuzzy search scoring
- [x] `tag:tagname` prefix syntax for exact tag filtering
- [x] Case-insensitive tag matching
- [x] 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:
- [x] Toast notification system with Gtk::Revealer overlay
- [x] Success toast for book import ("Added N books")
- [x] Error toast for failed imports ("Failed to import N files")
- [x] Mixed results toast ("Added N, failed M")
- [x] Auto-hide after 4 seconds with manual close button
- [x] 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