@embedpdf/plugin-annotation 2.8.0 → 2.9.0

package/dist/lib/geometry/cloudy-border.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Cloudy border path generator for PDF annotations.
+ *
+ * Framework-agnostic utility that generates SVG path `d` strings for cloudy
+ * (scalloped) borders on Rectangle, Ellipse, and Polygon shapes.
+ *
+ * Derived from Apache PDFBox's CloudyBorder.java:
+ * https://github.com/apache/pdfbox/blob/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/interactive/annotation/handlers/CloudyBorder.java
+ *
+ * Original code licensed under the Apache License, Version 2.0:
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Substantially modified: ported from Java to TypeScript, adapted for SVG
+ * path output, and reworked curl distribution and merging logic.
+ *
+ * Copyright (c) 2026 CloudPDF / EmbedPDF
+ *
+ * @module
+ */
+interface BBox {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/** Rect differences (inset from annotation Rect to drawn shape). */
+export interface RectDifferences {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface CloudyPathResult {
+    /** SVG path `d` attribute string */
+    path: string;
+    /** Bounding box of the generated cloudy border (in annotation-local coords) */
+    bbox: BBox;
+}
+/**
+ * Returns the per-side outward extent of a cloudy border (how far the
+ * scallop peaks + stroke extend beyond the inner shape boundary).
+ *
+ * Use this to compute `rectangleDifferences` for Square/Circle or the
+ * padding for Polygon Rect computation.
+ */
+export declare function getCloudyBorderExtent(intensity: number, lineWidth: number, isEllipse: boolean): number;
+/**
+ * Generates a cloudy border SVG path for a rectangle (Square annotation).
+ *
+ * @param rect - The annotation rect `{ x, y, width, height }` (top-left origin)
+ * @param rd - Rectangle differences (inset), or undefined
+ * @param intensity - Cloudy border intensity (typically 1 or 2)
+ * @param lineWidth - Stroke width of the annotation border
+ */
+export declare function generateCloudyRectanglePath(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, rd: RectDifferences | undefined, intensity: number, lineWidth: number): CloudyPathResult;
+/**
+ * Generates a cloudy border SVG path for an ellipse (Circle annotation).
+ *
+ * @param rect - The annotation rect `{ x, y, width, height }` (top-left origin)
+ * @param rd - Rectangle differences (inset), or undefined
+ * @param intensity - Cloudy border intensity (typically 1 or 2)
+ * @param lineWidth - Stroke width of the annotation border
+ */
+export declare function generateCloudyEllipsePath(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, rd: RectDifferences | undefined, intensity: number, lineWidth: number): CloudyPathResult;
+/**
+ * Generates a cloudy border SVG path for a polygon.
+ *
+ * @param vertices - The polygon vertices in annotation-local coordinates
+ * @param rectOrigin - The annotation rect origin `{ x, y }` for coordinate translation
+ * @param intensity - Cloudy border intensity (typically 1 or 2)
+ * @param lineWidth - Stroke width of the annotation border
+ */
+export declare function generateCloudyPolygonPath(vertices: ReadonlyArray<{
+    x: number;
+    y: number;
+}>, rectOrigin: {
+    x: number;
+    y: number;
+}, intensity: number, lineWidth: number): CloudyPathResult;
+export {};

package/dist/lib/geometry/index.d.ts

@@ -1 +1,2 @@
 export * from './rotation';
+export * from './cloudy-border';

package/dist/lib/handlers/types.d.ts

@@ -1,5 +1,5 @@
 import { PointerEventHandlersWithLifecycle } from '@embedpdf/plugin-interaction-manager';
-import { PdfAnnotationObject, PdfAnnotationSubtype, Rect, Rotation, Size, AnnotationCreateContext, PdfAnnotationBorderStyle, Position, LineEndings, PdfInkListObject, PdfStandardFont, PdfTextAlignment, PdfVerticalAlignment } from '@embedpdf/models';
+import { PdfAnnotationObject, PdfAnnotationSubtype, Rect, Rotation, Size, AnnotationCreateContext, PdfAnnotationBorderStyle, Position, LineEndings, PdfInkListObject, PdfStandardFont, PdfTextAlignment, PdfVerticalAlignment, PdfBlendMode } from '@embedpdf/models';
 import { FormattedSelection } from '@embedpdf/plugin-selection';
 import { AnnotationTool } from '../tools/types';
 export interface CirclePreviewData {
@@ -54,6 +54,7 @@ export interface InkPreviewData {
     strokeWidth: number;
     strokeColor: string;
     opacity: number;
+    blendMode?: PdfBlendMode;
 }
 export interface FreeTextPreviewData {
     rect: Rect;

package/dist/lib/tools/default-tools.d.ts

@@ -1,8 +1,33 @@
 import { PdfAnnotationBorderStyle, PdfAnnotationLineEnding, PdfAnnotationSubtype, PdfBlendMode, PdfStandardFont, PdfTextAlignment, PdfVerticalAlignment } from '@embedpdf/models';
 export declare const defaultTools: ({
+    id: string;
+    name: string;
+    matchScore: (annotation: import('@embedpdf/models').PdfAnnotationObject) => number;
+    defaults: Partial<import('@embedpdf/models').PdfInkAnnoObject>;
+    interaction: {
+        mode?: string;
+        exclusive: boolean;
+        cursor?: string;
+        textSelection?: boolean;
+        showSelectionRects?: boolean;
+        isDraggable?: import('./types').DynamicBooleanProp;
+        isResizable?: import('./types').DynamicBooleanProp;
+        isRotatable?: import('./types').DynamicBooleanProp;
+        lockAspectRatio?: import('./types').DynamicBooleanProp;
+        lockGroupAspectRatio?: import('./types').DynamicBooleanProp;
+        isGroupDraggable?: import('./types').DynamicBooleanProp;
+        isGroupResizable?: import('./types').DynamicBooleanProp;
+        isGroupRotatable?: import('./types').DynamicBooleanProp;
+    };
+    behavior?: ({
+        deactivateToolAfterCreate?: boolean;
+        selectAfterCreate?: boolean;
+        useAppearanceStream?: boolean;
+    } & import('./types').InkBehavior) | undefined;
+} | {
     id: "highlight";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         textSelection: true;
@@ -39,7 +64,7 @@ export declare const defaultTools: ({
 } | {
     id: "underline";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         textSelection: true;
@@ -76,7 +101,7 @@ export declare const defaultTools: ({
 } | {
     id: "strikeout";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         textSelection: true;
@@ -113,7 +138,7 @@ export declare const defaultTools: ({
 } | {
     id: "squiggly";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         textSelection: true;
@@ -150,7 +175,7 @@ export declare const defaultTools: ({
 } | {
     id: "insertText";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0 | 2;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1 | 2;
     interaction: {
         exclusive: false;
         textSelection: true;
@@ -221,84 +246,10 @@ export declare const defaultTools: ({
     };
     clickBehavior?: undefined;
     behavior?: undefined;
-} | {
-    id: "ink";
-    name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 5;
-    interaction: {
-        exclusive: false;
-        cursor: string;
-        isDraggable: true;
-        isResizable: true;
-        lockAspectRatio: false;
-        textSelection?: undefined;
-        isRotatable?: undefined;
-        isGroupDraggable?: undefined;
-        isGroupResizable?: undefined;
-        showSelectionRects?: undefined;
-        lockGroupAspectRatio?: undefined;
-    };
-    defaults: {
-        type: PdfAnnotationSubtype.INK;
-        strokeColor: string;
-        color: string;
-        opacity: number;
-        strokeWidth: number;
-        blendMode?: undefined;
-        intent?: undefined;
-        strokeStyle?: undefined;
-        lineEndings?: undefined;
-        contents?: undefined;
-        fontSize?: undefined;
-        fontColor?: undefined;
-        fontFamily?: undefined;
-        textAlign?: undefined;
-        verticalAlign?: undefined;
-        backgroundColor?: undefined;
-    };
-    clickBehavior?: undefined;
-    behavior?: undefined;
-} | {
-    id: "inkHighlighter";
-    name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 10;
-    interaction: {
-        exclusive: false;
-        cursor: string;
-        isDraggable: true;
-        isResizable: true;
-        lockAspectRatio: false;
-        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
-        textSelection?: undefined;
-        isRotatable?: undefined;
-        isGroupDraggable?: undefined;
-        isGroupResizable?: undefined;
-        showSelectionRects?: undefined;
-    };
-    defaults: {
-        type: PdfAnnotationSubtype.INK;
-        intent: string;
-        strokeColor: string;
-        color: string;
-        opacity: number;
-        strokeWidth: number;
-        blendMode: PdfBlendMode.Multiply;
-        strokeStyle?: undefined;
-        lineEndings?: undefined;
-        contents?: undefined;
-        fontSize?: undefined;
-        fontColor?: undefined;
-        fontFamily?: undefined;
-        textAlign?: undefined;
-        verticalAlign?: undefined;
-        backgroundColor?: undefined;
-    };
-    clickBehavior?: undefined;
-    behavior?: undefined;
 } | {
     id: "circle";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         cursor: string;
@@ -344,7 +295,7 @@ export declare const defaultTools: ({
 } | {
     id: "square";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         cursor: string;
@@ -390,7 +341,7 @@ export declare const defaultTools: ({
 } | {
     id: "line";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 5;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 5 | 0;
     interaction: {
         exclusive: false;
         cursor: string;
@@ -479,7 +430,7 @@ export declare const defaultTools: ({
 } | {
     id: "polyline";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         cursor: string;
@@ -516,7 +467,7 @@ export declare const defaultTools: ({
 } | {
     id: "polygon";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         cursor: string;
@@ -553,7 +504,7 @@ export declare const defaultTools: ({
 } | {
     id: "textComment";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         cursor: string;
@@ -594,7 +545,7 @@ export declare const defaultTools: ({
 } | {
     id: "freeText";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         cursor: string;
@@ -644,7 +595,7 @@ export declare const defaultTools: ({
 } | {
     id: "stamp";
     name: string;
-    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
     interaction: {
         exclusive: false;
         cursor: string;

package/dist/lib/tools/types.d.ts

@@ -83,6 +83,37 @@ type InsertUprightBehaviorFor<T extends PdfAnnotationObject> = Extract<T['type']
     /** Counter-rotate new annotations to appear visually upright on rotated pages. */
     insertUpright?: boolean;
 };
+/**
+ * Ink-specific behavior settings. Only available on tools whose annotation
+ * type is PdfAnnotationSubtype.INK (i.e. 'ink' and 'inkHighlighter').
+ */
+export interface InkBehavior {
+    /** ms of pointer inactivity before the accumulated strokes are committed. Default: 800. */
+    commitDelay?: number;
+    /** When true, line-like strokes are snapped to a clean 2-point straight line on pointerUp. */
+    smartLineRecognition?: boolean;
+    /**
+     * Maximum allowed perpendicular-deviation ratio (maxDeviation / strokeLength) for a stroke
+     * to qualify as a straight line. Lower = stricter. Default: 0.15.
+     */
+    smartLineThreshold?: number;
+    /**
+     * How many degrees from horizontal or vertical a recognised straight line may deviate
+     * before axis-snapping is skipped. Default: 15.
+     */
+    snapAngleDeg?: number;
+}
+/**
+ * Non-distributive conditional: wrapping both sides in [...] prevents TypeScript from
+ * distributing over a union. [PdfAnnotationObject] extends [PdfInkAnnoObject] is false
+ * (the full union is not a subtype of the specific ink type), so InkBehavior is only added
+ * when T is specifically the INK annotation type.
+ */
+type InkBehaviorFor<T extends PdfAnnotationObject> = [T] extends [
+    Extract<PdfAnnotationObject, {
+        type: PdfAnnotationSubtype.INK;
+    }>
+] ? InkBehavior : {};
 /**
  * The primary interface for defining an annotation tool.
  * Uses a type alias to properly combine the base interface with conditional properties.
@@ -136,6 +167,6 @@ export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject>
         selectAfterCreate?: boolean;
         /** Override whether this annotation type uses AP rendering before editing (default: true) */
         useAppearanceStream?: boolean;
-    } & InsertUprightBehaviorFor<T>;
+    } & InsertUprightBehaviorFor<T> & InkBehaviorFor<T>;
 } & ClickBehaviorFor<T>;
 export {};