From 2bac1280ec7c918ecd23b78343ab0333a38a9256 Mon Sep 17 00:00:00 2001
From: Surya Ahuja <sahuja4@meta.com>
Date: Sun, 19 Apr 2026 18:01:02 -0700
Subject: [PATCH] feat: Add color marking for read/last-read chapters in
 library

Add visual indicators in the chapter list so users can see which chapters
have been read and which one was most recently read.

Changes:
- Backend: Expose updated_at in chapter list endpoints (ChapterService.php)
  so the frontend can determine the last-read chapter by timestamp.

- Library chapter list (BookChapters.vue): Add item-class callback that
  applies 'chapter-read' or 'chapter-last-read' CSS class to table rows.
  Add a check-circle icon next to chapter names for read chapters (green
  for last-read, grey for others). Add lastReadChapterId computed property
  that finds the chapter with the highest updated_at among read chapters.

- Reader chapter list (TextReaderChapterList.vue): Apply matching visual
  indicators in the in-reader chapter list dialog.

- Styling (BookChapters.scss, TextReaderChapterList.scss): Add chapter-read
  class (4px muted green left border) and chapter-last-read class (4px green
  left border + tinted background).

- Theme colors (themes.js): Add chapterReadBorder and
  chapterLastReadBackground color variables for light, dark, and eink themes.

- Testing: Add BookFactory, ChapterFactory, and ChapterReadTrackingTest with
  4 feature tests covering read_count and updated_at in API responses, read
  count increment on finish, and timestamp update on finish. Enable SQLite
  in-memory DB in phpunit.xml for fast isolated tests.
---
 app/Services/ChapterService.php               |  56 ++++-----
 database/factories/BookFactory.php            |  25 ++++
 database/factories/ChapterFactory.php         |  34 ++++++
 phpunit.xml                                   |   4 +-
 .../js/components/Library/BookChapters.vue    |  63 ++++++++--
 .../TextReader/TextReaderChapterList.vue      |  51 +++++++-
 resources/js/themes.js                        |  16 ++-
 resources/sass/Library/BookChapters.scss      |  11 +-
 .../TextReader/TextReaderChapterList.scss     |  11 +-
 tests/Feature/ChapterReadTrackingTest.php     | 112 ++++++++++++++++++
 10 files changed, 328 insertions(+), 55 deletions(-)
 create mode 100644 database/factories/BookFactory.php
 create mode 100644 database/factories/ChapterFactory.php
 create mode 100644 tests/Feature/ChapterReadTrackingTest.php

diff --git a/app/Services/ChapterService.php b/app/Services/ChapterService.php
index 7300c5e4..4b45379c 100644
--- a/app/Services/ChapterService.php
+++ b/app/Services/ChapterService.php
@@ -27,13 +27,13 @@ public function getChaptersForBook($userId, $bookId) {
             ::where('id', $bookId)
             ->where('user_id', $userId)
             ->first();
-        
+
         if (!$book) {
             throw new \Exception('Book does not exist, or it belongs to a different user.');
         }
 
         $chapters = Chapter
-            ::select(['id', 'name', 'read_count', 'word_count', 'unique_word_ids', 'processing_status'])
+            ::select(['id', 'name', 'read_count', 'word_count', 'unique_word_ids', 'processing_status', 'updated_at'])
             ->where('book_id', $bookId)
             ->where('user_id', $userId)
             ->get();
@@ -54,7 +54,7 @@ public function getChaptersForBook($userId, $bookId) {
             $chapters[$i]->wordCount->highlighted = -1;
             $chapters[$i]->wordCount->new = -1;
         }
-        
+
         $data = new \stdClass();
         $data->book = $book;
         $data->chapters = $chapters;
@@ -67,7 +67,7 @@ public function getChaptersBookCount($userId, $userUuid, $bookId) {
             ::where('id', $bookId)
             ->where('user_id', $userId)
             ->first();
-        
+
         if (!$book) {
             throw new \Exception('Book does not exist, or it belongs to a different user.');
         }
@@ -102,10 +102,10 @@ public function getChaptersBookCount($userId, $userUuid, $bookId) {
                 $chaptersWithWordCounts = [];
             }
         }
-        
+
         return true;
     }
-    
+
     public function getChapterForEditor($userId, $chapterId) {
         $chapter = Chapter::
             select(['name', 'raw_text', 'type'])
@@ -118,7 +118,7 @@ public function getChapterForEditor($userId, $chapterId) {
         }
 
         $chapter->raw_text = str_replace(" NEWLINE \r\n", "\r\n", $chapter->raw_text);
-        
+
         return $chapter;
     }
 
