This commit removes the initialize() method from all engine classes. PDFium is now automatically initialized in the constructor, simplifying the API and reducing boilerplate.

Author: bobsingor

.changeset/remove-initialize-constructor-init.md

@@ -0,0 +1,92 @@
+---
+'@embedpdf/engines': major
+'@embedpdf/models': major
+'@embedpdf/core': minor
+---
+
+# Remove `initialize()` - PDFium Now Initializes in Constructor
+
+This release removes the `initialize()` method from all engine classes. PDFium is now automatically initialized in the constructor, simplifying the API and reducing boilerplate.
+
+## Breaking Changes
+
+### `initialize()` Method Removed
+
+The `initialize()` method has been removed from:
+
+- `PdfiumNative` (formerly `PdfiumEngine`)
+- `PdfEngine` orchestrator
+- `RemoteExecutor`
+- `WebWorkerEngine`
+- `IPdfiumExecutor` interface
+- `PdfEngine` interface (in models)
+
+**Migration:**
+
+```typescript
+// Before
+const native = new PdfiumNative(wasmModule, { logger });
+native.initialize();
+
+const engine = new PdfEngine(native, { imageConverter, logger });
+engine.initialize();
+
+// After - no initialize() needed!
+const native = new PdfiumNative(wasmModule, { logger });
+const engine = new PdfEngine(native, { imageConverter, logger });
+
+// Ready to use immediately
+const doc = await engine.openDocumentBuffer(file).toPromise();
+```
+
+### Framework Hooks Simplified
+
+The `usePdfiumEngine` hooks (React, Vue, Svelte) no longer require calling `initialize()`:
+
+```typescript
+// Before
+const { engine, isLoading } = usePdfiumEngine();
+const [initialized, setInitialized] = useState(false);
+
+useEffect(() => {
+  if (engine && !initialized) {
+    engine.initialize().wait(setInitialized, ignore);
+  }
+}, [engine, initialized]);
+
+// After - engine is ready when returned!
+const { engine, isLoading } = usePdfiumEngine();
+
+if (!isLoading && engine) {
+  // Ready to use immediately
+}
+```
+
+### `PluginRegistry.ensureEngineInitialized()` Removed
+
+The `ensureEngineInitialized()` method and `engineInitialized` property have been removed from `PluginRegistry` since engines are now initialized in their constructors.
+
+## Cross-Platform Image Data
+
+### `ImageData` → `ImageDataLike`
+
+The engine now returns `ImageDataLike` (a plain object with `data`, `width`, `height`) instead of the browser-specific `ImageData` class. This enables Node.js compatibility without polyfills.
+
+**Affected types:**
+
+- `PdfImageObject.imageData` now uses `ImageDataLike`
+- All raw render methods return `ImageDataLike`
+
+### Browser Converter Fallback
+
+`browserImageDataToBlobConverter` now falls back to regular `<canvas>` when `OffscreenCanvas` is not available (older browsers). The hybrid converter (`createHybridImageConverter`) uses:
+
+1. Worker pool with `OffscreenCanvas` (preferred, non-blocking)
+2. Main-thread `<canvas>` fallback (blocking, but works everywhere)
+
+## Benefits
+
+- **Simpler API**: One less step to get started
+- **Less boilerplate**: No more `initialize()` calls in every component
+- **Node.js compatible**: `ImageDataLike` works without browser APIs
+- **Broader browser support**: Canvas fallback for older browsers

packages/core/src/lib/registry/plugin-registry.ts

