Library Manager - Universal Novel Scraper

Overview

The Library Manager is your personal EPUB collection hub. It provides a modern interface for managing downloaded novels, tracking reading progress, and accessing a built-in EPUB reader with customizable themes.

All EPUBs stored in your library include extracted cover images, metadata, and automatic progress synchronization.

Library Views

Grid View

The default card-based layout displays:

Cover images extracted from EPUB files
Reading progress bars (for in-progress books)
Completion badges (green “Completed” tag)
Quick actions on hover (Read, Open, Download, Delete)

Features
Implementation

Visual browsing with large cover previews
Hover effects reveal action buttons
Progress indicators at bottom of each card
Animated transitions on page load
Responsive grid (2-6 columns based on screen size)

// Grid layout configuration
<div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 
                lg:grid-cols-5 xl:grid-cols-6 gap-x-6 gap-y-10">
  {books.map((book) => (
    <NovelCard 
      cover={`${API_BASE}/cover/${book.filename}`}
      progress={readProgress[book.filename]}
      onClick={() => handleReadNow(book)}
    />
  ))}
</div>

List View

Compact row-based layout showing:

Thumbnail covers (12x16px)
Title and author in single row
Progress text (e.g., “Ch 45 / 120”)
Quick actions on hover

List view is ideal for large collections where you need to scan titles quickly.

Library Statistics

The header displays interactive filter buttons:

Total Books

Complete count of all EPUBs in your library

Reading

Books with progress > 0% but < 100%

Completed

Books where you’ve reached the final chapter

Status Filtering

Click any statistic card to filter the library:

// Filter logic
const filteredBooks = books.filter(book => {
  const prog = readProgress[book.filename];
  const isCompleted = prog?.current === prog?.total;
  const isReading = prog?.current > 0 && prog?.current < prog?.total;
  
  if (statusFilter === 'reading' && !isReading) return false;
  if (statusFilter === 'completed' && !isCompleted) return false;
  
  return true;
});

Active filters are highlighted with a blue border and ring effect.

Search & Sort

Search Bar

Instant search across:

Title: Novel name
Author: Author metadata

🔍 Search by title or author...

Search is case-insensitive and matches partial strings (e.g., “estate” finds “The Greatest Estate Developer”).

Sort Options

Available Sorts
Direction Toggle

Sort Type	Order
Title	A-Z or Z-A
Author	A-Z or Z-A
Newest First	By date added (recent first)
Oldest First	By date added (oldest first)
File Size	Smallest to largest

Book Actions

Individual Actions

Hover over any book card to reveal:

Read Now

Opens the built-in EPUB reader (preserves progress)

Open Externally

Launches EPUB in your system’s default reader (e.g., Apple Books, Calibre)

Download

Downloads the EPUB file to your system

Delete

Removes the EPUB from library (requires confirmation)

Bulk Actions

Enable Selection Mode to manage multiple books:

Enter Selection Mode

Click the checkmark icon in the toolbar

Select Books

Click on book cards to toggle selection (blue ring indicates selected)

Bulk Delete

Click Delete button to remove all selected books at once

Exit Selection

Click Cancel or complete the bulk action

Bulk delete permanently removes EPUBs from the library. This action cannot be undone.

EPUB Reader

Opening a Book

Click Read Now or the book card to launch the full-screen reader.

The reader automatically resumes from your last read position using locally stored CFI (Canonical Fragment Identifier) bookmarks.

Reader Interface

Controls
Progress Tracking
Theme Customization

Top Navigation Bar:

Title & Author: Displayed prominently
Chapter Progress: Live indicator (e.g., “Ch. 24 / 150”)
Theme Toggle: Switch between dark and light modes
Close Button: Exit reader and save progress

Reading Area:

Click left edge to go to previous page
Click right edge to advance to next page
Click center to toggle navigation overlay
Table of Contents: Hamburger menu (left sidebar)

Progress is saved automatically every time you turn a page:

// Progress storage
const progressData = {
  cfi: epubcifi,           // Page position
  current: currentChapter,  // Chapter number
  total: totalChapters      // Total chapter count
};

localStorage.setItem(
  `epub-progress-${book.filename}`, 
  JSON.stringify(progressData)
);

This data persists across app restarts.

Dark Mode (default):

Background: #09090b (near-black)
Text: #e4e4e7 (light gray)
Links: #3b82f6 (blue)

Light Mode:

Background: #ffffff (white)
Text: #18181b (dark gray)
Links: #2563eb (darker blue)

