@embedpdf/engines 1.0.7 → 1.0.8

package/dist/pdfium-direct-engine.d.ts

@@ -1,4 +1,4 @@
-import { PdfEngine, Logger, Task, PdfErrorReason, PdfFileUrl, PdfUrlOptions, PdfDocumentObject, PdfFile, PdfFileLoader, PdfSignatureObject, PdfBookmarkObject, PdfPageObject, Rotation, PdfRenderOptions, ImageConversionTypes, PdfTask, Rect, PdfAnnotationObject, PdfAnnotationTransformation, PdfTextRectObject, PdfAttachmentObject, PdfWidgetAnnoObject, FormFieldValue, PdfPageFlattenFlag, PdfPageFlattenResult, PageTextSlice, PdfInkListObject, PdfHighlightAnnoObject, PdfUnderlineAnnoObject, PdfStrikeOutAnnoObject, PdfSquigglyAnnoObject, PdfStampAnnoObjectContents, Position, PdfPageGeometry, PdfGlyphObject, PdfAnnotationObjectBase, WebAlphaColor, MatchFlag, SearchAllPagesResult, PdfImage } from '@embedpdf/models';
+import { PdfEngine, Logger, Task, PdfErrorReason, PdfFileUrl, PdfUrlOptions, PdfDocumentObject, PdfFile, PdfFileLoader, PdfSignatureObject, PdfBookmarkObject, PdfPageObject, Rotation, PdfRenderOptions, ImageConversionTypes, PdfTask, Rect, PdfAnnotationObject, PdfTextRectObject, PdfAttachmentObject, PdfWidgetAnnoObject, FormFieldValue, PdfPageFlattenFlag, PdfPageFlattenResult, PageTextSlice, PdfInkAnnoObject, PdfHighlightAnnoObject, PdfUnderlineAnnoObject, PdfStrikeOutAnnoObject, PdfSquigglyAnnoObject, PdfStampAnnoObjectContents, Position, PdfPageGeometry, PdfGlyphObject, AppearanceMode, PdfAnnotationObjectBase, WebAlphaColor, MatchFlag, SearchAllPagesResult, PdfImage } from '@embedpdf/models';
 import { WrappedPdfiumModule } from '@embedpdf/pdfium';
 
 /**
@@ -163,12 +163,6 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      * @returns PdfTask<boolean>  –  true on success
      */
     updatePageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject): PdfTask<boolean>;
-    /**
-     * {@inheritDoc @embedpdf/models!PdfEngine.transformPageAnnotation}
-     *
-     * @public
-     */
-    transformPageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject, transformation: PdfAnnotationTransformation): Task<boolean, PdfErrorReason> | Task<any, PdfErrorReason>;
     /**
      * {@inheritDoc @embedpdf/models!PdfEngine.removePageAnnotation}
      *
@@ -283,7 +277,7 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      *
      * @private
      */
-    addInkStroke(page: PdfPageObject, pagePtr: number, annotationPtr: number, inkList: PdfInkListObject[]): boolean;
+    addInkStroke(page: PdfPageObject, pagePtr: number, annotationPtr: number, annotation: PdfInkAnnoObject): boolean;
     /**
      * Add highlight content to annotation
      * @param page - page info
@@ -293,7 +287,7 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      *
      * @private
      */
-    addTextMarkupContent(page: PdfPageObject, annotationPtr: number, annotation: PdfHighlightAnnoObject | PdfUnderlineAnnoObject | PdfStrikeOutAnnoObject | PdfSquigglyAnnoObject, shouldClearAP?: boolean): boolean;
+    addTextMarkupContent(page: PdfPageObject, pagePtr: number, annotationPtr: number, annotation: PdfHighlightAnnoObject | PdfUnderlineAnnoObject | PdfStrikeOutAnnoObject | PdfSquigglyAnnoObject): boolean;
     /**
      * Add contents to stamp annotation
      * @param docPtr - pointer to pdf document object
@@ -449,47 +443,6 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      * @private
      */
     private readAnnotationColor;
-    /**
-     * Extract the fill (or, if absent, the stroke) colour from a **path object**
-     * inside an appearance stream.
-     *
-     * Works for simple highlights produced by Chrome, Preview, etc. that paint a
-     * single filled rectangle with the desired tint.
-     *
-     * @param pathPtr - pointer to a `FPDF_PAGEOBJECT` of type **PATH**
-     * @returns RGBA tuple or `undefined` when no colour is set on the path
-     *
-     * @private
-     */
-    private getColorFromPath;
-    /**
-     * Recursively walk a page-object tree (PATHs and nested FORM XObjects) until
-     * a colour can be extracted.
-     *
-     * Acrobat often wraps its highlight rectangle in a Form XObject referenced by
-     * the "Do" operator, so this function drills down unlimited depth.
-     *
-     * @param objPtr - pointer to a `FPDF_PAGEOBJECT`
-     * @returns First RGBA tint found, or `undefined` if none of the descendants
-     *          carry an explicit fill/stroke colour
-     *
-     * @private
-     */
-    private walkPageObjTree;
-    /**
-     * Iterate over every top-level object in the annotation's **appearance stream**
-     * and invoke {@link walkPageObjTree} to locate a usable tint.
-     *
-     * Catches:
-     *   • Simple filled path (Preview, Chrome)
-     *   • Form XObject containing the path (Acrobat)
-     *
-     * @param annotPtr - pointer to an `FPDF_ANNOTATION`
-     * @returns RGBA tuple or `undefined` when no colour can be resolved from AP
-     *
-     * @private
-     */
-    private colorFromAppearance;
     /**
      * Resolve the visible fill colour for **Highlight / Underline / StrikeOut /
      * Squiggly** markup annotations.
@@ -518,6 +471,57 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      * @private
      */
     private setAnnotationColor;
