feat: implement group EPUB upload and section splitting (US #29)

Backend:
- Create hermes Django app with models: ReadingGroup, GroupBook, Section, ReadingSchedule, MemberProgress
- EPUB section splitting service with automatic detection and reading time estimation
- Section recommendation engine for 4-week meeting schedule
- REST API endpoints for groups, books, sections, schedule, and member progress
- Manual section adjustment (merge/split) support

Frontend:
- GroupsPage: list/create reading groups
- GroupDetailPage: manage members, upload EPUB to group, view group books
- GroupBookPage: section breakdown with merge/split controls, reading schedule, member progress
- API client and TypeScript types for all group operations
- i18n keys for English and Spanish

Shared:
- Group-related types and API endpoint constants in packages/shared

backend/apps/groups/admin.py

@@ -0,0 +1,46 @@
+from django.contrib import admin
+
+from apps.groups.models import (
+    GroupBook,
+    MemberProgress,
+    ReadingGroup,
+    ReadingGroupMembership,
+    ReadingSchedule,
+    Section,
+)
+
+
+@admin.register(ReadingGroup)
+class ReadingGroupAdmin(admin.ModelAdmin):
+    list_display = ["name", "admin", "created_at"]
+    search_fields = ["name", "admin__email"]
+
+
+@admin.register(ReadingGroupMembership)
+class ReadingGroupMembershipAdmin(admin.ModelAdmin):
+    list_display = ["user", "group", "role", "joined_at"]
+    list_filter = ["role", "group"]
+
+
+@admin.register(GroupBook)
+class GroupBookAdmin(admin.ModelAdmin):
+    list_display = ["title", "group", "status", "uploaded_by", "created_at"]
+    list_filter = ["status"]
+    search_fields = ["title", "group__name"]
+
+
+@admin.register(Section)
+class SectionAdmin(admin.ModelAdmin):
+    list_display = ["title", "group_book", "order", "estimated_reading_minutes"]
+    ordering = ["group_book", "order"]
+
+
+@admin.register(ReadingSchedule)
+class ReadingScheduleAdmin(admin.ModelAdmin):
+    list_display = ["group_book", "meeting_number", "week_date"]
+    ordering = ["group_book", "meeting_number"]
+
+
+@admin.register(MemberProgress)
+class MemberProgressAdmin(admin.ModelAdmin):
+    list_display = ["user", "group_book", "current_section", "updated_at"]

backend/apps/groups/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class GroupsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.groups"
+    verbose_name = "Reading Groups"

backend/apps/groups/migrations/0001_initial.py

@@ -0,0 +1,154 @@
+# Generated by Django 5.1.7 on 2026-06-20 19:21
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('books', '0003_readingprogress_epub_location'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ReadingGroup',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(db_index=True, max_length=256)),
+                ('description', models.TextField(blank=True, default='')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('admin', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='administered_groups', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Reading Group',
+                'verbose_name_plural': 'Reading Groups',
+                'db_table': 'groups_reading_group',
+                'ordering': ['-created_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='GroupBook',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(db_index=True, max_length=512)),
+                ('status', models.CharField(choices=[('active', 'Active'), ('replaced', 'Replaced')], db_index=True, default='active', max_length=16)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('ebook', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='group_books', to='books.ebook')),
+                ('uploaded_by', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='uploaded_group_books', to=settings.AUTH_USER_MODEL)),
+                ('group', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='group_books', to='groups.readinggroup')),
+            ],
+            options={
+                'verbose_name': 'Group Book',
+                'verbose_name_plural': 'Group Books',
+                'db_table': 'groups_group_book',
+                'ordering': ['-created_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='ReadingGroupMembership',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('role', models.CharField(choices=[('admin', 'Admin'), ('member', 'Member')], default='member', max_length=16)),
+                ('joined_at', models.DateTimeField(auto_now_add=True)),
+                ('group', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='memberships', to='groups.readinggroup')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Reading Group Membership',
+                'verbose_name_plural': 'Reading Group Memberships',
+                'db_table': 'groups_membership',
+            },
+        ),
+        migrations.AddField(
+            model_name='readinggroup',
+            name='members',
+            field=models.ManyToManyField(related_name='reading_groups', through='groups.ReadingGroupMembership', to=settings.AUTH_USER_MODEL),
+        ),
+        migrations.CreateModel(
+            name='ReadingSchedule',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('meeting_number', models.PositiveIntegerField()),
+                ('week_date', models.DateField()),
+                ('section_ids', models.JSONField(default=list, help_text='Ordered list of Section IDs for this meeting')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('group_book', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='schedules', to='groups.groupbook')),
+            ],
+            options={
+                'verbose_name': 'Reading Schedule',
+                'verbose_name_plural': 'Reading Schedules',
+                'db_table': 'groups_reading_schedule',
+                'ordering': ['meeting_number'],
+            },
+        ),
+        migrations.CreateModel(
+            name='Section',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(max_length=512)),
+                ('order', models.PositiveIntegerField(db_index=True)),
+                ('start_chapter_index', models.PositiveIntegerField(default=0)),
+                ('end_chapter_index', models.PositiveIntegerField(default=0)),
+                ('estimated_reading_minutes', models.PositiveIntegerField(default=0)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('group_book', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='sections', to='groups.groupbook')),
+            ],
+            options={
+                'verbose_name': 'Section',
+                'verbose_name_plural': 'Sections',
+                'db_table': 'groups_section',
+                'ordering': ['order'],
+            },
+        ),
+        migrations.CreateModel(
+            name='MemberProgress',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('completed_sections', models.JSONField(default=list, help_text='Ordered list of completed Section IDs')),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('group_book', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='member_progress', to='groups.groupbook')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='group_progress', to=settings.AUTH_USER_MODEL)),
+                ('current_section', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='current_readers', to='groups.section')),
+            ],
+            options={
+                'verbose_name': 'Member Progress',
+                'verbose_name_plural': 'Member Progress',
+                'db_table': 'groups_member_progress',
+            },
+        ),
+        migrations.AddIndex(
+            model_name='groupbook',
+            index=models.Index(fields=['group', 'status'], name='groups_grou_group_i_afdbf7_idx'),
+        ),
+        migrations.AlterUniqueTogether(
+            name='readinggroupmembership',
+            unique_together={('user', 'group')},
+        ),
+        migrations.AddIndex(
+            model_name='readingschedule',
+            index=models.Index(fields=['group_book', 'meeting_number'], name='groups_read_group_b_2fc416_idx'),
+        ),
+        migrations.AlterUniqueTogether(
+            name='readingschedule',
+            unique_together={('group_book', 'meeting_number')},
+        ),
+        migrations.AddIndex(
+            model_name='section',
+            index=models.Index(fields=['group_book', 'order'], name='groups_sect_group_b_e2810a_idx'),
+        ),
+        migrations.AlterUniqueTogether(
+            name='section',
+            unique_together={('group_book', 'order')},
+        ),
+        migrations.AlterUniqueTogether(
+            name='memberprogress',
+            unique_together={('user', 'group_book')},
+        ),
+    ]

backend/apps/groups/models.py

@@ -0,0 +1,161 @@
+from django.conf import settings
+from django.db import models
+
+from apps.books.models import EBook
+
+
+class ReadingGroup(models.Model):
+    """A reading group with an admin and members."""
+
+    name = models.CharField(max_length=256, db_index=True)
+    description = models.TextField(blank=True, default="")
+    admin = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="administered_groups",
+    )
+    members = models.ManyToManyField(
+        settings.AUTH_USER_MODEL,
+        through="ReadingGroupMembership",
+        related_name="reading_groups",
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "groups_reading_group"
+        verbose_name = "Reading Group"
+        verbose_name_plural = "Reading Groups"
+        ordering = ["-created_at"]
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class ReadingGroupMembership(models.Model):
+    class Role(models.TextChoices):
+        ADMIN = "admin", "Admin"
+        MEMBER = "member", "Member"
+
+    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
+    group = models.ForeignKey(ReadingGroup, on_delete=models.CASCADE, related_name="memberships")
+    role = models.CharField(max_length=16, choices=Role.choices, default=Role.MEMBER)
+    joined_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "groups_membership"
+        unique_together = [("user", "group")]
+        verbose_name = "Reading Group Membership"
+        verbose_name_plural = "Reading Group Memberships"
+
+    def __str__(self) -> str:
+        return f"{self.user} in {self.group.name} ({self.role})"
+
+
+class GroupBook(models.Model):
+    """Links an uploaded EBook to a reading group."""
+
+    class Status(models.TextChoices):
+        ACTIVE = "active", "Active"
+        REPLACED = "replaced", "Replaced"
+
+    group = models.ForeignKey(
+        ReadingGroup, on_delete=models.CASCADE, related_name="group_books"
+    )
+    ebook = models.ForeignKey(
+        EBook, on_delete=models.CASCADE, related_name="group_books"
+    )
+    uploaded_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="uploaded_group_books"
+    )
+    title = models.CharField(max_length=512, db_index=True)
+    status = models.CharField(
+        max_length=16, choices=Status.choices, default=Status.ACTIVE, db_index=True
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "groups_group_book"
+        verbose_name = "Group Book"
+        verbose_name_plural = "Group Books"
+        ordering = ["-created_at"]
+        indexes = [models.Index(fields=["group", "status"])]
+
+    def __str__(self) -> str:
+        return f"{self.group.name} — {self.title}"
+
+
+class Section(models.Model):
+    """A section/chunk of a GroupBook for group reading."""
+
+    group_book = models.ForeignKey(
+        GroupBook, on_delete=models.CASCADE, related_name="sections"
+    )
+    title = models.CharField(max_length=512)
+    order = models.PositiveIntegerField(db_index=True)
+    start_chapter_index = models.PositiveIntegerField(default=0)
+    end_chapter_index = models.PositiveIntegerField(default=0)
+    estimated_reading_minutes = models.PositiveIntegerField(default=0)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "groups_section"
+        verbose_name = "Section"
+        verbose_name_plural = "Sections"
+        ordering = ["order"]
+        unique_together = [("group_book", "order")]
+        indexes = [models.Index(fields=["group_book", "order"])]
+
+    def __str__(self) -> str:
+        return f"{self.group_book.title} — Section {self.order}: {self.title}"
+
+
+class ReadingSchedule(models.Model):
+    """Reading schedule mapping sections to weekly meetings."""
+
+    group_book = models.ForeignKey(
+        GroupBook, on_delete=models.CASCADE, related_name="schedules"
+    )
+    meeting_number = models.PositiveIntegerField()
+    week_date = models.DateField()
+    section_ids = models.JSONField(default=list, help_text="Ordered list of Section IDs for this meeting")
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "groups_reading_schedule"
+        verbose_name = "Reading Schedule"
+        verbose_name_plural = "Reading Schedules"
+        ordering = ["meeting_number"]
+        unique_together = [("group_book", "meeting_number")]
+        indexes = [models.Index(fields=["group_book", "meeting_number"])]
+
+    def __str__(self) -> str:
+        return f"{self.group_book.title} — Meeting {self.meeting_number}"
+
+
+class MemberProgress(models.Model):
+    """Tracks a member's progress through sections of a group book."""
+
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="group_progress"
+    )
+    group_book = models.ForeignKey(
+        GroupBook, on_delete=models.CASCADE, related_name="member_progress"
+    )
+    current_section = models.ForeignKey(
+        Section, on_delete=models.SET_NULL, null=True, blank=True, related_name="current_readers"
+    )
+    completed_sections = models.JSONField(
+        default=list, help_text="Ordered list of completed Section IDs"
+    )
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "groups_member_progress"
+        verbose_name = "Member Progress"
+        verbose_name_plural = "Member Progress"
+        unique_together = [("user", "group_book")]
+
+    def __str__(self) -> str:
+        return f"{self.user} — {self.group_book.title}"

backend/apps/groups/serializers.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from rest_framework import serializers
+
+from apps.groups.models import (
+    GroupBook,
+    MemberProgress,
+    ReadingGroup,
+    ReadingGroupMembership,
+    ReadingSchedule,
+    Section,
+)
+from apps.books.serializers import EBookListSerializer
+
+
+class ReadingGroupMembershipSerializer(serializers.ModelSerializer):
+    user_email = serializers.CharField(source="user.email", read_only=True)
+    user_username = serializers.CharField(source="user.username", read_only=True)
+
+    class Meta:
+        model = ReadingGroupMembership
+        fields = [
+            "id", "user", "user_email", "user_username",
+            "role", "joined_at",
+        ]
+        read_only_fields = ["id", "joined_at"]
+
+
+class ReadingGroupListSerializer(serializers.ModelSerializer):
+    member_count = serializers.SerializerMethodField()
+    admin_email = serializers.CharField(source="admin.email", read_only=True)
+
+    class Meta:
+        model = ReadingGroup
+        fields = [
+            "id", "name", "description", "admin", "admin_email",
+            "member_count", "created_at", "updated_at",
+        ]
+
+    def get_member_count(self, obj: ReadingGroup) -> int:
+        return obj.memberships.count()
+
+
+class ReadingGroupDetailSerializer(serializers.ModelSerializer):
+    admin_email = serializers.CharField(source="admin.email", read_only=True)
+    members = ReadingGroupMembershipSerializer(source="memberships", many=True, read_only=True)
+
+    class Meta:
+        model = ReadingGroup
+        fields = [
+            "id", "name", "description", "admin", "admin_email",
+            "members", "created_at", "updated_at",
+        ]
+
+
+class ReadingGroupCreateSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = ReadingGroup
+        fields = ["name", "description"]
+
+
+class AddMemberSerializer(serializers.Serializer):
+    user_id = serializers.IntegerField()
+
+    def validate_user_id(self, value: int) -> int:
+        from django.conf import settings
+        User = settings.AUTH_USER_MODEL
+        if not User.objects.filter(id=value).exists():
+            raise serializers.ValidationError("User not found.")
+        return value
+
+
+class SectionSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Section
+        fields = [
+            "id", "title", "order", "start_chapter_index",
+            "end_chapter_index", "estimated_reading_minutes", "created_at",
+        ]
+        read_only_fields = ["id", "created_at"]
+
+
+class SectionAdjustSerializer(serializers.Serializer):
+    """Payload for manual section adjustments (merge/split)."""
+    operation = serializers.ChoiceField(choices=["merge", "split"])
+    section_ids = serializers.ListField(
+        child=serializers.IntegerField(), min_length=1,
+        help_text="For merge: list of section IDs to merge. For split: [section_id] to split."
+    )
+    split_at = serializers.IntegerField(
+        required=False, default=2, min_value=2,
+        help_text="Number of new sections when splitting"
+    )
+
+
+class ReadingScheduleSerializer(serializers.ModelSerializer):
+    section_details = serializers.SerializerMethodField()
+
+    class Meta:
+        model = ReadingSchedule
+        fields = [
+            "id", "meeting_number", "week_date", "section_ids",
+            "section_details", "created_at",
+        ]
+        read_only_fields = ["id", "created_at"]
+
+    def get_section_details(self, obj: ReadingSchedule) -> list[dict]:
+        sections = Section.objects.filter(
+            id__in=obj.section_ids, group_book=obj.group_book
+        ).order_by("order")
+        return SectionSerializer(sections, many=True).data
+
+
+class MemberProgressSerializer(serializers.ModelSerializer):
+    user_email = serializers.CharField(source="user.email", read_only=True)
+    user_username = serializers.CharField(source="user.username", read_only=True)
+    current_section_title = serializers.SerializerMethodField()
+
+    class Meta:
+        model = MemberProgress
+        fields = [
+            "id", "user", "user_email", "user_username",
+            "current_section", "current_section_title",
+            "completed_sections", "updated_at",
+        ]
+        read_only_fields = ["id", "updated_at"]
+
+    def get_current_section_title(self, obj: MemberProgress) -> str | None:
+        if obj.current_section:
+            return obj.current_section.title
+        return None
+
+
+class GroupBookListSerializer(serializers.ModelSerializer):
+    ebook = EBookListSerializer(read_only=True)
+    uploaded_by_email = serializers.CharField(source="uploaded_by.email", read_only=True)
+    section_count = serializers.SerializerMethodField()
+
+    class Meta:
+        model = GroupBook
+        fields = [
+            "id", "title", "status", "ebook", "uploaded_by",
+            "uploaded_by_email", "section_count", "created_at", "updated_at",
+        ]
+
+    def get_section_count(self, obj: GroupBook) -> int:
+        return obj.sections.count()
+
+
+class GroupBookDetailSerializer(serializers.ModelSerializer):
+    ebook = EBookListSerializer(read_only=True)
+    uploaded_by_email = serializers.CharField(source="uploaded_by.email", read_only=True)
+    sections = SectionSerializer(many=True, read_only=True)
+    schedules = ReadingScheduleSerializer(source="schedules", many=True, read_only=True)
+
+    class Meta:
+        model = GroupBook
+        fields = [
+            "id", "group", "title", "status", "ebook",
+            "uploaded_by", "uploaded_by_email",
+            "sections", "schedules", "created_at", "updated_at",
+        ]
+
+
+class GroupBookCreateSerializer(serializers.Serializer):
+    ebook_id = serializers.IntegerField()
+    title = serializers.CharField(max_length=512, required=False)
+
+    def validate_ebook_id(self, value: int) -> int:
+        from apps.books.models import EBook
+        if not EBook.objects.filter(id=value).exists():
+            raise serializers.ValidationError("EBook not found.")
+        # Check format is EPUB
+        ebook = EBook.objects.get(id=value)
+        if ebook.format != "epub":
+            raise serializers.ValidationError("Only EPUB format is supported for group books.")
+        return value
+
+    def validate(self, data: dict) -> dict:
+        request = self.context.get("request")
+        if request and not data.get("title"):
+            from apps.books.models import EBook
+            ebook = EBook.objects.get(id=data["ebook_id"])
+            data["title"] = ebook.title
+        return data

backend/apps/groups/services/section_splitting.py

