The typeshare-generated GeneratedTypes.kt was gitignored and never actually used (no #[typeshare] annotations remain in the Rust sources), having been superseded by the uniffi bindings. Remove the whole pipeline: - Gradle: drop the generateKotlinTypes task, the findTypeshareExecutable helper, the dead commented-out compile hook, and the now-unused java.io imports. - justfile: drop the generate-types recipe. - Rust: drop the unused typeshare workspace/lib dependency (and its Cargo.lock entries) and the typeshare.toml config. - android/.gitignore: drop the GeneratedTypes.kt entry. - flake.nix: drop pkgs.typeshare from the dev shell. - docs: delete the obsolete TYPE_GENERATION.md, drop typeshare from BUILD.md and the PDF plan, and remove the stale build TODO. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
15 KiB
15 KiB
PDF Implementation Plan
This document outlines the phased implementation of full-featured PDF functionality for the personal data store app.
Goals
- Display PDFs with excellent rendering of non-Latin scripts and mathematical notation
- Pinch-zoom, pan, and rotate gestures for comfortable reading on phone screens
- Track reading progress (current page, zoom, scroll position) and sync across all nodes
- Bookmark pages with quick switching between bookmarks
- Integrate with the existing sync architecture
Immediate Implementation Steps (MuPDF Migration)
Small, self-contained commits to migrate from Android's native PdfRenderer to MuPDF:
-
Step 1: Add MuPDF dependency (commit
6d2b4ad)- Added
com.artifex.mupdf:fitz:1.27.0toapp/build.gradle.kts - Added Ghostscript Maven repository to
settings.gradle.kts
- Added
-
Step 2: Create MuPDF wrapper class
- Created
MuPdfDocument.ktinpdfs/directory - Wraps MuPDF's Document/Page API with a clean Kotlin interface
- Supports file paths, URIs, and byte arrays (needed for Typst preview)
- Created
-
Step 3: Update main PDF viewer
- Updated
PdfViewerinPdfRenderer.ktto use MuPDF - Same UI/navigation, swapped rendering backend
- Updated
-
Step 4: Update Typst preview
- Updated
PdfViewerFromBytesinnotes/SourceCodeInput.ktto use MuPDF - Proper resource cleanup with DisposableEffect
- Updated
-
Step 5: Remove old Android PdfRenderer code
- Removed all
android.graphics.pdf.PdfRendererimports - Cleaned up unused code (ParcelFileDescriptor, etc.)
- Removed all
Phase 1: Research & Library Selection
1.1 AGPL License Review
- Read the full AGPL v3 text: https://www.gnu.org/licenses/agpl-3.0.en.html
- Key AGPL considerations for this project:
- AGPL requires source code availability if users interact with the software over a network
- For a local-only app distributed as APK, AGPL is similar to GPL
- If using MuPDF, the entire app would need to be AGPL-compatible (or use commercial license)
- Your app is planned to be open-source, so this is likely fine
- Document decision and rationale
1.2 Library Comparison
| Feature | MuPDF | PDFium |
|---|---|---|
| License | AGPL (or commercial) | Apache 2.0 |
| Non-Latin rendering | Excellent | Good |
| Math/TeX rendering | Excellent | Moderate |
| Android support | Official SDK | Via wrappers |
| API style | Document/Page model | Similar |
| Bundle size | ~15MB | ~10MB |
MuPDF (recommended if AGPL is acceptable):
implementation("com.artifex.mupdf:fitz:1.27.0")- Superior text rendering engine
- Better handling of complex PDFs
PDFium (if permissive license required):
implementation("com.github.AhmerAfzal1:pdfium-android:1.9.0")(or similar wrapper)- Used by Chrome, well-tested
- More permissive license
1.3 Decision Checklist
- Confirm AGPL compatibility with project goals
- Test MuPDF with sample PDFs containing: CJK text, Arabic/Hebrew, mathematical notation
- Test PDFium with same samples for comparison
- Choose library and document decision here: ________________
Phase 2: Basic PDF Rendering with New Library
2.1 Remove Old Implementation
- Archive or delete the current PdfRenderer.kt implementation
- Remove any native PdfRenderer imports
2.2 Add New Library Dependency
- Add chosen library to
android/app/build.gradle.kts:// For MuPDF: implementation("com.artifex.mupdf:fitz:1.27.0") // OR for PDFium: implementation("com.github.AhmerAfzal1:pdfium-android:1.9.0") - Sync gradle and verify library downloads
2.3 Implement Basic Rendering (MuPDF approach)
Create new MuPdfRenderer.kt:
import com.artifex.mupdf.fitz.Document
import com.artifex.mupdf.fitz.Page
import com.artifex.mupdf.fitz.Matrix
import com.artifex.mupdf.fitz.android.AndroidDrawDevice
class PdfDocument(private val path: String) : AutoCloseable {
private val document: Document = Document.openDocument(path)
val pageCount: Int get() = document.countPages()
fun renderPage(pageIndex: Int, scale: Float = 2f): Bitmap {
val page = document.loadPage(pageIndex)
val bounds = page.bounds
val width = (bounds.x1 - bounds.x0) * scale
val height = (bounds.y1 - bounds.y0) * scale
val bitmap = Bitmap.createBitmap(
width.toInt(),
height.toInt(),
Bitmap.Config.ARGB_8888
)
val matrix = Matrix(scale)
val device = AndroidDrawDevice(bitmap)
page.run(device, matrix, null)
device.close()
page.destroy()
return bitmap
}
override fun close() {
document.destroy()
}
}
2.4 Integrate with Compose UI
- Create
PdfPagecomposable that displays a single rendered page - Implement page caching (keep current page + adjacent pages in memory)
- Add loading indicator while pages render
- Test with various PDF files
2.5 Verification
- PDF opens and displays correctly
- Non-Latin text renders properly (test with CJK, Arabic, Devanagari)
- Mathematical notation displays correctly
- Page navigation (next/previous) works
- Memory usage is reasonable for large PDFs
Phase 3: Gesture Handling
3.1 Core Transform State
@Stable
class PdfViewerState {
var scale by mutableFloatStateOf(1f)
var offset by mutableStateOf(Offset.Zero)
var rotation by mutableFloatStateOf(0f)
var currentPage by mutableIntStateOf(0)
companion object {
const val MIN_SCALE = 0.5f
const val MAX_SCALE = 5f
}
fun resetTransform() {
scale = 1f
offset = Offset.Zero
rotation = 0f
}
}
@Composable
fun rememberPdfViewerState() = remember { PdfViewerState() }
3.2 Gesture Implementation
@Composable
fun PdfViewer(
document: PdfDocument,
state: PdfViewerState = rememberPdfViewerState()
) {
val transformableState = rememberTransformableState { zoomChange, panChange, rotationChange ->
state.scale = (state.scale * zoomChange).coerceIn(
PdfViewerState.MIN_SCALE,
PdfViewerState.MAX_SCALE
)
state.offset += panChange
state.rotation += rotationChange
}
Box(
modifier = Modifier
.fillMaxSize()
.clipToBounds()
.transformable(state = transformableState)
.pointerInput(Unit) {
detectTapGestures(
onDoubleTap = { tapOffset ->
// Toggle between 1x and 2x zoom, centered on tap
if (state.scale > 1.5f) {
state.scale = 1f
state.offset = Offset.Zero
} else {
state.scale = 2.5f
// Center zoom on tap position
state.offset = calculateZoomOffset(tapOffset, state.scale)
}
}
)
}
.graphicsLayer {
scaleX = state.scale
scaleY = state.scale
translationX = state.offset.x
translationY = state.offset.y
rotationZ = state.rotation
}
) {
// Render current page
PdfPage(document, state.currentPage)
}
}
3.3 Page Swiping Logic
- Implement horizontal swipe detection for page changes
- Only trigger page change when zoomed out (scale close to 1.0)
- When zoomed in, swipes should pan instead
- Add edge bounce/resistance effect
- Consider adding page flip animation
3.4 Gesture Checklist
- Pinch-to-zoom works smoothly
- Two-finger pan works
- Two-finger rotation works (optional: can disable if not desired)
- Double-tap toggles zoom level
- Swipe changes pages when zoomed out
- Swipe pans when zoomed in
- Zoom is bounded (0.5x to 5x)
- No gesture conflicts or jank
Phase 4: Reading State Persistence
4.1 Data Models
Create in a new file PdfModels.kt:
@Serializable
data class PdfReadingState(
val documentHash: String, // SHA-256 of PDF content for identity
val documentName: String, // Display name
val lastUri: String, // Last known URI (may change across sessions)
val currentPage: Int,
val totalPages: Int,
val scale: Float,
val offsetX: Float,
val offsetY: Float,
val rotation: Float,
val lastReadTimestamp: Long, // Unix millis
val readingProgress: Float, // 0.0 to 1.0 (currentPage / totalPages)
val bookmarks: List<PdfBookmark>,
val nodeId: String // Which node last modified this state
)
@Serializable
data class PdfBookmark(
val id: String, // UUID
val page: Int,
val label: String?, // User-provided name, nullable
val createdAt: Long, // Unix millis
val color: BookmarkColor = BookmarkColor.DEFAULT
)
@Serializable
enum class BookmarkColor {
DEFAULT, RED, ORANGE, YELLOW, GREEN, BLUE, PURPLE
}
4.2 Local Persistence Options
Option A: Room Database
- Structured queries, familiar Android pattern
- Add Room dependencies and create DAO
Option B: Rust Storage Layer (Recommended)
- Consistent with project architecture
- Data automatically included in sync
- Extend existing FFI layer
4.3 Implementation Tasks
- Define data models (Kotlin + Rust if using Rust storage)
- Implement save/load functions
- Auto-save reading state on:
- Page change
- App backgrounding (onPause/onStop)
- Zoom/pan settling (debounced)
- Load reading state when opening a previously-read PDF
- Handle case where PDF content has changed (hash mismatch)
4.4 Document Identity
- Implement PDF hashing (hash first N bytes + file size for speed)
- Store mapping of hash -> reading state
- Handle same PDF at different URIs (recognize by hash)
Phase 5: Sync Integration
5.1 Rust Data Structures
Add to appropriate Rust module:
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct PdfReadingState {
pub document_hash: String,
pub document_name: String,
pub last_uri: String,
pub current_page: u32,
pub total_pages: u32,
pub scale: f32,
pub offset_x: f32,
pub offset_y: f32,
pub rotation: f32,
pub last_read_timestamp: i64,
pub reading_progress: f32,
pub bookmarks: Vec<PdfBookmark>,
pub node_id: String,
}
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct PdfBookmark {
pub id: String,
pub page: u32,
pub label: Option<String>,
pub created_at: i64,
pub color: BookmarkColor,
}
5.2 FFI Integration
- Add Rust functions for storing/retrieving PDF state
- Expose the types across the FFI (uniffi)
- Create JNI bindings
- Test round-trip serialization
5.3 Conflict Resolution Strategy
- For reading position: last-write-wins (most recent timestamp)
- For bookmarks: merge (union of all bookmarks, dedupe by page+label)
- Handle bookmark deletion across nodes (tombstone or explicit delete list)
5.4 Sync Testing
- Verify state syncs between two emulators/devices
- Test conflict scenarios
- Verify bookmark merge works correctly
Phase 6: Bookmark UI
6.1 Quick Bookmark Toggle
- Add bookmark icon in top bar (filled when current page is bookmarked)
- Tap to toggle bookmark on current page
- Long-press to add bookmark with custom label
6.2 Bookmark Bar (Bottom)
┌─────────────────────────────────────────────┐
│ [p.1 "Intro"] [p.47] [p.103 "Ch.3"] → │
└─────────────────────────────────────────────┘
- Horizontal scrollable row of bookmark chips
- Show page number and label (if set)
- Tap to jump to page
- Long-press for context menu (rename, change color, delete)
- Visual indicator for current page's bookmark
- Hide bar when no bookmarks exist
6.3 Expanded Bookmark Panel
- Swipe up on bookmark bar to expand
- Show page thumbnails alongside bookmarks
- Grid or list view toggle
- Search/filter bookmarks (for PDFs with many)
- Drag to reorder (optional)
6.4 Bookmark Chip Composable
@Composable
fun BookmarkChip(
bookmark: PdfBookmark,
isCurrentPage: Boolean,
onClick: () -> Unit,
onLongClick: () -> Unit
) {
Surface(
modifier = Modifier
.combinedClickable(
onClick = onClick,
onLongClick = onLongClick
),
shape = RoundedCornerShape(16.dp),
color = if (isCurrentPage)
MaterialTheme.colorScheme.primaryContainer
else
MaterialTheme.colorScheme.surfaceVariant
) {
Row(
modifier = Modifier.padding(horizontal = 12.dp, vertical = 8.dp),
verticalAlignment = Alignment.CenterVertically
) {
Text(
text = "p.${bookmark.page + 1}",
style = MaterialTheme.typography.labelMedium
)
bookmark.label?.let { label ->
Spacer(Modifier.width(4.dp))
Text(
text = label,
style = MaterialTheme.typography.labelSmall,
maxLines = 1,
overflow = TextOverflow.Ellipsis
)
}
}
}
}
File Locations
When implementing, place new files in:
android/app/src/main/java/com/gregshuflin/synchronicity/
├── pdf/
│ ├── PdfDocument.kt # MuPDF/PDFium wrapper
│ ├── PdfViewer.kt # Main viewer composable with gestures
│ ├── PdfViewerState.kt # State management
│ ├── PdfModels.kt # Data classes
│ ├── PdfRepository.kt # Storage/sync interface
│ ├── PdfViewerScreen.kt # Screen wrapper (exists, update)
│ ├── PdfLibraryScreen.kt # File picker (exists, update)
│ └── ui/
│ ├── BookmarkBar.kt # Bottom bookmark strip
│ ├── BookmarkChip.kt # Individual bookmark chip
│ └── BookmarkPanel.kt # Expanded bookmark view
Testing Checklist
Manual Testing
- Open small PDF (<10 pages)
- Open large PDF (>500 pages)
- Open PDF with CJK characters
- Open PDF with Arabic/Hebrew (RTL)
- Open PDF with mathematical notation
- Open PDF with complex vector graphics
- Test all gestures on physical device
- Test bookmark create/delete/navigate cycle
- Test app kill and restore (state persistence)
- Test sync between two devices
Edge Cases
- Corrupted PDF handling
- PDF with password protection
- Very wide/tall pages (non-standard aspect ratio)
- PDF with many pages (1000+)
- Low memory conditions
Resources
- MuPDF Android SDK: https://mupdf.com/docs/android-sdk.html
- MuPDF source: https://git.ghostscript.com/?p=mupdf-android-viewer.git
- PDFium Android wrapper: https://github.com/AhmerAfzal1/AhsanPdfiumAndroid
- AGPL v3 full text: https://www.gnu.org/licenses/agpl-3.0.en.html
- Compose gestures: https://developer.android.com/develop/ui/compose/touch-input/pointer-input/understand-gestures