fix(extract): address PR review for spatial OCR annotations

- Fall back to plain text when TSV-to-spatial conversion yields empty
- Validate confidence_threshold is 0-100 in config loading
- Detect page breaks in concatenated per-page TSV via block number decrease
- Fix doc comment to mention paragraph breaks
- Add tests for page break detection, spatial fallback, and threshold validation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cpcloud

internal/config/config.go

@@ -579,6 +579,12 @@ func LoadFromPath(path string) (Config, error) {
 		)
 	}
 
+	if t := cfg.Extraction.OCRConfThreshold(); t < 0 || t > 100 {
+		return cfg, fmt.Errorf(
+			"extraction.ocr.confidence_threshold must be 0-100, got %d", t,
+		)
+	}
+
 	checkFilePermissions(&cfg, path)
 
 	return cfg, nil

internal/config/config_test.go

@@ -1424,6 +1424,23 @@ func TestExtractionOCRConfThresholdEnvInvalidReturnsError(t *testing.T) {
 	assert.Contains(t, err.Error(), "MICASA_EXTRACTION_OCR_CONFIDENCE_THRESHOLD")
 }
 
+func TestExtractionOCRConfThresholdOutOfRange(t *testing.T) {
+	t.Parallel()
+	path := writeConfig(t, "[extraction.ocr]\nconfidence_threshold = 101\n")
+	_, err := LoadFromPath(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "extraction.ocr.confidence_threshold")
+	assert.Contains(t, err.Error(), "0-100")
+}
+
+func TestExtractionOCRConfThresholdNegative(t *testing.T) {
+	t.Parallel()
+	path := writeConfig(t, "[extraction.ocr]\nconfidence_threshold = -1\n")
+	_, err := LoadFromPath(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "extraction.ocr.confidence_threshold")
+}
+
 func TestFilePickerDir_FromTOML(t *testing.T) {
 	t.Parallel()
 	dir := t.TempDir()

internal/extract/llmextract.go

@@ -73,13 +73,18 @@ func operationExtractionUserMessage(in ExtractionPromptInput) string {
 	fmt.Fprintf(&b, "Size: %d bytes\n", in.SizeBytes)
 
 	for _, src := range in.Sources {
-		// When SendTSV is enabled and the source has TSV data, send
-		// a compact spatial format (line-level bounding boxes) instead
-		// of reconstructed plain text.
+		// When SendTSV is enabled and the source has TSV data, prefer
+		// a compact spatial format (line-level bounding boxes). If TSV
+		// conversion yields no content (e.g., header-only/invalid TSV),
+		// fall back to the reconstructed plain text.
 		content := strings.TrimSpace(src.Text)
-		hasSpatial := in.SendTSV && len(src.Data) > 0
-		if hasSpatial {
-			content = strings.TrimSpace(SpatialTextFromTSV(src.Data, in.ConfThreshold))
+		hasSpatial := false
+		if in.SendTSV && len(src.Data) > 0 {
+			spatialContent := strings.TrimSpace(SpatialTextFromTSV(src.Data, in.ConfThreshold))
+			if spatialContent != "" {
+				content = spatialContent
+				hasSpatial = true
+			}
 		}
 		if content == "" {
 			continue

internal/extract/llmextract_test.go

@@ -324,6 +324,34 @@ func TestBuildExtractionPrompt_TSVSourceWithoutData(t *testing.T) {
 	assert.Contains(t, user, "Fallback text")
 }
 
+func TestBuildExtractionPrompt_SpatialFallbackOnEmptyTSV(t *testing.T) {
+	t.Parallel()
+	// TSV with only a header (no data rows) should fall back to plain text.
+	headerOnlyTSV := "level\tpage_num\tblock_num\tpar_num\tline_num\tword_num\tleft\ttop\twidth\theight\tconf\ttext\n"
+	msgs := BuildExtractionPrompt(ExtractionPromptInput{
+		DocID:         1,
+		Filename:      "scan.pdf",
+		MIME:          "application/pdf",
+		SendTSV:       true,
+		ConfThreshold: DefaultOCRConfThreshold,
+		Sources: []TextSource{
+			{
+				Tool: "tesseract",
+				Desc: "OCR.",
+				Text: "Fallback plain text",
+				Data: []byte(headerOnlyTSV),
+			},
+		},
+	})
+
+	require.Len(t, msgs, 2)
+	user := msgs[1].Content
+	assert.Contains(t, user, "Fallback plain text",
+		"should fall back to plain text when TSV conversion yields empty")
+	assert.NotContains(t, user, "[",
+		"no bounding boxes when falling back to plain text")
+}
+
 func TestBuildExtractionPrompt_TSVPreambleMentionsSpatial(t *testing.T) {
 	t.Parallel()
 	msgs := BuildExtractionPrompt(ExtractionPromptInput{

internal/extract/ocr.go

@@ -370,8 +370,8 @@ const DefaultOCRConfThreshold = 70
 //
 //	[left,top,width;minConf] word1 word2 ...
 //
-// Lines within the same block/paragraph are separated by newlines; block
-// breaks produce a blank line.
+// Lines within the same block/paragraph are separated by newlines; block or
+// paragraph breaks produce a blank line.
 func SpatialTextFromTSV(tsv []byte, confThreshold int) string {
 	lines := bytes.Split(tsv, []byte("\n"))
 	if len(lines) < 2 {
@@ -436,11 +436,16 @@ func SpatialTextFromTSV(tsv []byte, confThreshold int) string {
 		newLine := firstLine || lineNum != cur.lineNum ||
 			block != cur.block || par != cur.par
 
+		// Detect page breaks in concatenated per-page TSV output.
+		// Each page is OCR'd independently so page_num is always 1;
+		// a decreasing block number signals a new page's data.
+		pageBreak := !firstLine && block < lastBlock
+
 		if !firstLine && newLine {
-			// Insert block/paragraph break before flushing.
-			if block != lastBlock || par != lastPar {
+			// Insert block/paragraph/page break before flushing.
+			if pageBreak || block != lastBlock || par != lastPar {
 				flush()
-				result.WriteByte('\n') // blank line for block break
+				result.WriteByte('\n') // blank line for break
 			} else {
 				flush()
 			}

internal/extract/ocr_test.go

@@ -181,6 +181,33 @@ func TestSpatialTextFromTSV_MixedConfidenceLines(t *testing.T) {
 	assert.Contains(t, lines[1], "Garbled text")
 }
 
+func TestSpatialTextFromTSV_PageBreak(t *testing.T) {
+	t.Parallel()
+	// Simulate concatenated per-page TSV output. Each page is OCR'd
+	// independently, so page_num is always 1. A decreasing block number
+	// (e.g., page 1 ends with block 2, page 2 starts with block 1)
+	// signals a page boundary and should produce a blank line.
+	tsv := []byte(
+		"level\tpage_num\tblock_num\tpar_num\tline_num\tword_num\tleft\ttop\twidth\theight\tconf\ttext\n" +
+			// Page 1, block 1
+			"5\t1\t1\t1\t1\t1\t100\t200\t50\t12\t96\tPage1\n" +
+			// Page 1, block 2
+			"5\t1\t2\t1\t1\t1\t100\t300\t60\t12\t95\tStill1\n" +
+			// Page 2 starts: block resets to 1 (< lastBlock 2) => page break
+			"5\t1\t1\t1\t1\t1\t100\t200\t70\t12\t94\tPage2\n",
+	)
+
+	result := SpatialTextFromTSV(tsv, DefaultOCRConfThreshold)
+	lines := strings.Split(result, "\n")
+	// Expect: "Page1" / "" (block break) / "Still1" / "" (page break) / "Page2"
+	require.Len(t, lines, 5, "expected 5 lines (3 content + 2 blank separators)")
+	assert.Contains(t, lines[0], "Page1")
+	assert.Empty(t, lines[1], "blank line between blocks")
+	assert.Contains(t, lines[2], "Still1")
+	assert.Empty(t, lines[3], "blank line at page break")
+	assert.Contains(t, lines[4], "Page2")
+}
+
 func TestSpatialTextFromTSV_Empty(t *testing.T) {
 	t.Parallel()
 	assert.Empty(t, SpatialTextFromTSV(nil, DefaultOCRConfThreshold))