@embedpdf/engines 1.0.7 → 1.0.9

package/dist/pdfium.js

@@ -1,4 +1,4 @@
-import { NoopLogger, PdfTaskHelper, PdfErrorCode, Task, Rotation, PdfAnnotationSubtype, stripPdfUnwantedMarkers, dateToPdfDate, PdfPageObjectType, pdfAlphaColorToWebAlphaColor, webAlphaColorToPdfAlphaColor, AppearanceMode, quadToRect, pdfDateToDate, PDF_FORM_FIELD_TYPE, toIntRect, transformRect, toIntSize, transformSize, PdfActionType, PdfZoomMode, MatchFlag, rectToQuad } from '@embedpdf/models';
+import { NoopLogger, PdfTaskHelper, PdfErrorCode, Task, Rotation, PdfAnnotationSubtype, stripPdfUnwantedMarkers, PdfAnnotationBorderStyle, dateToPdfDate, PdfAnnotationColorType, PdfPageObjectType, pdfAlphaColorToWebAlphaColor, webAlphaColorToPdfAlphaColor, quadToRect, pdfDateToDate, flagsToNames, PDF_FORM_FIELD_TYPE, toIntRect, transformRect, makeMatrix, AppearanceMode, toIntSize, transformSize, PdfActionType, PdfZoomMode, MatchFlag, rectToQuad } from '@embedpdf/models';
 import { init } from '@embedpdf/pdfium';
 
 /**
@@ -910,7 +910,7 @@ class PdfiumEngine {
         let isSucceed = false;
         switch (annotation.type) {
             case PdfAnnotationSubtype.INK:
-                isSucceed = this.addInkStroke(page, pageCtx.pagePtr, annotationPtr, annotation.inkList);
+                isSucceed = this.addInkStroke(page, pageCtx.pagePtr, annotationPtr, annotation);
                 break;
             case PdfAnnotationSubtype.STAMP:
                 isSucceed = this.addStampContent(ctx.docPtr, page, pageCtx.pagePtr, annotationPtr, annotation.rect, annotation.contents);
@@ -919,7 +919,7 @@ class PdfiumEngine {
             case PdfAnnotationSubtype.STRIKEOUT:
             case PdfAnnotationSubtype.SQUIGGLY:
             case PdfAnnotationSubtype.HIGHLIGHT:
-                isSucceed = this.addTextMarkupContent(page, annotationPtr, annotation);
+                isSucceed = this.addTextMarkupContent(page, pageCtx.pagePtr, annotationPtr, annotation);
                 break;
         }
         if (!isSucceed) {
@@ -931,6 +931,7 @@ class PdfiumEngine {
                 message: 'can not add content of the annotation',
             });
         }
+        this.pdfiumModule.EPDFAnnot_GenerateAppearance(annotationPtr);
         this.pdfiumModule.FPDFPage_GenerateContent(pageCtx.pagePtr);
         const annotId = this.pdfiumModule.FPDFPage_GetAnnotIndex(pageCtx.pagePtr, annotationPtr);
         this.pdfiumModule.FPDFPage_CloseAnnot(annotationPtr);
@@ -988,7 +989,7 @@ class PdfiumEngine {
                 /* clear every existing stroke first */
                 if (!this.pdfiumModule.FPDFAnnot_RemoveInkList(annotPtr))
                     break;
-                ok = this.addInkStroke(page, pageCtx.pagePtr, annotPtr, annotation.inkList);
+                ok = this.addInkStroke(page, pageCtx.pagePtr, annotPtr, annotation);
                 break;
             }
             /* ── Stamp ───────────────────────────────────────────────────────────── */
@@ -1006,7 +1007,7 @@ class PdfiumEngine {
             case PdfAnnotationSubtype.STRIKEOUT:
             case PdfAnnotationSubtype.SQUIGGLY: {
                 /* replace quad-points / colour / strings in one go */
-                ok = this.addTextMarkupContent(page, annotPtr, annotation, true);
+                ok = this.addTextMarkupContent(page, pageCtx.pagePtr, annotPtr, annotation);
                 break;
             }
             /* ── Unsupported edits – fall through to error ───────────────────────── */
@@ -1015,6 +1016,7 @@ class PdfiumEngine {
         }
         /* 3 ── regenerate appearance if payload was changed ───────────────────── */
         if (ok) {
+            this.pdfiumModule.EPDFAnnot_GenerateAppearance(annotPtr);
             this.pdfiumModule.FPDFPage_GenerateContent(pageCtx.pagePtr);
         }
         /* 4 ── tidy-up native handles ──────────────────────────────────────────── */
@@ -1028,85 +1030,6 @@ class PdfiumEngine {
                 message: 'failed to update annotation',
             });
     }
