@dvvebond/core

A fork of @libpdf/core with enhanced React components, Azure Document Intelligence integration, text extraction with bounding boxes, and enterprise PDF viewing features.

Fork Enhancements

This fork extends the original LibPDF library with:

• React Integration Layer: Production-ready React components and hooks for PDF viewing
• Text Extraction with Bounding Boxes: Character, word, line, and paragraph-level extraction with precise coordinates
• Search Functionality: Full-text search with highlighting and navigation
• Viewport Management: Virtual scrolling for large documents with efficient memory usage
• Azure Document Intelligence Integration: Process PDFs with Azure AI services
• Coordinate Transformation: Convert between PDF and screen coordinates

Features

Core PDF Operations (from LibPDF)

Feature	Status	Notes
Parse any PDF	Yes	Graceful fallback for malformed documents
Create PDFs	Yes	From scratch or modify existing
Encryption	Yes	RC4, AES-128, AES-256 (R2-R6)
Digital Signatures	Yes	PAdES B-B, B-T, B-LT, B-LTA
Form Filling	Yes	Text, checkbox, radio, dropdown, signature
Form Flattening	Yes	Bake fields into page content
Merge & Split	Yes	Combine or extract pages
Attachments	Yes	Embed and extract files
Text Extraction	Yes	With position information
Font Embedding	Yes	TTF/OpenType with subsetting
Images	Yes	JPEG, PNG (with alpha)
Incremental Saves	Yes	Append changes, preserve signatures

Enhanced Features (this fork)

Feature	Description
React Components	ReactPDFViewer, PageNavigation, ZoomControls, SearchInput
React Hooks	usePDFViewer, usePDFSearch, useBoundingBoxOverlay, useViewport
Text Extraction	Hierarchical extraction (char/word/line/paragraph)
Bounding Box Visualization	Overlay system for highlighting text regions
Virtual Scrolling	Efficient rendering of large documents
Search Engine	Full-text search with match highlighting
Coordinate Transformation	PDF-to-screen and screen-to-PDF conversions
PDF.js Integration	Seamless integration with Mozilla's PDF.js

Installation

npm install @dvvebond/core
# or
bun add @dvvebond/core
# or
pnpm add @dvvebond/core

For React components:

# React is a peer dependency
npm install @dvvebond/core react react-dom

Quick Start

Basic PDF Loading

import { PDF } from "@dvvebond/core";

const pdf = await PDF.load(bytes);
const pages = pdf.getPages();
console.log(`${pages.length} pages`);

React PDF Viewer

import { ReactPDFViewer, usePDFViewer, PageNavigation, ZoomControls } from "@dvvebond/core/react";
import { useRef } from "react";

function PDFViewerApp() {
  const viewerRef = useRef<ReactPDFViewerRef>(null);

  return (
    <div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
      <div className="toolbar">
        <PageNavigation viewerRef={viewerRef} />
        <ZoomControls viewerRef={viewerRef} />
      </div>
      <ReactPDFViewer
        ref={viewerRef}
        url="/document.pdf"
        initialScale={1.0}
        onPageChange={page => console.log("Current page:", page)}
        onDocumentLoad={info => console.log("Loaded:", info.numPages, "pages")}
      />
    </div>
  );
}

Text Extraction with Bounding Boxes

import {
  HierarchicalTextExtractor,
  createHierarchicalTextExtractor,
  type TextPage,
} from "@dvvebond/core";

// Extract text with full hierarchy
const extractor = createHierarchicalTextExtractor();
const pageText: TextPage = await extractor.extractPage(pdfPage, {
  includeCharacters: true,
  includeWords: true,
  includeLines: true,
  includeParagraphs: true,
});

// Access bounding boxes at any level
for (const paragraph of pageText.paragraphs) {
  console.log("Paragraph bbox:", paragraph.boundingBox);
  for (const line of paragraph.lines) {
    console.log("  Line:", line.text, "at", line.boundingBox);
  }
}

Search with Highlighting

import { usePDFSearch, useBoundingBoxOverlay } from "@dvvebond/core/react";

function SearchableViewer() {
  const { searchState, search, nextMatch, prevMatch, clearSearch } = usePDFSearch();
  const { boundingBoxes, setHighlights } = useBoundingBoxOverlay();

  const handleSearch = async (query: string) => {
    const results = await search(query);
    // Results include bounding boxes for highlighting
    setHighlights(results.map(r => r.boundingBox));
  };

  return (
    <div>
      <input type="text" onChange={e => handleSearch(e.target.value)} placeholder="Search..." />
      <span>
        {searchState.currentMatch} / {searchState.totalMatches}
      </span>
      <button onClick={prevMatch}>Previous</button>
      <button onClick={nextMatch}>Next</button>
    </div>
  );
}

