TeleBook 4.0: Next-Generation Cross-Platform Book Management & Reading App

TeleBook is a powerful cross-platform book parsing, management, and reading application developed with Flutter. It supports multiple import methods, intelligent library management, personalized reading experiences, and multi-device sync, making digital reading more convenient and comfortable than ever before.

Note: Version 4.0 is a major sync-engine rewrite (multi-device sync core re-implemented). Please back up your data before upgrading.

✨ Version 4.0 Highlights: Sync Engine Rewrite + True Background Sync + Diagnostics

🔄 Unified Sync Task Queue (every sync action is a "group task")

• One task model: Init / Refresh / Upload snapshot / Manual sync / Conflict resolution / Resume last sync / Local-change push — all enter the same serialized group-task queue
• Task Center page: queue list → task detail → per book → per image (3-level status). Failures show their cause and support whole-batch / single-book / single-page retry
• Unified global status strip (single source of truth): current task (Book X/N · page a/b) / pending conflicts / failed tasks, with a "View" button straight into the Task Center
• Local sync history: tasks in queue order; failed/interrupted tasks can be expanded and retried in place (reuses the original row, no ghost entries)

🔄 Resume & Interrupted-Task Recovery

• True resume: if a task is interrupted (app killed / network lost), restart marks leftover tasks interrupted; on user confirmation it resumes in place from the persisted task spec — already-finished books/pages are skipped, nothing is re-transferred and no duplicate history rows are created
• Failure isolation: a failing book/image never blocks the rest of the batch; failed pages fall back to "waiting" and retry cleanly without leftover partial files

🛡️ Streamlined Conflict Resolution

• Bidirectional sync detects content conflicts → conflict list → pick "Keep server" or "Keep local" per book
• The resolution itself runs as a group task and lands in local history — visible and retryable end to end

📱 iOS: True Background Download & Upload (native URLSession)

• Native background queue: a whole book's images are handed to the system URLSession background session at once; the native side caps concurrency and auto-dispatches the next task — the batch keeps progressing while the app is locked, suspended, or even killed by the system (no longer depends on the Dart process staying alive)
• Kill-recovery: each task's destination path is encoded into the request, so after the app is relaunched the system wakes it to finish writing files
• Background direct upload: new server endpoint uploads whole files (raw PUT, content-addressed & idempotent), falling back to chunked upload on failure

🤖 Android: Foreground-Service Keep-Alive

• A foreground service (persistent notification + partial wake lock) runs during sync, so the screen-off / backgrounded device stays online until the batch finishes

🐛 Image-Order Fix

• Fixed scrambled page order after repeated download retries: the server persists files in upload order and the client builds its page list from that order — no retry path rewrites page order anymore

🧰 Diagnostics & Logging (crash forensics)

• Unified logger: console + rolling file ({appDocDir}/logs/app.log) + in-memory ring buffer (last 200 lines before a crash)
• Automatic crash capture: Dart errors (FlutterError / async / zone) are written to crash records with device model, OS version, app version, sanitized server URL and the pre-crash buffer
• Log robustness: 2MB × 4 rolling files, total-dir budget, 30-min periodic cleanup, 10 crash records kept (max 30 days), write-failure cooldown & self-heal, legacy log migration
• Settings → Debug: live "Diagnostics Log" viewer + one-tap "Export Diagnostics Bundle" (logs + crash records + device info) shared via the system sheet; key lifecycle events (boot / DB migration / sync / foreground-background) are instrumented, so even other people's crash reports can be traced quickly

✨ New in Version 3.1: Multi-Device Sync (legacy)

🔄 Local-First (Offline-Ready)

• Offline usable: All changes (import / edit / delete / reading progress) take effect locally immediately and are queued for background push
• No interruption on disconnect: Keep using normally without network; sync catches up automatically when back online
• Status strip: Conflict > manual sync progress > syncing > pending N (tap to sync now)

🌐 Full-Library Sync

• Books & images: Book info, reading progress, and all image files stay consistent across devices
• Sync on connect: A new device downloads the whole library after "Save & Connect", with per-book image download progress
• Content addressing: Images deduplicated by SHA-256 with chunked upload; duplicate content is never re-transferred

