Add orchestrator and image encoder infrastructure

Introduces a new orchestrator layer for PDF engines, including task queueing, priority scheduling, and visibility-aware task ranking. Adds a dedicated image encoder worker pool to offload image encoding from the main PDFium worker, with supporting modules for worker management and encoding. Refactors PDFium engine integration to use the orchestrator and encoder pool, and removes legacy test files. Updates related plugin and shared code to support the new architecture.

Author: bobsingor

.husky/pre-commit

@@ -1,2 +1,13 @@
 #!/usr/bin/env sh
-./node_modules/.bin/lint-staged
+# Cross-platform pre-commit for GitHub Desktop, macOS, Windows (Git Bash), Linux.
+
+# Make Node visible for GUI apps (harmless elsewhere)
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# Load nvm if present (no-op if missing)
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+# Prefer Node's built-in npx so we don't rely on pnpm/yarn on PATH
+# --no-install ensures it uses the local devDependency
+exec npx --no-install lint-staged

packages/engines/src/lib/image-encoder/image-encoder-worker.ts

@@ -0,0 +1,94 @@
+/**
+ * Dedicated worker for image encoding operations
+ * Offloads OffscreenCanvas.convertToBlob() from the main PDFium worker
+ */
+
+export interface EncodeImageRequest {
+  id: string;
+  type: 'encode';
+  data: {
+    imageData: {
+      data: Uint8ClampedArray;
+      width: number;
+      height: number;
+    };
+    imageType: 'image/png' | 'image/jpeg' | 'image/webp';
+    quality?: number;
+  };
+}
+
+export interface EncodeImageResponse {
+  id: string;
+  type: 'result' | 'error';
+  data: Blob | { message: string };
+}
+
+/**
+ * Encode ImageData to Blob using OffscreenCanvas
+ */
+async function encodeImage(
+  imageData: { data: Uint8ClampedArray; width: number; height: number },
+  imageType: 'image/png' | 'image/jpeg' | 'image/webp',
+  quality?: number,
+): Promise<Blob> {
+  if (typeof OffscreenCanvas === 'undefined') {
+    throw new Error('OffscreenCanvas is not available in this worker environment');
+  }
+
+  const { data, width, height } = imageData;
+
+  // Create ImageData from the raw data
+  // Need to create a new Uint8ClampedArray to avoid type issues with ArrayBufferLike
+  const imgData = new ImageData(new Uint8ClampedArray(data), width, height);
+
+  // Create OffscreenCanvas and render
+  const canvas = new OffscreenCanvas(width, height);
+  const ctx = canvas.getContext('2d');
+
+  if (!ctx) {
+    throw new Error('Failed to get 2D context from OffscreenCanvas');
+  }
+
+  ctx.putImageData(imgData, 0, 0);
+
+  // Convert to blob
+  return canvas.convertToBlob({ type: imageType, quality });
+}
+
+/**
+ * Handle incoming encoding requests
+ */
+self.onmessage = async (event: MessageEvent<EncodeImageRequest>) => {
+  const request = event.data;
+
+  if (request.type !== 'encode') {
+    return;
+  }
+
+  try {
+    const { imageData, imageType, quality } = request.data;
+
+    // Perform the encoding
+    const blob = await encodeImage(imageData, imageType, quality);
+
+    // Send back the result
+    const response: EncodeImageResponse = {
+      id: request.id,
+      type: 'result',
+      data: blob,
+    };
+
+    self.postMessage(response);
+  } catch (error) {
+    // Send back error
+    const response: EncodeImageResponse = {
+      id: request.id,
+      type: 'error',
+      data: {
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+
+    self.postMessage(response);
+  }
+};

packages/engines/src/lib/image-encoder/index.ts

@@ -0,0 +1,2 @@
+export * from './worker-pool';
+export type { EncodeImageRequest, EncodeImageResponse } from './image-encoder-worker';

packages/engines/src/lib/image-encoder/worker-pool.ts

@@ -0,0 +1,190 @@
+import { Logger, NoopLogger } from '@embedpdf/models';
+import type { EncodeImageRequest, EncodeImageResponse } from './image-encoder-worker';
+
+const LOG_SOURCE = 'ImageEncoderPool';
+const LOG_CATEGORY = 'Encoder';
+
+interface EncodingTask {
+  resolve: (blob: Blob) => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Pool of image encoding workers to offload OffscreenCanvas operations
+ * from the main PDFium worker thread
+ */
+export class ImageEncoderWorkerPool {
+  private workers: Worker[] = [];
+  private pendingTasks = new Map<string, EncodingTask>();
+  private nextWorkerId = 0;
+  private requestCounter = 0;
+  private logger: Logger;
+
+  /**
+   * Create a pool of image encoding workers
+   * @param poolSize - Number of workers to create (default: 2)
+   * @param workerUrl - URL to the worker script
+   * @param logger - Logger instance
+   */
+  constructor(
+    private poolSize: number = 2,
+    private workerUrl: string,
+    logger?: Logger,
+  ) {
+    this.logger = logger ?? new NoopLogger();
+    this.initialize();
+  }
+
+  /**
+   * Initialize the worker pool
+   */
+  private initialize() {
+    this.logger.debug(
+      LOG_SOURCE,
+      LOG_CATEGORY,
+      `Creating worker pool with ${this.poolSize} workers`,
+    );
+
+    for (let i = 0; i < this.poolSize; i++) {
+      try {
+        const worker = new Worker(this.workerUrl, { type: 'module' });
+        worker.onmessage = this.handleWorkerMessage.bind(this);
+        worker.onerror = this.handleWorkerError.bind(this);
+        this.workers.push(worker);
+
+        this.logger.debug(LOG_SOURCE, LOG_CATEGORY, `Worker ${i} created successfully`);
+      } catch (error) {
+        this.logger.error(LOG_SOURCE, LOG_CATEGORY, `Failed to create worker ${i}:`, error);
+      }
+    }
+  }
+
+  /**
+   * Handle messages from workers
+   */
+  private handleWorkerMessage(event: MessageEvent<EncodeImageResponse>) {
+    const response = event.data;
+    const task = this.pendingTasks.get(response.id);
+
+    if (!task) {
+      this.logger.warn(
+        LOG_SOURCE,
+        LOG_CATEGORY,
+        `Received response for unknown task: ${response.id}`,
+      );
+      return;
+    }
+
+    this.pendingTasks.delete(response.id);
+
+    if (response.type === 'result') {
+      task.resolve(response.data as Blob);
+    } else {
+      const errorData = response.data as { message: string };
+      task.reject(new Error(errorData.message));
+    }
+  }
+
+  /**
+   * Handle worker errors
+   */
+  private handleWorkerError(error: ErrorEvent) {
+    this.logger.error(LOG_SOURCE, LOG_CATEGORY, 'Worker error:', error.message);
+  }
+
+  /**
+   * Get the next available worker using round-robin
+   */
+  private getNextWorker(): Worker | null {
+    if (this.workers.length === 0) {
+      return null;
+    }
+
+    const worker = this.workers[this.nextWorkerId];
+    this.nextWorkerId = (this.nextWorkerId + 1) % this.workers.length;
+    return worker;
+  }
+
+  /**
+   * Encode ImageData to Blob using a worker from the pool
+   * @param imageData - Raw image data
+   * @param imageType - Target image format
+   * @param quality - Image quality (0-1) for lossy formats
+   * @returns Promise that resolves to encoded Blob
+   */
+  encode(
+    imageData: { data: Uint8ClampedArray; width: number; height: number },
+    imageType: 'image/png' | 'image/jpeg' | 'image/webp' = 'image/webp',
+    quality?: number,
+  ): Promise<Blob> {
+    return new Promise((resolve, reject) => {
+      const worker = this.getNextWorker();
+
+      if (!worker) {
+        reject(new Error('No workers available in the pool'));
+        return;
+      }
+
+      const requestId = `encode-${Date.now()}-${this.requestCounter++}`;
+      this.pendingTasks.set(requestId, { resolve, reject });
+
+      const request: EncodeImageRequest = {
+        id: requestId,
+        type: 'encode',
+        data: {
+          imageData: {
+            data: imageData.data,
+            width: imageData.width,
+            height: imageData.height,
+          },
+          imageType,
+          quality,
+        },
+      };
+
+      this.logger.debug(
+        LOG_SOURCE,
+        LOG_CATEGORY,
+        `Sending encoding request ${requestId} (${imageData.width}x${imageData.height})`,
+      );
+
+      // Transfer the buffer for better performance
+      worker.postMessage(request, [imageData.data.buffer]);
+    });
+  }
+
+  /**
+   * Destroy all workers in the pool
+   */
+  destroy() {
+    this.logger.debug(LOG_SOURCE, LOG_CATEGORY, 'Destroying worker pool');
+
+    // Reject all pending tasks
+    this.pendingTasks.forEach((task, id) => {
+      task.reject(new Error('Worker pool destroyed'));
+      this.logger.debug(LOG_SOURCE, LOG_CATEGORY, `Rejected pending task: ${id}`);
+    });
+    this.pendingTasks.clear();
+
+    // Terminate all workers
+    this.workers.forEach((worker, index) => {
+      worker.terminate();
+      this.logger.debug(LOG_SOURCE, LOG_CATEGORY, `Worker ${index} terminated`);
+    });
+    this.workers = [];
+  }
+
+  /**
+   * Get the number of active workers in the pool
+   */
+  get activeWorkers(): number {
+    return this.workers.length;
+  }
+
+  /**
+   * Get the number of pending encoding tasks
+   */
+  get pendingTasksCount(): number {
+    return this.pendingTasks.size;
+  }
+}

packages/engines/src/lib/orchestrator/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Orchestrator layer for PDF engines
+ *
+ * This module provides the "smart" orchestration layer that wraps
+ * the "dumb" executor (PdfiumNative or RemoteExecutor) with:
+ * - Priority-based task scheduling
+ * - Visibility-aware task ranking
+ * - Parallel image encoding
+ * - Multi-page operation orchestration
+ *
+ * @packageDocumentation
+ */
+
+export * from './task-queue';
+export * from './pdf-engine';
+export * from './remote-executor';
+export * from './pdfium-native-runner';