-    /**
-     * {@inheritDoc @embedpdf/models!PdfEngine.transformPageAnnotation}
-     *
-     * @public
-     */
-    transformPageAnnotation(doc, page, annotation, transformation) {
-        this.logger.debug(LOG_SOURCE$1, LOG_CATEGORY$1, 'transformPageAnnotation', doc, page, annotation, transformation);
-        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `TransformPageAnnotation`, 'Begin', `${doc.id}-${page.index}`);
-        const ctx = this.cache.getContext(doc.id);
-        if (!ctx) {
-            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `TransformPageAnnotation`, 'End', `${doc.id}-${page.index}`);
-            return PdfTaskHelper.reject({
-                code: PdfErrorCode.DocNotOpen,
-                message: 'document does not open',
-            });
-        }
-        const pageCtx = ctx.acquirePage(page.index);
-        const annotationPtr = this.pdfiumModule.FPDFPage_GetAnnot(pageCtx.pagePtr, annotation.id);
-        const rect = {
-            origin: {
-                x: annotation.rect.origin.x + transformation.offset.x,
-                y: annotation.rect.origin.y + transformation.offset.y,
-            },
-            size: {
-                width: annotation.rect.size.width * transformation.scale.width,
-                height: annotation.rect.size.height * transformation.scale.height,
-            },
-        };
-        if (!this.setPageAnnoRect(page, pageCtx.pagePtr, annotationPtr, rect)) {
-            this.pdfiumModule.FPDFPage_CloseAnnot(annotationPtr);
-            pageCtx.release();
-            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `TransformPageAnnotation`, 'End', `${doc.id}-${page.index}`);
-            return PdfTaskHelper.reject({
-                code: PdfErrorCode.CantSetAnnotRect,
-                message: 'can not set the rect of the annotation',
-            });
-        }
-        switch (annotation.type) {
-            case PdfAnnotationSubtype.INK:
-                {
-                    if (!this.pdfiumModule.FPDFAnnot_RemoveInkList(annotationPtr)) {
-                        this.pdfiumModule.FPDFPage_CloseAnnot(annotationPtr);
-                        pageCtx.release();
-                        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `TransformPageAnnotation`, 'End', `${doc.id}-${page.index}`);
-                        return PdfTaskHelper.reject({
-                            code: PdfErrorCode.CantRemoveInkList,
-                            message: 'can not set the rect of the annotation',
-                        });
-                    }
-                    const inkList = annotation.inkList.map((inkStroke) => {
-                        return {
-                            points: inkStroke.points.map((point) => {
-                                return {
-                                    x: rect.origin.x +
-                                        (point.x - annotation.rect.origin.x) * transformation.scale.width,
-                                    y: rect.origin.y +
-                                        (point.y - annotation.rect.origin.y) * transformation.scale.height,
-                                };
-                            }),
-                        };
-                    });
-                    if (!this.addInkStroke(page, pageCtx.pagePtr, annotationPtr, inkList)) {
-                        this.pdfiumModule.FPDFPage_CloseAnnot(annotationPtr);
-                        pageCtx.release();
-                        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `TransformPageAnnotation`, 'End', `${doc.id}-${page.index}`);
-                        return PdfTaskHelper.reject({
-                            code: PdfErrorCode.CantAddInkStoke,
-                            message: 'can not add stroke to the ink list of annotation',
-                        });
-                    }
-                }
-                break;
-        }
-        this.pdfiumModule.FPDFPage_GenerateContent(pageCtx.pagePtr);
-        this.pdfiumModule.FPDFPage_CloseAnnot(annotationPtr);
-        pageCtx.release();
-        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `TransformPageAnnotation`, 'End', `${doc.id}-${page.index}`);
-        return PdfTaskHelper.resolve(true);
-    }
     /**
      * {@inheritDoc @embedpdf/models!PdfEngine.removePageAnnotation}
      *
@@ -1727,21 +1650,27 @@ class PdfiumEngine {
      *
      * @private
      */
