web-annotation-renderer


A framework-agnostic PDF annotation renderer with timeline synchronization for educational content, interactive presentations, and annotated documents.

This library renders structured annotation data (highlights, text boxes, drawings) on top of PDF documents, synchronized with audio or video timelines. Built on pdf.js with a clean, modern API.

Features

- 📄 PDF Rendering - Built on pdf.js for reliable PDF display
- ⏱️ Timeline Synchronization - Sync annotations with audio/video playback or manual controls
- 🎨 Multiple Annotation Types - Highlights, text, underlines, arrows, and circles
- 🌏 Multilingual Text - Full support for Latin, Korean (11,172 syllables), and CJK characters
- ⚛️ Framework Agnostic - Core engine works with any framework
- ⚛️ React Adapter - Ready-to-use React component included
- 🎯 Progressive Animations - Smooth reveal animations based on timeline
- 🎬 Continuous Sync - Built-in support for real-time audio/video synchronization
- 📦 Simple Setup - One-line worker configuration
- 🌲 Tree-shakeable - Import only what you need
- ⚡ Performance Optimized - Efficient canvas-based rendering with StrokeRenderer

Installation

``bash
npm install web-annotation-renderer
`

Requirements:

- Node.js >= 18
- React 18 or 19 (only if using React adapter)

Worker Configuration

Important: Before using the library, configure the PDF.js worker in your application:

`javascript
import * as pdfjsLib from "pdfjs-dist";

pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url
).toString();
`

This must be done once at application startup, before using any PDF functionality.

Quick Start - Vanilla JavaScript

`javascript
import { AnnotationRenderer } from "web-annotation-renderer";
import * as pdfjsLib from "pdfjs-dist";

// Configure PDF.js worker (call once at app startup)
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url
).toString();

// Create renderer instance
const renderer = new AnnotationRenderer({
container: document.getElementById("annotation-container"),
canvasElement: document.getElementById("pdf-canvas"),
});

// Load PDF
const result = await renderer.loadPDF("/path/to/document.pdf");
if (result.success) {
console.log(PDF loaded with ${result.pageCount} pages);
}

// Set annotations
renderer.setAnnotations([
{
id: "1",
type: "highlight",
page: 1,
start: 0,
end: 5,
mode: "quads",
quads: [{ x: 0.1, y: 0.2, w: 0.3, h: 0.05 }],
style: { color: "rgba(255, 255, 0, 0.3)" },
},
]);

// Set initial page and scale
await renderer.setPage(1);
await renderer.setScale(1.0);

// Update timeline position
renderer.setTime(2.5); // seconds
`

Quick Start - React

`javascript
import { useState } from "react";
import { AnnotPdf } from "web-annotation-renderer";
import * as pdfjsLib from "pdfjs-dist";

// Configure PDF.js worker (call once at app startup)
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url
).toString();

function App() {
const [currentTime, setCurrentTime] = useState(0);
const [page, setPage] = useState(1);
const [totalPages, setTotalPages] = useState(1);

const annotations = [
{
id: "1",
type: "highlight",
page: 1,
start: 0,
end: 5,
mode: "quads",
quads: [{ x: 0.1, y: 0.2, w: 0.3, h: 0.05 }],
style: { color: "rgba(255, 255, 0, 0.3)" },
},
];

const handleLoad = (pdfDocument) => {
setTotalPages(pdfDocument.pageCount);
console.log(PDF loaded with ${pdfDocument.pageCount} pages);
};

const handleError = (error) => {
console.error("PDF Error:", error);
};

return (
pdfUrl="/path/to/document.pdf"
annotations={annotations}
currentTime={currentTime}
page={page}
scale={1.5}
onLoad={handleLoad}
onError={handleError}
onPageChange={setPage}
/>
);
}
`

Audio/Video Synchronization

For smooth, real-time synchronization with audio or video playback, use the continuous sync feature:

$3

`javascript
const renderer = new AnnotationRenderer({
container: document.getElementById("annotation-container"),
canvasElement: document.getElementById("pdf-canvas"),
});

await renderer.loadPDF("/document.pdf");
await renderer.setPage(1);

// Get reference to audio/video element
const audioElement = document.getElementById("lecture-audio");

// Start continuous sync when playback begins
audioElement.addEventListener("play", () => {
renderer.timelineSync.startContinuousSync(() => audioElement.currentTime);
});

// Stop continuous sync when playback pauses
audioElement.addEventListener("pause", () => {
renderer.timelineSync.stopContinuousSync();
});

// Clean up on page unload
window.addEventListener("beforeunload", () => {
renderer.timelineSync.stopContinuousSync();
renderer.destroy();
});
`

$3

`javascript
import { useRef, useEffect } from "react";
import { AnnotPdf } from "web-annotation-renderer";

