squash perf experiments

Author: Schibum

.gitignore

@@ -15,3 +15,4 @@ config/tsup.frameworks.config.bundled*
 publish-summary.json
 **/.svelte-kit
 **/*/*.tgz
+.envrc

packages/engines/src/lib/extract-transferables.ts

@@ -0,0 +1,40 @@
+/**
+ * Recursively walks a response object and collects Transferable entries
+ * (ArrayBuffer from typed arrays, raw ArrayBuffer, ImageBitmap).
+ * Uses a Set to deduplicate — postMessage throws on duplicate transferables.
+ *
+ * Depth-limited to 6 to cover the deepest nesting in this codebase:
+ *   response.data.result[annotId][mode].data.data  (AnnotationAppearanceMap)
+ */
+export function extractTransferables(obj: unknown, depth = 6): Transferable[] {
+  const set = new Set<Transferable>();
+  collect(obj, depth, set);
+  return Array.from(set);
+}
+
+function collect(value: unknown, depth: number, set: Set<Transferable>): void {
+  if (depth < 0 || value == null) return;
+
+  if (value instanceof ArrayBuffer) {
+    set.add(value);
+    return;
+  }
+
+  if (ArrayBuffer.isView(value)) {
+    set.add(value.buffer as ArrayBuffer);
+    return;
+  }
+
+  if (typeof value !== 'object') return;
+
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      collect(value[i], depth - 1, set);
+    }
+    return;
+  }
+
+  for (const key in value as Record<string, unknown>) {
+    collect((value as Record<string, unknown>)[key], depth - 1, set);
+  }
+}

packages/engines/src/lib/orchestrator/pdf-engine.ts

@@ -322,7 +322,7 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
         execute: () => this.executor.renderPageRaw(doc, page, options),
         meta: { docId: doc.id, pageIndex: page.index, operation: 'renderPageRaw' },
       },
-      { priority: Priority.HIGH },
+      { priority: options?.priority ?? Priority.HIGH },
     );
   }
 
@@ -337,7 +337,7 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
         execute: () => this.executor.renderPageRect(doc, page, rect, options),
         meta: { docId: doc.id, pageIndex: page.index, operation: 'renderPageRectRaw' },
       },
-      { priority: Priority.HIGH },
+      { priority: options?.priority ?? Priority.HIGH },
     );
   }
 
@@ -488,9 +488,14 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
       height: rawImageData.height,
     };
 
+    const sizeLabel = `${rawImageData.width}x${rawImageData.height}`;
+    this.logger.perf(LOG_SOURCE, 'encodeImage', 'encode', 'Begin', sizeLabel);
     this.options
       .imageConverter(() => plainImageData, imageType, quality)
-      .then((result) => resultTask.resolve(result))
+      .then((result) => {
+        this.logger.perf(LOG_SOURCE, 'encodeImage', 'encode', 'End', sizeLabel);
+        resultTask.resolve(result);
+      })
       .catch((error) => resultTask.reject({ code: PdfErrorCode.Unknown, message: String(error) }));
   }
 

packages/engines/src/lib/orchestrator/pdfium-native-runner.ts

@@ -1,6 +1,7 @@
 import { Logger, NoopLogger, Task, TaskError, PdfErrorCode } from '@embedpdf/models';
 import { PdfiumNative } from '../pdfium/engine';
 import { init } from '@embedpdf/pdfium';
+import { extractTransferables } from '../extract-transferables';
 
 const LOG_SOURCE = 'PdfiumNativeRunner';
 const LOG_CATEGORY = 'Worker';
