react-native-pdfrender 0.1.0

package/README.md

@@ -0,0 +1,306 @@
+# react-native-pdfrender
+
+A production-ready React Native PDF rendering library built on the **New Architecture** (TurboModules + Fabric components).
+
+- **Embedded viewer** — drop `<PdfViewerView />` anywhere in your render tree
+- **Imperative viewer** — use the `usePdfViewer` hook to open a modal-style PDF viewer
+- **Native rendering** — CGPDFDocument / Core Graphics on iOS, Android PdfRenderer on Android
+- **Jetpack Compose** — modern Android UI, no XML layouts
+- **Codegen-driven** — TypeScript specs generate type-safe native bindings at build time
+- **Zero JS dependencies** — no third-party npm packages required at runtime
+
+---
+
+## Requirements
+
+| Platform | Minimum version |
+|----------|----------------|
+| React Native | 0.70+ |
+| iOS | 13.0+ |
+| Android | SDK 24+ (Android 7.0) |
+| Node | 18+ |
+
+---
+
+## Installation
+
+```sh
+npm install react-native-pdfrender
+# or
+yarn add react-native-pdfrender
+```
+
+### iOS
+
+```sh
+cd ios && pod install
+```
+
+### Android
+
+No extra steps — auto-linking handles it.
+
+---
+
+## Usage
+
+### 1. Declarative (embedded viewer)
+
+```tsx
+import { PdfViewerView } from 'react-native-pdfrender';
+
+function MyScreen() {
+  return (
+    <PdfViewerView
+      uri="file:///path/to/document.pdf"
+      initialPage={0}
+      defaultZoom={1.5}
+      isFullScreen={false}
+      style={{ flex: 1 }}
+      onZoomChange={(pct) => console.log('zoom:', pct)}
+      onFullScreenChange={(fs) => setFullScreen(fs)}
+    />
+  );
+}
+```
+
+### 2. Imperative (hook — modal viewer)
+
+```tsx
+import { usePdfViewer } from 'react-native-pdfrender';
+
+function MyScreen() {
+  const { open, dismiss, getPageCount, createPdf } = usePdfViewer({
+    onFullScreenChanged: (isFS) => console.log('fullscreen:', isFS),
+    onZoomChanged: (zoom) => console.log('zoom:', zoom),
+    onDismiss: () => console.log('viewer closed'),
+  });
+
+  return (
+    <>
+      <Button title="Open PDF" onPress={() => open('file:///path/to/doc.pdf')} />
+      <Button title="Dismiss"  onPress={dismiss} />
+      <Button title="Page count" onPress={async () => {
+        const n = await getPageCount('file:///path/to/doc.pdf');
+        console.log('pages:', n);
+      }} />
+    </>
+  );
+}
+```
+
+---
+
+## API
+
+### `<PdfViewerView />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `uri` | `string` | **required** | `file://` or `content://` path to the PDF |
+| `initialPage` | `number` | `-1` (first) | 0-based page index to open on |
+| `defaultZoom` | `number` | `1.5` | Initial zoom level (1.0 = 100%) |
+| `isFullScreen` | `boolean` | `false` | Fills the parent container when true |
+| `rightLayout` | `boolean` | `false` | Positions viewer on right side (split-view) |
+| `maxWidth` | `number` | — | Max pixel width (split-view) |
+| `screenWidthPercentage` | `number` | `100` | % of screen width |
+| `icons` | `IconSet` | — | Custom toolbar icon assets |
+| `iconSize` | `number` | `40` | Icon size in logical pixels |
+| `backButtonText` | `string` | — | Toolbar back button label |
+| `headerText` | `string` | — | Toolbar header label |
+| `style` | `ViewStyle` | — | Container style |
+| `onFullScreenChange` | `(isFullScreen: boolean) => void` | — | Fires when fullscreen state changes |
+| `onZoomChange` | `(zoomPercentage: number) => void` | — | Fires when zoom changes |
+| `onLeftScreenChange` | `(isLeftScreen: boolean) => void` | — | Fires in split-view |
+| `onRightScreenChange` | `(isRightScreen: boolean) => void` | — | Fires in split-view |
+
+#### `IconSet`
+
+```ts
+interface IconSet {
+  zoomIn?:         number | string; // require('./zoom_in.png') or URI
+  zoomOut?:        number | string;
+  fullScreen?:     number | string;
+  minimizeScreen?: number | string;
+  leftLayout?:     number | string;
+  rightLayout?:    number | string;
+}
+```
+
+---
+
+### `usePdfViewer(options?)`
+
+```ts
+interface UsePdfViewerOptions {
+  onFullScreenChanged?: (isFullScreen: boolean) => void;
+  onZoomChanged?:       (zoomPercentage: number) => void;
+  onDismiss?:           () => void;
+  onError?:             (error: string) => void;
+}
+
+interface UsePdfViewerReturn {
+  open:        (uri: string, pageIndex?: number, defaultZoom?: number) => void;
+  dismiss:     () => void;
+  getPageCount:(uri: string) => Promise<number>;
+  createPdf:   (pages: PdfPage[], widthPx: number, heightPx: number) => Promise<PdfCreationResult>;
+}
+```
+
+---
+
+### `NativePdfViewerModule` (low-level TurboModule)
+
+Exposed for advanced use cases. Prefer `usePdfViewer` for most scenarios.
+
+```ts
+import { NativePdfViewerModule } from 'react-native-pdfrender';
+
+NativePdfViewerModule.openPdfViewer(uri, pageIndex, defaultZoom);
+NativePdfViewerModule.dismissPdfViewer();
+const count = await NativePdfViewerModule.getPdfPageCount(uri);
+const result = await NativePdfViewerModule.createMultiPagePdfBase64(pages, width, height);
+```
+
+---
+
+## Architecture
+
+```
+react-native-pdfrender/
+├── android/
+│   ├── build.gradle                  ← library module (com.android.library)
+│   └── src/main/java/com/pdfrender/
+│       ├── PdfViewerTurboModule.kt   ← TurboModule (imperative API)
+│       ├── PdfViewerFabricManager.kt ← Fabric ViewManager (embedded viewer)
+│       ├── PdfViewerFragment.kt      ← modal viewer Fragment
+│       ├── PdfRenderingLogic.kt      ← Android PdfRenderer wrapper
+│       ├── ComposeRenderer.kt        ← Jetpack Compose UI
+│       └── events/                   ← Fabric event classes
+├── ios/
+│   ├── PdfViewerTurboModule.mm       ← ObjC++ TurboModule bridge
+│   ├── PdfViewerTurboModuleImpl.swift ← Swift business logic
+│   ├── PdfViewerComponentView.mm     ← ObjC++ Fabric ViewManager
+│   ├── PdfViewerView.swift           ← main PDF rendering view
+│   ├── PdfRenderingLogic.swift       ← CGPDFDocument wrapper
+│   └── ...
+├── src/
+│   ├── index.tsx                     ← public API exports
+│   ├── PdfViewerView.tsx             ← React component
+│   ├── usePdfViewer.ts               ← hook
+│   └── specs/
+│       ├── NativePdfViewerModule.ts  ← TurboModule codegen spec
+│       └── NativePdfViewerComponent.ts ← Fabric codegen spec
+├── lib/                              ← compiled output (generated by bob)
+├── example/                          ← example React Native app
+└── react-native-pdfrender.podspec
+```
+
+### New Architecture (codegen)
+
+The `codegenConfig` in `package.json` points to `src/specs/`. At build time:
+
+- **iOS** — CocoaPods generates `PdfViewerSpecs.h` and the Fabric C++ headers
+- **Android** — Gradle generates the abstract `NativePdfViewerModuleSpec` Kotlin class
+
+---
+
+## Building the library
+
+```sh
+# Install deps
+yarn install
+
+# Compile TypeScript → lib/
+yarn build
+# runs automatically as `prepare` before npm publish
+
+# Type-check only
+yarn typecheck
+```
+
+---
+
+## Running the example app
+
+### Install dependencies
+
+```sh
+# Library deps
+yarn install
+
+# Example deps
+cd example && yarn install
+```
+
+### iOS (one-time Xcode project cleanup required)
+
+The example Xcode project was migrated from the original monolithic app and still
+includes the library Swift files in the app target. Because CocoaPods now compiles
+those same files as part of the library pod, you must remove them from the app
+target first to avoid duplicate-symbol errors:
+
+1. Open `example/ios/pdfRender.xcodeproj` in Xcode
+2. Select the **pdfRender** app target → **Build Phases** → **Compile Sources**
+3. Remove these files (click each, press `–`):
+   - `PdfViewerView.swift`, `PdfViewerViewController.swift`
+   - `PdfViewerTurboModuleImpl.swift`, `PdfRenderingLogic.swift`
+   - `PdfPageView.swift`, `PdfToolbarView.swift`
+   - `PdfCacheManager.swift`, `PdfConstants.swift`
+   - `PdfViewerTurboModule.mm`, `PdfViewerComponentView.mm`
+4. Save the Xcode project, then:
+
+```sh
+cd example/ios && pod install && cd ../..
+yarn example:ios
+```
+
+### Android
+
+```sh
+yarn example:android
+```
+
+---
+
+## Publishing to npm
+
+```sh
+# Build the library
+yarn prepare
+
+# Verify what will be published
+npm pack --dry-run
+
+# Publish publicly
+npm publish --access public
+```
+
+---
+
+## Common Issues
+
+### `PdfViewerSpecs/PdfViewerSpecs.h` not found (iOS build)
+
+Run `pod install` inside `example/ios/` (or the consuming app's `ios/`). This triggers codegen which produces the `PdfViewerSpecs` headers.
+
+### Duplicate symbol errors on iOS
+
+Follow the [Xcode project cleanup](#ios-one-time-xcode-project-cleanup-required) steps above.
+
+### `NativePdfViewerModuleSpec` not found (Android)
+
+Run the app once — Gradle auto-generates the spec. Or run manually:
+```sh
+cd example/android && ./gradlew generateCodegenArtifactsFromSchema
+```
+
+### Metro can't resolve `react-native-pdfrender`
+
+Run `yarn install` inside `example/` (not just the root). The `file:../` entry creates a symlink in `example/node_modules/react-native-pdfrender` that Metro follows.
+
+---
+
+## License
+
+MIT © Shubham Keshari

package/android/build.gradle

@@ -0,0 +1,76 @@
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "org.jetbrains.kotlin.plugin.compose"
+apply plugin: "com.facebook.react"
+
+def kotlinVersion = "2.1.20"
+
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    classpath("com.android.tools.build:gradle")
+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.20")
+    classpath("org.jetbrains.kotlin:compose-compiler-gradle-plugin:2.1.20")
+    classpath("com.facebook.react:react-native-gradle-plugin")
+  }
+}
+
+android {
+  compileSdk 36
+  buildToolsVersion "36.0.0"
+
+  namespace "com.pdfrender"
+
+  defaultConfig {
+    minSdk 24
+    targetSdk 36
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+  }
+
+  buildFeatures {
+    buildConfig true
+    compose true
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs = ["src/main/java"]
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation("com.facebook.react:react-android")
+
+  def composeBom = platform("androidx.compose:compose-bom:2024.09.00")
+  implementation(composeBom)
+  implementation("androidx.compose.ui:ui")
+  implementation("androidx.compose.material:material")
+  implementation("androidx.compose.ui:ui-tooling-preview")
+  debugImplementation("androidx.compose.ui:ui-tooling")
+
+  implementation("androidx.activity:activity-compose:1.9.2")
+  implementation("androidx.fragment:fragment-ktx:1.8.3")
+  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
+}
+
+def isNewArchitectureEnabled() {
+  return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/pdfrender/ComposeRenderer.kt

@@ -0,0 +1,85 @@
+package com.pdfrender
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.Typeface
+import android.text.Layout
+import android.text.StaticLayout
+import android.text.TextPaint
+
+/**
+ * Render PDF page content to a Bitmap using Android Canvas API.
+ * This approach doesn't require Compose window attachment.
+ */
+fun renderComposableToBitmap(
+    context: Context,
+    widthPx: Int,
+    heightPx: Int,
+    title: String,
+    body: String
+): Bitmap {
+    val bitmap = Bitmap.createBitmap(widthPx, heightPx, Bitmap.Config.ARGB_8888)
+    val canvas = Canvas(bitmap)
+
+    // Fill white background
+    canvas.drawColor(android.graphics.Color.WHITE)
+
+    // Setup title paint
+    val titlePaint = TextPaint().apply {
+        color = android.graphics.Color.BLACK
+        textSize = 22f * context.resources.displayMetrics.density
+        typeface = Typeface.create(Typeface.DEFAULT, Typeface.BOLD)
+        isAntiAlias = true
+    }
+
+    // Setup body paint
+    val bodyPaint = TextPaint().apply {
+        color = android.graphics.Color.BLACK
+        textSize = 16f * context.resources.displayMetrics.density
+        typeface = Typeface.DEFAULT
+        isAntiAlias = true
+    }
+
+    val paddingPx = (24 * context.resources.displayMetrics.density).toInt()
+    val topPaddingPx = (12 * context.resources.displayMetrics.density).toInt()
+    val availableWidth = widthPx - (paddingPx * 2)
+
+    // Draw title
+    val titleLayout = StaticLayout.Builder.obtain(
+        title,
+        0,
+        title.length,
+        titlePaint,
+        availableWidth
+    ).setAlignment(Layout.Alignment.ALIGN_NORMAL)
+        .setLineSpacing(0f, 1f)
+        .setIncludePad(false)
+        .build()
+
+    canvas.save()
+    canvas.translate(paddingPx.toFloat(), paddingPx.toFloat())
+    titleLayout.draw(canvas)
+    canvas.restore()
+
+    // Draw body
+    val bodyYPosition = paddingPx + titleLayout.height + topPaddingPx
+    val bodyLayout = StaticLayout.Builder.obtain(
+        body,
+        0,
+        body.length,
+        bodyPaint,
+        availableWidth
+    ).setAlignment(Layout.Alignment.ALIGN_NORMAL)
+        .setLineSpacing(0f, 1f)
+        .setIncludePad(false)
+        .build()
+
+    canvas.save()
+    canvas.translate(paddingPx.toFloat(), bodyYPosition.toFloat())
+    bodyLayout.draw(canvas)
+    canvas.restore()
+
+    return bitmap
+}

package/android/src/main/java/com/pdfrender/PdfCacheManager.kt

@@ -0,0 +1,150 @@
+package com.pdfrender
+
+import android.graphics.Bitmap
+import android.util.Log
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+
+/**
+ * PDF Cache Management Utilities
+ * 
+ * This file contains helper functions for managing PDF page cache,
+ * batch calculations, and memory management.
+ */
+
+/**
+ * Calculates which batch a page belongs to
+ * 
+ * @param pageIndex The page index (0-based)
+ * @param batchSize The size of each batch
+ * @return The batch number containing this page
+ */
+fun getBatchNumber(pageIndex: Int, batchSize: Int): Int {
+    return pageIndex / batchSize
+}
+
+/**
+ * Gets the page range for a specific batch
+ * 
+ * @param batchNumber The batch number
+ * @param batchSize The size of each batch
+ * @param pageCount Total number of pages
+ * @return The IntRange of page indices in this batch
+ */
+fun getBatchRange(batchNumber: Int, batchSize: Int, pageCount: Int): IntRange {
+    val startPage = batchNumber * batchSize
+    val endPage = minOf((batchNumber + 1) * batchSize - 1, pageCount - 1)
+    return startPage..endPage
+}
+
+/**
+ * Calculates memory usage percentage
+ * 
+ * @return Memory usage as a percentage (0-100)
+ */
+fun getMemoryUsagePercent(): Int {
+    val runtime = Runtime.getRuntime()
+    val usedMemory = runtime.totalMemory() - runtime.freeMemory()
+    val maxMemory = runtime.maxMemory()
+    return (usedMemory * 100 / maxMemory).toInt()
+}
+
+/**
+ * Calculates effective cache size based on memory usage
+ * 
+ * Reduces cache size when memory is high to prevent OOM errors
+ * 
+ * @param maxCacheSize The maximum cache size
+ * @return The effective cache size to use
+ */
+fun calculateEffectiveCacheSize(maxCacheSize: Int): Int {
+    val memoryUsagePercent = getMemoryUsagePercent()
+    
+    return when {
+        memoryUsagePercent > 60 -> maxCacheSize / 2  // Reduce by half if memory > 60%
+        memoryUsagePercent > 50 -> (maxCacheSize * 2 / 3).toInt()  // Reduce to 2/3 if memory > 50%
+        else -> maxCacheSize
+    }
+}
+
+/**
+ * Determines which batches to keep based on current visible page
+ * 
+ * Keeps the current batch plus one batch before and after for smooth scrolling
+ * 
+ * @param currentVisiblePage The currently visible page index
+ * @param batchSize The size of each batch
+ * @param pageCount Total number of pages
+ * @return Set of batch numbers to keep in cache
+ */
+fun getBatchesToKeep(
+    currentVisiblePage: Int,
+    batchSize: Int,
+    pageCount: Int
+): Set<Int> {
+    val currentBatch = getBatchNumber(currentVisiblePage, batchSize)
+    
+    return setOf(
+        currentBatch - 1,
+        currentBatch,
+        currentBatch + 1
+    ).filter { it >= 0 && it * batchSize < pageCount }.toSet()
+}
+
+/**
+ * Safely recycles a bitmap after ensuring it's not in use
+ * 
+ * This function performs multiple safety checks before recycling:
+ * - Checks if bitmap is still in cache
+ * - Checks if bitmap is in active use
+ * - Validates bitmap is not already recycled
+ * 
+ * @param bitmap The bitmap to recycle
+ * @param isStillInCache Function to check if bitmap is still in cache
+ * @param isActive Function to check if bitmap is actively being used
+ */
+suspend fun safelyRecycleBitmap(
+    bitmap: Bitmap,
+    isStillInCache: suspend () -> Boolean,
+    isActive: () -> Boolean
+) {
+    try {
+        // Check if bitmap is still in cache
+        val stillInCache = isStillInCache()
+        if (stillInCache) {
+            Log.w("PdfRenderer", "[CRASH_LOG] Bitmap still in cache, skipping recycle")
+            return
+        }
+        
+        // Don't recycle if still in active use
+        if (isActive()) {
+            Log.d("PdfRenderer", "[CRASH_LOG] Skipping recycle of active bitmap")
+            return
+        }
+        
+        // Final check before recycling
+        if (!bitmap.isRecycled && bitmap.width > 0 && bitmap.height > 0) {
+            bitmap.recycle()
+            Log.d("PdfRenderer", "[CRASH_LOG] Recycled bitmap: ${bitmap.width}x${bitmap.height}")
+        } else {
+            Log.d("PdfRenderer", "[CRASH_LOG] Bitmap already recycled or invalid, skipping")
+        }
+    } catch (e: Exception) {
+        Log.e("PdfRenderer", "[CRASH_LOG] Error recycling bitmap: ${e.message}", e)
+        Log.e("PdfRenderer", "[CRASH_LOG] Stack trace: ${e.stackTraceToString()}")
+    }
+}
+
+/**
+ * Checks if a page needs to be re-rendered based on scale difference
+ * 
+ * @param cachedScale The scale at which the page is currently cached
+ * @param targetScale The desired scale
+ * @return True if the page needs to be re-rendered
+ */
+fun needsRerender(cachedScale: Float?, targetScale: Float): Boolean {
+    if (cachedScale == null) return true
+    return kotlin.math.abs(cachedScale - targetScale) > 0.08f
+}
+

package/android/src/main/java/com/pdfrender/PdfConstants.kt

@@ -0,0 +1,63 @@
+package com.pdfrender
+
+/**
+ * Constants and data classes for PDF Viewer
+ * 
+ * This file contains all constants, configuration values, and data classes
+ * used throughout the PDF viewer module.
+ */
+
+/**
+ * Data class representing a render request for a PDF page
+ * 
+ * @param pageIndex The index of the page to render (0-based)
+ * @param targetScale The scale at which to render the page (0.3f to 0.6f)
+ * @param priority Priority level: 0 = highest (visible), 1 = medium (near), 2 = low (prefetch)
+ */
+data class RenderRequest(
+    val pageIndex: Int,
+    val targetScale: Float,
+    val priority: Int
+)
+
+/**
+ * PDF Viewer Configuration Constants
+ */
+object PdfViewerConfig {
+    // Batch loading configuration - OPTIMIZED FOR IMMEDIATE UI DISPLAY
+    const val BATCH_SIZE = 3  // Load 3 pages per batch (requirement: show first 3 pages immediately)
+    const val MAX_CACHE_SIZE = 100  // Keep max 30 pages in memory (10 batches worth)
+    
+    // Scale configuration
+    const val MIN_SCALE = 0.65f  // Minimum zoom level (100% - STRICT REQUIREMENT)
+    const val MAX_SCALE_SMALL_SCREEN = 2.5f  // Maximum zoom for small screens/phones (250%)
+    const val MAX_SCALE_LARGE_SCREEN = 3.0f  // Maximum zoom for large screens/tablets (300%)
+    const val DEFAULT_SCALE = 1.5f  // Default zoom level fallback (only used if not provided from JS)
+    const val SCALE_STEP = 0.05f  // Zoom step size for buttons (5%)
+    
+    // Screen size thresholds for determining small vs large screen
+    const val SMALL_SCREEN_WIDTH_DP = 600  // Screens <= 600dp are considered small (phones)
+    
+    // Rendering configuration
+    const val RENDERING_TIMEOUT_MS = 5000L  // 5 seconds - timeout for stuck renders
+    const val WATCHDOG_CHECK_INTERVAL_MS = 2000L  // Check for stuck pages every 2 seconds
+    
+    // Gesture configuration
+    const val GESTURE_THROTTLE_MS = 16L  // 16ms = ~60fps for smooth updates
+    const val PINCH_GESTURE_END_DELAY_MS = 500L  // Delay before considering gesture ended
+    const val MIN_ZOOM_CHANGE_THRESHOLD = 0.005f  // 0.5% minimum change to process
+    const val SCALE_UPDATE_THRESHOLD = 0.005f  // 0.5% threshold for scale updates
+    
+    // Memory management
+    const val MEMORY_WARNING_THRESHOLD_PERCENT = 75  // Clean cache if memory > 75%
+    const val MEMORY_CRITICAL_THRESHOLD_PERCENT = 80  // Aggressive cleanup if memory > 80%
+    
+    // Initial loading - CRITICAL: Load ONLY first batch (3 pages) for immediate UI display
+    const val INITIAL_BATCHES_TO_LOAD = 1  // Load ONLY first 3 pages immediately
+    const val INITIAL_LOAD_DELAY_MS = 100L  // Delay before showing completion
+    
+    // Background loading configuration - NEW
+    const val BACKGROUND_BATCHES_TO_PREFETCH = 2  // Pre-fetch 2 batches (6 pages) in background after UI shows
+    const val SCROLL_PREFETCH_THRESHOLD = 2  // Start loading next batch when within 2 pages of unloaded content
+}
+