@@ -129,7 +129,7 @@ public function getChapterForReader($userId, $language, $languagesWithoutSpaces,
             ->where('language', $language)
             ->where('processing_status', ChapterProcessingStatusEnum::PROCESSED->value)
             ->first();
-        
+
         if (!$chapter) {
             throw new \Exception('Chapter could not be found.');
         }
@@ -140,7 +140,7 @@ public function getChapterForReader($userId, $language, $languagesWithoutSpaces,
             ->first();
 
         $chapters = Chapter
-            ::select(['id', 'name', 'read_count', 'word_count', 'unique_word_ids', 'processing_status'])
+            ::select(['id', 'name', 'read_count', 'word_count', 'unique_word_ids', 'processing_status', 'updated_at'])
             ->where('user_id', $userId)
             ->where('book_id', $book->id)
             ->get();
@@ -163,7 +163,7 @@ public function getChapterForReader($userId, $language, $languagesWithoutSpaces,
             $chapters[$i]->wordCount->known = -1;
             $chapters[$i]->wordCount->highlighted = -1;
             $chapters[$i]->wordCount->new = -1;
-            
+
             if ($chapters[$i]->processing_status !== ChapterProcessingStatusEnum::PROCESSED->value) {
                 continue;
             }
@@ -191,7 +191,7 @@ public function getChapterForReader($userId, $language, $languagesWithoutSpaces,
         $data->languageSpaces = !in_array($language, $languagesWithoutSpaces, true);
         $data->chapters = $chapters;
         $data->wordCount = $chapter->word_count;
-        
+
         return $data;
     }
 
@@ -203,7 +203,7 @@ public function finishChapter($userId, $chapterId, $autoMoveWordsToKnown, $uniqu
             foreach ($uniqueWords as $uniqueWordData) {
                 $saveData = [];
                 $saveData['read_count'] = $uniqueWordData->read_count;
-                
+
                 if ($uniqueWordData->stage == 2) {
                     $saveData['stage'] = 0;
                 }
@@ -266,7 +266,7 @@ public function finishChapter($userId, $chapterId, $autoMoveWordsToKnown, $uniqu
             }
 
             $word->setStage($word->stage + 1);
-            $word->save();  
+            $word->save();
         }
 
         return true;
@@ -298,14 +298,14 @@ public function createChapter($userId, $userUuid, $bookId, $chapterName, $chapte
         $chapter->save();
 
         $this->updateChapter($userId, $userUuid, $chapter->id, $chapter->name, $chapterText);
-        
+
         return true;
     }
 
     // updates the name and text of a chapter
     public function updateChapter($userId, $userUuid, $chapterId, $chapterName, $chapterText) {
         DB::disableQueryLog();
-        
+
         // retrieve chapter
         $chapter = Chapter
             ::where('id', $chapterId)
@@ -315,15 +315,15 @@ public function updateChapter($userId, $userUuid, $chapterId, $chapterName, $cha
         if (!$chapter) {
             throw new \Exception('Chapter does not exist, or it belongs to a different user.');
         }
-        
+
         // update chapter data
         $chapter->raw_text = $chapterText;
         $chapter->name = $chapterName;
         $chapter->processing_status = ChapterProcessingStatusEnum::UNPROCESSED->value;
         $chapter->save();
-        
+
         \App\Jobs\ProcessChapter::dispatch($userId, $userUuid, $chapter->id, $chapter->language);
-        
+
         return true;
     }
 
@@ -343,10 +343,10 @@ public function processChapterText($userId, $chapterId) {
             if (!$chapter) {
                 throw new \Exception('Chapter does not exist, or it belongs to a different user.');
             }
-            
+
             // process text
-            $textBlock = new TextBlockService($userId, $chapter->language);        
-            
+            $textBlock = new TextBlockService($userId, $chapter->language);
+
             if ($chapter->type == 'text') {
                 $textBlock->rawText = $chapter->raw_text;
                 $textBlock->tokenizeRawText();
@@ -355,7 +355,7 @@ public function processChapterText($userId, $chapterId) {
                 $textBlock->rawText = $chapter->raw_text;
                 $timeStamps = $textBlock->tokenizeRawSubtitles();
             }
-            
+
             $textBlock->processTokenizedWords();
             $textBlock->collectUniqueWords();
             $textBlock->updateAllPhraseIds();
@@ -379,15 +379,15 @@ public function processChapterText($userId, $chapterId) {
             $chapter->subtitle_timestamps = json_encode($timeStamps);
             $chapter->processing_status = ChapterProcessingStatusEnum::PROCESSED->value;
             $chapter->save();
-            
-            $bookId = $chapter->book_id;    
+
+            $bookId = $chapter->book_id;
         });
-        
+
         $this->bookService->updateBookWordCount($userId, $bookId);
     }
 
     public function deleteChapter($userId, $chapterId) {
-        
+
         // retrieve chapter
         $chapter = Chapter
             ::where('user_id', $userId)
@@ -409,7 +409,7 @@ public function deleteChapter($userId, $chapterId) {
     }
 
     public function retryFailedChapters($userId, $userUuid, $bookId) {
-        
+
         $chapters = Chapter
             ::where('user_id', $userId)
             ->where('book_id', $bookId)
@@ -428,4 +428,4 @@ public function retryFailedChapters($userId, $userUuid, $bookId) {
 
         return true;
     }
-}
\ No newline at end of file
+}
diff --git a/database/factories/BookFactory.php b/database/factories/BookFactory.php
new file mode 100644
index 00000000..4bfe2a1d
--- /dev/null
+++ b/database/factories/BookFactory.php
@@ -0,0 +1,25 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\Book;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\Book>
+ */
+class BookFactory extends Factory
+{
+    protected $model = Book::class;
+
+    public function definition(): array
+    {
+        return [
+            'user_id' => 1,
+            'name' => fake()->sentence(3),
+            'cover_image' => '',
+            'language' => 'english',
+            'word_count' => 0,
+        ];
+    }
+}
diff --git a/database/factories/ChapterFactory.php b/database/factories/ChapterFactory.php
new file mode 100644
index 00000000..64b8b6eb
--- /dev/null
+++ b/database/factories/ChapterFactory.php
@@ -0,0 +1,34 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\Chapter;
+use App\Enums\ChapterProcessingStatusEnum;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\Chapter>
+ */
+class ChapterFactory extends Factory
+{
+    protected $model = Chapter::class;
+
+    public function definition(): array
+    {
+        return [
+            'user_id' => 1,
+            'book_id' => 1,
+            'name' => fake()->sentence(3),
+            'read_count' => 0,
+            'word_count' => fake()->numberBetween(50, 500),
+            'language' => 'english',
+            'raw_text' => fake()->paragraph(),
+            'processed_text' => '',
+            'unique_words' => '[]',
+            'unique_word_ids' => '[]',
+            'type' => 'text',
+            'subtitle_timestamps' => '',
+            'processing_status' => ChapterProcessingStatusEnum::PROCESSED->value,
+        ];
+    }
+}
diff --git a/phpunit.xml b/phpunit.xml
index 506b9a38..61c031c4 100755
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -22,8 +22,8 @@
         <env name="APP_MAINTENANCE_DRIVER" value="file"/>
         <env name="BCRYPT_ROUNDS" value="4"/>
         <env name="CACHE_STORE" value="array"/>
-        <!-- <env name="DB_CONNECTION" value="sqlite"/> -->
-        <!-- <env name="DB_DATABASE" value=":memory:"/> -->
+        <env name="DB_CONNECTION" value="sqlite"/>
+        <env name="DB_DATABASE" value=":memory:"/>
         <env name="MAIL_MAILER" value="array"/>
         <env name="PULSE_ENABLED" value="false"/>
         <env name="QUEUE_CONNECTION" value="sync"/>
diff --git a/resources/js/components/Library/BookChapters.vue b/resources/js/components/Library/BookChapters.vue
index 55edd553..a5cb19e4 100644
--- a/resources/js/components/Library/BookChapters.vue
+++ b/resources/js/components/Library/BookChapters.vue
@@ -3,14 +3,14 @@
         <!-- Error dialog -->
         <error-dialog
             v-if="errorDialog.active"
-            v-model="errorDialog.active" 
+            v-model="errorDialog.active"
             content="An error has occurred while deleting the chapter."
         ></error-dialog>
 
         <!-- Edit book chapter dialog -->
         <edit-book-chapter-dialog
             v-if="editBookChapterDialog.active"
-            v-model="editBookChapterDialog.active" 
+            v-model="editBookChapterDialog.active"
             :book-id="$props.bookId"
             :chapter-id="editBookChapterDialog.chapterId"
             @chapter-saved="chapterSaved"
@@ -20,22 +20,22 @@
         <!-- Delete book chapter dialog -->
         <delete-book-chapter-dialog
             v-if="deleteBookChapterDialog.active"
-            v-model="deleteBookChapterDialog.active" 
+            v-model="deleteBookChapterDialog.active"
             :chapter-id="deleteBookChapterDialog.chapterId"
             :chapter-name="deleteBookChapterDialog.chapterName"
             @confirm="deleteChapter"
         >
         </delete-book-chapter-dialog>
-        
+
         <!-- Review dialog -->
-        <start-review-dialog 
-            v-model="startReviewDialog.active" 
-            :book-id="startReviewDialog.bookId" 
+        <start-review-dialog
+            v-model="startReviewDialog.active"
+            :book-id="startReviewDialog.bookId"
             :book-name="startReviewDialog.bookName"
-            :chapter-id="startReviewDialog.chapterId" 
+            :chapter-id="startReviewDialog.chapterId"
             :chapter-name="startReviewDialog.chapterName">
         </start-review-dialog>
-        
+
 
         <!-- Chapter list -->
         <v-data-table
@@ -52,9 +52,23 @@
             :items="chapters"
             :loading="chaptersLoading"
             :items-per-page="-1"
+            :item-class="chapterRowClass"
             hide-default-footer
         >
 
+            <!-- Chapter name with read indicator -->
+            <template v-slot:item.name="{ item }">
+                <div class="d-flex align-center">
+                    <v-icon
+                        v-if="item.read_count > 0"
+                        small
+                        class="mr-2"
+                        :color="item.id === lastReadChapterId ? 'success' : 'grey'"
+                    >mdi-check-circle</v-icon>
+                    {{ item.name }}
+                </div>
+            </template>
+
             <!-- Total words -->
             <template v-slot:item.wordCount.total="{ item }">
                 <!-- Count -->
@@ -248,6 +262,22 @@
             bookId: Number,
             wordCountDisplayType: Number,
         },
+        computed: {
+            lastReadChapterId() {
+                let lastRead = null;
+                let latestTime = null;
+                this.chapters.forEach((chapter) => {
+                    if (chapter.read_count > 0 && chapter.updated_at) {
+                        const time = new Date(chapter.updated_at).getTime();
+                        if (latestTime === null || time > latestTime) {
+                            latestTime = time;
+                            lastRead = chapter.id;
+                        }
+                    }
+                });
+                return lastRead;
+            },
+        },
         mounted() {
             this.loadChapters();
 
@@ -311,7 +341,7 @@
                     for (let chapterIndex = 0; chapterIndex < response.data.chapters.length; chapterIndex++) {
                         response.data.chapters[chapterIndex].wordCountsLoaded = false;
                     }
-                    
+
                     this.book = response.data.book;
                     this.chapters = response.data.chapters;
 
@@ -324,7 +354,7 @@
                     this.chaptersLoading = false;
                     this.$nextTick(() => {
                         axios.get('/chapters/word-counts/' + this.$props.bookId);
-                    }) 
+                    })
                 });
             },
             showStartReviewDialog(bookId, bookName, chapterId, chapterName) {
@@ -334,7 +364,16 @@
                 this.startReviewDialog.chapterId = chapterId;
                 this.startReviewDialog.active = true;
             },
