@embedpdf/plugin-annotation 2.4.1 → 2.6.0

package/dist/lib/annotation-plugin.d.ts

@@ -1,6 +1,6 @@
 import { BasePlugin, PluginRegistry } from '@embedpdf/core';
 import { PdfAnnotationObject, Position, Rect } from '@embedpdf/models';
-import { AnnotationCapability, AnnotationPluginConfig, AnnotationState, UnifiedDragOptions, UnifiedDragState, UnifiedDragEvent, UnifiedResizeOptions, UnifiedResizeState, UnifiedResizeEvent } from './types';
+import { AnnotationCapability, AnnotationPluginConfig, AnnotationState, UnifiedDragOptions, UnifiedDragState, UnifiedDragEvent, UnifiedResizeOptions, UnifiedResizeState, UnifiedResizeEvent, UnifiedRotateOptions, UnifiedRotateState, UnifiedRotateEvent } from './types';
 import { AnnotationAction } from './actions';
 import { AnnotationTool } from './tools/types';
 import { AnyPreviewState, HandlerServices } from './handlers/types';
@@ -25,6 +25,8 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     private readonly unifiedDrag$;
     private readonly unifiedResizeStates;
     private readonly unifiedResize$;
+    private readonly unifiedRotateStates;
+    private readonly unifiedRotate$;
     constructor(id: string, registry: PluginRegistry, config: AnnotationPluginConfig);
     protected onDocumentLoadingStarted(documentId: string): void;
     protected onDocumentLoaded(documentId: string): void;
@@ -59,6 +61,12 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     private purgeAnnotationMethod;
     private selectAnnotation;
     private deselectAnnotation;
+    /**
+     * Derive page activity from the current annotation selection.
+     * Called from onStoreUpdated whenever selectedUids changes,
+     * so ALL selection code paths are covered automatically.
+     */
+    private updateAnnotationSelectionActivity;
     private getSelectedAnnotationsMethod;
     private getSelectedAnnotationIdsMethod;
     private toggleSelectionMethod;
@@ -203,6 +211,21 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
      * Framework components use this for preview updates.
      */
     get onResizeChange(): import('@embedpdf/core').EventHook<UnifiedResizeEvent>;
+    private cloneRect;
+    private translateRect;
+    private normalizeAngle;
+    private normalizeDelta;
+    private buildRotationParticipants;
+    private computeRotatePreviewPatches;
+    startRotation(documentId: string, options: UnifiedRotateOptions): void;
+    updateRotation(documentId: string, cursorAngle: number, rotationDelta?: number): void;
+    commitRotation(documentId: string): void;
+    cancelRotation(documentId: string): void;
+    getRotateState(documentId: string): UnifiedRotateState | null;
+    /**
+     * Subscribe to unified rotation state changes.
+     */
+    get onRotateChange(): import('@embedpdf/core').EventHook<UnifiedRotateEvent>;
     private updateAnnotationsMethod;
     getActiveTool(documentId?: string): AnnotationTool | null;
     setActiveTool(toolId: string | null, documentId?: string): void;
@@ -233,9 +256,4 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
      */
     private releaseCommitLock;
     private commit;
-    /**
-     * Gets the effective behavior setting for a tool, checking tool-specific config first,
-     * then falling back to plugin config.
-     */
-    private getToolBehavior;
 }

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

@@ -0,0 +1 @@
+export * from './rotation';

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