Theme preference is remembered per-session but resets on app restart. This will be made persistent in a future update.

Arrow Keys

Left/Right: Navigate pagesUp/Down: Scroll within current page (if content overflows)

Escape Key

Quickly exit the reader and return to library

Importing EPUBs

Manual Import

Click Import Button

Select Import EPUB in the library header

Choose File

Native file picker opens → select .epub file

Automatic Processing

File copied to library directory
Cover extracted via backend
Metadata parsed
Book appears in library grid

// Import handler
const handleAddEpub = async () => {
  if (window.electronAPI) {
    const added = await window.electronAPI.addEpubToLibrary();
    if (added) fetchBooks(); // Refresh library
  }
};

Browse Library Directory

Click Browse Directory to open your library folder in the system file manager:

Windows: %APPDATA%/UNS/library/
macOS: ~/Library/Application Support/UNS/library/
Linux: ~/.config/UNS/library/

You can manually add EPUBs by copying them to this directory. Restart the app to see them in the library.

Reading Progress Details

Progress Calculation

const percentage = (current / total) * 100;

Status	Condition
Not Started	`current === 0`
In Progress	`current > 0 && current < total`
Completed	`current === total`

Visual Indicators

Grid View
List View

Progress bar: Thin line at bottom of card (blue gradient)
Percentage: Hidden in grid, visible on hover
Completion badge: Green “Completed” tag at top-left

Empty State

When no books match filters:

📚 No matches found

Try adjusting your search terms or filters.

[ Clear Filters ]

When library is empty:

📖 Your collection is empty

Import your EPUB files to start building your personal library.

Download novels from the Search page to automatically populate your library with properly formatted EPUBs.

Advanced Features

Cover Extraction

Covers are automatically extracted from EPUB metadata:

GET /api/cover/{filename}

If no cover is embedded, a fallback placeholder is shown:

<div className="flex items-center justify-center bg-zinc-900">
  <BookOpen size={48} className="text-zinc-800" />
  <span>No Cover</span>
</div>

Metadata Display

Title: Extracted from <dc:title> in EPUB metadata
Author: Extracted from <dc:creator> in EPUB metadata
Date Added: File creation timestamp
File Size: Calculated from EPUB file size

Troubleshooting

Books not appearing in library

Check that files are valid EPUB format (not MOBI or PDF)
Restart the app to trigger library refresh
Verify Python backend is running (http://localhost:8000/api/library)
Check file permissions in library directory

Progress not saving

Browser localStorage might be full (clear app cache)
Check console for JavaScript errors
Ensure you’re using the same device (progress is local)

Reader not opening

Large EPUBs (>50MB) may take 5-10 seconds to load
Check console for errors like “Failed to fetch EPUB”
Verify EPUB is not corrupted (try opening in another reader)

Covers not displaying

Some EPUBs don’t include cover metadata
Backend cover extraction requires valid image format (JPG/PNG)
Check /api/cover/{filename} endpoint directly in browser

Next Steps

Download Novels

Scrape new content to add to your library

Search & Discover

Find novels across multiple sources

EPUB Reader

Read your novels with the built-in reader

Provider System

Add more novel sources

Getting Started

Core Features

Advanced Usage

Architecture

Developer Guide

Help

​Overview

​Library Views

​Grid View

​List View

​Library Statistics

Total Books

Reading

Completed

​Status Filtering

​Search & Sort

​Search Bar

​Sort Options

​Book Actions

​Individual Actions

Read Now

Open Externally

Download

Delete

​Bulk Actions

​EPUB Reader

​Opening a Book

​Reader Interface

​Keyboard Navigation

Arrow Keys

Escape Key

​Importing EPUBs

​Manual Import

​Browse Library Directory

​Reading Progress Details

​Progress Calculation

​Visual Indicators

​Empty State

​Advanced Features

​Cover Extraction

​Metadata Display

​Troubleshooting

​Next Steps

Download Novels

Search & Discover

EPUB Reader

Provider System

Build docs developers (and LLMs) love

Overview

Library Views

Grid View

List View

Library Statistics

Status Filtering

Search & Sort

Search Bar

Sort Options

Book Actions

Individual Actions

Bulk Actions

EPUB Reader

Opening a Book

Reader Interface

Keyboard Navigation

Importing EPUBs

Manual Import

Browse Library Directory

Reading Progress Details

Progress Calculation

Visual Indicators

Empty State

Advanced Features

Cover Extraction

Metadata Display

Troubleshooting

Next Steps