-            formatNumber: formatNumber
+            formatNumber: formatNumber,
+            chapterRowClass(item) {
+                if (item.read_count > 0 && item.id === this.lastReadChapterId) {
+                    return 'chapter-last-read';
+                }
+                if (item.read_count > 0) {
+                    return 'chapter-read';
+                }
+                return '';
+            },
         }
     }
 </script>
diff --git a/resources/js/components/TextReader/TextReaderChapterList.vue b/resources/js/components/TextReader/TextReaderChapterList.vue
index 2fd322f2..9b45cf98 100644
--- a/resources/js/components/TextReader/TextReaderChapterList.vue
+++ b/resources/js/components/TextReader/TextReaderChapterList.vue
@@ -1,6 +1,6 @@
 <template>
     <v-dialog v-model="value" scrollable persistent max-width="1000" attach=".v-main">
-        <v-card 
+        <v-card
             id="text-reader-chapter-list"
             outlined
             class="rounded-lg"
@@ -25,8 +25,22 @@
                             </tr>
                         </thead>
                         <tbody>
-                            <tr v-for="(chapter, index) in chapters" :key="index">
-                                <td class="default-font">{{ chapter.name }}</td>
+                            <tr
+                                v-for="(chapter, index) in chapters"
+                                :key="index"
+                                :class="chapterRowClass(chapter)"
+                            >
+                                <td class="default-font">
+                                    <div class="d-flex align-center">
+                                        <v-icon
+                                            v-if="chapter.read_count > 0"
+                                            small
+                                            class="mr-2"
+                                            :color="chapter.id === lastReadChapterId ? 'success' : 'grey'"
+                                        >mdi-check-circle</v-icon>
+                                        {{ chapter.name }}
+                                    </div>
+                                </td>
                                 <td class="text-center">{{ chapter.wordCount.total }}</td>
                                 <td class="text-center">{{ chapter.wordCount.unique }}</td>
                                 <td class="text-center"><span class="rounded-pill highlighted">{{ chapter.wordCount.highlighted }}</span></td>
