Merge branch 'feature/engine-performance' into next

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';