From 8ef69955d7c8478e277f3ee1e16b0f0c8fa1fae1 Mon Sep 17 00:00:00 2001
From: Vasyl Vdovychenko <mrviduus@gmail.com>
Date: Sat, 23 May 2026 13:37:07 -0400
Subject: [PATCH 1/2] =?UTF-8?q?fix(pdf):=20bullet=20=E2=86=92=20new=20para?=
 =?UTF-8?q?graph,=20drop=20TOC=20chapter,=20allow=20re-extract?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two visible bugs reported on a fresh PDF upload:
- Bullet lists in the Preface got concatenated into one wall of text —
  "• You're building... • You want to... • Tool developers..." all in a
  single run. PdfPageTextExtractor.GroupLinesIntoParagraphs only split on
  vertical y-gap, and tightly-spaced lists don't have one.
- The "Table of Contents" chapter showed up as a single dense run of
  leader-dotted entries. It's rendered nowhere readably and the in-app
  TOC is already built from the chapter list itself.

Changes:
- Add BulletGlyphs set + StartsWithBulletGlyph check in
  GroupLinesIntoParagraphs — a line whose first word is •, ●, ▪, ◦, ○,
  ‣, ⁃ (etc.) forces a new paragraph regardless of y-gap.
- New FrontMatterFilter.IsTableOfContents (anchored regex, en + ru/uk +
  a few EU languages, tolerates trailing page-number bookmarks).
- PdfTextExtractor skips the chapter when the bookmark title matches.
- UserBookService.RetryAsync now also accepts Ready (not just Failed) so
  existing books can pick up extraction improvements without a
  delete+reupload roundtrip. UserIngestionService already wipes old
  chapters before re-extracting, so this is safe.
- UserBookDetailPage gets a small "Re-extract" icon button next to
  delete (single click, no confirm — reversible).

Tests: 36/36 in TextStack.Extraction.Tests pass — 14 new across
FrontMatterFilterTests + PdfPageTextExtractorTests covering bullet
glyph detection and TOC title matching.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 apps/web/src/pages/UserBookDetailPage.tsx     | 33 ++++++++++++++-
 apps/web/src/styles/books.css                 | 32 +++++++++++++++
 .../Application/UserBooks/UserBookService.cs  |  8 +++-
 .../Extractors/FrontMatterFilter.cs           | 29 +++++++++++++
 .../Extractors/Pdf/PdfPageTextExtractor.cs    | 32 ++++++++++++++-
 .../Extractors/PdfTextExtractor.cs            | 12 ++++++
 .../FrontMatterFilterTests.cs                 | 41 +++++++++++++++++++
 .../PdfPageTextExtractorTests.cs              | 32 +++++++++++++++
 8 files changed, 215 insertions(+), 4 deletions(-)
 create mode 100644 backend/src/Extraction/TextStack.Extraction/Extractors/FrontMatterFilter.cs
 create mode 100644 tests/TextStack.Extraction.Tests/FrontMatterFilterTests.cs
 create mode 100644 tests/TextStack.Extraction.Tests/PdfPageTextExtractorTests.cs

diff --git a/apps/web/src/pages/UserBookDetailPage.tsx b/apps/web/src/pages/UserBookDetailPage.tsx
index 97799768..d5ea0473 100644
--- a/apps/web/src/pages/UserBookDetailPage.tsx
+++ b/apps/web/src/pages/UserBookDetailPage.tsx
@@ -2,7 +2,7 @@ import { useState, useEffect, useMemo, useRef } from 'react'
 import { useParams, Link, useNavigate } from 'react-router-dom'
 import { useAuth } from '../context/AuthContext'
 import { useLanguage } from '../context/LanguageContext'
-import { getUserBook, deleteUserBook, markUserBookComplete, unmarkUserBookComplete, getUserBookCoverUrl, type UserBookDetail } from '../api/userBooks'
+import { getUserBook, deleteUserBook, retryUserBook, markUserBookComplete, unmarkUserBookComplete, getUserBookCoverUrl, type UserBookDetail } from '../api/userBooks'
 import { SeoHead } from '../components/SeoHead'
 import { Footer } from '../components/Footer'
 import { stringToColor } from '../utils/colors'