📚 Full-Library Snapshot History

• Sensitive operations (import / edit / delete / manual sync) archive a full-library snapshot on completion
• Browse history and restore to any archived point with one tap (full-library replacement)

📋 Local Sync Logs

• Each sync session: time / book count / status
• Expand each book: upload / download status
• Expand each image: upload / download progress

🛡️ Conflict Handling

• Conflicts detected automatically when multiple devices edit the same book
• Choose: keep local / keep server / manual merge (batch selection supported)

📍 Reading Progress Sync

• Auto-saved on page turn (800ms debounce); other devices resume at the last position
• High-frequency updates are merged automatically to avoid task flooding

✨ Major Updates in Version 3.0 (legacy)

📚 Brand New Library Management System

• 🗂️ Folders Feature: Create custom folders with icons and colors for intelligent book categorization
• ⭐ Star System: Add colorful labels to books for quick identification and filtering
• 📊 Layout Switching: Support for both list view and grid view display modes for personalized bookshelf experience
• ⚡ Batch Operations: Batch select, move, delete, and export books for efficient management of large collections
• 🔍 Smart Filtering: Quickly locate target books by folders, tags, and search keywords

📖 Personalized Reading Experience

• 📍 Reading Progress Tracking: Automatically save reading position for each book with seamless bookmark resume
• 🔄 Multiple Reading Directions: Support left-to-right, right-to-left (for manga), and top-to-bottom (long strip mode) reading
• ⚙️ Reading Settings: Quick access to reading direction settings via settings button, with auto-save
• 📊 Smart Progress Bar: Different progress indicator styles based on reading direction, showing percentage for vertical scrolling

📝 Enhanced Book Editing

• ✏️ Instant Renaming: Quickly rename books in the edit page with immediate effect
• 🗑️ Smart Deletion: Automatically clean up physical files and database records when deleting images to prevent storage waste
• 📄 Real-time Sync: All editing operations sync to database immediately, ensuring data consistency

🎨 UI & Performance Optimizations

• 🌙 Dark Mode Adaptation: Full support for system dark mode with eye-friendly night reading
• ⚡ Performance Optimization: Improved memory usage, loading speed, and responsiveness
• 🐛 Bug Fixes: Fixed known issues, enhanced app stability
• 💫 UI Beautification: Interface detail optimizations with more modern design language

🌐 Versatile Content Import

WebView Web Parsing

• Built-in WebView browser for direct web content loading
• Intelligent extraction of all images from pages
• Support for Telegraph and other image-based websites
• Real-time preview with selective download

Single Archive Import

• Support for ZIP, CBZ, RAR, and other compressed formats
• Automatic extraction and image file recognition
• Quick library building
• Unified file naming (8-digit leading zero format)

Batch Archive Import

• Select folder and automatically scan all ZIP/CBZ files
• Parallel extraction with background processing that doesn't block UI
• Editable file list for each archive (sorting, deletion)
• Batch save and one-click import of multiple books

PDF File Import

• Direct import of PDF files and conversion to image format
• High-quality image rendering support
• Automatic pagination processing

Image Folder Import

• Direct import of folders containing images
• Support for single folder and batch folder import
• Automatic sorting by filename

📤 Powerful Export Feature

• Single Book Export: Export as standard ZIP archive
• Batch Export: Select multiple books for one-click export
• Background Processing: Using Isolate technology, export process doesn't affect UI smoothness
• Smart Naming: Automatically use book name as filename

📥 Download & Installation

Method 1: Download Pre-compiled Version

Visit GitHub Releases to download the latest version

• Android: Download APK file and install directly
• iOS: Download IPA file (requires self-signing)
• Windows: Download ZIP and extract to run (requires WebView2 Runtime, usually pre-installed on Win10 1809+)
• macOS: Download ZIP and extract to run (unsigned, allow on first launch in System Settings → Privacy & Security)

Note

: The desktop version is now built with Flutter and released in this repository, supporting Windows / macOS.

Method 2: Manual Compilation

# Clone the project
git clone https://github.com/dorkytiger/TeleBook.git
cd TeleBook

# Install dependencies
flutter pub get

# Generate code (Drift database)
flutter pub run build_runner build --delete-conflicting-outputs

