feat: implement group creation and management (US #28)

Backend:
- Add groups Django app with models: Group, GroupMember, GroupInvite, JoinRequest
- Create serializers with business rule validation
- Implement GroupViewSet with full CRUD + custom actions (members, invites, roles, leave, join requests)
- Add JoinGroupViewSet for invite-based joining flow
- Register app in Django config and URL routing

Frontend:
- Add shared types for groups to @cloud-reader/shared
- Create groups API client (groupsApi)
- Build GroupsListPage, GroupDetailPage (member mgmt, invites, role transfer)
- Build CreateGroupPage and JoinGroupPage
- Add lazy-loaded routes to App.tsx with ProtectedRoute
- Add navigation links to Library header

Ref: #28

.gitignore

@@ -1,4 +1,29 @@
 node_modules
+dist
+frontend/dist
+frontend/dist/assets
+frontend/dist/assets/index.html
+frontend/dist/assets/index.html.gz
+frontend/dist/assets/index.html.br
+frontend/dist/assets/index.html.brotli
+frontend/dist/assets/index.html.gzip
+frontend/dist/assets/index.html.br
+frontend/dist/assets/index.html.brotli
+frontend/dist/assets/index.html.gzip
+frontend/dist/assets/index.html.br
+frontend/dist/assets/index.html.brotli
+frontend/dist/assets/index.html.gzip
+frontend/dist/assets/index.html.br
+frontend/dist/assets/index.html.brotli
+frontend/dist/assets/index.html.gzip
+frontend/dist/assets/index.html.br
+frontend/dist/assets/index.html.brotli
+frontend/dist/assets/index.html.gzip
+mobile/dist
+backend/media
+backend/staticfiles
+backend/media
+backend/staticfiles
 .pycache__
 __pycache__
 *.pyc

backend/apps/groups/admin.py

@@ -0,0 +1,30 @@
+from django.contrib import admin
+
+from apps.groups.models import Group, GroupInvite, GroupMember, JoinRequest
+
+
+@admin.register(Group)
+class GroupAdmin(admin.ModelAdmin):
+    list_display = ["id", "name", "created_by", "created_at"]
+    search_fields = ["name", "created_by__email"]
+
+
+@admin.register(GroupMember)
+class GroupMemberAdmin(admin.ModelAdmin):
+    list_display = ["id", "group", "user", "role", "joined_at"]
+    list_filter = ["role"]
+    search_fields = ["group__name", "user__email"]
+
+
+@admin.register(GroupInvite)
+class GroupInviteAdmin(admin.ModelAdmin):
+    list_display = ["id", "group", "code", "created_by", "use_count", "is_active", "created_at"]
+    list_filter = ["is_active"]
+    search_fields = ["code", "group__name"]
+
+
+@admin.register(JoinRequest)
+class JoinRequestAdmin(admin.ModelAdmin):
+    list_display = ["id", "group", "user", "status", "created_at"]
+    list_filter = ["status"]
+    search_fields = ["group__name", "user__email"]

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 = "Groups"

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

@@ -0,0 +1,88 @@
+# Generated by Django 5.x for groups app
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+import uuid
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Group",
+            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)),
+                ("created_by", models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name="created_groups", to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                "db_table": "groups_group",
+                "verbose_name": "Group",
+                "verbose_name_plural": "Groups",
+                "ordering": ["-created_at"],
+            },
+        ),
+        migrations.CreateModel(
+            name="GroupMember",
+            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.group")),
+                ("user", models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name="group_memberships", to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                "db_table": "groups_member",
+                "verbose_name": "Group Member",
+                "verbose_name_plural": "Group Members",
+                "ordering": ["joined_at"],
+                "unique_together": {("group", "user")},
+            },
+        ),
+        migrations.CreateModel(
+            name="GroupInvite",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("code", models.UUIDField(db_index=True, default=uuid.uuid4, editable=False, unique=True)),
+                ("max_uses", models.PositiveIntegerField(default=0, help_text="0 = unlimited")),
+                ("use_count", models.PositiveIntegerField(default=0)),
+                ("is_active", models.BooleanField(db_index=True, default=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("created_by", models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name="created_invites", to=settings.AUTH_USER_MODEL)),
+                ("group", models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name="invites", to="groups.group")),
+            ],
+            options={
+                "db_table": "groups_invite",
+                "verbose_name": "Group Invite",
+                "verbose_name_plural": "Group Invites",
+                "ordering": ["-created_at"],
+            },
+        ),
+        migrations.CreateModel(
+            name="JoinRequest",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("status", models.CharField(choices=[("pending", "Pending"), ("approved", "Approved"), ("rejected", "Rejected")], db_index=True, default="pending", max_length=16)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("group", models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name="join_requests", to="groups.group")),
+                ("invite", models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name="join_requests", to="groups.groupinvite")),
+                ("user", models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name="join_requests", to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                "db_table": "groups_join_request",
+                "verbose_name": "Join Request",
+                "verbose_name_plural": "Join Requests",
+                "ordering": ["-created_at"],
+                "unique_together": {("group", "user")},
+            },
+        ),
+    ]

backend/apps/groups/models.py

