@embedpdf/plugin-annotation 2.6.2 → 2.8.0

package/dist/lib/actions.d.ts

@@ -14,6 +14,7 @@ export declare const SET_SELECTION = "ANNOTATION/SET_SELECTION";
 export declare const SET_ACTIVE_TOOL_ID = "ANNOTATION/SET_ACTIVE_TOOL_ID";
 export declare const CREATE_ANNOTATION = "ANNOTATION/CREATE_ANNOTATION";
 export declare const PATCH_ANNOTATION = "ANNOTATION/PATCH_ANNOTATION";
+export declare const MOVE_ANNOTATION = "ANNOTATION/MOVE_ANNOTATION";
 export declare const DELETE_ANNOTATION = "ANNOTATION/DELETE_ANNOTATION";
 export declare const COMMIT_PENDING_CHANGES = "ANNOTATION/COMMIT";
 export declare const PURGE_ANNOTATION = "ANNOTATION/PURGE_ANNOTATION";
@@ -102,6 +103,15 @@ export interface PatchAnnotationAction extends Action {
         patch: Partial<PdfAnnotationObject>;
     };
 }
+export interface MoveAnnotationAction extends Action {
+    type: typeof MOVE_ANNOTATION;
+    payload: {
+        documentId: string;
+        pageIndex: number;
+        id: string;
+        patch: Partial<PdfAnnotationObject>;
+    };
+}
 export interface DeleteAnnotationAction extends Action {
     type: typeof DELETE_ANNOTATION;
     payload: {
@@ -140,7 +150,7 @@ export interface AddToolAction extends Action {
     type: typeof ADD_TOOL;
     payload: AnnotationTool;
 }
-export type AnnotationAction = InitAnnotationStateAction | CleanupAnnotationStateAction | SetActiveDocumentAction | SetAnnotationsAction | SelectAnnotationAction | DeselectAnnotationAction | AddToSelectionAction | RemoveFromSelectionAction | SetSelectionAction | SetActiveToolIdAction | CreateAnnotationAction | PatchAnnotationAction | DeleteAnnotationAction | CommitAction | PurgeAnnotationAction | AddColorPresetAction | SetToolDefaultsAction | AddToolAction;
+export type AnnotationAction = InitAnnotationStateAction | CleanupAnnotationStateAction | SetActiveDocumentAction | SetAnnotationsAction | SelectAnnotationAction | DeselectAnnotationAction | AddToSelectionAction | RemoveFromSelectionAction | SetSelectionAction | SetActiveToolIdAction | CreateAnnotationAction | PatchAnnotationAction | MoveAnnotationAction | DeleteAnnotationAction | CommitAction | PurgeAnnotationAction | AddColorPresetAction | SetToolDefaultsAction | AddToolAction;
 export declare function initAnnotationState(documentId: string, state: AnnotationDocumentState): InitAnnotationStateAction;
 export declare function cleanupAnnotationState(documentId: string): CleanupAnnotationStateAction;
 export declare function setActiveDocument(documentId: string | null): SetActiveDocumentAction;
@@ -153,6 +163,7 @@ export declare const setSelection: (documentId: string, ids: string[]) => SetSel
 export declare const setActiveToolId: (documentId: string, toolId: string | null) => SetActiveToolIdAction;
 export declare const createAnnotation: (documentId: string, pageIndex: number, annotation: PdfAnnotationObject) => CreateAnnotationAction;
 export declare const patchAnnotation: (documentId: string, pageIndex: number, id: string, patch: Partial<PdfAnnotationObject>) => PatchAnnotationAction;
+export declare const moveAnnotation: (documentId: string, pageIndex: number, id: string, patch: Partial<PdfAnnotationObject>) => MoveAnnotationAction;
 export declare const deleteAnnotation: (documentId: string, pageIndex: number, id: string) => DeleteAnnotationAction;
 export declare const commitPendingChanges: (documentId: string, committedUids: string[]) => CommitAction;
 export declare const purgeAnnotation: (documentId: string, pageIndex: number, uid: string) => PurgeAnnotationAction;

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

@@ -17,10 +17,12 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     private importQueue;
     private commitInProgress;
     private handlerFactories;
+    private selectionHandlerFactories;
     private readonly activeTool$;
     private readonly events$;
     private readonly toolsChange$;
     private readonly patchRegistry;
+    private readonly appearanceCache;
     private readonly unifiedDragStates;
     private readonly unifiedDrag$;
     private readonly unifiedResizeStates;
@@ -32,6 +34,7 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     protected onDocumentLoaded(documentId: string): void;
     protected onDocumentClosed(documentId: string): void;
     private registerHandlerFactories;
+    private registerSelectionHandlerFactories;
     private registerBuiltInPatches;
     initialize(): Promise<void>;
     private registerInteractionForTool;
@@ -50,6 +53,20 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     private getSelectedAnnotation;
     private getAnnotationById;
     private renderAnnotation;
+    /**
+     * Batch-fetch rendered appearance stream images for all annotations on a page.
+     * Results are cached per document + page. Call invalidatePageAppearances to clear.
+     */
+    private getPageAppearances;
+    /**
+     * Clear cached appearances for a specific page (e.g. on zoom change).
+     */
+    private invalidatePageAppearances;
+    /**
+     * Remove a single annotation's entry from the page appearance cache.
+     * Used after committing changes that regenerate the annotation's appearance.
+     */
+    private invalidateAnnotationAppearance;
     private importAnnotations;
     private processImportQueue;
     private processImportItems;
@@ -227,6 +244,8 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
      */
     get onRotateChange(): import('@embedpdf/core').EventHook<UnifiedRotateEvent>;
     private updateAnnotationsMethod;
+    private moveAnnotationsMethod;
+    private moveAnnotationMethod;
     getActiveTool(documentId?: string): AnnotationTool | null;
     setActiveTool(toolId: string | null, documentId?: string): void;
     getTool<T extends AnnotationTool>(toolId: string): T | undefined;

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

@@ -1,4 +1,5 @@
 export * from './ink.handler';
+export * from './text.handler';
 export * from './free-text.handler';
 export * from './line.handler';
 export * from './polyline.handler';
@@ -6,3 +7,6 @@ export * from './polygon.handler';
 export * from './square.handler';
 export * from './stamp.handler';
 export * from './circle.handler';
+export * from './text-markup.handler';
+export * from './insert-text.handler';
+export * from './replace-text.handler';

package/dist/lib/handlers/insert-text.handler.d.ts

@@ -0,0 +1,8 @@
+import { PdfCaretAnnoObject } from '@embedpdf/models';
+import { SelectionHandlerFactory } from './types';
+/**
+ * Selection handler for the "Insert Text" tool.
+ * Creates a single Caret annotation at the end of the text selection
+ * with intent "Insert".
+ */
+export declare const insertTextSelectionHandler: SelectionHandlerFactory<PdfCaretAnnoObject>;

package/dist/lib/handlers/replace-text.handler.d.ts

@@ -0,0 +1,9 @@
+import { PdfStrikeOutAnnoObject } from '@embedpdf/models';
+import { SelectionHandlerFactory } from './types';
+/**
+ * Selection handler for the "Replace Text" tool.
+ * Creates a Caret annotation (group leader, intent "Replace") at the end
+ * of the selection, plus a StrikeOut annotation (intent "StrikeOutTextEdit")
+ * over the full selection, linked to the Caret via IRT/RT=Group.
+ */
+export declare const replaceTextSelectionHandler: SelectionHandlerFactory<PdfStrikeOutAnnoObject>;

package/dist/lib/handlers/selection-utils.d.ts

@@ -0,0 +1,7 @@
+import { Rect } from '@embedpdf/models';
+/**
+ * Compute a caret annotation rect at the end of a text selection.
+ * The caret is half the line height, bottom-aligned with the line,
+ * and horizontally centered on the line's end edge.
+ */
+export declare function computeCaretRect(lastSegRect: Rect): Rect;

package/dist/lib/handlers/text-markup.handler.d.ts

@@ -0,0 +1,7 @@
+import { SelectionHandlerFactory } from './types';
+/**
+ * Default selection handler for text-markup tools (highlight, underline,
+ * strikeout, squiggly). Used as a fallback when no tool-specific
+ * SelectionHandlerFactory is registered.
+ */
+export declare const textMarkupSelectionHandler: SelectionHandlerFactory;

package/dist/lib/handlers/text.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfTextAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const textHandlerFactory: HandlerFactory<PdfTextAnnoObject>;

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

@@ -1,5 +1,6 @@
 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 { FormattedSelection } from '@embedpdf/plugin-selection';
 import { AnnotationTool } from '../tools/types';
 export interface CirclePreviewData {
     rect: Rect;
@@ -138,4 +139,15 @@ export interface HandlerContext<A extends PdfAnnotationObject> {
     onPreview: (state: AnyPreviewState | null) => void;
     onCommit: (annotation: A, context?: AnnotationCreateContext<A>) => void;
 }
+export interface SelectionHandlerContext<A extends PdfAnnotationObject = PdfAnnotationObject> {
+    toolId: string;
+    documentId: string;
+    getTool: () => AnnotationTool<A> | null;
+    createAnnotation: (pageIndex: number, annotation: PdfAnnotationObject) => void;
+    selectAnnotation: (pageIndex: number, id: string) => void;
+}
+export interface SelectionHandlerFactory<A extends PdfAnnotationObject = PdfAnnotationObject> {
+    toolId: string;
+    handle(context: SelectionHandlerContext<A>, selections: FormattedSelection[], getText: () => Promise<string | undefined>): void;
+}
 export {};

package/dist/lib/helpers.d.ts

@@ -8,7 +8,7 @@ export type AnnoOf<S extends PdfAnnotationSubtype> = Extract<PdfAnnotationObject
     type: S;
 }>;
 export type TextMarkupSubtype = PdfAnnotationSubtype.HIGHLIGHT | PdfAnnotationSubtype.UNDERLINE | PdfAnnotationSubtype.STRIKEOUT | PdfAnnotationSubtype.SQUIGGLY;
-export type SidebarSubtype = TextMarkupSubtype | PdfAnnotationSubtype.INK | PdfAnnotationSubtype.SQUARE | PdfAnnotationSubtype.CIRCLE | PdfAnnotationSubtype.POLYGON | PdfAnnotationSubtype.LINE | PdfAnnotationSubtype.POLYLINE | PdfAnnotationSubtype.FREETEXT | PdfAnnotationSubtype.STAMP | PdfAnnotationSubtype.REDACT;
+export type SidebarSubtype = TextMarkupSubtype | PdfAnnotationSubtype.TEXT | PdfAnnotationSubtype.INK | PdfAnnotationSubtype.SQUARE | PdfAnnotationSubtype.CIRCLE | PdfAnnotationSubtype.POLYGON | PdfAnnotationSubtype.LINE | PdfAnnotationSubtype.POLYLINE | PdfAnnotationSubtype.FREETEXT | PdfAnnotationSubtype.STAMP | PdfAnnotationSubtype.REDACT | PdfAnnotationSubtype.CARET;
 /** True when `a.object.type === INK` – and narrows the generic. */
 export declare function isInk(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.INK>>;
 /** Example for Circle – create similar ones for Square, Line, etc. */
@@ -27,4 +27,5 @@ export declare function isStamp(a: TrackedAnnotation): a is TrackedAnnotation<An
 export declare function isText(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.TEXT>>;
 export declare function isLink(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.LINK>>;
 export declare function isRedact(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.REDACT>>;
+export declare function isCaret(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.CARET>>;
 export declare function isSidebarAnnotation(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<SidebarSubtype>>;

package/dist/lib/selectors.d.ts

@@ -40,9 +40,14 @@ export declare function getToolDefaultsById<K extends keyof ToolMap>(state: Anno
  * Collect every sidebar-eligible annotation and attach its TEXT replies,
  * grouped by page for efficient rendering.
  *
+ * Annotations linked via IRT / RT=Group are collapsed: the group leader
+ * becomes the sidebar entry and its non-LINK group members are attached
+ * as `groupMembers`. This keeps the sidebar compact for tools like
+ * Replace Text (Caret + StrikeOut pair).
+ *
  * Result shape:
  * {
- *   0: [{ page: 0, annotation: <TrackedAnnotation>, replies: [ … ] }, ...],
+ *   0: [{ page: 0, annotation: <TrackedAnnotation>, replies: [ … ], groupMembers: [ … ] }, ...],
  *   1: [{ page: 1, annotation: <TrackedAnnotation>, replies: [ … ] }, ...],
  *   …
  * }

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

@@ -8,8 +8,10 @@ export declare const defaultTools: ({
         textSelection: true;
         isDraggable: false;
         isResizable: false;
+        isRotatable: false;
         isGroupDraggable: false;
         isGroupResizable: false;
+        showSelectionRects?: undefined;
         cursor?: undefined;
         lockAspectRatio?: undefined;
         lockGroupAspectRatio?: undefined;
@@ -20,8 +22,8 @@ export declare const defaultTools: ({
         color: string;
         opacity: number;
         blendMode: PdfBlendMode.Multiply;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -43,8 +45,10 @@ export declare const defaultTools: ({
         textSelection: true;
         isDraggable: false;
         isResizable: false;
+        isRotatable: false;
         isGroupDraggable: false;
         isGroupResizable: false;
+        showSelectionRects?: undefined;
         cursor?: undefined;
         lockAspectRatio?: undefined;
         lockGroupAspectRatio?: undefined;
@@ -55,8 +59,8 @@ export declare const defaultTools: ({
         color: string;
         opacity: number;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -78,8 +82,10 @@ export declare const defaultTools: ({
         textSelection: true;
         isDraggable: false;
         isResizable: false;
+        isRotatable: false;
         isGroupDraggable: false;
         isGroupResizable: false;
+        showSelectionRects?: undefined;
         cursor?: undefined;
         lockAspectRatio?: undefined;
         lockGroupAspectRatio?: undefined;
@@ -90,8 +96,8 @@ export declare const defaultTools: ({
         color: string;
         opacity: number;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -113,8 +119,10 @@ export declare const defaultTools: ({
         textSelection: true;
         isDraggable: false;
         isResizable: false;
+        isRotatable: false;
         isGroupDraggable: false;
         isGroupResizable: false;
+        showSelectionRects?: undefined;
         cursor?: undefined;
         lockAspectRatio?: undefined;
         lockGroupAspectRatio?: undefined;
@@ -125,8 +133,82 @@ export declare const defaultTools: ({
         color: string;
         opacity: number;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+    behavior?: undefined;
+} | {
+    id: "insertText";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0 | 2;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        showSelectionRects: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+        cursor?: undefined;
+        lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.CARET;
+        strokeColor: string;
+        opacity: number;
+        intent: string;
+        color?: undefined;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+    behavior?: undefined;
+} | {
+    id: "replaceText";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 2;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+        showSelectionRects?: undefined;
+        cursor?: undefined;
+        lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.STRIKEOUT;
+        strokeColor: string;
+        opacity: number;
+        intent: string;
+        color?: undefined;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -150,8 +232,10 @@ export declare const defaultTools: ({
         isResizable: true;
         lockAspectRatio: false;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
         lockGroupAspectRatio?: undefined;
     };
     defaults: {
@@ -186,8 +270,10 @@ export declare const defaultTools: ({
         lockAspectRatio: false;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.INK;
@@ -221,8 +307,10 @@ export declare const defaultTools: ({
         lockAspectRatio: false;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.CIRCLE;
@@ -265,8 +353,10 @@ export declare const defaultTools: ({
         lockAspectRatio: false;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.SQUARE;
@@ -310,7 +400,9 @@ export declare const defaultTools: ({
         isGroupResizable: true;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.LINE;
@@ -351,7 +443,9 @@ export declare const defaultTools: ({
         isGroupResizable: true;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.LINE;
@@ -395,7 +489,9 @@ export declare const defaultTools: ({
         isGroupResizable: true;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.POLYLINE;
@@ -430,7 +526,9 @@ export declare const defaultTools: ({
         isGroupResizable: true;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.POLYGON;
@@ -452,6 +550,47 @@ export declare const defaultTools: ({
     };
     clickBehavior?: undefined;
     behavior?: undefined;
+} | {
+    id: "textComment";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: false;
+        isRotatable: false;
+        textSelection?: undefined;
+        isGroupDraggable?: undefined;
+        isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
+        lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.TEXT;
+        strokeColor: string;
+        opacity: number;
+        color?: undefined;
+        blendMode?: undefined;
+        intent?: undefined;
+        strokeWidth?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    behavior: {
+        selectAfterCreate: true;
+        insertUpright?: undefined;
+        useAppearanceStream?: undefined;
+    };
+    clickBehavior?: undefined;
 } | {
     id: "freeText";
     name: string;
@@ -464,8 +603,10 @@ export declare const defaultTools: ({
         lockAspectRatio: false;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.FREETEXT;
@@ -480,8 +621,8 @@ export declare const defaultTools: ({
         opacity: number;
         strokeColor?: undefined;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
     };
@@ -497,6 +638,8 @@ export declare const defaultTools: ({
     };
     behavior: {
         insertUpright: true;
+        selectAfterCreate?: undefined;
+        useAppearanceStream?: undefined;
     };
 } | {
     id: "stamp";
@@ -510,8 +653,10 @@ export declare const defaultTools: ({
         lockAspectRatio: true;
         lockGroupAspectRatio: true;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.STAMP;
@@ -519,8 +664,8 @@ export declare const defaultTools: ({
         color?: undefined;
         opacity?: undefined;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -533,6 +678,8 @@ export declare const defaultTools: ({
     };
     behavior: {
         insertUpright: true;
+        useAppearanceStream: false;
+        selectAfterCreate?: undefined;
     };
     clickBehavior?: undefined;
 })[];

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

@@ -22,4 +22,6 @@ export declare const isPolylineTool: (tool: AnnotationTool<any> | undefined) =>
 export declare const isPolygonTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["polygon"];
 export declare const isFreeTextTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["freeText"];
 export declare const isStampTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["stamp"];
+export declare const isInsertTextTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["insertText"];
+export declare const isReplaceTextTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["replaceText"];
 export {};

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

@@ -109,6 +109,8 @@ export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject>
         cursor?: string;
         /** If true, this interaction mode is activated by selecting text. */
         textSelection?: boolean;
+        /** Whether to show the native text selection rectangles. Only relevant when textSelection is true. Defaults to false. */
+        showSelectionRects?: boolean;
         /** Whether this annotation can be dragged when selected individually. Can be dynamic based on annotation. */
         isDraggable?: DynamicBooleanProp;
         /** Whether this annotation can be resized when selected individually. Can be dynamic based on annotation. */
@@ -132,6 +134,8 @@ export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject>
         deactivateToolAfterCreate?: boolean;
         /** When true, select the annotation immediately after creation. Overrides plugin config. */
         selectAfterCreate?: boolean;
+        /** Override whether this annotation type uses AP rendering before editing (default: true) */
+        useAppearanceStream?: boolean;
     } & InsertUprightBehaviorFor<T>;
 } & ClickBehaviorFor<T>;
 export {};

package/dist/lib/types.d.ts

@@ -1,5 +1,5 @@
 import { BasePluginConfig, EventHook } from '@embedpdf/core';
-import { AnnotationCreateContext, PdfAnnotationObject, PdfAnnotationSubtype, PdfErrorReason, PdfRenderPageAnnotationOptions, PdfTextAnnoObject, Position, Rect, Size, Task } from '@embedpdf/models';
+import { AnnotationCreateContext, AnnotationAppearanceMap, PdfAnnotationObject, PdfAnnotationSubtype, PdfErrorReason, PdfRenderPageAnnotationOptions, PdfTextAnnoObject, Position, Rect, Size, Task } from '@embedpdf/models';
 import { AnnotationTool } from './tools/types';
 /**
  * Metadata attached to annotation history commands for filtering/purging.
@@ -38,10 +38,12 @@ export type AnnotationEvent = {
 export type AnnotationToolsChangeEvent = {
     tools: AnnotationTool[];
 };
-export type CommitState = 'new' | 'dirty' | 'deleted' | 'synced' | 'ignored';
+export type CommitState = 'new' | 'dirty' | 'moved' | 'deleted' | 'synced' | 'ignored';
 export interface TrackedAnnotation<T extends PdfAnnotationObject = PdfAnnotationObject> {
     commitState: CommitState;
     object: T;
+    /** When true, render using dict-based SVG/CSS instead of appearance stream image */
+    dictMode?: boolean;
 }
 /**
  * Represents a batch of pending annotation changes to be committed.
@@ -58,6 +60,8 @@ export interface CommitBatch {
     updates: Array<{
         uid: string;
         ta: TrackedAnnotation;
+        /** When true, only positional data changed -- skip appearance regeneration */
+        moved?: boolean;
     }>;
     /** Annotations that need to be deleted from the PDF */
     deletions: Array<{
@@ -204,6 +208,8 @@ export interface AnnotationScope {
         id: string;
         patch: Partial<PdfAnnotationObject>;
     }>): void;
+    /** Move an annotation by delta or to an absolute position (preserves appearance stream) */
+    moveAnnotation(pageIndex: number, annotationId: string, position: Position, mode?: 'delta' | 'absolute'): void;
     deleteAnnotation(pageIndex: number, annotationId: string): void;
     /** Delete multiple annotations in batch */
     deleteAnnotations(annotations: Array<{
@@ -213,6 +219,10 @@ export interface AnnotationScope {
     /** Remove an annotation from state without calling the engine (no PDF modification) */
     purgeAnnotation(pageIndex: number, annotationId: string): void;
     renderAnnotation(options: RenderAnnotationOptions): Task<Blob, PdfErrorReason>;
+    /** Batch-fetch rendered appearance stream images for all annotations on a page */
+    getPageAppearances(pageIndex: number, options?: PdfRenderPageAnnotationOptions): Task<AnnotationAppearanceMap<Blob>, PdfErrorReason>;
+    /** Clear cached appearance images for a page (e.g. on zoom change) */
+    invalidatePageAppearances(pageIndex: number): void;
     commit(): Task<boolean, PdfErrorReason>;
     /** Get link annotations attached to an annotation via IRT relationship */
     getAttachedLinks(annotationId: string): TrackedAnnotation[];
@@ -265,6 +275,8 @@ export interface AnnotationCapability {
         id: string;
         patch: Partial<PdfAnnotationObject>;
     }>) => void;
+    /** Move an annotation by delta or to an absolute position (preserves appearance stream) */
+    moveAnnotation: (pageIndex: number, annotationId: string, position: Position, mode?: 'delta' | 'absolute', documentId?: string) => void;
     deleteAnnotation: (pageIndex: number, annotationId: string) => void;
     /** Delete multiple annotations in batch */
     deleteAnnotations: (annotations: Array<{
@@ -274,6 +286,10 @@ export interface AnnotationCapability {
     /** Remove an annotation from state without calling the engine (no PDF modification) */
     purgeAnnotation: (pageIndex: number, annotationId: string, documentId?: string) => void;
     renderAnnotation: (options: RenderAnnotationOptions) => Task<Blob, PdfErrorReason>;
+    /** Batch-fetch rendered appearance stream images for all annotations on a page */
+    getPageAppearances: (pageIndex: number, options?: PdfRenderPageAnnotationOptions, documentId?: string) => Task<AnnotationAppearanceMap<Blob>, PdfErrorReason>;
+    /** Clear cached appearance images for a page (e.g. on zoom change) */
+    invalidatePageAppearances: (pageIndex: number, documentId?: string) => void;
     commit: () => Task<boolean, PdfErrorReason>;
     /** Get link annotations attached to an annotation via IRT relationship */
     getAttachedLinks: (annotationId: string, documentId?: string) => TrackedAnnotation[];
@@ -321,6 +337,7 @@ export interface SidebarAnnotationEntry {
     page: number;
     annotation: TrackedAnnotation;
     replies: TrackedAnnotation<PdfTextAnnoObject>[];
+    groupMembers?: TrackedAnnotation[];
 }
 /**
  * Information about an annotation needed for constraint calculation.