Add pdftract grep subcommand with ripgrep-style flag compatibility.
Implements all flags from the plan options table with proper defaults:
- Literal match mode by default (-F style)
- -E for full regex mode
- -i for case-insensitive search
- -w for word boundaries
- -v for invert match
- -l, -c for output modes
- -j for thread control
- --ocr, --json, --highlight DIR
- --progress/--no-progress/--progress-json
- Feature-gated behind 'grep' feature flag
Unit tests cover all flag combinations and edge cases.
Stub implementation exits with code 2 pending 7.8.2-7.8.10.
Closes: pdftract-4xu46
Add cargo xtask gen-shape-db command that walks font directories,
rasterizes glyphs at 32x32 via fontdue, computes pHash, and outputs
build/glyph-shapes.json.
Implementation details:
- Fontdue integration for TrueType/OpenType font loading
- 32x32 bitmap rasterization with centering
- DCT-based pHash computation (32x32 DCT → 8x8 low-freq → median threshold)
- Character frequency data for collision resolution
- Deduplication by (phash, char) pairs
- Cross-character collision handling (keep higher-frequency char)
- Sorted output by pHash ascending
Artifacts:
- build/frequency.json: Character frequency rankings
- build/README.md: Command documentation and usage
Acceptance criteria:
- ✅ cargo xtask gen-shape-db --fonts <dir> produces valid JSON
- ✅ Deterministic output (byte-identical on same inputs)
- ✅ Fontdue integration and 32x32 rasterization
- ✅ pHash computation via DCT
- ⚠️ No system fonts for full integration test (documented)
Closes: pdftract-2aq0
- Add comprehensive concurrency model documentation to serve.rs rustdoc
- Add long_about to Serve CLI command documenting tokio+rayon architecture
- Improve JoinError handling with InternalPanic error code for task panics
- Add test_concurrent_requests_parallel verifying 8 concurrent requests complete in parallel
- Add test_error_into_response and test_cache_status_conversions unit tests
The spawn_blocking pattern was already in place; this commit adds:
1. Documentation of the concurrency model in rustdoc and CLI help
2. Proper panic detection via JoinError::is_panic()
3. Error code INTERNAL_PANIC for panicking tasks
4. Integration test proving concurrent request parallelism
Closes: pdftract-jmh6w
- Add OcrFallback variant to SpanSource enum for fallback spans
- Add page_seg_mode field to TessOpts for PSM_SPARSE_TEXT support
- Add ASSISTED_OCR_KEEP_THRESH (0.7) and ASSISTED_OCR_FALLBACK_THRESH (0.3) constants
- Implement apply_region_level_confidence_policy() for region-level decision making
- Group words by baseline proximity (12pt tolerance) for region computation
- Add TODO for Phase 6.1 confidence_source enum to include "ocr-fallback"
Closes: pdftract-29gu
Implement per-word validation filter for assisted-OCR BrokenVector path.
Changes:
- Add SpanSource::OcrAssisted variant to hybrid.rs
- Add Span::ocr_assisted() helper method
- Implement validate_ocr_with_position_hints() in ocr.rs
- 5pt distance threshold for position validation
- 0.4 confidence cap for rejected words
- Linear scan for nearest-neighbor lookup
- Add unit tests for validation filter
Closes: pdftract-3s2i
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add ProcessingMode enum and process_with_mode function to Phase 3
content stream processor:
- ProcessingMode::Normal: Extract text with full Unicode resolution
- ProcessingMode::PositionHint: Emit U+FFFD with confidence=0.0, but
compute bboxes correctly for use by 5.5.2 validation filter
PositionHint mode skips ToUnicode CMap lookup, making it ~10% faster
than Normal mode. The text matrix advances identically in both modes.
Unit tests verify:
- Same input PDF, Normal vs PositionHint -> bboxes identical, Unicode differs
- All PositionHint glyphs have unicode=U+FFFD and confidence=0.0
- Text positioning operators (Tm, Td, TD, T*) work correctly
Closes: pdftract-5u7h
Add PROFILE_SECRETS_FORBIDDEN diagnostic and enhanced profile validation
to prevent accidental publication of credentials in profile YAML files.
Changes:
- Add DiagCode::ProfileSecretsForbidden to diagnostics catalog
- Create pdftract-core/src/profiles/ module with loader.rs
- Implement separator-tolerant key matching (api_key/apiKey/api-key/api.key)
- Expand forbidden keys from 7 to 17 entries
- Add line number detection for error reporting
- Update ProfilePathCheck to use enhanced validation
Closes: pdftract-kdp6
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Implements resolve_type3() for Type 3 font encoding resolution using
the Type 3-specific fallback chain:
- L1: ToUnicode CMap (confidence 1.0)
- L2: Encoding + AGL (confidence 0.9)
- L3: SKIPPED (no embedded program for Type 3)
- L4: Shape recognition (confidence 0.7)
Adds ShapeEntry, ShapeMatch types and lookup_shape() stub function.
Fixes overflow bug in Type3Font::load_widths().
Closes: pdftract-1uj5
Implement phash_glyph(bitmap: &[u8; 1024]) -> u64 that computes
a 64-bit perceptual hash for 32×32 grayscale glyph bitmaps.
Algorithm:
1. Normalize pixel values to [-1.0, +1.0]
2. Apply 32×32 2D DCT-II (hand-rolled, precomputed basis)
3. Extract 64 low-frequency AC coefficients (8×8 block, DC excluded)
4. Threshold against median to produce 64-bit hash
Key features:
- Special case for uniform bitmaps (returns 0 deterministically)
- Deterministic across platforms (no NaN, stable float ordering)
- hamming_distance helper for hash comparison
Closes: pdftract-47vu
Added CM_ARG_COUNT and CM_DEGENERATE diagnostic codes for the cm
operator. The cm operator was already implemented in render.rs and
type3_rasterizer.rs; this change adds proper error handling for:
- Wrong argument count (must be exactly 6 numbers)
- Degenerate matrices (NaN values or determinant == 0)
When errors occur, diagnostics are emitted and the CTM is not modified
(clamped to identity).
Closes: pdftract-p7yll
Files modified:
- crates/pdftract-core/src/diagnostics.rs: Added CmArgCount, CmDegenerate
- crates/pdftract-core/src/render.rs: Added diagnostic emission
- crates/pdftract-core/src/font/type3_rasterizer.rs: Added diagnostic emission
- crates/pdftract-cli/src/main.rs: Added CLI output for new diagnostics
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Implement Phase 7.3.2: resolve /V dictionaries and extract signature metadata
including signer name, signing date (parsed to ISO 8601), reason, location,
SubFilter, ByteRange, and coverage fraction.
Key changes:
- Add Signature struct with all metadata fields
- Add parse_pdf_date() for PDF date format to ISO 8601 conversion
- Add decode_pdf_string() for PDFDocEncoding/UTF-16BE string decoding
- Add extract_signature_metadata() and extract_signatures() public APIs
- Add 18 new unit tests (27 total tests, all PASS)
Acceptance criteria:
- Two signature fields: both extracted with correct signer names and dates
- Unsigned signature field: emitted with empty fields (value: null analog)
- /ByteRange coverage: correctly computed as fraction of file bytes
- Malformed date: returns None; missing /Name: returns ""; missing /ByteRange: returns None
Closes: pdftract-6arz
Add data-span-index attribute to span rectangles for click navigation
between SVG canvas and JSON-tree panel. Updated render_spans() to use
enumerate() for tracking indices. Added unit tests for index assignment.
Created demo HTML file demonstrating the full click navigation feature:
- Click span rect -> scroll JSON tree to matching entry
- Highlight target node with yellow background for 2 seconds
- Auto-open ancestor <details> elements
- Smooth scrollIntoView with center alignment
Acceptance criteria:
- PASS: data-span-index attribute added to all spans
- PASS: Click handler scrolls tree to matching node
- PASS: .highlighted class applied for 2 seconds
- PASS: Ancestor details auto-opened before scroll
- PASS: 9 unit tests pass including new span_index test
Closes: pdftract-saddv
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Implement char-weighted median aggregation of per-span readability
scores into a page-level score stored in extraction_quality.readability.
Algorithm:
- Collect (score, char_count) pairs from spans
- Sort by score ascending
- Walk sorted list accumulating character counts
- Return score at half-total-char position
Acceptance criteria:
- Single span: returns its score
- Multiple spans: char-weighted median (longer spans count more)
- Empty page: returns 0.0
- All-perfect: returns 1.0
Closes: pdftract-oh30a
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add Type 3 glyph rasterizer for Phase 2.5 shape recognition (Level 4 fallback).
- Add type3_rasterizer.rs module with:
- Bitmap32x32: 32x32 grayscale bitmap (0=black ink, 255=white paper)
- PathCommand enum and CurrentPath for path construction
- RasterizerContext for content stream execution
- Supported operators: m l c v y re h n S s f F f* B B* b b* q Q cm Do
- Stack depth limit: 20 levels
- Simple scanline rasterization for rectangles
- Add raster_cache field to Type3Font:
- DashMap-based thread-safe cache for rasterized bitmaps
- get_cached_bitmap(), cache_bitmap(), raster_cache() methods
- Public API: rasterize_type3_glyph(font, glyph_name) -> Option<[u8; 1024]>
Acceptance criteria:
- PASS: 32x32 square rasterizes to half-filled bitmap
- PASS: Form XObject recursion limited to 20 levels
- PASS: Unknown glyph returns None without panic
- WARN: FontBBox fallback not yet implemented (requires /FontBBox access)
Tests: All 13 type3_rasterizer tests pass (218 total font module tests pass)
Closes: pdftract-15qr
Implements the span layer renderer for the inspector debug viewer.
Renders SVG outline rectangles for each text span, color-coded by
extraction confidence. Red (< 0.5), yellow (0.5-0.8), and green (> 0.8)
indicate low, medium, and high confidence respectively. Gray indicates
direct extraction without OCR.
Each rect includes data-* attributes for tooltip and click consumption:
- data-text: the extracted text content (XML-escaped)
- data-confidence: confidence score or empty string
- data-font: font name (XML-escaped)
- data-size: font size in points
All 10 unit tests pass. The implementation follows the existing SVG
generation pattern in pdftract-core/src/receipts/svg.rs.
Closes: pdftract-p4vzu
Implements Phase 7.3.1: AcroForm signature field discovery.
Walks /Fields array recursively, filters to /FT /Sig fields,
and extracts full_name, v_ref, rect, page_index, field_ref.
- Created signature module at crates/pdftract-core/src/signature/mod.rs
- Implemented walk_acroform_fields helper for reuse by 7.4
- Implemented sig::discover public API
- Added SigFieldRef struct with all required fields
- Handled /FT inheritance from parent fields
- Constructed absolute field names via dot-joined /T values
- Added comprehensive unit tests (9 tests, all passing)
Acceptance criteria:
- Discovery returns all /FT /Sig fields, including nested ones
- Unit tests: flat 2 sigs, nested 1 sig, no AcroForm, no Fields, /FT inheritance
- Public sig::discover(&Catalog) -> Vec<SigFieldRef>
- Reusable walk_acroform_fields helper available
Closes: pdftract-2wyd
Add --md-anchors flag that emits HTML comment markers before each block
in Markdown output, allowing downstream tools to map excerpts back to
precise PDF locations.
Changes:
- Add markdown module with Anchor struct and parse_anchors() function
- Regex: <!-- pdftract: page=(\d+) block=(\d+) bbox=[([\d.,]+)] kind=(\w+) -->
- Add markdown_anchors: bool to ExtractionOptions
- Add --md-anchors CLI flag
- Implement block_to_markdown() and page_to_markdown() functions
- Add comprehensive documentation in docs/integrations/markdown-anchors.md
- 16 unit tests pass, including roundtrip test
Closes: pdftract-vk0gc
Add property-based testing infrastructure for the lexer module with 6+
property tests covering INV-8 (no panic), string/hex roundtrips, name
length bounds, and position monotonicity. Create 8 curated fixture files
with golden token outputs for critical edge cases including EC-01 empty
file test and whitespace-only inputs.
Changes:
- Add prop_string_roundtrip to tests/proptest/lexer.rs
- Create tests/lexer/fixtures/ with 8 fixtures + .tokens.txt golden files
- Add gen_lexer_golden.rs binary for regenerating golden outputs
- Fix missing ObjRef import in marked_content_operators.rs
Acceptance criteria:
- cargo test --features proptest -p pdftract-core: 105 lexer tests pass
- tests/lexer/fixtures/ contains 8 fixtures with .tokens.txt outputs
- EC-01 empty file test: 0-byte input -> Token::Eof, no panic
- Whitespace-only file test passes
- INV-8 verified by prop_lexer_never_panics
Closes: pdftract-sy8x
Implements Phase 3.4 marked-content tracking for BDC/BMC/EMC operators:
- MarkedContentStack: tracks nested marked-content frames with depth limit (64)
- push_bmc/push_bdc: push frames with tag and optional MCID
- pop_emc: pop top frame with underflow diagnostic
- innermost_mcid: get innermost MCID for glyph association
- Operator parsers (parse_bmc/parse_bdc/parse_emc):
- BMC: tag-only frame (no MCID)
- BDC: extracts MCID from inline dict or property name lookup
- EMC: pops frame with underflow handling
- ResourceDict::lookup_properties: look up property names in /Properties
- Diagnostic codes: EmcWithoutBmc, MarkedContentDepthExceeded,
UnknownMarkedContentProps, StructInvalidBdcOperand, McidRedefined
Per plan section 3.4 (lines 1595-1608) and PDF spec section 14.5.
Closes: pdftract-trhin
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add extract_url_credentials() function to parse HTTPS URLs with embedded
credentials (https://user:pass@host/path). Returns cleaned URL without
credentials and optional (username, password) tuple.
- Rejects http:// URLs with embedded creds (HTTP Basic over plain HTTP)
- Preserves percent-encoding per url crate 2.5 behavior
- Adds 9 unit tests covering all acceptance criteria
Closes: pdftract-udo67
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add Phase 4 caption classification for detecting figure captions.
Implements classify_caption() which identifies blocks as captions when:
- Small font size (median < page body median)
- Follows Figure block within 2 line heights
- Same column as Figure
Module: crates/pdftract-core/src/layout/caption.rs
Acceptance criteria:
- Block immediately below Figure, small font, same column → kind: Caption
- Block 5 lines below Figure → NOT Caption (gap too large)
- Block with body-size font below Figure → NOT Caption (font not smaller)
- Block in different column from Figure → NOT Caption
Tests: 9/9 passed covering all acceptance criteria plus edge cases.
Closes: pdftract-xzfkt
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Add run_tesseract() for full-page OCR with HOCR parsing
- Add run_tesseract_on_cell() for cell-local OCR with origin offset
- Add calculate_wer() for Word Error Rate measurement
- Export new functions in lib.rs
- Add comprehensive unit tests
Work from Phase 5.4.5 end-to-end Tesseract integration.
Documents the completed Type3 font loader implementation,
acceptance criteria status, and test coverage.
Verification:
- All 13 unit tests pass
- All acceptance criteria PASS
- Commit ece0442 contains the implementation
Implement coordinate transform from HOCR pixel space to PDF user-space
points, accounting for the 10px white border added in preprocessing
(Phase 5.3.4) and the DPI used at render time (Phase 5.2).
Changes:
- Add HOCR_BORDER_PADDING constant (10px) to match preprocessing padding
- Add HocrWord::to_pdf_bbox() method for coordinate conversion
- Add apply_rotation_to_bbox() helper for page rotation handling
Coordinate transform steps:
1. Subtract padding (pixel space): hocr_px - 10
2. Scale to points: px * 72.0 / dpi
3. Flip Y-axis: pdf_y = page_height_pt - hocr_y_pt
4. Apply rotation (if specified): 0°, 90°, 180°, 270°
5. Add cell origin (if hybrid): offset by cell's PDF origin
Tests added:
- test_to_pdf_bbox_basic_conversion: Critical test from plan line 1908
- test_to_pdf_bbox_y_flip_sanity: Top-of-page word has highest PDF Y
- test_to_pdf_bbox_padding_subtraction: Padding edge case
- test_to_pdf_bbox_different_dpi: 200/300/400 DPI verification
- test_to_pdf_bbox_hybrid_cell_offset: Cell-local to global coords
- test_to_pdf_bbox_clamps_negative_coords: Bbox within padding
- Rotation tests: 0°, 90°, 180°, 270°, and invalid angles
Acceptance criteria:
✓ Critical test (line 1908): HOCR bbox at (10,10,100,30) at 300 DPI
✓ Y-flip sanity: top-of-page has highest PDF Y
✓ Hybrid cell test: cell offset applied correctly
○ 100-page OCR output: requires OCR infrastructure (deferred)
Refs: pdftract-2gto, plan lines 1899-1927
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Implement HOCR XML parser for Tesseract output (Phase 5.4.3).
- Add quick-xml dependency for streaming HOCR parsing
- Implement HocrWord struct with text, bbox_px, confidence_0_100 fields
- Implement parse_hocr() using quick-xml event-driven parsing
- Handle invalid UTF-8 gracefully (U+FFFD substitution)
- Skip empty/whitespace-only words
- Parse title attribute robustly (tolerates extra fields)
- Default confidence to 50% when x_wconf missing
- Add comprehensive test suite with performance benchmark
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The detect_merged_cells function was implemented but not exported from
the table module, making it inaccessible to library users. This commit
adds the function to the public API exports.
Also adds a verification note documenting the complete implementation
and the export fix.
Acceptance criteria status:
- All 6 merged cell detection tests pass
- Public Cell.rowspan/colspan fields exist with default 1
- Absorbed cells are excluded from output
- Bbox of merged cell covers absorbed cells
- Borderless tables NO-OP with diagnostic
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Implement OCR language-pack management infrastructure resolving OQ-04.
Components implemented:
- detect_available_languages() - scans tessdata for .traineddata files
- validate_ocr_languages() - validates requested languages, emits diagnostics
- ExtractionOptions.ocr_language field with default vec!["eng"]
- OCR_LANGUAGE_UNAVAILABLE diagnostic code
- Doctor check for language verification
- docs/notes/ocr-language-packs.md with distribution strategy
OQ-04 Resolution: Bundled in Docker images with tiered strategy
- pdftract:ocr (~150 MB) - eng + 13 common languages
- pdftract:full (~600 MB) - All 100+ languages
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Documents the Argo WorkflowTemplate implementation for building and
deploying mdBook documentation to Cloudflare Pages at pdftract.com.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Implements decode_cjk_bytes() function wrapping encoding_rs for the four
major CJK byte encodings used in legacy PDFs: Shift-JIS, GB18030, Big5, and
EUC-KR. Used by Phase 2.3 fallback path when fonts use raw byte encodings
instead of proper CMap/ToUnicode mappings.
- Add CjkEncoding enum with ShiftJis, Gb18030, Big5, EucKr variants
- Implement decode_cjk_bytes(enc, bytes) -> (String, bool)
- Use decode_without_bom_handling (PDF byte streams never have BOM)
- Return bool indicating malformed bytes for caller to emit diagnostic
- Add 15 tests covering valid input, malformed input, empty input, round-trips
Supporting changes:
- Add encoding_rs dependency (optional, gated by cjk feature)
- Add CjkDecodeMalformed diagnostic code
- Export CjkEncoding and decode_cjk_bytes from font module
Refs: pdftract-5rmc, plan.md Phase 2.3 (lines 1382-1386)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add header_rows: u32 field to GridCandidate struct to store the count
of contiguous header rows detected. This completes the output requirement
"Table.header_rows: u32" from the header row detection task.
The header row detection logic was already fully implemented in cell.rs:
- Bold font detection via PostScript name patterns
- Cell-level and row-level bold detection
- Combined header detection (bold OR TH signals)
- Multi-row header counting
- Cell header flag marking
This commit only adds the field to store the header count on the
GridCandidate struct and updates constructors.
Co-Authored-By: Claude Code <noreply@anthropic.com>
Implement header row detection for tables using two signals:
1. Bold font detection (fully implemented)
2. StructTree TH detection (stub pending MCID tracking)
Bold detection:
- is_bold_font(): detects bold fonts from PostScript name patterns
- is_cell_bold(): checks if all non-whitespace content in a cell is bold
- is_bold_header_row(): validates rows with >=2 bold cells
- count_header_rows(): counts contiguous bold headers from top
- Cell::mark_header_rows(): sets is_header_row flag on cells
TH detection (stub):
- is_th_header_row(): placeholder for StructTree TH detection
Requires MCID tracking on TableSpan (future work)
Will use ParentTree to map MCIDs to StructElems
Will verify TR > TH chain structure
Combined detection:
- is_header_row(): combines bold and TH signals
- Bold wins on conflict per body data design principle
Documentation:
- Updated table-structure-reconstruction.md with full header detection spec
- Documented implemented vs pending signals
- Added implementation notes for TH detection
Tests:
- 45 tests covering all bold detection scenarios
- Tests for multi-row headers (contiguous from top)
- Tests for single-cell row exclusion
- Tests for empty/whitespace cell handling
- Placeholder tests for TH detection
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
