@embedpdf/engines 1.0.5 → 1.0.7

package/dist/pdfium-direct-engine.js

@@ -1,5 +1,5 @@
-import { NoopLogger, PdfTaskHelper, PdfErrorCode, Task, Rotation, PdfAnnotationSubtype, PdfPageObjectType, PdfAnnotationObjectStatus, quadToRect, PDF_FORM_FIELD_TYPE, toIntRect, transformRect, toIntSize, transformSize, PdfActionType, PdfZoomMode, AppearanceMode, MatchFlag } from '@embedpdf/models';
 import { init } from '@embedpdf/pdfium';
+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';
 
 /**
  * Read string from WASM heap
@@ -915,6 +915,12 @@ class PdfiumEngine {
             case PdfAnnotationSubtype.STAMP:
                 isSucceed = this.addStampContent(ctx.docPtr, page, pageCtx.pagePtr, annotationPtr, annotation.rect, annotation.contents);
                 break;
+            case PdfAnnotationSubtype.UNDERLINE:
+            case PdfAnnotationSubtype.STRIKEOUT:
+            case PdfAnnotationSubtype.SQUIGGLY:
+            case PdfAnnotationSubtype.HIGHLIGHT:
+                isSucceed = this.addTextMarkupContent(page, annotationPtr, annotation);
+                break;
         }
         if (!isSucceed) {
             this.pdfiumModule.FPDFPage_RemoveAnnot(pageCtx.pagePtr, annotationPtr);
@@ -926,10 +932,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, LOG_CATEGORY, `CreatePageAnnotation`, 'End', `${doc.id}-${page.index}`);
-        return PdfTaskHelper.resolve(true);
+        return annotId >= 0
+            ? PdfTaskHelper.resolve(annotId)
+            : PdfTaskHelper.reject({
+                code: 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, LOG_CATEGORY, 'updatePageAnnotation', doc, page, annotation);
+        this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'UpdatePageAnnotation', 'Begin', `${doc.id}-${page.index}`);
+        const ctx = this.cache.getContext(doc.id);
+        if (!ctx) {
+            this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'UpdatePageAnnotation', 'End', `${doc.id}-${page.index}`);
+            return PdfTaskHelper.reject({
+                code: 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, LOG_CATEGORY, 'UpdatePageAnnotation', 'End', `${doc.id}-${page.index}`);
+            return PdfTaskHelper.reject({ code: 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, LOG_CATEGORY, 'UpdatePageAnnotation', 'End', `${doc.id}-${page.index}`);
+            return PdfTaskHelper.reject({
+                code: PdfErrorCode.CantSetAnnotRect,
+                message: 'failed to move annotation',
+            });
+        }
+        /* 2 ── wipe previous payload and rebuild fresh one ─────────────────────── */
+        let ok = false;
+        switch (annotation.type) {
+            /* ── Ink ─────────────────────────────────────────────────────────────── */
+            case 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 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 PdfAnnotationSubtype.HIGHLIGHT:
+            case PdfAnnotationSubtype.UNDERLINE:
+            case PdfAnnotationSubtype.STRIKEOUT:
+            case 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, LOG_CATEGORY, 'UpdatePageAnnotation', 'End', `${doc.id}-${page.index}`);
+        return ok
+            ? PdfTaskHelper.resolve(true)
+            : PdfTaskHelper.reject({
+                code: PdfErrorCode.CantSetAnnotContent,
+                message: 'failed to update annotation',
+            });
     }
     /**
      * {@inheritDoc @embedpdf/models!PdfEngine.transformPageAnnotation}
@@ -1362,6 +1459,62 @@ class PdfiumEngine {
         this.logger.perf(LOG_SOURCE, LOG_CATEGORY, `ExtractText`, 'End', doc.id);
         return PdfTaskHelper.resolve(text);
     }
+    /**
+     * {@inheritDoc @embedpdf/models!PdfEngine.getTextSlices}
+     *
+     * @public
+     */
+    getTextSlices(doc, slices) {
+        this.logger.debug(LOG_SOURCE, LOG_CATEGORY, 'getTextSlices', doc, slices);
+        this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'GetTextSlices', 'Begin', doc.id);
+        /* ⚠︎ 1 — trivial case */
+        if (slices.length === 0) {
+            this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'GetTextSlices', 'End', doc.id);
+            return PdfTaskHelper.resolve([]);
+        }
+        /* ⚠︎ 2 — document must be open */
+        const ctx = this.cache.getContext(doc.id);
+        if (!ctx) {
+            this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'GetTextSlices', 'End', doc.id);
+            return PdfTaskHelper.reject({
+                code: PdfErrorCode.DocNotOpen,
+                message: 'document does not open',
+            });
+        }
+        try {
+            /* keep caller order */
+            const out = new Array(slices.length);
+            /* group → open each page once */
+            const byPage = new Map();
+            slices.forEach((s, i) => {
+                (byPage.get(s.pageIndex) ?? byPage.set(s.pageIndex, []).get(s.pageIndex)).push({
+                    slice: s,
+                    pos: i,
+                });
+            });
+            for (const [pageIdx, list] of byPage) {
+                const pageCtx = ctx.acquirePage(pageIdx);
+                const textPagePtr = pageCtx.getTextPage();
+                for (const { slice, pos } of list) {
+                    const bufPtr = this.malloc(2 * (slice.charCount + 1)); // UTF-16 + NIL
+                    this.pdfiumModule.FPDFText_GetText(textPagePtr, slice.charIndex, slice.charCount, bufPtr);
+                    out[pos] = stripPdfUnwantedMarkers(this.pdfiumModule.pdfium.UTF16ToString(bufPtr));
+                    this.free(bufPtr);
+                }
+                pageCtx.release();
+            }
+            this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'GetTextSlices', 'End', doc.id);
+            return PdfTaskHelper.resolve(out);
+        }
+        catch (e) {
+            this.logger.error(LOG_SOURCE, LOG_CATEGORY, 'getTextSlices error', e);
+            this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'GetTextSlices', 'End', doc.id);
+            return PdfTaskHelper.reject({
+                code: PdfErrorCode.Unknown,
+                message: String(e),
+            });
+        }
+    }
     /**
      * {@inheritDoc @embedpdf/models!PdfEngine.merge}
      *
@@ -1592,6 +1745,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', 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
@@ -1891,14 +2074,12 @@ class PdfiumEngine {
         const runs = [];
         let current = null;
         let curObjPtr = null;
+        let bounds = null;
         /** ── main loop ──────────────────────────────────────────── */
         for (let i = 0; i < glyphs.length; i++) {
             const g = glyphs[i];
             /* 1 — find the CPDF_TextObject this glyph belongs to */
             const objPtr = this.pdfiumModule.FPDFText_GetTextObject(textPagePtr, i);
-            if (g.isEmpty) {
-                continue;
-            }
             /* 2 — start a new run when the text object changes */
             if (objPtr !== curObjPtr) {
                 curObjPtr = objPtr;
@@ -1912,6 +2093,12 @@ class PdfiumEngine {
                     charStart: i,
                     glyphs: [],
                 };
+                bounds = {
+                    minX: g.origin.x,
+                    minY: g.origin.y,
+                    maxX: g.origin.x + g.size.width,
+                    maxY: g.origin.y + g.size.height,
+                };
                 runs.push(current);
             }
             /* 3 — append the slim glyph record */
@@ -1920,16 +2107,24 @@ class PdfiumEngine {
                 y: g.origin.y,
                 width: g.size.width,
                 height: g.size.height,
-                flags: g.isSpace ? 1 : 0,
+                flags: g.isEmpty ? 2 : g.isSpace ? 1 : 0,
             });
             /* 4 — expand the run's bounding rect */
