Merge pull request #467 from embedpdf/feature/appearance-based-rendering

Appearance based rendering

Author: bobsingor

.changeset/brave-lions-roar.md

@@ -0,0 +1,5 @@
+---
+'@embedpdf/engines': minor
+---
+
+Implemented `renderPageAnnotationsRaw` to batch render annotation appearance streams and updated `updatePageAnnotation` to support skipping appearance regeneration.

.changeset/calm-rivers-flow.md

@@ -0,0 +1,5 @@
+---
+'@embedpdf/models': minor
+---
+
+Added types and interfaces for annotation appearance streams (`AnnotationAppearanceMap`, `AnnotationAppearances`, `AnnotationAppearanceImage`) and updated `PdfEngine` interface with `renderPageAnnotationsRaw`.

.changeset/fix-vue-reactivity-anchors.md

@@ -0,0 +1,5 @@
+---
+'@embedpdf/plugin-ui': patch
+---
+
+Fix Vue reactivity bugs when switching documents in the schema-driven viewer. `useRegisterAnchor` now accepts `MaybeRefOrGetter<string>` and re-registers anchors when `documentId` changes. `AutoMenuRenderer` now passes a reactive getter to `useUIState` so menu state tracks the active document.

.changeset/happy-birds-sing.md

@@ -0,0 +1,8 @@
+---
+'@embedpdf/plugin-annotation': minor
+---
+
+- Added support for rendering annotation appearance streams (AP) for better visual fidelity with other PDF viewers.
+- Refactored annotation rendering to use a registry-based system, allowing for easier extensibility.
+- Introduced `moveAnnotation` API to update annotation positions without regenerating their appearance streams.
+- Added caching for rendered appearance streams.

.changeset/silent-winds-blow.md

@@ -0,0 +1,5 @@
+---
+'@embedpdf/plugin-redaction': patch
+---
+
+Updated redaction tools and renderers to explicitly disable appearance stream usage, ensuring dynamic rendering for redaction marks.

.changeset/wise-owls-hoot.md

@@ -0,0 +1,5 @@
+---
+'@embedpdf/snippet': patch
+---
+
+Fixed color matching case insensitivity and rotation debounce logic in the annotation sidebar.

examples/vue-tailwind/src/components/CommandButton.vue

@@ -71,12 +71,15 @@ const props = withDefaults(defineProps<Props>(), {
   className: undefined,
 });
 
-const command = useCommand(props.commandId, props.documentId);
+const command = useCommand(
+  () => props.commandId,
+  () => props.documentId,
+);
 
 // Register this button with the anchor registry if itemId is provided
 // This allows menus to anchor to it when opened via UI state changes
 const finalItemId = computed(() => props.itemId || props.commandId);
-const anchorRef = useRegisterAnchor(props.documentId, finalItemId.value);
+const anchorRef = useRegisterAnchor(() => props.documentId, finalItemId);
 
 // Get the icon component from the command's icon property
 const iconName = computed(() => (command.value?.icon ? `${command.value.icon}Icon` : null));

examples/vue-tailwind/src/components/CommandTabButton.vue

@@ -50,11 +50,14 @@ const props = withDefaults(defineProps<Props>(), {
   variant: 'text',
 });
 
-const command = useCommand(props.commandId, props.documentId);
+const command = useCommand(
+  () => props.commandId,
+  () => props.documentId,
+);
 
 // Register this button with the anchor registry if itemId is provided
 const finalItemId = computed(() => props.itemId || props.commandId);
-const anchorRef = useRegisterAnchor(props.documentId, finalItemId.value);
+const anchorRef = useRegisterAnchor(() => props.documentId, finalItemId);
 
 // Get the icon component from the command's icon property
 const iconName = computed(() => (command.value?.icon ? `${command.value.icon}Icon` : null));

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

@@ -46,6 +46,7 @@ import {
   CompoundTask,
   ImageDataLike,
   IPdfiumExecutor,
+  AnnotationAppearanceMap,
 } from '@embedpdf/models';
 import { WorkerTaskQueue, Priority } from './task-queue';
 import type { ImageDataConverter } from '../converters/types';
@@ -369,6 +370,59 @@ 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<ImageDataLike>> {
+    return this.workerQueue.enqueue(
+      {
+        execute: () => this.executor.renderPageAnnotationsRaw(doc, page, options),
+        meta: { docId: doc.id, pageIndex: page.index, operation: 'renderPageAnnotationsRaw' },
+      },
+      { priority: Priority.MEDIUM },
+    );
+  }
+
   /**
    * Helper to render and encode in two stages with priority queue
    */
@@ -440,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[]> {
@@ -471,10 +581,11 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
     doc: PdfDocumentObject,
     page: PdfPageObject,
     annotation: PdfAnnotationObject,
+    options?: { regenerateAppearance?: boolean },
   ): PdfTask<boolean> {
     return this.workerQueue.enqueue(
       {
-        execute: () => this.executor.updatePageAnnotation(doc, page, annotation),
+        execute: () => this.executor.updatePageAnnotation(doc, page, annotation, options),
         meta: { docId: doc.id, pageIndex: page.index, operation: 'updatePageAnnotation' },
       },
       { priority: Priority.MEDIUM },

packages/engines/src/lib/orchestrator/remote-executor.ts

@@ -38,6 +38,7 @@ import {
   serializeLogger,
   IPdfiumExecutor,
   ImageDataLike,
+  AnnotationAppearanceMap,
 } from '@embedpdf/models';
 import type { WorkerRequest, WorkerResponse } from './pdfium-native-runner';
 import type { FontFallbackConfig } from '../pdfium/font-fallback';
@@ -81,6 +82,7 @@ type MessageType =
   | 'renderPageRect'
   | 'renderThumbnailRaw'
   | 'renderPageAnnotationRaw'
+  | 'renderPageAnnotationsRaw'
   | 'getPageAnnotations'
   | 'getPageAnnotationsRaw'
   | 'createPageAnnotation'
@@ -351,6 +353,14 @@ export class RemoteExecutor implements IPdfiumExecutor {
     return this.send<ImageDataLike>('renderPageAnnotationRaw', [doc, page, annotation, options]);
   }
 
+  renderPageAnnotationsRaw(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    options?: PdfRenderPageAnnotationOptions,
+  ): PdfTask<AnnotationAppearanceMap> {
+    return this.send<AnnotationAppearanceMap>('renderPageAnnotationsRaw', [doc, page, options]);
+  }
+
   getPageAnnotationsRaw(
     doc: PdfDocumentObject,
     page: PdfPageObject,
@@ -375,8 +385,9 @@ export class RemoteExecutor implements IPdfiumExecutor {
     doc: PdfDocumentObject,
     page: PdfPageObject,
     annotation: PdfAnnotationObject,
+    options?: { regenerateAppearance?: boolean },
   ): PdfTask<boolean> {
-    return this.send<boolean>('updatePageAnnotation', [doc, page, annotation]);
+    return this.send<boolean>('updatePageAnnotation', [doc, page, annotation, options]);
   }
 
   removePageAnnotation(