@embedpdf/engines 1.0.6 → 1.0.7

package/dist/pdfium.cjs

@@ -917,6 +917,12 @@ class PdfiumEngine {
             case models.PdfAnnotationSubtype.STAMP:
                 isSucceed = this.addStampContent(ctx.docPtr, page, pageCtx.pagePtr, annotationPtr, annotation.rect, annotation.contents);
                 break;
+            case models.PdfAnnotationSubtype.UNDERLINE:
+            case models.PdfAnnotationSubtype.STRIKEOUT:
+            case models.PdfAnnotationSubtype.SQUIGGLY:
+            case models.PdfAnnotationSubtype.HIGHLIGHT:
+                isSucceed = this.addTextMarkupContent(page, annotationPtr, annotation);
+                break;
         }
         if (!isSucceed) {
             this.pdfiumModule.FPDFPage_RemoveAnnot(pageCtx.pagePtr, annotationPtr);
@@ -928,10 +934,101 @@ class PdfiumEngine {
             });
         }
         this.pdfiumModule.FPDFPage_GenerateContent(pageCtx.pagePtr);
+        const annotId = this.pdfiumModule.FPDFPage_GetAnnotIndex(pageCtx.pagePtr, annotationPtr);
         this.pdfiumModule.FPDFPage_CloseAnnot(annotationPtr);
         pageCtx.release();
         this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, `CreatePageAnnotation`, 'End', `${doc.id}-${page.index}`);
