Books

Books is the native EPUB reader for ryOS, designed to provide a tactile and immersive reading experience. It combines a skeuomorphic "wooden bookshelf" interface for library management with a high-performance, customizable reader for digital publications.

Overview

The Books app serves as the central hub for all electronic publications within the ryOS ecosystem. Its primary goal is to bridge the gap between digital convenience and the physical feel of reading, featuring smooth page-turn animations and a sophisticated zoom transition that moves the user seamlessly from the library shelf into the text.

Beyond simple viewing, Books integrates deeply with the ryOS file system. It automatically monitors the /Books directory, ensuring that any EPUB files imported via Finder or the app's own import utility are instantly cataloged, synchronized to the cloud, and assigned generated cover art for a consistent visual aesthetic.

Features

Core Functionality

EPUB Support: High-fidelity rendering of standard EPUB files with support for complex layouts.
Cloud Synchronization: Reading progress and library contents are automatically synced across ryOS instances.
Finder Integration: Import books directly through the File menu or by placing files in the system /Books folder.

User Interface

The Wooden Bookshelf: A skeuomorphic shelf view that displays your collection with dynamically generated book covers.
Interactive Page-Turns: A realistic reading interface where users can flip pages via click, keyboard, or touch gestures.
Animated Transitions: Smooth zoom-in and zoom-out effects when opening or closing books to maintain spatial context.

Customization & Accessibility

Typography Control: Choose from curated reading fonts, including the classic EB Garamond, and adjust text size for comfort.
Flexible Layouts: Toggle between single-column and double-column views to suit different window sizes and screen aspect ratios.
Adaptive Themes: Support for Light, Sepia, and Dark modes, with the ability to follow the global ryOS system theme automatically.

User Guide

Getting Started

To begin, launch the Books app from the ryOS App Launcher. If your library is empty, go to File ▸ Import to select an EPUB file from your local disk or ryOS storage. The book will appear on your shelf once the import is complete.

Key Actions

Opening a Book: Click any book cover on the shelf. The interface will zoom into the cover and transition into the reader view.
Navigating Pages: Click the left or right edges of the page to turn. Alternatively, use the Left/Right Arrow keys on your keyboard or swipe gestures on touch-enabled devices.
Adjusting the View: Use the View menu to change the theme (Light, Sepia, Dark), modify font sizes, or switch between single and double-column layouts.
Returning to Shelf: Click the "Back" or "Close" button in the navigation bar to trigger the reverse zoom animation and return to your collection.

Tips & Shortcuts

Automatic Bookmarks: You never need to manually save your place. Books remembers your exact progress and will return you to the same page next time you open the app.
Responsive Resizing: If you prefer a "paperback" feel, resize the window to a narrower width; the reader will automatically switch to a single-column layout.

Technical Details

Window Configuration

Default Size: 720×560px
Minimum Size: 420×360px

Component Architecture

The app is built using a modular React architecture, utilizing motion (from Framer Motion) for high-performance layout animations. Component Files:

src/apps/books/components/BookCloseZoom.tsx: Handles the "reverse-zoom" animation from reader to shelf.
src/apps/books/components/BookCover.tsx: Renders the visual representation of a book's front cover.
src/apps/books/components/BooksMenuBar.tsx: The top-level application menu for File and View actions.
src/apps/books/components/BooksReaderPane.tsx: The main container for the EPUB reading engine.
src/apps/books/components/BooksShelfView.tsx: Manages the grid layout and wooden shelf styling.
src/apps/books/components/ShelfBook.tsx: Individual book items within the shelf view.
src/apps/books/components/books-app/BooksAppComponent.tsx: The primary entry point and orchestrator for the app.

Hooks & Utilities

Custom Hooks:

src/apps/books/hooks/useBooksLogic.ts: Centralizes library management, file system watchers, and import logic.

Utilities:

src/apps/books/utils/booksReader.ts: Logic for parsing EPUB content and managing pagination.
src/apps/books/utils/useBookCover.ts: Utility for extracting or generating cover images from EPUB metadata.

State Management

Books utilizes a combination of local component state (for UI transitions) and a dedicated useBooksStore (Zustand). The store tracks the user's library, current reading settings (font, size, theme), and the reading progress for every book in the collection.

Related Apps

Finder: Use Finder to organize your .epub files within the /Books directory for automatic library updates.

Control Panels: Configure system-wide appearance settings to have the Books app automatically toggle between Light and Dark reading modes.