Skip to content

Commit 0c72618

Browse files
bobsingorbobsingor
committed
Merge branch 'next' of https://github.com/embedpdf/embed-pdf-viewer into next
2 parents e401e29 + 6c1e124 commit 0c72618

71 files changed

Lines changed: 529 additions & 35 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/pre.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
},
4949
"changesets": [
5050
"commands-svelte-use-current",
51+
"engine-orchestrator-architecture",
5152
"fix-document-manager-empty-array",
5253
"fix-i18n-vue-locale-reactivity",
5354
"hidden-items-dependency-rules",

‎packages/core/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# @embedpdf/core
22

3+
## 2.0.0-next.3
4+
35
## 2.0.0-next.2
46

57
## 2.0.0-next.1

‎packages/core/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@embedpdf/core",
3-
"version": "2.0.0-next.2",
3+
"version": "2.0.0-next.3",
44
"type": "module",
55
"license": "MIT",
66
"main": "./dist/index.cjs",

‎packages/engines/CHANGELOG.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,148 @@
11
# @embedpdf/engines
22

3+
## 2.0.0-next.3
4+
5+
### Major Changes
6+
7+
- [`f13b2d4`](https://github.com/embedpdf/embed-pdf-viewer/commit/f13b2d48eebd7b2f02e881fee80f68bf4219c1d6) by [@bobsingor](https://github.com/bobsingor) – # Major Engine Architecture Refactor: Orchestrator Layer & Image Encoding Pool
8+
9+
This release introduces a significant architectural improvement to the PDF engine system, separating concerns between execution and orchestration while adding parallel image encoding capabilities.
10+
11+
## Breaking Changes
12+
13+
### Engine Class Renamed
14+
- `PdfiumEngine` → `PdfiumNative` (the "dumb" executor)
15+
- New `PdfEngine` class wraps executors with orchestration logic
16+
- Factory functions (`createPdfiumEngine`) now return the orchestrated `PdfEngine<Blob>` wrapper
17+
18+
**Migration:**
19+
20+
```typescript
21+
// Before
22+
import { PdfiumEngine } from '@embedpdf/engines';
23+
const engine = new PdfiumEngine(wasmModule, { logger });
24+
25+
// After
26+
import { createPdfiumEngine } from '@embedpdf/engines/pdfium-worker-engine';
27+
// or
28+
import { createPdfiumEngine } from '@embedpdf/engines/pdfium-direct-engine';
29+
30+
const engine = await createPdfiumEngine('/wasm/pdfium.wasm', {
31+
logger,
32+
encoderPoolSize: 2, // Optional: parallel image encoding
33+
});
34+
```
35+
36+
### Rendering Methods Changed
37+
- `renderPage()` → Returns final encoded result (Blob) via orchestrator
38+
- `renderPageRaw()` → New method, returns raw `ImageData` from executor
39+
- `renderThumbnail()` → `renderThumbnailRaw()` for raw data
40+
- `renderPageAnnotation()` → `renderPageAnnotationRaw()` for raw data
41+
42+
### Search API Simplified
43+
- `searchAllPages()` → Now orchestrated at the `PdfEngine` level
44+
- `searchInPage()` → New single-page search method in executor
45+
- Progress tracking improved with proper `CompoundTask` support
46+
47+
### Document Loading Changes
48+
- Removed `openDocumentFromLoader()` - range request loading removed from executor
49+
- Removed `openDocumentUrl()` - URL fetching now handled in orchestrator
50+
- `openDocumentBuffer()` remains as the primary method in executor
51+
52+
## New Features
53+
54+
### 1. Orchestrator Architecture
55+
56+
New three-layer architecture:
57+
- **Executor Layer** (`PdfiumNative`, `RemoteExecutor`): "Dumb" workers that execute PDF operations
58+
- **Orchestrator Layer** (`PdfEngine`): "Smart" coordinator with priority queues and scheduling
59+
- **Worker Pool** (`ImageEncoderWorkerPool`): Parallel image encoding
60+
61+
Benefits:
62+
- Priority-based task scheduling
63+
- Visibility-aware rendering (viewport-based prioritization)
64+
- Parallel image encoding (non-blocking)
65+
- Automatic task cancellation and cleanup
66+
67+
### 2. Image Encoder Worker Pool
68+
69+
```typescript
70+
const engine = await createPdfiumEngine('/wasm/pdfium.wasm', {
71+
encoderPoolSize: 2, // Creates 2 encoder workers
72+
});
73+
```
74+
75+
- Offloads `OffscreenCanvas.convertToBlob()` from main PDFium worker
76+
- Prevents blocking during image encoding
77+
- Configurable pool size (default: 2 workers)
78+
- Automatic load balancing
79+
80+
### 3. Task Queue System
81+
82+
New `WorkerTaskQueue` with:
83+
- Priority levels: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`
84+
- Visibility-based ranking for render tasks
85+
- Automatic task deduplication
86+
- Graceful cancellation
87+
88+
### 4. CompoundTask for Multi-Page Operations
89+
90+
New `CompoundTask` class for aggregating results:
91+
92+
```typescript
93+
// Automatic progress tracking
94+
const task = engine.searchAllPages(doc, 'keyword');
95+
task.onProgress((progress) => {
96+
console.log(`Page ${progress.page} complete`);
97+
});
98+
```
99+
100+
- `CompoundTask.gather()` - Like `Promise.all()` with progress
101+
- `CompoundTask.gatherIndexed()` - Returns `Record<number, Result>`
102+
- `CompoundTask.first()` - Like `Promise.race()`
103+
- Automatic child task cleanup
104+
105+
## API Additions
106+
107+
### Models Package
108+
- `CompoundTask` - Multi-task aggregation with progress
109+
- `ImageConversionTypes` type refinements
110+
- `PdfAnnotationsProgress.result` (renamed from `annotations`)
111+
112+
### Engines Package
113+
114+
New exports:
115+
- `PdfEngine` - Main orchestrator class
116+
- `RemoteExecutor` - Worker communication proxy
117+
- `ImageEncoderWorkerPool` - Image encoding pool
118+
- `WorkerTaskQueue` - Priority-based queue
119+
- `PdfiumNative` - Renamed from `PdfiumEngine`
120+
121+
New image converters:
122+
- `browserImageDataToBlobConverter` - Legacy converter
123+
- `createWorkerPoolImageConverter()` - Pool-based converter
124+
- `createHybridImageConverter()` - Fallback support
125+
126+
### Plugin-Render Package
127+
128+
New config options:
129+
130+
```typescript
131+
{
132+
render: {
133+
defaultImageType: 'image/webp',
134+
defaultImageQuality: 0.92
135+
}
136+
}
137+
```
138+
139+
## Improvements
140+
- **Performance**: Parallel image encoding improves render throughput by ~40-60%
141+
- **Responsiveness**: Priority queues ensure visible pages render first
142+
- **Memory**: Better cleanup of completed tasks and worker references
143+
- **Logging**: Enhanced performance logging with duration tracking
144+
- **Developer Experience**: Clearer separation of concerns
145+
3146
## 2.0.0-next.2
4147

5148
## 2.0.0-next.1

‎packages/engines/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@embedpdf/engines",
3-
"version": "2.0.0-next.2",
3+
"version": "2.0.0-next.3",
44
"description": "Pluggable runtime layer that abstracts over multiple PDF engines (PDF-ium, Web Workers, mocks, etc.) to provide a unified API for rendering, search, annotation, and other document-level operations in EmbedPDF.",
55
"type": "module",
66
"main": "./dist/index.cjs",

‎packages/models/CHANGELOG.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,148 @@
11
# @embedpdf/models
22

3+
## 2.0.0-next.3
4+
5+
### Minor Changes
6+
7+
- [`f13b2d4`](https://github.com/embedpdf/embed-pdf-viewer/commit/f13b2d48eebd7b2f02e881fee80f68bf4219c1d6) by [@bobsingor](https://github.com/bobsingor) – # Major Engine Architecture Refactor: Orchestrator Layer & Image Encoding Pool
8+
9+
This release introduces a significant architectural improvement to the PDF engine system, separating concerns between execution and orchestration while adding parallel image encoding capabilities.
10+
11+
## Breaking Changes
12+
13+
### Engine Class Renamed
14+
- `PdfiumEngine` → `PdfiumNative` (the "dumb" executor)
15+
- New `PdfEngine` class wraps executors with orchestration logic
16+
- Factory functions (`createPdfiumEngine`) now return the orchestrated `PdfEngine<Blob>` wrapper
17+
18+
**Migration:**
19+
20+
```typescript
21+
// Before
22+
import { PdfiumEngine } from '@embedpdf/engines';
23+
const engine = new PdfiumEngine(wasmModule, { logger });
24+
25+
// After
26+
import { createPdfiumEngine } from '@embedpdf/engines/pdfium-worker-engine';
27+
// or
28+
import { createPdfiumEngine } from '@embedpdf/engines/pdfium-direct-engine';
29+
30+
const engine = await createPdfiumEngine('/wasm/pdfium.wasm', {
31+
logger,
32+
encoderPoolSize: 2, // Optional: parallel image encoding
33+
});
34+
```
35+
36+
### Rendering Methods Changed
37+
- `renderPage()` → Returns final encoded result (Blob) via orchestrator
38+
- `renderPageRaw()` → New method, returns raw `ImageData` from executor
39+
- `renderThumbnail()` → `renderThumbnailRaw()` for raw data
40+
- `renderPageAnnotation()` → `renderPageAnnotationRaw()` for raw data
41+
42+
### Search API Simplified
43+
- `searchAllPages()` → Now orchestrated at the `PdfEngine` level
44+
- `searchInPage()` → New single-page search method in executor
45+
- Progress tracking improved with proper `CompoundTask` support
46+
47+
### Document Loading Changes
48+
- Removed `openDocumentFromLoader()` - range request loading removed from executor
49+
- Removed `openDocumentUrl()` - URL fetching now handled in orchestrator
50+
- `openDocumentBuffer()` remains as the primary method in executor
51+
52+
## New Features
53+
54+
### 1. Orchestrator Architecture
55+
56+
New three-layer architecture:
57+
- **Executor Layer** (`PdfiumNative`, `RemoteExecutor`): "Dumb" workers that execute PDF operations
58+
- **Orchestrator Layer** (`PdfEngine`): "Smart" coordinator with priority queues and scheduling
59+
- **Worker Pool** (`ImageEncoderWorkerPool`): Parallel image encoding
60+
61+
Benefits:
62+
- Priority-based task scheduling
63+
- Visibility-aware rendering (viewport-based prioritization)
64+
- Parallel image encoding (non-blocking)
65+
- Automatic task cancellation and cleanup
66+
67+
### 2. Image Encoder Worker Pool
68+
69+
```typescript
70+
const engine = await createPdfiumEngine('/wasm/pdfium.wasm', {
71+
encoderPoolSize: 2, // Creates 2 encoder workers
72+
});
73+
```
74+
75+
- Offloads `OffscreenCanvas.convertToBlob()` from main PDFium worker
76+
- Prevents blocking during image encoding
77+
- Configurable pool size (default: 2 workers)
78+
- Automatic load balancing
79+
80+
### 3. Task Queue System
81+
82+
New `WorkerTaskQueue` with:
83+
- Priority levels: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`
84+
- Visibility-based ranking for render tasks
85+
- Automatic task deduplication
86+
- Graceful cancellation
87+
88+
### 4. CompoundTask for Multi-Page Operations
89+
90+
New `CompoundTask` class for aggregating results:
91+
92+
```typescript
93+
// Automatic progress tracking
94+
const task = engine.searchAllPages(doc, 'keyword');
95+
task.onProgress((progress) => {
96+
console.log(`Page ${progress.page} complete`);
97+
});
98+
```
99+
100+
- `CompoundTask.gather()` - Like `Promise.all()` with progress
101+
- `CompoundTask.gatherIndexed()` - Returns `Record<number, Result>`
102+
- `CompoundTask.first()` - Like `Promise.race()`
103+
- Automatic child task cleanup
104+
105+
## API Additions
106+
107+
### Models Package
108+
- `CompoundTask` - Multi-task aggregation with progress
109+
- `ImageConversionTypes` type refinements
110+
- `PdfAnnotationsProgress.result` (renamed from `annotations`)
111+
112+
### Engines Package
113+
114+
New exports:
115+
- `PdfEngine` - Main orchestrator class
116+
- `RemoteExecutor` - Worker communication proxy
117+
- `ImageEncoderWorkerPool` - Image encoding pool
118+
- `WorkerTaskQueue` - Priority-based queue
119+
- `PdfiumNative` - Renamed from `PdfiumEngine`
120+
121+
New image converters:
122+
- `browserImageDataToBlobConverter` - Legacy converter
123+
- `createWorkerPoolImageConverter()` - Pool-based converter
124+
- `createHybridImageConverter()` - Fallback support
125+
126+
### Plugin-Render Package
127+
128+
New config options:
129+
130+
```typescript
131+
{
132+
render: {
133+
defaultImageType: 'image/webp',
134+
defaultImageQuality: 0.92
135+
}
136+
}
137+
```
138+
139+
## Improvements
140+
- **Performance**: Parallel image encoding improves render throughput by ~40-60%
141+
- **Responsiveness**: Priority queues ensure visible pages render first
142+
- **Memory**: Better cleanup of completed tasks and worker references
143+
- **Logging**: Enhanced performance logging with duration tracking
144+
- **Developer Experience**: Clearer separation of concerns
145+
3146
## 2.0.0-next.2
4147

5148
## 2.0.0-next.1

‎packages/models/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@embedpdf/models",
3-
"version": "2.0.0-next.2",
3+
"version": "2.0.0-next.3",
44
"private": false,
55
"description": "Shared type definitions, data models, and utility helpers (geometry, tasks, logging, PDF primitives) that underpin every package in the EmbedPDF ecosystem.",
66
"type": "module",

‎packages/pdfium/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# @embedpdf/pdfium
22

3+
## 2.0.0-next.3
4+
35
## 2.0.0-next.2
46

57
## 2.0.0-next.1

‎packages/pdfium/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@embedpdf/pdfium",
3-
"version": "2.0.0-next.2",
3+
"version": "2.0.0-next.3",
44
"private": false,
55
"description": "PDFium WebAssembly for the web platform. This package provides a powerful JavaScript interface to PDFium, enabling high-quality PDF rendering and manipulation directly in web applications.",
66
"type": "module",

‎packages/plugin-annotation/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# @embedpdf/plugin-annotation
22

3+
## 2.0.0-next.3
4+
35
## 2.0.0-next.2
46

57
## 2.0.0-next.1

0 commit comments

Comments
 (0)