@embedpdf/utils 2.4.1 → 2.6.0

package/dist/shared-react/plugin-interaction-primitives/resize-geometry.d.ts

@@ -0,0 +1,72 @@
+import { Position, Rect } from '@embedpdf/models';
+import { ResizeHandle } from './drag-resize-controller';
+/** Anchor describes which edges stay fixed when resizing. */
+export type Anchor = {
+    x: 'left' | 'right' | 'center';
+    y: 'top' | 'bottom' | 'center';
+};
+/**
+ * Derive anchor from handle.
+ * - 'e' means we're dragging east → left edge is anchored
+ * - 'nw' means we're dragging north-west → bottom-right corner is anchored
+ */
+export declare function getAnchor(handle: ResizeHandle): Anchor;
+/** Get the anchor point (the visually fixed point) in page space for a given rect and anchor. */
+export declare function getAnchorPoint(rect: Rect, anchor: Anchor): Position;
+export interface ResizeConstraints {
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    boundingBox?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Apply the mouse delta to produce a raw (unconstrained) resized rect.
+ */
+export declare function applyResizeDelta(startRect: Rect, delta: Position, anchor: Anchor): Rect;
+/**
+ * Enforce aspect ratio while respecting the anchor.
+ * For edge handles (center anchor on one axis), the rect expands symmetrically on that axis.
+ * For corner handles, the anchor corner stays fixed.
+ */
+export declare function enforceAspectRatio(rect: Rect, startRect: Rect, anchor: Anchor, aspectRatio: number): Rect;
+/**
+ * Clamp rect to bounding box while respecting anchor.
+ */
+export declare function clampToBounds(rect: Rect, startRect: Rect, anchor: Anchor, bbox: {
+    width: number;
+    height: number;
+} | undefined, maintainAspectRatio: boolean): Rect;
+/**
+ * Reposition rect from current size so the start-gesture anchor remains fixed.
+ * This prevents translation drift when constraints clamp width/height.
+ */
+export declare function reanchorRect(rect: Rect, startRect: Rect, anchor: Anchor): Rect;
+/**
+ * Apply min/max constraints. Also used by the drag pipeline for position clamping.
+ */
+export declare function applyConstraints(position: Rect, constraints: ResizeConstraints | undefined, maintainAspectRatio: boolean, skipBoundingClamp?: boolean): Rect;
+/**
+ * Check if a rect, when rotated, fits within the given page bounds.
+ */
+export declare function isRectWithinRotatedBounds(rect: Rect, angleDegrees: number, bbox: {
+    width: number;
+    height: number;
+}): boolean;
+export interface ResizeConfig {
+    startRect: Rect;
+    maintainAspectRatio?: boolean;
+    annotationRotation?: number;
+    constraints?: ResizeConstraints;
+}
+/**
+ * Calculate the new rect after a resize operation.
+ *
+ * For non-rotated annotations, runs the pipeline once with local bound clamping.
+ * For rotated annotations, uses a binary search to find the largest delta that
+ * keeps the visual AABB within page bounds.
+ */
+export declare function computeResizedRect(delta: Position, handle: ResizeHandle, config: ResizeConfig): Rect;

package/dist/shared-react/plugin-interaction-primitives/utils.d.ts

@@ -13,10 +13,43 @@ export interface VertexUI {
     vertexSize?: number;
     zIndex?: number;
 }
+export interface RotationUI {
+    /** Handle size in px (default 32) */
+    handleSize?: number;
+    /** Screen-pixel gap between bounding box edge and handle center (default 30) */
+    margin?: number;
+    /** z-index of the rotation handle (default 5) */
+    zIndex?: number;
+    /** Whether to show the connector line from center to handle (default true) */
+    showConnector?: boolean;
+    /** Connector line width in px (default 1) */
+    connectorWidth?: number;
+}
+/** Screen-pixel gap between the rect edge and the rotation handle center (default orbit margin). */
+export declare const ROTATION_HANDLE_MARGIN = 35;
 export interface HandleDescriptor {
     handle: ResizeHandle;
     style: Record<string, number | string>;
     attrs?: Record<string, any>;
 }
+export interface RotationHandleDescriptor {
+    /** Style for the rotation handle itself */
+    handleStyle: Record<string, number | string>;
+    /** Style for the connector line (if shown) */
+    connectorStyle: Record<string, number | string>;
+    /** Orbit radius in screen pixels used to position the handle. */
+    radius: number;
+    /** Attributes for the handle element */
+    attrs?: Record<string, any>;
+}
 export declare function describeResizeFromConfig(cfg: DragResizeConfig, ui?: ResizeUI): HandleDescriptor[];
 export declare function describeVerticesFromConfig(cfg: DragResizeConfig, ui?: VertexUI, liveVertices?: Position[]): HandleDescriptor[];
+/**
+ * Describe the rotation handle position and style.
+ * The rotation handle orbits around the center of the bounding box based on the current angle.
+ *
+ * @param cfg - The drag/resize config containing the element rect and scale
+ * @param ui - UI customization options
+ * @param currentAngle - The current rotation angle in degrees (0 = top, clockwise positive)
+ */
+export declare function describeRotationFromConfig(cfg: DragResizeConfig, ui?: RotationUI, currentAngle?: number): RotationHandleDescriptor;

package/dist/shared-svelte/plugin-interaction-primitives/drag-resize-controller.d.ts

@@ -1,6 +1,16 @@
 import { Position, Rect } from '@embedpdf/models';
 export interface DragResizeConfig {
     element: Rect;
+    /**
+     * Optional world-space pivot to use for rotation interactions.
+     * Defaults to the center of `element`.
+     */
+    rotationCenter?: Position;
+    /**
+     * Optional rect used for rotation-handle orbit layout (typically the visible AABB container).
+     * Defaults to `element`.
+     */
+    rotationElement?: Rect;
     vertices?: Position[];
     constraints?: {
         minWidth?: number;
@@ -14,20 +24,37 @@ export interface DragResizeConfig {
     };
     maintainAspectRatio?: boolean;
     pageRotation?: number;
+    /** Rotation of the annotation itself in degrees (used to project mouse deltas into local space for resize/vertex-edit) */
+    annotationRotation?: number;
     scale?: number;
+    rotationSnapAngles?: number[];
+    rotationSnapThreshold?: number;
 }
-export type InteractionState = 'idle' | 'dragging' | 'resizing' | 'vertex-editing';
+export type InteractionState = 'idle' | 'dragging' | 'resizing' | 'vertex-editing' | 'rotating';
 export type ResizeHandle = 'nw' | 'ne' | 'sw' | 'se' | 'n' | 'e' | 's' | 'w';
 export interface TransformData {
-    type: 'move' | 'resize' | 'vertex-edit';
+    type: 'move' | 'resize' | 'vertex-edit' | 'rotate';
     changes: {
         rect?: Rect;
         vertices?: Position[];
+        rotation?: number;
     };
     metadata?: {
         handle?: ResizeHandle;
         vertexIndex?: number;
         maintainAspectRatio?: boolean;
+        /** The rotation angle in degrees */
+        rotationAngle?: number;
+        /** The center point used for rotation */
+        rotationCenter?: Position;
+        rotationDelta?: number;
+        isSnapped?: boolean;
+        snappedAngle?: number;
+        /** Screen-space cursor position during the gesture */
+        cursorPosition?: {
+            clientX: number;
+            clientY: number;
+        };
     };
 }
 export interface InteractionEvent {
@@ -35,7 +62,7 @@ export interface InteractionEvent {
     transformData?: TransformData;
 }
 /**
- * Pure geometric controller that manages drag/resize/vertex-edit logic.
+ * Pure geometric controller that manages drag/resize/vertex-edit/rotate logic.
  */
 export declare class DragResizeController {
     private config;
@@ -43,44 +70,43 @@ export declare class DragResizeController {
     private state;
     private startPoint;
     private startElement;
+    private startRotationElement;
+    private gestureRotationCenter;
     private activeHandle;
     private currentPosition;
     private activeVertexIndex;
     private startVertices;
     private currentVertices;
+    private rotationCenter;
+    private centerScreen;
+    private initialRotation;
+    private lastComputedRotation;
+    private rotationDelta;
+    private rotationSnappedAngle;
     constructor(config: DragResizeConfig, onUpdate: (event: InteractionEvent) => void);
     updateConfig(config: Partial<DragResizeConfig>): void;
     startDrag(clientX: number, clientY: number): void;
     startResize(handle: ResizeHandle, clientX: number, clientY: number): void;
     startVertexEdit(vertexIndex: number, clientX: number, clientY: number): void;
-    move(clientX: number, clientY: number): void;
+    startRotation(clientX: number, clientY: number, initialRotation?: number, orbitRadiusPx?: number): void;
+    move(clientX: number, clientY: number, buttons?: number): void;
     end(): void;
     cancel(): void;
     private reset;
-    private getCurrentPosition;
     private calculateDelta;
     private transformDelta;
+    /**
+     * Calculate delta projected into the annotation's local (unrotated) coordinate space.
+     * Used for resize and vertex-edit where mouse movement must be mapped to the
+     * annotation's own axes, accounting for its rotation.
+     */
+    private calculateLocalDelta;
     private clampPoint;
     private calculateVertexPosition;
     private calculateDragPosition;
     /**
-     * Calculate the new rect after a resize operation.
-     * Pipeline: applyDelta → enforceAspectRatio → clampToBounds → applyConstraints
-     */
-    private calculateResizePosition;
-    /**
-     * Apply the mouse delta to produce a raw (unconstrained) resized rect.
-     */
-    private applyResizeDelta;
-    /**
-     * Enforce aspect ratio while respecting the anchor.
-     * For edge handles (center anchor on one axis), the rect expands symmetrically on that axis.
-     * For corner handles, the anchor corner stays fixed.
-     */
-    private enforceAspectRatio;
-    /**
-     * Clamp rect to bounding box while respecting anchor and aspect ratio.
+     * Calculate the angle from the center to a point in screen coordinates.
      */
-    private clampToBounds;
-    private applyConstraints;
+    private calculateAngleFromMouse;
+    private applyRotationSnapping;
 }

package/dist/shared-svelte/plugin-interaction-primitives/index.d.ts

@@ -1,2 +1,3 @@
 export * from './drag-resize-controller';
+export * from './resize-geometry';
 export * from './utils';

package/dist/shared-svelte/plugin-interaction-primitives/resize-geometry.d.ts

@@ -0,0 +1,72 @@
+import { Position, Rect } from '@embedpdf/models';
+import { ResizeHandle } from './drag-resize-controller';
+/** Anchor describes which edges stay fixed when resizing. */
+export type Anchor = {
+    x: 'left' | 'right' | 'center';
+    y: 'top' | 'bottom' | 'center';
+};
+/**
+ * Derive anchor from handle.
+ * - 'e' means we're dragging east → left edge is anchored
+ * - 'nw' means we're dragging north-west → bottom-right corner is anchored
+ */
+export declare function getAnchor(handle: ResizeHandle): Anchor;
+/** Get the anchor point (the visually fixed point) in page space for a given rect and anchor. */
+export declare function getAnchorPoint(rect: Rect, anchor: Anchor): Position;
+export interface ResizeConstraints {
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    boundingBox?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Apply the mouse delta to produce a raw (unconstrained) resized rect.
+ */
+export declare function applyResizeDelta(startRect: Rect, delta: Position, anchor: Anchor): Rect;
+/**
+ * Enforce aspect ratio while respecting the anchor.
+ * For edge handles (center anchor on one axis), the rect expands symmetrically on that axis.
+ * For corner handles, the anchor corner stays fixed.
+ */
+export declare function enforceAspectRatio(rect: Rect, startRect: Rect, anchor: Anchor, aspectRatio: number): Rect;
+/**
+ * Clamp rect to bounding box while respecting anchor.
+ */
+export declare function clampToBounds(rect: Rect, startRect: Rect, anchor: Anchor, bbox: {
+    width: number;
+    height: number;
+} | undefined, maintainAspectRatio: boolean): Rect;
+/**
+ * Reposition rect from current size so the start-gesture anchor remains fixed.
+ * This prevents translation drift when constraints clamp width/height.
+ */
+export declare function reanchorRect(rect: Rect, startRect: Rect, anchor: Anchor): Rect;
+/**
+ * Apply min/max constraints. Also used by the drag pipeline for position clamping.
+ */
+export declare function applyConstraints(position: Rect, constraints: ResizeConstraints | undefined, maintainAspectRatio: boolean, skipBoundingClamp?: boolean): Rect;
+/**
+ * Check if a rect, when rotated, fits within the given page bounds.
+ */
+export declare function isRectWithinRotatedBounds(rect: Rect, angleDegrees: number, bbox: {
+    width: number;
+    height: number;
+}): boolean;
+export interface ResizeConfig {
+    startRect: Rect;
+    maintainAspectRatio?: boolean;
+    annotationRotation?: number;
+    constraints?: ResizeConstraints;
+}
+/**
+ * Calculate the new rect after a resize operation.
+ *
+ * For non-rotated annotations, runs the pipeline once with local bound clamping.
+ * For rotated annotations, uses a binary search to find the largest delta that
+ * keeps the visual AABB within page bounds.
+ */
+export declare function computeResizedRect(delta: Position, handle: ResizeHandle, config: ResizeConfig): Rect;

package/dist/shared-svelte/plugin-interaction-primitives/utils.d.ts

@@ -13,10 +13,43 @@ export interface VertexUI {
     vertexSize?: number;
     zIndex?: number;
 }
+export interface RotationUI {
+    /** Handle size in px (default 32) */
+    handleSize?: number;
+    /** Screen-pixel gap between bounding box edge and handle center (default 30) */
+    margin?: number;
+    /** z-index of the rotation handle (default 5) */
+    zIndex?: number;
+    /** Whether to show the connector line from center to handle (default true) */
+    showConnector?: boolean;
+    /** Connector line width in px (default 1) */
+    connectorWidth?: number;
+}
+/** Screen-pixel gap between the rect edge and the rotation handle center (default orbit margin). */
+export declare const ROTATION_HANDLE_MARGIN = 35;
 export interface HandleDescriptor {
     handle: ResizeHandle;
     style: Record<string, number | string>;
     attrs?: Record<string, any>;
 }
+export interface RotationHandleDescriptor {
+    /** Style for the rotation handle itself */
+    handleStyle: Record<string, number | string>;
+    /** Style for the connector line (if shown) */
+    connectorStyle: Record<string, number | string>;
+    /** Orbit radius in screen pixels used to position the handle. */
+    radius: number;
+    /** Attributes for the handle element */
+    attrs?: Record<string, any>;
+}
 export declare function describeResizeFromConfig(cfg: DragResizeConfig, ui?: ResizeUI): HandleDescriptor[];
 export declare function describeVerticesFromConfig(cfg: DragResizeConfig, ui?: VertexUI, liveVertices?: Position[]): HandleDescriptor[];
+/**
+ * Describe the rotation handle position and style.
+ * The rotation handle orbits around the center of the bounding box based on the current angle.
+ *
+ * @param cfg - The drag/resize config containing the element rect and scale
+ * @param ui - UI customization options
+ * @param currentAngle - The current rotation angle in degrees (0 = top, clockwise positive)
+ */
+export declare function describeRotationFromConfig(cfg: DragResizeConfig, ui?: RotationUI, currentAngle?: number): RotationHandleDescriptor;

package/dist/shared-vue/plugin-interaction-primitives/drag-resize-controller.d.ts

@@ -1,6 +1,16 @@
 import { Position, Rect } from '@embedpdf/models';
 export interface DragResizeConfig {
     element: Rect;
+    /**
+     * Optional world-space pivot to use for rotation interactions.
+     * Defaults to the center of `element`.
+     */
+    rotationCenter?: Position;
+    /**
+     * Optional rect used for rotation-handle orbit layout (typically the visible AABB container).
+     * Defaults to `element`.
+     */
+    rotationElement?: Rect;
     vertices?: Position[];
     constraints?: {
         minWidth?: number;
@@ -14,20 +24,37 @@ export interface DragResizeConfig {
     };
     maintainAspectRatio?: boolean;
     pageRotation?: number;
+    /** Rotation of the annotation itself in degrees (used to project mouse deltas into local space for resize/vertex-edit) */
+    annotationRotation?: number;
     scale?: number;
+    rotationSnapAngles?: number[];
+    rotationSnapThreshold?: number;
 }
-export type InteractionState = 'idle' | 'dragging' | 'resizing' | 'vertex-editing';
+export type InteractionState = 'idle' | 'dragging' | 'resizing' | 'vertex-editing' | 'rotating';
 export type ResizeHandle = 'nw' | 'ne' | 'sw' | 'se' | 'n' | 'e' | 's' | 'w';
 export interface TransformData {
-    type: 'move' | 'resize' | 'vertex-edit';
+    type: 'move' | 'resize' | 'vertex-edit' | 'rotate';
     changes: {
         rect?: Rect;
         vertices?: Position[];
+        rotation?: number;
     };
     metadata?: {
         handle?: ResizeHandle;
         vertexIndex?: number;
         maintainAspectRatio?: boolean;
+        /** The rotation angle in degrees */
+        rotationAngle?: number;
+        /** The center point used for rotation */
+        rotationCenter?: Position;
+        rotationDelta?: number;
+        isSnapped?: boolean;
+        snappedAngle?: number;
+        /** Screen-space cursor position during the gesture */
+        cursorPosition?: {
+            clientX: number;
+            clientY: number;
+        };
     };
 }
 export interface InteractionEvent {
@@ -35,7 +62,7 @@ export interface InteractionEvent {
     transformData?: TransformData;
 }
 /**
- * Pure geometric controller that manages drag/resize/vertex-edit logic.
+ * Pure geometric controller that manages drag/resize/vertex-edit/rotate logic.
  */
 export declare class DragResizeController {
     private config;
@@ -43,44 +70,43 @@ export declare class DragResizeController {
     private state;
     private startPoint;
     private startElement;
+    private startRotationElement;
+    private gestureRotationCenter;
     private activeHandle;
     private currentPosition;
     private activeVertexIndex;
     private startVertices;
     private currentVertices;
+    private rotationCenter;
+    private centerScreen;
+    private initialRotation;
+    private lastComputedRotation;
+    private rotationDelta;
+    private rotationSnappedAngle;
     constructor(config: DragResizeConfig, onUpdate: (event: InteractionEvent) => void);
     updateConfig(config: Partial<DragResizeConfig>): void;
     startDrag(clientX: number, clientY: number): void;
     startResize(handle: ResizeHandle, clientX: number, clientY: number): void;
     startVertexEdit(vertexIndex: number, clientX: number, clientY: number): void;
-    move(clientX: number, clientY: number): void;
+    startRotation(clientX: number, clientY: number, initialRotation?: number, orbitRadiusPx?: number): void;
+    move(clientX: number, clientY: number, buttons?: number): void;
     end(): void;
     cancel(): void;
     private reset;
-    private getCurrentPosition;
     private calculateDelta;
     private transformDelta;
+    /**
+     * Calculate delta projected into the annotation's local (unrotated) coordinate space.
+     * Used for resize and vertex-edit where mouse movement must be mapped to the
+     * annotation's own axes, accounting for its rotation.
+     */
+    private calculateLocalDelta;
     private clampPoint;
     private calculateVertexPosition;
     private calculateDragPosition;
     /**
-     * Calculate the new rect after a resize operation.
-     * Pipeline: applyDelta → enforceAspectRatio → clampToBounds → applyConstraints
-     */
-    private calculateResizePosition;
-    /**
-     * Apply the mouse delta to produce a raw (unconstrained) resized rect.
-     */
-    private applyResizeDelta;
-    /**
-     * Enforce aspect ratio while respecting the anchor.
-     * For edge handles (center anchor on one axis), the rect expands symmetrically on that axis.
-     * For corner handles, the anchor corner stays fixed.
-     */
-    private enforceAspectRatio;
-    /**
-     * Clamp rect to bounding box while respecting anchor and aspect ratio.
+     * Calculate the angle from the center to a point in screen coordinates.
      */
-    private clampToBounds;
-    private applyConstraints;
+    private calculateAngleFromMouse;
+    private applyRotationSnapping;
 }

package/dist/shared-vue/plugin-interaction-primitives/index.d.ts

@@ -1,2 +1,3 @@
 export * from './drag-resize-controller';
+export * from './resize-geometry';
 export * from './utils';

package/dist/shared-vue/plugin-interaction-primitives/resize-geometry.d.ts

@@ -0,0 +1,72 @@
+import { Position, Rect } from '@embedpdf/models';
+import { ResizeHandle } from './drag-resize-controller';
+/** Anchor describes which edges stay fixed when resizing. */
+export type Anchor = {
+    x: 'left' | 'right' | 'center';
+    y: 'top' | 'bottom' | 'center';
+};
+/**
+ * Derive anchor from handle.
+ * - 'e' means we're dragging east → left edge is anchored
+ * - 'nw' means we're dragging north-west → bottom-right corner is anchored
+ */
+export declare function getAnchor(handle: ResizeHandle): Anchor;
+/** Get the anchor point (the visually fixed point) in page space for a given rect and anchor. */
+export declare function getAnchorPoint(rect: Rect, anchor: Anchor): Position;
+export interface ResizeConstraints {
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    boundingBox?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Apply the mouse delta to produce a raw (unconstrained) resized rect.
+ */
+export declare function applyResizeDelta(startRect: Rect, delta: Position, anchor: Anchor): Rect;
+/**
+ * Enforce aspect ratio while respecting the anchor.
+ * For edge handles (center anchor on one axis), the rect expands symmetrically on that axis.
+ * For corner handles, the anchor corner stays fixed.
+ */
+export declare function enforceAspectRatio(rect: Rect, startRect: Rect, anchor: Anchor, aspectRatio: number): Rect;
+/**
+ * Clamp rect to bounding box while respecting anchor.
+ */
+export declare function clampToBounds(rect: Rect, startRect: Rect, anchor: Anchor, bbox: {
+    width: number;
+    height: number;
+} | undefined, maintainAspectRatio: boolean): Rect;
+/**
+ * Reposition rect from current size so the start-gesture anchor remains fixed.
+ * This prevents translation drift when constraints clamp width/height.
+ */
+export declare function reanchorRect(rect: Rect, startRect: Rect, anchor: Anchor): Rect;
+/**
+ * Apply min/max constraints. Also used by the drag pipeline for position clamping.
+ */
+export declare function applyConstraints(position: Rect, constraints: ResizeConstraints | undefined, maintainAspectRatio: boolean, skipBoundingClamp?: boolean): Rect;
+/**
+ * Check if a rect, when rotated, fits within the given page bounds.
+ */
+export declare function isRectWithinRotatedBounds(rect: Rect, angleDegrees: number, bbox: {
+    width: number;
+    height: number;
+}): boolean;
+export interface ResizeConfig {
+    startRect: Rect;
+    maintainAspectRatio?: boolean;
+    annotationRotation?: number;
+    constraints?: ResizeConstraints;
+}
+/**
+ * Calculate the new rect after a resize operation.
+ *
+ * For non-rotated annotations, runs the pipeline once with local bound clamping.
+ * For rotated annotations, uses a binary search to find the largest delta that
+ * keeps the visual AABB within page bounds.
+ */
+export declare function computeResizedRect(delta: Position, handle: ResizeHandle, config: ResizeConfig): Rect;

package/dist/shared-vue/plugin-interaction-primitives/utils.d.ts

@@ -13,10 +13,43 @@ export interface VertexUI {
     vertexSize?: number;
     zIndex?: number;
 }
+export interface RotationUI {
+    /** Handle size in px (default 32) */
+    handleSize?: number;
+    /** Screen-pixel gap between bounding box edge and handle center (default 30) */
+    margin?: number;
+    /** z-index of the rotation handle (default 5) */
+    zIndex?: number;
+    /** Whether to show the connector line from center to handle (default true) */
+    showConnector?: boolean;
+    /** Connector line width in px (default 1) */
+    connectorWidth?: number;
+}
+/** Screen-pixel gap between the rect edge and the rotation handle center (default orbit margin). */
+export declare const ROTATION_HANDLE_MARGIN = 35;
 export interface HandleDescriptor {
     handle: ResizeHandle;
     style: Record<string, number | string>;
     attrs?: Record<string, any>;
 }
+export interface RotationHandleDescriptor {
+    /** Style for the rotation handle itself */
+    handleStyle: Record<string, number | string>;
+    /** Style for the connector line (if shown) */
+    connectorStyle: Record<string, number | string>;
+    /** Orbit radius in screen pixels used to position the handle. */
+    radius: number;
+    /** Attributes for the handle element */
+    attrs?: Record<string, any>;
+}
 export declare function describeResizeFromConfig(cfg: DragResizeConfig, ui?: ResizeUI): HandleDescriptor[];
 export declare function describeVerticesFromConfig(cfg: DragResizeConfig, ui?: VertexUI, liveVertices?: Position[]): HandleDescriptor[];
+/**
+ * Describe the rotation handle position and style.
+ * The rotation handle orbits around the center of the bounding box based on the current angle.
+ *
+ * @param cfg - The drag/resize config containing the element rect and scale
+ * @param ui - UI customization options
+ * @param currentAngle - The current rotation angle in degrees (0 = top, clockwise positive)
+ */
+export declare function describeRotationFromConfig(cfg: DragResizeConfig, ui?: RotationUI, currentAngle?: number): RotationHandleDescriptor;

package/dist/svelte/hooks/use-drag-resize.svelte.d.ts

@@ -23,4 +23,5 @@ export declare function useDragResize(getOptions: () => UseDragResizeOptions): {
     };
     createResizeProps: (handle: ResizeHandle) => ResizeHandleEventProps;
     createVertexProps: (vertexIndex: number) => ResizeHandleEventProps;
+    createRotationProps: (initialRotation?: number, orbitRadiusPx?: number) => ResizeHandleEventProps;
 };

package/dist/svelte/hooks/use-interaction-handles.svelte.d.ts

@@ -1,20 +1,33 @@
 import { UseDragResizeOptions } from './use-drag-resize.svelte';
-import { ResizeUI, VertexUI } from '../../shared-svelte/plugin-interaction-primitives';
+import { ResizeUI, VertexUI, RotationUI } from '../../shared-svelte/plugin-interaction-primitives';
 export type HandleElementProps = {
-    key: string | number;
+    key?: string | number;
     style: string;
     onpointerdown: (e: PointerEvent) => void;
     onpointermove: (e: PointerEvent) => void;
     onpointerup: (e: PointerEvent) => void;
     onpointercancel: (e: PointerEvent) => void;
 } & Record<string, any>;
+export type RotationHandleElementProps = {
+    /** Props for the rotation handle element */
+    handle: HandleElementProps;
+    /** Props for the connector line element (if shown) */
+    connector: {
+        style: string;
+    } & Record<string, any>;
+};
 export declare function useInteractionHandles(getOpts: () => {
     controller: UseDragResizeOptions;
     resizeUI?: ResizeUI;
     vertexUI?: VertexUI;
+    rotationUI?: RotationUI;
     includeVertices?: boolean;
+    includeRotation?: boolean;
+    /** Current rotation angle of the annotation (for initializing rotation interaction) */
+    currentRotation?: number;
     handleAttrs?: (h: 'nw' | 'ne' | 'sw' | 'se' | 'n' | 'e' | 's' | 'w') => Record<string, any> | void;
     vertexAttrs?: (i: number) => Record<string, any> | void;
+    rotationAttrs?: () => Record<string, any> | void;
 }): {
     readonly dragProps: {
         onpointerdown: (e: PointerEvent) => void;
@@ -29,4 +42,5 @@ export declare function useInteractionHandles(getOpts: () => {
     };
     readonly resize: HandleElementProps[];
     readonly vertices: HandleElementProps[];
+    readonly rotation: RotationHandleElementProps | null;
 };