@@ -27,6 +27,7 @@ export function UserBookDetailPage() {
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState<string | null>(null)
   const [deleting, setDeleting] = useState(false)
+  const [reprocessing, setReprocessing] = useState(false)
   // Inline two-stage confirm — mirrors VocabularyPage's delete pattern.
   // First click flips the icon button into a red "Confirm?" pill; a second
   // click within 3 s actually deletes. Avoids the browser-native confirm()
@@ -297,6 +298,36 @@ export function UserBookDetailPage() {
               />
             )}
 
+            {isReady && (
+              <button
+                type="button"
+                onClick={async () => {
+                  if (!id || reprocessing) return
+                  setReprocessing(true)
+                  try {
+                    await retryUserBook(id)
+                    // Flip to Processing so the auto-refresh effect kicks in
+                    // and the user sees the spinner instead of stale Ready state.
+                    setBook({ ...book, status: 'Processing' })
+                  } catch (err) {
+                    setError(err instanceof Error ? err.message : 'Failed to reprocess')
+                  } finally {
+                    setReprocessing(false)
+                  }
+                }}
+                disabled={reprocessing}
+                className="user-book-detail__reextract-icon"
+                aria-label={reprocessing ? 'Reprocessing…' : 'Re-extract this book (pick up extraction improvements)'}
+              >
+                <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+                  <polyline points="23 4 23 10 17 10" />
+                  <polyline points="1 20 1 14 7 14" />
+                  <path d="M3.51 9a9 9 0 0 1 14.85-3.36L23 10" />
+                  <path d="M20.49 15a9 9 0 0 1-14.85 3.36L1 14" />
+                </svg>
+              </button>
+            )}
+
             {isReady && (
               <button
                 type="button"
diff --git a/apps/web/src/styles/books.css b/apps/web/src/styles/books.css
index 4b2b9261..b6c71aff 100644
--- a/apps/web/src/styles/books.css
+++ b/apps/web/src/styles/books.css
@@ -4662,6 +4662,38 @@ html.dark .add-to-collection-button--icon[aria-label]::after {
   background: rgba(0, 0, 0, 0.04);
 }
 
+/* Re-extract icon: same neutral shape as delete-idle. Single click, no
+   confirm — the worst case is a few minutes of processing, fully reversible. */
+.user-book-detail__reextract-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  padding: 0;
+  border-radius: 18px;
+  background: transparent;
+  border: 1px solid var(--color-border, #E8E2D9);
+  color: var(--color-text-muted, #6b6b6b);
+  cursor: pointer;
+  transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+}
+.user-book-detail__reextract-icon:hover:not(:disabled) {
+  color: var(--color-accent, #2563eb);
+  border-color: var(--color-accent, #2563eb);
+  background: rgba(37, 99, 235, 0.06);
+}
+.user-book-detail__reextract-icon:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.user-book-detail__reextract-icon:disabled svg {
+  animation: user-book-detail__spin 1s linear infinite;
+}
+@keyframes user-book-detail__spin {
+  to { transform: rotate(360deg); }
+}
+
 /* Trash icon in the primary action row. Idle styling matches the neighbour
    icon buttons (Add-to-collection, Link, Share) — neutral border so the
    destructive action doesn't shout. Two-stage confirm (see *--confirming
diff --git a/backend/src/Application/UserBooks/UserBookService.cs b/backend/src/Application/UserBooks/UserBookService.cs
index 3e2e2521..8a99e3ae 100644
--- a/backend/src/Application/UserBooks/UserBookService.cs
+++ b/backend/src/Application/UserBooks/UserBookService.cs
@@ -327,8 +327,12 @@ public async Task<IReadOnlyList<UserBookListDto>> GetBooksAsync(Guid userId, Can
         if (book is null)
             return (false, "Book not found");
 
-        if (book.Status != UserBookStatus.Failed)
-            return (false, "Only failed books can be retried");
+        // Allow retrying Failed (original behaviour) AND re-extracting Ready
+        // books — extractor improvements (e.g. bullet paragraph split, TOC
+        // drop) should be reachable without a delete+reupload roundtrip.
+        // Processing is excluded so we don't queue duplicate jobs.
+        if (book.Status != UserBookStatus.Failed && book.Status != UserBookStatus.Ready)
+            return (false, $"Cannot reprocess book in status {book.Status}");
 
         var bookFile = book.BookFiles.FirstOrDefault();
         if (bookFile is null)
diff --git a/backend/src/Extraction/TextStack.Extraction/Extractors/FrontMatterFilter.cs b/backend/src/Extraction/TextStack.Extraction/Extractors/FrontMatterFilter.cs
new file mode 100644
index 00000000..178214d4
--- /dev/null
+++ b/backend/src/Extraction/TextStack.Extraction/Extractors/FrontMatterFilter.cs
@@ -0,0 +1,29 @@
+using System.Text.RegularExpressions;
+
+namespace TextStack.Extraction.Extractors;
+
+/// <summary>
+/// Identifies low-value front-matter chapter titles that should be dropped at
+/// extraction time. Right now: only "Table of Contents" (and translated
+/// variants) — TOC chapters from PDFs come out as a flat run of leader-dotted
+/// entries with no usable line breaks; they add nothing to the in-app TOC
+/// (which we generate from the chapter list itself) and just waste a click.
+/// Kept narrow on purpose — adding e.g. "Copyright" or "Index" here would
+/// silently drop content some users want to keep.
+/// </summary>
+public static class FrontMatterFilter
+{
+    private static readonly Regex TocTitle = new(
+        @"^\s*(table\s+of\s+contents?|contents|toc|" +
+        @"оглавление|содержание|зміст|" +
+        @"sommaire|inhaltsverzeichnis|índice|indice|sumário)\s*$",
+        RegexOptions.IgnoreCase | RegexOptions.Compiled);
+
+    public static bool IsTableOfContents(string? title)
+    {
+        if (string.IsNullOrWhiteSpace(title)) return false;
+        // Tolerate trailing numbers/page refs the bookmark sometimes carries.
+        var normalized = Regex.Replace(title, @"\s*\d+\s*$", "").Trim();
+        return TocTitle.IsMatch(normalized);
+    }
+}
diff --git a/backend/src/Extraction/TextStack.Extraction/Extractors/Pdf/PdfPageTextExtractor.cs b/backend/src/Extraction/TextStack.Extraction/Extractors/Pdf/PdfPageTextExtractor.cs
index 9ccb4de5..21629a22 100644
--- a/backend/src/Extraction/TextStack.Extraction/Extractors/Pdf/PdfPageTextExtractor.cs
+++ b/backend/src/Extraction/TextStack.Extraction/Extractors/Pdf/PdfPageTextExtractor.cs
@@ -26,6 +26,15 @@ public static class PdfPageTextExtractor
         "|", "•", "·", "—", "-", "–", "*", "■", "□", "○", "●", "▪", "▫"
     };
 
+    // Glyphs that, when they're the first word of a line, mean the line is a
+    // bullet-list item — force a new paragraph regardless of vertical gap.
+    // Without this, tightly-spaced lists in PDFs get glued into one giant
+    // paragraph (the "•" loses its line-break role when only y-gap is used).
+    private static readonly HashSet<string> BulletGlyphs = new(StringComparer.Ordinal)
+    {
+        "•", "●", "▪", "■", "◦", "○", "▫", "◆", "‣", "⁃", "►", "❖"
+    };
+
     private static readonly Regex PageNumberPattern = new(@"^\d{1,4}$", RegexOptions.Compiled);
 
     // Running headers from O'Reilly-style tech books take the shape
@@ -221,7 +230,7 @@ private static List<List<List<Word>>> GroupLinesIntoParagraphs(List<List<Word>>
             var currY = lines[i].Average(w => w.BoundingBox.Bottom);
             var gap = Math.Abs(prevY - currY);
 
-            if (gap > paragraphGapThreshold)
+            if (gap > paragraphGapThreshold || StartsWithBulletGlyph(lines[i]))
             {
                 paragraphs.Add(currentParagraph);
                 currentParagraph = [lines[i]];
@@ -236,6 +245,27 @@ private static List<List<List<Word>>> GroupLinesIntoParagraphs(List<List<Word>>
         return paragraphs;
     }
 
+    /// <summary>
+    /// True if the first word of the line is (or begins with) a bullet glyph —
+    /// •, ●, ▪, ◦, etc. Lines like "• You're building..." should always start a
+    /// fresh paragraph, even if the y-gap from the previous line is normal.
+    /// </summary>
+    internal static bool StartsWithBulletGlyph(List<Word> line)
+    {
+        if (line.Count == 0) return false;
+        return IsBulletPrefix(line[0].Text);
+    }
+
+    /// <summary>Test-visible string form of <see cref="StartsWithBulletGlyph"/>.</summary>
+    internal static bool IsBulletPrefix(string? text)
+    {
+        if (string.IsNullOrEmpty(text)) return false;
+        if (BulletGlyphs.Contains(text)) return true;
+        // Some PDFs glue the bullet to the first word ("•You're").
+        var firstChar = text[0].ToString();
+        return BulletGlyphs.Contains(firstChar);
+    }
+
     private static string GetDominantFontName(List<Word> words)
     {
         var fontCounts = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);
diff --git a/backend/src/Extraction/TextStack.Extraction/Extractors/PdfTextExtractor.cs b/backend/src/Extraction/TextStack.Extraction/Extractors/PdfTextExtractor.cs
index 46864647..b0c72782 100644
--- a/backend/src/Extraction/TextStack.Extraction/Extractors/PdfTextExtractor.cs
+++ b/backend/src/Extraction/TextStack.Extraction/Extractors/PdfTextExtractor.cs
@@ -142,6 +142,18 @@ private static ExtractionResult ExtractFromDocument(
             var chapter = chapters[chapterIdx];
             var chapterNumber = chapterIdx + 1;
 
+            // Drop TOC chapters at extraction time. PDF TOCs come out as one
+            // dense run of leader-dotted entries (see fix/pdf-bullet-paragraph-split
+            // discussion) and we already build the reader-side TOC from the
+            // chapter list itself, so the chapter is pure noise.
+            if (FrontMatterFilter.IsTableOfContents(chapter.Title))
+            {
+                warnings.Add(new ExtractionWarning(
+                    ExtractionWarningCode.ContentFiltered,
+                    $"Skipped Table of Contents chapter: {chapter.Title}"));
+                continue;
+            }
+
             try
             {
                 // Extract pages for this chapter
diff --git a/tests/TextStack.Extraction.Tests/FrontMatterFilterTests.cs b/tests/TextStack.Extraction.Tests/FrontMatterFilterTests.cs
new file mode 100644
index 00000000..22cc9481
--- /dev/null
+++ b/tests/TextStack.Extraction.Tests/FrontMatterFilterTests.cs
@@ -0,0 +1,41 @@
+using TextStack.Extraction.Extractors;
+
+namespace TextStack.Extraction.Tests;
+
+public class FrontMatterFilterTests
+{
+    [Theory]
+    [InlineData("Table of Contents")]
+    [InlineData("table of contents")]
+    [InlineData("TABLE OF CONTENTS")]
+    [InlineData("Contents")]
+    [InlineData("CONTENTS")]
+    [InlineData("TOC")]
+    [InlineData("Оглавление")]
+    [InlineData("Содержание")]
+    [InlineData("Зміст")]
+    [InlineData("  Contents  ")]
+    [InlineData("Contents 5")]   // bookmark sometimes carries a page ref
+    [InlineData("Table of Contents 7")]
+    public void IsTableOfContents_Matches_KnownTocTitles(string title)
+    {
+        Assert.True(FrontMatterFilter.IsTableOfContents(title));
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData(null)]
+    [InlineData("Chapter 1")]
+    [InlineData("Introduction")]
+    [InlineData("Acknowledgments")]
+    [InlineData("Index")]
+    [InlineData("Bibliography")]
+    [InlineData("Glossary")]
+    // "Discontent" contains "content" as substring — anchors must reject this.
+    [InlineData("Discontent")]
+    [InlineData("Table Setting")]
+    public void IsTableOfContents_DoesNotMatch_OtherTitles(string? title)
+    {
+        Assert.False(FrontMatterFilter.IsTableOfContents(title));
+    }
+}
diff --git a/tests/TextStack.Extraction.Tests/PdfPageTextExtractorTests.cs b/tests/TextStack.Extraction.Tests/PdfPageTextExtractorTests.cs
new file mode 100644
index 00000000..d0a83d2c
--- /dev/null
+++ b/tests/TextStack.Extraction.Tests/PdfPageTextExtractorTests.cs
@@ -0,0 +1,32 @@
+using TextStack.Extraction.Extractors.Pdf;
+
+namespace TextStack.Extraction.Tests;
+
+public class PdfPageTextExtractorTests
+{
+    [Theory]
+    [InlineData("•")]
+    [InlineData("●")]
+    [InlineData("▪")]
+    [InlineData("◦")]
+    [InlineData("○")]
+    [InlineData("‣")]
+    [InlineData("⁃")]
+    [InlineData("•You're")]   // bullet glued to first word — still a list item
+    public void IsBulletPrefix_RecognizesBulletGlyphs(string firstWord)
+    {
+        Assert.True(PdfPageTextExtractor.IsBulletPrefix(firstWord));
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData(null)]
+    [InlineData("You're")]
+    [InlineData("1.")]   // numbered list — left out on purpose, "." is too noisy as a trigger
+    [InlineData("a)")]
+    [InlineData("This")]
+    public void IsBulletPrefix_RejectsNonBulletStarts(string? firstWord)
+    {
+        Assert.False(PdfPageTextExtractor.IsBulletPrefix(firstWord));
+    }
+}

From 9414534e782d6a03647d9de2ef742e9276d5ad1b Mon Sep 17 00:00:00 2001
From: Vasyl Vdovychenko <mrviduus@gmail.com>
Date: Sat, 23 May 2026 13:48:14 -0400
Subject: [PATCH 2/2] =?UTF-8?q?fix(pdf):=20median=20line=20gap=20+=20inden?=
 =?UTF-8?q?t=20=E2=86=92=20robust=20paragraph=20detection?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bullet-only fix in the previous commit only addressed list items.
The broader complaint was paragraph breaks missing everywhere — even
plain body text was glued into one run. Two root causes:

1. mean line gap was the baseline. Paragraph gaps in the data inflate
   the mean above themselves, so the threshold (mean × 1.5) ends up
   higher than any real paragraph gap. Self-defeating statistic.
2. y-gap-only detection. Many books use first-line indent instead of
   vertical paragraph spacing; we ignored indent entirely.

Changes:
- Median replaces mean for baseline gap. The modal spacing on a body
  page is line-height; paragraph gaps stay above the threshold.
- Multiplier 1.5 → 1.2. O'Reilly-style typography uses paragraph spacing
  around 1.25× line height; 1.5× missed them.
- New StartsWithIndent: compute the page's modal left margin, treat a
  line whose left edge is ≥6 pt right of it as a paragraph break.
  Catches indent-only paragraphs that have no y-gap signal at all.
- TOC drop in PdfTextExtractor now requires chapters.Count > 1, so a
  single-chapter book literally titled "Contents" won't disappear
  (PR #244 bug-report guard).

Integration tests build real PDFs (y-gap and indent variants) and
verify the extractor splits them. 259/259 in Extraction.Tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../Extractors/Pdf/PdfPageTextExtractor.cs    | 63 +++++++++++++++--
 .../Extractors/PdfTextExtractor.cs            | 10 +--
 .../Helpers/PdfFixtureGenerator.cs            | 69 +++++++++++++++++++
 .../PdfPageTextExtractorTests.cs              | 52 ++++++++++++++
 4 files changed, 184 insertions(+), 10 deletions(-)

diff --git a/backend/src/Extraction/TextStack.Extraction/Extractors/Pdf/PdfPageTextExtractor.cs b/backend/src/Extraction/TextStack.Extraction/Extractors/Pdf/PdfPageTextExtractor.cs
index 21629a22..3e82d1fb 100644
--- a/backend/src/Extraction/TextStack.Extraction/Extractors/Pdf/PdfPageTextExtractor.cs
+++ b/backend/src/Extraction/TextStack.Extraction/Extractors/Pdf/PdfPageTextExtractor.cs
@@ -14,7 +14,18 @@ namespace TextStack.Extraction.Extractors.Pdf;
 public static class PdfPageTextExtractor
 {
     private const double LineYTolerance = 3.0;
-    private const double ParagraphGapMultiplier = 1.5;
+    // Paragraph break = median line gap × multiplier. Median (not mean) so
+    // the actual paragraph gaps in the data don't pull the threshold above
+    // themselves. 1.2 covers O'Reilly-style 1.25× para-spacing and similar;
+    // 1.5 (the old value) missed almost every paragraph break because the
+    // modal spacing is line-spacing and the mean got dragged up by the rare
+    // gaps the algorithm was supposed to find.
+    private const double ParagraphGapMultiplier = 1.2;
+    // First-line indent: a line whose left edge is at least this many points
+    // greater than the page's modal left margin counts as a new paragraph,
+    // independent of y-gap. Most book typography uses an indent rather than
+    // vertical space — y-gap-only detection misses every one of those.
+    private const double IndentMinPoints = 6.0;
     private const double HeadingFontRatio = 0.9;
     private const double MinHeadingFontDifference = 1.5;
     private const int MaxHeadingTextLength = 200;
@@ -208,18 +219,32 @@ private static List<List<List<Word>>> GroupLinesIntoParagraphs(List<List<Word>>
         if (lines.Count == 0)
             return [];
 
-        var lineHeights = new List<double>();
+        var lineGaps = new List<double>();
         for (var i = 1; i < lines.Count; i++)
         {
             var prevY = lines[i - 1].Average(w => w.BoundingBox.Bottom);
             var currY = lines[i].Average(w => w.BoundingBox.Bottom);
             var gap = Math.Abs(prevY - currY);
             if (gap > 0)
-                lineHeights.Add(gap);
+                lineGaps.Add(gap);
         }
 
-        var avgLineHeight = lineHeights.Count > 0 ? lineHeights.Average() : 12.0;
-        var paragraphGapThreshold = avgLineHeight * ParagraphGapMultiplier;
+        // Median, not mean — paragraph gaps in the data must NOT pull the
+        // threshold up to (or above) themselves. The modal gap on a typical
+        // body page is one line-height; that's exactly what we want as the
+        // baseline.
+        var baselineGap = Median(lineGaps, fallback: 12.0);
+        var paragraphGapThreshold = baselineGap * ParagraphGapMultiplier;
+
+        // Modal left margin: rounded so micro-jitter (sub-point alignment
+        // differences) doesn't disqualify a margin from being modal.
+        var leftEdges = lines
+            .Where(l => l.Count > 0)
+            .Select(l => Math.Round(l.Min(w => w.BoundingBox.Left)))
+            .ToList();
+        var baseLeft = leftEdges.Count > 0
+            ? leftEdges.GroupBy(e => e).OrderByDescending(g => g.Count()).First().Key
+            : 0.0;
 
         var paragraphs = new List<List<List<Word>>>();
         var currentParagraph = new List<List<Word>> { lines[0] };
@@ -230,7 +255,11 @@ private static List<List<List<Word>>> GroupLinesIntoParagraphs(List<List<Word>>
             var currY = lines[i].Average(w => w.BoundingBox.Bottom);
             var gap = Math.Abs(prevY - currY);
 
-            if (gap > paragraphGapThreshold || StartsWithBulletGlyph(lines[i]))
+            var isYGapBreak = gap > paragraphGapThreshold;
+            var isBulletBreak = StartsWithBulletGlyph(lines[i]);
+            var isIndentBreak = StartsWithIndent(lines[i], baseLeft);
+
+            if (isYGapBreak || isBulletBreak || isIndentBreak)
             {
                 paragraphs.Add(currentParagraph);
                 currentParagraph = [lines[i]];
@@ -245,6 +274,28 @@ private static List<List<List<Word>>> GroupLinesIntoParagraphs(List<List<Word>>
         return paragraphs;
     }
 
+    /// <summary>
+    /// True if the line's left edge sits at least <see cref="IndentMinPoints"/>
+    /// further right than the modal left margin — the textbook signature of a
+    /// first-line indent and therefore a paragraph break.
+    /// </summary>
+    internal static bool StartsWithIndent(List<Word> line, double baseLeft)
+    {
+        if (line.Count == 0) return false;
+        var left = line.Min(w => w.BoundingBox.Left);
+        return left - baseLeft >= IndentMinPoints;
+    }
+
+    private static double Median(List<double> values, double fallback)
+    {
+        if (values.Count == 0) return fallback;
+        var sorted = values.OrderBy(v => v).ToList();
+        var mid = sorted.Count / 2;
+        return sorted.Count % 2 == 0
+            ? (sorted[mid - 1] + sorted[mid]) / 2.0
+            : sorted[mid];
+    }
+
     /// <summary>
     /// True if the first word of the line is (or begins with) a bullet glyph —
     /// •, ●, ▪, ◦, etc. Lines like "• You're building..." should always start a
diff --git a/backend/src/Extraction/TextStack.Extraction/Extractors/PdfTextExtractor.cs b/backend/src/Extraction/TextStack.Extraction/Extractors/PdfTextExtractor.cs
index b0c72782..1566ba1b 100644
--- a/backend/src/Extraction/TextStack.Extraction/Extractors/PdfTextExtractor.cs
+++ b/backend/src/Extraction/TextStack.Extraction/Extractors/PdfTextExtractor.cs
@@ -143,10 +143,12 @@ private static ExtractionResult ExtractFromDocument(
             var chapterNumber = chapterIdx + 1;
 
             // Drop TOC chapters at extraction time. PDF TOCs come out as one
-            // dense run of leader-dotted entries (see fix/pdf-bullet-paragraph-split
-            // discussion) and we already build the reader-side TOC from the
-            // chapter list itself, so the chapter is pure noise.
-            if (FrontMatterFilter.IsTableOfContents(chapter.Title))
+            // dense run of leader-dotted entries and we already build the
+            // reader-side TOC from the chapter list itself. Guard: never drop
+            // the only chapter — a single-chapter book literally titled
+            // "Contents" would otherwise vanish entirely (paranoid edge case
+            // raised in PR #244 bug report).
+            if (chapters.Count > 1 && FrontMatterFilter.IsTableOfContents(chapter.Title))
             {
                 warnings.Add(new ExtractionWarning(
                     ExtractionWarningCode.ContentFiltered,
diff --git a/tests/TextStack.Extraction.Tests/Helpers/PdfFixtureGenerator.cs b/tests/TextStack.Extraction.Tests/Helpers/PdfFixtureGenerator.cs
index 8f70f8f6..7edf69ac 100644
--- a/tests/TextStack.Extraction.Tests/Helpers/PdfFixtureGenerator.cs
+++ b/tests/TextStack.Extraction.Tests/Helpers/PdfFixtureGenerator.cs
@@ -169,4 +169,73 @@ public static byte[] GenerateEmptyPdf()
         builder.AddPage(UglyToad.PdfPig.Content.PageSize.A4);
         return builder.Build();
     }
+
+    /// <summary>
+    /// Builds a one-page PDF whose lines are arranged like book typography:
+    /// paragraph A (3 lines at line-spacing), wider gap, paragraph B (3 lines
+    /// at line-spacing). Used to verify paragraph-gap detection.
+    /// </summary>
+    public static byte[] GeneratePdfWithTwoParagraphs(double lineSpacing = 14, double paragraphSpacing = 20)
+    {
+        var builder = new PdfDocumentBuilder();
+        var font = builder.AddStandard14Font(UglyToad.PdfPig.Fonts.Standard14Fonts.Standard14Font.Helvetica);
+        var page = builder.AddPage(UglyToad.PdfPig.Content.PageSize.A4);
+
+        double y = 750;
+        // Paragraph A — three lines.
+        page.AddText("Paragraph A line one with several words to fill the line.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(72, y), font);
+        y -= lineSpacing;
+        page.AddText("Paragraph A line two continues with more content here.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(72, y), font);
+        y -= lineSpacing;
+        page.AddText("Paragraph A line three closing the first thought.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(72, y), font);
+        // Paragraph gap.
+        y -= paragraphSpacing;
+        page.AddText("Paragraph B starts here with a fresh idea entirely.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(72, y), font);
+        y -= lineSpacing;
+        page.AddText("Paragraph B line two continues the second thought.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(72, y), font);
+        y -= lineSpacing;
+        page.AddText("Paragraph B line three closes the page nicely.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(72, y), font);
+
+        return builder.Build();
+    }
+
+    /// <summary>
+    /// One page, all lines at line-spacing (no vertical paragraph gap), but
+    /// paragraph B's first line is indented. Verifies indent-based detection.
+    /// </summary>
+    public static byte[] GeneratePdfWithIndentedParagraph(double lineSpacing = 14, double indent = 12)
+    {
+        var builder = new PdfDocumentBuilder();
+        var font = builder.AddStandard14Font(UglyToad.PdfPig.Fonts.Standard14Fonts.Standard14Font.Helvetica);
+        var page = builder.AddPage(UglyToad.PdfPig.Content.PageSize.A4);
+
+        double y = 750;
+        const double baseLeft = 72;
+        page.AddText("Paragraph A line one filling the typical content area.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(baseLeft, y), font);
+        y -= lineSpacing;
+        page.AddText("Paragraph A line two flush left as the body continues.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(baseLeft, y), font);
+        y -= lineSpacing;
+        page.AddText("Paragraph A line three still aligned to the same margin.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(baseLeft, y), font);
+        y -= lineSpacing;
+        // Indented first line of paragraph B.
+        page.AddText("Paragraph B indented start opening the new idea here.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(baseLeft + indent, y), font);
+        y -= lineSpacing;
+        page.AddText("Paragraph B line two flush left again as expected.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(baseLeft, y), font);
+        y -= lineSpacing;
+        page.AddText("Paragraph B line three closing the page.", 10,
+            new UglyToad.PdfPig.Core.PdfPoint(baseLeft, y), font);
+
+        return builder.Build();
+    }
 }
diff --git a/tests/TextStack.Extraction.Tests/PdfPageTextExtractorTests.cs b/tests/TextStack.Extraction.Tests/PdfPageTextExtractorTests.cs
index d0a83d2c..bddb8e1e 100644
--- a/tests/TextStack.Extraction.Tests/PdfPageTextExtractorTests.cs
+++ b/tests/TextStack.Extraction.Tests/PdfPageTextExtractorTests.cs
@@ -1,4 +1,6 @@
 using TextStack.Extraction.Extractors.Pdf;
+using TextStack.Extraction.Tests.Helpers;
+using UglyToad.PdfPig;
 
 namespace TextStack.Extraction.Tests;
 
@@ -29,4 +31,54 @@ public void IsBulletPrefix_RejectsNonBulletStarts(string? firstWord)
     {
         Assert.False(PdfPageTextExtractor.IsBulletPrefix(firstWord));
     }
+
+    [Fact]
+    public void StartsWithIndent_EmptyLine_ReturnsFalse()
+    {
+        // PdfPig Word objects can't be synthesized here without a backing
+        // PdfDocument — the integration-level tests below cover the positive
+        // case. This guards the documented behaviour for empty input.
+        Assert.False(PdfPageTextExtractor.StartsWithIndent([], baseLeft: 72));
+    }
+
+    // Standard14 Helvetica word-spacing in PdfPig output is wider than ASCII
+    // " " — words come out separated by multiple whitespace chars. Match on
+    // content rather than exact whitespace so tests track intent, not the
+    // PdfPig font quirk.
+    private static string Normalize(string text) =>
+        System.Text.RegularExpressions.Regex.Replace(text, @"\s+", " ").Trim();
+
+    [Fact]
+    public void ExtractPage_TwoParagraphsByVerticalGap_AreSplit()
+    {
+        // lineSpacing=14, paragraphSpacing=20 → ratio 1.43.
+        // Median gap is 14; threshold = 14 × 1.2 = 16.8 → 20 > 16.8 → split.
+        // The old mean+1.5 path computed mean≈15 (one 20 + four 14s),
+        // threshold = 22.5, would NOT have split.
+        var pdfBytes = PdfFixtureGenerator.GeneratePdfWithTwoParagraphs(
+            lineSpacing: 14, paragraphSpacing: 20);
+        using var doc = PdfDocument.Open(pdfBytes);
+        var elements = PdfPageTextExtractor.ExtractPage(doc.GetPage(1));
+
+        Assert.Equal(2, elements.Count);
+        Assert.StartsWith("Paragraph A", Normalize(elements[0].Text));
+        Assert.StartsWith("Paragraph B", Normalize(elements[1].Text));
+    }
+
+    [Fact]
+    public void ExtractPage_IndentedFirstLine_StartsNewParagraph()
+    {
+        // All lines at line-spacing — no vertical signal at all.
+        // Paragraph B's first line is shifted 12pt right (typical book indent).
+        var pdfBytes = PdfFixtureGenerator.GeneratePdfWithIndentedParagraph(
+            lineSpacing: 14, indent: 12);
+        using var doc = PdfDocument.Open(pdfBytes);
+        var elements = PdfPageTextExtractor.ExtractPage(doc.GetPage(1));
+
+        Assert.True(elements.Count >= 2,
+            $"expected ≥2 paragraphs, got {elements.Count}: " +
+            string.Join(" | ", elements.Select(e => e.Text)));
+        // Some paragraph must start with "Paragraph B" (the indented start).
+        Assert.Contains(elements, e => Normalize(e.Text).StartsWith("Paragraph B"));
+    }
 }