+            if (g.isEmpty) {
+                continue;
+            }
             const right = g.origin.x + g.size.width;
             const bottom = g.origin.y + g.size.height;
-            current.rect.width =
-                Math.max(current.rect.x + current.rect.width, right) - current.rect.x;
-            current.rect.y = Math.min(current.rect.y, g.origin.y);
-            current.rect.height =
-                Math.max(current.rect.y + current.rect.height, bottom) - current.rect.y;
+            // Update bounds
+            bounds.minX = Math.min(bounds.minX, g.origin.x);
+            bounds.minY = Math.min(bounds.minY, g.origin.y);
+            bounds.maxX = Math.max(bounds.maxX, right);
+            bounds.maxY = Math.max(bounds.maxY, bottom);
+            // Calculate final rect from bounds
+            current.rect.x = bounds.minX;
+            current.rect.y = bounds.minY;
+            current.rect.width = bounds.maxX - bounds.minX;
+            current.rect.height = bounds.maxY - bounds.minY;
         }
         return runs;
     }
@@ -2202,8 +2397,6 @@ class PdfiumEngine {
                     annotation = this.readPdfCaretAnno(page, pageCtx.pagePtr, annotationPtr, index);
                 }
                 break;
-            case PdfAnnotationSubtype.POPUP:
-                break;
             default:
                 {
                     annotation = this.readPdfAnno(page, pageCtx.pagePtr, subType, annotationPtr, index);
@@ -2350,15 +2543,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 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 = webAlphaColorToPdfAlphaColor(webAlphaColor);
+        if (shouldClearAP) {
+            // NULL wide-string → remove the /AP entry
+            this.pdfiumModule.FPDFAnnot_SetAP(annotationPtr, 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
@@ -2371,11 +2584,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 [];
@@ -2402,7 +2615,60 @@ class PdfiumEngine {
             }
             this.free(quadPtr);
         }
-        return quads;
+        return quads.map(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 = 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
@@ -2415,30 +2681,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 = 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: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.TEXT,
             contents,
-            color,
+            ...webAlphaColor,
             rect,
-            popup,
-            appearances,
             inReplyToId,
             author,
             modified,
@@ -2457,16 +2716,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 = pdfDateToDate(modifiedRaw);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.FREETEXT,
@@ -2474,8 +2730,6 @@ class PdfiumEngine {
             author,
             modified,
             rect,
-            popup,
-            appearances,
         };
     }
     /**
@@ -2495,13 +2749,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 = 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);
@@ -2513,17 +2766,13 @@ class PdfiumEngine {
         }, () => {
             return this.pdfiumModule.FPDFLink_GetDest(docPtr, linkPtr);
         });
-        const popup = this.readPdfAnnoLinkedPopup(page, pagePtr, annotationPtr, index);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.LINK,
             text,
             target,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -2540,23 +2789,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 = pdfDateToDate(modifiedRaw);
         const field = this.readPdfWidgetAnnoField(formHandle, annotationPtr);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.WIDGET,
             rect,
             field,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -2572,21 +2816,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 = pdfDateToDate(modifiedRaw);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.FILEATTACHMENT,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -2602,13 +2841,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 = pdfDateToDate(modifiedRaw);
         const inkList = [];
         const count = this.pdfiumModule.FPDFAnnot_GetInkListCount(annotationPtr);
         for (let i = 0; i < count; i++) {
@@ -2632,14 +2869,11 @@ class PdfiumEngine {
             inkList.push({ points });
         }
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.INK,
             rect,
-            popup,
             inkList,
-            appearances,
             author,
             modified,
         };
@@ -2655,23 +2889,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 = pdfDateToDate(modifiedRaw);
         const vertices = this.readPdfAnnoVertices(page, pagePtr, annotationPtr);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.POLYGON,
             rect,
-            popup,
             vertices,
-            appearances,
             author,
             modified,
         };
@@ -2687,23 +2916,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 = pdfDateToDate(modifiedRaw);
         const vertices = this.readPdfAnnoVertices(page, pagePtr, annotationPtr);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.POLYLINE,
             rect,
-            popup,
             vertices,
-            appearances,
             author,
             modified,
         };
@@ -2719,13 +2943,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 = pdfDateToDate(modifiedRaw);
         const startPointPtr = this.malloc(8);
         const endPointPtr = this.malloc(8);
         this.pdfiumModule.FPDFAnnot_GetLine(annotationPtr, startPointPtr, endPointPtr);
@@ -2744,15 +2966,12 @@ class PdfiumEngine {
         this.free(startPointPtr);
         this.free(endPointPtr);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.LINE,
             rect,
-            popup,
             startPoint,
             endPoint,
-            appearances,
             author,
             modified,
         };
@@ -2768,25 +2987,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 = pdfDateToDate(modifiedRaw);
+        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.HIGHLIGHT,
             rect,
-            popup,
-            appearances,
-            segmentRects: quads.map(quadToRect),
-            color,
+            contents,
+            segmentRects,
+            ...webAlphaColor,
             author,
             modified,
         };
@@ -2802,21 +3018,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 = pdfDateToDate(modifiedRaw);
+        const segmentRects = this.getQuadPointsAnno(page, annotationPtr);
+        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.UNDERLINE,
             rect,
-            popup,
-            appearances,
+            contents,
+            segmentRects,
+            ...webAlphaColor,
             author,
             modified,
         };
@@ -2832,21 +3049,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 = pdfDateToDate(modifiedRaw);
+        const segmentRects = this.getQuadPointsAnno(page, annotationPtr);
+        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.STRIKEOUT,
             rect,
-            popup,
-            appearances,
+            contents,
+            segmentRects,
+            ...webAlphaColor,
             author,
             modified,
         };
@@ -2862,21 +3080,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 = pdfDateToDate(modifiedRaw);
+        const segmentRects = this.getQuadPointsAnno(page, annotationPtr);
+        const contents = this.getAnnotString(annotationPtr, 'Contents') || '';
+        const webAlphaColor = this.resolveAnnotationColor(annotationPtr);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.SQUIGGLY,
             rect,
-            popup,
-            appearances,
+            contents,
+            segmentRects,
+            ...webAlphaColor,
             author,
             modified,
         };
@@ -2892,21 +3111,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 = pdfDateToDate(modifiedRaw);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.CARET,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -2923,13 +3137,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 = pdfDateToDate(modifiedRaw);
         const contents = [];
         const objectCount = this.pdfiumModule.FPDFAnnot_GetObjectCount(annotationPtr);
         for (let i = 0; i < objectCount; i++) {
@@ -2940,14 +3152,11 @@ class PdfiumEngine {
             }
         }
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.STAMP,
             rect,
-            popup,
             contents,
-            appearances,
             author,
             modified,
         };
@@ -3127,21 +3336,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 = pdfDateToDate(modifiedRaw);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.CIRCLE,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -3157,21 +3361,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 = pdfDateToDate(modifiedRaw);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type: PdfAnnotationSubtype.SQUARE,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -3188,21 +3387,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 = pdfDateToDate(modifiedRaw);
         return {
-            status: PdfAnnotationObjectStatus.Committed,
             pageIndex: page.index,
             id: index,
             type,
             rect,
-            popup,
-            appearances,
             author,
             modified,
         };
@@ -3224,25 +3418,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.
      *
@@ -3262,41 +3437,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: PdfAnnotationObjectStatus.Committed,
-            pageIndex: page.index,
-            id: index,
-            type: 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
@@ -3737,6 +3890,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, LOG_CATEGORY, 'setAnnotationColor', doc, page, annotation, color, which);
+        this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'setAnnotationColor', 'Begin', doc.id);
+        const task = PdfTaskHelper.create();
+        try {
+            /* 1 ── sanity & native handles ────────────────────────────────────────── */
+            const ctx = this.cache.getContext(doc.id);
+            if (!ctx) {
+                this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'setAnnotationColor', 'End', doc.id);
+                this.logger.warn(LOG_SOURCE, LOG_CATEGORY, '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, LOG_CATEGORY, 'setAnnotationColor', 'End', doc.id);
+                this.logger.warn(LOG_SOURCE, LOG_CATEGORY, '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 === PdfAnnotationSubtype.HIGHLIGHT ||
+                annotation.type === PdfAnnotationSubtype.UNDERLINE ||
+                annotation.type === PdfAnnotationSubtype.STRIKEOUT ||
+                annotation.type === 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, LOG_CATEGORY, 'setAnnotationColor', 'End', doc.id);
+            task.resolve(!!ok);
+        }
+        catch (error) {
+            this.logger.perf(LOG_SOURCE, LOG_CATEGORY, 'setAnnotationColor', 'End', doc.id);
+            this.logger.error(LOG_SOURCE, LOG_CATEGORY, 'setAnnotationColor: error', error);
+            task.reject({
+                code: 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
@@ -4024,11 +4240,11 @@ class PdfiumEngine {
     }
 }
 
-async function createPdfiumEngine(wasmUrl) {
+async function createPdfiumEngine(wasmUrl, logger) {
     const response = await fetch(wasmUrl);
     const wasmBinary = await response.arrayBuffer();
     const wasmModule = await init({ wasmBinary });
-    return new PdfiumEngine(wasmModule);
+    return new PdfiumEngine(wasmModule, logger);
 }
 
 export { createPdfiumEngine };