Change annotation renderer to blob instead of canvas

Author: bobsingor

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

@@ -370,11 +370,50 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
     );
   }
 
+  renderPageAnnotations(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    options?: PdfRenderPageAnnotationOptions,
+  ): PdfTask<AnnotationAppearanceMap<T>> {
+    const resultTask = new Task<AnnotationAppearanceMap<T>, PdfErrorReason>();
+
+    const renderHandle = this.workerQueue.enqueue(
+      {
+        execute: () => this.executor.renderPageAnnotationsRaw(doc, page, options),
+        meta: { docId: doc.id, pageIndex: page.index, operation: 'renderPageAnnotationsRaw' },
+      },
+      { priority: Priority.MEDIUM },
+    );
+
+    // Wire up abort: when resultTask is aborted, also abort the queue task
+    const originalAbort = resultTask.abort.bind(resultTask);
+    resultTask.abort = (reason) => {
+      renderHandle.abort(reason);
+      originalAbort(reason);
+    };
+
+    renderHandle.wait(
+      (rawMap) => {
+        if (resultTask.state.stage !== 0 /* Pending */) {
+          return;
+        }
+        this.encodeAppearanceMap(rawMap, options, resultTask);
+      },
+      (error) => {
+        if (resultTask.state.stage === 0 /* Pending */) {
+          resultTask.fail(error);
+        }
+      },
+    );
+
+    return resultTask;
+  }
+
   renderPageAnnotationsRaw(
     doc: PdfDocumentObject,
     page: PdfPageObject,
     options?: PdfRenderPageAnnotationOptions,
-  ): PdfTask<AnnotationAppearanceMap> {
+  ): PdfTask<AnnotationAppearanceMap<ImageDataLike>> {
     return this.workerQueue.enqueue(
       {
         execute: () => this.executor.renderPageAnnotationsRaw(doc, page, options),
@@ -455,6 +494,62 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
       .catch((error) => resultTask.reject({ code: PdfErrorCode.Unknown, message: String(error) }));
   }
 
+  /**
+   * Encode a full annotation appearance map to the output type T.
+   */
+  private encodeAppearanceMap(
+    rawMap: AnnotationAppearanceMap<ImageDataLike>,
+    options: PdfRenderPageAnnotationOptions | undefined,
+    resultTask: Task<AnnotationAppearanceMap<T>, PdfErrorReason>,
+  ): void {
+    const imageType = options?.imageType ?? 'image/webp';
+    const quality = options?.imageQuality;
+
+    const convertImage = (rawImageData: ImageDataLike): Promise<T> => {
+      const plainImageData = {
+        data: new Uint8ClampedArray(rawImageData.data),
+        width: rawImageData.width,
+        height: rawImageData.height,
+      };
+      return this.options.imageConverter(() => plainImageData, imageType, quality);
+    };
+
+    const jobs: Promise<void>[] = [];
+    const encodedMap: AnnotationAppearanceMap<T> = {};
+    const modes: Array<'normal' | 'rollover' | 'down'> = ['normal', 'rollover', 'down'];
+
+    for (const [annotationId, appearances] of Object.entries(rawMap)) {
+      const encodedAppearances: NonNullable<AnnotationAppearanceMap<T>[string]> = {};
+      encodedMap[annotationId] = encodedAppearances;
+
+      for (const mode of modes) {
+        const appearance = appearances[mode];
+        if (!appearance) continue;
+
+        jobs.push(
+          convertImage(appearance.data).then((encodedData) => {
+            encodedAppearances[mode] = {
+              data: encodedData,
+              rect: appearance.rect,
+            };
+          }),
+        );
+      }
+    }
+
+    Promise.all(jobs)
+      .then(() => {
+        if (resultTask.state.stage === 0 /* Pending */) {
+          resultTask.resolve(encodedMap);
+        }
+      })
+      .catch((error) => {
+        if (resultTask.state.stage === 0 /* Pending */) {
+          resultTask.reject({ code: PdfErrorCode.Unknown, message: String(error) });
+        }
+      });
+  }
+
   // ========== Annotations ==========
 
   getPageAnnotations(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfAnnotationObject[]> {

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

@@ -496,14 +496,33 @@ export class WebWorkerEngine implements PdfEngine {
     return task;
   }
 
+  renderPageAnnotations(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    options?: PdfRenderPageAnnotationOptions,
+  ) {
+    this.logger.debug(LOG_SOURCE, LOG_CATEGORY, 'renderPageAnnotations', doc, page, options);
+    const requestId = this.generateRequestId(doc.id);
+    const task = new WorkerTask<AnnotationAppearanceMap<Blob>>(this.worker, requestId);
+
+    const request: ExecuteRequest = createRequest(requestId, 'renderPageAnnotations', [
+      doc,
+      page,
+      options,
+    ]);
+    this.proxy(task, request);
+
+    return task;
+  }
+
   renderPageAnnotationsRaw(
     doc: PdfDocumentObject,
     page: PdfPageObject,
     options?: PdfRenderPageAnnotationOptions,
   ) {
     this.logger.debug(LOG_SOURCE, LOG_CATEGORY, 'renderPageAnnotationsRaw', doc, page, options);
     const requestId = this.generateRequestId(doc.id);
-    const task = new WorkerTask<AnnotationAppearanceMap>(this.worker, requestId);
+    const task = new WorkerTask<AnnotationAppearanceMap<ImageDataLike>>(this.worker, requestId);
 
     const request: ExecuteRequest = createRequest(requestId, 'renderPageAnnotationsRaw', [
       doc,

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

@@ -297,6 +297,9 @@ export class EngineRunner {
       case 'renderPageAnnotation':
         task = engine.renderPageAnnotation!(...args);
         break;
+      case 'renderPageAnnotations':
+        task = engine.renderPageAnnotations!(...args);
+        break;
       case 'renderPageAnnotationsRaw':
         task = engine.renderPageAnnotationsRaw!(...args);
         break;

packages/models/src/pdf.ts

@@ -439,8 +439,8 @@ export const AP_MODE_DOWN = 4; // bit 2
  * A rendered appearance stream image for a single mode of an annotation.
  * @public
  */
-export interface AnnotationAppearanceImage {
-  data: ImageDataLike;
+export interface AnnotationAppearanceImage<TImage = ImageDataLike> {
+  data: TImage;
   rect: Rect;
 }
 
@@ -449,17 +449,20 @@ export interface AnnotationAppearanceImage {
  * keyed by mode (normal, rollover, down).
  * @public
  */
-export interface AnnotationAppearances {
-  normal?: AnnotationAppearanceImage;
-  rollover?: AnnotationAppearanceImage;
-  down?: AnnotationAppearanceImage;
+export interface AnnotationAppearances<TImage = ImageDataLike> {
+  normal?: AnnotationAppearanceImage<TImage>;
+  rollover?: AnnotationAppearanceImage<TImage>;
+  down?: AnnotationAppearanceImage<TImage>;
 }
 
 /**
  * Map of annotation ID to its rendered appearance stream images.
  * @public
  */
-export type AnnotationAppearanceMap = Record<string, AnnotationAppearances>;
+export type AnnotationAppearanceMap<TImage = ImageDataLike> = Record<
+  string,
+  AnnotationAppearances<TImage>
+>;
 
 /**
  * Representation of pdf action
@@ -3217,6 +3220,19 @@ export interface PdfEngine<T = Blob> {
     annotation: PdfAnnotationObject,
     options?: PdfRenderPageAnnotationOptions,
   ): PdfTask<T>;
+  /**
+   * Batch-render all annotation appearance streams for a page and encode
+   * each rendered image to the output type of this engine.
+   * Returns a map of annotation ID to rendered appearances (Normal/Rollover/Down).
+   * @param doc - pdf document
+   * @param page - pdf page
+   * @param options - render options
+   */
+  renderPageAnnotations(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    options?: PdfRenderPageAnnotationOptions,
+  ): PdfTask<AnnotationAppearanceMap<T>>;
   /**
    * Batch-render all annotation appearance streams for a page.
    * Returns a map of annotation ID to rendered appearances (Normal/Rollover/Down).
@@ -3229,7 +3245,7 @@ export interface PdfEngine<T = Blob> {
     doc: PdfDocumentObject,
     page: PdfPageObject,
     options?: PdfRenderPageAnnotationOptions,
-  ): PdfTask<AnnotationAppearanceMap>;
+  ): PdfTask<AnnotationAppearanceMap<ImageDataLike>>;
   /**
    * Get annotations of pdf page
    * @param doc - pdf document
@@ -3604,7 +3620,7 @@ export interface IPdfiumExecutor {
     doc: PdfDocumentObject,
     page: PdfPageObject,
     options?: PdfRenderPageAnnotationOptions,
-  ): PdfTask<AnnotationAppearanceMap>;
+  ): PdfTask<AnnotationAppearanceMap<ImageDataLike>>;
 
   // Single page operations
   getPageAnnotationsRaw(

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

@@ -148,8 +148,8 @@ export class AnnotationPlugin extends BasePlugin<
   private readonly toolsChange$ = createBehaviorEmitter<AnnotationToolsChangeEvent>();
   private readonly patchRegistry = new PatchRegistry();
 
-  // Appearance stream cache: documentId -> pageIndex -> AnnotationAppearanceMap
-  private readonly appearanceCache = new Map<string, Map<number, AnnotationAppearanceMap>>();
+  // Appearance stream cache: documentId -> pageIndex -> AnnotationAppearanceMap<Blob>
+  private readonly appearanceCache = new Map<string, Map<number, AnnotationAppearanceMap<Blob>>>();
 
   // Unified drag coordination (per-document)
   private readonly unifiedDragStates = new Map<string, UnifiedDragState>();
@@ -721,7 +721,7 @@ export class AnnotationPlugin extends BasePlugin<
     pageIndex: number,
     options?: PdfRenderPageAnnotationOptions,
     documentId?: string,
-  ): Task<AnnotationAppearanceMap, PdfErrorReason> {
+  ): Task<AnnotationAppearanceMap<Blob>, PdfErrorReason> {
     const id = documentId ?? this.getActiveDocumentId();
     const docState = this.getCoreDocument(id);
     const doc = docState?.document;
@@ -744,13 +744,13 @@ export class AnnotationPlugin extends BasePlugin<
 
     const cached = docCache.get(pageIndex);
     if (cached && !options) {
-      const task = new Task<AnnotationAppearanceMap, PdfErrorReason>();
+      const task = new Task<AnnotationAppearanceMap<Blob>, PdfErrorReason>();
       task.resolve(cached);
       return task;
     }
 
-    const engineTask = this.engine.renderPageAnnotationsRaw(doc, page, options);
-    const resultTask = new Task<AnnotationAppearanceMap, PdfErrorReason>();
+    const engineTask = this.engine.renderPageAnnotations(doc, page, options);
+    const resultTask = new Task<AnnotationAppearanceMap<Blob>, PdfErrorReason>();
 
     engineTask.wait(
       (result) => {

packages/plugin-annotation/src/lib/types.ts

@@ -268,7 +268,7 @@ export interface AnnotationScope {
   getPageAppearances(
     pageIndex: number,
     options?: PdfRenderPageAnnotationOptions,
-  ): Task<AnnotationAppearanceMap, PdfErrorReason>;
+  ): Task<AnnotationAppearanceMap<Blob>, PdfErrorReason>;
   /** Clear cached appearance images for a page (e.g. on zoom change) */
   invalidatePageAppearances(pageIndex: number): void;
   commit(): Task<boolean, PdfErrorReason>;
@@ -360,7 +360,7 @@ export interface AnnotationCapability {
     pageIndex: number,
     options?: PdfRenderPageAnnotationOptions,
     documentId?: string,
-  ) => Task<AnnotationAppearanceMap, PdfErrorReason>;
+  ) => Task<AnnotationAppearanceMap<Blob>, PdfErrorReason>;
   /** Clear cached appearance images for a page (e.g. on zoom change) */
   invalidatePageAppearances: (pageIndex: number, documentId?: string) => void;
   commit: () => Task<boolean, PdfErrorReason>;

packages/plugin-annotation/src/shared/components/annotation-container.tsx

@@ -59,7 +59,7 @@ interface AnnotationContainerProps<T extends PdfAnnotationObject> {
   onDoubleClick?: (event: any) => void;
   onSelect: (event: AnnotationInteractionEvent) => void;
   /** Pre-rendered appearance stream images for AP mode rendering */
-  appearance?: AnnotationAppearances | null;
+  appearance?: AnnotationAppearances<Blob> | null;
   zIndex?: number;
   resizeUI?: ResizeHandleUI;
   vertexUI?: VertexHandleUI;

packages/plugin-annotation/src/shared/components/annotations.tsx

@@ -68,7 +68,7 @@ export function Annotations(annotationsProps: AnnotationsProps) {
   const { register } = usePointerHandlers({ documentId, pageIndex });
   const [allSelectedIds, setAllSelectedIds] = useState<string[]>([]);
   const [editingId, setEditingId] = useState<string | null>(null);
-  const [appearanceMap, setAppearanceMap] = useState<AnnotationAppearanceMap>({});
+  const [appearanceMap, setAppearanceMap] = useState<AnnotationAppearanceMap<Blob>>({});
   const prevScaleRef = useRef<number>(scale);
 
   const annotationProvides = useMemo(
@@ -236,7 +236,7 @@ export function Annotations(annotationsProps: AnnotationsProps) {
   }, [annotationProvides, pageIndex, allSelectedIds]);
 
   const getAppearanceForAnnotation = useCallback(
-    (ta: TrackedAnnotation): AnnotationAppearances | null => {
+    (ta: TrackedAnnotation): AnnotationAppearances<Blob> | null => {
       if (ta.dictMode) return null;
       if (ta.object.rotation && ta.object.unrotatedRect) return null;
       const appearances = appearanceMap[ta.object.id];

packages/plugin-annotation/src/shared/components/appearance-image.tsx

@@ -1,45 +1,52 @@
-import { useEffect, useRef, CSSProperties } from '@framework';
-import { AnnotationAppearanceImage } from '@embedpdf/models';
+import type { AnnotationAppearanceImage } from '@embedpdf/models';
+import { useEffect, useRef, useState, CSSProperties } from '@framework';
 
 interface AppearanceImageProps {
-  appearance: AnnotationAppearanceImage;
+  appearance: AnnotationAppearanceImage<Blob>;
   style?: CSSProperties;
 }
 
 /**
- * Renders a pre-rendered annotation appearance stream image using a canvas.
- * The ImageDataLike data is drawn once and the canvas is sized to fill its container.
+ * Renders a pre-rendered annotation appearance stream image as an img URL.
  * Purely visual -- pointer events are always disabled; hit-area SVG handles interaction.
  */
 export function AppearanceImage({ appearance, style }: AppearanceImageProps) {
-  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const [imageUrl, setImageUrl] = useState<string | null>(null);
+  const urlRef = useRef<string | null>(null);
 
   useEffect(() => {
-    const canvas = canvasRef.current;
-    if (!canvas) return;
+    const url = URL.createObjectURL(appearance.data);
+    setImageUrl(url);
+    urlRef.current = url;
 
-    const { data } = appearance;
-    canvas.width = data.width;
-    canvas.height = data.height;
+    return () => {
+      if (urlRef.current) {
+        URL.revokeObjectURL(urlRef.current);
+        urlRef.current = null;
+      }
+    };
+  }, [appearance.data]);
 
-    const ctx = canvas.getContext('2d');
-    if (!ctx) return;
+  const handleImageLoad = () => {
+    if (urlRef.current) {
+      URL.revokeObjectURL(urlRef.current);
+      urlRef.current = null;
+    }
+  };
 
-    const imageData = new ImageData(data.data, data.width, data.height);
-    ctx.putImageData(imageData, 0, 0);
-  }, [appearance]);
-
-  return (
-    <canvas
-      ref={canvasRef}
+  return imageUrl ? (
+    <img
+      src={imageUrl}
+      onLoad={handleImageLoad}
       style={{
         position: 'absolute',
         width: '100%',
         height: '100%',
         display: 'block',
         pointerEvents: 'none',
+        userSelect: 'none',
         ...style,
       }}
     />
-  );
+  ) : null;
 }