-        return models.PdfTaskHelper.resolve(true);
+        return annotId >= 0
+            ? models.PdfTaskHelper.resolve(annotId)
+            : models.PdfTaskHelper.reject({
+                code: models.PdfErrorCode.CantCreateAnnot,
+                message: 'annotation created but index could not be determined',
+            });
+    }
+    /**
+     * Update an existing page annotation in-place
+     *
+     *  • 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
+     */
+    updatePageAnnotation(doc, page, annotation) {
+        this.logger.debug(LOG_SOURCE$1, LOG_CATEGORY$1, 'updatePageAnnotation', doc, page, annotation);
+        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'UpdatePageAnnotation', 'Begin', `${doc.id}-${page.index}`);
+        const ctx = this.cache.getContext(doc.id);
+        if (!ctx) {
+            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'UpdatePageAnnotation', 'End', `${doc.id}-${page.index}`);
+            return models.PdfTaskHelper.reject({
+                code: models.PdfErrorCode.DocNotOpen,
+                message: 'document does not open',
+            });
+        }
+        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, 'UpdatePageAnnotation', 'End', `${doc.id}-${page.index}`);
+            return models.PdfTaskHelper.reject({ code: models.PdfErrorCode.NotFound, message: 'annotation not found' });
+        }
+        /* 1 ── (re)set bounding-box ────────────────────────────────────────────── */
+        if (!this.setPageAnnoRect(page, pageCtx.pagePtr, annotPtr, annotation.rect)) {
+            this.pdfiumModule.FPDFPage_CloseAnnot(annotPtr);
+            pageCtx.release();
+            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'UpdatePageAnnotation', 'End', `${doc.id}-${page.index}`);
+            return models.PdfTaskHelper.reject({
+                code: models.PdfErrorCode.CantSetAnnotRect,
+                message: 'failed to move annotation',
+            });
+        }
+        /* 2 ── wipe previous payload and rebuild fresh one ─────────────────────── */
+        let ok = false;
+        switch (annotation.type) {
+            /* ── Ink ─────────────────────────────────────────────────────────────── */
+            case models.PdfAnnotationSubtype.INK: {
+                /* clear every existing stroke first */
+                if (!this.pdfiumModule.FPDFAnnot_RemoveInkList(annotPtr))
+                    break;
+                ok = this.addInkStroke(page, pageCtx.pagePtr, annotPtr, annotation.inkList);
+                break;
+            }
+            /* ── Stamp ───────────────────────────────────────────────────────────── */
+            case models.PdfAnnotationSubtype.STAMP: {
+                /* drop every page-object inside the annot */
+                for (let i = this.pdfiumModule.FPDFAnnot_GetObjectCount(annotPtr) - 1; i >= 0; i--) {
+                    this.pdfiumModule.FPDFAnnot_RemoveObject(annotPtr, i);
+                }
+                ok = this.addStampContent(ctx.docPtr, page, pageCtx.pagePtr, annotPtr, annotation.rect, annotation.contents);
+                break;
+            }
+            /* ── Text-markup family ──────────────────────────────────────────────── */
+            case models.PdfAnnotationSubtype.HIGHLIGHT:
+            case models.PdfAnnotationSubtype.UNDERLINE:
+            case models.PdfAnnotationSubtype.STRIKEOUT:
+            case models.PdfAnnotationSubtype.SQUIGGLY: {
+                /* replace quad-points / colour / strings in one go */
+                ok = this.addTextMarkupContent(page, annotPtr, annotation, true);
+                break;
+            }
+            /* ── Unsupported edits – fall through to error ───────────────────────── */
+            default:
+                ok = false;
+        }
+        /* 3 ── regenerate appearance if payload was changed ───────────────────── */
+        if (ok) {
+            this.pdfiumModule.FPDFPage_GenerateContent(pageCtx.pagePtr);
+        }
+        /* 4 ── tidy-up native handles ──────────────────────────────────────────── */
+        this.pdfiumModule.FPDFPage_CloseAnnot(annotPtr);
+        pageCtx.release();
+        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'UpdatePageAnnotation', 'End', `${doc.id}-${page.index}`);
+        return ok
+            ? models.PdfTaskHelper.resolve(true)
+            : models.PdfTaskHelper.reject({
+                code: models.PdfErrorCode.CantSetAnnotContent,
+                message: 'failed to update annotation',
+            });
     }
     /**
      * {@inheritDoc @embedpdf/models!PdfEngine.transformPageAnnotation}
@@ -1650,6 +1747,36 @@ class PdfiumEngine {
         }
         return true;
     }
+    /**
+     * 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, annotationPtr, annotation, shouldClearAP = false) {
+        if (!this.syncQuadPointsAnno(page, annotationPtr, annotation.segmentRects)) {
+            return false;
+        }
+        if (!this.setAnnotString(annotationPtr, 'Contents', annotation.contents ?? '')) {
+            return false;
+        }
+        if (!this.setAnnotString(annotationPtr, 'T', annotation.author || '')) {
+            return false;
+        }
+        if (!this.setAnnotString(annotationPtr, 'M', models.dateToPdfDate(annotation.modified))) {
+            return false;
+        }
+        if (!this.setAnnotationColor(annotationPtr, {
+            color: annotation.color ?? '#FFFF00',
+            opacity: annotation.opacity ?? 1,
+        }, shouldClearAP, 0)) {
+            return false;
+        }
+        return true;
+    }
     /**
      * Add contents to stamp annotation
      * @param docPtr - pointer to pdf document object
@@ -2272,8 +2399,6 @@ class PdfiumEngine {
                     annotation = this.readPdfCaretAnno(page, pageCtx.pagePtr, annotationPtr, index);
                 }
                 break;
-            case models.PdfAnnotationSubtype.POPUP:
-                break;
             default:
                 {
                     annotation = this.readPdfAnno(page, pageCtx.pagePtr, subType, annotationPtr, index);
@@ -2420,15 +2545,35 @@ class PdfiumEngine {
      *
      * @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`)
+     * @returns WebAlphaColor with hex color and opacity (0-1)
      *
      * @private
      */
     resolveAnnotationColor(annotationPtr, fallback = { red: 255, green: 245, blue: 155, alpha: 255 }) {
-        return (this.readAnnotationColor(annotationPtr) ?? // 1 – /C entry
+        const pdfColor = this.readAnnotationColor(annotationPtr) ?? // 1 – /C entry
             this.colorFromAppearance(annotationPtr) ?? // 2 – AP stream walk
-            fallback // 3 – default
-        );
+            fallback; // 3 – default
+        return models.pdfAlphaColorToWebAlphaColor(pdfColor);
+    }
+    /**
+     * Set the fill/stroke colour for a **Highlight / Underline / StrikeOut / Squiggly** markup annotation.
+     *
+     * @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
+     */
+    setAnnotationColor(annotationPtr, webAlphaColor, shouldClearAP = false, which = 0) {
+        const pdfAlphaColor = models.webAlphaColorToPdfAlphaColor(webAlphaColor);
+        if (shouldClearAP) {
+            // NULL wide-string → remove the /AP entry
+            this.pdfiumModule.FPDFAnnot_SetAP(annotationPtr, models.AppearanceMode.Normal, 
+            /* FPDF_WIDESTRING = */ 0);
+        }
+        return this.pdfiumModule.FPDFAnnot_SetColor(annotationPtr, which, pdfAlphaColor.red & 0xff, pdfAlphaColor.green & 0xff, pdfAlphaColor.blue & 0xff, (pdfAlphaColor.alpha ?? 255) & 0xff);
     }
     /**
      * Read `/QuadPoints` from any annotation and convert each quadrilateral to
@@ -2441,11 +2586,11 @@ class PdfiumEngine {
      *
      * @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
      */