+    /**
+     * Border‐style + width helper
+     *
+     * Tries the new PDFium helper `EPDFAnnot_GetBorderStyle()` (patch series
+     * 9 July 2025).
+     *
+     * @param  annotationPtr  pointer to an `FPDF_ANNOTATION`
+     * @returns `{ ok, style, width }`
+     *          • `ok`     – `true` when the call succeeded
+     *          • `style`  – `PdfAnnotationBorderStyle` enum
+     *          • `width`  – stroke-width in points (defaults to 0 pt)
+     */
+    private getBorderStyle;
+    private setBorderStyle;
+    /**
+     * Border-effect (“cloudy”) helper
+     *
+     * Calls the new PDFium function `EPDFAnnot_GetBorderEffect()` (July 2025).
+     *
+     * @param  annotationPtr  pointer to an `FPDF_ANNOTATION`
+     * @returns `{ ok, intensity }`
+     *          • `ok`        – `true` when the annotation *does* have a
+     *                          valid cloudy-border effect
+     *          • `intensity` – radius/intensity value (0 when `ok` is false)
+     */
+    private getBorderEffect;
+    /**
+     * Rectangle-differences helper ( /RD array on Square / Circle annots )
+     *
+     * Calls `EPDFAnnot_GetRectangleDifferences()` introduced in July 2025.
+     *
+     * @param  annotationPtr  pointer to an `FPDF_ANNOTATION`
+     * @returns `{ ok, left, top, right, bottom }`
+     *          • `ok`     – `true` when the annotation *has* an /RD entry
+     *          • the four floats are 0 when `ok` is false
+     */
+    private getRectangleDifferences;
+    /**
+     * Dash-pattern helper ( /BS → /D array, dashed borders only )
+     *
+     * Uses the two new PDFium helpers:
+     *   • `EPDFAnnot_GetBorderDashPatternCount`
+     *   • `EPDFAnnot_GetBorderDashPattern`
+     *
+     * @param  annotationPtr  pointer to an `FPDF_ANNOTATION`
+     * @returns `{ ok, pattern }`
+     *          • `ok`       – `true` when the annot is dashed *and* the array
+     *                          was retrieved successfully
+     *          • `pattern`  – numeric array of dash/space lengths (empty when `ok` is false)
+     */
+    private getBorderDashPattern;
     /**
      * Read `/QuadPoints` from any annotation and convert each quadrilateral to
      * device-space coordinates.
@@ -545,6 +549,21 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      * @private
      */
     private syncQuadPointsAnno;
+    /**
+     * Read ink list from annotation
+     * @param page  - logical page info object (`PdfPageObject`)
+     * @param annotationPtr - pointer to the annotation whose ink list is needed
+     * @returns ink list
+     */
+    private getInkList;
+    /**
+     * Add ink list to annotation
+     * @param page  - logical page info object (`PdfPageObject`)
+     * @param annotationPtr - pointer to the annotation whose ink list is needed
+     * @param annotation - annotation object (`PdfInkAnnoObject`)
+     * @returns `true` if the operation was successful
+     */
+    private setInkList;
     /**
      * Read pdf text annotation
      * @param page  - pdf page infor
@@ -763,6 +782,25 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      * @private
      */
     private readPdfPageObjectTransformMatrix;
+    /**
+     * Return the stroke-width declared in the annotation’s /Border or /BS entry.
+     * Falls back to 1 pt when nothing is defined.
+     *
+     * @param annotationPtr - pointer to pdf annotation
+     * @returns stroke-width
+     *
+     * @private
+     */
+    private getStrokeWidth;
+    /**
+     * Fetches the `/F` flag bit-field from an annotation.
+     *
+     * @param annotationPtr pointer to an `FPDF_ANNOTATION`
+     * @returns `{ raw, flags }`
+     *          • `raw`   – the 32-bit integer returned by PDFium
+     *          • `flags` – object with individual booleans
+     */
+    private getAnnotationFlags;
     /**
      * Read circle annotation
      * @param page  - pdf page infor
@@ -852,6 +890,13 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      * @private
      */
     private readPdfWidgetAnnoField;
+    /**
+     * {@inheritDoc @embedpdf/models!PdfEngine.renderAnnotation}
+     *
+     * @public
+     */
+    renderAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject, scaleFactor: number, rotation: Rotation, dpr?: number, // device-pixel-ratio (canvas)
+    mode?: AppearanceMode, imageType?: ImageConversionTypes): PdfTask<T>;
     /**
      * render rectangle of pdf page to image
      * @param docPtr - pointer to pdf document object