Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity
1,188 Commits 5 Branches 13 Tags
0191d36dc992914ba8ecfcaaea38eeb3bef0a481
Commit Graph
7 Commits
Author SHA1 Message Date
john-okeefe fa2d4c0fd8 Clarify reader implementation plan data flow and SSR responsibilities 
- Update Section 1.4 with detailed data flow diagram showing SSR skeleton approach
- Add Section 1.5 documenting SSR vs Client-Side responsibilities
- Clarify that SSR provides HTML shell with initial data, TypeScript handles UI
- Document specific examples of what SSR renders vs what TypeScript manages
- Remove confusing 'embedded JSON' terminology for clearer hybrid approach

These changes make the implementation plan more precise and implementation-ready
by clearly separating SSR (Go template) from client-side (TypeScript) concerns.
 2026-04-03 22:29:05 -04:00
john-okeefe 5550b730ee docs: update reader implementation plan with dockable panels 
- Add modular dockable panel architecture with:
  - Panel dock system (drag, lock, snap-back, window-shade)
  - TOC, Settings, Navigator, Bookmarks as dockable components
  - Lock toggle to prevent accidental moves
  - Snap-back to last valid position if dropped in invalid area
  - Per-user layout stored in reader_settings JSONB

- Update TypeScript types with PanelLayoutSettings and PanelState
- Add panel-dock-system.ts implementation to plan
- Add navigator-panel.ts for Affinity-style page navigation
- Update reader template with dockable panels and lock buttons

- Add Section 2.4 with database/Go implementation issues and fixes
- Document schema changes (DECIMAL -> REAL)
- Document all type fixes needed in reader.go
 2026-04-03 16:53:41 -04:00
john-okeefe 3228b62ea3 docs: update reader plan - Phase 0 prerequisites section 
Update READER_IMPLEMENTATION_PLAN.md to include comprehensive Phase 0
setup and verification guide.

## Phase 0: Prerequisites & Setup (NEW Section)

### 0.1 Database Schema Setup
- References Section 2.1 for SQL (no duplication)
- Step-by-step instructions for schema.sql modifications
- Database recreation vs manual migration options
- sqlc generate commands for Go code regeneration

### 0.2 Database Queries Setup
- 12 new SQL queries for reader functionality
- Complete query definitions with parameter types
- Instructions for regeneration with sqlc

### 0.3 Frontend Dependencies
- jszip@^3.10.1 for EPUB/comic archive parsing
- pdfjs-dist@^3.11.174 for PDF rendering
- npm install instructions

### 0.4 Directory Structure
- mkdir commands for reader components (ebook, comic, manga, pdf)
- Font directory for bundled reading fonts
- Bruno API test directory

### 0.5 Pre-Implementation Checklist
- 10-item verification checklist
- Database, frontend, and structure items

### 0.6 Verification Commands
- Database table existence check
- Query generation verification
- Frontend dependency verification
- Go build verification
- Directory structure verification

### 0.7 Troubleshooting
- Common setup problems and solutions
- sqlc generate failures
- Database table issues
- npm install problems
- Go compilation errors

## Rationale

This prevents developers from starting implementation without
the necessary foundation, which would result in:
- Compilation errors from missing database queries
- Runtime errors from missing database tables
- Frontend build errors from missing dependencies
- Lost time from having to stop and fix prerequisites

## Changes

- Added Phase 0 section (~415 lines)
- Updated database references
- Added verification commands
- Added troubleshooting guide

Total: 1 file changed, 24 insertions(+), 37 deletions(-)

Phase 0 is now complete and ready for implementation to begin.
 2026-04-02 21:02:08 -04:00
john-okeefe 40f519ce6e docs: add Phase 0 prerequisites section to reader implementation plan 
Add comprehensive setup and verification guide to ensure all
dependencies and database schema are in place before beginning
reader implementation.

## Phase 0: Prerequisites & Setup (NEW)

### 0.1 Database Schema Setup
- References Section 2.1 for actual SQL (no duplication)
- Clear step-by-step instructions for schema.sql modifications
- Instructions for both database recreation and manual migration
- sqlc generate commands for Go code regeneration