@@ -255,7 +256,7 @@ export class PdfiumNativeRunner {
    */
   private respond(response: WorkerResponse): void {
     this.logger.debug(LOG_SOURCE, LOG_CATEGORY, 'Sending response:', response.type);
-    self.postMessage(response);
+    self.postMessage(response, { transfer: extractTransferables(response) });
   }
 
   /**

packages/engines/src/lib/webworker/runner.ts

@@ -9,6 +9,7 @@ import {
   PdfErrorCode,
   TaskReturn,
 } from '@embedpdf/models';
+import { extractTransferables } from '../extract-transferables';
 
 /**
  * Request body that represent method calls of PdfEngine, it contains the
@@ -472,6 +473,6 @@ export class EngineRunner {
    */
   respond(response: Response) {
     this.logger.debug(LOG_SOURCE, LOG_CATEGORY, 'runner respond: ', response);
-    self.postMessage(response);
+    self.postMessage(response, { transfer: extractTransferables(response) });
   }
 }

packages/models/src/pdf.ts

@@ -2940,6 +2940,10 @@ export interface PdfRenderOptions {
    * Image quality (0-1) for jpeg and png
    */
   imageQuality?: number;
+  /**
+   * Scheduling priority (higher = more urgent). Only used by the orchestrator engine.
+   */
+  priority?: number;
 }
 
 export interface ConvertToBlobOptions {

packages/models/src/task.ts

@@ -271,6 +271,61 @@ export class Task<R, D, P = unknown> {
     }
   }
 