Bounding Box Visualization

import { createBoundingBoxOverlay, type OverlayBoundingBox } from "@dvvebond/core";

const overlay = createBoundingBoxOverlay(containerElement, {
  pageWidth: 612,
  pageHeight: 792,
  scale: 1.5,
});

// Add bounding boxes with different types
overlay.setBoundingBoxes([
  { x: 50, y: 100, width: 200, height: 20, type: "word", text: "Hello" },
  { x: 50, y: 130, width: 300, height: 20, type: "line", text: "Hello World" },
  { x: 50, y: 100, width: 300, height: 100, type: "paragraph" },
]);

// Control visibility by type
overlay.setVisibility({
  character: false,
  word: true,
  line: true,
  paragraph: false,
});

Virtual Scrolling for Large Documents

import { createViewportManager, createVirtualScroller, type PageSource } from "@dvvebond/core";

const scroller = createVirtualScroller(containerElement, {
  totalPages: 100,
  pageHeight: 792,
  pageGap: 10,
  overscan: 2, // Render 2 extra pages above/below viewport
});

const viewportManager = createViewportManager({
  pageSource: pdfDocument,
  scroller,
  renderer: createCanvasRenderer(),
});

// Pages are automatically loaded/unloaded as user scrolls
scroller.on("visibleRangeChange", ({ startPage, endPage }) => {
  console.log(`Visible pages: ${startPage} - ${endPage}`);
});

Coordinate Transformation

import {
  createCoordinateTransformer,
  getMousePdfCoordinates,
  transformBoundingBoxes,
} from "@dvvebond/core";

const transformer = createCoordinateTransformer({
  pageWidth: 612,
  pageHeight: 792,
  scale: 1.5,
  rotation: 0,
});

// Handle click events on PDF
containerElement.addEventListener("click", event => {
  const pdfCoords = getMousePdfCoordinates(event, containerElement, transformer);
  console.log(`Clicked at PDF coordinates: (${pdfCoords.x}, ${pdfCoords.y})`);
});

// Transform bounding boxes from PDF to screen coordinates
const screenBoxes = transformBoundingBoxes(pdfBoundingBoxes, transformer);

PDF.js Integration

import {
  initializePDFJS,
  loadPDFJSDocument,
  getPDFJSTextContent,
  createPDFJSRenderer,
} from "@dvvebond/core";

// Initialize PDF.js (call once at app startup)
await initializePDFJS();

// Load document
const doc = await loadPDFJSDocument(pdfBytes);
const page = await doc.getPage(1);

// Render to canvas
const renderer = createPDFJSRenderer(canvas, {
  scale: 1.5,
  enableTextLayer: true,
});
await renderer.render(page);

// Extract text content
const textContent = await getPDFJSTextContent(page);

React Hooks Reference

usePDFViewer

Main hook for PDF viewer state management.

const { currentPage, totalPages, scale, isLoading, error, goToPage, setScale, zoomIn, zoomOut } =
  usePDFViewer(viewerRef);

usePDFSearch

Hook for search functionality.

const {
  searchState, // { query, matches, currentMatch, totalMatches, status }
  search, // (query: string) => Promise<SearchResult[]>
  nextMatch, // () => void
  prevMatch, // () => void
  clearSearch, // () => void
} = usePDFSearch(viewerRef);

useBoundingBoxOverlay

Hook for bounding box visualization.

const {
  boundingBoxes,
  visibility,
  setVisibility,
  addBoundingBoxes,
  clearBoundingBoxes,
  highlightBox,
} = useBoundingBoxOverlay(viewerRef);

useViewport

Hook for viewport information.

const { viewportWidth, viewportHeight, scrollTop, scrollLeft, visiblePages } =
  useViewport(viewerRef);

useScrollPosition

Hook for scroll position tracking.

const { scrollTop, scrollLeft, scrollTo, scrollToPage } = useScrollPosition(viewerRef);

Runtime Support

Works in all modern JavaScript environments:

• Node.js 20+
• Bun
• Browsers (modern, with Web Crypto)

Migration from react-pdf

See MIGRATION.md for a detailed migration guide from react-pdf to @dvvebond/core.

API Reference

See API.md for complete API documentation.

Acknowledgments

This project is a fork of LibPDF by Documenso. The core PDF parsing and generation functionality is their excellent work.

License

MIT

The src/fontbox/ directory is licensed under Apache-2.0 as it is derived from Apache PDFBox.