Merge pull request #638 from embedpdf/fix/normalise-cloudy-border

Normalise `PdfAnnotationBorderStyle.CLOUDY` to `SOLID`

Author: bobsingor

.changeset/engine-cloudy-polygon-api-fix.md

@@ -0,0 +1,10 @@
+---
+'@embedpdf/engines': patch
+---
+
+Fix two bugs that caused polygon (and square/circle) annotations created via the `createAnnotation` API with `strokeStyle: PdfAnnotationBorderStyle.CLOUDY` to be saved as a half-built stub missing `/C`, `/IC`, `/CA`, `/F`, `/BE`, `/RD`, and `/AP`:
+
+- Normalise `PdfAnnotationBorderStyle.CLOUDY` to `SOLID` inside `setBorderStyle` before calling PDFium's `EPDFAnnot_SetBorderStyle`. Cloudy is not a `/BS/S` value — it is conveyed via the separate `/BE` (border effect) dict, which `setBorderEffect` already writes. PDFium previously rejected the call and aborted the rest of `addPolyContent` / `addShapeContent`, so the cloudy effect, colors, opacity, flags, and appearance stream were never written.
+- Fix the rollback path in `createPageAnnotation` so failed content-add calls actually remove the partially-built annotation. The previous code called `FPDFPage_RemoveAnnot(pagePtr, annotationPtr)`, but PDFium's C signature is `FPDFPage_RemoveAnnot(FPDF_PAGE, int index)` — the annotation pointer was interpreted as an out-of-range index and silently no-op'd, leaving the stub annotation in the page. It now uses `removeAnnotationByName` (via `EPDFPage_RemoveAnnotByName`) and closes the annotation handle.
+
+The `PdfAnnotationBorderStyle.CLOUDY` enum value is now treated as a deprecated alias for `SOLID + cloudyBorderIntensity` and is slated for removal in the next major release.

.changeset/pdfium-callout-transparent-background.md

@@ -0,0 +1,7 @@
+---
+'@embedpdf/pdfium': patch
+---
+
+Fix callout FreeText annotations rendering with a black background when the fill color is transparent.
+
+In `GenerateFreeTextAP`'s callout branch, the text-box rectangle was painted unconditionally with operator `B` (fill + stroke). When `/C` was absent, no fill colour was emitted, so `B` fell back to PDF's default black fill. Now the fill defaults to transparent via `GetColorStringWithDefault` and the paint operator is picked dynamically with `GetPaintOperatorString`, mirroring `GenerateCircleAP` / `GenerateSquareAP`.

.changeset/snippet-annotation-type-reexports.md

@@ -0,0 +1,15 @@
+---
+'@embedpdf/snippet': patch
+---
+
+Re-export the annotation API surface from `@embedpdf/models` through the snippet bundle so consumers can use named enums and typed annotation shapes instead of hardcoding numeric subtype/border-style values.
+
+Newly exported from `@embedpdf/snippet`:
+
+- Enums: `PdfAnnotationBorderStyle`, `PdfAnnotationLineEnding`, `PdfAnnotationFlags`, `PdfAnnotationName`, `PdfAnnotationIcon`, `PdfAnnotationState`, `PdfAnnotationStateModel`, `PdfAnnotationReplyType`, `PdfAnnotationObjectStatus`, `PdfBlendMode`, `PdfStampFit`, `AppearanceMode`.
+- Annotation flag helpers: `PdfAnnotationFlagName`, `flagsToNames`, `namesToFlags`.
+- Annotation object types: `PdfAnnotationObjectBase`, `PdfAnnotationObject`, `PdfSupportedAnnoObject`, `PdfUnsupportedAnnoObject`, `PdfTextAnnoObject`, `PdfLinkAnnoObject`, `PdfFreeTextAnnoObject`, `PdfLineAnnoObject`, `PdfSquareAnnoObject`, `PdfCircleAnnoObject`, `PdfPolygonAnnoObject`, `PdfPolylineAnnoObject`, `PdfHighlightAnnoObject`, `PdfUnderlineAnnoObject`, `PdfSquigglyAnnoObject`, `PdfStrikeOutAnnoObject`, `PdfCaretAnnoObject`, `PdfInkAnnoObject`, `PdfInkListObject`, `PdfPopupAnnoObject`, `PdfFileAttachmentAnnoObject`, `PdfWidgetAnnoObject`, `PdfRedactAnnoObject`, `PdfRectDifferences`, `LinePoints`, `LineEndings`, `PdfAnnotationOf`.
+- Create-context types: `AnnotationCreateContext`, `AnnotationContextMap`.
+- Geometry / color: `Position`, `Size`, `Rect`, `WebColor`.
+
+`PdfAnnotationSubtype` and `PdfStampAnnoObject` were already exported and continue to work unchanged.