-    readAnnotationQuads(page, annotationPtr) {
+    getQuadPointsAnno(page, annotationPtr) {
         const quadCount = this.pdfiumModule.FPDFAnnot_CountAttachmentPoints(annotationPtr);
         if (quadCount === 0)
             return [];
@@ -2472,7 +2617,60 @@ class PdfiumEngine {
             }
             this.free(quadPtr);
         }
-        return quads;
+        return quads.map(models.quadToRect);
+    }
+    /**
+     * 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
+     */
+    syncQuadPointsAnno(page, annotPtr, rects) {
+        const FS_QUADPOINTSF_SIZE = 8 * 4; // eight floats, 32 bytes
+        const pdf = this.pdfiumModule.pdfium;
+        const count = this.pdfiumModule.FPDFAnnot_CountAttachmentPoints(annotPtr);
+        const buf = this.malloc(FS_QUADPOINTSF_SIZE);
+        /** write one quad into `buf` in annotation space */
+        const writeQuad = (r) => {
+            const q = models.rectToQuad(r); // TL, TR, BR, BL
+            const p1 = this.convertDevicePointToPagePoint(page, q.p1);
+            const p2 = this.convertDevicePointToPagePoint(page, q.p2);
+            const p3 = this.convertDevicePointToPagePoint(page, q.p3); // BR
+            const p4 = this.convertDevicePointToPagePoint(page, q.p4); // BL
+            // PDF QuadPoints order: BL, BR, TL, TR (bottom-left, bottom-right, top-left, top-right)
+            pdf.setValue(buf + 0, p1.x, 'float'); // BL (bottom-left)
+            pdf.setValue(buf + 4, p1.y, 'float');
+            pdf.setValue(buf + 8, p2.x, 'float'); // BR (bottom-right)
+            pdf.setValue(buf + 12, p2.y, 'float');
+            pdf.setValue(buf + 16, p4.x, 'float'); // TL (top-left)
+            pdf.setValue(buf + 20, p4.y, 'float');
+            pdf.setValue(buf + 24, p3.x, 'float'); // TR (top-right)
+            pdf.setValue(buf + 28, p3.y, 'float');
+        };
+        /* ----------------------------------------------------------------------- */
+        /* 1. overwrite the quads that already exist                               */
+        const min = Math.min(count, rects.length);
+        for (let i = 0; i < min; i++) {
+            writeQuad(rects[i]);
+            if (!this.pdfiumModule.FPDFAnnot_SetAttachmentPoints(annotPtr, i, buf)) {
+                this.free(buf);
+                return false;
+            }
+        }
+        /* 2. append new quads if rects.length > count                             */
+        for (let i = count; i < rects.length; i++) {
+            writeQuad(rects[i]);
+            if (!this.pdfiumModule.FPDFAnnot_AppendAttachmentPoints(annotPtr, buf)) {
+                this.free(buf);
+                return false;
+            }
+        }
+        this.free(buf);
+        return true;
     }
     /**
      * Read pdf text annotation
@@ -2485,30 +2683,23 @@ class PdfiumEngine {
      * @private
      */
     readPdfTextAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(annotationPtr);
         const annoRect = this.readPageAnnoRect(annotationPtr);
         const rect = this.convertPageRectToDeviceRect(page, pagePtr, annoRect);
         const author = this.getAnnotString(annotationPtr, 'T');
         const modifiedRaw = this.getAnnotString(annotationPtr, 'M');