@@ -0,0 +1,32 @@
+import { Rect } from '@embedpdf/models';
+/**
+ * Re-export rotation geometry utilities from @embedpdf/models.
+ *
+ * These functions used to live here but have been promoted to the shared models
+ * package so that both @embedpdf/utils (DragResizeController) and
+ * @embedpdf/plugin-annotation (patches) can import from the same source.
+ *
+ * Existing imports from this module continue to work unchanged.
+ */
+export { rotatePointAround as rotatePointAroundCenter, rotateVertices, getRectCenter, calculateRotatedRectAABBAroundPoint, calculateRotatedRectAABB, inferRotationCenterFromRects, } from '@embedpdf/models';
+/**
+ * Convert an AABB-space rect to unrotated space.
+ *
+ * During group resize the pipeline works in AABB space (axis-aligned bounding
+ * box), but `baseResizeScaling` expects the incoming rect in unrotated space.
+ *
+ * The AABB of a rect rotated by θ around its center is:
+ *   AABB_w = w·|cosθ| + h·|sinθ|
+ *   AABB_h = w·|sinθ| + h·|cosθ|
+ *
+ * This function inverts that system to recover (w, h) from the new AABB size.
+ * Near 45° the system is degenerate (the AABB is always square), so we fall
+ * back to uniform scaling based on the area ratio.
+ *
+ * @param newAABBRect - the proportionally scaled AABB rect from the group resize
+ * @param originalAABBRect - the original AABB rect captured at resize start
+ * @param originalUnrotatedRect - the original unrotated rect captured at resize start
+ * @param rotationDegrees - the annotation's rotation in degrees
+ * @returns the equivalent rect in unrotated space
+ */
+export declare function convertAABBRectToUnrotatedSpace(newAABBRect: Rect, originalAABBRect: Rect, originalUnrotatedRect: Rect, rotationDegrees: number): Rect;

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

@@ -1,5 +1,5 @@
 import { PointerEventHandlersWithLifecycle } from '@embedpdf/plugin-interaction-manager';