### 0.2 Database Queries Setup
- 12 new SQL queries for reader functionality:
  * Panel data: GetPanelData, UpsertPanelData
  * Reading speed: GetReadingSpeed, CreateReadingSpeed, UpdateReadingSpeed
  * Dictionary: GetDictionaryEntry, CreateDictionaryEntry, UpdateDictionaryAccessed
  * Settings: GetReaderSettings, UpsertReaderSettings
  * Bookmarks: GetMediaBookmarks, CreateMediaBookmark, DeleteMediaBookmark, UpdateMediaBookmark

### 0.3 Frontend Dependencies
- jszip@^3.10.1 for EPUB/comic archive parsing
- pdfjs-dist@^3.11.174 for PDF rendering
- npm install instructions

### 0.4 Directory Structure
- web/src/reader/{ebook,comic,manga,pdf}/
- web/static/fonts/ for reading fonts
- bruno/reader/ for API tests

### 0.5 Pre-Implementation Checklist
- 10-item verification checklist
- Database schema and queries
- Frontend dependencies
- Directory creation
- Go compilation verification

### 0.6 Verification Commands
- Database table existence check
- Query generation verification
- Frontend dependency verification
- Go build verification
- Directory structure verification

### 0.7 Troubleshooting
- Common setup problems and solutions
- sqlc generate failures
- Database table issues
- npm install problems
- Go compilation errors

## Rationale

This prevents developers from starting implementation without
the necessary foundation, which would result in:
- Compilation errors from missing database queries
- Runtime errors from missing database tables
- Frontend build errors from missing dependencies
- Lost time from having to stop and fix prerequisites

By completing Phase 0 first, implementation proceeds smoothly
with all infrastructure in place.

## File Changes
- READER_IMPLEMENTATION_PLAN.md: +415 lines (Phase 0 section)

Total: 1 file changed, 415 insertions(+)
 2026-04-02 20:09:43 -04:00
john-okeefe 925228f7cf docs: comprehensive reader implementation plan updates 
Major changes:
- Convert all 22 OOP classes to procedural TypeScript functions
- Add complete PDF reader implementation (15 subsections, 6.1-6.15)
- Add 8 technical textbook features for PDFs (TOC, bookmarks, clipboard,
  dual-page, mini-map, rotation, variable page sizes)
- Remove duplicate sections and fix section numbering (1-19 sequential)
- Add 7 new comic/manga features (7.4-7.10):
  * Page order presets with auto-detect and user override
  * Extended keyboard shortcuts (Space, PageUp/Down, +/-, B, F, 1-9)
  * Page slider/scrubber for quick navigation
  * Touch gesture controls (swipe, pinch-to-zoom, tap, double-tap)
  * Panel gap controls with adjustable spacing and borders
  * Background color options (black/white/gray/sepia)
  * Chapter markers with visual boundaries

Architecture improvements:
- Universal reader + pluggable parser pipeline (all ebooks → CIF)
- Client-side parsers: EPUB, FB2, TXT, HTML
- Server-side parsers: MOBI, AZW3, DOCX, RTF (Go backend)
- ~500 KB total dependencies vs 182 MB Calibre

Database schema updates:
- Rename pdf_bookmarks to media_bookmarks
- Add chapter_number and cfi_position fields for all media types
- Unified bookmarks for ebooks, comics, manga, and PDFs

Preserved features:
- 8 bundled libre reading fonts with complete setup scripts
- 5 reading-optimized themes (light, sepia, dark, night, high-contrast)
- Hybrid theming strategy (11 themes for UI, 5 for ebook text)
- Panel detection (grid-based + ML + manual override)
- All 4 media types: ebook, comic, manga, PDF

All code follows PROJECT_GUIDELINES.md:
- No OOP (no classes, no this-capture)
- Procedural/imperative style
- Backend handles all position calculations (CFI, character offsets, etc.)
- Frontend receives positions from backend, no duplication
 2026-04-02 16:58:45 -04:00
