react-native-optimized-pdf 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -5,18 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.3.1] - 2026-11-01
+
+### Fixed
+
+- Local `file://` URIs and absolute paths are returned directly instead of being passed to the HTTP downloader, fixing local PDF opening on Android.
+
+### Changed
+
+- Replaced the abandoned `react-native-fs` with the maintained `@dr.pogodin/react-native-fs` (`^2.41.0`).
+
+## [1.3.0] - 2026-08-08
 
 ### Added
 
 - Annotation (annots) rendering support on Android and iOS
 - Tile-based PDF rendering for high-quality zoom (Android)
+- 100% automated test coverage for the TypeScript/JavaScript surface with a hard gate
+- CI workflow (GitHub Actions) running lint, typecheck, and coverage-gated tests on every push/PR
+- Test infrastructure: Jest, React Native Testing Library, and coverage thresholds in `jest.config.js`
+- Unit suites for `PdfCacheService`, `PdfNavigationControls`, `PdfOverlays`, and constants
+- Integration suite for `OptimizedPdfView` covering the load state machine, events, navigation, source changes, and platform fallback
 
 ### Changed
 
 - Android: migrated to `pdfiumandroid` and replaced previous rendering pipeline with tiled rendering
 - iOS: introduced annotation flattening using PDFKit when needed, while keeping CGPDF rendering for performance
 - Updated dependencies and improved TypeScript configuration
+- Removed unused and dead iOS code (delegate protocol, view/manager methods, error cases, imports)
+- Reconciled `PDF`/`Pdf` naming across the iOS Swift class, `@objc` export, Objective-C manager, and JS registration
+- Extracted duplicated `file://` URL handling into a shared iOS helper
+- Removed the unused `PdfSource.method` field (documented as non-breaking: the field was never consumed)
+- Removed unused `ERROR_MESSAGES.LOAD_FAILED` and `INVALID_SOURCE` entries
+- Aligned the iOS `maximumZoom` default with the JS side
 
 ### Improved
 
@@ -27,3 +48,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Annotations not being rendered
+- `_cancelled` reset semantics in `TiledPDFPageView`
+- Duplicated imports across iOS sources

package/README.md

@@ -41,6 +41,10 @@ cd ios && pod install
 
 No additional setup required! The module will be automatically linked.
 