@@ -0,0 +1,241 @@
+"""Automatic section detection and meeting recommendation for group books."""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, timedelta
+from typing import Any
+
+from django.db.models import QuerySet
+
+from apps.books.models import BookChapter, EBook
+from apps.groups.models import GroupBook, ReadingSchedule, Section
+
+logger = logging.getLogger(__name__)
+
+WORDS_PER_MINUTE = 250  # Average reading speed
+
+
+def _fetch_chapter_text(ebook: EBook, chapter: BookChapter) -> str:
+    """Extract plain text from a chapter for word counting."""
+    try:
+        from ebooklib import epub
+        from bs4 import BeautifulSoup
+    except ImportError:
+        return ""
+
+    try:
+        book = epub.read_epub(ebook.file.path)
+        href = chapter.href or ""
+        for item in book.get_items():
+            item_name = item.get_name() or ""
+            if href and (item_name.endswith(href) or href.endswith(item_name)):
+                content = item.get_content()
+                soup = BeautifulSoup(content, "html.parser")
+                body = soup.find("body")
+                if body:
+                    return body.get_text(separator=" ", strip=True)
+                return soup.get_text(separator=" ", strip=True)
+        return ""
+    except Exception:
+        logger.exception("Failed to extract text for chapter %s", chapter.id)
+        return ""
+
+
+def _estimate_reading_minutes(text: str) -> int:
+    """Estimate reading time based on word count at WORDS_PER_MINUTE."""
+    word_count = len(text.split())
+    if word_count == 0:
+        return 1
+    return max(1, round(word_count / WORDS_PER_MINUTE))
+
+
+def detect_sections(group_book: GroupBook) -> list[dict[str, Any]]:
+    """Auto-detect sections from a GroupBook's chapters.
+
+    Groups consecutive chapters into logical sections based on TOC structure.
+    Top-level TOC entries become sections; if there are very few (< 3),
+    groups of ~5 chapters become sections instead.
+    """
+    ebook = group_book.ebook
+    chapters = list(
+        BookChapter.objects.filter(ebook=ebook).order_by("index").select_related("ebook")
+    )
+
+    if not chapters:
+        return []
+
+    top_level = [ch for ch in chapters if not ch.children or len(ch.children) == 0]
+    has_children = [ch for ch in chapters if ch.children and len(ch.children) > 0]
+
+    sections: list[dict[str, Any]] = []
+
+    if len(has_children) >= 3:
+        # Use TOC structure: each top-level chapter (with children) is a section
+        for idx, ch in enumerate(has_children):
+            # Find all child chapters belonging to this parent
+            child_indices = _collect_child_indices(chapters, ch, idx)
+            start_idx = ch.index
+            end_idx = child_indices[-1] if child_indices else start_idx
+
+            section_chapters = [c for c in chapters if start_idx <= c.index <= end_idx]
+            total_text = ""
+            for sc in section_chapters:
+                total_text += " " + _fetch_chapter_text(ebook, sc)
+
+            sections.append({
+                "title": ch.title,
+                "order": idx + 1,
+                "start_chapter_index": start_idx,
+                "end_chapter_index": end_idx + 1,
+                "estimated_reading_minutes": _estimate_reading_minutes(total_text),
+            })
+    else:
+        # Group chapters into chunks of ~5
+        chunk_size = max(1, len(top_level) // 6 if len(top_level) > 6 else 5)
+        chunk_size = max(3, min(chunk_size, 10))
+
+        group_start = 0
+        section_order = 1
+        total = len(top_level) or len(chapters)
+        source = top_level or chapters
+
+        while group_start < total:
+            group_end = min(group_start + chunk_size, total)
+            chunk = source[group_start:group_end]
+
+            total_text = ""
+            for ch in chunk:
+                total_text += " " + _fetch_chapter_text(ebook, ch)
+
+            first_title = chunk[0].title if chunk else "Section"
+            last_title = chunk[-1].title if len(chunk) > 1 else ""
+            title = f"{first_title}" if not last_title or first_title == last_title else f"{first_title} — {last_title}"
+
+            sections.append({
+                "title": title,
+                "order": section_order,
+                "start_chapter_index": chunk[0].index,
+                "end_chapter_index": chunk[-1].index + 1,
+                "estimated_reading_minutes": _estimate_reading_minutes(total_text),
+            })
+            group_start = group_end
+            section_order += 1
+
+    return sections
+
+
+def _collect_child_indices(chapters: list[BookChapter], parent: BookChapter, parent_idx: int) -> list[int]:
+    """Collect indices of all chapters that are children of the given parent TOC entry."""
+    indices: list[int] = [parent.index]
+    child_hrefs: set[str] = set()
+    for child in parent.children:
+        if isinstance(child, dict):
+            child_hrefs.add(child.get("href", ""))
+        elif hasattr(child, "href"):
+            child_hrefs.add(getattr(child, "href", ""))
+
+    for ch in chapters:
+        if ch.index == parent.index:
+            continue
+        if ch.href in child_hrefs or any(
+            ch.href.endswith(h) or h.endswith(ch.href) for h in child_hrefs
+        ):
+            indices.append(ch.index)
+
+    # Also include chapters between this parent and the next parent
+    if parent_idx + 1 < len(chapters):
+        next_parent = chapters[parent_idx + 1]
+        for ch in chapters:
+            if parent.index < ch.index < next_parent.index:
+                indices.append(ch.index)
+
+    return sorted(set(indices))
+
+
+def apply_sections(group_book: GroupBook) -> list[Section]:
+    """Detect sections and persist them to the database, replacing existing ones."""
+    Section.objects.filter(group_book=group_book).delete()
+    sections_data = detect_sections(group_book)
+    created: list[Section] = []
+    for data in sections_data:
+        section = Section.objects.create(
+            group_book=group_book,
+            title=data["title"],
+            order=data["order"],
+            start_chapter_index=data["start_chapter_index"],
+            end_chapter_index=data["end_chapter_index"],
+            estimated_reading_minutes=data["estimated_reading_minutes"],
+        )
+        created.append(section)
+    return created
+
+
+def recommend_meetings(group_book: GroupBook, num_meetings: int = 4) -> list[dict[str, Any]]:
+    """Recommend which sections to assign to each weekly meeting.
+
+    Distributes sections across meetings, trying to balance total reading time.
+    Returns a list of meeting assignments ready for schedule creation.
+    """
+    sections = list(
+        Section.objects.filter(group_book=group_book).order_by("order")
+    )
+
+    if not sections:
+        return []
+
+    # Calculate total minutes to distribute
+    total_minutes = sum(s.estimated_reading_minutes for s in sections)
+    target_per_meeting = total_minutes / num_meetings
+
+    meetings: list[dict[str, Any]] = []
+    current_meeting: list[int] = []
+    current_minutes = 0
+
+    for section in sections:
+        if current_meeting and current_minutes + section.estimated_reading_minutes > target_per_meeting * 1.4:
+            # Start new meeting if adding this section would overshoot too much
+            if len(meetings) < num_meetings - 1:
+                meetings.append({
+                    "meeting_number": len(meetings) + 1,
+                    "section_ids": current_meeting,
+                    "total_minutes": current_minutes,
+                })
+                current_meeting = []
+                current_minutes = 0
+
+        current_meeting.append(section.id)
+        current_minutes += section.estimated_reading_minutes
+
+    # Add the last meeting
+    if current_meeting:
+        meetings.append({
+            "meeting_number": len(meetings) + 1,
+            "section_ids": current_meeting,
+            "total_minutes": current_minutes,
+        })
+
+    # If we have fewer than num_meetings, we could split the largest one
+    # For now, just return what we have
+    return meetings
+
+
+def apply_schedule(group_book: GroupBook, num_meetings: int = 4) -> list[ReadingSchedule]:
+    """Generate and persist a reading schedule."""
+    ReadingSchedule.objects.filter(group_book=group_book).delete()
+
+    recommendations = recommend_meetings(group_book, num_meetings)
+    today = date.today()
+
+    created: list[ReadingSchedule] = []
+    for rec in recommendations:
+        week_date = today + timedelta(weeks=rec["meeting_number"] - 1)
+        schedule = ReadingSchedule.objects.create(
+            group_book=group_book,
+            meeting_number=rec["meeting_number"],
+            week_date=week_date,
+            section_ids=rec["section_ids"],
+        )
+        created.append(schedule)
+
+    return created

backend/apps/groups/urls.py

@@ -0,0 +1,43 @@
+from django.urls import include, path
+from rest_framework.routers import DefaultRouter
+
+from apps.groups.views import GroupBookViewSet, ReadingGroupViewSet
+
+# ReadingGroup routes (standard ViewSet)
+router = DefaultRouter()
+router.register(r"", ReadingGroupViewSet, basename="group")
+
+urlpatterns = [
+    path("", include(router.urls)),
+    # Nested GroupBook routes under a group
+    path(
+        "<int:group_pk>/books/",
+        GroupBookViewSet.as_view({"get": "list", "post": "create"}),
+        name="group-book-list",
+    ),
+    path(
+        "<int:group_pk>/books/<int:pk>/",
+        GroupBookViewSet.as_view({"get": "retrieve", "delete": "destroy"}),
+        name="group-book-detail",
+    ),
+    path(
+        "<int:group_pk>/books/<int:pk>/detect-sections/",
+        GroupBookViewSet.as_view({"post": "detect_sections_action"}),
+        name="group-book-detect-sections",
+    ),
+    path(
+        "<int:group_pk>/books/<int:pk>/adjust-sections/",
+        GroupBookViewSet.as_view({"post": "adjust_sections"}),
+        name="group-book-adjust-sections",
+    ),
+    path(
+        "<int:group_pk>/books/<int:pk>/schedule/",
+        GroupBookViewSet.as_view({"get": "schedule", "post": "schedule", "delete": "schedule"}),
+        name="group-book-schedule",
+    ),
+    path(
+        "<int:group_pk>/books/<int:pk>/progress/",
+        GroupBookViewSet.as_view({"get": "progress", "patch": "progress"}),
+        name="group-book-progress",
+    ),
+]

backend/apps/groups/views.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from django.db.models import QuerySet
+from django.shortcuts import get_object_or_404
+from rest_framework import permissions, status, viewsets
+from rest_framework.decorators import action
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from apps.books.models import EBook
+from apps.groups.models import (
+    GroupBook,
+    MemberProgress,
+    ReadingGroup,
+    ReadingGroupMembership,
+    ReadingSchedule,
+    Section,
+)
+from apps.groups.serializers import (
+    AddMemberSerializer,
+    GroupBookCreateSerializer,
+    GroupBookDetailSerializer,
+    GroupBookListSerializer,
+    MemberProgressSerializer,
+    ReadingGroupCreateSerializer,
+    ReadingGroupDetailSerializer,
+    ReadingGroupListSerializer,
+    ReadingScheduleSerializer,
+    SectionAdjustSerializer,
+    SectionSerializer,
+)
+from apps.groups.services.section_splitting import (
+    apply_schedule,
+    apply_sections,
+    detect_sections,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class IsGroupAdmin(permissions.BasePermission):
+    """Only the group admin can modify group resources."""
+
+    def has_permission(self, request: Request, view: object) -> bool:
+        if not request.user.is_authenticated:
+            return False
+        if view.action in ("list", "retrieve"):
+            return True
+        group_id = view.kwargs.get("pk") or view.kwargs.get("group_pk")
+        if group_id:
+            return ReadingGroup.objects.filter(id=group_id, admin=request.user).exists()
+        return True
+
+    def has_object_permission(self, request: Request, view: object, obj: ReadingGroup) -> bool:
+        if request.method in permissions.SAFE_METHODS:
+            return True
+        return obj.admin == request.user
+
+
+class IsGroupMember(permissions.BasePermission):
+    """Only group members (including admin) can view group content."""
+
+    def has_permission(self, request: Request, view: object) -> bool:
+        if not request.user.is_authenticated:
+            return False
+        group_id = view.kwargs.get("pk") or view.kwargs.get("group_pk")
+        if group_id:
+            return ReadingGroupMembership.objects.filter(
+                group_id=group_id, user=request.user
+            ).exists()
+        return True
+
+
+class ReadingGroupViewSet(viewsets.ModelViewSet):
+    permission_classes = [permissions.IsAuthenticated, IsGroupAdmin]
+    queryset = ReadingGroup.objects.prefetch_related("memberships__user")
+
+    def get_serializer_class(self):
+        if self.action == "create":
+            return ReadingGroupCreateSerializer
+        if self.action == "retrieve":
+            return ReadingGroupDetailSerializer
+        return ReadingGroupListSerializer
+
+    def get_queryset(self) -> QuerySet[ReadingGroup]:
+        user = self.request.user
+        return ReadingGroup.objects.filter(
+            memberships__user=user
+        ).prefetch_related("memberships__user").distinct()
+
+    def perform_create(self, serializer: ReadingGroupCreateSerializer) -> ReadingGroup:
+        group = serializer.save(admin=self.request.user)
+        ReadingGroupMembership.objects.create(
+            user=self.request.user, group=group, role=ReadingGroupMembership.Role.ADMIN
+        )
+        return group
+
+    @action(detail=True, methods=["post"], permission_classes=[IsGroupAdmin])
+    def add_member(self, request: Request, pk: int | None = None) -> Response:
+        group = self.get_object()
+        member_serializer = AddMemberSerializer(data=request.data)
+        member_serializer.is_valid(raise_exception=True)
+
+        user_id = member_serializer.validated_data["user_id"]
+        from django.conf import settings
+        User = settings.AUTH_USER_MODEL
+        new_member = get_object_or_404(User, id=user_id)
+
+        if ReadingGroupMembership.objects.filter(group=group, user=new_member).exists():
+            return Response(
+                {"detail": "User is already a member of this group."},
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        membership = ReadingGroupMembership.objects.create(
+            user=new_member, group=group, role=ReadingGroupMembership.Role.MEMBER
+        )
+        from apps.groups.serializers import ReadingGroupMembershipSerializer
+        return Response(
+            ReadingGroupMembershipSerializer(membership).data,
+            status=status.HTTP_201_CREATED,
+        )
+
+    @action(detail=True, methods=["post"], permission_classes=[IsGroupAdmin])
+    def remove_member(self, request: Request, pk: int | None = None) -> Response:
+        group = self.get_object()
+        member_serializer = AddMemberSerializer(data=request.data)
+        member_serializer.is_valid(raise_exception=True)
+
+        user_id = member_serializer.validated_data["user_id"]
+        if user_id == group.admin_id:
+            return Response(
+                {"detail": "Cannot remove the group admin."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        deleted, _ = ReadingGroupMembership.objects.filter(
+            group=group, user_id=user_id
+        ).delete()
+        if not deleted:
+            return Response(
+                {"detail": "User is not a member of this group."},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        return Response(status=status.HTTP_204_NO_CONTENT)
+
+
+class GroupBookViewSet(viewsets.ModelViewSet):
+    permission_classes = [permissions.IsAuthenticated, IsGroupAdmin]
+
+    def get_serializer_class(self):
+        if self.action == "create":
+            return GroupBookCreateSerializer
+        if self.action == "retrieve":
+            return GroupBookDetailSerializer
+        return GroupBookListSerializer
+
+    def get_queryset(self) -> QuerySet[GroupBook]:
+        group_id = self.kwargs.get("group_pk")
+        return GroupBook.objects.filter(
+            group_id=group_id
+        ).select_related("ebook", "ebook__user", "uploaded_by").prefetch_related(
+            "sections", "schedules"
+        )
+
+    def perform_create(self, serializer: GroupBookCreateSerializer) -> GroupBook:
+        group = get_object_or_404(ReadingGroup, id=self.kwargs["group_pk"])
+        ebook = get_object_or_404(EBook, id=serializer.validated_data["ebook_id"])
+        title = serializer.validated_data.get("title") or ebook.title
+
+        # Mark existing active books as replaced
+        GroupBook.objects.filter(group=group, status=GroupBook.Status.ACTIVE).update(
+            status=GroupBook.Status.REPLACED
+        )
+
+        group_book = GroupBook.objects.create(
+            group=group,
+            ebook=ebook,
+            uploaded_by=self.request.user,
+            title=title,
+            status=GroupBook.Status.ACTIVE,
+        )
+
+        # Auto-detect sections
+        try:
+            apply_sections(group_book)
+        except Exception:
+            logger.exception("Auto-section detection failed for group_book %s", group_book.id)
+
+        # Auto-generate schedule
+        try:
+            apply_schedule(group_book)
+        except Exception:
+            logger.exception("Schedule generation failed for group_book %s", group_book.id)
+
+        return group_book
+
+    @action(detail=True, methods=["post"], url_path="detect-sections")
+    def detect_sections_action(self, request: Request, group_pk: int | None = None, pk: int | None = None) -> Response:
+        group_book = self.get_object()
+        try:
+            sections = apply_sections(group_book)
+        except Exception as exc:
+            logger.exception("Section detection failed for group_book %s", group_book.id)
+            return Response({"error": str(exc)}, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+        return Response(SectionSerializer(sections, many=True).data)
+
+    @action(detail=True, methods=["post"], url_path="adjust-sections")
+    def adjust_sections(self, request: Request, group_pk: int | None = None, pk: int | None = None) -> Response:
+        group_book = self.get_object()
+        adjust_serializer = SectionAdjustSerializer(data=request.data)
+        adjust_serializer.is_valid(raise_exception=True)
+
+        operation = adjust_serializer.validated_data["operation"]
+        section_ids: list[int] = adjust_serializer.validated_data["section_ids"]
+
+        if operation == "merge":
+            if len(section_ids) < 2:
+                return Response(
+                    {"error": "At least 2 section IDs required for merge."},
+                    status=status.HTTP_400_BAD_REQUEST,
+                )
+            sections = list(
+                Section.objects.filter(id__in=section_ids, group_book=group_book).order_by("order")
+            )
+            if len(sections) < 2:
+                return Response(
+                    {"error": "Not enough valid sections found."},
+                    status=status.HTTP_400_BAD_REQUEST,
+                )
+            merged_title = " — ".join(s.title for s in sections)
+            merged_minutes = sum(s.estimated_reading_minutes for s in sections)
+            merged_start = sections[0].start_chapter_index
+            merged_end = sections[-1].end_chapter_index
+            merged_order = sections[0].order
+
+            # Delete old sections
+            Section.objects.filter(id__in=section_ids, group_book=group_book).delete()
+
+            # Create merged section
+            merged = Section.objects.create(
+                group_book=group_book,
+                title=merged_title,
+                order=merged_order,
+                start_chapter_index=merged_start,
+                end_chapter_index=merged_end,
+                estimated_reading_minutes=merged_minutes,
+            )
+            # Reorder remaining sections
+            _renumber_sections(group_book)
+            return Response(SectionSerializer(merged).data)
+
+        if operation == "split":
+            if len(section_ids) != 1:
+                return Response(
+                    {"error": "Exactly 1 section ID required for split."},
+                    status=status.HTTP_400_BAD_REQUEST,
+                )
+            split_at = adjust_serializer.validated_data.get("split_at", 2)
+            section = get_object_or_404(Section, id=section_ids[0], group_book=group_book)
+            chapters = section.end_chapter_index - section.start_chapter_index
+            if chapters < split_at:
+                return Response(
+                    {"error": f"Section only has {chapters} chapters, cannot split into {split_at}."},
+                    status=status.HTTP_400_BAD_REQUEST,
+                )
+
+            # Delete original
+            orig_order = section.order
+            orig_title = section.title
+            section.delete()
+
+            # Create split sections
+            chunk_size = max(1, chapters // split_at)
+            new_sections: list[Section] = []
+            for i in range(split_at):
+                start_idx = section.start_chapter_index + i * chunk_size
+                end_idx = start_idx + chunk_size if i < split_at - 1 else section.end_chapter_index
+                minutes_each = max(1, section.estimated_reading_minutes // split_at)
+                new_sec = Section.objects.create(
+                    group_book=group_book,
+                    title=f"{orig_title} (Part {i + 1})",
+                    order=orig_order + i,
+                    start_chapter_index=start_idx,
+                    end_chapter_index=end_idx,
+                    estimated_reading_minutes=minutes_each,
+                )
+                new_sections.append(new_sec)
+
+            _renumber_sections(group_book)
+            return Response(SectionSerializer(new_sections, many=True).data)
+
+        return Response({"error": "Invalid operation."}, status=status.HTTP_400_BAD_REQUEST)
+
+    @action(detail=True, methods=["get", "post", "delete"], url_path="schedule")
+    def schedule(self, request: Request, group_pk: int | None = None, pk: int | None = None) -> Response:
+        group_book = self.get_object()
+
+        if request.method == "GET":
+            schedules = ReadingSchedule.objects.filter(group_book=group_book).order_by("meeting_number")
+            return Response(ReadingScheduleSerializer(schedules, many=True).data)
+
+        if request.method == "POST":
+            ReadingSchedule.objects.filter(group_book=group_book).delete()
+            num_meetings = int(request.data.get("num_meetings", 4))
+            try:
+                schedules = apply_schedule(group_book, num_meetings=num_meetings)
+            except Exception as exc:
+                logger.exception("Schedule generation failed for group_book %s", group_book.id)
+                return Response({"error": str(exc)}, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+            return Response(
+                ReadingScheduleSerializer(schedules, many=True).data,
+                status=status.HTTP_201_CREATED,
+            )
+
+        if request.method == "DELETE":
+            ReadingSchedule.objects.filter(group_book=group_book).delete()
+            return Response(status=status.HTTP_204_NO_CONTENT)
+
+    @action(detail=True, methods=["get", "patch"], url_path="progress")
+    def progress(self, request: Request, group_pk: int | None = None, pk: int | None = None) -> Response:
+        group_book = self.get_object()
+
+        if request.method == "GET":
+            progress_records = MemberProgress.objects.filter(
+                group_book=group_book
+            ).select_related("user", "current_section")
+            return Response(MemberProgressSerializer(progress_records, many=True).data)
+
+        # PATCH: update own progress
+        progress_obj, _created = MemberProgress.objects.get_or_create(
+            user=request.user, group_book=group_book,
+        )
+        serializer = MemberProgressSerializer(progress_obj, data=request.data, partial=True)
+        serializer.is_valid(raise_exception=True)
+        serializer.save()
+        return Response(serializer.data)
+
+
+def _renumber_sections(group_book: GroupBook) -> None:
+    """Re-number sections sequentially by their current order."""
+    sections = list(Section.objects.filter(group_book=group_book).order_by("order"))
+    for idx, section in enumerate(sections):
+        if section.order != idx + 1:
+            section.order = idx + 1
+            section.save(update_fields=["order"])

backend/config/django.py

@@ -39,6 +39,7 @@ INSTALLED_APPS = [
     # Local apps
     "apps.users",
     "apps.books",
+    "apps.groups",
     "apps.annotations",
     "apps.reader",
 ]

backend/config/urls.py

@@ -6,6 +6,7 @@ urlpatterns = [
     path("admin/", admin.site.urls),
     path("api/auth/", include("apps.users.urls")),
     path("api/books/", include("apps.books.urls")),
+    path("api/groups/", include("apps.groups.urls")),
     path("api/annotations/", include("apps.annotations.urls")),
     path("api/reader/", include("apps.reader.urls")),
 ]

docs/mobile/010-mobile-reader.md

@@ -0,0 +1,150 @@
+# 010 — Mobile EPUB Reader
+
+**Status:** Implemented
+**Created:** 2026-06-04
+
+## Objective
+
+Mirror the web reading experience (`frontend/src/pages/ReadingPage.tsx` and
+`frontend/src/components/reader/*`) inside the Expo app so users can open their
+uploaded library, read EPUBs with persisted progress and typography settings,
+and manage bookmarks/highlights — reusing the same Django REST API as the web
+client.
+
+The web EPUB renderer (`react-reader` / epub.js) is DOM-only, so mobile renders
+EPUBs with `@epubjs-react-native/core`, which runs epub.js inside a
+`react-native-webview`. This keeps behavior (CFI locations, themes, font
+controls, TOC, annotations) close to web while staying inside the managed Expo
+workflow.
+
+## Scope
+
+### Mirrored from web
+
+- EPUB rendering with swipe pagination (`flow: "paginated"`).
+- Resume position and debounced progress save (CFI + percentage).
+- Table of contents drawer with jump-to-chapter.
+- Reading settings: theme presets (light/sepia/paper/dark), font family, font
+  size, line spacing — persisted to `/api/reader/settings/`.
+- Bookmarks: bookmark the current page, list/jump/delete, and create highlights
+  from a text selection. Highlights are re-applied on open (best-effort).
+
+### Deferred (not in this pass)
+
+- PDF reading. PDF books show a placeholder pointing to the web reader.
+- Brightness and orientation-lock controls.
+- Per-highlight color picker (highlights use a single default color).
+- App-wide internationalization (web uses `react-i18n-lite`).
+
+## Architecture
+
+```
+LibraryScreen (EBook list)
+        |  navigate("BookDetail", { ebookId })
+        v
+BookDetailScreen ----------------> ReaderScreen ({ ebookId })
+                                        |
+                       GET /api/books/ebooks/:id/  (format guard)
+                                        |
+                       epub? --------------------- pdf? -> placeholder
+                          |
+                EpubReaderView (ReaderProvider)
+                          |
+   expo-file-system downloadAsync(file/, Bearer token) -> file:// uri
+                          |
+   <Reader src=file:// fileSystem=useFileSystem flow="paginated" />
+                          |
+   onLocationChange -> debounce 800ms -> PATCH progress/
+   onSelected       -> POST bookmarks/ (+ highlight annotation)
+   useReader().toc  -> goToLocation(href)
+   settings change  -> changeTheme / changeFontSize / changeFontFamily
+                       + PATCH /api/reader/settings/ (debounced)
+```
+
+The ebook file is downloaded to the app cache with an `Authorization` header
+(the `/file/` endpoint is JWT-protected) and the local `file://` URI is handed
+to the renderer — mirroring how the web client downloads a blob rather than
+using a public/signed URL.
+
+## Mobile changes
+
+| File | Role |
+|------|------|
+| `mobile/src/api/client.ts` | Adds `apiClient`, `saveTokens`, `loadTokens`, `getApiBaseUrl` |
+| `mobile/src/api/ebooks.ts` | `/api/books/ebooks/` list/detail/toc + `getFileUrl(id)` |
+| `mobile/src/api/reader.ts` | Reader settings + per-book progress (mirrors web `api/reader.ts`) |
+| `mobile/src/api/annotations.ts` | Bookmarks CRUD against `/api/annotations/bookmarks/` |
+| `mobile/src/types/reader.ts` | `ReadingSettings`, `ReadingProgress` (full reader shapes) |
+| `mobile/src/types/index.ts` | `AppStackParamList`, `Bookmark`, `CreateMarkerPayload` |
+| `mobile/src/hooks/useReadingSettings.ts` | Loads + debounced-saves reader settings |
+| `mobile/src/utils/epubTheme.ts` | Font stacks, theme palettes, `buildEpubTheme()` |
+| `mobile/src/navigation/AppStack.tsx` | Native stack: Tabs / BookDetail / Reader |
+| `mobile/src/screens/LibraryScreen.tsx` | Lists user EBooks (`ebooksApi.list`) |
+| `mobile/src/screens/BookDetailScreen.tsx` | Metadata + start/resume button |
+| `mobile/src/screens/ReaderScreen.tsx` | Format guard: EPUB view vs PDF placeholder |
+| `mobile/src/components/reader/EpubReaderView.tsx` | Reader, progress, bookmarks, settings wiring |
+| `mobile/src/components/reader/ReaderToolbar.tsx` | Title, chapter, progress bar, action buttons |
+| `mobile/src/components/reader/TocModal.tsx` | Table of contents sheet |
+| `mobile/src/components/reader/ReadingSettingsModal.tsx` | Theme/font/size/spacing controls |
+| `mobile/src/components/reader/BookmarksModal.tsx` | Bookmarks & highlights list |
+| `mobile/App.tsx` | Wraps the tree in `GestureHandlerRootView` |
+
+Removed unused scaffolding: `mobile/src/navigation/AppNavigator.tsx`,
+`mobile/src/navigation/MainTabs.tsx`.
+
+## API contracts (consumed)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/books/ebooks/` | User library list |
+| GET | `/api/books/ebooks/:id/` | EBook detail (format, progress, cover) |
+| GET | `/api/books/ebooks/:id/file/` | Stream EPUB bytes (JWT, owner) |
+| GET/PATCH | `/api/books/ebooks/:id/progress/` | Reading progress (`current_position`, `last_page`, `epub_location`) |
+| GET/PATCH | `/api/reader/settings/` | Reader typography/theme settings |
+| GET/POST/DELETE | `/api/annotations/bookmarks/` | Bookmarks & highlights (`ebook`, `epub_cfi`, `chapter_index`, ...) |
+
+## Settings mapping (web -> mobile)
+
+| Reader setting | Web (epub.js) | Mobile (`@epubjs-react-native/core`) |
+|----------------|---------------|--------------------------------------|
+| `theme` / colors | `themes.register/select` | `changeTheme(buildEpubTheme())` + `defaultTheme` |
+| `font_size` | `themes.fontSize` | `changeFontSize("Npx")` |
+| `font_family` | body font-family | `changeFontFamily(stack)` |
+| `line_height` | body line-height | `buildEpubTheme()` CSS rule |
+| `margin_width` | gap-based padding | not applied (deferred) |
+| `brightness` / `orientation_lock` | applied on web | deferred |
+
+## Dependencies added
+
+- `@epubjs-react-native/core@1.4.7`
+- `@epubjs-react-native/expo-file-system@1.1.4`
+- `react-native-webview@13.12.5`
+
+(`react-native-gesture-handler`, `react-native-reanimated`, and
+`expo-file-system` were already present.)
+
+## Configuration
+
+| Env var | Purpose |
+|---------|---------|
+| `EXPO_PUBLIC_API_URL` | Backend base URL (e.g. `http://10.0.2.2:8000` on Android emulator, LAN IP on a device) |
+
+## Compatibility notes
+
+- The Expo file-system adapter (`@epubjs-react-native/expo-file-system`) depends
+  only on `expo-file-system`, so the reader runs in Expo Go. (The library's
+  bare adapter pulls native `@dr.pogodin/react-native-fs`; that path is not
+  used here.)
+- React 19 / Expo SDK 52 may surface peer-dependency warnings for the
+  `@epubjs-react-native/*` packages.
+
+## Verification
+
+- [ ] Log in; Library lists the user's uploaded EBooks with covers/progress.
+- [ ] Open an EPUB; it renders and paginates by swipe.
+- [ ] Reopen a book; it resumes at the last position.
+- [ ] Change theme/font/size/spacing; the page updates and persists across reopen.
+- [ ] Open the TOC and jump to a chapter.
+- [ ] Bookmark the current page; it appears in the bookmarks list and can be re-opened/deleted.
+- [ ] Select text to create a highlight; it persists and re-renders on reopen.
+- [ ] Open a PDF book; the placeholder is shown instead of a crash.

frontend/src/App.tsx

@@ -12,6 +12,9 @@ const AddBookPage = lazy(() => import("./pages/AddBook").then((m) => ({ default:
 const SettingsPage = lazy(() => import("./pages/Settings").then((m) => ({ default: m.SettingsPage })));
 const BookmarksNotesPage = lazy(() => import("./components/annotations/BookmarksNotesPage").then((m) => ({ default: m.BookmarksNotesPage })));
 const ReadingPage = lazy(() => import("./pages/ReadingPage").then((m) => ({ default: m.default })));
+const GroupsPage = lazy(() => import("./pages/GroupsPage").then((m) => ({ default: m.GroupsPage })));
+const GroupDetailPage = lazy(() => import("./pages/GroupDetailPage").then((m) => ({ default: m.GroupDetailPage })));
+const GroupBookPage = lazy(() => import("./pages/GroupBookPage").then((m) => ({ default: m.GroupBookPage })));
 
 const AuthPage = lazy(() => import("./pages/AuthPage"));
 
@@ -44,6 +47,9 @@ function AppRoutes() {
         <Route path="/reader/:id" element={<ProtectedRoute><ReaderRedirect /></ProtectedRoute>} />
         <Route path="/add" element={<ProtectedRoute><AddBookPage /></ProtectedRoute>} />
         <Route path="/settings" element={<ProtectedRoute><SettingsPage /></ProtectedRoute>} />
+        <Route path="/groups" element={<ProtectedRoute><GroupsPage /></ProtectedRoute>} />
+        <Route path="/groups/:groupId" element={<ProtectedRoute><GroupDetailPage /></ProtectedRoute>} />
+        <Route path="/groups/:groupId/books/:bookId" element={<ProtectedRoute><GroupBookPage /></ProtectedRoute>} />
         <Route path="/bookmarks-notes/:bookId?" element={<ProtectedRoute><BookmarksNotesPage /></ProtectedRoute>} />
         <Route path="*" element={<Navigate to="/" replace />} />
       </Routes>

frontend/src/api/groups.ts

@@ -0,0 +1,151 @@
+import api from "./client";
+import type {
+  AddMemberPayload,
+  AdjustSectionsPayload,
+  CreateGroupBookPayload,
+  CreateGroupPayload,
+  GroupBook,
+  GroupBookDetail,
+  MemberProgress,
+  ReadingGroup,
+  ReadingGroupDetail,
+  ReadingSchedule,
+  Section,
+} from "../types/group";
+
+export const groupsApi = {
+  // ---- Reading Groups ----
+
+  async listGroups(): Promise<ReadingGroup[]> {
+    const { data } = await api.get<{ count: number; results: ReadingGroup[] } | ReadingGroup[]>(
+      "/groups/"
+    );
+    if (Array.isArray(data)) return data;
+    return data.results ?? [];
+  },
+
+  async getGroup(id: number): Promise<ReadingGroupDetail> {
+    const { data } = await api.get<ReadingGroupDetail>(`/groups/${id}/`);
+    return data;
+  },
+
+  async createGroup(payload: CreateGroupPayload): Promise<ReadingGroup> {
+    const { data } = await api.post<ReadingGroup>("/groups/", payload);
+    return data;
+  },
+
+  async deleteGroup(id: number): Promise<void> {
+    await api.delete(`/groups/${id}/`);
+  },
+
+  async addMember(groupId: number, payload: AddMemberPayload): Promise<void> {
+    await api.post(`/groups/${groupId}/add_member/`, payload);
+  },
+
+  async removeMember(groupId: number, payload: AddMemberPayload): Promise<void> {
+    await api.post(`/groups/${groupId}/remove_member/`, payload);
+  },
+
+  // ---- Group Books ----
+
+  async listGroupBooks(groupId: number): Promise<GroupBook[]> {
+    const { data } = await api.get<GroupBook[]>(`/groups/${groupId}/books/`);
+    return Array.isArray(data) ? data : (data as { results: GroupBook[] }).results ?? [];
+  },
+
+  async getGroupBook(groupId: number, bookId: number): Promise<GroupBookDetail> {
+    const { data } = await api.get<GroupBookDetail>(`/groups/${groupId}/books/${bookId}/`);
+    return data;
+  },
+
+  async createGroupBook(
+    groupId: number,
+    payload: CreateGroupBookPayload
+  ): Promise<GroupBookDetail> {
+    const { data } = await api.post<GroupBookDetail>(
+      `/groups/${groupId}/books/`,
+      payload
+    );
+    return data;
+  },
+
+  async deleteGroupBook(groupId: number, bookId: number): Promise<void> {
+    await api.delete(`/groups/${groupId}/books/${bookId}/`);
+  },
+
+  // ---- Sections ----
+
+  async detectSections(
+    groupId: number,
+    bookId: number
+  ): Promise<Section[]> {
+    const { data } = await api.post<Section[]>(
+      `/groups/${groupId}/books/${bookId}/detect-sections/`
+    );
+    return data;
+  },
+
+  async adjustSections(
+    groupId: number,
+    bookId: number,
+    payload: AdjustSectionsPayload
+  ): Promise<Section | Section[]> {
+    const { data } = await api.post<Section | Section[]>(
+      `/groups/${groupId}/books/${bookId}/adjust-sections/`,
+      payload
+    );
+    return data;
+  },
+
+  // ---- Schedule ----
+
+  async getSchedule(
+    groupId: number,
+    bookId: number
+  ): Promise<ReadingSchedule[]> {
+    const { data } = await api.get<ReadingSchedule[]>(
+      `/groups/${groupId}/books/${bookId}/schedule/`
+    );
+    return data;
+  },
+
+  async generateSchedule(
+    groupId: number,
+    bookId: number,
+    numMeetings: number = 4
+  ): Promise<ReadingSchedule[]> {
+    const { data } = await api.post<ReadingSchedule[]>(
+      `/groups/${groupId}/books/${bookId}/schedule/`,
+      { num_meetings: numMeetings }
+    );
+    return data;
+  },
+
+  async deleteSchedule(groupId: number, bookId: number): Promise<void> {
+    await api.delete(`/groups/${groupId}/books/${bookId}/schedule/`);
+  },
+
+  // ---- Progress ----
+
+  async getProgress(
+    groupId: number,
+    bookId: number
+  ): Promise<MemberProgress[]> {
+    const { data } = await api.get<MemberProgress[]>(
+      `/groups/${groupId}/books/${bookId}/progress/`
+    );
+    return data;
+  },
+
+  async updateProgress(
+    groupId: number,
+    bookId: number,
+    payload: { current_section?: number; completed_sections?: number[] }
+  ): Promise<MemberProgress> {
+    const { data } = await api.patch<MemberProgress>(
+      `/groups/${groupId}/books/${bookId}/progress/`,
+      payload
+    );
+    return data;
+  },
+};

frontend/src/locales/en-US.ts

@@ -245,6 +245,54 @@ const enUS = {
     home: "Home",
     bookmarksNotes: "Bookmarks & Notes",
   },
+  groups: {
+    title: "Reading Groups",
+    createGroup: "Create Group",
+    create: "Create",
+    cancel: "Cancel",
+    groupName: "Group Name",
+    groupNamePlaceholder: "Enter group name",
+    description: "Description",
+    descriptionPlaceholder: "What is this group about?",
+    optional: "Optional",
+    noGroups: "No groups yet",
+    noGroupsHint: "Create a reading group to start reading together!",
+    members: "Members",
+    admin: "Admin",
+    addMember: "Add Member",
+    memberIdPlaceholder: "Enter user ID",
+    add: "Add",
+    remove: "Remove",
+    books: "Group Books",
+    uploadEpub: "Upload EPUB",
+    selectEbook: "Select an EPUB to share with the group",
+    noEpubBooks: "No EPUB files uploaded yet",
+    uploadFirst: "Upload an EPUB first",
+    confirmUpload: "Confirm Upload",
+    noBooks: "No books in this group yet",
+    sections: "Sections",
+    schedule: "Schedule",
+    progress: "Progress",
+    detectSections: "Auto-Detect Sections",
+    mergeSections: "Merge Sections",
+    selectSectionsHint: "Click sections to select for merging",
+    merge: "Merge",
+    clear: "Clear",
+    split: "Split",
+    splitInto: "Split into",
+    parts: "parts",
+    splitBtn: "Split",
+    noSections: "No sections detected yet",
+    noSectionsHint: 'Click "Auto-Detect Sections" to parse the EPUB chapters into reading sections.',
+    readingSchedule: "Reading Schedule",
+    generateSchedule: "Generate Schedule",
+    noSchedule: "No schedule generated yet",
+    noScheduleHint: "Detect sections first, then generate a reading schedule for your group.",
+    meeting: "Meeting",
+    memberProgress: "Member Progress",
+    noProgress: "No progress data yet",
+    noProgressHint: "Members will show progress once they start reading.",
+  },
 } as const;
 
 export default enUS;

frontend/src/locales/es-ES.ts

@@ -247,6 +247,54 @@ const esES: Locale = {
     home: "Inicio",
     bookmarksNotes: "Marcadores y notas",
   },
+  groups: {
+    title: "Grupos de Lectura",
+    createGroup: "Crear Grupo",
+    create: "Crear",
+    cancel: "Cancelar",
+    groupName: "Nombre del Grupo",
+    groupNamePlaceholder: "Ingresa el nombre del grupo",
+    description: "Descripción",
+    descriptionPlaceholder: "¿De qué trata este grupo?",
+    optional: "Opcional",
+    noGroups: "Aún no hay grupos",
+    noGroupsHint: "¡Crea un grupo de lectura para leer juntos!",
+    members: "Miembros",
+    admin: "Admin",
+    addMember: "Agregar Miembro",
+    memberIdPlaceholder: "Ingresa ID de usuario",
+    add: "Agregar",
+    remove: "Eliminar",
+    books: "Libros del Grupo",
+    uploadEpub: "Subir EPUB",
+    selectEbook: "Selecciona un EPUB para compartir con el grupo",
+    noEpubBooks: "No hay archivos EPUB subidos aún",
+    uploadFirst: "Sube un EPUB primero",
+    confirmUpload: "Confirmar Subida",
+    noBooks: "No hay libros en este grupo aún",
+    sections: "Secciones",
+    schedule: "Calendario",
+    progress: "Progreso",
+    detectSections: "Auto-Detectar Secciones",
+    mergeSections: "Fusionar Secciones",
+    selectSectionsHint: "Haz clic en las secciones para seleccionar y fusionar",
+    merge: "Fusionar",
+    clear: "Limpiar",
+    split: "Dividir",
+    splitInto: "Dividir en",
+    parts: "partes",
+    splitBtn: "Dividir",
+    noSections: "No se detectaron secciones",
+    noSectionsHint: 'Haz clic en "Auto-Detectar Secciones" para analizar los capítulos del EPUB.',
+    readingSchedule: "Calendario de Lectura",
+    generateSchedule: "Generar Calendario",
+    noSchedule: "No hay calendario generado",
+    noScheduleHint: "Detecta secciones primero, luego genera un calendario de lectura para tu grupo.",
+    meeting: "Reunión",
+    memberProgress: "Progreso de Miembros",
+    noProgress: "Sin datos de progreso",
+    noProgressHint: "Los miembros mostrarán progreso cuando comiencen a leer.",
+  },
 };
 
 export default esES;

frontend/src/pages/GroupBookPage.tsx

@@ -0,0 +1,426 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+import { useTranslation } from "react-i18n-lite";
+import { groupsApi } from "../api/groups";
+import { getApiErrorMessage } from "../api/errors";
+import type {
+  GroupBookDetail,
+  ReadingSchedule,
+  Section,
+  MemberProgress,
+} from "../types/group";
+
+export function GroupBookPage() {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const { groupId, bookId } = useParams<{ groupId: string; bookId: string }>();
+
+  const [book, setBook] = useState<GroupBookDetail | null>(null);
+  const [sections, setSections] = useState<Section[]>([]);
+  const [schedules, setSchedules] = useState<ReadingSchedule[]>([]);
+  const [progress, setProgress] = useState<MemberProgress[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [tab, setTab] = useState<"sections" | "schedule" | "progress">("sections");
+
+  // Merge state
+  const [selectedForMerge, setSelectedForMerge] = useState<number[]>([]);
+  const [splitSectionId, setSplitSectionId] = useState<number | null>(null);
+  const [splitAt, setSplitAt] = useState(2);
+
+  const gId = Number(groupId);
+  const bId = Number(bookId);
+
+  const loadData = useCallback(async () => {
+    if (!gId || !bId) return;
+    setLoading(true);
+    try {
+      const [bookData, schedData, progData] = await Promise.all([
+        groupsApi.getGroupBook(gId, bId),
+        groupsApi.getSchedule(gId, bId).catch(() => [] as ReadingSchedule[]),
+        groupsApi.getProgress(gId, bId).catch(() => [] as MemberProgress[]),
+      ]);
+      setBook(bookData);
+      setSections(bookData.sections ?? []);
+      setSchedules(schedData);
+      setProgress(progData);
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to load book"));
+    } finally {
+      setLoading(false);
+    }
+  }, [gId, bId]);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  const handleDetectSections = async () => {
+    if (!gId || !bId) return;
+    try {
+      const newSections = await groupsApi.detectSections(gId, bId);
+      setSections(newSections);
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to detect sections"));
+    }
+  };
+
+  const handleMerge = async () => {
+    if (selectedForMerge.length < 2 || !gId || !bId) return;
+    try {
+      await groupsApi.adjustSections(gId, bId, {
+        operation: "merge",
+        section_ids: selectedForMerge,
+      });
+      setSelectedForMerge([]);
+      await loadData();
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to merge sections"));
+    }
+  };
+
+  const handleSplit = async () => {
+    if (!splitSectionId || !gId || !bId) return;
+    try {
+      await groupsApi.adjustSections(gId, bId, {
+        operation: "split",
+        section_ids: [splitSectionId],
+        split_at: splitAt,
+      });
+      setSplitSectionId(null);
+      await loadData();
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to split section"));
+    }
+  };
+
+  const handleGenerateSchedule = async () => {
+    if (!gId || !bId) return;
+    try {
+      const newSched = await groupsApi.generateSchedule(gId, bId, 4);
+      setSchedules(newSched);
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to generate schedule"));
+    }
+  };
+
+  const toggleMergeSelect = (id: number) => {
+    setSelectedForMerge((prev) =>
+      prev.includes(id) ? prev.filter((s) => s !== id) : [...prev, id]
+    );
+  };
+
+  const formatMinutes = (mins: number): string => {
+    if (mins < 60) return `${mins}m`;
+    const h = Math.floor(mins / 60);
+    const m = mins % 60;
+    return m > 0 ? `${h}h ${m}m` : `${h}h`;
+  };
+
+  if (loading) {
+    return (
+      <div style={{ maxWidth: 800, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
+        <p style={{ textAlign: "center", color: "#888", padding: 40 }}>{t("common.loading")}</p>
+      </div>
+    );
+  }
+
+  if (!book) {
+    return (
+      <div style={{ maxWidth: 800, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
+        <p style={{ textAlign: "center", color: "#e74c3c", padding: 40 }}>Book not found</p>
+        <button onClick={() => navigate(`/groups/${groupId}`)} style={{ display: "block", margin: "0 auto" }}>← Back</button>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ maxWidth: 800, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
+      {/* Header */}
+      <header style={{ display: "flex", justifyContent: "space-between", alignItems: "center", padding: "16px 0", borderBottom: "1px solid #eee", marginBottom: 20 }}>
+        <div>
+          <h1 style={{ fontSize: 24, fontWeight: 700, color: "#1a1a2e", margin: 0 }}>{book.title}</h1>
+          <p style={{ margin: 4, fontSize: 13, color: "#888" }}>
+            {book.ebook.author && `by ${book.ebook.author} · `}
+            {book.ebook.page_count} chapters · {book.ebook.format.toUpperCase()}
+          </p>
+        </div>
+        <button onClick={() => navigate(`/groups/${groupId}`)} style={{ padding: "8px 16px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 14 }}>
+          ← {t("common.back")}
+        </button>
+      </header>
+
+      {error && (
+        <div style={{ background: "#fde8e8", padding: 12, borderRadius: 6, color: "#e74c3c", fontSize: 14, marginBottom: 16 }}>
+          {error}
+          <button onClick={() => setError(null)} style={{ marginLeft: 12, background: "none", border: "none", cursor: "pointer", fontWeight: 600 }}>✕</button>
+        </div>
+      )}
+
+      {/* Tabs */}
+      <div style={{ display: "flex", gap: 4, marginBottom: 20, background: "#eee", borderRadius: 8, padding: 4 }}>
+        {(["sections", "schedule", "progress"] as const).map((t) => (
+          <button
+            key={t}
+            onClick={() => setTab(t)}
+            style={{
+              flex: 1, padding: "10px 16px", borderRadius: 6, border: "none",
+              fontSize: 14, fontWeight: 600, cursor: "pointer",
+              background: tab === t ? "#fff" : "transparent",
+              color: tab === t ? "#1a1a2e" : "#888",
+              boxShadow: tab === t ? "0 1px 4px rgba(0,0,0,0.1)" : "none",
+            }}
+          >
+            {t === "sections" ? t("groups.sections") : t === "schedule" ? t("groups.schedule") : t("groups.progress")}
+          </button>
+        ))}
+      </div>
+
+      {/* Sections Tab */}
+      {tab === "sections" && (
+        <section>
+          <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 16 }}>
+            <h2 style={{ fontSize: 18, fontWeight: 600, color: "#1a1a2e", margin: 0 }}>
+              {sections.length} {t("groups.sections")}
+            </h2>
+            <div style={{ display: "flex", gap: 8 }}>
+              <button
+                onClick={handleDetectSections}
+                style={{ padding: "8px 16px", borderRadius: 6, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 13, fontWeight: 600, cursor: "pointer" }}
+              >
+                {t("groups.detectSections")}
+              </button>
+            </div>
+          </div>
+
+          {/* Merge controls */}
+          <div style={{ background: "#fff", padding: 16, borderRadius: 10, marginBottom: 12, boxShadow: "0 1px 4px rgba(0,0,0,0.06)" }}>
+            <div style={{ display: "flex", alignItems: "center", gap: 10, flexWrap: "wrap" }}>
+              <span style={{ fontSize: 14, fontWeight: 600, color: "#555" }}>{t("groups.mergeSections")}:</span>
+              <span style={{ fontSize: 13, color: "#888" }}>
+                {selectedForMerge.length === 0
+                  ? t("groups.selectSectionsHint")
+                  : `${selectedForMerge.length} selected`}
+              </span>
+              {selectedForMerge.length >= 2 && (
+                <button
+                  onClick={handleMerge}
+                  style={{ padding: "6px 14px", borderRadius: 6, border: "none", background: "#27ae60", color: "#fff", fontSize: 13, fontWeight: 600, cursor: "pointer" }}
+                >
+                  {t("groups.merge")}
+                </button>
+              )}
+              {selectedForMerge.length > 0 && (
+                <button
+                  onClick={() => setSelectedForMerge([])}
+                  style={{ padding: "6px 12px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", fontSize: 13, cursor: "pointer" }}
+                >
+                  {t("groups.clear")}
+                </button>
+              )}
+            </div>
+          </div>
+
+          {sections.length === 0 ? (
+            <div style={{ textAlign: "center", padding: 40, color: "#888" }}>
+              <p style={{ fontSize: 16 }}>{t("groups.noSections")}</p>
+              <p style={{ fontSize: 14 }}>{t("groups.noSectionsHint")}</p>
+            </div>
+          ) : (
+            <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
+              {sections.map((section) => (
+                <div
+                  key={section.id}
+                  style={{
+                    background: selectedForMerge.includes(section.id) ? "#e8f0fe" : "#fff",
+                    border: selectedForMerge.includes(section.id) ? "2px solid #1a1a2e" : "1px solid #eee",
+                    padding: 16, borderRadius: 10, cursor: "pointer",
+                    boxShadow: "0 1px 4px rgba(0,0,0,0.06)",
+                    transition: "all 0.15s",
+                  }}
+                  onClick={() => toggleMergeSelect(section.id)}
+                >
+                  <div style={{ display: "flex", justifyContent: "space-between", alignItems: "flex-start" }}>
+                    <div style={{ flex: 1 }}>
+                      <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+                        <span style={{
+                          background: "#1a1a2e", color: "#fff", borderRadius: 20,
+                          width: 26, height: 26, display: "flex", alignItems: "center", justifyContent: "center",
+                          fontSize: 13, fontWeight: 700, flexShrink: 0,
+                        }}>
+                          {section.order}
+                        </span>
+                        <h3 style={{ margin: 0, fontSize: 15, fontWeight: 600, color: "#1a1a2e" }}>{section.title}</h3>
+                      </div>
+                      <p style={{ margin: "6px 0 0 34px", fontSize: 13, color: "#888" }}>
+                        Ch. {section.start_chapter_index}–{section.end_chapter_index - 1} · ~{formatMinutes(section.estimated_reading_minutes)} reading time
+                      </p>
+                    </div>
+                    <button
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        setSplitSectionId(splitSectionId === section.id ? null : section.id);
+                      }}
+                      style={{
+                        padding: "4px 10px", borderRadius: 4, border: "1px solid #ddd",
+                        background: splitSectionId === section.id ? "#1a1a2e" : "#fff",
+                        color: splitSectionId === section.id ? "#fff" : "#666",
+                        fontSize: 12, cursor: "pointer", flexShrink: 0,
+                      }}
+                    >
+                      {t("groups.split")}
+                    </button>
+                  </div>
+                  {splitSectionId === section.id && (
+                    <div
+                      style={{ marginTop: 10, padding: 10, background: "#f8f9fa", borderRadius: 6, display: "flex", alignItems: "center", gap: 8 }}
+                      onClick={(e) => e.stopPropagation()}
+                    >
+                      <span style={{ fontSize: 13 }}>{t("groups.splitInto")}</span>
+                      <input
+                        type="number"
+                        value={splitAt}
+                        min={2}
+                        max={10}
+                        onChange={(e) => setSplitAt(Number(e.target.value))}
+                        style={{ width: 50, padding: "4px 8px", borderRadius: 4, border: "1px solid #ddd", fontSize: 13, textAlign: "center" }}
+                      />
+                      <span style={{ fontSize: 13 }}>{t("groups.parts")}</span>
+                      <button
+                        onClick={handleSplit}
+                        style={{ padding: "4px 12px", borderRadius: 4, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 12, cursor: "pointer" }}
+                      >
+                        {t("groups.splitBtn")}
+                      </button>
+                    </div>
+                  )}
+                </div>
+              ))}
+            </div>
+          )}
+        </section>
+      )}
+
+      {/* Schedule Tab */}
+      {tab === "schedule" && (
+        <section>
+          <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 16 }}>
+            <h2 style={{ fontSize: 18, fontWeight: 600, color: "#1a1a2e", margin: 0 }}>
+              {t("groups.readingSchedule")}
+            </h2>
+            <button
+              onClick={handleGenerateSchedule}
+              style={{ padding: "8px 16px", borderRadius: 6, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 13, fontWeight: 600, cursor: "pointer" }}
+            >
+              {t("groups.generateSchedule")}
+            </button>
+          </div>
+
+          {schedules.length === 0 ? (
+            <div style={{ textAlign: "center", padding: 40, color: "#888" }}>
+              <p style={{ fontSize: 16 }}>{t("groups.noSchedule")}</p>
+              <p style={{ fontSize: 14 }}>{t("groups.noScheduleHint")}</p>
+            </div>
+          ) : (
+            <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+              {schedules.map((s) => (
+                <div
+                  key={s.id}
+                  style={{ background: "#fff", padding: 20, borderRadius: 12, boxShadow: "0 2px 8px rgba(0,0,0,0.06)" }}
+                >
+                  <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 12 }}>
+                    <div>
+                      <h3 style={{ margin: 0, fontSize: 17, fontWeight: 700, color: "#1a1a2e" }}>
+                        {t("groups.meeting")} {s.meeting_number}
+                      </h3>
+                      <p style={{ margin: "4px 0 0", fontSize: 13, color: "#888" }}>
+                        Week of {new Date(s.week_date).toLocaleDateString("en-US", { month: "long", day: "numeric", year: "numeric" })}
+                      </p>
+                    </div>
+                    <span style={{
+                      background: "#f0f0f0", padding: "6px 12px", borderRadius: 20,
+                      fontSize: 13, fontWeight: 600, color: "#555",
+                    }}>
+                      {s.section_details.reduce((sum, sec) => sum + sec.estimated_reading_minutes, 0) > 0
+                        ? `~${formatMinutes(s.section_details.reduce((sum, sec) => sum + sec.estimated_reading_minutes, 0))}`
+                        : ""}
+                    </span>
+                  </div>
+                  <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+                    {s.section_details.map((sec) => (
+                      <div
+                        key={sec.id}
+                        style={{
+                          display: "flex", alignItems: "center", gap: 10, padding: "8px 12px",
+                          background: "#f8f9fa", borderRadius: 6, fontSize: 14,
+                        }}
+                      >
+                        <span style={{
+                          background: "#1a1a2e", color: "#fff", borderRadius: 12,
+                          width: 22, height: 22, display: "flex", alignItems: "center", justifyContent: "center",
+                          fontSize: 11, fontWeight: 700, flexShrink: 0,
+                        }}>
+                          {sec.order}
+                        </span>
+                        <span style={{ flex: 1 }}>{sec.title}</span>
+                        <span style={{ fontSize: 12, color: "#999" }}>{formatMinutes(sec.estimated_reading_minutes)}</span>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+        </section>
+      )}
+
+      {/* Progress Tab */}
+      {tab === "progress" && (
+        <section>
+          <h2 style={{ fontSize: 18, fontWeight: 600, color: "#1a1a2e", margin: "0 0 16px" }}>
+            {t("groups.memberProgress")}
+          </h2>
+          {progress.length === 0 ? (
+            <div style={{ textAlign: "center", padding: 40, color: "#888" }}>
+              <p style={{ fontSize: 16 }}>{t("groups.noProgress")}</p>
+              <p style={{ fontSize: 14 }}>{t("groups.noProgressHint")}</p>
+            </div>
+          ) : (
+            <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
+              {progress.map((p) => {
+                const totalSections = sections.length;
+                const completed = p.completed_sections.length;
+                const pct = totalSections > 0 ? Math.round((completed / totalSections) * 100) : 0;
+                return (
+                  <div
+                    key={p.id}
+                    style={{ background: "#fff", padding: 16, borderRadius: 10, boxShadow: "0 1px 4px rgba(0,0,0,0.06)" }}
+                  >
+                    <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 8 }}>
+                      <span style={{ fontSize: 15, fontWeight: 600 }}>{p.user_email}</span>
+                      <span style={{ fontSize: 13, color: "#888" }}>{completed}/{totalSections} · {pct}%</span>
+                    </div>
+                    <div style={{ height: 6, background: "#eee", borderRadius: 3, overflow: "hidden" }}>
+                      <div
+                        style={{
+                          height: "100%", borderRadius: 3,
+                          background: "linear-gradient(90deg, #27ae60, #2ecc71)",
+                          width: `${pct}%`, transition: "width 0.3s",
+                        }}
+                      />
+                    </div>
+                    {p.current_section_title && (
+                      <p style={{ margin: "8px 0 0", fontSize: 13, color: "#888" }}>
+                        Currently: {p.current_section_title}
+                      </p>
+                    )}
+                  </div>
+                );
+              })}
+            </div>
+          )}
+        </section>
+      )}
+    </div>
+  );
+}

frontend/src/pages/GroupDetailPage.tsx

@@ -0,0 +1,300 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+import { useTranslation } from "react-i18n-lite";
+import { groupsApi } from "../api/groups";
+import { booksApi } from "../api/books";
+import { getApiErrorMessage } from "../api/errors";
+import type { ReadingGroupDetail, GroupBook, GroupBookDetail } from "../types/group";
+import type { EBookListItem } from "../types/book";
+
+export function GroupDetailPage() {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const { groupId } = useParams<{ groupId: string }>();
+  const [group, setGroup] = useState<ReadingGroupDetail | null>(null);
+  const [books, setBooks] = useState<GroupBook[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Upload state
+  const [showUpload, setShowUpload] = useState(false);
+  const [ebooks, setEbooks] = useState<EBookListItem[]>([]);
+  const [selectedEbookId, setSelectedEbookId] = useState<number | null>(null);
+  const [uploading, setUploading] = useState(false);
+
+  // Add member state
+  const [showAddMember, setShowAddMember] = useState(false);
+  const [memberEmail, setMemberEmail] = useState("");
+  const [adding, setAdding] = useState(false);
+
+  const id = Number(groupId);
+
+  const loadData = useCallback(async () => {
+    if (!id) return;
+    setLoading(true);
+    try {
+      const [groupData, bookData] = await Promise.all([
+        groupsApi.getGroup(id),
+        groupsApi.listGroupBooks(id),
+      ]);
+      setGroup(groupData);
+      setBooks(bookData);
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to load group"));
+    } finally {
+      setLoading(false);
+    }
+  }, [id]);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  const handleUploadClick = async () => {
+    setShowUpload(true);
+    try {
+      const ebookList = await booksApi.getEBooks();
+      setEbooks(ebookList.filter((e) => e.format === "epub"));
+    } catch {
+      // Ebook list fetch failed silently
+    }
+  };
+
+  const handleUpload = async () => {
+    if (!selectedEbookId || !id) return;
+    setUploading(true);
+    try {
+      const created = await groupsApi.createGroupBook(id, { ebook_id: selectedEbookId });
+      setShowUpload(false);
+      setSelectedEbookId(null);
+      await loadData();
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to upload book to group"));
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  const handleAddMember = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!memberEmail.trim() || !id) return;
+    setAdding(true);
+    try {
+      // Note: In a real implementation, we'd look up user by email.
+      // For now this requires user_id. Email lookup would be an enhancement.
+      await groupsApi.addMember(id, { user_id: Number(memberEmail) });
+      setShowAddMember(false);
+      setMemberEmail("");
+      await loadData();
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to add member. Please use a valid user ID."));
+    } finally {
+      setAdding(false);
+    }
+  };
+
+  const handleRemoveMember = async (userId: number) => {
+    if (!id) return;
+    try {
+      await groupsApi.removeMember(id, { user_id: userId });
+      await loadData();
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to remove member"));
+    }
+  };
+
+  if (loading) {
+    return (
+      <div style={{ maxWidth: 700, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
+        <p style={{ textAlign: "center", color: "#888", padding: 40 }}>{t("common.loading")}</p>
+      </div>
+    );
+  }
+
+  if (!group) {
+    return (
+      <div style={{ maxWidth: 700, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
+        <p style={{ textAlign: "center", color: "#e74c3c", padding: 40 }}>Group not found</p>
+        <button onClick={() => navigate("/groups")} style={{ display: "block", margin: "0 auto" }}>← Back to Groups</button>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ maxWidth: 700, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
+      <header style={{ display: "flex", justifyContent: "space-between", alignItems: "center", padding: "16px 0", borderBottom: "1px solid #eee", marginBottom: 20 }}>
+        <div>
+          <h1 style={{ fontSize: 24, fontWeight: 700, color: "#1a1a2e", margin: 0 }}>{group.name}</h1>
+          {group.description && <p style={{ margin: "4px 0 0", fontSize: 14, color: "#666" }}>{group.description}</p>}
+        </div>
+        <button onClick={() => navigate("/groups")} style={{ padding: "8px 16px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 14 }}>
+          ← {t("common.back")}
+        </button>
+      </header>
+
+      {error && (
+        <div style={{ background: "#fde8e8", padding: 12, borderRadius: 6, color: "#e74c3c", fontSize: 14, marginBottom: 16 }}>
+          {error}
+          <button onClick={() => setError(null)} style={{ marginLeft: 12, background: "none", border: "none", cursor: "pointer", fontWeight: 600 }}>✕</button>
+        </div>
+      )}
+
+      {/* Members Section */}
+      <section style={{ background: "#fff", padding: 20, borderRadius: 12, marginBottom: 20, boxShadow: "0 2px 8px rgba(0,0,0,0.06)" }}>
+        <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 12 }}>
+          <h2 style={{ fontSize: 18, fontWeight: 600, color: "#1a1a2e", margin: 0 }}>{t("groups.members")} ({group.members.length})</h2>
+          <button
+            onClick={() => setShowAddMember(!showAddMember)}
+            style={{ padding: "6px 14px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 13 }}
+          >
+            {showAddMember ? t("groups.cancel") : `+ ${t("groups.addMember")}`}
+          </button>
+        </div>
+        {showAddMember && (
+          <form onSubmit={handleAddMember} style={{ display: "flex", gap: 8, marginBottom: 12 }}>
+            <input
+              type="text"
+              value={memberEmail}
+              onChange={(e) => setMemberEmail(e.target.value)}
+              placeholder={t("groups.memberIdPlaceholder")}
+              style={{ flex: 1, padding: "8px 12px", borderRadius: 6, border: "1px solid #ddd", fontSize: 14, outline: "none" }}
+            />
+            <button
+              type="submit"
+              disabled={adding}
+              style={{ padding: "8px 16px", borderRadius: 6, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 14, cursor: "pointer", opacity: adding ? 0.6 : 1 }}
+            >
+              {t("groups.add")}
+            </button>
+          </form>
+        )}
+        <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+          {group.members.map((m) => (
+            <div key={m.id} style={{ display: "flex", justifyContent: "space-between", alignItems: "center", padding: "8px 0", borderBottom: "1px solid #f0f0f0" }}>
+              <div>
+                <span style={{ fontSize: 14, fontWeight: 500 }}>{m.user_email}</span>
+                <span style={{ marginLeft: 8, fontSize: 12, color: m.role === "admin" ? "#e67e22" : "#999", background: m.role === "admin" ? "#fef3e2" : "#f0f0f0", padding: "2px 8px", borderRadius: 4 }}>
+                  {m.role}
+                </span>
+              </div>
+              {m.role !== "admin" && (
+                <button
+                  onClick={() => handleRemoveMember(m.user)}
+                  style={{ background: "none", border: "none", color: "#e74c3c", cursor: "pointer", fontSize: 13 }}
+                >
+                  {t("groups.remove")}
+                </button>
+              )}
+            </div>
+          ))}
+        </div>
+      </section>
+
+      {/* Books Section */}
+      <section style={{ background: "#fff", padding: 20, borderRadius: 12, boxShadow: "0 2px 8px rgba(0,0,0,0.06)" }}>
+        <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 12 }}>
+          <h2 style={{ fontSize: 18, fontWeight: 600, color: "#1a1a2e", margin: 0 }}>{t("groups.books")} ({books.length})</h2>
+          <button
+            onClick={handleUploadClick}
+            style={{ padding: "8px 18px", borderRadius: 8, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 14, fontWeight: 600, cursor: "pointer" }}
+          >
+            {t("groups.uploadEpub")}
+          </button>
+        </div>
+
+        {showUpload && (
+          <div style={{ background: "#f8f9fa", padding: 16, borderRadius: 8, marginBottom: 16 }}>
+            <h3 style={{ fontSize: 15, fontWeight: 600, margin: "0 0 12px" }}>{t("groups.selectEbook")}</h3>
+            {ebooks.length === 0 ? (
+              <div style={{ textAlign: "center", padding: 20, color: "#888" }}>
+                <p>{t("groups.noEpubBooks")}</p>
+                <button onClick={() => navigate("/add")} style={{ marginTop: 8, padding: "8px 16px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 13 }}>
+                  {t("groups.uploadFirst")}
+                </button>
+              </div>
+            ) : (
+              <div>
+                <div style={{ display: "flex", flexDirection: "column", gap: 8, marginBottom: 12, maxHeight: 200, overflowY: "auto" }}>
+                  {ebooks.map((eb) => (
+                    <label
+                      key={eb.id}
+                      style={{
+                        display: "flex", alignItems: "center", gap: 10, padding: "10px 12px",
+                        borderRadius: 8, cursor: "pointer", fontSize: 14,
+                        background: selectedEbookId === eb.id ? "#e8f0fe" : "#fff",
+                        border: selectedEbookId === eb.id ? "2px solid #1a1a2e" : "1px solid #eee",
+                      }}
+                    >
+                      <input
+                        type="radio"
+                        name="ebook"
+                        value={eb.id}
+                        checked={selectedEbookId === eb.id}
+                        onChange={() => setSelectedEbookId(eb.id)}
+                        style={{ accentColor: "#1a1a2e" }}
+                      />
+                      <div>
+                        <strong>{eb.title}</strong>
+                        {eb.author && <span style={{ color: "#888", marginLeft: 8 }}>by {eb.author}</span>}
+                        <span style={{ marginLeft: 8, fontSize: 12, color: "#aaa" }}>({eb.filename})</span>
+                      </div>
+                    </label>
+                  ))}
+                </div>
+                <div style={{ display: "flex", gap: 8 }}>
+                  <button
+                    onClick={handleUpload}
+                    disabled={!selectedEbookId || uploading}
+                    style={{ padding: "10px 20px", borderRadius: 8, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 14, fontWeight: 600, cursor: uploading ? "default" : "pointer", opacity: uploading ? 0.6 : 1 }}
+                  >
+                    {uploading ? t("common.loading") : t("groups.confirmUpload")}
+                  </button>
+                  <button
+                    onClick={() => setShowUpload(false)}
+                    style={{ padding: "10px 20px", borderRadius: 8, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 14 }}
+                  >
+                    {t("groups.cancel")}
+                  </button>
+                </div>
+              </div>
+            )}
+          </div>
+        )}
+
+        {books.length === 0 ? (
+          <p style={{ textAlign: "center", color: "#888", padding: 30 }}>{t("groups.noBooks")}</p>
+        ) : (
+          <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
+            {books.map((book) => (
+              <div
+                key={book.id}
+                onClick={() => navigate(`/groups/${groupId}/books/${book.id}`)}
+                style={{
+                  display: "flex", justifyContent: "space-between", alignItems: "center",
+                  padding: 16, borderRadius: 10, cursor: "pointer", transition: "background 0.2s",
+                  background: book.status === "active" ? "#f0faf0" : "#fafafa",
+                  border: book.status === "active" ? "2px solid #27ae60" : "1px solid #eee",
+                }}
+                onMouseEnter={(e) => (e.currentTarget.style.background = book.status === "active" ? "#e8f5e9" : "#f5f5f5")}
+                onMouseLeave={(e) => (e.currentTarget.style.background = book.status === "active" ? "#f0faf0" : "#fafafa")}
+              >
+                <div>
+                  <h3 style={{ margin: 0, fontSize: 16, fontWeight: 600, color: "#1a1a2e" }}>
+                    {book.title}
+                    {book.status === "active" && (
+                      <span style={{ marginLeft: 8, fontSize: 11, color: "#27ae60", background: "#e8f5e9", padding: "2px 8px", borderRadius: 4 }}>Active</span>
+                    )}
+                  </h3>
+                  <p style={{ margin: "4px 0 0", fontSize: 13, color: "#888" }}>
+                    {book.section_count} sections · {book.ebook.page_count} chapters · uploaded by {book.uploaded_by_email}
+                  </p>
+                </div>
+                <span style={{ fontSize: 20, color: "#ccc" }}>→</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}

frontend/src/pages/GroupsPage.tsx

@@ -0,0 +1,162 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { useTranslation } from "react-i18n-lite";
+import { groupsApi } from "../api/groups";
+import { getApiErrorMessage } from "../api/errors";
+import type { ReadingGroup } from "../types/group";
+
+export function GroupsPage() {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const [groups, setGroups] = useState<ReadingGroup[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [showCreate, setShowCreate] = useState(false);
+  const [newName, setNewName] = useState("");
+  const [newDesc, setNewDesc] = useState("");
+  const [creating, setCreating] = useState(false);
+
+  const loadGroups = useCallback(async () => {
+    setLoading(true);
+    try {
+      const data = await groupsApi.listGroups();
+      setGroups(data);
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to load groups"));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    loadGroups();
+  }, [loadGroups]);
+
+  const handleCreate = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!newName.trim()) return;
+    setCreating(true);
+    try {
+      await groupsApi.createGroup({ name: newName.trim(), description: newDesc.trim() });
+      setShowCreate(false);
+      setNewName("");
+      setNewDesc("");
+      await loadGroups();
+    } catch (err) {
+      setError(getApiErrorMessage(err, "Failed to create group"));
+    } finally {
+      setCreating(false);
+    }
+  };
+
+  return (
+    <div style={{ maxWidth: 700, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
+      <header style={{ display: "flex", justifyContent: "space-between", alignItems: "center", padding: "16px 0", borderBottom: "1px solid #eee", marginBottom: 20 }}>
+        <h1 style={{ fontSize: 24, fontWeight: 700, color: "#1a1a2e", margin: 0 }}>{t("groups.title")}</h1>
+        <button
+          type="button"
+          onClick={() => navigate("/")}
+          style={{ padding: "8px 16px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 14 }}
+        >
+          ← {t("common.back")}
+        </button>
+      </header>
+
+      {error && (
+        <div style={{ background: "#fde8e8", padding: 12, borderRadius: 6, color: "#e74c3c", fontSize: 14, marginBottom: 16 }}>
+          {error}
+          <button onClick={() => setError(null)} style={{ marginLeft: 12, background: "none", border: "none", cursor: "pointer", fontWeight: 600 }}>✕</button>
+        </div>
+      )}
+
+      <div style={{ marginBottom: 20 }}>
+        <button
+          type="button"
+          onClick={() => setShowCreate(!showCreate)}
+          style={{
+            padding: "12px 24px", borderRadius: 8, border: "none",
+            background: "#1a1a2e", color: "#fff", fontSize: 15, fontWeight: 600, cursor: "pointer",
+          }}
+        >
+          {showCreate ? t("groups.cancel") : t("groups.createGroup")}
+        </button>
+      </div>
+
+      {showCreate && (
+        <form onSubmit={handleCreate} style={{
+          background: "#fff", padding: 20, borderRadius: 12, marginBottom: 24,
+          boxShadow: "0 2px 8px rgba(0,0,0,0.06)", display: "flex", flexDirection: "column", gap: 14,
+        }}>
+          <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+            <label style={{ fontSize: 14, fontWeight: 600, color: "#555" }}>{t("groups.groupName")}</label>
+            <input
+              type="text"
+              value={newName}
+              onChange={(e) => setNewName(e.target.value)}
+              placeholder={t("groups.groupNamePlaceholder")}
+              style={{ padding: "10px 12px", borderRadius: 6, border: "1px solid #ddd", fontSize: 16, outline: "none" }}
+              required
+            />
+          </div>
+          <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+            <label style={{ fontSize: 14, fontWeight: 600, color: "#555" }}>{t("groups.description")} ({t("common.optional")})</label>
+            <textarea
+              value={newDesc}
+              onChange={(e) => setNewDesc(e.target.value)}
+              placeholder={t("groups.descriptionPlaceholder")}
+              rows={3}
+              style={{ padding: "10px 12px", borderRadius: 6, border: "1px solid #ddd", fontSize: 15, outline: "none", resize: "vertical" }}
+            />
+          </div>
+          <button
+            type="submit"
+            disabled={creating || !newName.trim()}
+            style={{
+              padding: "10px 20px", borderRadius: 8, border: "none",
+              background: "#1a1a2e", color: "#fff", fontSize: 15, fontWeight: 600,
+              cursor: creating ? "default" : "pointer", opacity: creating ? 0.6 : 1, alignSelf: "flex-start",
+            }}
+          >
+            {creating ? t("common.loading") : t("groups.create")}
+          </button>
+        </form>
+      )}
+
+      {loading ? (
+        <p style={{ textAlign: "center", color: "#888", padding: 40 }}>{t("common.loading")}</p>
+      ) : groups.length === 0 ? (
+        <div style={{ textAlign: "center", padding: 40, color: "#888" }}>
+          <p style={{ fontSize: 16, marginBottom: 8 }}>{t("groups.noGroups")}</p>
+          <p style={{ fontSize: 14 }}>{t("groups.noGroupsHint")}</p>
+        </div>
+      ) : (
+        <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+          {groups.map((group) => (
+            <div
+              key={group.id}
+              onClick={() => navigate(`/groups/${group.id}`)}
+              style={{
+                background: "#fff", padding: 20, borderRadius: 12, cursor: "pointer",
+                boxShadow: "0 2px 8px rgba(0,0,0,0.06)", transition: "box-shadow 0.2s",
+                display: "flex", justifyContent: "space-between", alignItems: "center",
+              }}
+              onMouseEnter={(e) => (e.currentTarget.style.boxShadow = "0 4px 16px rgba(0,0,0,0.1)")}
+              onMouseLeave={(e) => (e.currentTarget.style.boxShadow = "0 2px 8px rgba(0,0,0,0.06)")}
+            >
+              <div>
+                <h3 style={{ margin: 0, fontSize: 18, fontWeight: 600, color: "#1a1a2e" }}>{group.name}</h3>
+                {group.description && (
+                  <p style={{ margin: "6px 0 0", fontSize: 14, color: "#666" }}>{group.description}</p>
+                )}
+                <p style={{ margin: "8px 0 0", fontSize: 13, color: "#999" }}>
+                  {group.member_count} {t("groups.members")} · {t("groups.admin")}: {group.admin_email}
+                </p>
+              </div>
+              <span style={{ fontSize: 20, color: "#ccc" }}>→</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/types/group.ts

@@ -0,0 +1,109 @@
+/** Types for reading groups, group books, sections, and schedules */
+
+export interface ReadingGroup {
+  id: number;
+  name: string;
+  description: string;
+  admin: number;
+  admin_email: string;
+  member_count: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ReadingGroupDetail {
+  id: number;
+  name: string;
+  description: string;
+  admin: number;
+  admin_email: string;
+  members: GroupMembership[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface GroupMembership {
+  id: number;
+  user: number;
+  user_email: string;
+  user_username: string;
+  role: "admin" | "member";
+  joined_at: string;
+}
+
+export interface GroupBook {
+  id: number;
+  title: string;
+  status: "active" | "replaced";
+  ebook: {
+    id: number;
+    title: string;
+    author: string;
+    filename: string;
+    format: string;
+    page_count: number;
+    file_size: number;
+    cover_image: string | null;
+    created_at: string;
+  };
+  uploaded_by: number;
+  uploaded_by_email: string;
+  section_count: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface Section {
+  id: number;
+  title: string;
+  order: number;
+  start_chapter_index: number;
+  end_chapter_index: number;
+  estimated_reading_minutes: number;
+  created_at: string;
+}
+
+export interface GroupBookDetail extends GroupBook {
+  sections: Section[];
+  schedules: ReadingSchedule[];
+}
+
+export interface ReadingSchedule {
+  id: number;
+  meeting_number: number;
+  week_date: string;
+  section_ids: number[];
+  section_details: Section[];
+  created_at: string;
+}
+
+export interface MemberProgress {
+  id: number;
+  user: number;
+  user_email: string;
+  user_username: string;
+  current_section: number | null;
+  current_section_title: string | null;
+  completed_sections: number[];
+  updated_at: string;
+}
+
+export interface CreateGroupPayload {
+  name: string;
+  description?: string;
+}
+
+export interface AddMemberPayload {
+  user_id: number;
+}
+
+export interface CreateGroupBookPayload {
+  ebook_id: number;
+  title?: string;
+}
+
+export interface AdjustSectionsPayload {
+  operation: "merge" | "split";
+  section_ids: number[];
+  split_at?: number;
+}

mobile/.env.example

@@ -0,0 +1,10 @@
+# Mobile (Expo) environment (example – never commit real secrets)
+# Base URL of the Django backend. Must be reachable from the device/emulator.
+#   - Android emulator: http://10.0.2.2:8000
+#   - iOS simulator:    http://localhost:8000
+#   - Physical device:  http://<your-lan-ip>:8000
+EXPO_PUBLIC_API_URL=http://10.0.2.2:8000
+
+# EAS Build: set per profile in mobile/eas.json or via:
+#   eas secret:create --name EXPO_PUBLIC_API_URL --value https://your-api.example.com
+# Run all eas commands from mobile/ (not repo root).

mobile/App.tsx

@@ -1,4 +1,8 @@
 import React from "react";
+// Peer dependencies for @epubjs-react-native/core and gesture-handler.
+import "react-native-webview";
+import "react-native-reanimated";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { NavigationContainer } from "@react-navigation/native";
 import { StatusBar } from "expo-status-bar";
 import { AuthProvider } from "./src/context/AuthContext";
@@ -6,11 +10,13 @@ import { RootNavigator } from "./src/navigation/RootNavigator";
 
 export default function App() {
   return (
-    <AuthProvider>
+    <GestureHandlerRootView style={{ flex: 1 }}>
-      <NavigationContainer>
+      <AuthProvider>
-        <StatusBar style="auto" />
+        <NavigationContainer>
-        <RootNavigator />
+          <StatusBar style="auto" />
-      </NavigationContainer>
+          <RootNavigator />
-    </AuthProvider>
+        </NavigationContainer>
+      </AuthProvider>
+    </GestureHandlerRootView>
   );
-}
+}

mobile/app.json

@@ -21,7 +21,6 @@
       "package": "com.cloudreader.app"
     },
     "plugins": [
-      "expo-document-picker",
       "expo-file-system"
     ]
   }

mobile/eas.json

@@ -0,0 +1,42 @@
+{
+  "cli": {
+    "version": ">= 13.0.0",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "base": {
+      "node": "20.18.0",
+      "env": {
+        "EXPO_PUBLIC_API_URL": "https://api.example.com"
+      }
+    },
+    "development": {
+      "extends": "base",
+      "developmentClient": true,
+      "distribution": "internal",
+      "ios": {
+        "simulator": true
+      },
+      "android": {
+        "buildType": "apk"
+      },
+      "env": {
+        "EXPO_PUBLIC_API_URL": "http://10.0.2.2:8000"
+      }
+    },
+    "preview": {
+      "extends": "base",
+      "distribution": "internal",
+      "android": {
+        "buildType": "apk"
+      }
+    },
+    "production": {
+      "extends": "base",
+      "autoIncrement": true
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}

mobile/metro.config.js

@@ -0,0 +1,25 @@
+const { getDefaultConfig } = require("expo/metro-config");
+const path = require("path");
+
+const projectRoot = __dirname;
+const monorepoRoot = path.resolve(projectRoot, "..");
+
+/**
+ * Expo SDK 52+ configures Metro for Yarn/npm/pnpm workspaces automatically
+ * when using expo/metro-config. This file keeps an explicit monorepo root so
+ * @cloud-reader/shared (packages/shared) resolves reliably in dev and on EAS.
+ *
+ * If you previously added manual watchFolders/nodeModulesPaths and things
+ * work, prefer this minimal config. After changes: npx expo start --clear
+ *
+ * @see https://docs.expo.dev/guides/monorepos/
+ */
+const config = getDefaultConfig(projectRoot);
+
+config.watchFolders = [monorepoRoot];
+config.resolver.nodeModulesPaths = [
+  path.resolve(projectRoot, "node_modules"),
+  path.resolve(monorepoRoot, "node_modules"),
+];
+
+module.exports = config;

mobile/package.json

@@ -8,7 +8,11 @@
     "android": "expo start --android",
     "ios": "expo start --ios",
     "web": "expo start --web",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "eas:init": "eas init",
+    "eas:build:dev": "eas build --profile development --platform all",
+    "eas:build:preview": "eas build --profile preview --platform all",
+    "eas:build:prod": "eas build --profile production --platform all"
   },
   "dependencies": {
     "expo": "~52.0.0",
@@ -22,10 +26,12 @@
     "@react-navigation/bottom-tabs": "^7.0.0",
     "axios": "^1.7.9",
     "@react-native-async-storage/async-storage": "2.1.0",
-    "expo-document-picker": "~13.0.0",
+    "@epubjs-react-native/core": "1.4.7",
+    "@epubjs-react-native/expo-file-system": "1.1.4",
     "expo-file-system": "~18.0.0",
     "react-native-gesture-handler": "~2.20.0",
     "react-native-reanimated": "~3.16.0",
+    "react-native-webview": "13.12.5",
     "@cloud-reader/shared": "*"
   },
   "devDependencies": {

mobile/src/api/annotations.ts

@@ -1,55 +1,31 @@
 import api from "./client";
-import type {
+import type { PaginatedResponse } from "@cloud-reader/shared";
-  Bookmark,
+import type { Bookmark, CreateMarkerPayload } from "../types";
-  Note,
-  CreateBookmarkPayload,
-  CreateNotePayload,
-  PaginatedResponse,
-} from "@cloud-reader/shared";
 
-export function fetchBookmarks(
+export async function fetchBookmarks(
-  bookId?: string,
+  ebookId?: string | number,
 ): Promise<PaginatedResponse<Bookmark>> {
-  const params = bookId ? { book: bookId } : {};
+  const params: Record<string, string> = {};
-  return api
+  if (ebookId != null && ebookId !== "") {
-    .get<PaginatedResponse<Bookmark>>("/api/annotations/bookmarks/", { params })
+    params.ebook = String(ebookId);
-    .then((res) => res.data);
+  }
+  const { data } = await api.get<PaginatedResponse<Bookmark>>(
+    "/api/annotations/bookmarks/",
+    { params },
+  );
+  return data;
 }
 
-export function createBookmark(
+export async function createMarker(
-  payload: CreateBookmarkPayload,
+  payload: CreateMarkerPayload,
 ): Promise<Bookmark> {
-  return api
+  const { data } = await api.post<Bookmark>(
-    .post<Bookmark>("/api/annotations/bookmarks/", payload)
+    "/api/annotations/bookmarks/",
-    .then((res) => res.data);
+    payload,
+  );
+  return data;
 }
 
-export function deleteBookmark(id: string): Promise<void> {
+export async function deleteBookmark(id: string): Promise<void> {
-  return api.delete(`/api/annotations/bookmarks/${id}/`).then(() => {});
+  await api.delete(`/api/annotations/bookmarks/${id}/`);
 }
-
-export function fetchNotes(bookId?: string): Promise<PaginatedResponse<Note>> {
-  const params = bookId ? { book: bookId } : {};
-  return api
-    .get<PaginatedResponse<Note>>("/api/annotations/notes/", { params })
-    .then((res) => res.data);
-}
-
-export function createNote(payload: CreateNotePayload): Promise<Note> {
-  return api
-    .post<Note>("/api/annotations/notes/", payload)
-    .then((res) => res.data);
-}
-
-export function updateNote(
-  id: string,
-  content: string,
-): Promise<Note> {
-  return api
-    .patch<Note>(`/api/annotations/notes/${id}/`, { content })
-    .then((res) => res.data);
-}
-
-export function deleteNote(id: string): Promise<void> {
-  return api.delete(`/api/annotations/notes/${id}/`).then(() => {});
-}

mobile/src/api/books.ts

@@ -1,31 +1,12 @@
 import api from "./client";
 import type { Book, PaginatedResponse } from "@cloud-reader/shared";
 
-export function fetchBooks(
-  page = 1,
-  pageSize = 20,
-): Promise<PaginatedResponse<Book>> {
-  return api
-    .get<PaginatedResponse<Book>>("/api/books/", {
-      params: { page, page_size: pageSize },
-    })
-    .then((res) => res.data);
-}
-
-export function fetchBook(id: string): Promise<Book> {
-  return api.get<Book>(`/api/books/${id}/`).then((res) => res.data);
-}
-
 export function searchBooks(
   query: string,
 ): Promise<PaginatedResponse<Book>> {
   return api
-    .get<PaginatedResponse<Book>>("/api/books/search/", {
+    .get<PaginatedResponse<Book>>("/api/books/", {
       params: { q: query },
     })
     .then((res) => res.data);
 }
-
-export function deleteBook(id: string): Promise<void> {
-  return api.delete(`/api/books/${id}/`).then(() => {});
-}

mobile/src/api/client.ts

@@ -1,5 +1,6 @@
 import axios, { type AxiosError, type InternalAxiosRequestConfig } from "axios";
 import AsyncStorage from "@react-native-async-storage/async-storage";
+import type { TokenResponse } from "@cloud-reader/shared";
 
 const STORAGE_KEYS = {
   ACCESS_TOKEN: "access_token",
@@ -39,6 +40,26 @@ async function clearTokens(): Promise<void> {
   ]);
 }
 
+async function saveTokens(tokens: TokenResponse): Promise<void> {
+  await setTokens(tokens.access, tokens.refresh);
+}
+
+async function loadTokens(): Promise<TokenResponse | null> {
+  const [access, refresh] = await Promise.all([
+    getAccessToken(),
+    getRefreshToken(),
+  ]);
+  if (!access || !refresh) {
+    return null;
+  }
+  return { access, refresh };
+}
+
+/** Absolute base URL used for direct (non-axios) requests like file downloads. */
+function getApiBaseUrl(): string {
+  return api.defaults.baseURL ?? "";
+}
+
 // ── Request interceptor ─────────────────────────────────────────────
 
 api.interceptors.request.use(async (config: InternalAxiosRequestConfig) => {
@@ -136,5 +157,14 @@ api.interceptors.response.use(
   },
 );
 
-export { getAccessToken, getRefreshToken, setTokens, clearTokens };
+const apiClient = api;
+
+export {
+  apiClient,
+  getAccessToken,
+  saveTokens,
+  loadTokens,
+  clearTokens,
+  getApiBaseUrl,
+};
 export default api;

mobile/src/api/ebooks.ts

@@ -1,54 +1,35 @@
-import { apiClient } from "./client";
+import { apiClient, getApiBaseUrl } from "./client";
 import type {
   EBookListItem,
   EBookDetail,
-  ReadingProgress,
-  ReadingSettings,
   TocResponse,
-  ContentResponse,
   PaginatedResponse,
 } from "@cloud-reader/shared";
 
 export const ebooksApi = {
-  /** List uploaded e-books */
+  /** List the authenticated user's uploaded e-books */
   list() {
-    return apiClient.get<PaginatedResponse<EBookListItem>>("/api/ebooks/");
+    return apiClient.get<PaginatedResponse<EBookListItem>>(
+      "/api/books/ebooks/",
+    );
   },
 
-  /** Get e-book detail */
+  /** Get e-book detail (metadata, format, progress) */
   get(id: number) {
-    return apiClient.get<EBookDetail>(`/api/ebooks/${id}/`);
+    return apiClient.get<EBookDetail>(`/api/books/ebooks/${id}/`);
   },
 
-  /** Get table of contents */
+  /** Get the table of contents (used as a fallback for chapter navigation) */
   getToc(id: number) {
-    return apiClient.get<TocResponse>(`/api/ebooks/${id}/toc/`);
+    return apiClient.get<TocResponse>(`/api/books/ebooks/${id}/toc/`);
   },
 
-  /** Get page content */
+  /**
-  getContent(id: number, page: number) {
+   * Absolute URL to stream the raw ebook file. The endpoint requires JWT auth,
-    return apiClient.get<ContentResponse>(
+   * so callers download it with an Authorization header (e.g. via
-      `/api/ebooks/${id}/content/?page=${page}`,
+   * expo-file-system) rather than handing the URL to a renderer directly.
-    );
+   */
+  getFileUrl(id: number): string {
+    return `${getApiBaseUrl()}/api/books/ebooks/${id}/file/`;
   },
-
+};
-  /** Update reading progress */
-  updateProgress(id: number, data: Partial<ReadingProgress>) {
-    return apiClient.patch<ReadingProgress>(
-      `/api/ebooks/${id}/progress/`,
-      data,
-    );
-  },
-
-  /** Get or update reading settings */
-  getSettings(id: number) {
-    return apiClient.get<ReadingSettings>(`/api/ebooks/${id}/settings/`);
-  },
-
-  updateSettings(id: number, data: Partial<ReadingSettings>) {
-    return apiClient.patch<ReadingSettings>(
-      `/api/ebooks/${id}/settings/`,
-      data,
-    );
-  },
-};

mobile/src/api/index.ts

@@ -1,4 +0,0 @@
-export { apiClient, saveTokens, loadTokens, clearTokens } from "./client";
-export { booksApi } from "./books";
-export { ebooksApi } from "./ebooks";
-export { annotationsApi } from "./annotations";

mobile/src/api/reader.ts

@@ -0,0 +1,75 @@
+/**
+ * Reader API client — reading settings and per-book progress.
+ * Mirrors frontend/src/api/reader.ts. Uses the shared axios client so the
+ * JWT access token is attached automatically.
+ */
+
+import api from "./client";
+import type { ReadingProgress, ReadingSettings } from "../types/reader";
+
+export async function getReadingSettings(): Promise<ReadingSettings> {
+  const { data } = await api.get<ReadingSettings>("/api/reader/settings/");
+  return data;
+}
+
+export async function updateReadingSettings(
+  settings: Partial<ReadingSettings>,
+): Promise<ReadingSettings> {
+  const { data } = await api.patch<ReadingSettings>(
+    "/api/reader/settings/",
+    settings,
+  );
+  return data;
+}
+
+interface ProgressWire {
+  current_position: number;
+  last_page: number;
+  epub_location?: string;
+  updated_at?: string;
+}
+
+function toReadingProgress(bookId: number, data: ProgressWire): ReadingProgress {
+  return {
+    id: bookId,
+    book: bookId,
+    current_chapter: data.last_page || 1,
+    current_position: data.current_position ?? 0,
+    percentage: data.current_position ?? 0,
+    epub_location: data.epub_location ?? "",
+    updated_at: data.updated_at ?? "",
+  };
+}
+
+export async function getReadingProgress(
+  bookId: number,
+): Promise<ReadingProgress> {
+  const { data } = await api.get<ProgressWire>(
+    `/api/books/ebooks/${bookId}/progress/`,
+  );
+  return toReadingProgress(bookId, data);
+}
+
+export async function updateReadingProgress(
+  bookId: number,
+  progress: Partial<ReadingProgress>,
+): Promise<ReadingProgress> {
+  const body: Record<string, string | number> = {};
+  if (
+    progress.percentage !== undefined ||
+    progress.current_position !== undefined
+  ) {
+    body.current_position = progress.percentage ?? progress.current_position ?? 0;
+  }
+  if (progress.current_chapter !== undefined) {
+    body.last_page = progress.current_chapter;
+  }
+  if (progress.epub_location !== undefined) {
+    body.epub_location = progress.epub_location;
+  }
+  const { data } = await api.patch<ProgressWire>(
+    `/api/books/ebooks/${bookId}/progress/`,
+    body,
+  );
+  return toReadingProgress(bookId, data);
+}

mobile/src/components/reader/BookmarksModal.tsx

@@ -0,0 +1,147 @@
+import { type ReactNode } from "react";
+import {
+  Text,
+  FlatList,
+  TouchableOpacity,
+  StyleSheet,
+  View,
+} from "react-native";
+import { resolvePalette } from "../../utils/epubTheme";
+import type { ReadingSettings } from "../../types/reader";
+import type { Bookmark } from "../../types";
+import { ReaderBottomSheet } from "./ReaderBottomSheet";
+
+interface BookmarksModalProps {
+  visible: boolean;
+  bookmarks: Bookmark[];
+  settings: ReadingSettings;
+  onSelect: (bookmark: Bookmark) => void;
+  onDelete: (bookmark: Bookmark) => void;
+  onClose: () => void;
+}
+
+export function BookmarksModal({
+  visible,
+  bookmarks,
+  settings,
+  onSelect,
+  onDelete,
+  onClose,
+}: BookmarksModalProps): ReactNode {
+  const palette = resolvePalette(settings);
+
+  return (
+    <ReaderBottomSheet
+      visible={visible}
+      title="Bookmarks & highlights"
+      chromeColor={palette.chrome}
+      textColor={palette.text}
+      onClose={onClose}
+    >
+      <FlatList
+        data={bookmarks}
+        keyExtractor={(item) => item.id}
+        ListEmptyComponent={
+          <Text style={[styles.empty, { color: palette.text }]}>
+            No bookmarks yet. Tap the star to bookmark a page, or select text to
+            highlight it.
+          </Text>
+        }
+        renderItem={({ item }) => (
+          <View style={styles.row}>
+            <TouchableOpacity
+              style={styles.rowMain}
+              onPress={() => onSelect(item)}
+            >
+              {item.highlight_color ? (
+                <View
+                  style={[
+                    styles.dot,
+                    { backgroundColor: item.highlight_color },
+                  ]}
+                />
+              ) : (
+                <Text style={styles.star}>★</Text>
+              )}
+              <View style={styles.rowTextWrap}>
+                {item.chapter_title ? (
+                  <Text
+                    style={[styles.chapter, { color: palette.text }]}
+                    numberOfLines={1}
+                  >
+                    {item.chapter_title}
+                  </Text>
+                ) : null}
+                <Text
+                  style={[styles.excerpt, { color: palette.text }]}
+                  numberOfLines={2}
+                >
+                  {item.content || item.location_text || "Bookmarked page"}
+                </Text>
+              </View>
+            </TouchableOpacity>
+            <TouchableOpacity
+              onPress={() => onDelete(item)}
+              hitSlop={8}
+              style={styles.deleteButton}
+            >
+              <Text style={styles.deleteText}>Delete</Text>
+            </TouchableOpacity>
+          </View>
+        )}
+      />
+    </ReaderBottomSheet>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    paddingVertical: 12,
+    paddingHorizontal: 16,
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: "rgba(127,127,127,0.2)",
+  },
+  rowMain: {
+    flex: 1,
+    flexDirection: "row",
+    alignItems: "center",
+  },
+  rowTextWrap: {
+    flex: 1,
+    marginLeft: 10,
+  },
+  star: {
+    fontSize: 16,
+    color: "#4f8ef7",
+  },
+  dot: {
+    width: 14,
+    height: 14,
+    borderRadius: 7,
+  },
+  chapter: {
+    fontSize: 12,
+    opacity: 0.7,
+    marginBottom: 2,
+  },
+  excerpt: {
+    fontSize: 14,
+  },
+  deleteButton: {
+    marginLeft: 12,
+    paddingHorizontal: 10,
+    paddingVertical: 6,
+  },
+  deleteText: {
+    color: "#ff453a",
+    fontSize: 13,
+    fontWeight: "600",
+  },
+  empty: {
+    padding: 24,
+    textAlign: "center",
+    opacity: 0.7,
+  },
+});

mobile/src/components/reader/EpubReaderView.tsx

@@ -0,0 +1,436 @@
+import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+import {
+  View,
+  Text,
+  ActivityIndicator,
+  StyleSheet,
+  type LayoutChangeEvent,
+} from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { Reader, ReaderProvider, useReader } from "@epubjs-react-native/core";
+import { useFileSystem } from "@epubjs-react-native/expo-file-system";
+import * as FileSystem from "expo-file-system";
+import type { EBookDetail } from "@cloud-reader/shared";
+import { getAccessToken } from "../../api/client";
+import { ebooksApi } from "../../api/ebooks";
+import { getReadingProgress, updateReadingProgress } from "../../api/reader";
+import {
+  fetchBookmarks,
+  createMarker,
+  deleteBookmark,
+} from "../../api/annotations";
+import { useReadingSettings } from "../../hooks/useReadingSettings";
+import {
+  buildEpubTheme,
+  FONT_STACKS,
+  resolvePalette,
+} from "../../utils/epubTheme";
+import type { Bookmark } from "../../types";
+import { ReaderToolbar } from "./ReaderToolbar";
+import { TocModal, type TocItem } from "./TocModal";
+import { ReadingSettingsModal } from "./ReadingSettingsModal";
+import { BookmarksModal } from "./BookmarksModal";
+
+const HIGHLIGHT_COLOR = "#ffd54a";
+const PROGRESS_SAVE_MS = 800;
+
+/** Loose view of the epubjs-react-native reader API we rely on. */
+interface ReaderApi {
+  goToLocation?: (target: string) => void;
+  changeTheme?: (theme: Record<string, Record<string, string>>) => void;
+  changeFontSize?: (size: string) => void;
+  changeFontFamily?: (font: string) => void;
+  addAnnotation?: (
+    type: string,
+    cfiRange: string,
+    data?: unknown,
+    styles?: Record<string, unknown>,
+  ) => void;
+  removeAnnotationByCfi?: (cfi: string) => void;
+  removeSelection?: () => void;
+  toc?: TocItem[];
+}
+
+interface EpubLocation {
+  start?: { cfi?: string };
+}
+
+interface EpubSection {
+  label?: string;
+  index?: number;
+}
+
+interface EpubReaderViewProps {
+  book: EBookDetail;
+  ebookId: number;
+  onClose: () => void;
+}
+
+export function EpubReaderView(props: EpubReaderViewProps): ReactNode {
+  return (
+    <ReaderProvider>
+      <EpubReaderInner {...props} />
+    </ReaderProvider>
+  );
+}
+
+function EpubReaderInner({
+  book,
+  ebookId,
+  onClose,
+}: EpubReaderViewProps): ReactNode {
+  const reader = useReader() as unknown as ReaderApi;
+  const { settings, updateSettings } = useReadingSettings();
+
+  const [src, setSrc] = useState<string | null>(null);
+  const [initialLocation, setInitialLocation] = useState<string | undefined>();
+  const [fileError, setFileError] = useState(false);
+  const [ready, setReady] = useState(false);
+  const [size, setSize] = useState<{ width: number; height: number } | null>(
+    null,
+  );
+
+  const [progressPct, setProgressPct] = useState(
+    Math.round(book.progress?.current_position ?? 0),
+  );
+  const [chapterTitle, setChapterTitle] = useState("");
+  const [currentCfi, setCurrentCfi] = useState("");
+  const [bookmarks, setBookmarks] = useState<Bookmark[]>([]);
+
+  const [tocOpen, setTocOpen] = useState(false);
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [bookmarksOpen, setBookmarksOpen] = useState(false);
+
+  const currentCfiRef = useRef("");
+  const progressPctRef = useRef(progressPct);
+  const sectionRef = useRef<{ index: number; label: string }>({
+    index: 0,
+    label: "",
+  });
+  const bookmarksRef = useRef<Bookmark[]>([]);
+  const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    bookmarksRef.current = bookmarks;
+  }, [bookmarks]);
+
+  // Download the EPUB with auth, and resolve the saved resume location.
+  useEffect(() => {
+    let active = true;
+    (async () => {
+      try {
+        const progress = await getReadingProgress(ebookId).catch(() => null);
+        if (active && progress?.epub_location) {
+          setInitialLocation(progress.epub_location);
+          currentCfiRef.current = progress.epub_location;
+          setCurrentCfi(progress.epub_location);
+        }
+        const token = await getAccessToken();
+        const url = ebooksApi.getFileUrl(ebookId);
+        const dest = `${FileSystem.cacheDirectory}ebook-${ebookId}.epub`;
+        const result = await FileSystem.downloadAsync(url, dest, {
+          headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+        });
+        if (!active) return;
+        if (result.status >= 400) {
+          setFileError(true);
+          return;
+        }
+        setSrc(result.uri);
+      } catch {
+        if (active) setFileError(true);
+      }
+    })();
+    return () => {
+      active = false;
+    };
+  }, [ebookId]);
+
+  // Load existing bookmarks/highlights for this book.
+  useEffect(() => {
+    let active = true;
+    fetchBookmarks(ebookId)
+      .then((res) => {
+        if (active) setBookmarks(res.results);
+      })
+      .catch(() => {
+        /* bookmarks are optional */
+      });
+    return () => {
+      active = false;
+    };
+  }, [ebookId]);
+
+  // Apply typography/theme to the rendition once it is ready and on changes.
+  useEffect(() => {
+    if (!ready) return;
+    try {
+      reader.changeTheme?.(buildEpubTheme(settings));
+      reader.changeFontSize?.(`${settings.font_size}px`);
+      reader.changeFontFamily?.(FONT_STACKS[settings.font_family]);
+    } catch {
+      /* ignore rendition styling errors */
+    }
+  }, [ready, settings, reader]);
+
+  const flushProgress = useCallback(() => {
+    const cfi = currentCfiRef.current;
+    if (!cfi) return;
+    updateReadingProgress(ebookId, {
+      percentage: progressPctRef.current,
+      epub_location: cfi,
+      current_chapter: sectionRef.current.index + 1,
+    }).catch(() => {
+      /* progress is best-effort */
+    });
+  }, [ebookId]);
+
+  // Flush the latest progress when leaving the reader.
+  useEffect(
+    () => () => {
+      if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
+      flushProgress();
+    },
+    [flushProgress],
+  );
+
+  const handleReady = useCallback(() => {
+    setReady(true);
+    bookmarksRef.current.forEach((bookmark) => {
+      if (bookmark.highlight_color && bookmark.epub_cfi) {
+        try {
+          reader.addAnnotation?.("highlight", bookmark.epub_cfi, undefined, {
+            fill: bookmark.highlight_color,
+          });
+        } catch {
+          /* highlight rendering is best-effort */
+        }
+      }
+    });
+  }, [reader]);
+
+  const handleLocationChange = useCallback(
+    (
+      _total: number,
+      location: EpubLocation,
+      progress: number,
+      section: EpubSection | null,
+    ) => {
+      const cfi = location?.start?.cfi ?? "";
+      if (cfi) {
+        currentCfiRef.current = cfi;
+        setCurrentCfi(cfi);
+      }
+      const pct = Math.round(progress ?? 0);
+      progressPctRef.current = pct;
+      setProgressPct(pct);
+      const label = section?.label?.trim() ?? "";
+      sectionRef.current = {
+        index: section?.index ?? sectionRef.current.index,
+        label,
+      };
+      setChapterTitle(label);
+
+      if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
+      saveTimerRef.current = setTimeout(flushProgress, PROGRESS_SAVE_MS);
+    },
+    [flushProgress],
+  );
+
+  const handleSelected = useCallback(
+    async (selectedText: string, cfiRange: string) => {
+      const excerpt = (selectedText ?? "").slice(0, 280);
+      try {
+        const created = await createMarker({
+          ebook: ebookId,
+          epub_cfi: cfiRange,
+          chapter_index: sectionRef.current.index,
+          chapter_title: sectionRef.current.label,
+          location_text: excerpt,
+          content: excerpt,
+          highlight_color: HIGHLIGHT_COLOR,
+        });
+        setBookmarks((prev) => [created, ...prev]);
+        try {
+          reader.addAnnotation?.("highlight", cfiRange, undefined, {
+            fill: HIGHLIGHT_COLOR,
+          });
+          reader.removeSelection?.();
+        } catch {
+          /* annotation rendering is best-effort */
+        }
+      } catch {
+        /* ignore highlight save failures */
+      }
+    },
+    [ebookId, reader],
+  );
+
+  const handleToggleBookmarkHere = useCallback(async () => {
+    const cfi = currentCfiRef.current;
+    if (!cfi) return;
+    const existing = bookmarksRef.current.find((b) => b.epub_cfi === cfi);
+    if (existing) {
+      setBookmarks((prev) => prev.filter((b) => b.id !== existing.id));
+      try {
+        reader.removeAnnotationByCfi?.(cfi);
+      } catch {
+        /* best-effort */
+      }
+      deleteBookmark(existing.id).catch(() => {});
+      return;
+    }
+    try {
+      const created = await createMarker({
+        ebook: ebookId,
+        epub_cfi: cfi,
+        chapter_index: sectionRef.current.index,
+        chapter_title: sectionRef.current.label,
+        location_text: sectionRef.current.label,
+      });
+      setBookmarks((prev) => [created, ...prev]);
+    } catch {
+      /* ignore bookmark save failures */
+    }
+  }, [ebookId, reader]);
+
+  const handleSelectBookmark = useCallback(
+    (bookmark: Bookmark) => {
+      setBookmarksOpen(false);
+      try {
+        reader.goToLocation?.(bookmark.epub_cfi);
+      } catch {
+        /* best-effort */
+      }
+    },
+    [reader],
+  );
+
+  const handleDeleteBookmark = useCallback(
+    (bookmark: Bookmark) => {
+      setBookmarks((prev) => prev.filter((b) => b.id !== bookmark.id));
+      try {
+        if (bookmark.highlight_color) {
+          reader.removeAnnotationByCfi?.(bookmark.epub_cfi);
+        }
+      } catch {
+        /* best-effort */
+      }
+      deleteBookmark(bookmark.id).catch(() => {});
+    },
+    [reader],
+  );
+
+  const handleTocSelect = useCallback(
+    (href: string) => {
+      setTocOpen(false);
+      try {
+        reader.goToLocation?.(href);
+      } catch {
+        /* best-effort */
+      }
+    },
+    [reader],
+  );
+
+  const onReaderLayout = useCallback((event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setSize((prev) =>
+      prev && prev.width === width && prev.height === height
+        ? prev
+        : { width, height },
+    );
+  }, []);
+
+  const palette = resolvePalette(settings);
+  const isBookmarked = bookmarks.some((b) => b.epub_cfi === currentCfi);
+
+  return (
+    <SafeAreaView
+      style={[styles.container, { backgroundColor: palette.background }]}
+      edges={["top", "bottom"]}
+    >
+      <ReaderToolbar
+        title={book.title}
+        chapterTitle={chapterTitle}
+        progressPct={progressPct}
+        settings={settings}
+        isBookmarked={isBookmarked}
+        onBack={onClose}
+        onToggleToc={() => setTocOpen(true)}
+        onToggleSettings={() => setSettingsOpen(true)}
+        onToggleBookmarks={() => setBookmarksOpen(true)}
+        onToggleBookmarkHere={handleToggleBookmarkHere}
+      />
+
+      <View style={styles.readerArea} onLayout={onReaderLayout}>
+        {fileError ? (
+          <View style={styles.centered}>
+            <Text style={[styles.message, { color: palette.text }]}>
+              Could not download this book. Check your connection and try again.
+            </Text>
+          </View>
+        ) : src && size ? (
+          <Reader
+            src={src}
+            fileSystem={useFileSystem}
+            width={size.width}
+            height={size.height}
+            initialLocation={initialLocation}
+            enableSelection
+            flow="paginated"
+            defaultTheme={buildEpubTheme(settings)}
+            onReady={handleReady}
+            onLocationChange={handleLocationChange}
+            onSelected={handleSelected}
+          />
+        ) : (
+          <View style={styles.centered}>
+            <ActivityIndicator size="large" color="#4f8ef7" />
+          </View>
+        )}
+      </View>
+
+      <TocModal
+        visible={tocOpen}
+        toc={reader.toc ?? []}
+        settings={settings}
+        onSelect={handleTocSelect}
+        onClose={() => setTocOpen(false)}
+      />
+      <ReadingSettingsModal
+        visible={settingsOpen}
+        settings={settings}
+        onChange={updateSettings}
+        onClose={() => setSettingsOpen(false)}
+      />
+      <BookmarksModal
+        visible={bookmarksOpen}
+        bookmarks={bookmarks}
+        settings={settings}
+        onSelect={handleSelectBookmark}
+        onDelete={handleDeleteBookmark}
+        onClose={() => setBookmarksOpen(false)}
+      />
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  readerArea: {
+    flex: 1,
+  },
+  centered: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    padding: 24,
+  },
+  message: {
+    fontSize: 15,
+    textAlign: "center",
+  },
+});

mobile/src/components/reader/ReaderBottomSheet.tsx

@@ -0,0 +1,92 @@
+import { type ReactNode } from "react";
+import {
+  Modal,
+  View,
+  Text,
+  TouchableOpacity,
+  StyleSheet,
+  type StyleProp,
+  type ViewStyle,
+} from "react-native";
+
+interface ReaderBottomSheetProps {
+  visible: boolean;
+  title: string;
+  chromeColor: string;
+  textColor: string;
+  onClose: () => void;
+  children: ReactNode;
+  /** When true, caps sheet height (TOC/bookmarks). Settings uses a full-width panel. */
+  tall?: boolean;
+  sheetStyle?: StyleProp<ViewStyle>;
+}
+
+export function ReaderBottomSheet({
+  visible,
+  title,
+  chromeColor,
+  textColor,
+  onClose,
+  children,
+  tall = true,
+  sheetStyle,
+}: ReaderBottomSheetProps): ReactNode {
+  return (
+    <Modal
+      visible={visible}
+      animationType="slide"
+      transparent
+      onRequestClose={onClose}
+    >
+      <View style={styles.backdrop}>
+        <View
+          style={[
+            styles.sheet,
+            tall && styles.sheetTall,
+            { backgroundColor: chromeColor },
+            sheetStyle,
+          ]}
+        >
+          <View style={styles.header}>
+            <Text style={[styles.headerTitle, { color: textColor }]}>
+              {title}
+            </Text>
+            <TouchableOpacity onPress={onClose} hitSlop={12}>
+              <Text style={[styles.close, { color: textColor }]}>✕</Text>
+            </TouchableOpacity>
+          </View>
+          {children}
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  backdrop: {
+    flex: 1,
+    backgroundColor: "rgba(0,0,0,0.4)",
+    justifyContent: "flex-end",
+  },
+  sheet: {
+    borderTopLeftRadius: 16,
+    borderTopRightRadius: 16,
+    paddingBottom: 24,
+  },
+  sheetTall: {
+    maxHeight: "75%",
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    padding: 16,
+  },
+  headerTitle: {
+    fontSize: 16,
+    fontWeight: "700",
+  },
+  close: {
+    fontSize: 18,
+  },
+});

mobile/src/components/reader/ReaderToolbar.tsx

@@ -0,0 +1,152 @@
+import { type ReactNode } from "react";
+import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
+import { resolvePalette } from "../../utils/epubTheme";
+import type { ReadingSettings } from "../../types/reader";
+
+interface ReaderToolbarProps {
+  title: string;
+  chapterTitle: string;
+  progressPct: number;
+  settings: ReadingSettings;
+  isBookmarked: boolean;
+  onBack: () => void;
+  onToggleToc: () => void;
+  onToggleSettings: () => void;
+  onToggleBookmarks: () => void;
+  onToggleBookmarkHere: () => void;
+}
+
+export function ReaderToolbar({
+  title,
+  chapterTitle,
+  progressPct,
+  settings,
+  isBookmarked,
+  onBack,
+  onToggleToc,
+  onToggleSettings,
+  onToggleBookmarks,
+  onToggleBookmarkHere,
+}: ReaderToolbarProps): ReactNode {
+  const palette = resolvePalette(settings);
+
+  return (
+    <View style={[styles.bar, { backgroundColor: palette.chrome }]}>
+      <View style={styles.row}>
+        <TouchableOpacity
+          onPress={onBack}
+          hitSlop={12}
+          style={styles.iconButton}
+        >
+          <Text style={[styles.icon, { color: palette.text }]}>‹</Text>
+        </TouchableOpacity>
+
+        <View style={styles.titles}>
+          <Text
+            style={[styles.title, { color: palette.text }]}
+            numberOfLines={1}
+          >
+            {title}
+          </Text>
+          {chapterTitle ? (
+            <Text
+              style={[styles.chapter, { color: palette.text }]}
+              numberOfLines={1}
+            >
+              {chapterTitle}
+            </Text>
+          ) : null}
+        </View>
+
+        <TouchableOpacity
+          onPress={onToggleBookmarkHere}
+          hitSlop={12}
+          style={styles.iconButton}
+        >
+          <Text style={[styles.icon, { color: palette.text }]}>
+            {isBookmarked ? "★" : "☆"}
+          </Text>
+        </TouchableOpacity>
+        <TouchableOpacity
+          onPress={onToggleBookmarks}
+          hitSlop={12}
+          style={styles.iconButton}
+        >
+          <Text style={[styles.iconSmall, { color: palette.text }]}>≡</Text>
+        </TouchableOpacity>
+        <TouchableOpacity
+          onPress={onToggleToc}
+          hitSlop={12}
+          style={styles.iconButton}
+        >
+          <Text style={[styles.iconSmall, { color: palette.text }]}>⊟</Text>
+        </TouchableOpacity>
+        <TouchableOpacity
+          onPress={onToggleSettings}
+          hitSlop={12}
+          style={styles.iconButton}
+        >
+          <Text style={[styles.iconSmall, { color: palette.text }]}>Aa</Text>
+        </TouchableOpacity>
+      </View>
+
+      <View style={styles.progressTrack}>
+        <View
+          style={[
+            styles.progressFill,
+            { width: `${Math.min(100, Math.max(0, progressPct))}%` },
+          ]}
+        />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  bar: {
+    paddingTop: 8,
+    paddingHorizontal: 8,
+    paddingBottom: 6,
+  },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+  },
+  titles: {
+    flex: 1,
+    marginHorizontal: 8,
+  },
+  title: {
+    fontSize: 14,
+    fontWeight: "600",
+  },
+  chapter: {
+    fontSize: 11,
+    opacity: 0.7,
+  },
+  iconButton: {
+    paddingHorizontal: 8,
+    paddingVertical: 4,
+    minWidth: 28,
+    alignItems: "center",
+  },
+  icon: {
+    fontSize: 28,
+    lineHeight: 30,
+  },
+  iconSmall: {
+    fontSize: 17,
+    fontWeight: "600",
+  },
+  progressTrack: {
+    height: 3,
+    borderRadius: 2,
+    backgroundColor: "rgba(127,127,127,0.25)",
+    marginTop: 6,
+    overflow: "hidden",
+  },
+  progressFill: {
+    height: "100%",
+    backgroundColor: "#4f8ef7",
+  },
+});

mobile/src/components/reader/ReadingSettingsModal.tsx

@@ -0,0 +1,249 @@
+import { type ReactNode } from "react";
+import {
+  View,
+  Text,
+  TouchableOpacity,
+  StyleSheet,
+} from "react-native";
+import { resolvePalette, THEME_PALETTES } from "../../utils/epubTheme";
+import type {
+  FontFamily,
+  ReadingSettings,
+  ThemePreset,
+} from "../../types/reader";
+import { ReaderBottomSheet } from "./ReaderBottomSheet";
+
+const THEMES: ThemePreset[] = ["light", "sepia", "paper", "dark"];
+const FONTS: { value: FontFamily; label: string }[] = [
+  { value: "serif", label: "Serif" },
+  { value: "sans-serif", label: "Sans" },
+  { value: "monospace", label: "Mono" },
+];
+const FONT_SIZE_MIN = 12;
+const FONT_SIZE_MAX = 32;
+const LINE_HEIGHT_MIN = 1.2;
+const LINE_HEIGHT_MAX = 2.2;
+
+interface ReadingSettingsModalProps {
+  visible: boolean;
+  settings: ReadingSettings;
+  onChange: (patch: Partial<ReadingSettings>) => void;
+  onClose: () => void;
+}
+
+export function ReadingSettingsModal({
+  visible,
+  settings,
+  onChange,
+  onClose,
+}: ReadingSettingsModalProps): ReactNode {
+  const palette = resolvePalette(settings);
+
+  const adjustFontSize = (delta: number) => {
+    const next = Math.min(
+      FONT_SIZE_MAX,
+      Math.max(FONT_SIZE_MIN, settings.font_size + delta),
+    );
+    onChange({ font_size: next });
+  };
+
+  const adjustLineHeight = (delta: number) => {
+    const next = Math.min(
+      LINE_HEIGHT_MAX,
+      Math.max(
+        LINE_HEIGHT_MIN,
+        Math.round((settings.line_height + delta) * 10) / 10,
+      ),
+    );
+    onChange({ line_height: next });
+  };
+
+  return (
+    <ReaderBottomSheet
+      visible={visible}
+      title="Display"
+      chromeColor={palette.chrome}
+      textColor={palette.text}
+      onClose={onClose}
+      tall={false}
+      sheetStyle={styles.sheetBody}
+    >
+      <Text style={[styles.sectionLabel, { color: palette.text }]}>Theme</Text>
+      <View style={styles.rowWrap}>
+        {THEMES.map((theme) => {
+          const p = THEME_PALETTES[theme];
+          const active = settings.theme === theme;
+          return (
+            <TouchableOpacity
+              key={theme}
+              onPress={() =>
+                onChange({
+                  theme,
+                  background_color: p.background,
+                  text_color: p.text,
+                })
+              }
+              style={[
+                styles.themeSwatch,
+                { backgroundColor: p.background },
+                active && styles.themeSwatchActive,
+              ]}
+            >
+              <Text style={[styles.themeSwatchText, { color: p.text }]}>
+                Aa
+              </Text>
+            </TouchableOpacity>
+          );
+        })}
+      </View>
+
+      <Text style={[styles.sectionLabel, { color: palette.text }]}>Font</Text>
+      <View style={styles.rowWrap}>
+        {FONTS.map((font) => {
+          const active = settings.font_family === font.value;
+          return (
+            <TouchableOpacity
+              key={font.value}
+              onPress={() => onChange({ font_family: font.value })}
+              style={[styles.pill, active && styles.pillActive]}
+            >
+              <Text
+                style={[
+                  styles.pillText,
+                  { color: active ? "#fff" : palette.text },
+                ]}
+              >
+                {font.label}
+              </Text>
+            </TouchableOpacity>
+          );
+        })}
+      </View>
+
+      <Stepper
+        label="Font size"
+        value={`${settings.font_size}px`}
+        color={palette.text}
+        onDecrease={() => adjustFontSize(-1)}
+        onIncrease={() => adjustFontSize(1)}
+      />
+      <Stepper
+        label="Line spacing"
+        value={settings.line_height.toFixed(1)}
+        color={palette.text}
+        onDecrease={() => adjustLineHeight(-0.1)}
+        onIncrease={() => adjustLineHeight(0.1)}
+      />
+    </ReaderBottomSheet>
+  );
+}
+
+function Stepper({
+  label,
+  value,
+  color,
+  onDecrease,
+  onIncrease,
+}: {
+  label: string;
+  value: string;
+  color: string;
+  onDecrease: () => void;
+  onIncrease: () => void;
+}): ReactNode {
+  return (
+    <View style={styles.stepperRow}>
+      <Text style={[styles.sectionLabel, { color, marginBottom: 0 }]}>
+        {label}
+      </Text>
+      <View style={styles.stepperControls}>
+        <TouchableOpacity style={styles.stepperButton} onPress={onDecrease}>
+          <Text style={styles.stepperButtonText}>−</Text>
+        </TouchableOpacity>
+        <Text style={[styles.stepperValue, { color }]}>{value}</Text>
+        <TouchableOpacity style={styles.stepperButton} onPress={onIncrease}>
+          <Text style={styles.stepperButtonText}>+</Text>
+        </TouchableOpacity>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  sheetBody: {
+    paddingHorizontal: 20,
+    paddingBottom: 32,
+  },
+  sectionLabel: {
+    fontSize: 13,
+    fontWeight: "600",
+    marginBottom: 8,
+    marginTop: 8,
+    opacity: 0.8,
+  },
+  rowWrap: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    gap: 10,
+  },
+  themeSwatch: {
+    width: 56,
+    height: 48,
+    borderRadius: 10,
+    justifyContent: "center",
+    alignItems: "center",
+    borderWidth: 2,
+    borderColor: "transparent",
+  },
+  themeSwatchActive: {
+    borderColor: "#4f8ef7",
+  },
+  themeSwatchText: {
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  pill: {
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+    borderRadius: 20,
+    borderWidth: 1,
+    borderColor: "rgba(127,127,127,0.4)",
+  },
+  pillActive: {
+    backgroundColor: "#4f8ef7",
+    borderColor: "#4f8ef7",
+  },
+  pillText: {
+    fontSize: 14,
+    fontWeight: "600",
+  },
+  stepperRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    marginTop: 16,
+  },
+  stepperControls: {
+    flexDirection: "row",
+    alignItems: "center",
+  },
+  stepperButton: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    backgroundColor: "rgba(127,127,127,0.2)",
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  stepperButtonText: {
+    fontSize: 20,
+    fontWeight: "700",
+    color: "#4f8ef7",
+  },
+  stepperValue: {
+    minWidth: 56,
+    textAlign: "center",
+    fontSize: 15,
+    fontWeight: "600",
+  },
+});

mobile/src/components/reader/TocModal.tsx

@@ -0,0 +1,111 @@
+import { type ReactNode } from "react";
+import {
+  Text,
+  FlatList,
+  TouchableOpacity,
+  StyleSheet,
+} from "react-native";
+import { resolvePalette } from "../../utils/epubTheme";
+import type { ReadingSettings } from "../../types/reader";
+import { ReaderBottomSheet } from "./ReaderBottomSheet";
+
+export interface TocItem {
+  id?: string;
+  label: string;
+  href: string;
+  subitems?: TocItem[];
+}
+
+interface FlatTocItem {
+  key: string;
+  label: string;
+  href: string;
+  depth: number;
+}
+
+function flatten(items: TocItem[], depth = 0, acc: FlatTocItem[] = []) {
+  items.forEach((item, index) => {
+    acc.push({
+      key: `${item.id ?? item.href}-${depth}-${index}`,
+      label: (item.label ?? "").trim() || "Untitled section",
+      href: item.href,
+      depth,
+    });
+    if (item.subitems?.length) {
+      flatten(item.subitems, depth + 1, acc);
+    }
+  });
+  return acc;
+}
+
+interface TocModalProps {
+  visible: boolean;
+  toc: TocItem[];
+  settings: ReadingSettings;
+  onSelect: (href: string) => void;
+  onClose: () => void;
+}
+
+export function TocModal({
+  visible,
+  toc,
+  settings,
+  onSelect,
+  onClose,
+}: TocModalProps): ReactNode {
+  const palette = resolvePalette(settings);
+  const data = flatten(toc);
+
+  return (
+    <ReaderBottomSheet
+      visible={visible}
+      title="Contents"
+      chromeColor={palette.chrome}
+      textColor={palette.text}
+      onClose={onClose}
+    >
+      <FlatList
+        data={data}
+        keyExtractor={(item) => item.key}
+        ListEmptyComponent={
+          <Text style={[styles.empty, { color: palette.text }]}>
+            No table of contents available.
+          </Text>
+        }
+        renderItem={({ item }) => (
+          <TouchableOpacity
+            style={styles.row}
+            onPress={() => onSelect(item.href)}
+          >
+            <Text
+              style={[
+                styles.rowText,
+                { color: palette.text, marginLeft: item.depth * 16 },
+              ]}
+              numberOfLines={2}
+            >
+              {item.label}
+            </Text>
+          </TouchableOpacity>
+        )}
+      />
+    </ReaderBottomSheet>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    paddingVertical: 12,
+    paddingHorizontal: 16,
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: "rgba(127,127,127,0.2)",
+  },
+  rowText: {
+    fontSize: 14,
+  },
+  empty: {
+    padding: 24,
+    textAlign: "center",
+    opacity: 0.7,
+  },
+});

mobile/src/hooks/index.ts

@@ -1,2 +0,0 @@
-export { useAuth } from "../context/AuthContext";
-export { useAsyncData } from "./useAsyncData";

mobile/src/hooks/useAsyncData.ts

@@ -1,33 +0,0 @@
-import { useState, useEffect, useCallback } from "react";
-
-/**
- * Generic async data fetching hook for mobile screens.
- */
-export function useAsyncData<T>(
-  fetcher: () => Promise<T>,
-  deps: unknown[] = [],
-) {
-  const [data, setData] = useState<T | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const execute = useCallback(async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const result = await fetcher();
-      setData(result);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setLoading(false);
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, deps);
-
-  useEffect(() => {
-    execute();
-  }, [execute]);
-
-  return { data, loading, error, refetch: execute };
-}

mobile/src/hooks/useReadingSettings.ts

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  getReadingSettings,
+  updateReadingSettings,
+} from "../api/reader";
+import type { ReadingSettings } from "../types/reader";
+
+const DEFAULT_READING_SETTINGS: ReadingSettings = {
+  font_family: "serif",
+  font_size: 18,
+  line_height: 1.5,
+  margin_width: 16,
+  background_color: "#fbfbf8",
+  text_color: "#2b2b2b",
+  brightness: 1,
+  orientation_lock: "auto",
+  theme: "paper",
+  created_at: "",
+  updated_at: "",
+};
+
+const SAVE_DEBOUNCE_MS = 600;
+
+interface UseReadingSettingsReturn {
+  settings: ReadingSettings;
+  loaded: boolean;
+  updateSettings: (patch: Partial<ReadingSettings>) => void;
+}
+
+/**
+ * Loads the user's reader settings and persists changes with a debounce.
+ * Mirrors frontend/src/hooks/useReadingSettings.ts behavior.
+ */
+export function useReadingSettings(): UseReadingSettingsReturn {
+  const [settings, setSettings] = useState<ReadingSettings>(
+    DEFAULT_READING_SETTINGS,
+  );
+  const [loaded, setLoaded] = useState(false);
+  const pendingRef = useRef<Partial<ReadingSettings>>({});
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    let active = true;
+    getReadingSettings()
+      .then((data) => {
+        if (active) {
+          setSettings(data);
+        }
+      })
+      .catch(() => {
+        /* keep defaults if the request fails */
+      })
+      .finally(() => {
+        if (active) {
+          setLoaded(true);
+        }
+      });
+    return () => {
+      active = false;
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, []);
+
+  const updateSettings = useCallback((patch: Partial<ReadingSettings>) => {
+    setSettings((prev) => ({ ...prev, ...patch }));
+    pendingRef.current = { ...pendingRef.current, ...patch };
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+    }
+    timerRef.current = setTimeout(() => {
+      const body = pendingRef.current;
+      pendingRef.current = {};
+      updateReadingSettings(body).catch(() => {
+        /* ignore transient save failures */
+      });
+    }, SAVE_DEBOUNCE_MS);
+  }, []);
+
+  return { settings, loaded, updateSettings };
+}

mobile/src/navigation/AppNavigator.tsx

@@ -1,45 +0,0 @@
-import { type ReactNode } from "react";
-import { NavigationContainer } from "@react-navigation/native";
-import { createNativeStackNavigator } from "@react-navigation/native-stack";
-import { useAuth } from "../context/AuthContext";
-import LoginScreen from "../screens/LoginScreen";
-import RegisterScreen from "../screens/RegisterScreen";
-import MainTabs from "./MainTabs";
-
-export type AuthStackParamList = {
-  Login: undefined;
-  Register: undefined;
-};
-
-export type RootStackParamList = {
-  Auth: undefined;
-  Main: undefined;
-};
-
-const RootStack = createNativeStackNavigator<RootStackParamList>();
-const AuthStack = createNativeStackNavigator<AuthStackParamList>();
-
-function AuthNavigator(): ReactNode {
-  return (
-    <AuthStack.Navigator screenOptions={{ headerShown: false }}>
-      <AuthStack.Screen name="Login" component={LoginScreen} />
-      <AuthStack.Screen name="Register" component={RegisterScreen} />
-    </AuthStack.Navigator>
-  );
-}
-
-export default function AppNavigator(): ReactNode {
-  const { state } = useAuth();
-
-  return (
-    <NavigationContainer>
-      <RootStack.Navigator screenOptions={{ headerShown: false }}>
-        {state.isAuthenticated ? (
-          <RootStack.Screen name="Main" component={MainTabs} />
-        ) : (
-          <RootStack.Screen name="Auth" component={AuthNavigator} />
-        )}
-      </RootStack.Navigator>
-    </NavigationContainer>
-  );
-}

mobile/src/navigation/AppStack.tsx

@@ -0,0 +1,36 @@
+import React from "react";
+import { createNativeStackNavigator } from "@react-navigation/native-stack";
+import { MainNavigator } from "./MainNavigator";
+import BookDetailScreen from "../screens/BookDetailScreen";
+import ReaderScreen from "../screens/ReaderScreen";
+import type { AppStackParamList } from "../types";
+
+const Stack = createNativeStackNavigator<AppStackParamList>();
+
+export function AppStack() {
+  return (
+    <Stack.Navigator
+      screenOptions={{
+        headerStyle: { backgroundColor: "#fff" },
+        headerTitleStyle: { fontWeight: "600", color: "#1a1a2e" },
+        headerTintColor: "#4a6cf7",
+      }}
+    >
+      <Stack.Screen
+        name="Tabs"
+        component={MainNavigator}
+        options={{ headerShown: false }}
+      />
+      <Stack.Screen
+        name="BookDetail"
+        component={BookDetailScreen}
+        options={{ title: "" }}
+      />
+      <Stack.Screen
+        name="Reader"
+        component={ReaderScreen}
+        options={{ headerShown: false }}
+      />
+    </Stack.Navigator>
+  );
+}

mobile/src/navigation/AuthNavigator.tsx

@@ -3,7 +3,7 @@ import { createNativeStackNavigator } from "@react-navigation/native-stack";
 import LoginScreen from "../screens/LoginScreen";
 import RegisterScreen from "../screens/RegisterScreen";
 
-export type AuthStackParamList = {
+type AuthStackParamList = {
   Login: undefined;
   Register: undefined;
 };

mobile/src/navigation/MainTabs.tsx

@@ -1,55 +0,0 @@
-import { type ReactNode } from "react";
-import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
-import { Text } from "react-native";
-import LibraryScreen from "../screens/LibraryScreen";
-import SearchScreen from "../screens/SearchScreen";
-import SettingsScreen from "../screens/SettingsScreen";
-
-export type MainTabParamList = {
-  Library: undefined;
-  Search: undefined;
-  Settings: undefined;
-};
-
-const Tab = createBottomTabNavigator<MainTabParamList>();
-
-function TabIcon({ label, focused }: { label: string; focused: boolean }) {
-  return (
-    <Text style={{ fontSize: 22, opacity: focused ? 1 : 0.5 }}>
-      {label === "Library" ? "📚" : label === "Search" ? "🔍" : "⚙️"}
-    </Text>
-  );
-}
-
-export default function MainTabs(): ReactNode {
-  return (
-    <Tab.Navigator
-      screenOptions={({ route }) => ({
-        tabBarIcon: ({ focused }: { focused: boolean }) => (
-          <TabIcon label={route.name} focused={focused} />
-        ),
-        tabBarActiveTintColor: "#4f8ef7",
-        tabBarInactiveTintColor: "#888",
-        headerStyle: { backgroundColor: "#1a1a2e" },
-        headerTintColor: "#fff",
-        tabBarStyle: { backgroundColor: "#1a1a2e", borderTopColor: "#333" },
-      })}
-    >
-      <Tab.Screen
-        name="Library"
-        component={LibraryScreen}
-        options={{ title: "My Library" }}
-      />
-      <Tab.Screen
-        name="Search"
-        component={SearchScreen}
-        options={{ title: "Search" }}
-      />
-      <Tab.Screen
-        name="Settings"
-        component={SettingsScreen}
-        options={{ title: "Settings" }}
-      />
-    </Tab.Navigator>
-  );
-}

mobile/src/navigation/RootNavigator.tsx

@@ -2,7 +2,7 @@ import React from "react";
 import { ActivityIndicator, View } from "react-native";
 import { useAuth } from "../context/AuthContext";
 import { AuthNavigator } from "./AuthNavigator";
-import { MainNavigator } from "./MainNavigator";
+import { AppStack } from "./AppStack";
 
 export function RootNavigator() {
   const { isLoading, isAuthenticated } = useAuth();
@@ -19,5 +19,5 @@ export function RootNavigator() {
     return <AuthNavigator />;
   }
 
-  return <MainNavigator />;
+  return <AppStack />;
 }

mobile/src/screens/AuthFormError.tsx

@@ -0,0 +1,11 @@
+import { type ReactNode } from "react";
+import { View, Text } from "react-native";
+import { authStyles } from "./authStyles";
+
+export function AuthFormError({ message }: { message: string }): ReactNode {
+  return (
+    <View style={authStyles.errorBox}>
+      <Text style={authStyles.errorText}>{message}</Text>
+    </View>
+  );
+}

mobile/src/screens/BookDetailScreen.tsx

@@ -0,0 +1,226 @@
+import { useState, useEffect, useCallback, type ReactNode } from "react";
+import {
+  View,
+  Text,
+  Image,
+  ScrollView,
+  TouchableOpacity,
+  StyleSheet,
+  ActivityIndicator,
+} from "react-native";
+import type { RouteProp } from "@react-navigation/native";
+import { ebooksApi } from "../api/ebooks";
+import { formatFileSize } from "@cloud-reader/shared";
+import type { EBookDetail } from "@cloud-reader/shared";
+import type { AppStackParamList } from "../types";
+
+type DetailRoute = RouteProp<AppStackParamList, "BookDetail">;
+
+export default function BookDetailScreen({
+  route,
+  navigation,
+}: {
+  route: DetailRoute;
+  navigation: any;
+}): ReactNode {
+  const { ebookId } = route.params;
+  const [book, setBook] = useState<EBookDetail | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(false);
+
+  const load = useCallback(async () => {
+    try {
+      const { data } = await ebooksApi.get(ebookId);
+      setBook(data);
+    } catch {
+      setError(true);
+    } finally {
+      setLoading(false);
+    }
+  }, [ebookId]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  if (loading) {
+    return (
+      <View style={styles.centered}>
+        <ActivityIndicator size="large" color="#4f8ef7" />
+      </View>
+    );
+  }
+
+  if (error || !book) {
+    return (
+      <View style={styles.centered}>
+        <Text style={styles.errorText}>Could not load this book.</Text>
+      </View>
+    );
+  }
+
+  const progressPct =
+    typeof book.progress?.current_position === "number"
+      ? Math.round(book.progress.current_position)
+      : 0;
+  const hasProgress = progressPct > 0;
+
+  return (
+    <ScrollView style={styles.container} contentContainerStyle={styles.content}>
+      <View style={styles.header}>
+        {book.cover_image ? (
+          <Image source={{ uri: book.cover_image }} style={styles.cover} />
+        ) : (
+          <View style={styles.cover}>
+            <Text style={styles.coverText}>
+              {book.title.charAt(0).toUpperCase()}
+            </Text>
+          </View>
+        )}
+        <Text style={styles.title}>{book.title}</Text>
+        <Text style={styles.author}>{book.author || "Unknown author"}</Text>
+      </View>
+
+      <View style={styles.metaRow}>
+        <MetaPill label="Format" value={book.format?.toUpperCase() || "—"} />
+        <MetaPill
+          label="Pages"
+          value={book.page_count ? String(book.page_count) : "—"}
+        />
+        <MetaPill label="Size" value={formatFileSize(book.file_size || 0)} />
+      </View>
+
+      {hasProgress && (
+        <View style={styles.progressWrap}>
+          <View style={styles.progressTrack}>
+            <View style={[styles.progressFill, { width: `${progressPct}%` }]} />
+          </View>
+          <Text style={styles.progressLabel}>{progressPct}% read</Text>
+        </View>
+      )}
+
+      <TouchableOpacity
+        style={styles.readButton}
+        onPress={() => navigation.navigate("Reader", { ebookId: book.id })}
+      >
+        <Text style={styles.readButtonText}>
+          {hasProgress ? "Resume reading" : "Start reading"}
+        </Text>
+      </TouchableOpacity>
+    </ScrollView>
+  );
+}
+
+function MetaPill({ label, value }: { label: string; value: string }): ReactNode {
+  return (
+    <View style={styles.metaPill}>
+      <Text style={styles.metaValue}>{value}</Text>
+      <Text style={styles.metaLabel}>{label}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: "#0f0f23",
+  },
+  content: {
+    padding: 24,
+  },
+  centered: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    backgroundColor: "#0f0f23",
+    padding: 24,
+  },
+  header: {
+    alignItems: "center",
+    marginBottom: 24,
+  },
+  cover: {
+    width: 140,
+    height: 200,
+    borderRadius: 12,
+    backgroundColor: "#2a2a4e",
+    justifyContent: "center",
+    alignItems: "center",
+    marginBottom: 16,
+  },
+  coverText: {
+    fontSize: 56,
+    fontWeight: "bold",
+    color: "#4f8ef7",
+  },
+  title: {
+    fontSize: 22,
+    fontWeight: "700",
+    color: "#fff",
+    textAlign: "center",
+    marginBottom: 6,
+  },
+  author: {
+    fontSize: 15,
+    color: "#888",
+    textAlign: "center",
+  },
+  metaRow: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    marginBottom: 24,
+  },
+  metaPill: {
+    flex: 1,
+    backgroundColor: "#1a1a2e",
+    borderRadius: 10,
+    paddingVertical: 12,
+    marginHorizontal: 4,
+    alignItems: "center",
+    borderWidth: 1,
+    borderColor: "#333",
+  },
+  metaValue: {
+    fontSize: 15,
+    fontWeight: "600",
+    color: "#fff",
+  },
+  metaLabel: {
+    fontSize: 12,
+    color: "#666",
+    marginTop: 2,
+  },
+  progressWrap: {
+    marginBottom: 24,
+  },
+  progressTrack: {
+    height: 6,
+    borderRadius: 3,
+    backgroundColor: "#1a1a2e",
+    overflow: "hidden",
+  },
+  progressFill: {
+    height: "100%",
+    backgroundColor: "#4f8ef7",
+  },
+  progressLabel: {
+    fontSize: 12,
+    color: "#888",
+    marginTop: 6,
+  },
+  readButton: {
+    backgroundColor: "#4f8ef7",
+    borderRadius: 10,
+    paddingVertical: 16,
+    alignItems: "center",
+  },
+  readButtonText: {
+    color: "#fff",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  errorText: {
+    color: "#888",
+    fontSize: 15,
+  },
+});

mobile/src/screens/LibraryScreen.tsx

@@ -2,34 +2,31 @@ import { useState, useEffect, useCallback, type ReactNode } from "react";
 import {
   View,
   Text,
+  Image,
   FlatList,
   TouchableOpacity,
   StyleSheet,
   ActivityIndicator,
   RefreshControl,
 } from "react-native";
-import { fetchBooks } from "../api/books";
+import { ebooksApi } from "../api/ebooks";
-import type { Book, PaginatedResponse } from "@cloud-reader/shared";
+import type { EBookListItem } from "@cloud-reader/shared";
 
-export default function LibraryScreen({ navigation }: { navigation: any }): ReactNode {
+export default function LibraryScreen({
-  const [books, setBooks] = useState<Book[]>([]);
+  navigation,
+}: {
+  navigation: any;
+}): ReactNode {
+  const [books, setBooks] = useState<EBookListItem[]>([]);
   const [loading, setLoading] = useState(true);
   const [refreshing, setRefreshing] = useState(false);
-  const [page, setPage] = useState(1);
-  const [hasMore, setHasMore] = useState(true);
 
-  const loadBooks = useCallback(async (pageNum: number, isRefresh = false) => {
+  const loadBooks = useCallback(async () => {
     try {
-      const data: PaginatedResponse<Book> = await fetchBooks(pageNum);
+      const { data } = await ebooksApi.list();
-      if (isRefresh) {
+      setBooks(data.results);
-        setBooks(data.results);
-      } else {
-        setBooks((prev) => [...prev, ...data.results]);
-      }
-      setHasMore(data.next !== null);
-      setPage(pageNum);
     } catch {
-      // Silent error for now
+      // Silent error for now; pull-to-refresh lets the user retry.
     } finally {
       setLoading(false);
       setRefreshing(false);
@@ -37,44 +34,49 @@ export default function LibraryScreen({ navigation }: { navigation: any }): Reac
   }, []);
 
   useEffect(() => {
-    loadBooks(1, true);
+    loadBooks();
   }, [loadBooks]);
 
   const onRefresh = () => {
     setRefreshing(true);
-    loadBooks(1, true);
+    loadBooks();
   };
 
-  const loadMore = () => {
+  const renderBook = ({ item }: { item: EBookListItem }) => {
-    if (hasMore && !loading) {
+    const progress =
-      loadBooks(page + 1);
+      typeof item.progress === "number"
-    }
+        ? Math.round(item.progress)
+        : null;
+    return (
+      <TouchableOpacity
+        style={styles.bookCard}
+        onPress={() => navigation.navigate("BookDetail", { ebookId: item.id })}
+      >
+        {item.cover_image ? (
+          <Image source={{ uri: item.cover_image }} style={styles.bookCover} />
+        ) : (
+          <View style={styles.bookCover}>
+            <Text style={styles.coverText}>
+              {item.title.charAt(0).toUpperCase()}
+            </Text>
+          </View>
+        )}
+        <View style={styles.bookInfo}>
+          <Text style={styles.bookTitle} numberOfLines={2}>
+            {item.title}
+          </Text>
+          <Text style={styles.bookAuthor} numberOfLines={1}>
+            {item.author || "Unknown author"}
+          </Text>
+          <Text style={styles.bookMeta}>
+            {item.format?.toUpperCase()}
+            {progress !== null ? ` · ${progress}% read` : ""}
+          </Text>
+        </View>
+      </TouchableOpacity>
+    );
   };
 
-  const renderBook = ({ item }: { item: Book }) => (
-    <TouchableOpacity
-      style={styles.bookCard}
-      onPress={() =>
-        navigation.navigate("BookDetail", { bookId: item.id })
-      }
-    >
-      <View style={styles.bookCover}>
-        <Text style={styles.coverText}>
-          {item.title.charAt(0).toUpperCase()}
-        </Text>
-      </View>
-      <View style={styles.bookInfo}>
-        <Text style={styles.bookTitle} numberOfLines={1}>
-          {item.title}
-        </Text>
-        <Text style={styles.bookAuthor} numberOfLines={1}>
-          {item.author}
-        </Text>
-        <Text style={styles.bookPages}>{item.total_pages} pages</Text>
-      </View>
-    </TouchableOpacity>
-  );
-
   if (loading && books.length === 0) {
     return (
       <View style={styles.centered}>
@@ -88,9 +90,7 @@ export default function LibraryScreen({ navigation }: { navigation: any }): Reac
       <FlatList
         data={books}
         renderItem={renderBook}
-        keyExtractor={(item) => item.id}
+        keyExtractor={(item) => String(item.id)}
-        onEndReached={loadMore}
-        onEndReachedThreshold={0.5}
         contentContainerStyle={styles.list}
         refreshControl={
           <RefreshControl
@@ -103,7 +103,7 @@ export default function LibraryScreen({ navigation }: { navigation: any }): Reac
           <View style={styles.centered}>
             <Text style={styles.emptyText}>Your library is empty</Text>
             <Text style={styles.emptySubtext}>
-              Add books to get started
+              Upload books from the web app to get started
             </Text>
           </View>
         }
@@ -125,6 +125,7 @@ const styles = StyleSheet.create({
   },
   list: {
     padding: 16,
+    flexGrow: 1,
   },
   bookCard: {
     flexDirection: "row",
@@ -164,7 +165,7 @@ const styles = StyleSheet.create({
     color: "#888",
     marginBottom: 4,
   },
-  bookPages: {
+  bookMeta: {
     fontSize: 12,
     color: "#666",
   },
@@ -177,5 +178,6 @@ const styles = StyleSheet.create({
   emptySubtext: {
     fontSize: 14,
     color: "#666",
+    textAlign: "center",
   },
-});
+});

mobile/src/screens/LoginScreen.tsx

@@ -4,29 +4,31 @@ import {
   Text,
   TextInput,
   TouchableOpacity,
-  StyleSheet,
   Alert,
   ActivityIndicator,
   KeyboardAvoidingView,
   Platform,
 } from "react-native";
 import { useAuth } from "../context/AuthContext";
-import { isValidEmail } from "@cloud-reader/shared";
+import { authStyles } from "./authStyles";
+import { AuthFormError } from "./AuthFormError";
+import { requireValidEmail } from "./authValidation";
 
-export default function LoginScreen({ navigation }: { navigation: any }): ReactNode {
+export default function LoginScreen({
-  const { state, login, clearError } = useAuth();
+  navigation,
+}: {
+  navigation: any;
+}): ReactNode {
+  const { login } = useAuth();
   const [email, setEmail] = useState("");
   const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
 
   const handleLogin = async () => {
-    clearError();
+    setError(null);
 
-    if (!email.trim()) {
+    if (!requireValidEmail(email)) {
-      Alert.alert("Validation Error", "Please enter your email.");
-      return;
-    }
-    if (!isValidEmail(email.trim())) {
-      Alert.alert("Validation Error", "Please enter a valid email address.");
       return;
     }
     if (!password) {
@@ -34,30 +36,29 @@ export default function LoginScreen({ navigation }: { navigation: any }): ReactN
       return;
     }
 
+    setSubmitting(true);
     try {
       await login(email.trim(), password);
     } catch {
-      // Error handled in context
+      setError("Invalid email or password.");
+    } finally {
+      setSubmitting(false);
     }
   };
 
   return (
     <KeyboardAvoidingView
-      style={styles.container}
+      style={authStyles.container}
       behavior={Platform.OS === "ios" ? "padding" : "height"}
     >
-      <View style={styles.inner}>
+      <View style={authStyles.inner}>
-        <Text style={styles.title}>Cloud Reader</Text>
+        <Text style={authStyles.title}>Cloud Reader</Text>
-        <Text style={styles.subtitle}>Sign in to your account</Text>
+        <Text style={authStyles.subtitle}>Sign in to your account</Text>
 
-        {state.error && (
+        {error ? <AuthFormError message={error} /> : null}
-          <View style={styles.errorBox}>
-            <Text style={styles.errorText}>{state.error}</Text>
-          </View>
-        )}
 
         <TextInput
-          style={styles.input}
+          style={authStyles.input}
           placeholder="Email"
           placeholderTextColor="#666"
           value={email}
@@ -68,7 +69,7 @@ export default function LoginScreen({ navigation }: { navigation: any }): ReactN
         />
 
         <TextInput
-          style={styles.input}
+          style={authStyles.input}
           placeholder="Password"
           placeholderTextColor="#666"
           value={password}
@@ -77,97 +78,24 @@ export default function LoginScreen({ navigation }: { navigation: any }): ReactN
         />
 
         <TouchableOpacity
-          style={[styles.button, state.isLoading && styles.buttonDisabled]}
+          style={[authStyles.button, submitting && authStyles.buttonDisabled]}
           onPress={handleLogin}
-          disabled={state.isLoading}
+          disabled={submitting}
         >
-          {state.isLoading ? (
+          {submitting ? (
             <ActivityIndicator color="#fff" />
           ) : (
-            <Text style={styles.buttonText}>Sign In</Text>
+            <Text style={authStyles.buttonText}>Sign In</Text>
           )}
         </TouchableOpacity>
 
         <TouchableOpacity onPress={() => navigation.navigate("Register")}>
-          <Text style={styles.linkText}>
+          <Text style={authStyles.linkText}>
             Don't have an account?{" "}
-            <Text style={styles.linkBold}>Sign Up</Text>
+            <Text style={authStyles.linkBold}>Sign Up</Text>
           </Text>
         </TouchableOpacity>
       </View>
     </KeyboardAvoidingView>
   );
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: "#0f0f23",
-  },
-  inner: {
-    flex: 1,
-    justifyContent: "center",
-    paddingHorizontal: 24,
-  },
-  title: {
-    fontSize: 32,
-    fontWeight: "bold",
-    color: "#fff",
-    textAlign: "center",
-    marginBottom: 8,
-  },
-  subtitle: {
-    fontSize: 16,
-    color: "#888",
-    textAlign: "center",
-    marginBottom: 32,
-  },
-  input: {
-    backgroundColor: "#1a1a2e",
-    borderRadius: 8,
-    padding: 16,
-    fontSize: 16,
-    color: "#fff",
-    marginBottom: 12,
-    borderWidth: 1,
-    borderColor: "#333",
-  },
-  button: {
-    backgroundColor: "#4f8ef7",
-    borderRadius: 8,
-    padding: 16,
-    alignItems: "center",
-    marginTop: 8,
-    marginBottom: 24,
-  },
-  buttonDisabled: {
-    opacity: 0.6,
-  },
-  buttonText: {
-    color: "#fff",
-    fontSize: 16,
-    fontWeight: "600",
-  },
-  errorBox: {
-    backgroundColor: "rgba(255, 69, 58, 0.15)",
-    borderRadius: 8,
-    padding: 12,
-    marginBottom: 16,
-    borderWidth: 1,
-    borderColor: "rgba(255, 69, 58, 0.3)",
-  },
-  errorText: {
-    color: "#ff453a",
-    fontSize: 14,
-    textAlign: "center",
-  },
-  linkText: {
-    color: "#888",
-    textAlign: "center",
-    fontSize: 14,
-  },
-  linkBold: {
-    color: "#4f8ef7",
-    fontWeight: "600",
-  },
-});

mobile/src/screens/ReaderScreen.tsx

@@ -0,0 +1,133 @@
+import { useEffect, useState, type ReactNode } from "react";
+import {
+  View,
+  Text,
+  TouchableOpacity,
+  ActivityIndicator,
+  StyleSheet,
+} from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import type { RouteProp } from "@react-navigation/native";
+import type { EBookDetail } from "@cloud-reader/shared";
+import { ebooksApi } from "../api/ebooks";
+import { EpubReaderView } from "../components/reader/EpubReaderView";
+import type { AppStackParamList } from "../types";
+
+type ReaderRoute = RouteProp<AppStackParamList, "Reader">;
+
+export default function ReaderScreen({
+  route,
+  navigation,
+}: {
+  route: ReaderRoute;
+  navigation: any;
+}): ReactNode {
+  const { ebookId } = route.params;
+  const [book, setBook] = useState<EBookDetail | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(false);
+
+  useEffect(() => {
+    let active = true;
+    ebooksApi
+      .get(ebookId)
+      .then(({ data }) => {
+        if (active) setBook(data);
+      })
+      .catch(() => {
+        if (active) setError(true);
+      })
+      .finally(() => {
+        if (active) setLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, [ebookId]);
+
+  if (loading) {
+    return (
+      <View style={styles.centered}>
+        <ActivityIndicator size="large" color="#4f8ef7" />
+      </View>
+    );
+  }
+
+  if (error || !book) {
+    return (
+      <SafeAreaView style={styles.centered} edges={["top", "bottom"]}>
+        <Text style={styles.message}>Could not open this book.</Text>
+        <TouchableOpacity
+          style={styles.backButton}
+          onPress={() => navigation.goBack()}
+        >
+          <Text style={styles.backText}>Go back</Text>
+        </TouchableOpacity>
+      </SafeAreaView>
+    );
+  }
+
+  const format = (book.format ?? "").toLowerCase();
+
+  if (format !== "epub") {
+    return (
+      <SafeAreaView style={styles.centered} edges={["top", "bottom"]}>
+        <Text style={styles.placeholderTitle}>PDF reading is coming soon</Text>
+        <Text style={styles.message}>
+          “{book.title}” is a {format.toUpperCase() || "non-EPUB"} file. PDF
+          reading isn&apos;t available on mobile yet — open it in the web reader
+          for now.
+        </Text>
+        <TouchableOpacity
+          style={styles.backButton}
+          onPress={() => navigation.goBack()}
+        >
+          <Text style={styles.backText}>Go back</Text>
+        </TouchableOpacity>
+      </SafeAreaView>
+    );
+  }
+
+  return (
+    <EpubReaderView
+      book={book}
+      ebookId={ebookId}
+      onClose={() => navigation.goBack()}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  centered: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    backgroundColor: "#0f0f23",
+    padding: 24,
+  },
+  placeholderTitle: {
+    fontSize: 20,
+    fontWeight: "700",
+    color: "#fff",
+    marginBottom: 12,
+    textAlign: "center",
+  },
+  message: {
+    fontSize: 15,
+    color: "#aaa",
+    textAlign: "center",
+    lineHeight: 22,
+  },
+  backButton: {
+    marginTop: 24,
+    backgroundColor: "#4f8ef7",
+    borderRadius: 10,
+    paddingHorizontal: 24,
+    paddingVertical: 12,
+  },
+  backText: {
+    color: "#fff",
+    fontSize: 15,
+    fontWeight: "600",
+  },
+});

mobile/src/screens/RegisterScreen.tsx

@@ -1,10 +1,8 @@
 import { useState, type ReactNode } from "react";
 import {
-  View,
   Text,
   TextInput,
   TouchableOpacity,
-  StyleSheet,
   Alert,
   ActivityIndicator,
   KeyboardAvoidingView,
@@ -12,40 +10,39 @@ import {
   ScrollView,
 } from "react-native";
 import { useAuth } from "../context/AuthContext";
-import {
+import { isStrongPassword } from "@cloud-reader/shared";
-  isValidEmail,
+import { authStyles } from "./authStyles";
-  validatePasswordStrength,
+import { AuthFormError } from "./AuthFormError";
-} from "@cloud-reader/shared";
+import { requireValidEmail } from "./authValidation";
 
 export default function RegisterScreen({
   navigation,
 }: {
   navigation: any;
 }): ReactNode {
-  const { state, register, clearError } = useAuth();
+  const { register } = useAuth();
   const [username, setUsername] = useState("");
   const [email, setEmail] = useState("");
   const [password, setPassword] = useState("");
   const [confirmPassword, setConfirmPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
 
   const handleRegister = async () => {
-    clearError();
+    setError(null);
 
     if (!username.trim()) {
       Alert.alert("Validation Error", "Please enter a username.");
       return;
     }
-    if (!email.trim()) {
+    if (!requireValidEmail(email)) {
-      Alert.alert("Validation Error", "Please enter your email.");
       return;
     }
-    if (!isValidEmail(email.trim())) {
+    if (!isStrongPassword(password)) {
-      Alert.alert("Validation Error", "Please enter a valid email address.");
+      Alert.alert(
-      return;
+        "Validation Error",
-    }
+        "Password must be at least 8 characters and include uppercase, lowercase, and a number.",
-    const passwordError = validatePasswordStrength(password);
+      );
-    if (passwordError) {
-      Alert.alert("Validation Error", passwordError);
       return;
     }
     if (password !== confirmPassword) {
@@ -53,30 +50,29 @@ export default function RegisterScreen({
       return;
     }
 
+    setSubmitting(true);
     try {
-      await register(email.trim(), password, username.trim());
+      await register(email.trim(), username.trim(), password);
     } catch {
-      // Error handled in context
+      setError("Could not create the account. Try a different email.");
+    } finally {
+      setSubmitting(false);
     }
   };
 
   return (
     <KeyboardAvoidingView
-      style={styles.container}
+      style={authStyles.container}
       behavior={Platform.OS === "ios" ? "padding" : "height"}
     >
-      <ScrollView contentContainerStyle={styles.inner}>
+      <ScrollView contentContainerStyle={authStyles.innerScroll}>
-        <Text style={styles.title}>Create Account</Text>
+        <Text style={authStyles.titleCompact}>Create Account</Text>
-        <Text style={styles.subtitle}>Join Cloud Reader</Text>
+        <Text style={authStyles.subtitle}>Join Cloud Reader</Text>
 
-        {state.error && (
+        {error ? <AuthFormError message={error} /> : null}
-          <View style={styles.errorBox}>
-            <Text style={styles.errorText}>{state.error}</Text>
-          </View>
-        )}
 
         <TextInput
-          style={styles.input}
+          style={authStyles.input}
           placeholder="Username"
           placeholderTextColor="#666"
           value={username}
@@ -86,7 +82,7 @@ export default function RegisterScreen({
         />
 
         <TextInput
-          style={styles.input}
+          style={authStyles.input}
           placeholder="Email"
           placeholderTextColor="#666"
           value={email}
@@ -97,7 +93,7 @@ export default function RegisterScreen({
         />
 
         <TextInput
-          style={styles.input}
+          style={authStyles.input}
           placeholder="Password"
           placeholderTextColor="#666"
           value={password}
@@ -106,7 +102,7 @@ export default function RegisterScreen({
         />
 
         <TextInput
-          style={styles.input}
+          style={authStyles.input}
           placeholder="Confirm Password"
           placeholderTextColor="#666"
           value={confirmPassword}
@@ -115,98 +111,24 @@ export default function RegisterScreen({
         />
 
         <TouchableOpacity
-          style={[styles.button, state.isLoading && styles.buttonDisabled]}
+          style={[authStyles.button, submitting && authStyles.buttonDisabled]}
           onPress={handleRegister}
-          disabled={state.isLoading}
+          disabled={submitting}
         >
-          {state.isLoading ? (
+          {submitting ? (
             <ActivityIndicator color="#fff" />
           ) : (
-            <Text style={styles.buttonText}>Create Account</Text>
+            <Text style={authStyles.buttonText}>Create Account</Text>
           )}
         </TouchableOpacity>
 
         <TouchableOpacity onPress={() => navigation.goBack()}>
-          <Text style={styles.linkText}>
+          <Text style={authStyles.linkText}>
             Already have an account?{" "}
-            <Text style={styles.linkBold}>Sign In</Text>
+            <Text style={authStyles.linkBold}>Sign In</Text>
           </Text>
         </TouchableOpacity>
       </ScrollView>
     </KeyboardAvoidingView>
   );
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: "#0f0f23",
-  },
-  inner: {
-    flexGrow: 1,
-    justifyContent: "center",
-    paddingHorizontal: 24,
-    paddingVertical: 48,
-  },
-  title: {
-    fontSize: 28,
-    fontWeight: "bold",
-    color: "#fff",
-    textAlign: "center",
-    marginBottom: 8,
-  },
-  subtitle: {
-    fontSize: 16,
-    color: "#888",
-    textAlign: "center",
-    marginBottom: 32,
-  },
-  input: {
-    backgroundColor: "#1a1a2e",
-    borderRadius: 8,
-    padding: 16,
-    fontSize: 16,
-    color: "#fff",
-    marginBottom: 12,
-    borderWidth: 1,
-    borderColor: "#333",
-  },
-  button: {
-    backgroundColor: "#4f8ef7",
-    borderRadius: 8,
-    padding: 16,
-    alignItems: "center",
-    marginTop: 8,
-    marginBottom: 24,
-  },
-  buttonDisabled: {
-    opacity: 0.6,
-  },
-  buttonText: {
-    color: "#fff",
-    fontSize: 16,
-    fontWeight: "600",
-  },
-  errorBox: {
-    backgroundColor: "rgba(255, 69, 58, 0.15)",
-    borderRadius: 8,
-    padding: 12,
-    marginBottom: 16,
-    borderWidth: 1,
-    borderColor: "rgba(255, 69, 58, 0.3)",
-  },
-  errorText: {
-    color: "#ff453a",
-    fontSize: 14,
-    textAlign: "center",
-  },
-  linkText: {
-    color: "#888",
-    textAlign: "center",
-    fontSize: 14,
-  },
-  linkBold: {
-    color: "#4f8ef7",
-    fontWeight: "600",
-  },
-});

mobile/src/screens/SettingsScreen.tsx

@@ -9,7 +9,7 @@ import {
 import { useAuth } from "../context/AuthContext";
 
 export default function SettingsScreen(): ReactNode {
-  const { state, logout } = useAuth();
+  const { user, logout } = useAuth();
 
   const handleLogout = () => {
     Alert.alert("Logout", "Are you sure you want to sign out?", [
@@ -24,11 +24,11 @@ export default function SettingsScreen(): ReactNode {
         <Text style={styles.sectionTitle}>Account</Text>
         <View style={styles.infoRow}>
           <Text style={styles.label}>Username</Text>
-          <Text style={styles.value}>{state.user?.username ?? "—"}</Text>
+          <Text style={styles.value}>{user?.username ?? "—"}</Text>
         </View>
         <View style={styles.infoRow}>
           <Text style={styles.label}>Email</Text>
-          <Text style={styles.value}>{state.user?.email ?? "—"}</Text>
+          <Text style={styles.value}>{user?.email ?? "—"}</Text>
         </View>
       </View>
 

mobile/src/screens/authStyles.ts

@@ -0,0 +1,88 @@
+import { StyleSheet } from "react-native";
+
+/** Shared layout/styles for Login and Register screens. */
+export const authStyles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: "#0f0f23",
+  },
+  inner: {
+    flex: 1,
+    justifyContent: "center",
+    paddingHorizontal: 24,
+  },
+  innerScroll: {
+    flexGrow: 1,
+    justifyContent: "center",
+    paddingHorizontal: 24,
+    paddingVertical: 48,
+  },
+  title: {
+    fontSize: 32,
+    fontWeight: "bold",
+    color: "#fff",
+    textAlign: "center",
+    marginBottom: 8,
+  },
+  titleCompact: {
+    fontSize: 28,
+    fontWeight: "bold",
+    color: "#fff",
+    textAlign: "center",
+    marginBottom: 8,
+  },
+  subtitle: {
+    fontSize: 16,
+    color: "#888",
+    textAlign: "center",
+    marginBottom: 32,
+  },
+  input: {
+    backgroundColor: "#1a1a2e",
+    borderRadius: 8,
+    padding: 16,
+    fontSize: 16,
+    color: "#fff",
+    marginBottom: 12,
+    borderWidth: 1,
+    borderColor: "#333",
+  },
+  button: {
+    backgroundColor: "#4f8ef7",
+    borderRadius: 8,
+    padding: 16,
+    alignItems: "center",
+    marginTop: 8,
+    marginBottom: 24,
+  },
+  buttonDisabled: {
+    opacity: 0.6,
+  },
+  buttonText: {
+    color: "#fff",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  errorBox: {
+    backgroundColor: "rgba(255, 69, 58, 0.15)",
+    borderRadius: 8,
+    padding: 12,
+    marginBottom: 16,
+    borderWidth: 1,
+    borderColor: "rgba(255, 69, 58, 0.3)",
+  },
+  errorText: {
+    color: "#ff453a",
+    fontSize: 14,
+    textAlign: "center",
+  },
+  linkText: {
+    color: "#888",
+    textAlign: "center",
+    fontSize: 14,
+  },
+  linkBold: {
+    color: "#4f8ef7",
+    fontWeight: "600",
+  },
+});

mobile/src/screens/authValidation.ts

@@ -0,0 +1,15 @@
+import { Alert } from "react-native";
+import { isValidEmail } from "@cloud-reader/shared";
+
+/** Returns true when email is non-empty and well-formed. */
+export function requireValidEmail(email: string): boolean {
+  if (!email.trim()) {
+    Alert.alert("Validation Error", "Please enter your email.");
+    return false;
+  }
+  if (!isValidEmail(email.trim())) {
+    Alert.alert("Validation Error", "Please enter a valid email address.");
+    return false;
+  }
+  return true;
+}

mobile/src/types/index.ts

@@ -1,8 +1,37 @@
 // Mobile-specific type aliases and extensions not covered by shared types
 
-export type RootStackParamList = {
+import type { NavigatorScreenParams } from "@react-navigation/native";
-  Auth: undefined;
+import type { MainTabParamList } from "../navigation/MainNavigator";
-  Main: undefined;
+
-  BookReader: { bookId: number };
+/** Stack hosted above the bottom tabs once the user is authenticated. */
-  BookDetail: { bookId: number };
+export type AppStackParamList = {
-};
+  Tabs: NavigatorScreenParams<MainTabParamList> | undefined;
+  BookDetail: { ebookId: number };
+  Reader: { ebookId: number };
+};
+
+/** EPUB bookmark/highlight, mirrors frontend/src/types Bookmark. */
+export interface Bookmark {
+  id: string;
+  ebook: number;
+  ebook_title: string;
+  epub_cfi: string;
+  chapter_index: number;
+  chapter_title: string;
+  page: number;
+  location_text: string;
+  content: string;
+  highlight_color?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateMarkerPayload {
+  ebook: number;
+  epub_cfi: string;
+  chapter_index: number;
+  chapter_title?: string;
+  location_text?: string;
+  content?: string;
+  highlight_color?: string;
+}

mobile/src/types/reader.ts

@@ -0,0 +1,32 @@
+/**
+ * Reader module types for the mobile app. Mirrors
+ * frontend/src/types/reader.ts so settings and progress behave the same
+ * way across web and mobile.
+ */
+
+export interface ReadingSettings {
+  font_family: "sans-serif" | "serif" | "monospace";
+  font_size: number;
+  line_height: number;
+  margin_width: number;
+  background_color: string;
+  text_color: string;
+  brightness: number;
+  orientation_lock: "auto" | "portrait" | "landscape";
+  theme: "sepia" | "dark" | "light" | "paper";
+  created_at: string;
+  updated_at: string;
+}
+
+export type ThemePreset = ReadingSettings["theme"];
+export type FontFamily = ReadingSettings["font_family"];
+
+export interface ReadingProgress {
+  id: number;
+  book: number;
+  current_chapter: number;
+  current_position: number;
+  percentage: number;
+  epub_location: string;
+  updated_at: string;
+}

mobile/src/utils/epubTheme.ts

@@ -0,0 +1,66 @@
+import type { ReadingSettings, ThemePreset } from "../types/reader";
+
+/** CSS font stacks per family, mirrors frontend/src/utils/epubRendition.ts. */
+export const FONT_STACKS: Record<ReadingSettings["font_family"], string> = {
+  serif: 'Georgia, "Times New Roman", serif',
+  "sans-serif":
+    'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+  monospace: 'ui-monospace, "Cascadia Code", monospace',
+};
+
+/** Background/text/chrome colors for each reader theme preset. */
+export const THEME_PALETTES: Record<
+  ThemePreset,
+  { background: string; text: string; chrome: string }
+> = {
+  light: { background: "#ffffff", text: "#1a1a1a", chrome: "#f2f2f2" },
+  dark: { background: "#121212", text: "#e0e0e0", chrome: "#1c1c1e" },
+  sepia: { background: "#f4ecd8", text: "#5b4636", chrome: "#e8ddc4" },
+  paper: { background: "#fbfbf8", text: "#2b2b2b", chrome: "#efefe9" },
+};
+
+export function resolvePalette(settings: ReadingSettings) {
+  const preset = THEME_PALETTES[settings.theme] ?? THEME_PALETTES.light;
+  return {
+    background: settings.background_color || preset.background,
+    text: settings.text_color || preset.text,
+    chrome: preset.chrome,
+  };
+}
+
+/**
+ * Build an epub.js theme object (selector -> CSS rules) from reader settings.
+ * Used with the epubjs-react-native `changeTheme` method.
+ */
+export function buildEpubTheme(
+  settings: ReadingSettings,
+): Record<string, Record<string, string>> {
+  const { background, text } = resolvePalette(settings);
+  const fontStack = FONT_STACKS[settings.font_family] ?? FONT_STACKS.serif;
+  const lineHeight = `${settings.line_height} !important`;
+  const fontFamily = `${fontStack} !important`;
+  const color = `${text} !important`;
+
+  return {
+    body: {
+      background: `${background} !important`,
+      color,
+      "font-family": fontFamily,
+      "line-height": lineHeight,
+    },
+    p: {
+      color,
+      "font-family": fontFamily,
+      "line-height": lineHeight,
+    },
+    li: { color, "font-family": fontFamily, "line-height": lineHeight },
+    span: { color },
+    a: { color },
+    h1: { color },
+    h2: { color },
+    h3: { color },
+    h4: { color },
+    h5: { color },
+    h6: { color },
+  };
+}

mobile/tsconfig.json

@@ -12,7 +12,8 @@
     "forceConsistentCasingInFileNames": true,
     "baseUrl": ".",
     "paths": {
-      "@/*": ["src/*"]
+      "@/*": ["src/*"],
+      "@cloud-reader/shared": ["../packages/shared/src/index.ts"]
     }
   },
   "include": ["**/*.ts", "**/*.tsx"],

packages/shared/src/types.ts

@@ -215,4 +215,48 @@ export interface PaginatedResponse<T> {
 export interface ApiError {
   detail?: string;
   [key: string]: unknown;
+}
+
+// ---- Reading Groups ----
+
+export interface ReadingGroup {
+  id: number;
+  name: string;
+  description: string;
+  admin: number;
+  admin_email: string;
+  member_count: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface GroupMembership {
+  id: number;
+  user: number;
+  user_email: string;
+  user_username: string;
+  role: "admin" | "member";
+  joined_at: string;
+}
+
+export interface GroupBookSummary {
+  id: number;
+  title: string;
+  status: "active" | "replaced";
+  section_count: number;
+  created_at: string;
+}
+
+export interface SectionSummary {
+  id: number;
+  title: string;
+  order: number;
+  estimated_reading_minutes: number;
+}
+
+export interface ReadingScheduleEntry {
+  id: number;
+  meeting_number: number;
+  week_date: string;
+  section_ids: number[];
 }

packages/shared/src/utils.ts

@@ -114,4 +114,14 @@ export const API_ENDPOINTS = {
     bookmarkDetail: (id: string) => `/api/annotations/bookmarks/${id}/`,
     noteDetail: (id: string) => `/api/annotations/notes/${id}/`,
   },
+  groups: {
+    list: "/api/groups/",
+    detail: (id: number) => `/api/groups/${id}/`,
+    books: (groupId: number) => `/api/groups/${groupId}/books/`,
+    bookDetail: (groupId: number, bookId: number) => `/api/groups/${groupId}/books/${bookId}/`,
+    detectSections: (groupId: number, bookId: number) => `/api/groups/${groupId}/books/${bookId}/detect-sections/`,
+    adjustSections: (groupId: number, bookId: number) => `/api/groups/${groupId}/books/${bookId}/adjust-sections/`,
+    schedule: (groupId: number, bookId: number) => `/api/groups/${groupId}/books/${bookId}/schedule/`,
+    progress: (groupId: number, bookId: number) => `/api/groups/${groupId}/books/${bookId}/progress/`,
+  },
 } as const;