@@ -56,8 +70,8 @@
 </template>
 
 <script>
-    export default {    
-        emits: ['input'],   
+    export default {
+        emits: ['input'],
         data: function() {
             return {
             }
@@ -67,12 +81,37 @@
             chapters: Array,
             currentChapterId: Number
         },
+        computed: {
+            lastReadChapterId() {
+                let lastRead = null;
+                let latestTime = null;
+                this.chapters.forEach((chapter) => {
+                    if (chapter.read_count > 0 && chapter.updated_at) {
+                        const time = new Date(chapter.updated_at).getTime();
+                        if (latestTime === null || time > latestTime) {
+                            latestTime = time;
+                            lastRead = chapter.id;
+                        }
+                    }
+                });
+                return lastRead;
+            },
+        },
         mounted() {
         },
         methods: {
             close: function() {
                 this.$emit('input', false);
-            }
+            },
+            chapterRowClass(chapter) {
+                if (chapter.read_count > 0 && chapter.id === this.lastReadChapterId) {
+                    return 'chapter-last-read';
+                }
+                if (chapter.read_count > 0) {
+                    return 'chapter-read';
+                }
+                return '';
+            },
         }
     }
 </script>
diff --git a/resources/js/themes.js b/resources/js/themes.js
index b96516e7..703426eb 100644
--- a/resources/js/themes.js
+++ b/resources/js/themes.js
@@ -4,7 +4,7 @@ export default {
         foreground: '#FFFFFF',
         navigation: '#FFFFFF',
         primary: '#AB8875',
-        
+
         gray: '#E9EAEC',
         gray2: '#E4E4E4',
         gray3: '#F0F0F0',
@@ -14,7 +14,7 @@ export default {
         info: '#057CBC',
         success: '#3DCF59',
         warning: '#FFA73C',
-        
+
         text: '#333333',
         textDark: '#333333',
 
@@ -22,6 +22,8 @@ export default {
         highlightedWordText: '#333333',
         highlightedWordBackground: '#71EB7A',
         newWordBackground: '#ffD08B',
+        chapterReadBorder: '#8BC68F',
+        chapterLastReadBackground: '#E8F5E9',
     },
     dark: {
         background: '#1C1B20',
@@ -41,7 +43,9 @@ export default {
         readerWordSelection: '#B6B6B6',
         highlightedWordText: '#121212',
         highlightedWordBackground: '#49A74F',
-        newWordBackground: '#ffD08B'
+        newWordBackground: '#ffD08B',
+        chapterReadBorder: '#4A8B4F',
+        chapterLastReadBackground: '#1B3A1D',
     },
     eink: {
         name: '#000000',
@@ -59,7 +63,7 @@ export default {
         info: '#057CBC',
         success: '#000000',
         warning: '#000000',
-        
+
         text: '#000000',
         textDark: '#000000',
 
@@ -67,5 +71,7 @@ export default {
         highlightedWordText: '#FFFFFF',
         highlightedWordBackground: '#000000',
         newWordBackground: '#000000',
+        chapterReadBorder: '#888888',
+        chapterLastReadBackground: '#F0F0F0',
     },
-}
\ No newline at end of file
+}
diff --git a/resources/sass/Library/BookChapters.scss b/resources/sass/Library/BookChapters.scss
index 333256a1..af85777f 100644
--- a/resources/sass/Library/BookChapters.scss
+++ b/resources/sass/Library/BookChapters.scss
@@ -1,4 +1,13 @@
 .book-chapters {
+    .chapter-read {
+        border-left: 4px solid var(--v-chapterReadBorder-base);
+    }
+
+    .chapter-last-read {
+        border-left: 4px solid var(--v-success-base);
+        background-color: var(--v-chapterLastReadBackground-base) !important;
+    }
+
     .highlighted-words {
         background-color: var(--v-highlightedWordBackground-base);
         color: var(--v-highlightedWordText-base);
@@ -25,4 +34,4 @@
     .importing-text {
         color: var(--v-warning-base);
     }
-}
\ No newline at end of file
+}
diff --git a/resources/sass/TextReader/TextReaderChapterList.scss b/resources/sass/TextReader/TextReaderChapterList.scss
index 9a0357c1..7815bdea 100644
--- a/resources/sass/TextReader/TextReaderChapterList.scss
+++ b/resources/sass/TextReader/TextReaderChapterList.scss
@@ -1,4 +1,13 @@
 #text-reader-chapter-list {
+    tr.chapter-read {
+        border-left: 4px solid var(--v-chapterReadBorder-base);
+    }
+
+    tr.chapter-last-read {
+        border-left: 4px solid var(--v-success-base);
+        background-color: var(--v-chapterLastReadBackground-base) !important;
+    }
+
     span.highlighted{
         display: block;
         margin: auto;
@@ -48,4 +57,4 @@
             display: none;
         }
     }
-}
\ No newline at end of file
+}
diff --git a/tests/Feature/ChapterReadTrackingTest.php b/tests/Feature/ChapterReadTrackingTest.php
new file mode 100644
index 00000000..f1adedeb
--- /dev/null
+++ b/tests/Feature/ChapterReadTrackingTest.php
@@ -0,0 +1,112 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\Book;
+use App\Models\Chapter;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class ChapterReadTrackingTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private User $user;
+    private Book $book;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->user = User::factory()->create();
+        $this->book = Book::factory()->create([
+            'user_id' => $this->user->id,
+        ]);
+    }
+
+    public function test_chapters_endpoint_returns_read_count(): void
+    {
+        Chapter::factory()->create([
+            'user_id' => $this->user->id,
+            'book_id' => $this->book->id,
+            'read_count' => 3,
+        ]);
+
+        $response = $this->actingAs($this->user)->post('/chapters', [
+            'bookId' => $this->book->id,
+        ]);
+
+        $response->assertStatus(200);
+        $data = $response->json();
+        $this->assertArrayHasKey('chapters', $data);
+        $this->assertCount(1, $data['chapters']);
+        $this->assertEquals(3, $data['chapters'][0]['read_count']);
+    }
+
+    public function test_chapters_endpoint_returns_updated_at(): void
+    {
+        Chapter::factory()->create([
+            'user_id' => $this->user->id,
+            'book_id' => $this->book->id,
+        ]);
+
+        $response = $this->actingAs($this->user)->post('/chapters', [
+            'bookId' => $this->book->id,
+        ]);
+
+        $response->assertStatus(200);
+        $data = $response->json();
+        $this->assertArrayHasKey('updated_at', $data['chapters'][0]);
+        $this->assertNotNull($data['chapters'][0]['updated_at']);
+    }
+
+    public function test_finish_chapter_increments_read_count(): void
+    {
+        $chapter = Chapter::factory()->create([
+            'user_id' => $this->user->id,
+            'book_id' => $this->book->id,
+            'read_count' => 0,
+        ]);
+
+        $response = $this->actingAs($this->user)->post('/chapters/finish', [
+            'chapterId' => $chapter->id,
+            'autoMoveWordsToKnown' => false,
+            'uniqueWords' => [],
+            'autoLevelUpWords' => false,
+            'leveledUpWords' => [],
+            'leveledUpPhrases' => [],
+            'language' => 'english',
+        ]);
+
+        $response->assertStatus(200);
+
+        $chapter->refresh();
+        $this->assertEquals(1, $chapter->read_count);
+    }
+
+    public function test_finish_chapter_updates_timestamp(): void
+    {
+        $chapter = Chapter::factory()->create([
+            'user_id' => $this->user->id,
+            'book_id' => $this->book->id,
+            'read_count' => 0,
+            'updated_at' => now()->subDay(),
+        ]);
+
+        $originalTimestamp = $chapter->updated_at;
+
+        $this->actingAs($this->user)->post('/chapters/finish', [
+            'chapterId' => $chapter->id,
+            'autoMoveWordsToKnown' => false,
+            'uniqueWords' => [],
+            'autoLevelUpWords' => false,
+            'leveledUpWords' => [],
+            'leveledUpPhrases' => [],
+            'language' => 'english',
+        ]);
+
+        $chapter->refresh();
+        $this->assertTrue($chapter->updated_at->gt($originalTimestamp));
+    }
+}