.changeset/snippet-brazilian-portuguese-locale.md

@@ -0,0 +1,9 @@
+---
+'@embedpdf/snippet': patch
+---
+
+Add Brazilian Portuguese (`pt-BR`) as a built-in locale of the snippet viewer.
+
+- New `brazilianPortugueseTranslations` export from `@embedpdf/snippet`, covering the full translation schema so users see localised strings everywhere (search panel, password prompt, document-error dialog, outline, comments, blend-mode picker, link dialog, full protect/security flows, signature flow, etc.) — no English fallback noise.
+- Registered in the default `i18n.locales` array alongside the existing nine locales, so the viewer's language picker now lists "Português (Brasil)" out of the box.
+- The wide-label responsive override that used to be German/Dutch-only now also applies to `pt-BR`, because words like "Visualizar" (10) and "Formulário" (10) are as wide as German labels and would otherwise overflow the toolbar at the `md` breakpoint. The override group id was renamed from `germanic-languages` to `wide-label-languages` to reflect the broader scope; behaviour for `de`/`nl` is unchanged.

packages/engines/src/lib/pdfium/engine.ts

@@ -1408,7 +1408,13 @@ export class PdfiumNative implements IPdfiumExecutor {
     }
 
     if (!isSucceed) {
-      this.pdfiumModule.FPDFPage_RemoveAnnot(pageCtx.pagePtr, annotationPtr);
+      // FPDFPage_RemoveAnnot's C signature is (FPDF_PAGE, int index), not
+      // (FPDF_PAGE, FPDF_ANNOTATION). Passing the annotation pointer here is
+      // interpreted as an out-of-range index and silently no-ops, leaving the
+      // half-built annotation in the page. Use the name-based remover instead,
+      // which matches how /NM was set above.
+      this.removeAnnotationByName(pageCtx.pagePtr, annotation.id);
+      this.pdfiumModule.FPDFPage_CloseAnnot(annotationPtr);
       pageCtx.release();
       this.logger.perf(
         LOG_SOURCE,
@@ -6410,7 +6416,20 @@ export class PdfiumNative implements IPdfiumExecutor {
     style: PdfAnnotationBorderStyle,
     width: number,
   ): boolean {
-    return this.pdfiumModule.EPDFAnnot_SetBorderStyle(annotationPtr, style, width);
+    // PDFium's EPDFAnnot_SetBorderStyle (and the PDF spec) only accept the
+    // /BS /S names S/D/B/I/U. CLOUDY isn't a /BS/S value — it's conveyed via
+    // the separate /BE (border effect) dict, which setBorderEffect() writes
+    // later for polygon/square/circle. Normalise CLOUDY to SOLID here so a
+    // caller passing strokeStyle: CLOUDY (sponsor API convention) doesn't
+    // make PDFium reject the call and abort the rest of the save.
+    //
+    // TODO(next-major): remove the PdfAnnotationBorderStyle.CLOUDY enum value
+    // entirely. Cloudy is not a border-style; callers should use
+    // strokeStyle: SOLID + cloudyBorderIntensity: N. Once the enum value is
+    // gone, this normalisation can be deleted.
+    const effectiveStyle =
+      style === PdfAnnotationBorderStyle.CLOUDY ? PdfAnnotationBorderStyle.SOLID : style;
+    return this.pdfiumModule.EPDFAnnot_SetBorderStyle(annotationPtr, effectiveStyle, width);
   }
 
   /**