@embedpdf/engines 1.0.6 → 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, PdfStampAnnoObjectContents, Position, PdfPageGeometry, PdfGlyphObject, 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';
 
 /**
@@ -152,13 +152,17 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      *
      * @public
      */
-    createPageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject): Task<boolean, PdfErrorReason> | Task<any, PdfErrorReason>;
+    createPageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject): PdfTask<number>;
     /**
-     * {@inheritDoc @embedpdf/models!PdfEngine.transformPageAnnotation}
+     * Update an existing page annotation in-place
      *
-     * @public
+     *  • Locates the annot by page-local index (`annotation.id`)
+     *  • Re-writes its /Rect and type-specific payload
+     *  • Calls FPDFPage_GenerateContent so the new appearance is rendered
+     *
+     * @returns PdfTask<boolean>  –  true on success
      */
-    transformPageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject, transformation: PdfAnnotationTransformation): Task<boolean, PdfErrorReason> | Task<any, PdfErrorReason>;
+    updatePageAnnotation(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObject): PdfTask<boolean>;
     /**
      * {@inheritDoc @embedpdf/models!PdfEngine.removePageAnnotation}
      *
@@ -273,7 +277,17 @@ 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
+     * @param annotationPtr - pointer to highlight annotation
+     * @param annotation - highlight annotation
+     * @returns whether highlight content is added to annotation
+     *
+     * @private
+     */
+    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
@@ -430,62 +444,84 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      */
     private readAnnotationColor;
     /**
-     * Extract the fill (or, if absent, the stroke) colour from a **path object**
-     * inside an appearance stream.
+     * Resolve the visible fill colour for **Highlight / Underline / StrikeOut /
+     * Squiggly** markup annotations.
      *
-     * Works for simple highlights produced by Chrome, Preview, etc. that paint a
-     * single filled rectangle with the desired tint.
+     * Resolution order (first non-`undefined` wins):
+     *  1. `/C` dictionary entry – fast, present in Acrobat / Office PDFs
+     *  2. Appearance-stream objects – drills into paths & nested forms
+     *  3. Hard-coded fallback (Acrobat-style opaque yellow)
      *
-     * @param pathPtr - pointer to a `FPDF_PAGEOBJECT` of type **PATH**
-     * @returns RGBA tuple or `undefined` when no colour is set on the path
+     * @param annotationPtr - pointer to an `FPDF_ANNOTATION`
+     * @param fallback      - colour to use when the PDF stores no tint at all
+     * @returns WebAlphaColor with hex color and opacity (0-1)
      *
      * @private
      */
-    private getColorFromPath;
+    private resolveAnnotationColor;
     /**
-     * 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.
+     * Set the fill/stroke colour for a **Highlight / Underline / StrikeOut / Squiggly** markup annotation.
      *
-     * @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
+     * @param annotationPtr - pointer to the annotation whose colour is being set
+     * @param webAlphaColor - WebAlphaColor with hex color and opacity (0-1)
+     * @param shouldClearAP - whether to clear the /AP entry
+     * @param which - which colour to set (0 = fill, 1 = stroke)
+     * @returns `true` if the operation was successful
      *
      * @private
      */