-import { PdfAnnotationObject, PdfAnnotationSubtype, Rect, 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 } from '@embedpdf/models';
 import { AnnotationTool } from '../tools/types';
 export interface CirclePreviewData {
     rect: Rect;
@@ -131,6 +131,8 @@ export interface HandlerContext<A extends PdfAnnotationObject> {
     getTool: () => AnnotationTool<A> | undefined;
     pageIndex: number;
     pageSize: Size;
+    /** Effective page rotation (page intrinsic + document rotation), as a quarter-turn value (0-3). */
+    pageRotation: Rotation;
     scale: number;
     services: HandlerServices;
     onPreview: (state: AnyPreviewState | null) => void;

package/dist/lib/index.d.ts

@@ -11,5 +11,6 @@ export * from './helpers';
 export * from './handlers/types';
 export * from './tools/types';
 export * from './tools/tools-utils';
+export * from './geometry';
 export * as patching from './patching';
 export { initialState, initialDocumentState } from './reducer';

package/dist/lib/patching/base-patch.d.ts

@@ -0,0 +1,87 @@
+import { Rect } from '@embedpdf/models';
+import { TransformContext } from './patch-registry';
+/**
+ * Minimal shape required by the shared patch helpers.
+ * All annotation objects satisfy this through PdfAnnotationObject.
+ */
+export interface RotatableAnnotation {
+    rect: Rect;
+    unrotatedRect?: Rect;
+    rotation?: number;
+}
+/**
+ * Shared rotate logic.
+ * Returns the full patch (rect, unrotatedRect, rotation) or `null` when the
+ * context doesn't carry a rotationAngle (in which case the caller should
+ * fall through to `ctx.changes`).
+ */
+export declare function baseRotateChanges(orig: RotatableAnnotation, ctx: TransformContext<any>): Partial<{
+    rect: Rect;
+    unrotatedRect: Rect;
+    rotation: number;
+}> | null;
+/**
+ * Shared property-update rotation logic.
+ * Recomputes rect and unrotatedRect for a new rotation angle, preserving
+ * the annotation's rotation center. Works for all annotation types since
+ * it only touches rect/unrotatedRect/rotation.
+ */
+export declare function basePropertyRotationChanges(orig: RotatableAnnotation, newRotation: number): {
+    rotation: number;
+    rect: Rect;
+    unrotatedRect: Rect;
+};
+/**
+ * Shared move logic: computes dx/dy and translates rect + unrotatedRect.
+ * Callers use the returned `dx`/`dy` to translate their own type-specific
+ * data (vertices, linePoints, inkList, etc.).
+ */
+export declare function baseMoveChanges(orig: RotatableAnnotation, newRect: Rect): {
+    dx: number;
+    dy: number;
+    rects: {
+        rect: Rect;
+        unrotatedRect?: Rect;
+    };
+};
+export interface ResizeScalingResult {
+    /** Horizontal scale factor */
+    scaleX: number;
+    /** Vertical scale factor */
+    scaleY: number;
+    /** The old rect used as the scaling reference (unrotatedRect ?? rect) */
+    oldRect: Rect;
+    /** The adjusted new rect after min-size and aspect-ratio enforcement */
+    resolvedRect: Rect;
+    /** The final rect + unrotatedRect patches to spread into the result */
+    rects: {
+        rect: Rect;
+        unrotatedRect?: Rect;
+    };
+}
+/**
+ * Shared resize scaling logic:
+ * 1. Determines scale factors from oldRect → newRect
+ * 2. Enforces a minimum size of 10
+ * 3. Optionally maintains aspect ratio
+ * 4. Resolves rect vs unrotatedRect for rotated annotations
+ *
+ * Callers use `scaleX`, `scaleY`, `oldRect`, and `resolvedRect` to scale
+ * their own type-specific data (vertices, linePoints, etc.), then spread
+ * `rects` into their result.
+ */
+export declare function baseResizeScaling(orig: RotatableAnnotation, newRect: Rect, metadata?: {
+    maintainAspectRatio?: boolean;
+}): ResizeScalingResult;
+/**
+ * Compute the orbit translation (dx/dy) from a rotation result.
+ * Point-based annotations (line, polyline, polygon, ink) use this to
+ * translate their vertices/points alongside the rect orbit during
+ * group rotation. For single-annotation rotation the delta is zero.
+ */
+export declare function rotateOrbitDelta(orig: RotatableAnnotation, rotateResult: {
+    unrotatedRect?: Rect;
+}): {
+    dx: number;
+    dy: number;
+};

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

@@ -2,3 +2,4 @@ export * from './patch-utils';
 export * from './line-ending-handlers';
 export * from './line-endings';
 export * from './patch-registry';
+export * from './insert-upright';

package/dist/lib/patching/insert-upright.d.ts

@@ -0,0 +1,20 @@
+import { PdfAnnotationObject, Rotation, Size } from '@embedpdf/models';
+/**
+ * Applies a counter-rotation to make an annotation appear visually upright
+ * on a rotated page. Uses `basePropertyRotationChanges` to correctly compute
+ * rect, unrotatedRect, and rotation for the annotation.
+ *
+ * @param annotation - The annotation to transform
+ * @param pageRotation - Effective page rotation as quarter-turn value (0-3)
+ * @param rectWasDrawn - `true` if the rect was produced by a marquee drag
+ *   (PagePointerProvider transposes dimensions on 90/270 pages),
+ *   `false` if the rect was placed from config/content (click-to-place, stamp)
+ * @returns The annotation with rotation, unrotatedRect, and rect set
+ */
+export declare function applyInsertUpright<T extends PdfAnnotationObject>(annotation: T, pageRotation: Rotation, rectWasDrawn: boolean): T;
+/**
+ * Clamps an annotation's rect to stay within page bounds.
+ * If the annotation has an unrotatedRect, it is shifted by the same delta
+ * to keep the geometry consistent.
+ */
+export declare function clampAnnotationToPage<T extends PdfAnnotationObject>(annotation: T, pageSize: Size): T;

package/dist/lib/patching/patch-registry.d.ts

@@ -1,12 +1,25 @@
 import { PdfAnnotationObject, PdfAnnotationSubtype } from '@embedpdf/models';
 export interface TransformContext<T extends PdfAnnotationObject = PdfAnnotationObject> {
     /** The type of transformation being applied */
-    type: 'move' | 'resize' | 'vertex-edit' | 'property-update';
+    type: 'move' | 'resize' | 'vertex-edit' | 'rotate' | 'property-update';
     /** The changes being applied - can be any properties of the annotation */
     changes: Partial<T>;
     /** Optional metadata about the transformation */
     metadata?: {
         maintainAspectRatio?: boolean;
+        /** Rotation angle in degrees (for 'rotate' transform type) */
+        rotationAngle?: number;
+        /** Delta from the initial rotation angle in degrees */
+        rotationDelta?: number;
+        /** Center point for rotation (defaults to rect center) */
+        rotationCenter?: {
+            x: number;
+            y: number;
+        };
+        /** Whether the rotation input is currently snapped */
+        isSnapped?: boolean;
+        /** Snap target angle when isSnapped is true */
+        snappedAngle?: number;
         [key: string]: any;
     };
 }

package/dist/lib/patching/patch-utils.d.ts

@@ -1,7 +1,60 @@
-import { Rect, Position, LineEndings } from '@embedpdf/models';
+import { Rect, Position, LineEndings, getRectCenter, rotatePointAround, rotateVertices, calculateRotatedRectAABB, calculateRotatedRectAABBAroundPoint } from '@embedpdf/models';
+export { rotatePointAround as rotatePointAroundCenter, rotateVertices, getRectCenter, calculateRotatedRectAABB, calculateRotatedRectAABBAroundPoint, };
+/**
+ * Calculate the axis-aligned bounding box for rotated vertices.
+ * @param vertices - The rotated vertices
+ * @param padding - Optional padding to add around the bounding box
+ * @returns The axis-aligned bounding box
+ */
+export declare function calculateAABBFromVertices(vertices: Position[], padding?: number): Rect;
 /**
  * Computes the exact bounding box for a line or polyline, including its endings and stroke width.
  * This function uses the central `LINE_ENDING_HANDLERS` to ensure calculations are
  * perfectly in sync with the rendering logic.
  */
 export declare function lineRectWithEndings(vertices: Position[], strokeWidth: number, endings: LineEndings | undefined): Rect;
+/**
+ * Build rect patches for vertex editing.
+ * For rotated annotations, the tight rect is kept as unrotatedRect and the AABB is
+ * computed around the new content center so rotation UI follows the edited geometry.
+ */
+export declare function resolveVertexEditRects(original: {
+    rect: Rect;
+    unrotatedRect?: Rect;
+    rotation?: number;
+}, tightRect: Rect): {
+    rect: Rect;
+    unrotatedRect?: Rect;
+};
+/**
+ * Resolve an annotation's effective rotation center in page coordinates.
+ */
+export declare function resolveAnnotationRotationCenter(original: {
+    rect: Rect;
+    unrotatedRect?: Rect;
+    rotation?: number;
+}): Position;
+/**
+ * Build rotate patches while preserving an annotation's effective rotation center.
+ * The incoming unrotated rect may already include a translation (group rotation/orbit).
+ */
+export declare function resolveRotateRects(original: {
+    rect: Rect;
+    unrotatedRect?: Rect;
+    rotation?: number;
+}, nextUnrotatedRect: Rect, angleDegrees: number): {
+    rect: Rect;
+    unrotatedRect: Rect;
+};
+/**
+ * Compensate vertices for rotated vertex editing so the dragged point tracks the cursor
+ * while the rotation center follows edited geometry.
+ *
+ * Without this compensation, changing the tight bounds center during a rotated vertex edit
+ * applies an additional translation to all points, which appears as opposite-end drift.
+ */
+export declare function compensateRotatedVertexEdit(original: {
+    rect: Rect;
+    unrotatedRect?: Rect;
+    rotation?: number;
+}, vertices: Position[], tightRect: Rect): Position[];

package/dist/lib/patching/patches/circle.patch.d.ts

@@ -0,0 +1,3 @@
+import { PdfCircleAnnoObject } from '@embedpdf/models';
+import { PatchFunction } from '../patch-registry';
+export declare const patchCircle: PatchFunction<PdfCircleAnnoObject>;

package/dist/lib/patching/patches/freetext.patch.d.ts

@@ -0,0 +1,3 @@
+import { PdfFreeTextAnnoObject } from '@embedpdf/models';
+import { PatchFunction } from '../patch-registry';
+export declare const patchFreeText: PatchFunction<PdfFreeTextAnnoObject>;

package/dist/lib/patching/patches/index.d.ts

@@ -2,3 +2,7 @@ export * from './ink.patch';
 export * from './line.patch';
 export * from './polyline.patch';
 export * from './polygon.patch';
+export * from './circle.patch';
+export * from './square.patch';
+export * from './freetext.patch';
+export * from './stamp.patch';

package/dist/lib/patching/patches/square.patch.d.ts

@@ -0,0 +1,3 @@
+import { PdfSquareAnnoObject } from '@embedpdf/models';
+import { PatchFunction } from '../patch-registry';
+export declare const patchSquare: PatchFunction<PdfSquareAnnoObject>;

package/dist/lib/patching/patches/stamp.patch.d.ts

@@ -0,0 +1,3 @@
+import { PdfStampAnnoObject } from '@embedpdf/models';
+import { PatchFunction } from '../patch-registry';
+export declare const patchStamp: PatchFunction<PdfStampAnnoObject>;

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

@@ -12,6 +12,7 @@ export declare const defaultTools: ({
         isGroupResizable: false;
         cursor?: undefined;
         lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.HIGHLIGHT;
@@ -32,6 +33,7 @@ export declare const defaultTools: ({
         backgroundColor?: undefined;
     };
     clickBehavior?: undefined;
+    behavior?: undefined;
 } | {
     id: "underline";
     name: string;
@@ -45,6 +47,7 @@ export declare const defaultTools: ({
         isGroupResizable: false;
         cursor?: undefined;
         lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.UNDERLINE;
@@ -65,6 +68,7 @@ export declare const defaultTools: ({
         backgroundColor?: undefined;
     };
     clickBehavior?: undefined;
+    behavior?: undefined;
 } | {
     id: "strikeout";
     name: string;
@@ -78,6 +82,7 @@ export declare const defaultTools: ({
         isGroupResizable: false;
         cursor?: undefined;
         lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.STRIKEOUT;
@@ -98,6 +103,7 @@ export declare const defaultTools: ({
         backgroundColor?: undefined;
     };
     clickBehavior?: undefined;
+    behavior?: undefined;
 } | {
     id: "squiggly";
     name: string;
@@ -111,6 +117,7 @@ export declare const defaultTools: ({
         isGroupResizable: false;
         cursor?: undefined;
         lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.SQUIGGLY;
@@ -131,6 +138,7 @@ export declare const defaultTools: ({
         backgroundColor?: undefined;
     };
     clickBehavior?: undefined;
+    behavior?: undefined;
 } | {
     id: "ink";
     name: string;
@@ -144,6 +152,7 @@ export declare const defaultTools: ({
         textSelection?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        lockGroupAspectRatio?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.INK;
@@ -164,6 +173,7 @@ export declare const defaultTools: ({
         backgroundColor?: undefined;
     };
     clickBehavior?: undefined;
+    behavior?: undefined;
 } | {
     id: "inkHighlighter";
     name: string;
@@ -174,6 +184,7 @@ export declare const defaultTools: ({
         isDraggable: true;
         isResizable: true;
         lockAspectRatio: false;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
@@ -197,6 +208,7 @@ export declare const defaultTools: ({
         backgroundColor?: undefined;
     };
     clickBehavior?: undefined;
+    behavior?: undefined;
 } | {
     id: "circle";
     name: string;
@@ -207,6 +219,7 @@ export declare const defaultTools: ({
         isDraggable: true;
         isResizable: true;
         lockAspectRatio: false;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
@@ -239,6 +252,7 @@ export declare const defaultTools: ({
         defaultAngle?: undefined;
         defaultContent?: undefined;
     };
+    behavior?: undefined;
 } | {
     id: "square";
     name: string;
@@ -249,6 +263,7 @@ export declare const defaultTools: ({
         isDraggable: true;
         isResizable: true;
         lockAspectRatio: false;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
@@ -281,6 +296,7 @@ export declare const defaultTools: ({
         defaultAngle?: undefined;
         defaultContent?: undefined;
     };
+    behavior?: undefined;
 } | {
     id: "line";
     name: string;
@@ -292,6 +308,7 @@ export declare const defaultTools: ({
         isResizable: false;
         lockAspectRatio: false;
         isGroupResizable: true;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
     };
@@ -320,6 +337,7 @@ export declare const defaultTools: ({
         defaultSize?: undefined;
         defaultContent?: undefined;
     };
+    behavior?: undefined;
 } | {
     id: "lineArrow";
     name: string;
@@ -331,6 +349,7 @@ export declare const defaultTools: ({
         isResizable: false;
         lockAspectRatio: false;
         isGroupResizable: true;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
     };
@@ -362,6 +381,7 @@ export declare const defaultTools: ({
         defaultSize?: undefined;
         defaultContent?: undefined;
     };
+    behavior?: undefined;
 } | {
     id: "polyline";
     name: string;
@@ -373,6 +393,7 @@ export declare const defaultTools: ({
         isResizable: false;
         lockAspectRatio: false;
         isGroupResizable: true;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
     };
@@ -395,6 +416,7 @@ export declare const defaultTools: ({
         backgroundColor?: undefined;
     };
     clickBehavior?: undefined;
+    behavior?: undefined;
 } | {
     id: "polygon";
     name: string;
@@ -406,6 +428,7 @@ export declare const defaultTools: ({
         isResizable: false;
         lockAspectRatio: false;
         isGroupResizable: true;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
     };
@@ -428,6 +451,7 @@ export declare const defaultTools: ({
         backgroundColor?: undefined;
     };
     clickBehavior?: undefined;
+    behavior?: undefined;
 } | {
     id: "freeText";
     name: string;
@@ -438,6 +462,7 @@ export declare const defaultTools: ({
         isDraggable: true;
         isResizable: true;
         lockAspectRatio: false;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
@@ -470,6 +495,9 @@ export declare const defaultTools: ({
         defaultLength?: undefined;
         defaultAngle?: undefined;
     };
+    behavior: {
+        insertUpright: true;
+    };
 } | {
     id: "stamp";
     name: string;
@@ -480,6 +508,7 @@ export declare const defaultTools: ({
         isDraggable: true;
         isResizable: true;
         lockAspectRatio: true;
+        lockGroupAspectRatio: true;
         textSelection?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
@@ -502,5 +531,8 @@ export declare const defaultTools: ({
         verticalAlign?: undefined;
         backgroundColor?: undefined;
     };
+    behavior: {
+        insertUpright: true;
+    };
     clickBehavior?: undefined;
 })[];

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

@@ -70,6 +70,19 @@ type GetToolConfig<T extends PdfAnnotationObject> = T['type'] extends keyof Tool
 type ClickBehaviorFor<T extends PdfAnnotationObject> = Extract<T['type'], keyof ClickBehaviorMap> extends never ? {} : {
     clickBehavior?: ClickBehaviorMap[Extract<T['type'], keyof ClickBehaviorMap>];
 };
+/**
+ * Map of annotation types that support the insertUpright behavior.
+ * Only types with a "natural upright orientation" (readable text, image content)
+ * should be listed here.
+ */
+export interface InsertUprightBehaviorMap {
+    [PdfAnnotationSubtype.STAMP]: true;
+    [PdfAnnotationSubtype.FREETEXT]: true;
+}
+type InsertUprightBehaviorFor<T extends PdfAnnotationObject> = Extract<T['type'], keyof InsertUprightBehaviorMap> extends never ? {} : {
+    /** Counter-rotate new annotations to appear visually upright on rotated pages. */
+    insertUpright?: boolean;
+};
 /**
  * The primary interface for defining an annotation tool.
  * Uses a type alias to properly combine the base interface with conditional properties.
@@ -100,12 +113,18 @@ export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject>
         isDraggable?: DynamicBooleanProp;
         /** Whether this annotation can be resized when selected individually. Can be dynamic based on annotation. */
         isResizable?: DynamicBooleanProp;
+        /** Whether this annotation can be rotated when selected individually. Can be dynamic based on annotation. */
+        isRotatable?: DynamicBooleanProp;
         /** Whether to maintain aspect ratio during resize. Can be dynamic based on annotation. */
         lockAspectRatio?: DynamicBooleanProp;
+        /** Whether to maintain aspect ratio during group resize. Defaults to lockAspectRatio. Can be dynamic based on annotation. */
+        lockGroupAspectRatio?: DynamicBooleanProp;
         /** Whether this annotation can be dragged when part of a group. Defaults to isDraggable. Can be dynamic based on annotation. */
         isGroupDraggable?: DynamicBooleanProp;
         /** Whether this annotation can be resized when part of a group. Defaults to isResizable. Can be dynamic based on annotation. */
         isGroupResizable?: DynamicBooleanProp;
+        /** Whether this annotation can be rotated when part of a group. Defaults to isRotatable. Can be dynamic based on annotation. */
+        isGroupRotatable?: DynamicBooleanProp;
     };
     /** Tool-specific behavior settings that override plugin defaults */
     behavior?: {
@@ -113,6 +132,6 @@ export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject>
         deactivateToolAfterCreate?: boolean;
         /** When true, select the annotation immediately after creation. Overrides plugin config. */
         selectAfterCreate?: boolean;
-    };
+    } & InsertUprightBehaviorFor<T>;
 } & ClickBehaviorFor<T>;
 export {};