# PDF-CLI TODO List
This document tracks the planned features, improvements, and tasks for the PDF-CLI project.
## Priority Legend
- 🔴 **Critical**: Must-have for core functionality
- 🟡 **High**: Important features that significantly improve the tool
- 🟢 **Medium**: Nice-to-have features and enhancements
- 🔵 **Low**: Future considerations and minor improvements
---
## Phase 1: Core Functionality (Current Development)
### 🔴 Critical
- [x] Basic PDF generation from text
- [x] PDF parsing and text extraction
- [x] Markdown to PDF conversion
- [x] PDF to Markdown conversion
- [x] CLI interface with subcommands
- [x] Font selection (basic Type 1 fonts)
- [x] Multi-page support
- [x] Compression handling (deflate)
- [x] Table rendering from Markdown
### 🟡 High
- [x] Better text extraction with PDF operator handling
- [x] Image support framework
- [x] Error handling improvements
- [x] Performance optimizations
- [x] Roundtrip MD->PDF->MD with complex examples
- [x] PDF stream parsing for Tj text operators
- [x] Escaped parentheses handling in PDF strings
- [x] Integration tests for roundtrip validation (17 test cases)
- [x] Complex PDF generation examples validated via round-trip:
- [x] `full_features.md` — all 17 element types (10KB, 6 pages)
- [x] `technical_report_complex.md` — dense tables, multi-language code, nested lists (23KB, 6+ pages)
- [x] `api_reference_complex.md` — definitions, footnotes, code examples, feature matrix (28KB, 8+ pages)
- [x] `math_and_formulas.md` — LaTeX math blocks/inline, code blocks, tables, formulas (27KB, 14 pages)
- [x] Library API integration tests (generate_pdf_bytes + validate_pdf_bytes, portrait + landscape batch)
- [x] Math parsing library API test (MathBlock + MathInline element detection + PDF generation)
---
## Phase 2: Enhanced Features
### 🔴 Critical
- [x] Complete image support implementation
- [x] JPEG embedding with proper positioning (DCTDecode)
- [x] PNG dimension parsing
- [x] BMP dimension parsing
- [x] Image scaling and optimization (aspect-ratio preserving)
- [x] CLI add-image command wired up
- [x] PNG pixel data embedding
- [x] BMP pixel data embedding
### 🟡 High
- [x] Advanced PDF parsing
- [x] Font encoding handling (WinAnsiEncoding, MacRomanEncoding)
- [x] Text positioning and layout analysis (Td/Tm operator tracking)
- [x] TJ array operator support for text extraction
- [x] Improved dictionary parsing
- [x] Octal escape handling in PDF strings
- [x] Cross-reference stream parsing (for PDF 1.5+) — `parse_xref_stream` with /W field widths
- [x] Object stream handling — `parse_object_stream` for /Type /ObjStm
- [x] Enhanced Markdown features
- [x] Task list support
- [x] Footnotes and references (definitions + inline ref stripping)
- [x] Definition lists
- [x] Strikethrough text
- [x] Blockquote support (nested)
- [x] Tables with alignment parsing (left/center/right)
- [x] PDF generation improvements
- [x] Text justification and alignment (H1 centered, TextAlign enum)
- [x] Page numbering
- [x] Header font size hierarchy (H1-H6)
- [x] Code block reduced font size with background, border, and page-break support
- [x] Horizontal rule rendering
- [x] Watermarks — `watermark` CLI command (diagonal text, configurable opacity/size)
- [x] Page orientation (landscape/portrait) with --landscape CLI flag
- [x] Math/formula rendering (MathBlock with blue background + accent border, MathInline italic)
- [x] LaTeX-to-text math conversion (Greek letters, operators, fractions, integrals, sums, limits)
- [x] Fixed font object ID references in PDF assembly
- [x] Fixed table rendering crash with ragged row column counts
### 🟢 Medium
- [ ] Font improvements
- [ ] Embedded font support
- [ ] TrueType font handling
- [x] Font size variations within document (headers, code blocks)
- [x] Text color support — `Color` struct (RGB), code blocks in gray
- [x] Security features
- [x] Password protection — `PdfSecurity` with user/owner passwords
- [x] User/owner permissions — `PdfPermissions` with PDF 1.7 compliance
- [ ] Digital signatures
- [ ] Performance improvements
- [ ] Memory usage optimization
- [ ] Faster PDF parsing
- [ ] Streaming processing for large files
- [ ] Parallel processing where applicable
---
## Phase 3.5: Advanced Features (Surpassing Ghostscript)
### 🔴 Critical (Competitive Advantages)
#### FR12: Streaming & Incremental Processing
- [ ] **FR12.1**: Streaming PDF generation trait
```rust
pub trait StreamingPdfGenerator {
fn generate_streaming(&mut self, elements: &[Element]) -> Stream<Page>;
}
```
- [ ] **FR12.2**: Page-by-page lazy loading
```rust
pub fn render_page_range(&mut self, elements: &[Element], range: Range<usize>) -> Result<Vec<Page>>;
```
- [ ] **FR12.3**: Incremental PDF writing (write pages as generated)
```rust
pub fn create_pdf_streaming(filename: &str, elements: &[Element]) -> Result<()>;
```
- [ ] **FR12.4**: Lazy PDF document (load pages on-demand)
```rust
pub struct LazyPdfDocument { }
```
#### FR13: Performance & Parallelism
- [ ] **FR13.1**: Add `rayon` dependency for parallelism
- [ ] **FR13.2**: Parallel page rendering with `par_iter()`
- [ ] **FR13.3**: Parallel PDF merging (load inputs concurrently)
- [ ] **FR13.4**: SIMD text width calculations
- [ ] **FR13.5**: Async PDF API for web servers (`tokio`)
#### FR15: Developer Experience
- [ ] **FR15.1**: Builder API with fluent interface
```rust
PdfBuilder::new().with_layout(PageLayout::landscape()).build()?;
```
- [ ] **FR15.2**: Property-based testing with `proptest`
- [ ] **FR15.3**: Diff/patch support for version control
- [ ] **FR15.4**: Hot-reload during development
- [ ] **FR15.5**: Interactive REPL for PDF manipulation
#### FR18: Intelligent Optimization
- [ ] **FR18.1**: Smart content-aware compression
- [ ] **FR18.2**: Font subsetting to reduce file size
- [ ] **FR18.3**: Object deduplication across pages
- [ ] **FR18.4**: Optimization profiles (web, print, archive, ebook)
### 🟡 High Impact
#### FR14: Smart Content Analysis
- [ ] **FR14.1**: Structure detection (headings, sections, tables)
- [ ] **FR14.2**: Table extraction to CSV/Excel formats
- [ ] **FR14.3**: Form field detection and filling
- [ ] **FR14.4**: Content-aware image compression
- [ ] **FR14.5**: PDF/A validation and conversion
#### FR16: WebAssembly Support
- [ ] **FR16.1**: Add `wasm-bindgen` and `wasm-pack`
- [ ] **FR16.2**: WASM-compatible API
```rust
#[wasm_bindgen]
pub fn render_markdown_to_pdf(md: &str) -> Result<Vec<u8>, JsValue>;
```
- [ ] **FR16.3**: JavaScript bindings and npm package
- [ ] **FR16.4**: Canvas-based PDF viewer in browser
### 🟢 Medium
#### FR17: Advanced Format Support
- [ ] **FR17.1**: PDF 2.0 specification features
- [ ] **FR17.2**: PDF/A-3 and PDF/UA (accessibility)
- [ ] **FR17.3**: Embedded file attachments
- [ ] **FR17.4**: PDF portfolios and collections
- [ ] **FR17.5**: 3D annotations (U3D)
#### FR19: Security
- [ ] **FR19.1**: Malformed PDF sanitization
- [ ] **FR19.2**: JavaScript action sandbox
- [ ] **FR19.3**: Digital signature creation/verification
- [ ] **FR19.4**: Certificate management
---
## Quick Wins (This Session)
### High Impact, Low Complexity
1. ✅ **Table border rendering** (COMPLETED)
2. ✅ **Code block text visibility** (COMPLETED)
3. ✅ **Text wrapping** (COMPLETED)
4. ⏳ **FR12.3**: Streaming PDF write
5. ⏳ **FR13.3**: Parallel PDF merge
6. ⏳ **FR15.1**: Builder API
7. ⏳ **FR18.4**: Optimization profiles
---
## Phase 3: Advanced Features
### 🟡 High
- [x] PDF manipulation features
- [x] PDF merging (combine multiple PDFs) — `merge` CLI command
- [x] PDF splitting (extract pages) — `split` CLI command
- [x] Page reordering — `reorder` CLI command (comma-separated page order)
- [x] Page rotation — `rotate` CLI command (0/90/180/270°)
- [x] Advanced image features
- [ ] Image filters and effects
- [x] Multiple images per page — `create_pdf_with_images` API
- [x] Image overlay and watermarking
- [ ] Vector graphics support
- [x] Form and annotation support
- [x] Interactive form fields
- [x] Text annotations — `TextAnnotation` + `create_pdf_with_annotations` API
- [x] Link annotations — `LinkAnnotation` with URI actions
- [x] Highlighting and markup — `HighlightAnnotation` with QuadPoints
### 🟢 Medium
- [x] Metadata handling
- [x] Document properties (title, author, subject, keywords) — `md-to-pdf-meta` CLI
- [x] Producer tag (pdf-cli)
- [x] Custom metadata fields
- [x] Metadata preservation during conversion
- [x] Accessibility features
- [x] Tagged PDF structure types (`StructureType` enum, 35 types)
- [x] `StructureElement` tree with alt_text, actual_text
- [x] `element_to_structure()` mapping for all Element variants
- [x] `AccessibilityOptions` builder (tagged_pdf, language, title)
- [ ] Full tagged PDF generation in output
- [ ] Screen reader compliance testing
- [ ] Localization
- [ ] Multi-language error messages
- [ ] Locale-specific formatting
- [ ] RTL text support
---
## Phase 4: Ecosystem and Integration
### 🟡 High
- [x] Library API
- [x] Crate for use as a library (`pdf-rs` with `pub mod` exports)
- [x] `generate_pdf_bytes()` — in-memory PDF generation without filesystem
- [x] `validate_pdf()` / `validate_pdf_bytes()` — structural PDF validation
- [x] `PdfValidation` result struct (errors, warnings, page_count, object_count)
- [x] Rich `Element` enum with 19 variants for document modeling (including MathBlock, MathInline)
- [ ] Rust API documentation (rustdoc with examples)
- [ ] Example usage patterns (examples/ directory)
- [ ] Plugin system
- [ ] Plugin architecture
- [ ] Custom parser plugins
- [ ] Custom generator plugins
- [ ] Third-party integrations
### 🟢 Medium
- [ ] WebAssembly support
- [ ] Compile to WASM
- [ ] Browser-based PDF processing
- [ ] Web interface
- [ ] Cloud integration
- [ ] Cloud storage providers
- [ ] Batch processing
- [ ] REST API wrapper
---
## Quality and Maintenance Tasks
### 🔴 Critical
- [x] Comprehensive test suite (272 tests: 126 lib + 112 bin + 22 integration + 12 doc-tests)
- [x] Unit tests for all modules (pdf, pdf_generator, pdf_ops, elements, markdown, image, compression)
- [x] Integration tests for workflows (roundtrip, merge, split, rotate, watermark, reorder, metadata)
- [x] Round-trip validation tests (generate → validate → parse → verify all element types)
- [x] Performance benchmarks (criterion-based)
- [x] Property-based tests (proptest for compression, image, pdf_ops, elements modules)
- [ ] Automated testing pipeline
- [x] Documentation
- [x] README.md with all CLI commands and examples
- [x] ARCHITECTURE.md with module descriptions
- [x] SPEC.md with functional requirements
- [ ] API documentation (rustdoc with examples)
- [ ] User guide
- [ ] Contributing guidelines
### 🟡 High
- [ ] Code quality improvements
- [ ] Code refactoring for maintainability
- [ ] Error handling consistency
- [ ] Memory safety verification
- [ ] Security audit
- [ ] CI/CD improvements
- [ ] Automated testing on multiple platforms
- [ ] Automated release process
- [ ] Performance regression testing
- [ ] Dependency vulnerability scanning
### 🟢 Medium
- [ ] Monitoring and analytics
- [ ] Usage statistics
- [ ] Performance metrics
- [ ] Error tracking
- [ ] User feedback collection
---
## Research and Investigation
### 🔵 Low
- [ ] PDF 2.0 specification research
- [ ] Advanced compression algorithms
- [ ] Machine learning for OCR integration
- [ ] Vector graphics (SVG) support
- [ ] 3D PDF support investigation
---
## Long-term Vision
### Future Considerations
- [ ] Full PDF 2.0 compliance
- [ ] GUI application
- [ ] Mobile app development
- [ ] Enterprise features
- [ ] Educational content and tutorials
---
## Timeline Estimates
### Phase 1 (Q1 2026): Core Foundation
- Core PDF functionality
- Basic CLI interface
- Initial testing
### Phase 2 (Q2 2026): Feature Enhancement
- Advanced parsing and generation
- Image support
- Performance improvements
### Phase 3 (Q3-Q4 2026): Advanced Features
- PDF manipulation
- Security features
- Form and annotation support
### Phase 4 (Q1 2027): Ecosystem
- Library API
- Plugin system
- WebAssembly support
---
## Resource Planning
### Team Structure (Future)
- **Core Developers**: PDF spec experts, Rust developers
- **QA Engineers**: Testing and quality assurance
- **Documentation Writers**: User guides and API docs
- **Community Managers**: User support and feedback
### Technology Stack
- **Core**: Rust (for performance and safety)
- **Testing**: Rust testing framework, property testing
- **CI/CD**: GitHub Actions or similar
- **Documentation**: Markdown, mdBook
- **Distribution**: Cargo, crates.io
---
## Risk Assessment
### Technical Risks
- **PDF Complexity**: The PDF specification is vast and complex
- **Performance**: Large file processing may be challenging
- **Compatibility**: Ensuring broad PDF format support
### Mitigation Strategies
- **Incremental Development**: Build features incrementally
- **Community Involvement**: Leverage community knowledge
- **Extensive Testing**: Comprehensive test coverage
---
## Success Metrics
### Technical Metrics
- **Performance**: <1s for 1MB PDF processing
- **Memory**: <100MB for typical operations
- **Compatibility**: Support for 90% of common PDFs
### User Metrics
- **Adoption**: Growing user base
- **Contributions**: Community involvement
- **Issues**: Low bug rate, quick resolution
---
This TODO list serves as a roadmap for the PDF-CLI project, guiding development priorities and ensuring a structured approach to feature implementation and quality improvement.