john-okeefe 9dd217afb6 docs: Complete Reader Implementation Plan overhaul with PDF support and universal reader architecture 
Major Architecture Changes:
- Added PDF support (Mozilla pdf.js) with text selection, highlights, search, bookmarks
- Universal reader with pluggable parser pipeline for all reflowable ebooks
- Common Intermediate Format (CIF) to standardize ebook parsing
- Server-side parsing for complex formats (MOBI, AZW3, DOCX, RTF)
- Client-side parsing for simple formats (EPUB, FB2, TXT, HTML)
- PDF-specific features: TOC navigation, bookmarks, dual-page view, mini-map

Procedural TypeScript:
- Refactored all code to follow PROJECT_GUIDELINES.md (no classes, no OOP)
- Functions and modules instead of classes
- Functional techniques where appropriate

New Components:
- Parser manager (router) to detect format and route to appropriate parser
- CIF types for universal ebook representation
- PDF reader with full feature set (text-layer, annotation, search, etc.)
- Server-side Go handlers for MOBI/AZW3/DOCX/RTF parsing

Database Schema:
- Added pdf_bookmarks table for custom PDF bookmarks

API Routes:
- Added PDF outline/TOC endpoint
- Added PDF thumbnail endpoint for mini-map

Theming:
- Added PDF-specific reading themes (5 options: light, sepia, dark, night, high-contrast)
- Hybrid approach maintained: chrome_theme for UI, reading_theme for content
 2026-04-02 16:54:34 -04:00
john-okeefe 9f7dffd292 docs: add comprehensive reader implementation plan 
Add detailed 8-week implementation plan for ebook, comic, and manga reader
with hybrid architecture, panel detection, offline support, and libre fonts.

Key Features:
- Hybrid reader architecture: Shared infrastructure + specialized components
- Ebook reader: EPUB parsing, HTML rendering, CFI navigation, typography engine
- Comic reader: Grid-based + ML + manual panel detection, zoom animations
- Manga reader: RTL navigation, vertical scroll mode
- Offline support: PWA with service worker, cached pages
- Dictionary: Offline-capable word lookup
- Annotations: Bookmarks, highlights, notes (reuses existing DB schema)
- Reading statistics: Speed tracking, time estimation
- KOReader-style progress: Pages, chapter-relative, percentage, time-left

Theming Strategy:
- UI Chrome: All 11 Bookhoard themes
- Ebook text: 5 reading-optimized themes (light, sepia, dark, night, high-contrast)
- Comics/manga: All 11 themes (visual content works well with colors)

Typography:
- 8 bundled libre fonts (~1.2MB WOFF2): Literata, Crimson Text,
  Source Serif 4, EB Garamond, Libertinus, Noto Serif, Charis SIL, IBM Plex
- Standard weights only (400, 400i, 700, 700i)
- Font acquisition script included
- Offline-ready (no network requests for fonts)

Database Schema:
- panel_data: Hybrid panel detection (grid/ML/manual)
- reading_speed: Per-user reading speed tracking
- dictionary_cache: Offline dictionary support
- reader_settings: Per-user preferences (DB + localStorage fallback)

API Endpoints:
- 10 new reader routes (/api/readers/*)
- Lazy-loading page cache (5-page ahead)
- WebSocket integration for real-time sync
- Bruno API tests included

Phased Timeline:
- Week 1-2: Infrastructure & basic reader
- Week 3-4: Comic/manga features
- Week 5-6: Advanced features
- Week 7: Offline support
- Week 8: Polish & testing

Code Reuse:
- Reuses existing WebSocket sync, progress tracking, annotations
- Surgical code edits (extend, don't duplicate)
- Follows existing Bookhoard patterns and conventions

Includes:
- Database schema changes (SQL)
- API endpoint specifications
- TypeScript type definitions
- Frontend architecture (SSR-first with Alpine.js)
- Integration test patterns
- Bruno OpenCollection YAML tests
- User and developer documentation locations

Estimated total implementation time: 8 weeks
 2026-04-01 21:10:34 -04:00