+### Local files
+
+`source.uri` accepts a remote URL (`http://` or `https://`), a `file://` URI, or an absolute path. Local files are opened directly and are not copied to the cache; only remote URLs are downloaded. Remote downloads use the maintained [`@dr.pogodin/react-native-fs`](https://github.com/birdofpreyru/react-native-fs) package, installed automatically as a dependency.
+
 ## Usage
 
 ### Basic Example
@@ -198,8 +202,8 @@ const isValid = await PdfCacheService.isCacheValid({
 
 | Property        | Type                     | Default      | Description                                                  |
 | --------------- | ------------------------ | ------------ | ------------------------------------------------------------ |
-| `uri`           | `string`                 | **required** | PDF file URI (remote URL or local path)                      |
-| `cache`         | `boolean`                | `true`       | Enable local caching                                         |
+| `uri`           | `string`                 | **required** | PDF file URI (remote URL, `file://` URI, or absolute path) |
+| `cache`         | `boolean`                | `true`       | Enable local caching for remote URLs (ignored for local files) |
 | `cacheFileName` | `string`                 | MD5 of URI   | Custom filename for cached file                              |
 | `expiration`    | `number`                 | -            | Cache expiration in seconds (0 or undefined = no expiration) |
 | `headers`       | `Record<string, string>` | -            | HTTP headers for download                                    |
@@ -210,7 +214,7 @@ Static methods for managing PDF cache:
 
 - `getCacheFilePath(source: PdfSource): string` - Get local cache path
 - `isCacheValid(source: PdfSource): Promise<boolean>` - Check if cache is valid
-- `downloadPdf(source: PdfSource, onProgress?: (percent: number) => void): Promise<string>` - Download and cache PDF
+- `downloadPdf(source: PdfSource, onProgress?: (percent: number) => void): Promise<string>` - Download and cache a remote PDF; local paths are returned directly
 - `clearCache(source: PdfSource): Promise<void>` - Clear specific cached file
 - `clearAllCache(): Promise<void>` - Clear all cached PDFs
 - `getCacheSize(): Promise<number>` - Get total cache size in bytes
@@ -276,6 +280,26 @@ import { PdfNavigationControls } from 'react-native-optimized-pdf';
 - Pass the password via the `password` prop
 - Check for "Invalid password" in error message to show retry prompt
 
+## Development
+
+### Commands
+
+```bash
+# Run the test suite
+yarn test
+
+# Run tests with coverage (enforces the 100% gate)
+yarn test:coverage
+
+# Lint the codebase
+yarn lint
+
+# Type-check the codebase
+yarn typecheck
+```
+
+The test suite enforces **100% coverage** (lines, statements, functions, and branches) on the TypeScript/JavaScript surface (`src/**` and `index.ts`). `yarn test:coverage` exits non-zero if any threshold drops below 100%. The thresholds live in `jest.config.js`, and CI (GitHub Actions) runs `yarn lint`, `yarn typecheck`, and `yarn test:coverage` on every push and pull request, blocking merges when the gate fails.
+
 ## License
 
 MIT

package/ios/Core/PDFConfiguration.swift

@@ -3,7 +3,7 @@ import UIKit
 /// Configuration options for PDF rendering.
 struct PDFConfiguration {
     /// Maximum zoom scale allowed.
-    var maximumZoom: CGFloat = 5.0
+    var maximumZoom: CGFloat = 3
 
     /// Whether to enable antialiasing for smoother rendering.
     var enableAntialiasing: Bool = true

package/ios/Core/PDFDocumentLoader.swift

@@ -1,6 +1,12 @@
 import Foundation
 import CoreGraphics
 
+/// Strips the `file://` scheme prefix from a local PDF source string, if present.
+/// Shared by the document loader and the view so URL normalization stays in one place.
+func normalizedPDFPath(from source: String) -> String {
+    source.hasPrefix("file://") ? String(source.dropFirst(7)) : source
+}
+
 /// Protocol for PDF document loading operations.
 protocol PDFDocumentLoading {
     func loadDocument(from source: String, password: String?) -> Result<CGPDFDocument, PDFError>
@@ -40,10 +46,7 @@ final class PDFDocumentLoader: PDFDocumentLoading {
 
     /// Normalizes the source path to a file URL.
     private func normalizedURL(from source: String) -> URL {
-        let path = source.hasPrefix("file://")
-            ? String(source.dropFirst(7))
-            : source
-        return URL(fileURLWithPath: path)
+        URL(fileURLWithPath: normalizedPDFPath(from: source))
     }
 
     /// Attempts to unlock an encrypted PDF document.

package/ios/Core/PDFError.swift

@@ -3,29 +3,20 @@ import Foundation
 /// Errors that can occur during PDF operations.
 enum PDFError: Error, LocalizedError {
     case emptySource
-    case invalidPath(String)
     case documentLoadFailed(String)
     case passwordRequired
     case invalidPassword
-    case pageNotFound(Int)
-    case renderingFailed
 
     var errorDescription: String? {
         switch self {
         case .emptySource:
             return "PDF source path is empty"
-        case .invalidPath(let path):
-            return "Invalid PDF path: \(path)"
         case .documentLoadFailed(let path):
             return "Failed to open PDF at: \(path)"
         case .passwordRequired:
             return "PDF is password protected"
         case .invalidPassword:
             return "Invalid password for PDF"
-        case .pageNotFound(let index):
-            return "Page not found at index: \(index)"
-        case .renderingFailed:
-            return "Failed to render PDF page"
         }
     }
 

package/ios/ReactNative/OptimizedPDFViewManager.swift

@@ -17,32 +17,4 @@ final class OptimizedPDFViewManager: RCTViewManager {
     override static func requiresMainQueueSetup() -> Bool {
         true
     }
-
-    // MARK: - Exported Methods
-
-    /// Navigates to a specific page in the PDF.
-    /// - Parameters:
-    ///   - node: The React Native view tag.
-    ///   - page: The page index to navigate to (0-based).
-    @objc func goToPage(_ node: NSNumber, page: NSNumber) {
-        DispatchQueue.main.async { [weak self] in
-            guard let self = self,
-                  let pdfView = self.bridge?.uiManager.view(forReactTag: node) as? OptimizedPDFView else {
-                return
-            }
-            pdfView.goToPage(page.intValue)
-        }
-    }
-
-    /// Resets the zoom level to fit the page.
-    /// - Parameter node: The React Native view tag.
-    @objc func resetZoom(_ node: NSNumber) {
-        DispatchQueue.main.async { [weak self] in
-            guard let self = self,
-                  let pdfView = self.bridge?.uiManager.view(forReactTag: node) as? OptimizedPDFView else {
-                return
-            }
-            pdfView.resetZoom()
-        }
-    }
 }

package/ios/ReactNative/OptimizedPdfViewManager.m

@@ -6,8 +6,6 @@
  */
 
 #import <React/RCTViewManager.h>
-#import <React/RCTUIManager.h>
-#import <React/RCTBridgeModule.h>
 
 @interface RCT_EXTERN_MODULE(OptimizedPdfViewManager, RCTViewManager)
 
@@ -42,13 +40,4 @@ RCT_EXPORT_VIEW_PROPERTY(onPageCount, RCTDirectEventBlock)
 /// Called when the PDF requires a password to open.
 RCT_EXPORT_VIEW_PROPERTY(onPasswordRequired, RCTDirectEventBlock)
 
-#pragma mark - Native Methods
-
-/// Navigates to a specific page in the PDF.
-RCT_EXTERN_METHOD(goToPage:(nonnull NSNumber *)node
-                  page:(nonnull NSNumber *)page)
-
-/// Resets the zoom level to fit the page.
-RCT_EXTERN_METHOD(resetZoom:(nonnull NSNumber *)node)
-
 @end

package/ios/Views/OptimizedPDFView.swift

@@ -2,18 +2,15 @@ import UIKit
 import React
 import PDFKit
 
-/// Protocol for receiving PDF view events.
-@objc protocol OptimizedPDFViewDelegate: AnyObject {
-    @objc optional func pdfView(_ pdfView: OptimizedPDFView, didFailWithError error: Error)
-    @objc optional func pdfView(_ pdfView: OptimizedPDFView, didLoadWithPageCount pageCount: Int)
-    @objc optional func pdfView(_ pdfView: OptimizedPDFView, didDisplayPage page: Int, size: CGSize)
-    @objc optional func pdfViewDidRequestPassword(_ pdfView: OptimizedPDFView)
-}
-
 /// A high-performance PDF view using CATiledLayer for smooth zooming and scrolling.
 ///
 /// This view is optimized for React Native integration, providing callbacks for
 /// load completion, errors, and page navigation events.
+///
+/// Naming note: the Swift type is `OptimizedPDFView` while its `@objc` export is
+/// `OptimizedPdfView`, and the Objective-C manager/registration is
+/// `OptimizedPdfViewManager`. The `Pdf` spellings are the native bridge contract
+/// with JavaScript and must not be renamed.
 @objc(OptimizedPdfView)
 final class OptimizedPDFView: UIScrollView {
 
@@ -34,7 +31,7 @@ final class OptimizedPDFView: UIScrollView {
     }
 
     /// Maximum zoom scale.
-    @objc var maximumZoom: NSNumber = 5.0 {
+    @objc var maximumZoom: NSNumber = 3 {
         didSet {
             configuration.maximumZoom = CGFloat(truncating: maximumZoom)
             applyZoomConfiguration()
@@ -66,8 +63,6 @@ final class OptimizedPDFView: UIScrollView {
 
     // MARK: - Public Properties
 
-    weak var pdfDelegate: OptimizedPDFViewDelegate?
-
     /// Current number of pages in the document.
     private(set) var pageCount: Int = 0
 
@@ -83,7 +78,6 @@ final class OptimizedPDFView: UIScrollView {
     private var needsLoad = false
     private var lastBoundsSize: CGSize = .zero
     private var currentPageRect: CGRect?
-    private var initialZoomScale: CGFloat = 1.0
 
     // MARK: - Initialization
 
@@ -101,14 +95,6 @@ final class OptimizedPDFView: UIScrollView {
         setupView()
     }
 
-    /// Initializes with a custom document loader (useful for testing).
-    init(frame: CGRect, documentLoader: PDFDocumentLoading) {
-        self.tiledPageView = TiledPDFPageView(frame: frame)
-        self.documentLoader = documentLoader
-        super.init(frame: frame)
-        setupView()
-    }
-
     // MARK: - Setup
 
     private func setupView() {
@@ -137,7 +123,6 @@ final class OptimizedPDFView: UIScrollView {
 
         let fitScale = calculateFitScale(for: pageRect)
         minimumZoomScale = fitScale
-        initialZoomScale = fitScale
     }
 }
 
@@ -177,7 +162,7 @@ private extension OptimizedPDFView {
     func loadDocument() {
         guard !source.isEmpty else { return }
 
-        let path = source.hasPrefix("file://") ? String(source.dropFirst(7)) : source
+        let path = normalizedPDFPath(from: source)
         pdfURL = URL(fileURLWithPath: path)
 
         let result = documentLoader.loadDocument(from: source, password: configuration.password)
@@ -199,7 +184,6 @@ private extension OptimizedPDFView {
         DispatchQueue.main.async { [weak self] in
             guard let self = self else { return }
             self.onPageCount?(["numberOfPages": NSNumber(value: self.pageCount)])
-            self.pdfDelegate?.pdfView?(self, didLoadWithPageCount: self.pageCount)
         }
 
         // Display pending or first page
@@ -214,12 +198,10 @@ private extension OptimizedPDFView {
             DispatchQueue.main.async { [weak self] in
                 guard let self = self else { return }
                 self.onPasswordRequired?([:])
-                self.pdfDelegate?.pdfViewDidRequestPassword?(self)
             }
         }
 
         onError?(error.eventPayload)
-        pdfDelegate?.pdfView?(self, didFailWithError: error)
     }
 
     func clampPageIndex(_ index: Int, for document: CGPDFDocument) -> Int {
@@ -270,7 +252,6 @@ private extension OptimizedPDFView {
     func applyFitScale(for pageRect: CGRect) {
         let fitScale = calculateFitScale(for: pageRect)
         minimumZoomScale = fitScale
-        initialZoomScale = fitScale
         setZoomScale(fitScale, animated: false)
     }
 
@@ -284,7 +265,6 @@ private extension OptimizedPDFView {
         DispatchQueue.main.async { [weak self] in
             guard let self = self else { return }
             self.onLoadComplete?(payload)
-            self.pdfDelegate?.pdfView?(self, didDisplayPage: index + 1, size: size)
         }
     }
 }
@@ -379,23 +359,3 @@ extension OptimizedPDFView {
         centerContent()
     }
 }
-
-// MARK: - Public Methods
-
-extension OptimizedPDFView {
-
-    /// Resets the zoom to fit the page.
-    @objc func resetZoom() {
-        UIView.animate(withDuration: configuration.zoomResetAnimationDuration) { [weak self] in
-            guard let self = self else { return }
-            self.setZoomScale(self.initialZoomScale, animated: false)
-            self.centerContent()
-        }
-    }
-
-    /// Navigates to a specific page.
-    /// - Parameter index: The page index (0-based).
-    @objc func goToPage(_ index: Int) {
-        page = NSNumber(value: index)
-    }
-}

package/ios/Views/TiledPDFPageView.swift

@@ -2,10 +2,6 @@ import UIKit
 import CoreGraphics
 import PDFKit
 
-
-import UIKit
-import CoreGraphics
-
 /// A view that renders a PDF page using CATiledLayer for efficient tiled rendering.
 ///
 /// CATiledLayer divides the content into tiles, allowing smooth zooming and scrolling
@@ -29,10 +25,6 @@ final class FlattenedPageCache {
         cache.setObject(entry, forKey: key as NSString)
     }
 
-    func removeEntry(forKey key: String) {
-        cache.removeObject(forKey: key as NSString)
-    }
-
     func removeAll() {
         cache.removeAllObjects()
     }
@@ -60,6 +52,12 @@ final class OSAtomicFlag {
         os_unfair_lock_unlock(&_lock)
     }
 
+    func reset() {
+        os_unfair_lock_lock(&_lock)
+        _value = false
+        os_unfair_lock_unlock(&_lock)
+    }
+
     func isSet() -> Bool {
         os_unfair_lock_lock(&_lock)
         let v = _value
@@ -145,6 +143,7 @@ final class TiledPDFPageView: UIView {
     // MARK: - Prepare Page (Flatten Pipeline)
 
     func preparePage() {
+        _cancelled.reset()
         _generation &+= 1
         let currentGen = _generation
 
@@ -278,35 +277,3 @@ final class TiledPDFPageView: UIView {
         tiledLayer.levelsOfDetail == 1 ? .low : .high
     }
 }
-
-// MARK: - Public Methods
-
-extension TiledPDFPageView {
-
-    func prepareForReuse() {
-        pdfPage = nil
-        _activePage = nil
-        layer.contents = nil
-    }
-
-    /// Updates the view size to match the page dimensions.
-    func updateFrame(for page: CGPDFPage) {
-        let pageRect = page.getBoxRect(.cropBox)
-        frame = CGRect(origin: .zero, size: pageRect.size)
-        pdfPage = page
-    }
-
-    func invalidateCache() {
-        FlattenedPageCache.shared.removeEntry(forKey: currentCacheKey)
-        _activePage = pdfPage
-        _pdfKitDocument = nil
-        setNeedsDisplay()
-    }
-
-    func invalidateAllCache() {
-        FlattenedPageCache.shared.removeAll()
-        _pdfKitDocument = nil
-        _activePage = pdfPage
-        setNeedsDisplay()
-    }
-}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "react-native-optimized-pdf",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "React Native PDF viewer with high performance, zoom, and support for large PDF files. Fast, memory-efficient, and supports annotations (annots) on iOS and Android.",
   "main": "index.ts",
   "types": "index.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "jest",
+    "test:coverage": "jest --coverage --coverageReporters=text",
     "lint": "eslint . --ext .ts,.tsx",
     "lint:fix": "eslint . --ext .ts,.tsx --fix",
     "format": "prettier --write \"**/*.{ts,tsx,js,json,md}\"",
@@ -44,7 +45,9 @@
   },
   "devDependencies": {
     "@react-native-community/eslint-config": "^3.2.0",
+    "@testing-library/react-native": "^13.3.1",
     "@types/crypto-js": "^4.2.2",
+    "@types/jest": "^29.5.14",
     "@types/react": "^18.2.6",
     "@types/react-native": "^0.64.19",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
@@ -53,9 +56,11 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jest": "^29.11.0",
     "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^29.7.0",
     "prettier": "2.8.8",
     "react": "18.2.0",
     "react-native": "0.73.11",
+    "react-test-renderer": "18.2.0",
     "typescript": "^5.0.0"
   },
   "repository": {
@@ -63,7 +68,7 @@
     "url": "https://github.com/Herbeth-LKS/react-native-optimized-pdf"
   },
   "dependencies": {
-    "crypto-js": "^4.2.0",
-    "react-native-fs": "^2.20.0"
+    "@dr.pogodin/react-native-fs": "^2.41.0",
+    "crypto-js": "^4.2.0"
   }
 }

package/src/OptimizedPdfView.tsx

@@ -141,14 +141,10 @@ export default function OptimizedPdfView({
     return <PdfErrorOverlay error={error} style={style} />;
   }
 
-  if (!localPath) {
-    return null;
-  }
-
   return (
     <View style={[{ flex: 1 }, style]}>
       <NativeOptimizedPdfView
-        source={localPath}
+        source={localPath as string}
         page={showNavigationControls ? internalPage : page || 0}
         enableAntialiasing={enableAntialiasing}
         maximumZoom={maximumZoom}

package/src/constants.ts

@@ -8,6 +8,4 @@ export const DEFAULT_SHOW_NAVIGATION_CONTROLS = true;
 
 export const ERROR_MESSAGES = {
   DOWNLOAD_FAILED: 'Failed to download PDF',
-  LOAD_FAILED: 'Failed to load PDF',
-  INVALID_SOURCE: 'Invalid PDF source',
 } as const;

package/src/services/pdfCache.ts

@@ -1,4 +1,4 @@
-import RNFS from 'react-native-fs';
+import * as RNFS from '@dr.pogodin/react-native-fs';
 import md5 from 'crypto-js/md5';
 import type { PdfSource } from '../types';
 
@@ -33,11 +33,12 @@ export class PdfCacheService {
     // Check if cache has expired
     const stat = await RNFS.stat(localPath);
     const now = Date.now() / 1000;
-    return now - stat.mtime < source.expiration;
+    const modifiedAt = stat.mtime.getTime() / 1000;
+    return now - modifiedAt < source.expiration;
   }
 
   /**
-   * Download a PDF file and cache it locally
+   * Download a PDF file and cache it locally, or return a local file directly
    * @param source PDF source configuration
    * @param onProgress Optional callback for download progress
    * @returns Local file path
@@ -46,6 +47,11 @@ export class PdfCacheService {
     source: PdfSource,
     onProgress?: (percent: number) => void,
   ): Promise<string> {
+    // Local files are already readable by the native viewer.
+    if (source.uri.startsWith('file://') || source.uri.startsWith('/')) {
+      return source.uri;
+    }
+
     const localPath = this.getCacheFilePath(source);
 
     // Check if we can use cached version

package/src/types/index.ts

@@ -12,8 +12,6 @@ export interface PdfSource {
   cacheFileName?: string;
   /** Cache expiration time in seconds. If not set, cache never expires */
   expiration?: number;
-  /** HTTP method for download. Default: 'GET' */
-  method?: string;
   /** HTTP headers for download request */
   headers?: Record<string, string>;
 }