-    private walkPageObjTree;
+    private setAnnotationColor;
     /**
-     * Iterate over every top-level object in the annotation's **appearance stream**
-     * and invoke {@link walkPageObjTree} to locate a usable tint.
+     * Border‐style + width helper
      *
-     * Catches:
-     *   • Simple filled path (Preview, Chrome)
-     *   • Form XObject containing the path (Acrobat)
+     * Tries the new PDFium helper `EPDFAnnot_GetBorderStyle()` (patch series
+     * 9 July 2025).
      *
-     * @param annotPtr - pointer to an `FPDF_ANNOTATION`
-     * @returns RGBA tuple or `undefined` when no colour can be resolved from AP
+     * @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
      *
-     * @private
+     * 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 colorFromAppearance;
+    private getBorderEffect;
     /**
-     * Resolve the visible fill colour for **Highlight / Underline / StrikeOut /
-     * Squiggly** markup annotations.
+     * Rectangle-differences helper ( /RD array on Square / Circle annots )
      *
-     * Resolution order (first non-`undefined` wins):
-     *  1. `/C` dictionary entry – fast, present in Acrobat / Office PDFs
-     *  2. Appearance-stream objects – drills into paths & nested forms
-     *  3. Hard-coded fallback (Acrobat-style opaque yellow)
+     * Calls `EPDFAnnot_GetRectangleDifferences()` introduced in July 2025.
      *
-     * @param annotationPtr - pointer to an `FPDF_ANNOTATION`
-     * @param fallback      - colour to use when the PDF stores no tint at all
-     * @returns Guaranteed RGBA tuple (never `undefined`)
+     * @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 )
      *
-     * @private
+     * 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 resolveAnnotationColor;
+    private getBorderDashPattern;
     /**
      * Read `/QuadPoints` from any annotation and convert each quadrilateral to
      * device-space coordinates.
@@ -497,11 +533,37 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      *
      * @param page          - logical page info object (`PdfPageObject`)
      * @param annotationPtr - pointer to the annotation whose quads are needed
-     * @returns Array of `Quad` objects (`[]` if the annotation has no quads)
+     * @returns Array of `Rect` objects (`[]` if the annotation has no quads)
      *
      * @private
      */
-    private readAnnotationQuads;
+    private getQuadPointsAnno;
+    /**
+     * Set the quadrilaterals for a **Highlight / Underline / StrikeOut / Squiggly** markup annotation.
+     *
+     * @param page          - logical page info object (`PdfPageObject`)
+     * @param annotationPtr - pointer to the annotation whose quads are needed
+     * @param rects         - array of `Rect` objects (`[]` if the annotation has no quads)
+     * @returns `true` if the operation was successful
+     *
+     * @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
@@ -720,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
@@ -764,14 +845,6 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      * @private
      */
     private getInReplyToId;
-    /**
-     * Parse a PDF date string **D:YYYYMMDDHHmmSSOHH'mm'** to ISO-8601.
-     *
-     * Returns `undefined` if the input is malformed.
-     *
-     * @private
-     */
-    private toIsoDate;
     /**
      * Fetch a string value (`/T`, `/M`, `/State`, …) from an annotation.
      *
@@ -781,16 +854,13 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      */
     private getAnnotString;
     /**
-     * Read linked popup of pdf annotation
-     * @param page  - pdf page infor
-     * @param pagePtr - pointer to pdf page object
-     * @param annotationPtr - pointer to pdf annotation
-     * @param index  - index of annotation in the pdf page
-     * @returns pdf popup linked to annotation
+     * Set a string value (`/T`, `/M`, `/State`, …) to an annotation.
+     *
+     * @returns `true` if the operation was successful
      *
      * @private
      */
-    private readPdfAnnoLinkedPopup;
+    private setAnnotString;
     /**
      * Read vertices of pdf annotation
      * @param page  - pdf page infor
@@ -820,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
@@ -916,6 +993,23 @@ declare class PdfiumEngine<T = Blob> implements PdfEngine<T> {
      * @private
      */
     private readPageAnnoAppearanceStream;
+    /**
+     * Change the visible colour (and opacity) of an existing annotation.
+     *
+     * For markup annotations (highlight / underline / strikeout / squiggly) we
+     * first clear the AP dictionary entry, otherwise the stored appearance stream
+     * will override the new tint.  For all other sub-types we keep the existing
+     * AP so custom artwork isn't lost.
+     *
+     * @param doc         logical document object
+     * @param page        logical page object
+     * @param annotation  the annotation we want to recolour
+     * @param colour      RGBA tuple (0-255 per channel)
+     * @param which       0 = stroke/fill colour  (PDFium's "colourType" param)
+     *
+     * @returns `true` when the operation succeeded
+     */
+    updateAnnotationColor(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfAnnotationObjectBase, color: WebAlphaColor, which?: number): PdfTask<boolean>;
     /**
      * Set the rect of specified annotation
      * @param page - page info that the annotation is belonged to