@@ -34,7 +34,6 @@ export class PluginRegistry {
   private resolver: DependencyResolver;
   private configurations: Map<string, unknown> = new Map();
   private engine: PdfEngine;
-  private engineInitialized = false;
   private store: Store<CoreState, CoreAction>;
   private initPromise: Promise<void> | null = null;
   private logger: Logger;
@@ -62,23 +61,6 @@ export class PluginRegistry {
     return this.logger;
   }
 
-  /**
-   * Ensure engine is initialized before proceeding
-   */
-  private async ensureEngineInitialized(): Promise<void> {
-    if (this.engineInitialized) {
-      return;
-    }
-
-    if (this.engine.initialize) {
-      const task = this.engine.initialize();
-      await task.toPromise();
-      this.engineInitialized = true;
-    } else {
-      this.engineInitialized = true;
-    }
-  }
-
   /**
    * Register a plugin without initializing it
    */
@@ -181,7 +163,6 @@ export class PluginRegistry {
       this.isInitializing = true;
 
       try {
-        await this.ensureEngineInitialized();
         if (this.destroyed) return;
 
         while (this.pendingRegistrations.length > 0) {

packages/engines/README.md

@@ -10,7 +10,7 @@
 
 # @embedpdf/engines
 
-Pluggable rendering engines for EmbedPDF. Ships with **`PdfiumEngine`** – a high‑level, promise‑first wrapper built on top of `@embedpdf/pdfium`.
+Pluggable rendering engines for EmbedPDF. Ships with **`PdfiumNative`** (low-level executor) and **`PdfEngine`** (high-level orchestrator) – a promise‑first API built on top of `@embedpdf/pdfium`.
 
 ## Documentation
 
@@ -43,23 +43,29 @@ npm install @embedpdf/engines @embedpdf/pdfium
 
 ```typescript
 import { init } from '@embedpdf/pdfium';
-import { PdfiumEngine } from '@embedpdf/engines/pdfium';
+import { PdfiumNative, PdfEngine } from '@embedpdf/engines/pdfium';
+import { browserImageDataToBlobConverter } from '@embedpdf/engines/converters';
 
 const pdfiumWasm =
   'https://cdn.jsdelivr.net/npm/@embedpdf/pdfium/dist/pdfium.wasm';
 
 (async () => {
   const response = await fetch(pdfiumWasm);
   const wasmBinary = await response.arrayBuffer();
-  // 1 – boot the low‑level WASM module
-  const pdfium = await init({ wasmBinary });
 
-  // 2 – create the high‑level engine
-  const engine = new PdfiumEngine(pdfium);
-  engine.initialize();
+  // 1 – boot the low‑level WASM module
+  const pdfiumModule = await init({ wasmBinary });
 
-  // 3 – open & render
-  const document = await engine
+  // 2 – create the native executor (initializes PDFium automatically)
+  const native = new PdfiumNative(pdfiumModule);
+
+  // 3 – create the orchestrator with image converter
+  const engine = new PdfEngine(native, {
+    imageConverter: browserImageDataToBlobConverter,
+  });
+
+  // 4 – open & render
+  const doc = await engine
     .openDocumentUrl({ id: 'demo', url: '/demo.pdf' })
     .toPromise();
   const page0 = doc.pages[0];

packages/engines/demo/main.ts

@@ -36,8 +36,6 @@ async function run() {
   });
   const engine = new WebWorkerEngine(worker, logger);
 
-  engine.initialize();
-
   const passwordElem = document.getElementById('pdf-password') as HTMLInputElement;
   const inputElem = document.getElementById('pdf-file') as HTMLInputElement;
   const bookmarksElem = document.getElementById('pdf-bookmarks') as HTMLParagraphElement;

packages/engines/examples/node/annotation-render-example.js

@@ -4,25 +4,31 @@ import { fileURLToPath } from 'url';
 import sharp from 'sharp';
 
 import { init } from '@embedpdf/pdfium';
-import { PdfiumEngine } from '@embedpdf/engines/pdfium';
+import { PdfiumNative, PdfEngine } from '@embedpdf/engines/pdfium';
 import { createNodeImageDataToBufferConverter } from '@embedpdf/engines/converters';
 import { ConsoleLogger, Rotation } from '@embedpdf/models';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 async function runExample() {
-  const consoleLogger = new ConsoleLogger();
+  const logger = new ConsoleLogger();
 
+  // Create the image converter using sharp
   const imageConverter = createNodeImageDataToBufferConverter(sharp);
 
-  // Initialize PDFium
-  const pdfiumInstance = await init();
-  const engine = new PdfiumEngine(pdfiumInstance, {
-    logger: consoleLogger,
-    imageDataConverter: imageConverter,
+  // Initialize PDFium WASM module
+  const pdfiumModule = await init();
+
+  // Create the native executor (low-level PDFium wrapper)
+  const native = new PdfiumNative(pdfiumModule, { logger });
+
+  // Create the orchestrator (high-level API with priority scheduling)
+  // PdfiumNative initializes PDFium in its constructor, no separate init needed
+  const engine = new PdfEngine(native, {
+    imageConverter,
+    logger,
   });
-  engine.initialize();
 
   const pdfPath = process.argv[2] || join(__dirname, 'sample.pdf');
   const pdfBuffer = await readFile(pdfPath);

packages/engines/examples/node/basic-example.js

@@ -4,25 +4,31 @@ import { fileURLToPath } from 'url';
 import sharp from 'sharp';
 
 import { init } from '@embedpdf/pdfium';
-import { PdfiumEngine } from '@embedpdf/engines/pdfium';
+import { PdfiumNative, PdfEngine } from '@embedpdf/engines/pdfium';
 import { createNodeImageDataToBufferConverter } from '@embedpdf/engines/converters';
 import { ConsoleLogger, Rotation } from '@embedpdf/models';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 async function runExample() {
-  const consoleLogger = new ConsoleLogger();
+  const logger = new ConsoleLogger();
 
+  // Create the image converter using sharp
   const imageConverter = createNodeImageDataToBufferConverter(sharp);
 
-  // Initialize PDFium
-  const pdfiumInstance = await init();
-  const engine = new PdfiumEngine(pdfiumInstance, {
-    logger: consoleLogger,
-    imageDataConverter: imageConverter,
+  // Initialize PDFium WASM module
+  const pdfiumModule = await init();
+
+  // Create the native executor (low-level PDFium wrapper)
+  const native = new PdfiumNative(pdfiumModule, { logger });
+
+  // Create the orchestrator (high-level API with priority scheduling)
+  // PdfiumNative initializes PDFium in its constructor, no separate init needed
+  const engine = new PdfEngine(native, {
+    imageConverter,
+    logger,
   });
-  engine.initialize();
 
   const pdfPath = process.argv[2] || join(__dirname, 'sample.pdf');
   const pdfBuffer = await readFile(pdfPath);

packages/engines/examples/node/read-write-metadata.js

@@ -4,25 +4,31 @@ import { fileURLToPath } from 'url';
 import sharp from 'sharp';
 
 import { init } from '@embedpdf/pdfium';
-import { PdfiumEngine } from '@embedpdf/engines/pdfium';
+import { PdfiumNative, PdfEngine } from '@embedpdf/engines/pdfium';
 import { createNodeImageDataToBufferConverter } from '@embedpdf/engines/converters';
 import { ConsoleLogger, PdfTrappedStatus } from '@embedpdf/models';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 async function runExample() {
-  const consoleLogger = new ConsoleLogger();
+  const logger = new ConsoleLogger();
 
+  // Create the image converter using sharp
   const imageConverter = createNodeImageDataToBufferConverter(sharp);
 
-  // Initialize PDFium
-  const pdfiumInstance = await init();
-  const engine = new PdfiumEngine(pdfiumInstance, {
-    logger: consoleLogger,
-    imageDataConverter: imageConverter,
+  // Initialize PDFium WASM module
+  const pdfiumModule = await init();
+
+  // Create the native executor (low-level PDFium wrapper)
+  const native = new PdfiumNative(pdfiumModule, { logger });
+
+  // Create the orchestrator (high-level API with priority scheduling)
+  // PdfiumNative initializes PDFium in its constructor, no separate init needed
+  const engine = new PdfEngine(native, {
+    imageConverter,
+    logger,
   });
-  engine.initialize();
 
   const pdfPath = process.argv[2] || join(__dirname, 'ebook.pdf');
   const pdfBuffer = await readFile(pdfPath);