function VideoSyncViewer() {
const audioRef = useRef(null);
const engineRef = useRef(null);

// Access the internal engine through the component
useEffect(() => {
const audio = audioRef.current;
if (!audio) return;

const handlePlay = () => {
// Start continuous sync at 60fps
if (engineRef.current) {
engineRef.current.timelineSync.startContinuousSync(
() => audio.currentTime
);
}
};

const handlePause = () => {
// Stop continuous sync
if (engineRef.current) {
engineRef.current.timelineSync.stopContinuousSync();
}
};

audio.addEventListener("play", handlePlay);
audio.addEventListener("pause", handlePause);

return () => {
audio.removeEventListener("play", handlePlay);
audio.removeEventListener("pause", handlePause);
engineRef.current?.timelineSync.stopContinuousSync();
};
}, []);

return (



);
}
`

How it works:
- startContinuousSync() creates a 60fps requestAnimationFrame loop
- Each frame reads the current time from your callback function
- Annotations update smoothly in sync with playback
- stopContinuousSync() stops the loop to save resources when paused

For manual controls (sliders, buttons), simply use renderer.setTime() or the currentTime prop - continuous sync is not needed.

Multilingual Text Support

The library supports hand-written style text rendering for multiple languages using single-stroke fonts.

$3

| Language | Unicode Range | Characters | Loading | Status |
|----------|---------------|------------|---------|--------|
| Latin | U+0000-007F | 78 (A-Z, a-z, 0-9, punctuation) | Bundled | ✅ Ready |
| Korean | U+AC00-D7A3 | 11,172 (가-힣, all syllables) | Bundled | ✅ Ready |
| CJK (Chinese/Japanese Kanji) | U+4E00-9FFF | 20,976 | Dynamic | ⚠️ Requires preload |

$3

| Configuration | Size (gzip) |
|---------------|-------------|
| Core + Latin | ~50 KB |
| Core + Latin + Korean | ~639 KB |
| CJK data (separate) | ~2 MB |

$3

CJK character data is not bundled by default due to its large size (~10MB uncompressed). You must preload it before rendering CJK text.

#### Step 1: Serve the CJK data file

Copy node_modules/web-annotation-renderer/public/cjk.json to your public assets folder.

#### Step 2: Preload before rendering

`javascript
import { preloadCJK } from "web-annotation-renderer";

// Option 1: Default path (/cjk.json)
await preloadCJK();

// Option 2: Custom path
await preloadCJK("/assets/fonts/cjk.json");

// Now CJK characters will render correctly
renderer.setAnnotations([
{
id: "chinese-text",
type: "text",
page: 1,
start: 0,
end: 5,
content: "中文文字", // Chinese text
x: 0.1,
y: 0.2,
fontSize: 24,
},
]);
`

#### Important Notes

- Without preloading: CJK characters will silently fail to render (no error, just blank)
- Preload timing: Call preloadCJK() early in your app initialization
- Caching: The library caches CJK data after first load; subsequent calls are no-ops
- Mixed text: Latin and Korean render immediately; only CJK requires preloading

$3

The following character ranges are not currently supported:

| Type | Examples | Workaround |
|------|----------|------------|
| Extended Latin | é, ñ, ü, ø | Use ASCII equivalents |
| Korean Jamo | ㄱ, ㅏ, ㄴ | Use complete syllables (가, 나) |
| Japanese Hiragana/Katakana | あ, ア | Not supported |
| Emoji | 😀, 🎉 | Not supported |

Unsupported characters are skipped during rendering with default spacing.

API Reference

$3

#### Constructor

`javascript
const renderer = new AnnotationRenderer(config);
`

Configuration Options:

| Property | Type | Required | Default | Description |
| --------------- | ----------------- | -------- | ------- | -------------------------------------- |
| container | HTMLElement | ✅ Yes | - | DOM element for annotation layers |
| canvasElement | HTMLCanvasElement | ✅ Yes | - | Canvas element for PDF rendering |
| pdfUrl | string | No | null | PDF URL to auto-load on initialization |
| initialPage | number | No | 1 | Initial page number to display |
| initialScale | number | No | 1.0 | Initial zoom/scale factor |
| annotations | Array | No | [] | Initial annotation data |

Example:

`javascript
const renderer = new AnnotationRenderer({
container: document.getElementById("annotation-container"),
canvasElement: document.getElementById("pdf-canvas"),
pdfUrl: "/document.pdf", // Optional: auto-load
initialPage: 1,
initialScale: 1.5,
annotations: [],
});
`

#### Methods

##### loadPDF(url)

Load a PDF document from URL.

`javascript
const result = await renderer.loadPDF("/path/to/document.pdf");
`

Parameters:

- url (string): URL or path to PDF file

Returns: Promise