# Build
flutter build apk        # Android
flutter build ios        # iOS
flutter build windows    # Windows
flutter build macos      # macOS

🚀 Quick Start

📖 Import Your First Book

Method 1: Parse via Web Link

1. Copy Book Link - Find your desired book on Telegraph or other websites, copy the link
2. Open Import Interface - Click the ➕ icon in the top right corner
3. Select Web Data Source - Choose "Web", paste the link in the "URL" field
4. Parse and Preview - App automatically loads the page and extracts images with real-time preview
5. Add to Download Queue - Click "Save" button to add images to download queue
6. Save Book - After download completes, click "Save Book" to add to bookshelf

Method 2: Import via Archive

1. Prepare Archive - Package image files into ZIP, CBZ or other compressed formats
2. Select Archive Data Source - Click ➕, choose "Archive"
3. Select File - Click "Select File", choose archive from device
4. Auto Extract - App automatically extracts and recognizes images, click "Save" to add to bookshelf

Method 3: Batch Archive Import

1. Prepare Folder - Place multiple ZIP/CBZ files in the same folder
2. Select Batch Data Source - Choose "Batch Archive"
3. Select Folder - Choose the folder containing archives
4. Edit File List - Optionally edit file order for each archive
5. Batch Import - Click ✅ button to batch save all books

📚 Manage Your Library

Create Folders

1. Enter Folder Management - In the book list page, click the three-dot menu in top right → "Folder Management"
2. Create New Folder - Click ➕ button, enter name, select icon and color
3. Add Books to Folder - Long press book and select "Add to Folder", or use batch operations

Use Tag System

1. Create Tags - Create different colored tags in "Tag Management" page
2. Add Tags to Books - Select "Add Tag" in book operation menu
3. Filter by Tags - Use filter function in book list to view books by tag

Switch Display Layout

• In the book list page, click the filter button to switch between list view and grid view

📖 Personalized Reading Settings

Set Reading Direction

1. Open Reading Settings - Click the settings icon in top right corner of reading page
2. Choose Reading Direction:
   • Left to Right: Suitable for most books and comics
   • Right to Left: Suitable for Japanese manga
   • Top to Bottom: Suitable for long strip comics with continuous scrolling display
3. Auto-save Settings - Settings are saved immediately upon selection and automatically applied next time

Reading Progress Tracking

• App automatically records reading position for each book
• Automatically jumps to last reading position when reopening book
• Progress bars visible for each book in the book list

📖 Reading Experience

🎯 Smart Progress Display

• Pagination Mode (horizontal reading): Shows current page number and draggable progress slider
• Scrolling Mode (vertical reading): Shows percentage progress and linear progress bar
• Real-time Sync: Reading progress saved to local database in real-time

🔄 Diverse Reading Methods

• Traditional Page Turning: Swipe left/right to turn pages, suitable for comics and albums
• Continuous Scrolling: Swipe up/down with seamless image connection, suitable for long strip comics
• Reverse Reading: Right-to-left page turning, supports Japanese manga reading habits

🖼️ Enhanced Image Viewing

• Zoom Support: Pinch to zoom for detail viewing (0.5x - 4x)
• Fullscreen Immersion: Tap to toggle progress bar display
• High-quality Rendering: Maintains original image quality

🛠️ Tech Stack

• Flutter 3.47+ - Cross-platform UI framework
• Riverpod - State management & dependency injection
• Drift - Local database (SQLite)
• ForUI - UI component library (shadcn-style)
• webview_all - Cross-platform WebView (system WebView on Windows/macOS)
• pdf / pdfrx - PDF parsing & rendering
• archive - Archive processing
• path_provider - File path management
• file_picker - File selection
• Go + PostgreSQL + MinIO - Multi-device sync backend (TelebookServer)

🔄 Multi-Device Sync Setup

