@embedpdf/models 2.6.2 → 2.8.0

package/dist/pdf.d.ts

@@ -382,6 +382,36 @@ export type ImageDataLike = {
     height: number;
     colorSpace?: PredefinedColorSpace;
 };
+/**
+ * Bitmask constants for annotation appearance stream modes.
+ * @public
+ */
+export declare const AP_MODE_NORMAL = 1;
+export declare const AP_MODE_ROLLOVER = 2;
+export declare const AP_MODE_DOWN = 4;
+/**
+ * A rendered appearance stream image for a single mode of an annotation.
+ * @public
+ */
+export interface AnnotationAppearanceImage<TImage = ImageDataLike> {
+    data: TImage;
+    rect: Rect;
+}
+/**
+ * All available appearance stream images for one annotation,
+ * keyed by mode (normal, rollover, down).
+ * @public
+ */
+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<TImage = ImageDataLike> = Record<string, AnnotationAppearances<TImage>>;
 /**
  * Representation of pdf action
  *
@@ -863,6 +893,18 @@ export declare enum PdfAnnotationReplyType {
      */
     Group = 2
 }
+/**
+ * Rectangle differences (/RD) defining the inset between an annotation's
+ * /Rect and the actual drawn appearance.
+ *
+ * @public
+ */
+export interface PdfRectDifferences {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
 /**
  * Basic information of pdf annotation
  *
@@ -928,6 +970,12 @@ export interface PdfAnnotationObjectBase {
      * Custom data of the annotation
      */
     custom?: any;
+    /**
+     * Bitmask of available appearance stream modes.
+     * bit 0 (1) = Normal, bit 1 (2) = Rollover, bit 2 (4) = Down.
+     * 0 or undefined = no appearance stream.
+     */
+    appearanceModes?: number;
     /**
      * In reply to annotation id (IRT - for grouping or reply threads)
      */
@@ -996,7 +1044,11 @@ export interface PdfTextAnnoObject extends PdfAnnotationObjectBase {
      */
     contents: string;
     /**
-     * color of text annotation
+     * Color of the text annotation (preferred over deprecated `color`)
+     */
+    strokeColor?: string;
+    /**
+     * @deprecated Use strokeColor instead. Will be removed in next major version.
      */
     color?: string;
     /**
@@ -1326,6 +1378,10 @@ export interface PdfPolygonAnnoObject extends PdfAnnotationObjectBase {
      * stroke dash array of polygon annotation
      */
     strokeDashArray?: number[];
+    /**
+     * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
+     */
+    rectangleDifferences?: PdfRectDifferences;
 }
 /**
  * PDF polyline annotation
@@ -1616,9 +1672,9 @@ export interface PdfCircleAnnoObject extends PdfAnnotationObjectBase {
      */
     cloudyBorderIntensity?: number;
     /**
-     * cloudy border inset of circle annotation
+     * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
      */
-    cloudyBorderInset?: number[];
+    rectangleDifferences?: PdfRectDifferences;
 }
 /**
  * Pdf square annotation
@@ -1665,9 +1721,9 @@ export interface PdfSquareAnnoObject extends PdfAnnotationObjectBase {
      */
     cloudyBorderIntensity?: number;
     /**
-     * cloudy border inset of circle annotation
+     * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
      */
-    cloudyBorderInset?: number[];
+    rectangleDifferences?: PdfRectDifferences;
 }
 /**
  * Pdf squiggly annotation
@@ -1764,6 +1820,14 @@ export interface PdfStrikeOutAnnoObject extends PdfAnnotationObjectBase {
 export interface PdfCaretAnnoObject extends PdfAnnotationObjectBase {
     /** {@inheritDoc PdfAnnotationObjectBase.type} */
     type: PdfAnnotationSubtype.CARET;
+    /** Stroke color of the caret symbol */
+    strokeColor?: string;
+    /** Opacity (0-1) */
+    opacity?: number;
+    /**
+     * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
+     */
+    rectangleDifferences?: PdfRectDifferences;
 }
 /**
  * Pdf free text annotation
@@ -1817,6 +1881,10 @@ export interface PdfFreeTextAnnoObject extends PdfAnnotationObjectBase {
      * Rich content of the free text annotation
      */
     richContent?: string;
+    /**
+     * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
+     */
+    rectangleDifferences?: PdfRectDifferences;
 }
 /**
  * Pdf redact annotation
@@ -2770,6 +2838,24 @@ export interface PdfEngine<T = Blob> {
      * @param options - render options
      */
     renderPageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, 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).
+     * Skips EmbedPDF-rotated annotations and annotations without appearance streams.
+     * @param doc - pdf document
+     * @param page - pdf page
+     * @param options - render options (scaleFactor, dpr, rotation)
+     */
+    renderPageAnnotationsRaw(doc: PdfDocumentObject, page: PdfPageObject, options?: PdfRenderPageAnnotationOptions): PdfTask<AnnotationAppearanceMap<ImageDataLike>>;
     /**
      * Get annotations of pdf page
      * @param doc - pdf document
@@ -2793,7 +2879,9 @@ export interface PdfEngine<T = Blob> {
      * @param annotation - new annotations
      * @returns task that indicates whether the operation succeeded
      */
-    updatePageAnnotation: (doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject) => PdfTask<boolean>;
+    updatePageAnnotation: (doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject, options?: {
+        regenerateAppearance?: boolean;
+    }) => PdfTask<boolean>;
     /**
      * Remove a annotation on specified page
      * @param doc - pdf document
@@ -3063,10 +3151,13 @@ export interface IPdfiumExecutor {
     renderPageRect(doc: PdfDocumentObject, page: PdfPageObject, rect: Rect, options?: PdfRenderPageOptions): PdfTask<ImageDataLike>;
     renderThumbnailRaw(doc: PdfDocumentObject, page: PdfPageObject, options?: PdfRenderThumbnailOptions): PdfTask<ImageDataLike>;
     renderPageAnnotationRaw(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject, options?: PdfRenderPageAnnotationOptions): PdfTask<ImageDataLike>;
+    renderPageAnnotationsRaw(doc: PdfDocumentObject, page: PdfPageObject, options?: PdfRenderPageAnnotationOptions): PdfTask<AnnotationAppearanceMap<ImageDataLike>>;
     getPageAnnotationsRaw(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfAnnotationObject[]>;
     getPageAnnotations(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfAnnotationObject[]>;
     createPageAnnotation<A extends PdfAnnotationObject>(doc: PdfDocumentObject, page: PdfPageObject, annotation: A, context?: AnnotationCreateContext<A>): PdfTask<string>;
-    updatePageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject): PdfTask<boolean>;
+    updatePageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject, options?: {
+        regenerateAppearance?: boolean;
+    }): PdfTask<boolean>;
     removePageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject): PdfTask<boolean>;
     getPageTextRects(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfTextRectObject[]>;
     searchInPage(doc: PdfDocumentObject, page: PdfPageObject, keyword: string, flags: number): PdfTask<SearchResult[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/models",
-  "version": "2.6.2",
+  "version": "2.8.0",
   "private": false,
   "description": "Shared type definitions, data models, and utility helpers (geometry, tasks, logging, PDF primitives) that underpin every package in the EmbedPDF ecosystem.",
   "type": "module",