-    addInkStroke(page, pagePtr, annotationPtr, inkList) {
-        for (const inkStroke of inkList) {
-            const inkPointsCount = inkStroke.points.length;
-            const inkPointsPtr = this.malloc(inkPointsCount * 8);
-            for (let i = 0; i < inkPointsCount; i++) {
-                const point = inkStroke.points[i];
-                const { x, y } = this.convertDevicePointToPagePoint(page, point);
-                this.pdfiumModule.pdfium.setValue(inkPointsPtr + i * 8, x, 'float');
-                this.pdfiumModule.pdfium.setValue(inkPointsPtr + i * 8 + 4, y, 'float');
-            }
-            if (this.pdfiumModule.FPDFAnnot_AddInkStroke(annotationPtr, inkPointsPtr, inkPointsCount) === -1) {
-                this.free(inkPointsPtr);
-                return false;
-            }
-            this.free(inkPointsPtr);
+    addInkStroke(page, pagePtr, annotationPtr, annotation) {
+        if (!this.setBorderStyle(annotationPtr, PdfAnnotationBorderStyle.SOLID, annotation.strokeWidth)) {
+            return false;
+        }
+        if (!this.setPageAnnoRect(page, pagePtr, annotationPtr, annotation.rect)) {
+            return false;
+        }
+        if (!this.setInkList(page, annotationPtr, annotation.inkList)) {
+            return false;
+        }
+        if (!this.setAnnotString(annotationPtr, 'T', annotation.author || '')) {
+            return false;
+        }
+        if (!this.setAnnotString(annotationPtr, 'M', dateToPdfDate(annotation.modified))) {
+            return false;
+        }
+        if (!this.setAnnotationColor(annotationPtr, {
+            color: annotation.color ?? '#FFFF00',
+            opacity: annotation.opacity ?? 1,
+        }, PdfAnnotationColorType.Color)) {
+            return false;
         }
         return true;
     }
@@ -1754,7 +1683,10 @@ class PdfiumEngine {
      *
      * @private
      */
-    addTextMarkupContent(page, annotationPtr, annotation, shouldClearAP = false) {
+    addTextMarkupContent(page, pagePtr, annotationPtr, annotation) {
+        if (!this.setPageAnnoRect(page, pagePtr, annotationPtr, annotation.rect)) {
+            return false;
+        }
         if (!this.syncQuadPointsAnno(page, annotationPtr, annotation.segmentRects)) {
             return false;
         }
@@ -1770,7 +1702,7 @@ class PdfiumEngine {
         if (!this.setAnnotationColor(annotationPtr, {
             color: annotation.color ?? '#FFFF00',
             opacity: annotation.opacity ?? 1,
-        }, shouldClearAP, 0)) {
+        }, PdfAnnotationColorType.Color)) {
             return false;
         }
         return true;
@@ -2417,14 +2349,13 @@ class PdfiumEngine {
      *
      * @private
      */
-    readAnnotationColor(annotationPtr) {
+    readAnnotationColor(annotationPtr, colorType = PdfAnnotationColorType.Color) {
         const rPtr = this.malloc(4);
         const gPtr = this.malloc(4);
         const bPtr = this.malloc(4);
         const aPtr = this.malloc(4);
         // colourType 0 = "colour" (stroke/fill); other types are interior/border
-        const ok = this.pdfiumModule.FPDFAnnot_GetColor(annotationPtr, 
-        /* colorType = */ 0, rPtr, gPtr, bPtr, aPtr);
+        const ok = this.pdfiumModule.EPDFAnnot_GetColor(annotationPtr, colorType, rPtr, gPtr, bPtr, aPtr);
         let colour;
         if (ok) {
             colour = {
@@ -2441,97 +2372,6 @@ class PdfiumEngine {
         return colour;
     }
     /* --------------------------------------------------------------------------- */
-    /**
-     * 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
-     */
-    getColorFromPath(pathPtr) {
-        const r = this.malloc(4), g = this.malloc(4), b = this.malloc(4), a = this.malloc(4);
-        const fillOk = this.pdfiumModule.FPDFPageObj_GetFillColor(pathPtr, r, g, b, a);
-        const strokeOk = !fillOk && // try stroke only if fill failed
-            this.pdfiumModule.FPDFPageObj_GetStrokeColor(pathPtr, r, g, b, a);
-        const ok = fillOk || strokeOk;
-        let c;
-        if (ok) {
-            c = {
-                red: this.pdfiumModule.pdfium.getValue(r, 'i32') & 0xff,
-                green: this.pdfiumModule.pdfium.getValue(g, 'i32') & 0xff,
-                blue: this.pdfiumModule.pdfium.getValue(b, 'i32') & 0xff,
-                alpha: this.pdfiumModule.pdfium.getValue(a, 'i32') & 0xff,
-            };
-        }
-        this.free(r);
-        this.free(g);
-        this.free(b);
-        this.free(a);
-        return c;
-    }
-    /* --------------------------------------------------------------------------- */
-    /**
-     * 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
-     */
-    walkPageObjTree(objPtr) {
-        const type = this.pdfiumModule.FPDFPageObj_GetType(objPtr);
-        if (type === PdfPageObjectType.PATH)
-            return this.getColorFromPath(objPtr);
-        if (type !== PdfPageObjectType.FORM)
-            return undefined;
-        const cnt = this.pdfiumModule.FPDFFormObj_CountObjects(objPtr);
-        for (let i = 0; i < cnt; i++) {
-            const child = this.pdfiumModule.FPDFFormObj_GetObject(objPtr, i);
-            if (!child)
-                continue;
-            const c = this.walkPageObjTree(child);
-            if (c)
-                return c;
-        }
-        return undefined;
-    }
-    /* --------------------------------------------------------------------------- */
-    /**
-     * 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
-     */
-    colorFromAppearance(annotPtr) {
-        const n = this.pdfiumModule.FPDFAnnot_GetObjectCount(annotPtr);
-        for (let i = 0; i < n; i++) {
-            const obj = this.pdfiumModule.FPDFAnnot_GetObject(annotPtr, i);
-            if (!obj)
-                continue;
-            const c = this.walkPageObjTree(obj);
-            if (c)
-                return c;
-        }
-        return undefined;
-    }
-    /* --------------------------------------------------------------------------- */
     /**
      * Resolve the visible fill colour for **Highlight / Underline / StrikeOut /
      * Squiggly** markup annotations.
@@ -2547,10 +2387,8 @@ class PdfiumEngine {
      *
      * @private
      */
-    resolveAnnotationColor(annotationPtr, fallback = { red: 255, green: 245, blue: 155, alpha: 255 }) {
-        const pdfColor = this.readAnnotationColor(annotationPtr) ?? // 1 – /C entry
-            this.colorFromAppearance(annotationPtr) ?? // 2 – AP stream walk
-            fallback; // 3 – default
+    resolveAnnotationColor(annotationPtr, colorType = PdfAnnotationColorType.Color, fallback = { red: 255, green: 245, blue: 155, alpha: 255 }) {
+        const pdfColor = this.readAnnotationColor(annotationPtr, colorType) ?? fallback;
         return pdfAlphaColorToWebAlphaColor(pdfColor);
     }
     /**
@@ -2564,14 +2402,115 @@ class PdfiumEngine {
      *
      * @private
      */
-    setAnnotationColor(annotationPtr, webAlphaColor, shouldClearAP = false, which = 0) {
+    setAnnotationColor(annotationPtr, webAlphaColor, colorType = PdfAnnotationColorType.Color) {
         const pdfAlphaColor = webAlphaColorToPdfAlphaColor(webAlphaColor);
-        if (shouldClearAP) {
-            // NULL wide-string → remove the /AP entry
-            this.pdfiumModule.FPDFAnnot_SetAP(annotationPtr, AppearanceMode.Normal, 
-            /* FPDF_WIDESTRING = */ 0);
+        return this.pdfiumModule.EPDFAnnot_SetColor(annotationPtr, colorType, pdfAlphaColor.red & 0xff, pdfAlphaColor.green & 0xff, pdfAlphaColor.blue & 0xff, (pdfAlphaColor.alpha ?? 255) & 0xff);
+    }
+    /**
+     * 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)
+     */
+    getBorderStyle(annotationPtr) {
+        /* 1 ── allocate tmp storage for the returned width ─────────────── */
+        const widthPtr = this.malloc(4);
+        let width = 0;
+        let style = PdfAnnotationBorderStyle.UNKNOWN;
+        let ok = false;
+        style = this.pdfiumModule.EPDFAnnot_GetBorderStyle(annotationPtr, widthPtr);
+        width = this.pdfiumModule.pdfium.getValue(widthPtr, 'float');
+        ok = style !== PdfAnnotationBorderStyle.UNKNOWN;
+        this.free(widthPtr);
+        return { ok, style, width };
+    }
+    setBorderStyle(annotationPtr, style, width) {
+        return this.pdfiumModule.EPDFAnnot_SetBorderStyle(annotationPtr, style, width);
+    }
+    /**
+     * 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)
+     */
+    getBorderEffect(annotationPtr) {
+        const intensityPtr = this.malloc(4);
+        const ok = !!this.pdfiumModule.EPDFAnnot_GetBorderEffect(annotationPtr, intensityPtr);
+        const intensity = ok ? this.pdfiumModule.pdfium.getValue(intensityPtr, 'float') : 0;
+        this.free(intensityPtr);
+        return { ok, intensity };
+    }
+    /**
+     * 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
+     */
+    getRectangleDifferences(annotationPtr) {
+        /* tmp storage ─────────────────────────────────────────── */
+        const lPtr = this.malloc(4);
+        const tPtr = this.malloc(4);
+        const rPtr = this.malloc(4);
+        const bPtr = this.malloc(4);
+        const ok = !!this.pdfiumModule.EPDFAnnot_GetRectangleDifferences(annotationPtr, lPtr, tPtr, rPtr, bPtr);
+        const pdf = this.pdfiumModule.pdfium;
+        const left = pdf.getValue(lPtr, 'float');
+        const top = pdf.getValue(tPtr, 'float');
+        const right = pdf.getValue(rPtr, 'float');
+        const bottom = pdf.getValue(bPtr, 'float');
+        /* cleanup ─────────────────────────────────────────────── */
+        this.free(lPtr);
+        this.free(tPtr);
+        this.free(rPtr);
+        this.free(bPtr);
+        return { ok, left, top, right, bottom };
+    }
+    /**
+     * 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)
+     */
+    getBorderDashPattern(annotationPtr) {
+        const count = this.pdfiumModule.EPDFAnnot_GetBorderDashPatternCount(annotationPtr);
+        if (count === 0) {
+            return { ok: false, pattern: [] };
+        }
+        /* allocate `count` floats on the WASM heap */
+        const arrPtr = this.malloc(4 * count);
+        const okNative = !!this.pdfiumModule.EPDFAnnot_GetBorderDashPattern(annotationPtr, arrPtr, count);
+        /* copy out */
+        const pattern = [];
+        if (okNative) {
+            const pdf = this.pdfiumModule.pdfium;
+            for (let i = 0; i < count; i++) {
+                pattern.push(pdf.getValue(arrPtr + 4 * i, 'float'));
+            }
         }
-        return this.pdfiumModule.FPDFAnnot_SetColor(annotationPtr, which, pdfAlphaColor.red & 0xff, pdfAlphaColor.green & 0xff, pdfAlphaColor.blue & 0xff, (pdfAlphaColor.alpha ?? 255) & 0xff);
+        this.free(arrPtr);
+        return { ok: okNative, pattern };
     }
     /**
      * Read `/QuadPoints` from any annotation and convert each quadrilateral to
@@ -2670,6 +2609,62 @@ class PdfiumEngine {
         this.free(buf);
         return true;
     }
+    /**
+     * 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
+     */
+    getInkList(page, annotationPtr) {
+        const inkList = [];
+        const count = this.pdfiumModule.FPDFAnnot_GetInkListCount(annotationPtr);
+        for (let i = 0; i < count; i++) {
+            const points = [];
+            const pointsCount = this.pdfiumModule.FPDFAnnot_GetInkListPath(annotationPtr, i, 0, 0);
+            if (pointsCount > 0) {
+                const pointMemorySize = 8;
+                const pointsPtr = this.malloc(pointsCount * pointMemorySize);
+                this.pdfiumModule.FPDFAnnot_GetInkListPath(annotationPtr, i, pointsPtr, pointsCount);
+                for (let j = 0; j < pointsCount; j++) {
+                    const pointX = this.pdfiumModule.pdfium.getValue(pointsPtr + j * 8, 'float');
+                    const pointY = this.pdfiumModule.pdfium.getValue(pointsPtr + j * 8 + 4, 'float');
+                    const { x, y } = this.convertPagePointToDevicePoint(page, {
+                        x: pointX,
+                        y: pointY,
+                    });
+                    points.push({ x, y });
+                }
+                this.free(pointsPtr);
+            }
+            inkList.push({ points });
+        }
+        return inkList;
+    }
+    /**
+     * 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
+     */
+    setInkList(page, annotationPtr, inkList) {
+        for (const inkStroke of inkList) {
+            const inkPointsCount = inkStroke.points.length;
+            const inkPointsPtr = this.malloc(inkPointsCount * 8);
+            for (let i = 0; i < inkPointsCount; i++) {
+                const point = inkStroke.points[i];
+                const { x, y } = this.convertDevicePointToPagePoint(page, point);
+                this.pdfiumModule.pdfium.setValue(inkPointsPtr + i * 8, x, 'float');
+                this.pdfiumModule.pdfium.setValue(inkPointsPtr + i * 8 + 4, y, 'float');
+            }
+            if (this.pdfiumModule.FPDFAnnot_AddInkStroke(annotationPtr, inkPointsPtr, inkPointsCount) === -1) {
+                this.free(inkPointsPtr);
+                return false;
+            }
+            this.free(inkPointsPtr);
+        }
+        return true;
+    }
     /**
      * Read pdf text annotation
      * @param page  - pdf page infor
@@ -2846,32 +2841,15 @@ class PdfiumEngine {
         const author = this.getAnnotString(annotationPtr, 'T');
         const modifiedRaw = this.getAnnotString(annotationPtr, 'M');
         const modified = pdfDateToDate(modifiedRaw);
-        const inkList = [];
-        const count = this.pdfiumModule.FPDFAnnot_GetInkListCount(annotationPtr);
-        for (let i = 0; i < count; i++) {
-            const points = [];
-            const pointsCount = this.pdfiumModule.FPDFAnnot_GetInkListPath(annotationPtr, i, 0, 0);
-            if (pointsCount > 0) {
-                const pointMemorySize = 8;
-                const pointsPtr = this.malloc(pointsCount * pointMemorySize);
-                this.pdfiumModule.FPDFAnnot_GetInkListPath(annotationPtr, i, pointsPtr, pointsCount);
-                for (let j = 0; j < pointsCount; j++) {
-                    const pointX = this.pdfiumModule.pdfium.getValue(pointsPtr + j * 8, 'float');
-                    const pointY = this.pdfiumModule.pdfium.getValue(pointsPtr + j * 8 + 4, 'float');
-                    const { x, y } = this.convertPagePointToDevicePoint(page, {
-                        x: pointX,
-                        y: pointY,
-                    });
-                    points.push({ x, y });
-                }
-                this.free(pointsPtr);
-            }
-            inkList.push({ points });
-        }
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
+        const { width: strokeWidth } = this.getBorderStyle(annotationPtr);
+        const inkList = this.getInkList(page, annotationPtr);
         return {
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.INK,
+            ...webAlphaColor,
+            strokeWidth,
             rect,
             inkList,
             author,
@@ -3325,6 +3303,39 @@ class PdfiumEngine {
         this.free(matrixPtr);
         return { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
     }
+    /**
+     * 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
+     */
+    getStrokeWidth(annotationPtr) {
+        // FPDFAnnot_GetBorder(annot, &hRadius, &vRadius, &borderWidth)
+        const hPtr = this.malloc(4);
+        const vPtr = this.malloc(4);
+        const wPtr = this.malloc(4);
+        const ok = this.pdfiumModule.FPDFAnnot_GetBorder(annotationPtr, hPtr, vPtr, wPtr);
+        const width = ok ? this.pdfiumModule.pdfium.getValue(wPtr, 'float') : 1; // default 1 pt
+        this.free(hPtr);
+        this.free(vPtr);
+        this.free(wPtr);
+        return width;
+    }
+    /**
+     * 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
+     */
+    getAnnotationFlags(annotationPtr) {
+        const rawFlags = this.pdfiumModule.FPDFAnnot_GetFlags(annotationPtr); // number
+        return flagsToNames(rawFlags);
+    }
     /**
      * Read circle annotation
      * @param page  - pdf page infor
@@ -3336,18 +3347,51 @@ class PdfiumEngine {
      * @private
      */
     readPdfCircleAnno(page, pagePtr, annotationPtr, index) {
+        const flags = this.getAnnotationFlags(annotationPtr);
         const pageRect = this.readPageAnnoRect(annotationPtr);
         const rect = this.convertPageRectToDeviceRect(page, pagePtr, pageRect);
         const author = this.getAnnotString(annotationPtr, 'T');
         const modifiedRaw = this.getAnnotString(annotationPtr, 'M');
         const modified = pdfDateToDate(modifiedRaw);
+        const { color, opacity } = this.resolveAnnotationColor(annotationPtr, PdfAnnotationColorType.InteriorColor);
+        const { color: strokeColor } = this.resolveAnnotationColor(annotationPtr);
+        let { style: strokeStyle, width: strokeWidth } = this.getBorderStyle(annotationPtr);
+        let cloudyBorderIntensity;
+        let cloudyBorderInset;
+        if (strokeStyle === PdfAnnotationBorderStyle.CLOUDY ||
+            strokeStyle === PdfAnnotationBorderStyle.UNKNOWN) {
+            const { ok: hasEffect, intensity } = this.getBorderEffect(annotationPtr);
+            if (hasEffect) {
+                cloudyBorderIntensity = intensity;
+                strokeStyle = PdfAnnotationBorderStyle.CLOUDY;
+                const { ok: hasInset, left, top, right, bottom, } = this.getRectangleDifferences(annotationPtr);
+                if (hasInset)
+                    cloudyBorderInset = [left, top, right, bottom];
+            }
+        }
+        let strokeDashArray;
+        if (strokeStyle === PdfAnnotationBorderStyle.DASHED) {
+            const { ok, pattern } = this.getBorderDashPattern(annotationPtr);
+            if (ok) {
+                strokeDashArray = pattern;
+            }
+        }
         return {
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.CIRCLE,
+            flags,
+            color,
+            opacity,
+            strokeWidth,
+            strokeColor,
+            strokeStyle,
             rect,
             author,
             modified,
+            ...(cloudyBorderIntensity !== undefined && { cloudyBorderIntensity }),
+            ...(cloudyBorderInset !== undefined && { cloudyBorderInset }),
+            ...(strokeDashArray !== undefined && { strokeDashArray }),
         };
     }
     /**
@@ -3361,18 +3405,51 @@ class PdfiumEngine {
      * @private
      */
     readPdfSquareAnno(page, pagePtr, annotationPtr, index) {
+        const flags = this.getAnnotationFlags(annotationPtr);
         const pageRect = this.readPageAnnoRect(annotationPtr);
         const rect = this.convertPageRectToDeviceRect(page, pagePtr, pageRect);
         const author = this.getAnnotString(annotationPtr, 'T');
         const modifiedRaw = this.getAnnotString(annotationPtr, 'M');
         const modified = pdfDateToDate(modifiedRaw);
+        const { color, opacity } = this.resolveAnnotationColor(annotationPtr, PdfAnnotationColorType.InteriorColor);
+        const { color: strokeColor } = this.resolveAnnotationColor(annotationPtr);
+        let { style: strokeStyle, width: strokeWidth } = this.getBorderStyle(annotationPtr);
+        let cloudyBorderIntensity;
+        let cloudyBorderInset;
+        if (strokeStyle === PdfAnnotationBorderStyle.CLOUDY ||
+            strokeStyle === PdfAnnotationBorderStyle.UNKNOWN) {
+            const { ok: hasEffect, intensity } = this.getBorderEffect(annotationPtr);
+            if (hasEffect) {
+                cloudyBorderIntensity = intensity;
+                strokeStyle = PdfAnnotationBorderStyle.CLOUDY;
+                const { ok: hasInset, left, top, right, bottom, } = this.getRectangleDifferences(annotationPtr);
+                if (hasInset)
+                    cloudyBorderInset = [left, top, right, bottom];
+            }
+        }
+        let strokeDashArray;
+        if (strokeStyle === PdfAnnotationBorderStyle.DASHED) {
+            const { ok, pattern } = this.getBorderDashPattern(annotationPtr);
+            if (ok) {
+                strokeDashArray = pattern;
+            }
+        }
         return {
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.SQUARE,
+            flags,
+            color,
+            opacity,
+            strokeColor,
+            strokeWidth,
+            strokeStyle,
             rect,
             author,
             modified,
+            ...(cloudyBorderIntensity !== undefined && { cloudyBorderIntensity }),
+            ...(cloudyBorderInset !== undefined && { cloudyBorderInset }),
+            ...(strokeDashArray !== undefined && { strokeDashArray }),
         };
     }
     /**
@@ -3558,6 +3635,81 @@ class PdfiumEngine {
             options,
         };
     }
+    /**
+     * {@inheritDoc @embedpdf/models!PdfEngine.renderAnnotation}
+     *
+     * @public
+     */
+    renderAnnotation(doc, page, annotation, scaleFactor, rotation, dpr = 1, // device-pixel-ratio (canvas)
+    mode = AppearanceMode.Normal, imageType = 'image/webp') {
+        this.logger.debug(LOG_SOURCE$1, LOG_CATEGORY$1, 'renderAnnotation', doc, page, annotation, scaleFactor, rotation, dpr, mode, imageType);
+        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `RenderAnnotation`, 'Begin', `${doc.id}-${page.index}-${annotation.id}`);
+        const task = new Task();
+        const ctx = this.cache.getContext(doc.id);
+        if (!ctx) {
+            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `RenderAnnotation`, 'End', `${doc.id}-${page.index}-${annotation.id}`);
+            return PdfTaskHelper.reject({
+                code: PdfErrorCode.DocNotOpen,
+                message: 'document does not open',
+            });
+        }
+        /* ── 1. grab native handles ───────────────────────────────────────── */
+        const pageCtx = ctx.acquirePage(page.index);
+        const annotPtr = this.pdfiumModule.FPDFPage_GetAnnot(pageCtx.pagePtr, annotation.id);
+        if (!annotPtr) {
+            pageCtx.release();
+            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `RenderAnnotation`, 'End', `${doc.id}-${page.index}-${annotation.id}`);
+            return PdfTaskHelper.reject({
+                code: PdfErrorCode.NotFound,
+                message: 'annotation not found',
+            });
+        }
+        const finalScale = scaleFactor * dpr;
+        /* ── 2. decide bitmap size (integer pixels) ──────────────────────── */
+        const annotRect = annotation.rect;
+        const bitmapRect = toIntRect(transformRect(page.size, annotRect, rotation, finalScale));
+        const format = BitmapFormat.Bitmap_BGRA;
+        const bytesPerPixel = 4;
+        const bitmapHeapLength = bitmapRect.size.width * bitmapRect.size.height * bytesPerPixel;
+        const bitmapHeapPtr = this.malloc(bitmapHeapLength);
+        const bitmapPtr = this.pdfiumModule.FPDFBitmap_CreateEx(bitmapRect.size.width, bitmapRect.size.height, format, bitmapHeapPtr, bitmapRect.size.width * bytesPerPixel);
+        this.pdfiumModule.FPDFBitmap_FillRect(bitmapPtr, 0, 0, bitmapRect.size.width, bitmapRect.size.height, 0x00000000);
+        const matrix = makeMatrix(annotation.rect, rotation, finalScale);
+        // Allocate memory for the matrix on the wasm heap and write to it
+        const matrixSize = 6 * 4;
+        const matrixPtr = this.malloc(matrixSize);
+        const matrixView = new Float32Array(this.pdfiumModule.pdfium.HEAPF32.buffer, matrixPtr, 6);
+        matrixView.set([matrix.a, matrix.b, matrix.c, matrix.d, matrix.e, matrix.f]);
+        /* ── 5. call the native helper with the new matrix ───────────────── */
+        const FLAGS = RenderFlag.REVERSE_BYTE_ORDER;
+        const ok = !!this.pdfiumModule.EPDF_RenderAnnotBitmap(bitmapPtr, pageCtx.pagePtr, annotPtr, mode, matrixPtr, FLAGS);
+        /* ── 6. tear down native resources ───────────────────────────────── */
+        this.free(matrixPtr); // Free the matrix memory
+        this.pdfiumModule.FPDFBitmap_Destroy(bitmapPtr);
+        this.pdfiumModule.FPDFPage_CloseAnnot(annotPtr);
+        pageCtx.release();
+        if (!ok) {
+            this.free(bitmapHeapPtr);
+            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `RenderAnnotation`, 'End', `${doc.id}-${page.index}-${annotation.id}`);
+            return PdfTaskHelper.reject({
+                code: PdfErrorCode.Unknown,
+                message: 'EPDF_RenderAnnotBitmap failed',
+            });
+        }
+        /* ── 6. copy out + convert to Blob (reuse existing converter) ─────── */
+        const data = this.pdfiumModule.pdfium.HEAPU8.subarray(bitmapHeapPtr, bitmapHeapPtr + bitmapHeapLength);
+        const imageData = {
+            data: new Uint8ClampedArray(data),
+            width: bitmapRect.size.width,
+            height: bitmapRect.size.height,
+        };
+        this.free(bitmapHeapPtr);
+        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `RenderAnnotation`, 'End', `${doc.id}-${page.index}-${annotation.id}`);
+        this.imageDataConverter(imageData, imageType)
+            .then((blob) => task.resolve(blob))
+            .catch((err) => task.reject({ code: PdfErrorCode.Unknown, message: String(err) }));
+        return task;
+    }
     /**
      * render rectangle of pdf page to image
      * @param docPtr - pointer to pdf document object
@@ -3928,12 +4080,7 @@ class PdfiumEngine {
                 task.resolve(false);
                 return task;
             }
-            /* 2 ── wipe AP if it's a simple markup annotation ─────────────────────── */
-            const shouldClearAP = annotation.type === PdfAnnotationSubtype.HIGHLIGHT ||
-                annotation.type === PdfAnnotationSubtype.UNDERLINE ||
-                annotation.type === PdfAnnotationSubtype.STRIKEOUT ||
-                annotation.type === PdfAnnotationSubtype.SQUIGGLY;
-            const ok = this.setAnnotationColor(annotPtr, color, shouldClearAP, which);
+            const ok = this.setAnnotationColor(annotPtr, color, which);
             /* 4 ── regenerate appearance & clean-up ───────────────────────────────── */
             if (ok) {
                 this.pdfiumModule.FPDFPage_GenerateContent(pageCtx.pagePtr);
@@ -4343,6 +4490,9 @@ class EngineRunner {
                 case 'renderPageRect':
                     task = this.engine[name](...args);
                     break;
+                case 'renderAnnotation':
+                    task = this.engine[name](...args);
+                    break;
                 case 'renderThumbnail':
                     task = this.engine[name](...args);
                     break;
@@ -4358,9 +4508,6 @@ class EngineRunner {
                 case 'updatePageAnnotation':
                     task = this.engine[name](...args);
                     break;
-                case 'transformPageAnnotation':
-                    task = this.engine[name](...args);
-                    break;
                 case 'removePageAnnotation':
                     task = this.engine[name](...args);
                     break;