1. Deploy backend: Clone TelebookServer, configure cp .env.example .env secrets, then docker compose up --build
2. Connect device A: Settings → Sync Server → enter server address (e.g. http://192.168.x.x:18080) and connection key → Save & Connect, library and images upload automatically
3. Connect device B: Same steps; the whole library downloads automatically
4. Continuous sync: Imports / edits / deletes / reading on either side sync to the other automatically; offline operations never block, and catch up when back online

✅ Completed Features

New in Version 4.0 (sync engine rewrite)

• ✅ Unified group-task queue (init / refresh / snapshot upload / manual / conflict / resume / push)
• ✅ Sync Task Center (queue → task → book → image 3-level detail; batch / per-book / per-page retry)
• ✅ Unified global status strip (single source of truth)
• ✅ Local sync history (expand & retry in place, no ghost rows)
• ✅ True resume after interruption (in-place recovery from persisted spec, no re-transfer)
• ✅ Streamlined conflict resolution (keep-server/keep-local runs as a group task)
• ✅ iOS native background download/upload (URLSession queue; keeps going when locked/suspended/killed; kill-recovery writes files on relaunch)
• ✅ Android foreground-service keep-alive (stays online with screen off)
• ✅ Image-order fix (retries no longer scramble page order)
• ✅ Diagnostics logging (rolling file + automatic crash capture + ring-buffer forensics)
• ✅ One-tap diagnostics bundle export (logs + crashes + device info; other people's crashes become traceable)

New in Version 3.1 (legacy)

• ✅ Multi-device sync (local-first + outbox background push)
• ✅ Full-library snapshot history & restore
• ✅ Local sync logs (session → book → image detail)
• ✅ Image file sync (SHA-256 dedup + chunked upload + presigned download)
• ✅ Conflict detection & resolution (keep local / server / manual merge)
• ✅ Reading progress sync (debounced save + task merging)
• ✅ Non-dismissable sync download page on connect (per-book progress)
• ✅ Sync status strip in bottom bar

New in Version 3.0 (legacy)

• ✅ Folder feature (custom icons and colors)
• ✅ Star system (colorful labels)
• ✅ Layout switching (list/grid view)
• ✅ Batch operations
• ✅ Dark mode adaptation
• ✅ Reading progress tracking
• ✅ Multiple reading directions (left-right/right-left/top-bottom)
• ✅ Slider pagination (draggable progress slider)
• ✅ Reading settings persistence
• ✅ Instant rename function
• ✅ Smart file deletion
• ✅ Real-time data sync
• ✅ Download group operations (retry / delete, ✓ after auto-save)
• ✅ Business blue theme
• ✅ Performance optimization

Core Features

• ✅ WebView web parsing
• ✅ Archive import (ZIP/CBZ/RAR)
• ✅ Batch archive import
• ✅ PDF file import
• ✅ Image folder import
• ✅ Batch folder import
• ✅ Book export feature
• ✅ Background download management
• ✅ Local library management
• ✅ Windows / macOS desktop support

📝 Future Development Plans

Short-term Plans

• Enhanced bookmark feature (in-page bookmarks)
• Reading history
• Global search function
• Theme customization

Long-term Vision

• Linux desktop support
• Community sharing
• Plugin system
• AI smart recommendations

🌟 TeleBook 3.0 Feature Overview

Feature Category	Feature	Description
📚 Content Import	WebView Parsing	Direct parsing of Telegraph and image websites
	Archive Import	Support for ZIP/CBZ/RAR and more
	PDF Import	High-quality PDF to image conversion
	Folder Import	Batch import of image folders
🗂️ Library Management	Folder System	Custom icon and color folders
	Star System	Colorful labels for quick identification
	Batch Operations	Multi-select edit, move, delete
	Smart Filtering	Multi-dimensional book filtering
📖 Reading Experience	Progress Tracking	Bookmark resume with auto-save position
	Multi-direction	Three reading modes: LTR/RTL/TTB
	Smart Progress	Adaptive display styles
	Zoom Viewing	0.5x-4x zoom support
🎨 UI Experience	Dark Mode	Full system theme adaptation
	Dual Layout	List/grid view switching
	Modern Design	ForUI-style UI (shadcn design language)
	Performance	Smooth responsive experience

🤝 Contributing

Issues and Pull Requests are welcome!

How to Contribute

1. Fork this project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Thanks to all developers and users who have contributed to TeleBook!

---

⭐ If TeleBook helps you, please give it a Star!

📱 Download Now: GitHub Releases