+  /**
+   * Transform the result of this task using a mapping function.
+   * Returns a new Task that resolves with the mapped value.
+   * Aborting the derived task also aborts the source task.
+   *
+   * @param fn - mapping function (may return a value or a Promise)
+   * @returns a new Task that resolves with the mapped result
+   */
+  map<U>(fn: (result: R) => U | Promise<U>): Task<U, D> {
+    const derived = new Task<U, D>();
+
+    // Wire abort propagation: aborting derived aborts source
+    const originalAbort = derived.abort.bind(derived);
+    derived.abort = (reason: D) => {
+      this.abort(reason);
+      originalAbort(reason);
+    };
+
+    this.wait(
+      (result) => {
+        if (derived.state.stage !== TaskStage.Pending) return;
+        try {
+          const mapped = fn(result);
+          if (mapped instanceof Promise) {
+            mapped.then(
+              (value) => {
+                if (derived.state.stage === TaskStage.Pending) {
+                  derived.resolve(value);
+                }
+              },
+              (err) => {
+                if (derived.state.stage === TaskStage.Pending) {
+                  derived.reject(err);
+                }
+              },
+            );
+          } else {
+            derived.resolve(mapped);
+          }
+        } catch (err) {
+          if (derived.state.stage === TaskStage.Pending) {
+            derived.reject(err as D);
+          }
+        }
+      },
+      (error) => {
+        if (derived.state.stage === TaskStage.Pending) {
+          derived.fail(error);
+        }
+      },
+    );
+
+    return derived;
+  }
+
   /**
    * add a progress callback
    * @param cb - progress callback

packages/plugin-render/src/lib/render-plugin.ts

@@ -1,4 +1,5 @@
 import { BasePlugin, PluginRegistry } from '@embedpdf/core';
+import { PdfDocumentObject, PdfPageObject, PdfRenderPageOptions } from '@embedpdf/models';
 import {
   RenderCapability,
   RenderPageOptions,
@@ -32,6 +33,9 @@ export class RenderPlugin extends BasePlugin<RenderPluginConfig, RenderCapabilit
       renderPageRect: (options: RenderPageRectOptions) => this.renderPageRect(options),
       renderPageRaw: (options: RenderPageOptions) => this.renderPageRaw(options),
       renderPageRectRaw: (options: RenderPageRectOptions) => this.renderPageRectRaw(options),
+      renderPageBitmap: (options: RenderPageOptions) => this.renderPageBitmap(options),
+      renderPageRectBitmap: (options: RenderPageRectOptions) => this.renderPageRectBitmap(options),
+      renderMode: this.config.renderMode ?? 'blob',
 
       // Document-scoped operations
       forDocument: (documentId: string) => this.createRenderScope(documentId),
@@ -49,14 +53,21 @@ export class RenderPlugin extends BasePlugin<RenderPluginConfig, RenderCapabilit
       renderPageRaw: (options: RenderPageOptions) => this.renderPageRaw(options, documentId),
       renderPageRectRaw: (options: RenderPageRectOptions) =>
         this.renderPageRectRaw(options, documentId),
+      renderPageBitmap: (options: RenderPageOptions) => this.renderPageBitmap(options, documentId),
+      renderPageRectBitmap: (options: RenderPageRectOptions) =>
+        this.renderPageRectBitmap(options, documentId),
+      renderMode: this.config.renderMode ?? 'blob',
     };
   }
 
   // ─────────────────────────────────────────────────────────
-  // Core Operations
+  // Helpers
   // ─────────────────────────────────────────────────────────
 
-  private renderPage({ pageIndex, options }: RenderPageOptions, documentId?: string) {
+  private resolveDocAndPage(
+    pageIndex: number,
+    documentId?: string,
+  ): { doc: PdfDocumentObject; page: PdfPageObject } {
     const id = documentId ?? this.getActiveDocumentId();
     const coreDoc = this.coreState.core.documents[id];
 
@@ -69,90 +80,92 @@ export class RenderPlugin extends BasePlugin<RenderPluginConfig, RenderCapabilit
       throw new Error(`Page ${pageIndex} not found in document ${id}`);
     }
 
-    const mergedOptions = {
+    return { doc: coreDoc.document, page };
+  }
+
+  private mergeImageOptions(options?: PdfRenderPageOptions): PdfRenderPageOptions {
+    return {
       ...(options ?? {}),
       withForms: options?.withForms ?? this.config.withForms ?? false,
       withAnnotations: options?.withAnnotations ?? this.config.withAnnotations ?? false,
       imageType: options?.imageType ?? this.config.defaultImageType ?? 'image/png',
       imageQuality: options?.imageQuality ?? this.config.defaultImageQuality ?? 0.92,
     };
-
-    return this.engine.renderPage(coreDoc.document, page, mergedOptions);
   }
 
-  private renderPageRect({ pageIndex, rect, options }: RenderPageRectOptions, documentId?: string) {
-    const id = documentId ?? this.getActiveDocumentId();
-    const coreDoc = this.coreState.core.documents[id];
-
-    if (!coreDoc?.document) {
-      throw new Error(`Document ${id} not loaded`);
-    }
-
-    const page = coreDoc.document.pages.find((p) => p.index === pageIndex);
-    if (!page) {
-      throw new Error(`Page ${pageIndex} not found in document ${id}`);
-    }
-
-    const mergedOptions = {
+  private mergeRawOptions(options?: PdfRenderPageOptions): PdfRenderPageOptions {
+    return {
       ...(options ?? {}),
       withForms: options?.withForms ?? this.config.withForms ?? false,
       withAnnotations: options?.withAnnotations ?? this.config.withAnnotations ?? false,
-      imageType: options?.imageType ?? this.config.defaultImageType ?? 'image/png',
-      imageQuality: options?.imageQuality ?? this.config.defaultImageQuality ?? 0.92,
     };
-
-    return this.engine.renderPageRect(coreDoc.document, page, rect, mergedOptions);
   }
 
   // ─────────────────────────────────────────────────────────
-  // Raw Rendering (returns ImageDataLike, skips encoding)
+  // Core Operations
   // ─────────────────────────────────────────────────────────
 
-  private renderPageRaw({ pageIndex, options }: RenderPageOptions, documentId?: string) {
-    const id = documentId ?? this.getActiveDocumentId();
-    const coreDoc = this.coreState.core.documents[id];
-
-    if (!coreDoc?.document) {
-      throw new Error(`Document ${id} not loaded`);
-    }
+  private renderPage({ pageIndex, options }: RenderPageOptions, documentId?: string) {
+    const { doc, page } = this.resolveDocAndPage(pageIndex, documentId);
+    return this.engine.renderPage(doc, page, this.mergeImageOptions(options));
+  }
 
-    const page = coreDoc.document.pages.find((p) => p.index === pageIndex);
-    if (!page) {
-      throw new Error(`Page ${pageIndex} not found in document ${id}`);
-    }
+  private renderPageRect({ pageIndex, rect, options }: RenderPageRectOptions, documentId?: string) {
+    const { doc, page } = this.resolveDocAndPage(pageIndex, documentId);
+    return this.engine.renderPageRect(doc, page, rect, this.mergeImageOptions(options));
+  }
 
-    const mergedOptions = {
-      ...(options ?? {}),
-      withForms: options?.withForms ?? this.config.withForms ?? false,
-      withAnnotations: options?.withAnnotations ?? this.config.withAnnotations ?? false,
-    };
+  // ─────────────────────────────────────────────────────────
+  // Raw Rendering (returns ImageDataLike, skips encoding)
+  // ─────────────────────────────────────────────────────────
 
-    return this.engine.renderPageRaw(coreDoc.document, page, mergedOptions);
+  private renderPageRaw({ pageIndex, options }: RenderPageOptions, documentId?: string) {
+    const { doc, page } = this.resolveDocAndPage(pageIndex, documentId);
+    return this.engine.renderPageRaw(doc, page, this.mergeRawOptions(options));
   }
 
   private renderPageRectRaw(
     { pageIndex, rect, options }: RenderPageRectOptions,
     documentId?: string,
   ) {
-    const id = documentId ?? this.getActiveDocumentId();
-    const coreDoc = this.coreState.core.documents[id];
-
-    if (!coreDoc?.document) {
-      throw new Error(`Document ${id} not loaded`);
-    }
+    const { doc, page } = this.resolveDocAndPage(pageIndex, documentId);
+    return this.engine.renderPageRectRaw(doc, page, rect, this.mergeRawOptions(options));
+  }
 
-    const page = coreDoc.document.pages.find((p) => p.index === pageIndex);
-    if (!page) {
-      throw new Error(`Page ${pageIndex} not found in document ${id}`);
-    }
+  // ─────────────────────────────────────────────────────────
+  // Bitmap Rendering (raw → createImageBitmap on main thread)
+  // ─────────────────────────────────────────────────────────
 
-    const mergedOptions = {
-      ...(options ?? {}),
-      withForms: options?.withForms ?? this.config.withForms ?? false,
-      withAnnotations: options?.withAnnotations ?? this.config.withAnnotations ?? false,
-    };
+  private renderPageBitmap({ pageIndex, options }: RenderPageOptions, documentId?: string) {
+    const { doc, page } = this.resolveDocAndPage(pageIndex, documentId);
+    return this.engine
+      .renderPageRaw(doc, page, {
+        ...this.mergeRawOptions(options),
+        priority: 3,
+      })
+      .map(async (raw) => {
+        const sizeLabel = `${raw.width}x${raw.height}`;
+        this.logger.perf('RenderPlugin', 'createImageBitmap', 'call', 'Begin', sizeLabel);
+        const bmp = await createImageBitmap(new ImageData(raw.data, raw.width, raw.height));
+        this.logger.perf('RenderPlugin', 'createImageBitmap', 'call', 'End', sizeLabel);
+        return bmp;
+      });
+  }
 
-    return this.engine.renderPageRectRaw(coreDoc.document, page, rect, mergedOptions);
+  private renderPageRectBitmap(
+    { pageIndex, rect, options }: RenderPageRectOptions,
+    documentId?: string,
+  ) {
+    const { doc, page } = this.resolveDocAndPage(pageIndex, documentId);
+    return this.engine
+      .renderPageRectRaw(doc, page, rect, this.mergeRawOptions(options))
+      .map(async (raw) => {
+        const sizeLabel = `${raw.width}x${raw.height}`;
+        this.logger.perf('RenderPlugin', 'createImageBitmap', 'call', 'Begin', sizeLabel);
+        const bmp = await createImageBitmap(new ImageData(raw.data, raw.width, raw.height));
+        this.logger.perf('RenderPlugin', 'createImageBitmap', 'call', 'End', sizeLabel);
+        return bmp;
+      });
   }
 
   // ─────────────────────────────────────────────────────────