-        const modified = this.toIsoDate(modifiedRaw);
+        const modified = models.pdfDateToDate(modifiedRaw);
         const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
         const state = this.getAnnotString(annotationPtr, 'State');
         const stateModel = this.getAnnotString(annotationPtr, 'StateModel');
-        const color = this.resolveAnnotationColor(annotationPtr);
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
         const inReplyToId = this.getInReplyToId(pagePtr, annotationPtr);
-        const popup = !inReplyToId
-            ? this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index)
-            : undefined;
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.TEXT,
             contents,
-            color,
+            ...webAlphaColor,
             rect,
-            popup,
-            appearances,
             inReplyToId,
             author,
             modified,
@@ -2527,16 +2718,13 @@ class PdfiumEngine {
      * @private
      */
     readPdfFreeTextAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(annotationPtr);
         const annoRect = this.readPageAnnoRect(annotationPtr);
         const rect = this.convertPageRectToDeviceRect(page, pagePtr, annoRect);
         const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
         const author = this.getAnnotString(annotationPtr, 'T');
         const modifiedRaw = this.getAnnotString(annotationPtr, 'M');
-        const modified = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.FREETEXT,
@@ -2544,8 +2732,6 @@ class PdfiumEngine {
             author,
             modified,
             rect,
-            popup,
-            appearances,
         };
     }
     /**
@@ -2565,13 +2751,12 @@ class PdfiumEngine {
         if (!linkPtr) {
             return;
         }
-        const appearances = this.readPageAnnoAppearanceStreams(annotationPtr);
         const annoRect = this.readPageAnnoRect(annotationPtr);
         const { left, top, right, bottom } = annoRect;
         const rect = this.convertPageRectToDeviceRect(page, pagePtr, annoRect);
         const author = this.getAnnotString(annotationPtr, 'T');
         const modifiedRaw = this.getAnnotString(annotationPtr, 'M');
-        const modified = this.toIsoDate(modifiedRaw);
+        const modified = models.pdfDateToDate(modifiedRaw);
         const utf16Length = this.pdfiumModule.FPDFText_GetBoundedText(textPagePtr, left, top, right, bottom, 0, 0);
         const bytesCount = (utf16Length + 1) * 2; // include NIL
         const textBufferPtr = this.malloc(bytesCount);
@@ -2583,17 +2768,13 @@ class PdfiumEngine {
         }, () => {
             return this.pdfiumModule.FPDFLink_GetDest(docPtr, linkPtr);
         });
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.LINK,
             text,
             target,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -2610,23 +2791,18 @@ class PdfiumEngine {
      * @private
      */
     readPdfWidgetAnno(page, pagePtr, annotationPtr, formHandle, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         const field = this.readPdfWidgetAnnoField(formHandle, annotationPtr);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.WIDGET,
             rect,
             field,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -2642,21 +2818,16 @@ class PdfiumEngine {
      * @private
      */
     readPdfFileAttachmentAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.FILEATTACHMENT,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -2672,13 +2843,11 @@ class PdfiumEngine {
      * @private
      */
     readPdfInkAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         const inkList = [];
         const count = this.pdfiumModule.FPDFAnnot_GetInkListCount(annotationPtr);
         for (let i = 0; i < count; i++) {
@@ -2702,14 +2871,11 @@ class PdfiumEngine {
             inkList.push({ points });
         }
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.INK,
             rect,
-            popup,
             inkList,
-            appearances,
             author,
             modified,
         };
@@ -2725,23 +2891,18 @@ class PdfiumEngine {
      * @private
      */
     readPdfPolygonAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         const vertices = this.readPdfAnnoVertices(page, pagePtr, annotationPtr);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.POLYGON,
             rect,
-            popup,
             vertices,
-            appearances,
             author,
             modified,
         };
@@ -2757,23 +2918,18 @@ class PdfiumEngine {
      * @private
      */
     readPdfPolylineAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         const vertices = this.readPdfAnnoVertices(page, pagePtr, annotationPtr);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.POLYLINE,
             rect,
-            popup,
             vertices,
-            appearances,
             author,
             modified,
         };
@@ -2789,13 +2945,11 @@ class PdfiumEngine {
      * @private
      */
     readPdfLineAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         const startPointPtr = this.malloc(8);
         const endPointPtr = this.malloc(8);
         this.pdfiumModule.FPDFAnnot_GetLine(annotationPtr, startPointPtr, endPointPtr);
@@ -2814,15 +2968,12 @@ class PdfiumEngine {
         this.free(startPointPtr);
         this.free(endPointPtr);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.LINE,
             rect,
-            popup,
             startPoint,
             endPoint,
-            appearances,
             author,
             modified,
         };
@@ -2838,25 +2989,22 @@ class PdfiumEngine {
      * @private
      */
     readPdfHighlightAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(annotationPtr);
         const pageRect = this.readPageAnnoRect(annotationPtr);
         const rect = this.convertPageRectToDeviceRect(page, pagePtr, pageRect);
-        const quads = this.readAnnotationQuads(page, annotationPtr);
-        const color = this.resolveAnnotationColor(annotationPtr);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const segmentRects = this.getQuadPointsAnno(page, annotationPtr);
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
         const author = this.getAnnotString(annotationPtr, 'T');
         const modifiedRaw = this.getAnnotString(annotationPtr, 'M');
-        const modified = this.toIsoDate(modifiedRaw);
+        const modified = models.pdfDateToDate(modifiedRaw);
+        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.HIGHLIGHT,
             rect,
-            popup,
-            appearances,
-            segmentRects: quads.map(models.quadToRect),
-            color,
+            contents,
+            segmentRects,
+            ...webAlphaColor,
             author,
             modified,
         };
@@ -2872,21 +3020,22 @@ class PdfiumEngine {
      * @private
      */
     readPdfUnderlineAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
+        const segmentRects = this.getQuadPointsAnno(page, annotationPtr);
+        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.UNDERLINE,
             rect,
-            popup,
-            appearances,
+            contents,
+            segmentRects,
+            ...webAlphaColor,
             author,
             modified,
         };
@@ -2902,21 +3051,22 @@ class PdfiumEngine {
      * @private
      */
     readPdfStrikeOutAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
+        const segmentRects = this.getQuadPointsAnno(page, annotationPtr);
+        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.STRIKEOUT,
             rect,
-            popup,
-            appearances,
+            contents,
+            segmentRects,
+            ...webAlphaColor,
             author,
             modified,
         };
@@ -2932,21 +3082,22 @@ class PdfiumEngine {
      * @private
      */
     readPdfSquigglyAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
+        const segmentRects = this.getQuadPointsAnno(page, annotationPtr);
+        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.SQUIGGLY,
             rect,
-            popup,
-            appearances,
+            contents,
+            segmentRects,
+            ...webAlphaColor,
             author,
             modified,
         };
@@ -2962,21 +3113,16 @@ class PdfiumEngine {
      * @private
      */
     readPdfCaretAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.CARET,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -2993,13 +3139,11 @@ class PdfiumEngine {
      * @private
      */
     readPdfStampAnno(docPtr, page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         const contents = [];
         const objectCount = this.pdfiumModule.FPDFAnnot_GetObjectCount(annotationPtr);
         for (let i = 0; i < objectCount; i++) {
@@ -3010,14 +3154,11 @@ class PdfiumEngine {
             }
         }
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.STAMP,
             rect,
-            popup,
             contents,
-            appearances,
             author,
             modified,
         };
@@ -3197,21 +3338,16 @@ class PdfiumEngine {
      * @private
      */
     readPdfCircleAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.CIRCLE,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -3227,21 +3363,16 @@ class PdfiumEngine {
      * @private
      */
     readPdfSquareAnno(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: models.PdfAnnotationSubtype.SQUARE,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -3258,21 +3389,16 @@ class PdfiumEngine {
      * @private
      */
     readPdfAnno(page, pagePtr, type, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(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 = this.toIsoDate(modifiedRaw);
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
+        const modified = models.pdfDateToDate(modifiedRaw);
         return {
-            status: models.PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -3294,25 +3420,6 @@ class PdfiumEngine {
         const idx = this.pdfiumModule.FPDFPage_GetAnnotIndex(pagePtr, parentPtr);
         return idx >= 0 ? idx : undefined;
     }
-    /**
-     * Parse a PDF date string **D:YYYYMMDDHHmmSSOHH'mm'** to ISO-8601.
-     *
-     * Returns `undefined` if the input is malformed.
-     *
-     * @private
-     */
-    toIsoDate(pdfDate) {
-        if (!pdfDate?.startsWith('D:'))
-            return;
-        // Minimal parse – ignore timezone for brevity
-        const y = pdfDate.substring(2, 6);
-        const m = pdfDate.substring(6, 8) || '01';
-        const d = pdfDate.substring(8, 10) || '01';
-        const H = pdfDate.substring(10, 12) || '00';
-        const M = pdfDate.substring(12, 14) || '00';
-        const S = pdfDate.substring(14, 16) || '00';
-        return `${y}-${m}-${d}T${H}:${M}:${S}`;
-    }
     /**
      * Fetch a string value (`/T`, `/M`, `/State`, …) from an annotation.
      *
@@ -3332,41 +3439,19 @@ class PdfiumEngine {
         return value || undefined;
     }
     /**
-     * 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
      */
-    readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index) {
-        const appearances = this.readPageAnnoAppearanceStreams(annotationPtr);
-        const popupAnnotationPtr = this.pdfiumModule.FPDFAnnot_GetLinkedAnnot(annotationPtr, 'Popup');
-        if (!popupAnnotationPtr) {
-            return;
-        }
-        const pageRect = this.readPageAnnoRect(popupAnnotationPtr);
-        const rect = this.convertPageRectToDeviceRect(page, pagePtr, pageRect);
-        const author = this.getAnnotString(annotationPtr, 'T');
-        const modifiedRaw = this.getAnnotString(annotationPtr, 'M');
-        const modified = this.toIsoDate(modifiedRaw);
-        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
-        const open = this.getAnnotString(annotationPtr, 'Open') || 'false';
-        this.pdfiumModule.FPDFPage_CloseAnnot(popupAnnotationPtr);
-        return {
-            status: models.PdfAnnotationObjectStatus.Committed,
-            pageIndex: page.index,
-            id: index,
-            type: models.PdfAnnotationSubtype.POPUP,
-            rect,
-            contents,
-            open: open === 'true',
-            appearances,
-            author,
-            modified,
-        };
+    setAnnotString(annotationPtr, key, value) {
+        const bytes = 2 * (value.length + 1);
+        const ptr = this.malloc(bytes);
+        this.pdfiumModule.pdfium.stringToUTF16(value, ptr, bytes);
+        const ok = this.pdfiumModule.FPDFAnnot_SetStringValue(annotationPtr, key, ptr);
+        this.free(ptr);
+        return ok;
     }
     /**
      * Read vertices of pdf annotation
@@ -3807,6 +3892,69 @@ class PdfiumEngine {
         this.free(bufferPtr);
         return ap;
     }
+    /**
+     * 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, page, annotation, color, which = 0) {
+        this.logger.debug(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor', doc, page, annotation, color, which);
+        this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor', 'Begin', doc.id);
+        const task = models.PdfTaskHelper.create();
+        try {
+            /* 1 ── sanity & native handles ────────────────────────────────────────── */
+            const ctx = this.cache.getContext(doc.id);
+            if (!ctx) {
+                this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor', 'End', doc.id);
+                this.logger.warn(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor: doc closed');
+                task.resolve(false);
+                return task;
+            }
+            const pageCtx = ctx.acquirePage(page.index);
+            const annotPtr = this.pdfiumModule.FPDFPage_GetAnnot(pageCtx.pagePtr, annotation.id);
+            if (!annotPtr) {
+                this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor', 'End', doc.id);
+                this.logger.warn(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor: annot not found');
+                pageCtx.release();
+                task.resolve(false);
+                return task;
+            }
+            /* 2 ── wipe AP if it's a simple markup annotation ─────────────────────── */
+            const shouldClearAP = annotation.type === models.PdfAnnotationSubtype.HIGHLIGHT ||
+                annotation.type === models.PdfAnnotationSubtype.UNDERLINE ||
+                annotation.type === models.PdfAnnotationSubtype.STRIKEOUT ||
+                annotation.type === models.PdfAnnotationSubtype.SQUIGGLY;
+            const ok = this.setAnnotationColor(annotPtr, color, shouldClearAP, which);
+            /* 4 ── regenerate appearance & clean-up ───────────────────────────────── */
+            if (ok) {
+                this.pdfiumModule.FPDFPage_GenerateContent(pageCtx.pagePtr);
+            }
+            this.pdfiumModule.FPDFPage_CloseAnnot(annotPtr);
+            pageCtx.release();
+            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor', 'End', doc.id);
+            task.resolve(!!ok);
+        }
+        catch (error) {
+            this.logger.perf(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor', 'End', doc.id);
+            this.logger.error(LOG_SOURCE$1, LOG_CATEGORY$1, 'setAnnotationColor: error', error);
+            task.reject({
+                code: models.PdfErrorCode.Unknown,
+                message: `Failed to set annotation color: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+        return task;
+    }
     /**
      * Set the rect of specified annotation
      * @param page - page info that the annotation is belonged to
@@ -4142,7 +4290,7 @@ class EngineRunner {
                     type: 'reject',
                     reason: {
                         code: models.PdfErrorCode.NotSupport,
-                        message: 'engine method has not supported yet',
+                        message: `engine method ${name} is not supported yet`,
                     },
                 };
                 const response = {
@@ -4209,12 +4357,18 @@ class EngineRunner {
                 case 'createPageAnnotation':
                     task = this.engine[name](...args);
                     break;
+                case 'updatePageAnnotation':
+                    task = this.engine[name](...args);
+                    break;
                 case 'transformPageAnnotation':
                     task = this.engine[name](...args);
                     break;
                 case 'removePageAnnotation':
                     task = this.engine[name](...args);
                     break;
+                case 'updateAnnotationColor':
+                    task = this.engine[name](...args);
+                    break;
                 case 'getPageTextRects':
                     task = this.engine[name](...args);
                     break;