@@ -0,0 +1,129 @@
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+
+class GroupRole(models.TextChoices):
+    ADMIN = "admin", "Admin"
+    MEMBER = "member", "Member"
+
+
+class JoinRequestStatus(models.TextChoices):
+    PENDING = "pending", "Pending"
+    APPROVED = "approved", "Approved"
+    REJECTED = "rejected", "Rejected"
+
+
+class Group(models.Model):
+    name = models.CharField(max_length=256, db_index=True)
+    description = models.TextField(blank=True, default="")
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="created_groups",
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "groups_group"
+        verbose_name = "Group"
+        verbose_name_plural = "Groups"
+        ordering = ["-created_at"]
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class GroupMember(models.Model):
+    group = models.ForeignKey(
+        Group,
+        on_delete=models.CASCADE,
+        related_name="memberships",
+    )
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="group_memberships",
+    )
+    role = models.CharField(
+        max_length=16,
+        choices=GroupRole.choices,
+        default=GroupRole.MEMBER,
+    )
+    joined_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "groups_member"
+        verbose_name = "Group Member"
+        verbose_name_plural = "Group Members"
+        ordering = ["joined_at"]
+        unique_together = [("group", "user")]
+
+    def __str__(self) -> str:
+        return f"{self.user} in {self.group} ({self.role})"
+
+
+class GroupInvite(models.Model):
+    group = models.ForeignKey(
+        Group,
+        on_delete=models.CASCADE,
+        related_name="invites",
+    )
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="created_invites",
+    )
+    code = models.UUIDField(default=uuid.uuid4, unique=True, editable=False, db_index=True)
+    max_uses = models.PositiveIntegerField(default=0, help_text="0 = unlimited")
+    use_count = models.PositiveIntegerField(default=0)
+    is_active = models.BooleanField(default=True, db_index=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "groups_invite"
+        verbose_name = "Group Invite"
+        verbose_name_plural = "Group Invites"
+        ordering = ["-created_at"]
+
+    def __str__(self) -> str:
+        return f"Invite for {self.group.name} ({self.code})"
+
+
+class JoinRequest(models.Model):
+    group = models.ForeignKey(
+        Group,
+        on_delete=models.CASCADE,
+        related_name="join_requests",
+    )
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="join_requests",
+    )
+    invite = models.ForeignKey(
+        GroupInvite,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="join_requests",
+    )
+    status = models.CharField(
+        max_length=16,
+        choices=JoinRequestStatus.choices,
+        default=JoinRequestStatus.PENDING,
+        db_index=True,
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "groups_join_request"
+        verbose_name = "Join Request"
+        verbose_name_plural = "Join Requests"
+        ordering = ["-created_at"]
+        unique_together = [("group", "user")]
+
+    def __str__(self) -> str:
+        return f"{self.user} → {self.group.name} ({self.status})"

backend/apps/groups/permissions.py

@@ -0,0 +1,25 @@
+from rest_framework import permissions
+from rest_framework.request import Request
+
+from apps.groups.models import Group, GroupMember, GroupRole
+
+
+class IsGroupAdmin(permissions.BasePermission):
+    """Only group admins can perform the action."""
+
+    def has_object_permission(self, request: Request, view: object, obj: Group) -> bool:
+        return GroupMember.objects.filter(
+            group=obj,
+            user=request.user,
+            role=GroupRole.ADMIN,
+        ).exists()
+
+
+class IsGroupMember(permissions.BasePermission):
+    """Only group members (any role) can perform the action."""
+
+    def has_object_permission(self, request: Request, view: object, obj: Group) -> bool:
+        return GroupMember.objects.filter(
+            group=obj,
+            user=request.user,
+        ).exists()

backend/apps/groups/serializers.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from rest_framework import serializers
+
+from apps.groups.models import Group, GroupInvite, GroupMember, GroupRole, JoinRequest, JoinRequestStatus
+
+
+class GroupMemberSerializer(serializers.ModelSerializer):
+    user_id = serializers.IntegerField(source="user.id", read_only=True)
+    user_email = serializers.CharField(source="user.email", read_only=True)
+    user_username = serializers.CharField(source="user.username", read_only=True)
+
+    class Meta:
+        model = GroupMember
+        fields = [
+            "id", "user_id", "user_email", "user_username",
+            "role", "joined_at",
+        ]
+
+
+class GroupListSerializer(serializers.ModelSerializer):
+    member_count = serializers.SerializerMethodField()
+    user_role = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Group
+        fields = [
+            "id", "name", "description", "created_by",
+            "member_count", "user_role", "created_at", "updated_at",
+        ]
+
+    def get_member_count(self, obj: Group) -> int:
+        return getattr(obj, "_member_count", obj.memberships.count())
+
+    def get_user_role(self, obj: Group) -> str | None:
+        request = self.context.get("request")
+        if not request or not request.user.is_authenticated:
+            return None
+        membership = getattr(obj, "_user_membership", None)
+        if membership is None:
+            try:
+                membership = obj.memberships.get(user=request.user)
+            except GroupMember.DoesNotExist:
+                return None
+        return membership.role
+
+
+class GroupDetailSerializer(serializers.ModelSerializer):
+    members = GroupMemberSerializer(source="memberships", many=True, read_only=True)
+    member_count = serializers.SerializerMethodField()
+    user_role = serializers.SerializerMethodField()
+    created_by_email = serializers.CharField(source="created_by.email", read_only=True)
+    created_by_username = serializers.CharField(source="created_by.username", read_only=True)
+
+    class Meta:
+        model = Group
+        fields = [
+            "id", "name", "description", "created_by", "created_by_email",
+            "created_by_username", "members", "member_count", "user_role",
+            "created_at", "updated_at",
+        ]
+
+    def get_member_count(self, obj: Group) -> int:
+        return getattr(obj, "_member_count", obj.memberships.count())
+
+    def get_user_role(self, obj: Group) -> str | None:
+        request = self.context.get("request")
+        if not request or not request.user.is_authenticated:
+            return None
+        membership = getattr(obj, "_user_membership", None)
+        if membership is None:
+            try:
+                membership = obj.memberships.get(user=request.user)
+            except GroupMember.DoesNotExist:
+                return None
+        return membership.role
+
+
+class GroupCreateSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Group
+        fields = ["name", "description"]
+
+    def validate_name(self, value: str) -> str:
+        if not value.strip():
+            raise serializers.ValidationError("Group name cannot be empty.")
+        if len(value.strip()) < 2:
+            raise serializers.ValidationError("Group name must be at least 2 characters.")
+        return value.strip()
+
+    def create(self, validated_data: dict) -> Group:
+        user = self.context["request"].user
+        group = Group.objects.create(created_by=user, **validated_data)
+        GroupMember.objects.create(group=group, user=user, role=GroupRole.ADMIN)
+        return group
+
+
+class GroupUpdateSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Group
+        fields = ["name", "description"]
+
+    def validate_name(self, value: str) -> str:
+        if not value.strip():
+            raise serializers.ValidationError("Group name cannot be empty.")
+        if len(value.strip()) < 2:
+            raise serializers.ValidationError("Group name must be at least 2 characters.")
+        return value.strip()
+
+
+class GroupInviteSerializer(serializers.ModelSerializer):
+    created_by_email = serializers.CharField(source="created_by.email", read_only=True)
+    group_name = serializers.CharField(source="group.name", read_only=True)
+    join_url = serializers.SerializerMethodField()
+
+    class Meta:
+        model = GroupInvite
+        fields = [
+            "id", "group", "group_name", "code", "created_by", "created_by_email",
+            "max_uses", "use_count", "is_active", "join_url", "created_at",
+        ]
+        read_only_fields = ["id", "group", "code", "created_by", "use_count", "created_at"]
+
+    def get_join_url(self, obj: GroupInvite) -> str:
+        request = self.context.get("request")
+        if request:
+            return f"{request.build_absolute_uri('/')[:-1]}/groups/join/{obj.code}"
+        return f"/groups/join/{obj.code}"
+
+
+class GroupInviteCreateSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = GroupInvite
+        fields = ["max_uses"]
+
+    def validate_max_uses(self, value: int) -> int:
+        if value < 0:
+            raise serializers.ValidationError("Max uses cannot be negative.")
+        return value
+
+    def create(self, validated_data: dict) -> GroupInvite:
+        group = self.context["group"]
+        user = self.context["request"].user
+        return GroupInvite.objects.create(
+            group=group,
+            created_by=user,
+            **validated_data,
+        )
+
+
+class JoinRequestSerializer(serializers.ModelSerializer):
+    user_id = serializers.IntegerField(source="user.id", read_only=True)
+    user_email = serializers.CharField(source="user.email", read_only=True)
+    user_username = serializers.CharField(source="user.username", read_only=True)
+    group_name = serializers.CharField(source="group.name", read_only=True)
+    invite_code = serializers.UUIDField(source="invite.code", read_only=True, default=None)
+
+    class Meta:
+        model = JoinRequest
+        fields = [
+            "id", "group", "group_name", "user", "user_id", "user_email",
+            "user_username", "invite", "invite_code", "status", "created_at",
+        ]
+        read_only_fields = ["id", "group", "user", "invite", "created_at"]
+
+
+class JoinViaInviteSerializer(serializers.Serializer):
+    """Validates and processes joining a group via an invite code."""
+
+    code = serializers.UUIDField()
+
+    def validate_code(self, value: str) -> str:
+        try:
+            invite = GroupInvite.objects.select_related("group").get(code=value)
+        except GroupInvite.DoesNotExist:
+            raise serializers.ValidationError("Invalid invite code.")
+
+        if not invite.is_active:
+            raise serializers.ValidationError("This invite is no longer active.")
+
+        if invite.max_uses > 0 and invite.use_count >= invite.max_uses:
+            raise serializers.ValidationError("This invite has reached its maximum uses.")
+
+        return value
+
+
+class RoleUpdateSerializer(serializers.Serializer):
+    role = serializers.ChoiceField(choices=GroupRole.choices)
+
+    def validate_role(self, value: str) -> str:
+        if value == GroupRole.MEMBER:
+            group = self.context["group"]
+            admin_count = group.memberships.filter(role=GroupRole.ADMIN).count()
+            if admin_count <= 1:
+                raise serializers.ValidationError(
+                    "Cannot remove the last admin. Transfer admin role first or dissolve the group."
+                )
+        return value

backend/apps/groups/urls.py

@@ -0,0 +1,12 @@
+from django.urls import include, path
+from rest_framework.routers import DefaultRouter
+
+from apps.groups.views import GroupViewSet, JoinGroupViewSet
+
+router = DefaultRouter()
+router.register(r"groups", GroupViewSet, basename="group")
+router.register(r"join", JoinGroupViewSet, basename="join-group")
+
+urlpatterns = [
+    path("", include(router.urls)),
+]

backend/apps/groups/views.py

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+from django.db.models import Count, Prefetch, QuerySet
+from rest_framework import status, viewsets
+from rest_framework.decorators import action
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from apps.groups.models import Group, GroupInvite, GroupMember, GroupRole, JoinRequest, JoinRequestStatus
+from apps.groups.permissions import IsGroupAdmin, IsGroupMember
+from apps.groups.serializers import (
+    GroupCreateSerializer,
+    GroupDetailSerializer,
+    GroupInviteCreateSerializer,
+    GroupInviteSerializer,
+    GroupListSerializer,
+    GroupMemberSerializer,
+    GroupUpdateSerializer,
+    JoinRequestSerializer,
+    JoinViaInviteSerializer,
+    RoleUpdateSerializer,
+)
+
+
+class GroupViewSet(viewsets.ModelViewSet):
+    permission_classes = [IsAuthenticated]
+
+    def get_serializer_class(self):
+        if self.action == "create":
+            return GroupCreateSerializer
+        if self.action in ("update", "partial_update"):
+            return GroupUpdateSerializer
+        if self.action == "retrieve":
+            return GroupDetailSerializer
+        return GroupListSerializer
+
+    def get_queryset(self) -> QuerySet[Group]:
+        user = self.request.user
+        qs = Group.objects.filter(memberships__user=user).distinct()
+        qs = qs.annotate(_member_count=Count("memberships"))
+        if self.action in ("list", "retrieve"):
+            qs = qs.prefetch_related(
+                Prefetch(
+                    "memberships",
+                    queryset=GroupMember.objects.select_related("user").order_by("joined_at"),
+                )
+            )
+        return qs
+
+    def get_object(self) -> Group:
+        obj = super().get_object()
+        # Cache the requesting user's membership for serializers
+        try:
+            obj._user_membership = obj.memberships.get(user=self.request.user)
+        except GroupMember.DoesNotExist:
+            obj._user_membership = None
+        return obj
+
+    def perform_create(self, serializer: GroupCreateSerializer) -> Group:
+        return serializer.save()
+
+    def perform_destroy(self, instance: Group) -> None:
+        # Only admin can delete/dissolve the group
+        if not GroupMember.objects.filter(
+            group=instance, user=self.request.user, role=GroupRole.ADMIN
+        ).exists():
+            from rest_framework.exceptions import PermissionDenied
+
+            raise PermissionDenied("Only group admins can delete the group.")
+        instance.delete()
+
+    # ---- Members ----
+
+    @action(detail=True, methods=["get"], permission_classes=[IsAuthenticated, IsGroupMember])
+    def members(self, request: Request, pk: str | None = None) -> Response:
+        """List all members of the group."""
+        group = self.get_object()
+        memberships = group.memberships.select_related("user").order_by("joined_at")
+        serializer = GroupMemberSerializer(memberships, many=True)
+        return Response(serializer.data)
+
+    @action(
+        detail=True,
+        methods=["delete"],
+        url_path="members/(?P<user_id>[^/.]+)",
+        permission_classes=[IsAuthenticated, IsGroupAdmin],
+    )
+    def remove_member(self, request: Request, pk: str | None = None, user_id: str | None = None) -> Response:
+        """Admin removes a member from the group."""
+        group = self.get_object()
+        try:
+            membership = GroupMember.objects.get(group=group, user_id=user_id)
+        except GroupMember.DoesNotExist:
+            return Response({"error": "Member not found."}, status=status.HTTP_404_NOT_FOUND)
+
+        if membership.user == request.user:
+            return Response(
+                {"error": "Admins cannot remove themselves. Use leave instead, or transfer admin first."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        membership.delete()
+        return Response(status=status.HTTP_204_NO_CONTENT)
+
+    @action(
+        detail=True,
+        methods=["patch"],
+        url_path="members/(?P<user_id>[^/.]+)/role",
+        permission_classes=[IsAuthenticated, IsGroupAdmin],
+    )
+    def update_member_role(self, request: Request, pk: str | None = None, user_id: str | None = None) -> Response:
+        """Admin transfers admin role or changes member role."""
+        group = self.get_object()
+        serializer = RoleUpdateSerializer(data=request.data, context={"group": group})
+        serializer.is_valid(raise_exception=True)
+
+        try:
+            membership = GroupMember.objects.get(group=group, user_id=user_id)
+        except GroupMember.DoesNotExist:
+            return Response({"error": "Member not found."}, status=status.HTTP_404_NOT_FOUND)
+
+        membership.role = serializer.validated_data["role"]
+        membership.save(update_fields=["role"])
+
+        if serializer.validated_data["role"] == GroupRole.ADMIN and membership.user != request.user:
+            # Downgrade the current admin to member
+            GroupMember.objects.filter(group=group, user=request.user).update(role=GroupRole.MEMBER)
+
+        return Response(GroupMemberSerializer(membership).data)
+
+    @action(detail=True, methods=["post"], permission_classes=[IsAuthenticated, IsGroupMember])
+    def leave(self, request: Request, pk: str | None = None) -> Response:
+        """Member leaves the group. If admin is last admin, dissolve the group."""
+        group = self.get_object()
+        membership = GroupMember.objects.filter(group=group, user=request.user).first()
+
+        if not membership:
+            return Response({"error": "You are not a member of this group."}, status=status.HTTP_400_BAD_REQUEST)
+
+        if membership.role == GroupRole.ADMIN:
+            admin_count = GroupMember.objects.filter(group=group, role=GroupRole.ADMIN).count()
+            if admin_count <= 1:
+                # Last admin leaving — dissolve the group
+                group.delete()
+                return Response({"detail": "You were the last admin. The group has been dissolved."})
+
+        membership.delete()
+        return Response({"detail": "You have left the group."})
+
+    # ---- Invites ----
+
+    @action(detail=True, methods=["get", "post"], permission_classes=[IsAuthenticated, IsGroupAdmin])
+    def invites(self, request: Request, pk: str | None = None) -> Response:
+        """List or create invites for the group."""
+        group = self.get_object()
+
+        if request.method == "GET":
+            invites_qs = group.invites.select_related("created_by").order_by("-created_at")
+            serializer = GroupInviteSerializer(invites_qs, many=True, context={"request": request})
+            return Response(serializer.data)
+
+        serializer = GroupInviteCreateSerializer(
+            data=request.data,
+            context={"group": group, "request": request},
+        )
+        serializer.is_valid(raise_exception=True)
+        invite = serializer.save()
+        return Response(
+            GroupInviteSerializer(invite, context={"request": request}).data,
+            status=status.HTTP_201_CREATED,
+        )
+
+    @action(
+        detail=True,
+        methods=["delete"],
+        url_path="invites/(?P<invite_id>[^/.]+)",
+        permission_classes=[IsAuthenticated, IsGroupAdmin],
+    )
+    def revoke_invite(self, request: Request, pk: str | None = None, invite_id: str | None = None) -> Response:
+        """Revoke an invite by deactivating it."""
+        group = self.get_object()
+        try:
+            invite = GroupInvite.objects.get(id=invite_id, group=group)
+        except GroupInvite.DoesNotExist:
+            return Response({"error": "Invite not found."}, status=status.HTTP_404_NOT_FOUND)
+
+        invite.is_active = False
+        invite.save(update_fields=["is_active"])
+        return Response(status=status.HTTP_204_NO_CONTENT)
+
+    # ---- Join Requests ----
+
+    @action(detail=True, methods=["get"], permission_classes=[IsAuthenticated, IsGroupAdmin])
+    def requests(self, request: Request, pk: str | None = None) -> Response:
+        """List pending join requests for the group (admin only)."""
+        group = self.get_object()
+        join_requests = group.join_requests.select_related("user", "invite").order_by("-created_at")
+        serializer = JoinRequestSerializer(join_requests, many=True)
+        return Response(serializer.data)
+
+    @action(
+        detail=True,
+        methods=["post"],
+        url_path="requests/(?P<request_id>[^/.]+)/approve",
+        permission_classes=[IsAuthenticated, IsGroupAdmin],
+    )
+    def approve_request(self, request: Request, pk: str | None = None, request_id: str | None = None) -> Response:
+        """Approve a pending join request."""
+        group = self.get_object()
+        try:
+            join_request = JoinRequest.objects.get(id=request_id, group=group, status=JoinRequestStatus.PENDING)
+        except JoinRequest.DoesNotExist:
+            return Response({"error": "Pending join request not found."}, status=status.HTTP_404_NOT_FOUND)
+
+        join_request.status = JoinRequestStatus.APPROVED
+        join_request.save(update_fields=["status"])
+
+        GroupMember.objects.get_or_create(
+            group=group,
+            user=join_request.user,
+            defaults={"role": GroupRole.MEMBER},
+        )
+
+        # Increment invite use count
+        if join_request.invite:
+            join_request.invite.use_count += 1
+            join_request.invite.save(update_fields=["use_count"])
+
+        return Response(JoinRequestSerializer(join_request).data)
+
+    @action(
+        detail=True,
+        methods=["post"],
+        url_path="requests/(?P<request_id>[^/.]+)/reject",
+        permission_classes=[IsAuthenticated, IsGroupAdmin],
+    )
+    def reject_request(self, request: Request, pk: str | None = None, request_id: str | None = None) -> Response:
+        """Reject a pending join request."""
+        group = self.get_object()
+        try:
+            join_request = JoinRequest.objects.get(id=request_id, group=group, status=JoinRequestStatus.PENDING)
+        except JoinRequest.DoesNotExist:
+            return Response({"error": "Pending join request not found."}, status=status.HTTP_404_NOT_FOUND)
+
+        join_request.status = JoinRequestStatus.REJECTED
+        join_request.save(update_fields=["status"])
+        return Response(JoinRequestSerializer(join_request).data)
+
+
+class JoinGroupViewSet(viewsets.GenericViewSet):
+    """Public(ish) endpoint for joining a group via an invite code."""
+
+    permission_classes = [IsAuthenticated]
+
+    @action(detail=False, methods=["get"], url_path="(?P<code>[^/.]+)")
+    def validate_invite(self, request: Request, code: str | None = None) -> Response:
+        """Check if an invite code is valid and show group info."""
+        try:
+            invite = GroupInvite.objects.select_related("group", "group__created_by").get(code=code)
+        except GroupInvite.DoesNotExist:
+            return Response({"error": "Invalid invite code."}, status=status.HTTP_404_NOT_FOUND)
+
+        if not invite.is_active:
+            return Response({"error": "This invite is no longer active."}, status=status.HTTP_410_GONE)
+
+        if invite.max_uses > 0 and invite.use_count >= invite.max_uses:
+            return Response({"error": "This invite has reached its maximum uses."}, status=status.HTTP_410_GONE)
+
+        return Response({
+            "group": {
+                "id": invite.group.id,
+                "name": invite.group.name,
+                "description": invite.group.description,
+                "created_by_email": invite.group.created_by.email,
+                "member_count": invite.group.memberships.count(),
+            },
+            "invite": {
+                "code": str(invite.code),
+                "created_by_email": invite.created_by.email,
+            },
+        })
+
+    @action(detail=False, methods=["post"], url_path="(?P<code>[^/.]+)")
+    def join(self, request: Request, code: str | None = None) -> Response:
+        """Join a group via invite code."""
+        try:
+            invite = GroupInvite.objects.select_related("group").get(code=code)
+        except GroupInvite.DoesNotExist:
+            return Response({"error": "Invalid invite code."}, status=status.HTTP_404_NOT_FOUND)
+
+        if not invite.is_active:
+            return Response({"error": "This invite is no longer active."}, status=status.HTTP_410_GONE)
+
+        if invite.max_uses > 0 and invite.use_count >= invite.max_uses:
+            return Response({"error": "This invite has reached its maximum uses."}, status=status.HTTP_410_GONE)
+
+        group = invite.group
+
+        # Check if already a member
+        if GroupMember.objects.filter(group=group, user=request.user).exists():
+            return Response(
+                {"detail": "You are already a member of this group.", "group_id": group.id},
+                status=status.HTTP_200_OK,
+            )
+
+        # Check for existing pending request
+        existing_request = JoinRequest.objects.filter(
+            group=group, user=request.user, status=JoinRequestStatus.PENDING
+        ).first()
+        if existing_request:
+            return Response(
+                JoinRequestSerializer(existing_request).data,
+                status=status.HTTP_200_OK,
+            )
+
+        # Create join request or add directly (direct join for now — simple invite flow)
+        member = GroupMember.objects.create(group=group, user=request.user, role=GroupRole.MEMBER)
+        invite.use_count += 1
+        invite.save(update_fields=["use_count"])
+
+        # Also create a join request record for tracking
+        JoinRequest.objects.create(
+            group=group,
+            user=request.user,
+            invite=invite,
+            status=JoinRequestStatus.APPROVED,
+        )
+
+        serializer = GroupDetailSerializer(group, context={"request": request})
+        return Response(serializer.data, status=status.HTTP_201_CREATED)

backend/config/django.py

@@ -41,6 +41,7 @@ INSTALLED_APPS = [
     "apps.books",
     "apps.annotations",
     "apps.reader",
+    "apps.groups",
 ]
 
 MIDDLEWARE = [

backend/config/urls.py

@@ -8,6 +8,7 @@ urlpatterns = [
     path("api/books/", include("apps.books.urls")),
     path("api/annotations/", include("apps.annotations.urls")),
     path("api/reader/", include("apps.reader.urls")),
+    path("api/", include("apps.groups.urls")),
 ]
 
 if settings.DEBUG:

backend/media/ebooks/2026/06/03/q.epub

@@ -1 +0,0 @@
-x

backend/media/ebooks/2026/06/03/test.epub

@@ -1 +0,0 @@
-fake

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/dist/assets/ReaderToolbar-wmOf7G3U.js

@@ -1 +0,0 @@
-import{X as c,j as e}from"./index-BQiEVoRj.js";function h({bookTitle:s,chapterTitle:l,progress:a,onBack:t,onToggleToc:n,onToggleSettings:o,onToggleMarkers:i}){const{t:r}=c(),d=(a==null?void 0:a.percentage)??0;return e.jsxs(e.Fragment,{children:[e.jsxs("header",{className:"reader-top-bar",children:[t?e.jsx("button",{type:"button",className:"reader-bar-btn",onClick:t,"aria-label":r("reader.backToLibraryAria"),children:e.jsx("svg",{width:"20",height:"20",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",children:e.jsx("path",{d:"M20 12H4M10 18l-6-6 6-6"})})}):e.jsx("button",{type:"button",className:"reader-bar-btn",onClick:n,"aria-label":r("reader.tocAria"),children:e.jsxs("svg",{width:"20",height:"20",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",children:[e.jsx("line",{x1:"3",y1:"6",x2:"21",y2:"6"}),e.jsx("line",{x1:"3",y1:"12",x2:"21",y2:"12"}),e.jsx("line",{x1:"3",y1:"18",x2:"21",y2:"18"})]})}),e.jsxs("div",{className:"reader-bar-title",children:[e.jsx("span",{className:"reader-bar-book",children:s}),e.jsx("span",{className:"reader-bar-chapter",children:l})]}),e.jsxs("div",{className:"reader-bar-actions",children:[t&&e.jsx("button",{type:"button",className:"reader-bar-btn",onClick:n,"aria-label":r("reader.tocAria"),children:e.jsxs("svg",{width:"20",height:"20",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",children:[e.jsx("line",{x1:"3",y1:"6",x2:"21",y2:"6"}),e.jsx("line",{x1:"3",y1:"12",x2:"21",y2:"12"}),e.jsx("line",{x1:"3",y1:"18",x2:"21",y2:"18"})]})}),i&&e.jsx("button",{type:"button",className:"reader-bar-btn",onClick:i,"aria-label":r("annotations.inBookPanel"),children:e.jsx("svg",{width:"20",height:"20",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",children:e.jsx("path",{d:"M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"})})}),e.jsx("button",{type:"button",className:"reader-bar-btn",onClick:o,"aria-label":r("reader.settingsAria"),children:e.jsxs("svg",{width:"20",height:"20",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",children:[e.jsx("circle",{cx:"12",cy:"12",r:"3"}),e.jsx("path",{d:"M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"})]})})]})]}),e.jsx("div",{className:"reader-progress-bar",children:e.jsx("div",{className:"reader-progress-fill",style:{width:`${Math.min(d,100)}%`}})})]})}export{h as default};

frontend/dist/assets/ReadingSettingsPanel-Bt3-VHc7.js

@@ -1 +0,0 @@
-import{X as m,j as e}from"./index-BQiEVoRj.js";const g=[{value:"sepia",labelKey:"reader.themeSepia"},{value:"dark",labelKey:"reader.themeDark"},{value:"light",labelKey:"reader.themeLight"},{value:"paper",labelKey:"reader.themePaper"}],u=[{value:"sans-serif",labelKey:"reader.fontSans"},{value:"serif",labelKey:"reader.fontSerif"},{value:"monospace",labelKey:"reader.fontMonospace"}],x=[{value:"auto",labelKey:"reader.orientationAuto"},{value:"portrait",labelKey:"reader.orientationPortrait"},{value:"landscape",labelKey:"reader.orientationLandscape"}];function v({settings:t,isOpen:c,onClose:d,onUpdate:o,onFlush:h}){const{t:s}=m(),n=()=>{h(),d()},i=(a,r)=>{o({[a]:r},"debounced")},l=(a,r)=>{o({[a]:r},"immediate")};return e.jsxs(e.Fragment,{children:[c&&e.jsx("div",{className:"settings-overlay",onClick:n,onKeyDown:a=>{a.key==="Escape"&&n()},role:"presentation"}),e.jsxs("aside",{className:`settings-drawer ${c?"settings-drawer--open":""}`,children:[e.jsxs("div",{className:"settings-header",children:[e.jsx("h2",{className:"settings-title",children:s("reader.settingsTitle")}),e.jsx("button",{type:"button",className:"settings-close-btn",onClick:n,"aria-label":s("reader.closeSettingsAria"),children:e.jsxs("svg",{width:"20",height:"20",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",children:[e.jsx("line",{x1:"18",y1:"6",x2:"6",y2:"18"}),e.jsx("line",{x1:"6",y1:"6",x2:"18",y2:"18"})]})})]}),e.jsxs("div",{className:"settings-body",children:[e.jsxs("section",{className:"settings-section",children:[e.jsx("h3",{className:"settings-section-title",children:s("reader.theme")}),e.jsx("div",{className:"theme-grid",children:g.map(a=>e.jsx("button",{type:"button",className:`theme-btn ${t.theme===a.value?"theme-btn--active":""}`,onClick:()=>l("theme",a.value),children:s(a.labelKey)},a.value))})]}),e.jsxs("section",{className:"settings-section",children:[e.jsx("h3",{className:"settings-section-title",children:s("reader.font")}),e.jsx("div",{className:"font-grid",children:u.map(a=>e.jsx("button",{type:"button",className:`font-btn ${t.font_family===a.value?"font-btn--active":""}`,onClick:()=>l("font_family",a.value),children:s(a.labelKey)},a.value))})]}),e.jsxs("section",{className:"settings-section",children:[e.jsx("h3",{className:"settings-section-title",children:s("reader.fontSize",{size:String(t.font_size)})}),e.jsx("input",{type:"range",min:"12",max:"32",value:t.font_size,onChange:a=>i("font_size",Number(a.target.value)),className:"settings-slider","aria-label":s("reader.fontSizeAria")})]}),e.jsxs("section",{className:"settings-section",children:[e.jsx("h3",{className:"settings-section-title",children:s("reader.lineHeight",{value:t.line_height.toFixed(1)})}),e.jsx("input",{type:"range",min:"1.2",max:"2.0",step:"0.1",value:t.line_height,onChange:a=>i("line_height",Number(a.target.value)),className:"settings-slider","aria-label":s("reader.lineHeightAria")})]}),e.jsxs("section",{className:"settings-section",children:[e.jsx("h3",{className:"settings-section-title",children:s("reader.margins",{value:String(t.margin_width)})}),e.jsx("input",{type:"range",min:"8",max:"48",value:t.margin_width,onChange:a=>i("margin_width",Number(a.target.value)),className:"settings-slider","aria-label":s("reader.marginWidthAria")})]}),e.jsxs("section",{className:"settings-section",children:[e.jsx("h3",{className:"settings-section-title",children:s("reader.brightness",{value:String(t.brightness)})}),e.jsx("input",{type:"range",min:"0",max:"100",value:t.brightness,onChange:a=>i("brightness",Number(a.target.value)),className:"settings-slider","aria-label":s("reader.brightnessAria")})]}),e.jsxs("section",{className:"settings-section",children:[e.jsx("h3",{className:"settings-section-title",children:s("reader.orientation")}),e.jsx("div",{className:"orientation-grid",children:x.map(a=>e.jsx("button",{type:"button",className:`orientation-btn ${t.orientation_lock===a.value?"orientation-btn--active":""}`,onClick:()=>l("orientation_lock",a.value),children:s(a.labelKey)},a.value))})]})]})]})]})}export{v as default};

frontend/package.json

@@ -12,13 +12,12 @@
   },
   "dependencies": {
     "axios": "^1.7.9",
-    "dompurify": "^3.4.7",
+    "react-router-dom": "^7.1.0",
     "pdfjs-dist": "^4.10.38",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-i18n-lite": "^1.0.10",
-    "react-reader": "^2.0.15",
-    "react-router-dom": "^7.1.0"
+    "react-reader": "^2.0.15"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",

frontend/src/App.tsx

@@ -1,4 +1,4 @@
-import React, { lazy, Suspense, useState } from "react";
+import React, { lazy, Suspense } from "react";
 import { BrowserRouter, Navigate, Route, Routes, useParams } from "react-router-dom";
 import { AuthProvider, useAuth } from "./context/AuthContext";
 import { I18nProvider } from "./i18n/I18nProvider";
@@ -12,15 +12,12 @@ 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 GroupsListPage = lazy(() => import("./pages/GroupsListPage").then((m) => ({ default: m.GroupsListPage })));
+const GroupDetailPage = lazy(() => import("./pages/GroupDetailPage").then((m) => ({ default: m.GroupDetailPage })));
+const CreateGroupPage = lazy(() => import("./pages/CreateGroupPage").then((m) => ({ default: m.CreateGroupPage })));
+const JoinGroupPage = lazy(() => import("./pages/JoinGroupPage").then((m) => ({ default: m.JoinGroupPage })));
 
-const AuthPage = lazy(() =>
-  import("./pages/AuthPage").then((m) => ({
-    default: () => {
-      const [isLogin, setIsLogin] = useState(true);
-      return isLogin ? <m.LoginPage onToggle={() => setIsLogin(false)} /> : <m.RegisterPage onToggle={() => setIsLogin(true)} />;
-    },
-  })),
-);
+const AuthPage = lazy(() => import("./pages/AuthPage"));
 
 function LoadingFallback() {
   const { t } = useTranslation();
@@ -52,6 +49,10 @@ function AppRoutes() {
         <Route path="/add" element={<ProtectedRoute><AddBookPage /></ProtectedRoute>} />
         <Route path="/settings" element={<ProtectedRoute><SettingsPage /></ProtectedRoute>} />
         <Route path="/bookmarks-notes/:bookId?" element={<ProtectedRoute><BookmarksNotesPage /></ProtectedRoute>} />
+        <Route path="/groups" element={<ProtectedRoute><GroupsListPage /></ProtectedRoute>} />
+        <Route path="/groups/create" element={<ProtectedRoute><CreateGroupPage /></ProtectedRoute>} />
+        <Route path="/groups/join/:code" element={<ProtectedRoute><JoinGroupPage /></ProtectedRoute>} />
+        <Route path="/groups/:id" element={<ProtectedRoute><GroupDetailPage /></ProtectedRoute>} />
         <Route path="*" element={<Navigate to="/" replace />} />
       </Routes>
     </Suspense>

frontend/src/api/annotations.ts

@@ -27,6 +27,3 @@ export async function createMarker(
 export async function deleteBookmark(id: string): Promise<void> {
   await api.delete(`/annotations/bookmarks/${id}/`);
 }
-
-/** @deprecated Use createMarker */
-export const createBookmark = createMarker;

frontend/src/api/groups.ts

@@ -0,0 +1,100 @@
+import api from "./client";
+import type {
+  CreateGroupPayload,
+  CreateInvitePayload,
+  GroupDetail,
+  GroupInvite,
+  GroupListItem,
+  InviteValidation,
+  JoinRequest,
+  UpdateGroupPayload,
+} from "../../packages/shared/src/types";
+
+export const groupsApi = {
+  // ---- Group CRUD ----
+
+  async listGroups(): Promise<GroupListItem[]> {
+    const { data } = await api.get<{ count: number; results: GroupListItem[] } | GroupListItem[]>("/groups/");
+    if (Array.isArray(data)) return data;
+    return data.results ?? [];
+  },
+
+  async getGroup(id: number): Promise<GroupDetail> {
+    const { data } = await api.get<GroupDetail>(`/groups/${id}/`);
+    return data;
+  },
+
+  async createGroup(payload: CreateGroupPayload): Promise<GroupDetail> {
+    const { data } = await api.post<GroupDetail>("/groups/", payload);
+    return data;
+  },
+
+  async updateGroup(id: number, payload: UpdateGroupPayload): Promise<GroupDetail> {
+    const { data } = await api.patch<GroupDetail>(`/groups/${id}/`, payload);
+    return data;
+  },
+
+  async deleteGroup(id: number): Promise<void> {
+    await api.delete(`/groups/${id}/`);
+  },
+
+  // ---- Members ----
+
+  async removeMember(groupId: number, userId: number): Promise<void> {
+    await api.delete(`/groups/${groupId}/members/${userId}/`);
+  },
+
+  async updateMemberRole(groupId: number, userId: number, role: "admin" | "member"): Promise<void> {
+    await api.patch(`/groups/${groupId}/members/${userId}/role/`, { role });
+  },
+
+  async leaveGroup(groupId: number): Promise<{ detail: string }> {
+    const { data } = await api.post<{ detail: string }>(`/groups/${groupId}/leave/`);
+    return data;
+  },
+
+  // ---- Invites ----
+
+  async listInvites(groupId: number): Promise<GroupInvite[]> {
+    const { data } = await api.get<GroupInvite[]>(`/groups/${groupId}/invites/`);
+    return data;
+  },
+
+  async createInvite(groupId: number, payload: CreateInvitePayload = {}): Promise<GroupInvite> {
+    const { data } = await api.post<GroupInvite>(`/groups/${groupId}/invites/`, payload);
+    return data;
+  },
+
+  async revokeInvite(groupId: number, inviteId: number): Promise<void> {
+    await api.delete(`/groups/${groupId}/invites/${inviteId}/`);
+  },
+
+  // ---- Join Requests ----
+
+  async listJoinRequests(groupId: number): Promise<JoinRequest[]> {
+    const { data } = await api.get<JoinRequest[]>(`/groups/${groupId}/requests/`);
+    return data;
+  },
+
+  async approveRequest(groupId: number, requestId: number): Promise<JoinRequest> {
+    const { data } = await api.post<JoinRequest>(`/groups/${groupId}/requests/${requestId}/approve/`);
+    return data;
+  },
+
+  async rejectRequest(groupId: number, requestId: number): Promise<JoinRequest> {
+    const { data } = await api.post<JoinRequest>(`/groups/${groupId}/requests/${requestId}/reject/`);
+    return data;
+  },
+
+  // ---- Join via Invite ----
+
+  async validateInvite(code: string): Promise<InviteValidation> {
+    const { data } = await api.get<InviteValidation>(`/join/${code}/`);
+    return data;
+  },
+
+  async joinViaInvite(code: string): Promise<GroupDetail> {
+    const { data } = await api.post<GroupDetail>(`/join/${code}/`);
+    return data;
+  },
+};

frontend/src/api/loadEbookWithProgress.ts

@@ -0,0 +1,14 @@
+import { booksApi } from "@/api/books";
+import { getReadingProgress } from "@/api/reader";
+import type { ReadingProgress } from "@/types/reader";
+
+export async function loadEbookWithProgress(bookId: number): Promise<{
+  progressData: ReadingProgress | null;
+  blob: Blob;
+}> {
+  const [progressData, blob] = await Promise.all([
+    getReadingProgress(bookId).catch(() => null),
+    booksApi.getEbookFile(bookId),
+  ]);
+  return { progressData, blob };
+}

frontend/src/api/reader.ts

@@ -1,22 +1,10 @@
 /**
- * API client for the reader module — reading settings, chapters, and progress.
+ * API client for the reader module — reading settings and progress.
  * Uses the shared axios client so JWT auth is attached automatically.
  */
 
 import api from "./client";
-import type {
-  ChapterDetail,
-  ChapterSummary,
-  ReadingProgress,
-  ReadingSettings,
-} from "../types/reader";
-
-interface TocChapter {
-  id: number;
-  title: string;
-  index: number;
-  href?: string;
-}
+import type { ReadingProgress, ReadingSettings } from "../types/reader";
 
 export async function getReadingSettings(): Promise<ReadingSettings> {
   const { data } = await api.get<ReadingSettings>("/reader/settings/");
@@ -30,39 +18,6 @@ export async function updateReadingSettings(
   return data;
 }
 
-export async function getChapters(bookId: number): Promise<ChapterSummary[]> {
-  const { data } = await api.get<{ chapters: TocChapter[] }>(
-    `/books/ebooks/${bookId}/toc/`,
-  );
-  const chapters = data.chapters ?? [];
-  return chapters.map((ch) => ({
-    id: ch.id,
-    book: bookId,
-    title: ch.title,
-    number: ch.index + 1,
-  }));
-}
-
-export async function getChapterContent(
-  bookId: number,
-  chapterNumber: number,
-): Promise<ChapterDetail> {
-  const { data } = await api.get<{
-    page: number;
-    chapter_title: string;
-    content: string;
-  }>(`/books/ebooks/${bookId}/content/`, { params: { page: chapterNumber } });
-  return {
-    id: chapterNumber,
-    book: bookId,
-    title: data.chapter_title ?? "",
-    number: data.page ?? chapterNumber,
-    content: data.content ?? "",
-    created_at: "",
-    updated_at: "",
-  };
-}
-
 export async function getReadingProgress(
   bookId: number,
 ): Promise<ReadingProgress> {

frontend/src/components/annotations/MarkerPassageActions.tsx

@@ -0,0 +1,20 @@
+import { useTranslation } from "react-i18n-lite";
+
+interface MarkerPassageActionsProps {
+  onGoToPassage: () => void;
+  onDelete: () => void;
+}
+
+export function MarkerPassageActions({ onGoToPassage, onDelete }: MarkerPassageActionsProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="annotation-actions">
+      <button type="button" className="btn btn-sm" onClick={onGoToPassage}>
+        {t("annotations.goToPassage")}
+      </button>
+      <button type="button" className="btn btn-sm btn-danger" onClick={onDelete}>
+        {t("common.delete")}
+      </button>
+    </div>
+  );
+}

frontend/src/components/annotations/MarkerThreadsView.tsx

@@ -6,6 +6,7 @@ import {
   CollapsibleMarkerPassage,
   CollapsibleMarkerThought,
 } from "@/components/annotations/CollapsibleMarkerText";
+import { MarkerPassageActions } from "@/components/annotations/MarkerPassageActions";
 
 interface MarkerThreadsViewProps {
   ebookIdFilter?: string;
@@ -91,22 +92,10 @@ export function MarkerThreadsView({
                     ) : (
                       <span className="annotation-kind-badge bookmark-badge">{t("annotations.bookmarkOnly")}</span>
                     )}
-                    <div className="annotation-actions">
-                      <button
-                        type="button"
-                        className="btn btn-sm"
-                        onClick={() => onGoToPassage(m.ebook_id, m.epub_cfi)}
-                      >
-                        {t("annotations.goToPassage")}
-                      </button>
-                      <button
-                        type="button"
-                        className="btn btn-sm btn-danger"
-                        onClick={() => removeBookmark(m.id)}
-                      >
-                        {t("common.delete")}
-                      </button>
-                    </div>
+                    <MarkerPassageActions
+                      onGoToPassage={() => onGoToPassage(m.ebook_id, m.epub_cfi)}
+                      onDelete={() => removeBookmark(m.id)}
+                    />
                   </li>
                 ))}
               </ul>

frontend/src/components/annotations/index.ts

@@ -1,2 +0,0 @@
-export { BookmarksNotesPage } from "./BookmarksNotesPage";
-export { MarkerThreadsView } from "./MarkerThreadsView";

frontend/src/components/layout/Layout.tsx

@@ -1,28 +0,0 @@
-import React from "react";
-import { useTranslation } from "react-i18n-lite";
-
-interface LayoutProps {
-  children: React.ReactNode;
-  title?: string;
-}
-
-export function Layout({
-  children,
-  title,
-}: LayoutProps): React.ReactElement {
-  const { t } = useTranslation();
-  const pageTitle = title ?? t("common.appName");
-
-  return (
-    <div className="app-container">
-      <header className="app-header">
-        <h1 className="app-title">{pageTitle}</h1>
-        <nav className="app-nav">
-          <a href="/" className="nav-link">{t("annotations.home")}</a>
-          <a href="/bookmarks-notes" className="nav-link">{t("annotations.bookmarksNotes")}</a>
-        </nav>
-      </header>
-      <main className="app-main">{children}</main>
-    </div>
-  );
-}

frontend/src/components/layout/SimpleFormPageLayout.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+import { useTranslation } from "react-i18n-lite";
+
+interface SimpleFormPageLayoutProps {
+  title: string;
+  onBack: () => void;
+  children: ReactNode;
+}
+
+export function SimpleFormPageLayout({ title, onBack, children }: SimpleFormPageLayoutProps) {
+  const { t } = useTranslation();
+  return (
+    <div style={{ maxWidth: 500, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
+      <header style={{ display: "flex", alignItems: "center", gap: 12, marginBottom: 24, padding: "16px 0", borderBottom: "1px solid #eee" }}>
+        <button
+          type="button"
+          onClick={onBack}
+          style={{ padding: "8px 16px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 14 }}
+        >
+          ← {t("common.back")}
+        </button>
+        <h1 style={{ fontSize: 24, fontWeight: 700, color: "#1a1a2e", margin: 0 }}>{title}</h1>
+      </header>
+      {children}
+    </div>
+  );
+}

frontend/src/components/layout/index.ts

@@ -1 +0,0 @@
-export { Layout } from "./Layout";

frontend/src/components/library/FinishedBooksShelf.tsx

@@ -2,7 +2,7 @@ import { useEffect, useState } from "react";
 import { useTranslation } from "react-i18n-lite";
 import styles from "./FinishedBooksShelf.module.css";
 
-export interface ShelfBook {
+interface ShelfBook {
   id: number;
   title: string;
   author: string;

frontend/src/components/library/LibraryBookCard.tsx

@@ -2,14 +2,14 @@ import { useTranslation } from "react-i18n-lite";
 import { readingStatusKey } from "@/locales";
 import styles from "../../pages/Library.module.css";
 
-export const LIBRARY_STATUS_COLORS: Record<string, { bg: string; text: string }> = {
+const LIBRARY_STATUS_COLORS: Record<string, { bg: string; text: string }> = {
   want_to_read: { bg: "#dbeafe", text: "#1d4ed8" },
   reading: { bg: "#dcfce7", text: "#16a34a" },
   finished: { bg: "#f3e8ff", text: "#9333ea" },
   dnf: { bg: "#fef3c7", text: "#b45309" },
 };
 
-export interface LibraryBookCardData {
+interface LibraryBookCardData {
   id: number;
   title: string;
   author: string;

frontend/src/components/reader/BookMarkersPanel.tsx

@@ -6,6 +6,7 @@ import {
   CollapsibleMarkerPassage,
   CollapsibleMarkerThought,
 } from "@/components/annotations/CollapsibleMarkerText";
+import { MarkerPassageActions } from "@/components/annotations/MarkerPassageActions";
 
 interface BookMarkersPanelProps {
   ebookId: number;
@@ -67,18 +68,10 @@ export function BookMarkersPanel({
                   ) : (
                     <span className="annotation-kind-badge bookmark-badge">{t("annotations.bookmarkOnly")}</span>
                   )}
-                  <div className="annotation-actions">
-                    <button type="button" className="btn btn-sm" onClick={() => onGoToPassage(m)}>
-                      {t("annotations.goToPassage")}
-                    </button>
-                    <button
-                      type="button"
-                      className="btn btn-sm btn-danger"
-                      onClick={() => removeBookmark(m.id)}
-                    >
-                      {t("common.delete")}
-                    </button>
-                  </div>
+                  <MarkerPassageActions
+                    onGoToPassage={() => onGoToPassage(m)}
+                    onDelete={() => removeBookmark(m.id)}
+                  />
                 </li>
               ))}
             </ul>

frontend/src/components/reader/EpubReadingView.tsx

@@ -2,7 +2,7 @@
  * EpubReadingView — full-screen EPUB reading powered by react-reader (epub.js).
  */
 
-import { lazy, Suspense, useCallback, useEffect, useMemo, useState } from "react";
+import { lazy, useCallback, useEffect, useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18n-lite";
 import { EpubView, EpubViewStyle } from "react-reader";
@@ -12,6 +12,10 @@ import { useEpubHighlights } from "../../hooks/useEpubHighlights";
 import { useEpubReader } from "../../hooks/useEpubReader";
 import { useEpubSelection } from "../../hooks/useEpubSelection";
 import { useReadingSettings } from "../../hooks/useReadingSettings";
+import { useReaderOrientationCss } from "../../hooks/useReaderOrientationCss";
+import { ReaderErrorScreen } from "./ReaderErrorScreen";
+import { ReaderLoadingScreen } from "./ReaderLoadingScreen";
+import { ReaderSuspenseShell } from "./ReaderSuspenseShell";
 import type { EBookDetail } from "../../types/book";
 import type { EpubTocItem } from "./TableOfContents";
 import { SelectionPopover } from "./SelectionPopover";
@@ -82,17 +86,7 @@ export function EpubReadingView({ book, bookId, initialEpubLocation }: EpubReadi
     applySettings(settings);
   }, [settings, applySettings]);
 
-  useEffect(() => {
-    const root = document.documentElement;
-    if (settings.orientation_lock !== "auto") {
-      root.style.setProperty(
-        "--reader-orientation",
-        settings.orientation_lock === "portrait" ? "portrait" : "landscape",
-      );
-    } else {
-      root.style.removeProperty("--reader-orientation");
-    }
-  }, [settings.orientation_lock]);
+  useReaderOrientationCss(settings.orientation_lock);
 
   const handleTocChanged = useCallback((toc: EpubTocItem[]) => {
     setTocItems(toc);
@@ -122,34 +116,20 @@ export function EpubReadingView({ book, bookId, initialEpubLocation }: EpubReadi
   );
 
   if (epubLoading) {
-    return (
-      <div className="reader-loading">
-        <div className="spinner" />
-        <p>{t("reader.loading")}</p>
-      </div>
-    );
+    return <ReaderLoadingScreen />;
   }
 
   if (epubError || !epubUrl) {
     return (
-      <div className="reader-loading">
-        <p className="reader-error">{epubError ?? t("reader.unableToOpen")}</p>
-        <button type="button" className="back-button" onClick={() => navigate("/")}>
-          {t("reader.backToLibrary")}
-        </button>
-      </div>
+      <ReaderErrorScreen
+        message={epubError ?? t("reader.unableToOpen")}
+        onBack={() => navigate("/")}
+      />
     );
   }
 
   return (
-    <Suspense
-      fallback={
-        <div className="reader-loading">
-          <div className="spinner" />
-        </div>
-      }
-    >
-      <div className="reader-container" data-theme={settings.theme}>
+    <ReaderSuspenseShell theme={settings.theme}>
         <ReaderToolbar
           bookTitle={book.title}
           chapterTitle={chapterTitle || t("reader.reading")}
@@ -235,7 +215,6 @@ export function EpubReadingView({ book, bookId, initialEpubLocation }: EpubReadi
             ›
           </button>
         </main>
-      </div>
-    </Suspense>
+    </ReaderSuspenseShell>
   );
 }

frontend/src/components/reader/PanelCloseButton.tsx

@@ -0,0 +1,16 @@
+interface PanelCloseButtonProps {
+  className: string;
+  onClick: () => void;
+  ariaLabel: string;
+}
+
+export function PanelCloseButton({ className, onClick, ariaLabel }: PanelCloseButtonProps) {
+  return (
+    <button type="button" className={className} onClick={onClick} aria-label={ariaLabel}>
+      <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+        <line x1="18" y1="6" x2="6" y2="18" />
+        <line x1="6" y1="6" x2="18" y2="18" />
+      </svg>
+    </button>
+  );
+}

frontend/src/components/reader/PdfReadingView.tsx

@@ -2,13 +2,17 @@
  * PdfReadingView — full-screen PDF reading powered by PDF.js.
  */
 
-import { lazy, Suspense, useCallback, useEffect, useMemo, useState } from "react";
+import { lazy, useCallback, useEffect, useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18n-lite";
 import { useAnnotations } from "@/context/AnnotationsContext";
 import { useBookmarkRailLayout } from "../../hooks/useBookmarkRailLayout";
 import { usePdfReader } from "../../hooks/usePdfReader";
 import { useReadingSettings } from "../../hooks/useReadingSettings";
+import { useReaderOrientationCss } from "../../hooks/useReaderOrientationCss";
+import { ReaderErrorScreen } from "./ReaderErrorScreen";
+import { ReaderLoadingScreen } from "./ReaderLoadingScreen";
+import { ReaderSuspenseShell } from "./ReaderSuspenseShell";
 import { useToast } from "../../hooks/useToast";
 import { booksApi } from "../../api/books";
 import type { EBookDetail } from "../../types/book";
@@ -96,17 +100,7 @@ export function PdfReadingView({ book, bookId, initialAnchor }: PdfReadingViewPr
       );
   }, [bookId, pageCount, t]);
 
-  useEffect(() => {
-    const root = document.documentElement;
-    if (settings.orientation_lock !== "auto") {
-      root.style.setProperty(
-        "--reader-orientation",
-        settings.orientation_lock === "portrait" ? "portrait" : "landscape",
-      );
-    } else {
-      root.style.removeProperty("--reader-orientation");
-    }
-  }, [settings.orientation_lock]);
+  useReaderOrientationCss(settings.orientation_lock);
 
   const handleTocNavigate = useCallback(
     (href: string) => {
@@ -165,36 +159,17 @@ export function PdfReadingView({ book, bookId, initialAnchor }: PdfReadingViewPr
   }, [bookMarkers, currentPage]);
 
   if (isLoading) {
-    return (
-      <div className="reader-loading">
-        <div className="spinner" />
-        <p>{t("reader.loading")}</p>
-      </div>
-    );
+    return <ReaderLoadingScreen />;
   }
 
   if (error || !pdfDocument) {
     const message =
       error === "PDF_PASSWORD" ? t("reader.pdfPassword") : (error ?? t("reader.unableToOpen"));
-    return (
-      <div className="reader-loading">
-        <p className="reader-error">{message}</p>
-        <button type="button" className="back-button" onClick={() => navigate("/")}>
-          {t("reader.backToLibrary")}
-        </button>
-      </div>
-    );
+    return <ReaderErrorScreen message={message} onBack={() => navigate("/")} />;
   }
 
   return (
-    <Suspense
-      fallback={
-        <div className="reader-loading">
-          <div className="spinner" />
-        </div>
-      }
-    >
-      <div className="reader-container" data-theme={settings.theme}>
+    <ReaderSuspenseShell theme={settings.theme}>
         <ReaderToolbar
           bookTitle={book.title}
           chapterTitle={chapterTitle || t("reader.reading")}
@@ -270,7 +245,6 @@ export function PdfReadingView({ book, bookId, initialAnchor }: PdfReadingViewPr
             ›
           </button>
         </main>
-      </div>
-    </Suspense>
+    </ReaderSuspenseShell>
   );
 }

frontend/src/components/reader/ReaderErrorScreen.tsx

@@ -0,0 +1,18 @@
+import { useTranslation } from "react-i18n-lite";
+
+interface ReaderErrorScreenProps {
+  message: string;
+  onBack: () => void;
+}
+
+export function ReaderErrorScreen({ message, onBack }: ReaderErrorScreenProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="reader-loading">
+      <p className="reader-error">{message}</p>
+      <button type="button" className="back-button" onClick={onBack}>
+        {t("reader.backToLibrary")}
+      </button>
+    </div>
+  );
+}

frontend/src/components/reader/ReaderLoadingScreen.tsx

@@ -0,0 +1,15 @@
+import { useTranslation } from "react-i18n-lite";
+
+interface ReaderLoadingScreenProps {
+  showMessage?: boolean;
+}
+
+export function ReaderLoadingScreen({ showMessage = true }: ReaderLoadingScreenProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="reader-loading">
+      <div className="spinner" />
+      {showMessage && <p>{t("reader.loading")}</p>}
+    </div>
+  );
+}

frontend/src/components/reader/ReaderSuspenseShell.tsx

@@ -0,0 +1,17 @@
+import { Suspense, type ReactNode } from "react";
+import { ReaderLoadingScreen } from "./ReaderLoadingScreen";
+
+interface ReaderSuspenseShellProps {
+  theme: string;
+  children: ReactNode;
+}
+
+export function ReaderSuspenseShell({ theme, children }: ReaderSuspenseShellProps) {
+  return (
+    <Suspense fallback={<ReaderLoadingScreen showMessage={false} />}>
+      <div className="reader-container" data-theme={theme}>
+        {children}
+      </div>
+    </Suspense>
+  );
+}

frontend/src/components/reader/ReaderTocButton.tsx

@@ -0,0 +1,23 @@
+import { useTranslation } from "react-i18n-lite";
+
+interface ReaderTocButtonProps {
+  onClick: () => void;
+}
+
+export function ReaderTocButton({ onClick }: ReaderTocButtonProps) {
+  const { t } = useTranslation();
+  return (
+    <button
+      type="button"
+      className="reader-bar-btn"
+      onClick={onClick}
+      aria-label={t("reader.tocAria")}
+    >
+      <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+        <line x1="3" y1="6" x2="21" y2="6" />
+        <line x1="3" y1="12" x2="21" y2="12" />
+        <line x1="3" y1="18" x2="21" y2="18" />
+      </svg>
+    </button>
+  );
+}

frontend/src/components/reader/ReaderToolbar.tsx

@@ -4,6 +4,7 @@
 
 import { useTranslation } from "react-i18n-lite";
 import type { ReadingProgress } from "../../types/reader";
+import { ReaderTocButton } from "./ReaderTocButton";
 
 interface ReaderToolbarProps {
   bookTitle: string;
@@ -47,38 +48,14 @@ export default function ReaderToolbar({
             </svg>
           </button>
         ) : (
-          <button
-            type="button"
-            className="reader-bar-btn"
-            onClick={onToggleToc}
-            aria-label={t("reader.tocAria")}
-          >
-            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-              <line x1="3" y1="6" x2="21" y2="6" />
-              <line x1="3" y1="12" x2="21" y2="12" />
-              <line x1="3" y1="18" x2="21" y2="18" />
-            </svg>
-          </button>
+          <ReaderTocButton onClick={onToggleToc} />
         )}
         <div className="reader-bar-title">
           <span className="reader-bar-book">{bookTitle}</span>
           <span className="reader-bar-chapter">{chapterTitle}</span>
         </div>
         <div className="reader-bar-actions">
-          {onBack && (
-            <button
-              type="button"
-              className="reader-bar-btn"
-              onClick={onToggleToc}
-              aria-label={t("reader.tocAria")}
-            >
-              <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-                <line x1="3" y1="6" x2="21" y2="6" />
-                <line x1="3" y1="12" x2="21" y2="12" />
-                <line x1="3" y1="18" x2="21" y2="18" />
-              </svg>
-            </button>
-          )}
+          {onBack && <ReaderTocButton onClick={onToggleToc} />}
           {onBookmarkPage && (
             <button
               type="button"

frontend/src/components/reader/ReadingSettingsPanel.tsx

@@ -12,6 +12,7 @@ import type {
   ThemePreset,
 } from "../../types/reader";
 import type { SettingsPersistMode } from "../../hooks/useReadingSettings";
+import { PanelCloseButton } from "./PanelCloseButton";
 
 interface ReadingSettingsPanelProps {
   format?: "epub" | "pdf";
@@ -89,17 +90,11 @@ export default function ReadingSettingsPanel({
       >
         <div className="settings-header">
           <h2 className="settings-title">{t("reader.settingsTitle")}</h2>
-          <button
-            type="button"
+          <PanelCloseButton
             className="settings-close-btn"
             onClick={handleClose}
-            aria-label={t("reader.closeSettingsAria")}
-          >
-            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-              <line x1="18" y1="6" x2="6" y2="18" />
-              <line x1="6" y1="6" x2="18" y2="18" />
-            </svg>
-          </button>
+            ariaLabel={t("reader.closeSettingsAria")}
+          />
         </div>
 
         <div className="settings-body">
@@ -124,7 +119,7 @@ export default function ReadingSettingsPanel({
           {format === "pdf" && onPdfScaleChange && (
             <section className="settings-section">
               <h3 className="settings-section-title">
-                {t("reader.pdfZoom", { value: Math.round(pdfScale * 100) })}
+                {t("reader.pdfZoom", { value: String(Math.round(pdfScale * 100)) })}
               </h3>
               <input
                 type="range"

frontend/src/components/reader/TableOfContents.tsx

@@ -4,6 +4,7 @@
 
 import type { KeyboardEvent } from "react";
 import { useTranslation } from "react-i18n-lite";
+import { PanelCloseButton } from "./PanelCloseButton";
 
 export interface EpubTocItem {
   label: string;
@@ -73,17 +74,11 @@ export default function TableOfContents({
       <aside className={`toc-drawer ${isOpen ? "toc-drawer--open" : ""}`}>
         <div className="toc-header">
           <h2 className="toc-title">{t("reader.tocTitle")}</h2>
-          <button
-            type="button"
+          <PanelCloseButton
             className="toc-close-btn"
             onClick={onClose}
-            aria-label={t("reader.closeTocAria")}
-          >
-            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-              <line x1="18" y1="6" x2="6" y2="18" />
-              <line x1="6" y1="6" x2="18" y2="18" />
-            </svg>
-          </button>
+            ariaLabel={t("reader.closeTocAria")}
+          />
         </div>
 
         <nav className="toc-list">

frontend/src/constants/bookmarkHighlightColors.ts

@@ -48,7 +48,7 @@ export function highlightBackgroundStyle(color: string): {
   };
 }
 
-export const BOOKMARK_COLOR_STORAGE_KEY = "cloud-reader:lastBookmarkHighlightColor";
+const BOOKMARK_COLOR_STORAGE_KEY = "cloud-reader:lastBookmarkHighlightColor";
 
 export function loadLastHighlightColor(): string {
   try {

frontend/src/context/AnnotationsContext.tsx

@@ -8,7 +8,7 @@ import {
 } from "react";
 import type { Bookmark, CreateMarkerPayload, MarkerEntry, MarkersByBook } from "@/types";
 import * as annotationsApi from "@/api/annotations";
-import { bookmarkToMarkerEntry, groupMarkersByBook, sortMarkers } from "@/utils/markers";
+import { bookmarkToMarkerEntry, groupMarkersByBook, sortBookmarks } from "@/utils/markers";
 
 interface AnnotationsState {
   bookmarks: Bookmark[];
@@ -37,10 +37,7 @@ function annotationsReducer(
     case "FETCH_BOOKMARKS_START":
       return { ...state, bookmarksLoading: true, error: null };
     case "FETCH_BOOKMARKS_SUCCESS": {
-      const sorted = [...action.payload].sort((a, b) => {
-        if (a.chapter_index !== b.chapter_index) return a.chapter_index - b.chapter_index;
-        return a.epub_cfi.localeCompare(b.epub_cfi);
-      });
+      const sorted = [...action.payload].sort(sortBookmarks);
       return { ...state, bookmarks: sorted, bookmarksLoading: false };
     }
     case "SET_ERROR":
@@ -51,10 +48,7 @@ function annotationsReducer(
         bookmarks: state.bookmarks.filter((b) => b.id !== action.payload),
       };
     case "ADD_BOOKMARK": {
-      const next = [...state.bookmarks, action.payload].sort((a, b) => {
-        if (a.chapter_index !== b.chapter_index) return a.chapter_index - b.chapter_index;
-        return a.epub_cfi.localeCompare(b.epub_cfi);
-      });
+      const next = [...state.bookmarks, action.payload].sort(sortBookmarks);
       return { ...state, bookmarks: next };
     }
     default:
@@ -105,7 +99,7 @@ export function AnnotationsProvider({
   }, []);
 
   const markers = useMemo(
-    () => state.bookmarks.map(bookmarkToMarkerEntry).sort(sortMarkers),
+    () => [...state.bookmarks].sort(sortBookmarks).map(bookmarkToMarkerEntry),
     [state.bookmarks],
   );
 

frontend/src/hooks/index.ts

@@ -1,4 +0,0 @@
-export { usePaginatedQuery } from "./usePaginatedQuery";
-export { useDebounce } from "./useDebounce";
-export { useVoiceSearch } from "./useVoiceSearch";
-export { useMediaQuery } from "./useMediaQuery";

frontend/src/hooks/useEpubReader.ts

@@ -3,8 +3,8 @@
  */
 
 import { useCallback, useEffect, useRef, useState } from "react";
-import { booksApi } from "../api/books";
-import { getReadingProgress, updateReadingProgress } from "../api/reader";
+import { loadEbookWithProgress } from "../api/loadEbookWithProgress";
+import { updateReadingProgress } from "../api/reader";
 import type { ReadingProgress, ReadingSettings } from "../types/reader";
 import {
   applyRenditionSettings,
@@ -197,10 +197,7 @@ export function useEpubReader(
       setIsLoading(true);
       setError(null);
       try {
-        const [progressData, blob] = await Promise.all([
-          getReadingProgress(bookId).catch(() => null),
-          booksApi.getEbookFile(bookId),
-        ]);
+        const { progressData, blob } = await loadEbookWithProgress(bookId);
         if (cancelled) return;
 
         blobUrl = URL.createObjectURL(blob);

frontend/src/hooks/usePaginatedQuery.ts

@@ -1,69 +0,0 @@
-import { useState, useCallback, useRef, useEffect } from "react";
-import type { PaginatedResponse } from "@/types";
-
-interface UsePaginatedQueryOptions<T> {
-  fetchFn: (cursor?: string) => Promise<PaginatedResponse<T>>;
-}
-
-interface UsePaginatedQueryResult<T> {
-  items: T[];
-  loading: boolean;
-  error: string | null;
-  hasMore: boolean;
-  loadMore: () => Promise<void>;
-  refresh: () => Promise<void>;
-}
-
-/**
- * Hook for paginated list fetching with infinite scroll support.
- */
-export function usePaginatedQuery<T>({
-  fetchFn,
-}: UsePaginatedQueryOptions<T>): UsePaginatedQueryResult<T> {
-  const [items, setItems] = useState<T[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [nextCursor, setNextCursor] = useState<string | null>(null);
-  const loadingRef = useRef(false);
-
-  const refresh = useCallback(async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const response = await fetchFn();
-      setItems(response.results);
-      setNextCursor(response.next);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Failed to fetch data");
-    } finally {
-      setLoading(false);
-    }
-  }, [fetchFn]);
-
-  const loadMore = useCallback(async () => {
-    if (!nextCursor || loadingRef.current) return;
-    loadingRef.current = true;
-    try {
-      const response = await fetchFn(nextCursor);
-      setItems((prev) => [...prev, ...response.results]);
-      setNextCursor(response.next);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Failed to load more");
-    } finally {
-      loadingRef.current = false;
-    }
-  }, [nextCursor, fetchFn]);
-
-  useEffect(() => {
-    refresh();
-  }, [refresh]);
-
-  return {
-    items,
-    loading,
-    error,
-    hasMore: nextCursor !== null,
-    loadMore,
-    refresh,
-  };
-}

frontend/src/hooks/usePdfReader.ts

@@ -3,8 +3,8 @@
  */
 
 import { useCallback, useEffect, useRef, useState } from "react";
-import { booksApi } from "../api/books";
-import { getReadingProgress, updateReadingProgress } from "../api/reader";
+import { loadEbookWithProgress } from "../api/loadEbookWithProgress";
+import { updateReadingProgress } from "../api/reader";
 import type { ReadingProgress } from "../types/reader";
 import { parsePdfAnchor } from "../utils/pdfAnchor";
 import { pdfjs, type PdfDocumentProxy } from "../utils/pdfjsSetup";
@@ -175,10 +175,7 @@ export function usePdfReader(
       setIsLoading(true);
       setError(null);
       try {
-        const [progressData, blob] = await Promise.all([
-          getReadingProgress(bookId).catch(() => null),
-          booksApi.getEbookFile(bookId),
-        ]);
+        const { progressData, blob } = await loadEbookWithProgress(bookId);
         if (cancelled) return;
 
         const loadingTask = pdfjs.getDocument({ data: await blob.arrayBuffer() });

frontend/src/hooks/useReaderOrientationCss.ts

@@ -0,0 +1,16 @@
+import { useEffect } from "react";
+import type { ReadingSettings } from "@/types/reader";
+
+export function useReaderOrientationCss(orientationLock: ReadingSettings["orientation_lock"]): void {
+  useEffect(() => {
+    const root = document.documentElement;
+    if (orientationLock !== "auto") {
+      root.style.setProperty(
+        "--reader-orientation",
+        orientationLock === "portrait" ? "portrait" : "landscape",
+      );
+    } else {
+      root.style.removeProperty("--reader-orientation");
+    }
+  }, [orientationLock]);
+}

frontend/src/hooks/useReadingSettings.ts

@@ -36,7 +36,7 @@ const DEFAULT_SETTINGS: ReadingSettings = {
 
 const SAVE_DEBOUNCE_MS = 600;
 
-export function applyReadingCssVariables(settings: ReadingSettings): void {
+function applyReadingCssVariables(settings: ReadingSettings): void {
   const root = document.documentElement;
   root.style.setProperty("--reader-bg", settings.background_color);
   root.style.setProperty("--reader-text", settings.text_color);

frontend/src/pages/AddBook.tsx

@@ -3,6 +3,7 @@ import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18n-lite";
 import { booksApi } from "../api/books";
 import { getApiErrorMessage } from "../api/errors";
+import { SimpleFormPageLayout } from "../components/layout/SimpleFormPageLayout";
 
 export function AddBookPage() {
   const { t } = useTranslation();
@@ -33,11 +34,7 @@ export function AddBookPage() {
   };
 
   return (
-    <div style={{ maxWidth: 500, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
-      <header style={{ display: "flex", alignItems: "center", gap: 12, marginBottom: 24, padding: "16px 0", borderBottom: "1px solid #eee" }}>
-        <button onClick={() => navigate("/")} style={{ padding: "8px 16px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 14 }}>← {t("common.back")}</button>
-        <h1 style={{ fontSize: 24, fontWeight: 700, color: "#1a1a2e", margin: 0 }}>{t("addBook.title")}</h1>
-      </header>
+    <SimpleFormPageLayout title={t("addBook.title")} onBack={() => navigate("/")}>
       <form onSubmit={handleSubmit} style={{ display: "flex", flexDirection: "column", gap: 20 }}>
         {error && <div style={{ background: "#fde8e8", padding: 12, borderRadius: 6, color: "#e74c3c", fontSize: 14 }}>{error}</div>}
         <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
@@ -55,6 +52,6 @@ export function AddBookPage() {
         </div>
         <button type="submit" disabled={uploading} style={{ padding: "12px 24px", borderRadius: 8, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 16, fontWeight: 600, cursor: "pointer", opacity: uploading ? 0.6 : 1, marginTop: 8 }}>{uploading ? t("addBook.uploading") : t("addBook.upload")}</button>
       </form>
-    </div>
+    </SimpleFormPageLayout>
   );
 }

frontend/src/pages/AuthPage.tsx

@@ -56,5 +56,7 @@ function AuthForm({ isLogin, onToggle }: { isLogin: boolean; onToggle: () => voi
   );
 }
 
-export function LoginPage({ onToggle }: { onToggle: () => void }) { return <AuthForm isLogin={true} onToggle={onToggle} />; }
-export function RegisterPage({ onToggle }: { onToggle: () => void }) { return <AuthForm isLogin={false} onToggle={onToggle} />; }
+export default function AuthPage() {
+  const [isLogin, setIsLogin] = useState(true);
+  return <AuthForm isLogin={isLogin} onToggle={() => setIsLogin((v) => !v)} />;
+}

frontend/src/pages/CreateGroupPage.tsx

@@ -0,0 +1,104 @@
+import React, { useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { groupsApi } from "../api/groups";
+import { useToast } from "../hooks/useToast";
+
+const S = {
+  container: { maxWidth: 500, margin: "0 auto", padding: "24px 16px" } satisfies React.CSSProperties,
+  backBtn: {
+    background: "none", border: "none", color: "#3b82f6", fontSize: 14, cursor: "pointer",
+    padding: 0, marginBottom: 16, minHeight: 44, minWidth: 44,
+  } satisfies React.CSSProperties,
+  title: { fontSize: 24, fontWeight: 700, marginBottom: 24 } satisfies React.CSSProperties,
+  label: { display: "block", fontSize: 14, fontWeight: 500, marginBottom: 6 } satisfies React.CSSProperties,
+  input: {
+    width: "100%", padding: "10px 12px", border: "1px solid #d1d5db", borderRadius: 8,
+    fontSize: 14, marginBottom: 16, boxSizing: "border-box" as const,
+  } satisfies React.CSSProperties,
+  textarea: {
+    width: "100%", padding: "10px 12px", border: "1px solid #d1d5db", borderRadius: 8,
+    fontSize: 14, marginBottom: 16, minHeight: 80, resize: "vertical" as const,
+    boxSizing: "border-box" as const, fontFamily: "inherit",
+  } satisfies React.CSSProperties,
+  submitBtn: (disabled: boolean): React.CSSProperties => ({
+    width: "100%", padding: "12px", backgroundColor: disabled ? "#93c5fd" : "#3b82f6",
+    color: "#fff", border: "none", borderRadius: 8, fontSize: 15, fontWeight: 600,
+    cursor: disabled ? "not-allowed" : "pointer", minHeight: 44,
+  }),
+  errorText: { color: "#ef4444", fontSize: 13, marginBottom: 12 },
+};
+
+export function CreateGroupPage() {
+  const navigate = useNavigate();
+  const { showToast } = useToast();
+
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!name.trim()) {
+      setError("Group name is required.");
+      return;
+    }
+    if (name.trim().length < 2) {
+      setError("Group name must be at least 2 characters.");
+      return;
+    }
+    setSubmitting(true);
+    setError(null);
+    try {
+      const group = await groupsApi.createGroup({
+        name: name.trim(),
+        description: description.trim() || undefined,
+      });
+      showToast({ message: "Group created!", variant: "success" });
+      navigate(`/groups/${group.id}`);
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : "Failed to create group";
+      setError(msg);
+      showToast({ message: msg, variant: "error" });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <div style={S.container}>
+      <button style={S.backBtn} onClick={() => navigate("/groups")}>
+        ← Back to Groups
+      </button>
+      <h1 style={S.title}>Create a Group</h1>
+
+      <form onSubmit={handleSubmit}>
+        {error && <div style={S.errorText}>{error}</div>}
+
+        <label style={S.label} htmlFor="group-name">Group Name *</label>
+        <input
+          id="group-name"
+          style={S.input}
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder="e.g., Sci-Fi Book Club"
+          maxLength={256}
+          autoFocus
+        />
+
+        <label style={S.label} htmlFor="group-desc">Description</label>
+        <textarea
+          id="group-desc"
+          style={S.textarea}
+          value={description}
+          onChange={(e) => setDescription(e.target.value)}
+          placeholder="What's this group about? (optional)"
+        />
+
+        <button type="submit" style={S.submitBtn(submitting || !name.trim())} disabled={submitting || !name.trim()}>
+          {submitting ? "Creating..." : "Create Group"}
+        </button>
+      </form>
+    </div>
+  );
+}

frontend/src/pages/GroupDetailPage.tsx

@@ -0,0 +1,334 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+import { groupsApi } from "../api/groups";
+import { useAuth } from "../context/AuthContext";
+import { useToast } from "../hooks/useToast";
+import type { GroupDetail, GroupInvite, GroupMember } from "../../packages/shared/src/types";
+
+const S = {
+  container: { maxWidth: 800, margin: "0 auto", padding: "24px 16px" } satisfies React.CSSProperties,
+  backBtn: {
+    background: "none", border: "none", color: "#3b82f6", fontSize: 14, cursor: "pointer",
+    padding: 0, marginBottom: 16, minHeight: 44, minWidth: 44,
+  } satisfies React.CSSProperties,
+  title: { fontSize: 28, fontWeight: 700, margin: "0 0 4px 0" } satisfies React.CSSProperties,
+  desc: { fontSize: 14, color: "#6b7280", margin: "0 0 20px 0" } satisfies React.CSSProperties,
+  section: { marginTop: 28 } satisfies React.CSSProperties,
+  sectionTitle: { fontSize: 18, fontWeight: 600, marginBottom: 12 } satisfies React.CSSProperties,
+  memberItem: {
+    display: "flex", justifyContent: "space-between", alignItems: "center",
+    padding: "10px 0", borderBottom: "1px solid #f3f4f6",
+  } satisfies React.CSSProperties,
+  memberInfo: { display: "flex", flexDirection: "column" as const },
+  memberName: { fontSize: 14, fontWeight: 500 } satisfies React.CSSProperties,
+  memberEmail: { fontSize: 12, color: "#9ca3af" } satisfies React.CSSProperties,
+  badge: (role: string): React.CSSProperties => ({
+    display: "inline-block", padding: "2px 8px", borderRadius: 6, fontSize: 11, fontWeight: 600,
+    backgroundColor: role === "admin" ? "#dbeafe" : "#f3f4f6",
+    color: role === "admin" ? "#1d4ed8" : "#6b7280",
+  }),
+  removeBtn: {
+    padding: "4px 12px", fontSize: 12, color: "#ef4444", background: "#fef2f2",
+    border: "1px solid #fecaca", borderRadius: 6, cursor: "pointer", minHeight: 32,
+  } satisfies React.CSSProperties,
+  transferBtn: {
+    padding: "4px 12px", fontSize: 12, color: "#3b82f6", background: "#eff6ff",
+    border: "1px solid #bfdbfe", borderRadius: 6, cursor: "pointer", minHeight: 32,
+    marginRight: 8,
+  } satisfies React.CSSProperties,
+  inviteCard: {
+    padding: "12px 16px", border: "1px solid #e5e7eb", borderRadius: 8, marginBottom: 8,
+  } satisfies React.CSSProperties,
+  inviteCode: { fontSize: 13, fontFamily: "monospace", marginBottom: 4 } satisfies React.CSSProperties,
+  inviteMeta: { fontSize: 12, color: "#9ca3af" } satisfies React.CSSProperties,
+  actionBtn: (color: string): React.CSSProperties => ({
+    padding: "8px 16px", backgroundColor: color, color: "#fff", border: "none",
+    borderRadius: 8, fontSize: 13, fontWeight: 600, cursor: "pointer",
+    minHeight: 44, minWidth: 44,
+  }),
+  dangerBtn: {
+    padding: "8px 16px", backgroundColor: "#ef4444", color: "#fff", border: "none",
+    borderRadius: 8, fontSize: 13, fontWeight: 600, cursor: "pointer",
+    minHeight: 44, minWidth: 44,
+  } satisfies React.CSSProperties,
+  leaveBtn: {
+    padding: "8px 16px", backgroundColor: "#fff", color: "#ef4444",
+    border: "1px solid #ef4444", borderRadius: 8, fontSize: 13, fontWeight: 600,
+    cursor: "pointer", minHeight: 44, minWidth: 44,
+  } satisfies React.CSSProperties,
+  inlineBtn: {
+    padding: "4px 10px", fontSize: 12, color: "#ef4444", background: "#fef2f2",
+    border: "1px solid #fecaca", borderRadius: 6, cursor: "pointer", minHeight: 28,
+  } satisfies React.CSSProperties,
+  copyRow: { display: "flex", gap: 8, alignItems: "center", marginBottom: 12 } satisfies React.CSSProperties,
+  input: {
+    flex: 1, padding: "10px 12px", border: "1px solid #d1d5db", borderRadius: 8, fontSize: 14,
+  } satisfies React.CSSProperties,
+  loading: { textAlign: "center" as const, padding: 60, color: "#9ca3af" },
+  error: { textAlign: "center" as const, padding: 40, color: "#ef4444" },
+};
+
+export function GroupDetailPage() {
+  const { id } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+  const { user } = useAuth();
+  const { showToast } = useToast();
+
+  const [group, setGroup] = useState<GroupDetail | null>(null);
+  const [invites, setInvites] = useState<GroupInvite[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [editingName, setEditingName] = useState(false);
+  const [editName, setEditName] = useState("");
+  const [showInviteSection, setShowInviteSection] = useState(false);
+
+  const groupId = Number(id);
+  const isAdmin = group?.user_role === "admin";
+
+  const loadGroup = useCallback(async () => {
+    if (!groupId) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await groupsApi.getGroup(groupId);
+      setGroup(data);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Failed to load group");
+    } finally {
+      setLoading(false);
+    }
+  }, [groupId]);
+
+  const loadInvites = useCallback(async () => {
+    if (!groupId || !isAdmin) return;
+    try {
+      const data = await groupsApi.listInvites(groupId);
+      setInvites(data);
+    } catch {
+      // Silently fail — invites are supplementary
+    }
+  }, [groupId, isAdmin]);
+
+  useEffect(() => {
+    loadGroup();
+  }, [loadGroup]);
+
+  useEffect(() => {
+    if (group && isAdmin) loadInvites();
+  }, [group, isAdmin, loadInvites]);
+
+  const handleRemoveMember = async (userId: number, memberEmail: string) => {
+    if (!confirm(`Remove ${memberEmail} from the group?`)) return;
+    try {
+      await groupsApi.removeMember(groupId, userId);
+      showToast({ message: "Member removed", variant: "success" });
+      loadGroup();
+    } catch (err: unknown) {
+      showToast({ message: "Failed to remove member", variant: "error" });
+    }
+  };
+
+  const handleTransferAdmin = async (userId: number, memberEmail: string) => {
+    if (!confirm(`Transfer admin role to ${memberEmail}? You will become a regular member.`)) return;
+    try {
+      await groupsApi.updateMemberRole(groupId, userId, "admin");
+      showToast({ message: "Admin role transferred", variant: "success" });
+      loadGroup();
+    } catch (err: unknown) {
+      showToast({ message: "Failed to transfer admin", variant: "error" });
+    }
+  };
+
+  const handleLeave = async () => {
+    if (!confirm("Are you sure you want to leave this group?")) return;
+    try {
+      const result = await groupsApi.leaveGroup(groupId);
+      showToast({ message: result.detail || "Left group", variant: "success" });
+      navigate("/groups");
+    } catch (err: unknown) {
+      showToast({ message: "Failed to leave group", variant: "error" });
+    }
+  };
+
+  const handleCreateInvite = async () => {
+    try {
+      const invite = await groupsApi.createInvite(groupId);
+      setInvites((prev) => [invite, ...prev]);
+      showToast({ message: "Invite link created!", variant: "success" });
+    } catch (err: unknown) {
+      showToast({ message: "Failed to create invite", variant: "error" });
+    }
+  };
+
+  const handleRevokeInvite = async (inviteId: number) => {
+    try {
+      await groupsApi.revokeInvite(groupId, inviteId);
+      setInvites((prev) => prev.map((i) => (i.id === inviteId ? { ...i, is_active: false } : i)));
+      showToast({ message: "Invite revoked", variant: "success" });
+    } catch (err: unknown) {
+      showToast({ message: "Failed to revoke invite", variant: "error" });
+    }
+  };
+
+  const handleSaveName = async () => {
+    if (!editName.trim()) return;
+    try {
+      const updated = await groupsApi.updateGroup(groupId, { name: editName.trim() });
+      setGroup(updated);
+      setEditingName(false);
+      showToast({ message: "Group name updated", variant: "success" });
+    } catch (err: unknown) {
+      showToast({ message: "Failed to update group", variant: "error" });
+    }
+  };
+
+  const handleDeleteGroup = async () => {
+    if (!confirm("Delete this group? This cannot be undone.")) return;
+    try {
+      await groupsApi.deleteGroup(groupId);
+      showToast({ message: "Group deleted", variant: "success" });
+      navigate("/groups");
+    } catch (err: unknown) {
+      showToast({ message: "Failed to delete group", variant: "error" });
+    }
+  };
+
+  const copyToClipboard = (text: string) => {
+    navigator.clipboard.writeText(text).then(
+      () => showToast({ message: "Link copied!" }),
+      () => showToast({ message: "Failed to copy", variant: "error" }),
+    );
+  };
+
+  if (loading) return <div style={S.loading}>Loading group...</div>;
+  if (error) return <div style={S.error}>{error} <br /><button onClick={loadGroup} style={{ marginTop: 12, padding: "8px 16px", cursor: "pointer", border: "1px solid #d1d5db", borderRadius: 6, background: "#fff" }}>Retry</button></div>;
+  if (!group) return <div style={S.error}>Group not found</div>;
+
+  return (
+    <div style={S.container}>
+      <button style={S.backBtn} onClick={() => navigate("/groups")}>
+        ← Back to Groups
+      </button>
+
+      {/* Group Header */}
+      {editingName ? (
+        <div style={{ display: "flex", gap: 8, marginBottom: 16 }}>
+          <input
+            style={S.input}
+            value={editName}
+            onChange={(e) => setEditName(e.target.value)}
+            onKeyDown={(e) => { if (e.key === "Enter") handleSaveName(); if (e.key === "Escape") setEditingName(false); }}
+            autoFocus
+          />
+          <button style={S.actionBtn("#3b82f6")} onClick={handleSaveName}>Save</button>
+          <button style={{ ...S.actionBtn("#6b7280"), padding: "8px 16px" }} onClick={() => setEditingName(false)}>Cancel</button>
+        </div>
+      ) : (
+        <h1
+          style={S.title}
+          onClick={() => {
+            if (isAdmin) { setEditName(group.name); setEditingName(true); }
+          }}
+          title={isAdmin ? "Click to edit name" : undefined}
+        >
+          {group.name}
+        </h1>
+      )}
+      <p style={S.desc}>{group.description || "No description"}</p>
+      <p style={{ fontSize: 12, color: "#9ca3af", marginBottom: 20 }}>
+        Created by {group.created_by_email} · {group.member_count} member{group.member_count !== 1 ? "s" : ""}
+      </p>
+
+      {/* Admin Actions */}
+      {isAdmin && (
+        <div style={{ display: "flex", gap: 8, flexWrap: "wrap", marginBottom: 20 }}>
+          <button
+            style={S.actionBtn("#3b82f6")}
+            onClick={() => setShowInviteSection((v) => !v)}
+          >
+            {showInviteSection ? "Hide Invites" : "Manage Invites"}
+          </button>
+          <button style={S.dangerBtn} onClick={handleDeleteGroup}>
+            Delete Group
+          </button>
+        </div>
+      )}
+
+      {/* Invites Section */}
+      {isAdmin && showInviteSection && (
+        <div style={S.section}>
+          <h2 style={S.sectionTitle}>Invite Links</h2>
+          <button style={S.actionBtn("#22c55e")} onClick={handleCreateInvite}>
+            + Generate Invite Link
+          </button>
+          {invites.length === 0 ? (
+            <p style={{ color: "#9ca3af", fontSize: 14, marginTop: 12 }}>No invites yet.</p>
+          ) : (
+            invites.map((inv) => (
+              <div key={inv.id} style={S.inviteCard}>
+                <div style={S.inviteCode}>{inv.code}</div>
+                <div style={S.inviteMeta}>
+                  {inv.is_active ? "Active" : "Revoked"} ·{" "}
+                  {inv.max_uses > 0 ? `${inv.use_count}/${inv.max_uses} uses` : `${inv.use_count} uses (unlimited)`}
+                </div>
+                <div style={{ marginTop: 8, display: "flex", gap: 8 }}>
+                  <button style={S.actionBtn("#3b82f6")} onClick={() => copyToClipboard(inv.join_url)}>
+                    Copy Link
+                  </button>
+                  {inv.is_active && (
+                    <button style={S.inlineBtn} onClick={() => handleRevokeInvite(inv.id)}>
+                      Revoke
+                    </button>
+                  )}
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      )}
+
+      {/* Members Section */}
+      <div style={S.section}>
+        <h2 style={S.sectionTitle}>Members ({group.member_count})</h2>
+        {group.members.map((member) => (
+          <div key={member.id} style={S.memberItem}>
+            <div style={S.memberInfo}>
+              <span style={S.memberName}>
+                {member.user_username || member.user_email}{" "}
+                <span style={S.badge(member.role)}>{member.role}</span>
+              </span>
+              <span style={S.memberEmail}>{member.user_email}</span>
+            </div>
+            {isAdmin && member.user_id !== Number(user?.email ? undefined : undefined) && (
+              <div style={{ display: "flex", gap: 8 }}>
+                {member.role === "member" && (
+                  <button
+                    style={S.transferBtn}
+                    onClick={() => handleTransferAdmin(member.user_id, member.user_email)}
+                  >
+                    Make Admin
+                  </button>
+                )}
+                <button
+                  style={S.removeBtn}
+                  onClick={() => handleRemoveMember(member.user_id, member.user_email)}
+                >
+                  Remove
+                </button>
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {/* Leave Group (non-admins only) */}
+      {!isAdmin && (
+        <div style={{ ...S.section, marginTop: 40 }}>
+          <button style={S.leaveBtn} onClick={handleLeave}>
+            Leave Group
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/pages/GroupsListPage.tsx

@@ -0,0 +1,195 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { groupsApi } from "../api/groups";
+import type { GroupListItem } from "../../packages/shared/src/types";
+import { useAuth } from "../context/AuthContext";
+
+const styles = {
+  container: {
+    maxWidth: 800,
+    margin: "0 auto",
+    padding: "24px 16px",
+  } satisfies React.CSSProperties,
+  header: {
+    display: "flex",
+    justifyContent: "space-between",
+    alignItems: "center",
+    marginBottom: 24,
+  } satisfies React.CSSProperties,
+  title: {
+    fontSize: 28,
+    fontWeight: 700,
+    margin: 0,
+  } satisfies React.CSSProperties,
+  createBtn: {
+    padding: "10px 20px",
+    backgroundColor: "#3b82f6",
+    color: "#fff",
+    border: "none",
+    borderRadius: 8,
+    fontSize: 14,
+    fontWeight: 600,
+    cursor: "pointer",
+    minHeight: 44,
+    minWidth: 44,
+  } satisfies React.CSSProperties,
+  groupCard: {
+    border: "1px solid #e5e7eb",
+    borderRadius: 12,
+    padding: 20,
+    marginBottom: 12,
+    cursor: "pointer",
+    transition: "box-shadow 0.15s",
+  } satisfies React.CSSProperties,
+  groupName: {
+    fontSize: 18,
+    fontWeight: 600,
+    margin: "0 0 4px 0",
+  } satisfies React.CSSProperties,
+  groupDesc: {
+    fontSize: 14,
+    color: "#6b7280",
+    margin: "0 0 8px 0",
+  } satisfies React.CSSProperties,
+  groupMeta: {
+    display: "flex",
+    gap: 12,
+    fontSize: 13,
+    color: "#9ca3af",
+  } satisfies React.CSSProperties,
+  badge: {
+    display: "inline-block",
+    padding: "2px 8px",
+    borderRadius: 6,
+    fontSize: 11,
+    fontWeight: 600,
+  } satisfies React.CSSProperties,
+  adminBadge: {
+    backgroundColor: "#dbeafe",
+    color: "#1d4ed8",
+  } satisfies React.CSSProperties,
+  memberBadge: {
+    backgroundColor: "#f3f4f6",
+    color: "#6b7280",
+  } satisfies React.CSSProperties,
+  empty: {
+    textAlign: "center" as const,
+    padding: 60,
+    color: "#9ca3af",
+  },
+  loadingText: {
+    textAlign: "center" as const,
+    padding: 60,
+    color: "#9ca3af",
+    fontSize: 16,
+  },
+  errorText: {
+    textAlign: "center" as const,
+    padding: 40,
+    color: "#ef4444",
+    fontSize: 14,
+  },
+};
+
+export function GroupsListPage() {
+  const navigate = useNavigate();
+  const { user } = useAuth();
+  const [groups, setGroups] = useState<GroupListItem[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const loadGroups = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await groupsApi.listGroups();
+      setGroups(data);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Failed to load groups");
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    loadGroups();
+  }, [loadGroups]);
+
+  if (loading) {
+    return <div style={styles.loadingText}>Loading groups...</div>;
+  }
+
+  if (error) {
+    return (
+      <div style={styles.container}>
+        <div style={styles.errorText}>
+          {error}
+          <br />
+          <button
+            onClick={loadGroups}
+            style={{
+              marginTop: 12,
+              padding: "8px 16px",
+              cursor: "pointer",
+              border: "1px solid #d1d5db",
+              borderRadius: 6,
+              background: "#fff",
+            }}
+          >
+            Retry
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div style={styles.container}>
+      <div style={styles.header}>
+        <h1 style={styles.title}>Groups</h1>
+        <button
+          style={styles.createBtn}
+          onClick={() => navigate("/groups/create")}
+        >
+          + Create Group
+        </button>
+      </div>
+
+      {groups.length === 0 ? (
+        <div style={styles.empty}>
+          <p style={{ fontSize: 16, marginBottom: 8 }}>You're not in any groups yet.</p>
+          <p style={{ fontSize: 14 }}>Create a group to start reading together with friends!</p>
+        </div>
+      ) : (
+        groups.map((group) => (
+          <div
+            key={group.id}
+            style={styles.groupCard}
+            onClick={() => navigate(`/groups/${group.id}`)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                navigate(`/groups/${group.id}`);
+              }
+            }}
+            role="button"
+            tabIndex={0}
+          >
+            <h2 style={styles.groupName}>{group.name}</h2>
+            {group.description && (
+              <p style={styles.groupDesc}>{group.description}</p>
+            )}
+            <div style={styles.groupMeta}>
+              <span>{group.member_count} member{group.member_count !== 1 ? "s" : ""}</span>
+              {group.user_role === "admin" ? (
+                <span style={{ ...styles.badge, ...styles.adminBadge }}>Admin</span>
+              ) : group.user_role === "member" ? (
+                <span style={{ ...styles.badge, ...styles.memberBadge }}>Member</span>
+              ) : null}
+            </div>
+          </div>
+        ))
+      )}
+    </div>
+  );
+}

frontend/src/pages/JoinGroupPage.tsx

@@ -0,0 +1,138 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+import { groupsApi } from "../api/groups";
+import { useToast } from "../hooks/useToast";
+import type { InviteValidation } from "../../packages/shared/src/types";
+
+const S = {
+  container: { maxWidth: 500, margin: "0 auto", padding: "24px 16px" } satisfies React.CSSProperties,
+  backBtn: {
+    background: "none", border: "none", color: "#3b82f6", fontSize: 14, cursor: "pointer",
+    padding: 0, marginBottom: 16, minHeight: 44, minWidth: 44,
+  } satisfies React.CSSProperties,
+  card: {
+    padding: 24, border: "1px solid #e5e7eb", borderRadius: 12, textAlign: "center" as const,
+  } satisfies React.CSSProperties,
+  groupIcon: {
+    width: 64, height: 64, borderRadius: "50%", backgroundColor: "#dbeafe",
+    display: "flex", alignItems: "center", justifyContent: "center",
+    margin: "0 auto 16px auto", fontSize: 28, color: "#3b82f6", fontWeight: 700,
+  } satisfies React.CSSProperties,
+  groupName: { fontSize: 22, fontWeight: 700, marginBottom: 4 } satisfies React.CSSProperties,
+  groupDesc: { fontSize: 14, color: "#6b7280", marginBottom: 8 } satisfies React.CSSProperties,
+  groupMeta: { fontSize: 13, color: "#9ca3af", marginBottom: 20 } satisfies React.CSSProperties,
+  joinBtn: {
+    padding: "12px 32px", backgroundColor: "#3b82f6", color: "#fff",
+    border: "none", borderRadius: 8, fontSize: 16, fontWeight: 600,
+    cursor: "pointer", minHeight: 44,
+  } satisfies React.CSSProperties,
+  joinBtnDisabled: {
+    padding: "12px 32px", backgroundColor: "#93c5fd", color: "#fff",
+    border: "none", borderRadius: 8, fontSize: 16, fontWeight: 600,
+    cursor: "not-allowed", minHeight: 44,
+  } satisfies React.CSSProperties,
+  loading: { textAlign: "center" as const, padding: 60, color: "#9ca3af" },
+  error: { textAlign: "center" as const, padding: 40, color: "#ef4444" },
+  errorCard: {
+    padding: 24, border: "1px solid #fecaca", borderRadius: 12, textAlign: "center" as const,
+    backgroundColor: "#fef2f2",
+  } satisfies React.CSSProperties,
+  errorTitle: { fontSize: 18, fontWeight: 600, color: "#dc2626", marginBottom: 8 } satisfies React.CSSProperties,
+  errorMsg: { fontSize: 14, color: "#ef4444" } satisfies React.CSSProperties,
+};
+
+export function JoinGroupPage() {
+  const { code } = useParams<{ code: string }>();
+  const navigate = useNavigate();
+  const { showToast } = useToast();
+
+  const [inviteInfo, setInviteInfo] = useState<InviteValidation | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [joining, setJoining] = useState(false);
+
+  const validateInvite = useCallback(async () => {
+    if (!code) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await groupsApi.validateInvite(code);
+      setInviteInfo(data);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Invalid invite");
+    } finally {
+      setLoading(false);
+    }
+  }, [code]);
+
+  useEffect(() => {
+    validateInvite();
+  }, [validateInvite]);
+
+  const handleJoin = async () => {
+    if (!code) return;
+    setJoining(true);
+    try {
+      const group = await groupsApi.joinViaInvite(code);
+      showToast({ message: `You've joined ${group.name}!`, variant: "success" });
+      navigate(`/groups/${group.id}`);
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : "Failed to join group";
+      showToast({ message: msg, variant: "error" });
+      setError(msg);
+    } finally {
+      setJoining(false);
+    }
+  };
+
+  if (loading) return <div style={S.loading}>Validating invite...</div>;
+
+  if (error && !inviteInfo) {
+    return (
+      <div style={S.container}>
+        <div style={S.errorCard}>
+          <div style={S.errorTitle}>Invalid Invite</div>
+          <div style={S.errorMsg}>{error}</div>
+          <button
+            style={{ ...S.backBtn, marginTop: 16, display: "inline-block" }}
+            onClick={() => navigate("/groups")}
+          >
+            Go to Groups
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  if (!inviteInfo) return null;
+
+  return (
+    <div style={S.container}>
+      <button style={S.backBtn} onClick={() => navigate("/groups")}>
+        ← Back to Groups
+      </button>
+
+      <div style={S.card}>
+        <div style={S.groupIcon}>
+          {inviteInfo.group.name.charAt(0).toUpperCase()}
+        </div>
+        <h1 style={S.groupName}>{inviteInfo.group.name}</h1>
+        {inviteInfo.group.description && (
+          <p style={S.groupDesc}>{inviteInfo.group.description}</p>
+        )}
+        <p style={S.groupMeta}>
+          {inviteInfo.group.member_count} member{inviteInfo.group.member_count !== 1 ? "s" : ""} ·{" "}
+          Created by {inviteInfo.invite.created_by_email}
+        </p>
+
+        <button
+          style={joining ? S.joinBtnDisabled : S.joinBtn}
+          onClick={handleJoin}
+          disabled={joining}
+        >
+          {joining ? "Joining..." : "Join Group"}
+        </button>
+      </div>
+    </div>
+  );
+}

frontend/src/pages/Library.tsx

@@ -57,7 +57,6 @@ export function LibraryPage() {
   const [filters, setFilters] = useState<FilterState>({ genre: "", author: "", reading_status: "" });
   const [genres, setGenres] = useState<string[]>([]);
   const [authors, setAuthors] = useState<string[]>([]);
-  const [totalCount, setTotalCount] = useState(0);
   const [showFilters, setShowFilters] = useState(false);
   const [showSuggestions, setShowSuggestions] = useState(false);
   const [contextMenu, setContextMenu] = useState<ContextMenuState | null>(null);
@@ -95,11 +94,9 @@ export function LibraryPage() {
         items = items.filter((b) => b.reading_status === params.reading_status);
       }
       setBooks(items);
-      setTotalCount(items.length);
     } catch (err) {
       setError(err instanceof Error ? err.message : t("library.loadFailed"));
       setBooks([]);
-      setTotalCount(0);
     } finally {
       setLoading(false);
     }
@@ -169,7 +166,6 @@ export function LibraryPage() {
       refreshFilterOptions(next);
       return next;
     });
-    setTotalCount((count) => Math.max(0, count - 1));
   }, [refreshFilterOptions]);
 
   const handleBookContextMenu = useCallback((e: React.MouseEvent, book: LibraryBook) => {
@@ -245,6 +241,7 @@ export function LibraryPage() {
           {isMobile ? (
             <>
               <button onClick={() => navigate("/add")} style={{ ...TOUCH_TARGET, fontSize: 20, background: "none", border: "none", cursor: "pointer", padding: 8 }} title={t("library.addBook")}>➕</button>
+              <button onClick={() => navigate("/groups")} style={{ ...TOUCH_TARGET, fontSize: 20, background: "none", border: "none", cursor: "pointer", padding: 8 }} title="Groups">👥</button>
               <button onClick={() => navigate("/bookmarks-notes")} style={{ ...TOUCH_TARGET, fontSize: 20, background: "none", border: "none", cursor: "pointer", padding: 8 }} title={t("library.bookmarks")}>🔖</button>
               <button onClick={() => navigate("/settings")} style={{ ...TOUCH_TARGET, fontSize: 20, background: "none", border: "none", cursor: "pointer", padding: 8 }} title={t("library.settings")}>⚙️</button>
               <button onClick={logout} style={{ ...TOUCH_TARGET, fontSize: 20, background: "none", border: "none", cursor: "pointer", padding: 8 }} title={t("library.logout")}>🚪</button>
@@ -252,6 +249,7 @@ export function LibraryPage() {
           ) : (
             <>
               <button onClick={() => navigate("/add")} className="btn">+ {t("library.addBook")}</button>
+              <button onClick={() => navigate("/groups")} className="btn btn-secondary">Groups</button>
               <button onClick={() => navigate("/bookmarks-notes")} className="btn btn-secondary">{t("library.bookmarks")}</button>
               <button onClick={() => navigate("/settings")} className="btn btn-secondary">{t("library.settings")}</button>
               <button onClick={logout} className="btn btn-danger">{t("library.logout")}</button>

frontend/src/pages/Settings.tsx

@@ -4,6 +4,7 @@ import { useTranslation } from "react-i18n-lite";
 import { booksApi } from "../api/books";
 import type { ReadingSettings } from "../types/book";
 import type { SupportedLanguage } from "../locales";
+import { SimpleFormPageLayout } from "../components/layout/SimpleFormPageLayout";
 
 const BG_COLORS = [
   { value: "#ffffff", labelKey: "settings.bgWhite" },
@@ -41,11 +42,7 @@ export function SettingsPage() {
   if (loading) return <div style={{ maxWidth: 500, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}><p>{t("settings.loading")}</p></div>;
 
   return (
-    <div style={{ maxWidth: 500, margin: "0 auto", padding: 16, minHeight: "100vh", background: "#f8f9fa" }}>
-      <header style={{ display: "flex", alignItems: "center", gap: 12, marginBottom: 24, padding: "16px 0", borderBottom: "1px solid #eee" }}>
-        <button onClick={() => navigate("/")} style={{ padding: "8px 16px", borderRadius: 6, border: "1px solid #ddd", background: "#fff", cursor: "pointer", fontSize: 14 }}>← {t("common.back")}</button>
-        <h1 style={{ fontSize: 24, fontWeight: 700, color: "#1a1a2e", margin: 0 }}>{t("settings.title")}</h1>
-      </header>
+    <SimpleFormPageLayout title={t("settings.title")} onBack={() => navigate("/")}>
       <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
         {error && <div style={{ background: "#fde8e8", padding: 12, borderRadius: 6, color: "#e74c3c", fontSize: 14 }}>{error}</div>}
         {success && <div style={{ background: "#d4edda", padding: 12, borderRadius: 6, color: "#155724", fontSize: 14 }}>{t("settings.saved")}</div>}
@@ -90,6 +87,6 @@ export function SettingsPage() {
 
         <button onClick={handleSave} disabled={saving} style={{ padding: "12px 24px", borderRadius: 8, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 16, fontWeight: 600, cursor: "pointer", opacity: saving ? 0.6 : 1, marginTop: 8 }}>{saving ? t("common.saving") : t("settings.saveSettings")}</button>
       </div>
-    </div>
+    </SimpleFormPageLayout>
   );
 }

frontend/src/types/book.ts

@@ -102,11 +102,3 @@ export interface BookSearchParams {
   page?: number;
   page_size?: number;
 }
-
-export const READING_STATUS_OPTIONS: { value: string; label: string }[] = [
-  { value: "", label: "All Statuses" },
-  { value: "want_to_read", label: "Want to Read" },
-  { value: "reading", label: "Reading" },
-  { value: "finished", label: "Finished" },
-  { value: "dnf", label: "Did Not Finish" },
-];

frontend/src/types/index.ts

@@ -1,29 +1,5 @@
 /** Core domain types for Cloud Reader */
 
-export interface User {
-  id: number;
-  email: string;
-  username: string;
-}
-
-export interface Book {
-  id: string;
-  title: string;
-  author: string;
-  total_pages: number;
-  cover_image: string;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface BookSummary {
-  id: string;
-  title: string;
-  author: string;
-  total_pages: number;
-  cover_image: string;
-}
-
 export interface Bookmark {
   id: string;
   ebook: number;
@@ -39,17 +15,6 @@ export interface Bookmark {
   updated_at: string;
 }
 
-export interface Note {
-  id: string;
-  book: string;
-  book_title: string;
-  page: number;
-  location_text: string;
-  content: string;
-  created_at: string;
-  updated_at: string;
-}
-
 export interface CreateMarkerPayload {
   ebook: number;
   epub_cfi: string;
@@ -60,18 +25,6 @@ export interface CreateMarkerPayload {
   highlight_color?: string;
 }
 
-/** @deprecated Legacy note create */
-export interface CreateNotePayload {
-  book: string;
-  page: number;
-  location_text?: string;
-  content: string;
-}
-
-export interface UpdateNotePayload {
-  content: string;
-}
-
 export interface PaginatedResponse<T> {
   count: number;
   next: string | null;
@@ -79,11 +32,6 @@ export interface PaginatedResponse<T> {
   results: T[];
 }
 
-export interface TokenResponse {
-  access: string;
-  refresh: string;
-}
-
 export interface MarkerEntry {
   id: string;
   ebook_id: number;

frontend/src/types/reader.ts

@@ -3,19 +3,6 @@
  * Reading view, settings, chapters, and progress types.
  */
 
-export interface ChapterSummary {
-  id: number;
-  book: number;
-  title: string;
-  number: number;
-}
-
-export interface ChapterDetail extends ChapterSummary {
-  content: string;
-  created_at: string;
-  updated_at: string;
-}
-
 export interface ReadingSettings {
   font_family: "sans-serif" | "serif" | "monospace";
   font_size: number;

frontend/src/utils/ebookLibrary.ts

@@ -55,7 +55,10 @@ export function ebookMatchesQuery(item: Pick<EbookLibraryItem, "title" | "author
   return item.subjects.some((s) => s.toLowerCase().includes(q));
 }
 
-export function collectGenresFromEbooks(ebooks: EBookListItem[], locale: SupportedLanguage): string[] {
+export function collectGenresFromEbooks(
+  ebooks: Pick<EBookListItem, "subjects">[],
+  locale: SupportedLanguage,
+): string[] {
   const set = new Set<string>();
   for (const e of ebooks) {
     for (const s of filterSubjectsByLocale(e.subjects ?? [], locale)) set.add(s);
@@ -63,7 +66,7 @@ export function collectGenresFromEbooks(ebooks: EBookListItem[], locale: Support
   return [...set].sort((a, b) => a.localeCompare(b, locale));
 }
 
-export function collectAuthorsFromEbooks(ebooks: EBookListItem[]): string[] {
+export function collectAuthorsFromEbooks(ebooks: Pick<EBookListItem, "author">[]): string[] {
   const set = new Set<string>();
   for (const e of ebooks) {
     if (e.author?.trim()) set.add(e.author.trim());

frontend/src/utils/epubHighlights.ts

@@ -28,7 +28,7 @@ function annotationId(bookmarkId: string): string {
   return `bookmark-hl-${bookmarkId}`;
 }
 
-export function applyBookmarkHighlight(
+function applyBookmarkHighlight(
   rendition: EpubRenditionWithHighlights,
   bookmark: BookmarkHighlight,
 ): void {
@@ -53,7 +53,7 @@ export function applyBookmarkHighlight(
   }
 }
 
-export function removeBookmarkHighlight(
+function removeBookmarkHighlight(
   rendition: EpubRenditionWithHighlights,
   bookmark: BookmarkHighlight,
 ): void {

frontend/src/utils/epubRendition.ts

@@ -67,11 +67,6 @@ export function percentageFromCfi(rendition: EpubRendition, cfi: string): number
   }
 }
 
-export function spineLength(rendition: EpubRendition): number {
-  const items = rendition.book?.spine?.spineItems;
-  return items?.length ?? 0;
-}
-
 /** Map nav/TOC href to a spine href epub.js can display. */
 export function resolveSpineHref(book: EpubBookForNav, href: string): string {
   const hashIndex = href.indexOf("#");

frontend/src/utils/libraryStatus.ts

@@ -1,9 +1,9 @@
-export const FINISHED_PROGRESS_THRESHOLD = 99;
+const FINISHED_PROGRESS_THRESHOLD = 99;
 
 export type LibraryReadingStatus = "want_to_read" | "reading" | "finished";
 
 /** API may return progress as a number or numeric string. */
-export function coerceProgressPercent(progress: unknown): number | null {
+function coerceProgressPercent(progress: unknown): number | null {
   if (progress == null || progress === "") return null;
   const n = typeof progress === "number" ? progress : Number(progress);
   if (!Number.isFinite(n)) return null;

frontend/src/utils/markers.ts

@@ -1,5 +1,4 @@
 import { DEFAULT_BOOKMARK_HIGHLIGHT_COLOR } from "@/constants/bookmarkHighlightColors";
-import { DEFAULT_BOOKMARK_HIGHLIGHT_COLOR } from "@/constants/bookmarkHighlightColors";
 import type { Bookmark, MarkerEntry, MarkersByBook } from "@/types";
 
 export function bookmarkToMarkerEntry(b: Bookmark): MarkerEntry {
@@ -19,7 +18,14 @@ export function bookmarkToMarkerEntry(b: Bookmark): MarkerEntry {
   };
 }
 
-export function sortMarkers(a: MarkerEntry, b: MarkerEntry): number {
+function sortMarkers(a: MarkerEntry, b: MarkerEntry): number {
+  if (a.chapter_index !== b.chapter_index) {
+    return a.chapter_index - b.chapter_index;
+  }
+  return a.epub_cfi.localeCompare(b.epub_cfi);
+}
+
+export function sortBookmarks(a: Bookmark, b: Bookmark): number {
   if (a.chapter_index !== b.chapter_index) {
     return a.chapter_index - b.chapter_index;
   }

frontend/src/utils/pdfAnchor.ts

@@ -7,10 +7,6 @@ export interface ParsedPdfAnchor {
 
 const PDF_ANCHOR_PREFIX = "pdf:v1:";
 
-export function isPdfAnchor(anchor: string): boolean {
-  return anchor.startsWith(PDF_ANCHOR_PREFIX) || anchor.startsWith("pdf:page:");
-}
-
 export function parsePageHref(href: string): number | null {
   const match = href.match(/^pdf:page:(\d+)$/);
   if (!match) return null;
@@ -38,7 +34,7 @@ export function parsePdfAnchor(anchor: string): ParsedPdfAnchor | null {
 
   const rectsMatch = anchor.match(/rects=([^;]+)/);
   let rects: PdfRect[] = [];
-  if (rectsMatch) {
+  if (rectsMatch?.[1]) {
     try {
       const parsed = JSON.parse(decodeURIComponent(rectsMatch[1])) as unknown;
       if (Array.isArray(parsed)) {
@@ -56,27 +52,3 @@ export function parsePdfAnchor(anchor: string): ParsedPdfAnchor | null {
 
   return { page, rects };
 }
-
-export function rectsFromSelection(
-  range: Range,
-  pageElement: HTMLElement,
-): PdfRect[] {
-  const pageRect = pageElement.getBoundingClientRect();
-  if (pageRect.width <= 0 || pageRect.height <= 0) return [];
-
-  const rects: PdfRect[] = [];
-  for (const clientRect of range.getClientRects()) {
-    if (clientRect.width <= 0 || clientRect.height <= 0) continue;
-    const x = (clientRect.left - pageRect.left) / pageRect.width;
-    const y = (clientRect.top - pageRect.top) / pageRect.height;
-    const w = clientRect.width / pageRect.width;
-    const h = clientRect.height / pageRect.height;
-    rects.push([
-      Math.max(0, Math.min(1, x)),
-      Math.max(0, Math.min(1, y)),
-      Math.max(0, Math.min(1, w)),
-      Math.max(0, Math.min(1, h)),
-    ]);
-  }
-  return rects;
-}

frontend/src/utils/pdfjsSetup.ts

@@ -7,4 +7,6 @@ pdfjs.GlobalWorkerOptions.workerSrc = new URL(
 
 export { pdfjs };
 
-export type PdfDocumentProxy = Awaited<ReturnType<typeof pdfjs.getDocument>>["promise"];
+export type PdfDocumentProxy = Awaited<
+  ReturnType<typeof pdfjs.getDocument>["promise"]
+>;

frontend/src/utils/reactReaderTheme.ts

@@ -1,65 +0,0 @@
-import { ReactReaderStyle, type IReactReaderStyle } from "react-reader";
-import type { ReadingSettings } from "../types/reader";
-
-const THEME_ARROWS: Record<ReadingSettings["theme"], string> = {
-  sepia: "#b8a898",
-  dark: "#666666",
-  light: "#cccccc",
-  paper: "#c4b8a8",
-};
-
-const THEME_ARROW_HOVER: Record<ReadingSettings["theme"], string> = {
-  sepia: "#8a7a6a",
-  dark: "#aaaaaa",
-  light: "#888888",
-  paper: "#7a6a5a",
-};
-
-/** Build complete react-reader styles — must spread ReactReaderStyle; partial objects break layout. */
-export function buildReaderStyles(settings: ReadingSettings): IReactReaderStyle {
-  return {
-    ...ReactReaderStyle,
-    container: {
-      ...ReactReaderStyle.container,
-      height: "100%",
-      width: "100%",
-    },
-    containerExpanded: ReactReaderStyle.containerExpanded,
-    readerArea: {
-      ...ReactReaderStyle.readerArea,
-      backgroundColor: settings.background_color,
-      transition: undefined,
-    },
-    titleArea: {
-      ...ReactReaderStyle.titleArea,
-      display: "none",
-    },
-    reader: {
-      ...ReactReaderStyle.reader,
-      top: 0,
-      left: 0,
-      right: 0,
-      bottom: 0,
-    },
-    arrow: {
-      ...ReactReaderStyle.arrow,
-      color: THEME_ARROWS[settings.theme],
-      fontSize: 48,
-      marginTop: -24,
-    },
-    arrowHover: {
-      ...ReactReaderStyle.arrowHover,
-      color: THEME_ARROW_HOVER[settings.theme],
-    },
-    tocButton: {
-      ...ReactReaderStyle.tocButton,
-      display: "none",
-    },
-    tocArea: ReactReaderStyle.tocArea,
-    tocAreaButton: ReactReaderStyle.tocAreaButton,
-    loadingView: {
-      ...ReactReaderStyle.loadingView,
-      color: "#999",
-    },
-  };
-}

frontend/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/app.tsx","./src/main.tsx","./src/api/annotations.ts","./src/api/books.ts","./src/api/client.ts","./src/api/errors.ts","./src/api/reader.ts","./src/components/bookcontextmenu.tsx","./src/components/toastcontainer.tsx","./src/components/annotations/bookmarksnotespage.tsx","./src/components/annotations/markerthreadsview.tsx","./src/components/annotations/index.ts","./src/components/layout/layout.tsx","./src/components/layout/index.ts","./src/components/reader/bookmarkerspanel.tsx","./src/components/reader/readertoolbar.tsx","./src/components/reader/readingsettingspanel.tsx","./src/components/reader/selectionpopover.tsx","./src/components/reader/tableofcontents.tsx","./src/components/search/searchsuggestions.tsx","./src/context/annotationscontext.tsx","./src/context/authcontext.tsx","./src/hooks/index.ts","./src/hooks/usedebounce.ts","./src/hooks/useepubreader.ts","./src/hooks/useepubselection.ts","./src/hooks/usemediaquery.ts","./src/hooks/usepaginatedquery.ts","./src/hooks/usereadingsettings.ts","./src/hooks/usetoast.tsx","./src/hooks/usevoicesearch.ts","./src/i18n/i18nprovider.tsx","./src/locales/en-us.ts","./src/locales/es-es.ts","./src/locales/index.ts","./src/pages/addbook.tsx","./src/pages/authpage.tsx","./src/pages/bookdetailpage.tsx","./src/pages/library.tsx","./src/pages/readingpage.tsx","./src/pages/settings.tsx","./src/types/book.ts","./src/types/index.ts","./src/types/reader.ts","./src/types/speech-recognition.d.ts","./src/types/__tests__/types.test.ts","./src/utils/epubrendition.ts","./src/utils/librarystatus.ts","./src/utils/markers.ts","./src/utils/reactreadertheme.ts","./vite-env.d.ts"],"version":"5.7.3"}
+{"root":["./src/app.tsx","./src/main.tsx","./src/api/annotations.ts","./src/api/books.ts","./src/api/client.ts","./src/api/errors.ts","./src/api/loadebookwithprogress.ts","./src/api/reader.ts","./src/components/bookcontextmenu.tsx","./src/components/toastcontainer.tsx","./src/components/annotations/bookmarksnotespage.tsx","./src/components/annotations/collapsiblemarkertext.tsx","./src/components/annotations/markerpassageactions.tsx","./src/components/annotations/markerthreadsview.tsx","./src/components/layout/simpleformpagelayout.tsx","./src/components/library/finishedbooksshelf.tsx","./src/components/library/librarybookcard.tsx","./src/components/reader/bookmarkerspanel.tsx","./src/components/reader/bookmarkcolorpicker.tsx","./src/components/reader/bookmarkicon.tsx","./src/components/reader/bookmarkreaderrail.tsx","./src/components/reader/epubreadingview.tsx","./src/components/reader/panelclosebutton.tsx","./src/components/reader/pdflimitationsnotice.tsx","./src/components/reader/pdfreadingview.tsx","./src/components/reader/pdfviewer.tsx","./src/components/reader/readererrorscreen.tsx","./src/components/reader/readerloadingscreen.tsx","./src/components/reader/readersuspenseshell.tsx","./src/components/reader/readertocbutton.tsx","./src/components/reader/readertoolbar.tsx","./src/components/reader/readingsettingspanel.tsx","./src/components/reader/resumereadingbutton.tsx","./src/components/reader/selectionpopover.tsx","./src/components/reader/tableofcontents.tsx","./src/components/search/searchsuggestions.tsx","./src/constants/bookmarkhighlightcolors.ts","./src/context/annotationscontext.tsx","./src/context/authcontext.tsx","./src/hooks/usebookmarkraillayout.ts","./src/hooks/usedebounce.ts","./src/hooks/useepubhighlights.ts","./src/hooks/useepubreader.ts","./src/hooks/useepubselection.ts","./src/hooks/usemediaquery.ts","./src/hooks/usepdfreader.ts","./src/hooks/usereaderorientationcss.ts","./src/hooks/usereadingsettings.ts","./src/hooks/usetoast.tsx","./src/hooks/usevoicesearch.ts","./src/i18n/i18nprovider.tsx","./src/locales/en-us.ts","./src/locales/es-es.ts","./src/locales/index.ts","./src/pages/addbook.tsx","./src/pages/authpage.tsx","./src/pages/bookdetailpage.tsx","./src/pages/library.tsx","./src/pages/readingpage.tsx","./src/pages/settings.tsx","./src/types/book.ts","./src/types/index.ts","./src/types/reader.ts","./src/types/speech-recognition.d.ts","./src/types/__tests__/types.test.ts","./src/utils/bookmarkraillayout.ts","./src/utils/ebooklibrary.ts","./src/utils/epubhighlights.ts","./src/utils/epubrendition.ts","./src/utils/librarystatus.ts","./src/utils/markers.ts","./src/utils/pdfanchor.ts","./src/utils/pdftoc.ts","./src/utils/pdfjssetup.ts","./src/utils/subjectlocale.ts","./vite-env.d.ts"],"version":"5.7.3"}

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>
-      <NavigationContainer>
-        <StatusBar style="auto" />
-        <RootNavigator />
-      </NavigationContainer>
-    </AuthProvider>
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <AuthProvider>
+        <NavigationContainer>
+          <StatusBar style="auto" />
+          <RootNavigator />
+        </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 {
-  Bookmark,
-  Note,
-  CreateBookmarkPayload,
-  CreateNotePayload,
-  PaginatedResponse,
-} from "@cloud-reader/shared";
+import type { PaginatedResponse } from "@cloud-reader/shared";
+import type { Bookmark, CreateMarkerPayload } from "../types";
 
-export function fetchBookmarks(
-  bookId?: string,
+export async function fetchBookmarks(
+  ebookId?: string | number,
 ): Promise<PaginatedResponse<Bookmark>> {
-  const params = bookId ? { book: bookId } : {};
-  return api
-    .get<PaginatedResponse<Bookmark>>("/api/annotations/bookmarks/", { params })
-    .then((res) => res.data);
+  const params: Record<string, string> = {};
+  if (ebookId != null && ebookId !== "") {
+    params.ebook = String(ebookId);
+  }
+  const { data } = await api.get<PaginatedResponse<Bookmark>>(
+    "/api/annotations/bookmarks/",
+    { params },
+  );
+  return data;
 }
 
-export function createBookmark(
-  payload: CreateBookmarkPayload,
+export async function createMarker(
+  payload: CreateMarkerPayload,
 ): Promise<Bookmark> {
-  return api
-    .post<Bookmark>("/api/annotations/bookmarks/", payload)
-    .then((res) => res.data);
+  const { data } = await api.post<Bookmark>(
+    "/api/annotations/bookmarks/",
+    payload,
+  );
+  return data;
 }
 
-export function deleteBookmark(id: string): Promise<void> {
-  return api.delete(`/api/annotations/bookmarks/${id}/`).then(() => {});
-}
-
-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(() => {});
+export async function deleteBookmark(id: string): Promise<void> {
+  await api.delete(`/api/annotations/bookmarks/${id}/`);
 }

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) {
-    return apiClient.get<ContentResponse>(
-      `/api/ebooks/${id}/content/?page=${page}`,
-    );
-  },
-
-  /** 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,
-    );
+  /**
+   * Absolute URL to stream the raw ebook file. The endpoint requires JWT auth,
+   * so callers download it with an Authorization header (e.g. via
+   * expo-file-system) rather than handing the URL to a renderer directly.
+   */
+  getFileUrl(id: number): string {
+    return `${getApiBaseUrl()}/api/books/ebooks/${id}/file/`;
   },
 };

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 };
-}