Files
synchronicity/docs/PDF_IMPLEMENTATION_PLAN.md
Greg ShuflinandClaude Opus 4.8 c12ca31aa1 build: remove the dead typeshare type-generation pipeline
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>
2026-05-31 02:50:30 -07:00

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.0 to app/build.gradle.kts
    • Added Ghostscript Maven repository to settings.gradle.kts
  • Step 2: Create MuPDF wrapper class

    • Created MuPdfDocument.kt in pdfs/ directory
    • Wraps MuPDF's Document/Page API with a clean Kotlin interface
    • Supports file paths, URIs, and byte arrays (needed for Typst preview)
  • Step 3: Update main PDF viewer

    • Updated PdfViewer in PdfRenderer.kt to use MuPDF
    • Same UI/navigation, swapped rendering backend
  • Step 4: Update Typst preview

    • Updated PdfViewerFromBytes in notes/SourceCodeInput.kt to use MuPDF
    • Proper resource cleanup with DisposableEffect
  • Step 5: Remove old Android PdfRenderer code

    • Removed all android.graphics.pdf.PdfRenderer imports
    • Cleaned up unused code (ParcelFileDescriptor, etc.)

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 PdfPage composable 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