@embedpdf/plugin-annotation 2.6.2 → 2.8.0

package/dist/shared/annotation-bounds.d.ts

@@ -0,0 +1,14 @@
+import { Rotation } from '@embedpdf/models';
+import { TrackedAnnotation } from '../index.ts';
+export interface ScreenBounds {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Compute the screen-space bounding box of an annotation, correctly accounting
+ * for `noZoom` (constant pixel size regardless of zoom) and `noRotate`
+ * (visually upright regardless of page rotation) annotation flags.
+ */
+export declare function getAnnotationScreenBounds(annotation: TrackedAnnotation, scale: number, rotation: Rotation): ScreenBounds;

package/dist/shared/components/annotation-container.d.ts

@@ -1,7 +1,7 @@
-import { PdfAnnotationObject } from '@embedpdf/models';
+import { PdfAnnotationObject, AnnotationAppearances } from '@embedpdf/models';
 import { TrackedAnnotation } from '../../index.ts';
 import { JSX, CSSProperties } from '../../react/adapter.ts';
-import { CustomAnnotationRenderer, ResizeHandleUI, AnnotationSelectionMenuRenderFn, VertexHandleUI, RotationHandleUI, GroupSelectionMenuRenderFn, BoxedAnnotationRenderer, SelectionOutline } from './types';
+import { CustomAnnotationRenderer, ResizeHandleUI, AnnotationSelectionMenuRenderFn, AnnotationInteractionEvent, VertexHandleUI, RotationHandleUI, GroupSelectionMenuRenderFn, BoxedAnnotationRenderer, SelectionOutline } from './types';
 import { VertexConfig } from '../types';
 interface AnnotationContainerProps<T extends PdfAnnotationObject> {
     scale: number;
@@ -11,8 +11,12 @@ interface AnnotationContainerProps<T extends PdfAnnotationObject> {
     pageWidth: number;
     pageHeight: number;
     trackedAnnotation: TrackedAnnotation<T>;
-    children: JSX.Element | ((annotation: T) => JSX.Element);
+    children: JSX.Element | ((annotation: T, options: {
+        appearanceActive: boolean;
+    }) => JSX.Element);
     isSelected: boolean;
+    /** Whether the annotation is in editing mode (e.g., FreeText text editing) */
+    isEditing?: boolean;
     /** Whether multiple annotations are selected (container becomes passive) */
     isMultiSelected?: boolean;
     isDraggable: boolean;
@@ -25,7 +29,9 @@ interface AnnotationContainerProps<T extends PdfAnnotationObject> {
     /** @deprecated Use `selectionOutline.offset` instead */
     outlineOffset?: number;
     onDoubleClick?: (event: any) => void;
-    onSelect: (event: any) => void;
+    onSelect: (event: AnnotationInteractionEvent) => void;
+    /** Pre-rendered appearance stream images for AP mode rendering */
+    appearance?: AnnotationAppearances<Blob> | null;
     zIndex?: number;
     resizeUI?: ResizeHandleUI;
     vertexUI?: VertexHandleUI;
@@ -47,5 +53,5 @@ interface AnnotationContainerProps<T extends PdfAnnotationObject> {
  * When isMultiSelected is true, the container becomes passive - drag/resize
  * is handled by the GroupSelectionBox instead.
  */
-export declare function AnnotationContainer<T extends PdfAnnotationObject>({ scale, documentId, pageIndex, rotation, pageWidth, pageHeight, trackedAnnotation, children, isSelected, isMultiSelected, isDraggable, isResizable, isRotatable, lockAspectRatio, style, vertexConfig, selectionMenu, outlineOffset, onDoubleClick, onSelect, zIndex, resizeUI, vertexUI, rotationUI, selectionOutlineColor, selectionOutline, customAnnotationRenderer, groupSelectionMenu: _groupSelectionMenu, groupSelectionOutline: _groupSelectionOutline, annotationRenderers: _annotationRenderers, ...props }: AnnotationContainerProps<T>): JSX.Element;
+export declare function AnnotationContainer<T extends PdfAnnotationObject>({ scale, documentId, pageIndex, rotation, pageWidth, pageHeight, trackedAnnotation, children, isSelected, isEditing, isMultiSelected, isDraggable, isResizable, isRotatable, lockAspectRatio, style, vertexConfig, selectionMenu, outlineOffset, onDoubleClick, onSelect, appearance, zIndex, resizeUI, vertexUI, rotationUI, selectionOutlineColor, selectionOutline, customAnnotationRenderer, groupSelectionMenu: _groupSelectionMenu, groupSelectionOutline: _groupSelectionOutline, annotationRenderers: _annotationRenderers, ...props }: AnnotationContainerProps<T>): JSX.Element;
 export {};

package/dist/shared/components/annotations/caret.d.ts

@@ -0,0 +1,24 @@
+import { MouseEvent } from '../../../react/adapter.ts';
+import { Rect } from '@embedpdf/models';
+interface CaretProps {
+    /** Whether the annotation is selected */
+    isSelected: boolean;
+    /** Stroke colour */
+    strokeColor?: string;
+    /** 0 – 1 */
+    opacity?: number;
+    /** Bounding box of the annotation (PDF units) */
+    rect: Rect;
+    /** Current page zoom factor */
+    scale: number;
+    /** Click handler (used for selection) */
+    onClick?: (e: MouseEvent<SVGElement>) => void;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
+}
+/**
+ * Renders a PDF Caret annotation as an SVG ^ symbol using bezier curves
+ * that mirror the C++ appearance stream.
+ */
+export declare function Caret({ isSelected, strokeColor, opacity, rect, scale, onClick, appearanceActive, }: CaretProps): JSX.Element;
+export {};

package/dist/shared/components/annotations/circle.d.ts

@@ -1,9 +1,9 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { MouseEvent } from '../../../react/adapter.ts';
 import { PdfAnnotationBorderStyle, Rect } from '@embedpdf/models';
 interface CircleProps {
     /** Whether the annotation is selected */
     isSelected: boolean;
-    /** Fill colour – defaults to PDFium’s black if omitted */
+    /** Fill colour – defaults to PDFium's black if omitted */
     color?: string;
     /** Stroke colour – defaults to same as fill when omitted */
     strokeColor?: string;
@@ -20,10 +20,12 @@ interface CircleProps {
     /** Current page zoom factor */
     scale: number;
     /** Click handler (used for selection) */
-    onClick?: (e: MouseEvent<SVGElement> | TouchEvent<SVGElement>) => void;
+    onClick?: (e: MouseEvent<SVGElement>) => void;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
 }
 /**
  * Renders a PDF Circle annotation (ellipse) as SVG.
  */
-export declare function Circle({ color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, rect, scale, onClick, isSelected, }: CircleProps): JSX.Element;
+export declare function Circle({ color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, rect, scale, onClick, isSelected, appearanceActive, }: CircleProps): JSX.Element;
 export {};

package/dist/shared/components/annotations/free-text.d.ts

@@ -1,14 +1,17 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { MouseEvent } from '../../../react/adapter.ts';
 import { PdfFreeTextAnnoObject } from '@embedpdf/models';
 import { TrackedAnnotation } from '../../../index.ts';
 interface FreeTextProps {
+    documentId: string;
     isSelected: boolean;
     isEditing: boolean;
     annotation: TrackedAnnotation<PdfFreeTextAnnoObject>;
     pageIndex: number;
     scale: number;
-    onClick?: (e: MouseEvent<HTMLDivElement> | TouchEvent<HTMLDivElement>) => void;
+    onClick?: (e: MouseEvent<HTMLDivElement>) => void;
     onDoubleClick?: (event: MouseEvent<HTMLDivElement>) => void;
+    /** When true, AP canvas provides the visual; hide text content */
+    appearanceActive?: boolean;
 }
-export declare function FreeText({ isSelected, isEditing, annotation, pageIndex, scale, onClick, }: FreeTextProps): import("react/jsx-runtime").JSX.Element;
+export declare function FreeText({ documentId, isSelected, isEditing, annotation, pageIndex, scale, onClick, appearanceActive, }: FreeTextProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/shared/components/annotations/ink.d.ts

@@ -1,4 +1,4 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { MouseEvent } from '../../../react/adapter.ts';
 import { PdfInkListObject, Rect } from '@embedpdf/models';
 interface InkProps {
     /** Whether the annotation is selected */
@@ -16,10 +16,12 @@ interface InkProps {
     /** Page zoom factor */
     scale: number;
     /** Callback for when the annotation is clicked */
-    onClick?: (e: MouseEvent<SVGPathElement> | TouchEvent<SVGPathElement>) => void;
+    onClick?: (e: MouseEvent<SVGPathElement>) => void;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
 }
 /**
  * Renders a PDF Ink annotation (free-hand drawing) as SVG.
  */
-export declare function Ink({ isSelected, strokeColor, opacity, strokeWidth, inkList, rect, scale, onClick, }: InkProps): JSX.Element;
+export declare function Ink({ isSelected, strokeColor, opacity, strokeWidth, inkList, rect, scale, onClick, appearanceActive, }: InkProps): JSX.Element;
 export {};

package/dist/shared/components/annotations/line.d.ts

@@ -1,4 +1,4 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { MouseEvent } from '../../../react/adapter.ts';
 import { Rect, LinePoints, LineEndings, PdfAnnotationBorderStyle } from '@embedpdf/models';
 interface LineProps {
     /** interior colour */
@@ -22,12 +22,14 @@ interface LineProps {
     /** Current page zoom factor */
     scale: number;
     /** Click handler (used for selection) */
-    onClick?: (e: MouseEvent<SVGElement> | TouchEvent<SVGElement>) => void;
+    onClick?: (e: MouseEvent<SVGElement>) => void;
     /** Whether the annotation is selected */
     isSelected: boolean;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
 }
 /**
  * Renders a PDF Line annotation as SVG (with arrow/butt endings).
  */
-export declare function Line({ color, opacity, strokeWidth, strokeColor, strokeStyle, strokeDashArray, rect, linePoints, lineEndings, scale, onClick, isSelected, }: LineProps): JSX.Element;
+export declare function Line({ color, opacity, strokeWidth, strokeColor, strokeStyle, strokeDashArray, rect, linePoints, lineEndings, scale, onClick, isSelected, appearanceActive, }: LineProps): JSX.Element;
 export {};

package/dist/shared/components/annotations/link.d.ts

@@ -1,4 +1,4 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { MouseEvent } from '../../../react/adapter.ts';
 import { PdfAnnotationBorderStyle, Rect } from '@embedpdf/models';
 interface LinkProps {
     /** Whether the annotation is selected */
@@ -16,7 +16,7 @@ interface LinkProps {
     /** Current page zoom factor */
     scale: number;
     /** Click handler (used for selection) */
-    onClick?: (e: MouseEvent<SVGElement> | TouchEvent<SVGElement>) => void;
+    onClick?: (e: MouseEvent<SVGElement>) => void;
     /** Whether this link has an IRT (In Reply To) reference - disables direct interaction */
     hasIRT?: boolean;
 }

package/dist/shared/components/annotations/polygon.d.ts

@@ -1,4 +1,4 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { MouseEvent } from '../../../react/adapter.ts';
 import { Rect, Position, PdfAnnotationBorderStyle } from '@embedpdf/models';
 interface PolygonProps {
     rect: Rect;
@@ -11,10 +11,11 @@ interface PolygonProps {
     strokeDashArray?: number[];
     scale: number;
     isSelected: boolean;
-    onClick?: (e: MouseEvent<SVGElement> | TouchEvent<SVGElement>) => void;
+    onClick?: (e: MouseEvent<SVGElement>) => void;
     currentVertex?: Position;
     handleSize?: number;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
 }
-export declare function Polygon({ rect, vertices, color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, scale, isSelected, onClick, currentVertex, // A preview-only prop
-handleSize, }: PolygonProps): JSX.Element;
+export declare function Polygon({ rect, vertices, color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, scale, isSelected, onClick, currentVertex, handleSize, appearanceActive, }: PolygonProps): JSX.Element;
 export {};

package/dist/shared/components/annotations/polyline.d.ts

@@ -1,5 +1,5 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
-import { Rect, Position, LineEndings } from '@embedpdf/models';
+import { MouseEvent } from '../../../react/adapter.ts';
+import { Rect, Position, LineEndings, PdfAnnotationBorderStyle } from '@embedpdf/models';
 interface PolylineProps {
     rect: Rect;
     vertices: Position[];
@@ -7,11 +7,17 @@ interface PolylineProps {
     strokeColor?: string;
     opacity?: number;
     strokeWidth: number;
+    /** Stroke style */
+    strokeStyle?: PdfAnnotationBorderStyle;
+    /** Stroke dash array */
+    strokeDashArray?: number[];
     scale: number;
     isSelected: boolean;
-    onClick?: (e: MouseEvent<SVGElement> | TouchEvent<SVGElement>) => void;
+    onClick?: (e: MouseEvent<SVGElement>) => void;
     /** Optional start & end endings */
     lineEndings?: LineEndings;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
 }
-export declare function Polyline({ rect, vertices, color, strokeColor, opacity, strokeWidth, scale, isSelected, onClick, lineEndings, }: PolylineProps): JSX.Element;
+export declare function Polyline({ rect, vertices, color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, scale, isSelected, onClick, lineEndings, appearanceActive, }: PolylineProps): JSX.Element;
 export {};

package/dist/shared/components/annotations/square.d.ts

@@ -1,9 +1,9 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { MouseEvent } from '../../../react/adapter.ts';
 import { PdfAnnotationBorderStyle, Rect } from '@embedpdf/models';
 interface SquareProps {
     /** Whether the annotation is selected */
     isSelected: boolean;
-    /** Fill colour – defaults to PDFium’s black if omitted */
+    /** Fill colour – defaults to PDFium's black if omitted */
     color?: string;
     /** Stroke colour – defaults to same as fill when omitted */
     strokeColor?: string;
@@ -20,10 +20,12 @@ interface SquareProps {
     /** Current page zoom factor */
     scale: number;
     /** Click handler (used for selection) */
-    onClick?: (e: MouseEvent<SVGElement> | TouchEvent<SVGElement>) => void;
+    onClick?: (e: MouseEvent<SVGElement>) => void;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
 }
 /**
  * Renders a PDF Square annotation (rectangle) as SVG.
  */
-export declare function Square({ isSelected, color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, rect, scale, onClick, }: SquareProps): JSX.Element;
+export declare function Square({ isSelected, color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, rect, scale, onClick, appearanceActive, }: SquareProps): JSX.Element;
 export {};

package/dist/shared/components/annotations/stamp.d.ts

@@ -1,4 +1,4 @@
-import { MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { MouseEvent } from '../../../react/adapter.ts';
 import { PdfStampAnnoObject } from '@embedpdf/models';
 import { TrackedAnnotation } from '../../../index.ts';
 interface StampProps {
@@ -7,7 +7,7 @@ interface StampProps {
     documentId: string;
     pageIndex: number;
     scale: number;
-    onClick: (e: MouseEvent<HTMLDivElement> | TouchEvent<HTMLDivElement>) => void;
+    onClick: (e: MouseEvent<HTMLDivElement>) => void;
 }
 export declare function Stamp({ isSelected, annotation, documentId, pageIndex, scale, onClick, }: StampProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/shared/components/annotations/text.d.ts

@@ -0,0 +1,14 @@
+import { MouseEvent } from '../../../react/adapter.ts';
+interface TextProps {
+    isSelected: boolean;
+    color?: string;
+    opacity?: number;
+    onClick?: (e: MouseEvent<HTMLDivElement>) => void;
+    appearanceActive?: boolean;
+}
+/**
+ * Renders a fallback sticky-note icon for PDF Text annotations when no
+ * appearance stream image is available.
+ */
+export declare function Text({ isSelected, color, opacity, onClick, appearanceActive, }: TextProps): JSX.Element;
+export {};

package/dist/shared/components/annotations.d.ts

@@ -16,7 +16,6 @@ interface AnnotationsProps {
     selectionOutline?: SelectionOutline;
     groupSelectionOutline?: SelectionOutline;
     customAnnotationRenderer?: CustomAnnotationRenderer<PdfAnnotationObject>;
-    /** Custom renderers for specific annotation types (provided by external plugins) */
     annotationRenderers?: BoxedAnnotationRenderer[];
 }
 export declare function Annotations(annotationsProps: AnnotationsProps): import("react/jsx-runtime").JSX.Element;

package/dist/shared/components/appearance-image.d.ts

@@ -0,0 +1,12 @@
+import { AnnotationAppearanceImage } from '@embedpdf/models';
+import { CSSProperties } from '../../react/adapter.ts';
+interface AppearanceImageProps {
+    appearance: AnnotationAppearanceImage<Blob>;
+    style?: CSSProperties;
+}
+/**
+ * Renders a pre-rendered annotation appearance stream image as an img URL.
+ * Purely visual -- pointer events are always disabled; hit-area SVG handles interaction.
+ */
+export declare function AppearanceImage({ appearance, style }: AppearanceImageProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/shared/components/built-in-renderers.d.ts

@@ -0,0 +1,2 @@
+import { BoxedAnnotationRenderer } from './types';
+export declare const builtInRenderers: BoxedAnnotationRenderer[];

package/dist/shared/components/text-markup/highlight.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { CSSProperties, MouseEvent } from '../../../react/adapter.ts';
 import { Rect } from '@embedpdf/models';
 type HighlightProps = {
     /** Stroke/markup color */
@@ -7,8 +7,10 @@ type HighlightProps = {
     segmentRects: Rect[];
     rect?: Rect;
     scale: number;
-    onClick?: (e: MouseEvent<HTMLDivElement> | TouchEvent<HTMLDivElement>) => void;
+    onClick?: (e: MouseEvent<HTMLDivElement>) => void;
     style?: CSSProperties;
+    /** When true, AP image provides the visual; only render hit area */
+    appearanceActive?: boolean;
 };
-export declare function Highlight({ strokeColor, opacity, segmentRects, rect, scale, onClick, style, }: HighlightProps): import("react/jsx-runtime").JSX.Element;
+export declare function Highlight({ strokeColor, opacity, segmentRects, rect, scale, onClick, style, appearanceActive, }: HighlightProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/shared/components/text-markup/squiggly.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { CSSProperties, MouseEvent } from '../../../react/adapter.ts';
 import { Rect } from '@embedpdf/models';
 type SquigglyProps = {
     /** Stroke/markup color */
@@ -7,8 +7,10 @@ type SquigglyProps = {
     segmentRects: Rect[];
     rect?: Rect;
     scale: number;
-    onClick?: (e: MouseEvent<HTMLDivElement> | TouchEvent<HTMLDivElement>) => void;
+    onClick?: (e: MouseEvent<HTMLDivElement>) => void;
     style?: CSSProperties;
+    /** When true, AP image provides the visual; only render hit area */
+    appearanceActive?: boolean;
 };
-export declare function Squiggly({ strokeColor, opacity, segmentRects, rect, scale, onClick, style, }: SquigglyProps): import("react/jsx-runtime").JSX.Element;
+export declare function Squiggly({ strokeColor, opacity, segmentRects, rect, scale, onClick, style, appearanceActive, }: SquigglyProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/shared/components/text-markup/strikeout.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { CSSProperties, MouseEvent } from '../../../react/adapter.ts';
 import { Rect } from '@embedpdf/models';
 type StrikeoutProps = {
     /** Stroke/markup color */
@@ -7,8 +7,10 @@ type StrikeoutProps = {
     segmentRects: Rect[];
     rect?: Rect;
     scale: number;
-    onClick?: (e: MouseEvent<HTMLDivElement> | TouchEvent<HTMLDivElement>) => void;
+    onClick?: (e: MouseEvent<HTMLDivElement>) => void;
     style?: CSSProperties;
+    /** When true, AP image provides the visual; only render hit area */
+    appearanceActive?: boolean;
 };
-export declare function Strikeout({ strokeColor, opacity, segmentRects, rect, scale, onClick, style, }: StrikeoutProps): import("react/jsx-runtime").JSX.Element;
+export declare function Strikeout({ strokeColor, opacity, segmentRects, rect, scale, onClick, style, appearanceActive, }: StrikeoutProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/shared/components/text-markup/underline.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, MouseEvent, TouchEvent } from '../../../react/adapter.ts';
+import { CSSProperties, MouseEvent } from '../../../react/adapter.ts';
 import { Rect } from '@embedpdf/models';
 type UnderlineProps = {
     /** Stroke/markup color */
@@ -7,8 +7,10 @@ type UnderlineProps = {
     segmentRects: Rect[];
     rect?: Rect;
     scale: number;
-    onClick?: (e: MouseEvent<HTMLDivElement> | TouchEvent<HTMLDivElement>) => void;
+    onClick?: (e: MouseEvent<HTMLDivElement>) => void;
     style?: CSSProperties;
+    /** When true, AP image provides the visual; only render hit area */
+    appearanceActive?: boolean;
 };
-export declare function Underline({ strokeColor, opacity, segmentRects, rect, scale, onClick, style, }: UnderlineProps): import("react/jsx-runtime").JSX.Element;
+export declare function Underline({ strokeColor, opacity, segmentRects, rect, scale, onClick, style, appearanceActive, }: UnderlineProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/shared/components/types.d.ts

@@ -1,7 +1,8 @@
 import { PdfAnnotationObject } from '@embedpdf/models';
 import { TrackedAnnotation } from '../../index.ts';
 import { HandleElementProps, SelectionMenuPropsBase, SelectionMenuRenderFn } from '../../react/utils.ts';
-import { JSX, CSSProperties, MouseEvent, TouchEvent } from '../../react/adapter.ts';
+import { JSX, CSSProperties, MouseEvent } from '../../react/adapter.ts';
+import { VertexConfig } from '../types';
 export type ResizeDirection = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none';
 export interface AnnotationSelectionContext {
     type: 'annotation';
@@ -106,15 +107,34 @@ export interface CustomAnnotationRendererProps<T extends PdfAnnotationObject> {
  * Custom renderer for an annotation
  */
 export type CustomAnnotationRenderer<T extends PdfAnnotationObject> = (props: CustomAnnotationRendererProps<T>) => JSX.Element | null;
+/**
+ * Properly typed event for annotation interactions (click, select, etc.)
+ */
+export type AnnotationInteractionEvent = MouseEvent<Element>;
 /**
  * Props for an annotation renderer entry
  */
-export interface AnnotationRendererProps<T extends PdfAnnotationObject> {
+export interface AnnotationRendererProps<T extends PdfAnnotationObject = PdfAnnotationObject> {
     annotation: TrackedAnnotation<T>;
+    currentObject: T;
     isSelected: boolean;
+    isEditing: boolean;
     scale: number;
     pageIndex: number;
-    onClick: (e: MouseEvent<Element> | TouchEvent<Element>) => void;
+    documentId: string;
+    onClick: (e: AnnotationInteractionEvent) => void;
+    /** When true, AP canvas provides the visual; component should only render hit area */
+    appearanceActive: boolean;
+}
+/**
+ * Helpers passed to selectOverride for custom selection behavior.
+ */
+export interface SelectOverrideHelpers {
+    defaultSelect: (e: AnnotationInteractionEvent, annotation: TrackedAnnotation) => void;
+    selectAnnotation: (pageIndex: number, id: string) => void;
+    clearSelection: () => void;
+    allAnnotations: TrackedAnnotation[];
+    pageIndex: number;
 }
 /**
  * Entry for a custom annotation renderer that handles specific annotation types.
@@ -128,20 +148,56 @@ export interface AnnotationRendererEntry<T extends PdfAnnotationObject = PdfAnno
     matches: (annotation: PdfAnnotationObject) => annotation is T;
     /** The component to render the annotation */
     render: (props: AnnotationRendererProps<T>) => JSX.Element;
+    /** Vertex configuration for annotations with draggable vertices (line, polyline, polygon) */
+    vertexConfig?: VertexConfig<T>;
+    /** z-index for the annotation container (default: 1, text markup uses 0) */
+    zIndex?: number;
+    /** Style applied to the annotation container (overrides default blendMode style) */
+    containerStyle?: (annotation: T) => CSSProperties;
+    /** Type-specific interaction fallbacks used when the tool doesn't define a property */
+    interactionDefaults?: {
+        isDraggable?: boolean;
+        isResizable?: boolean;
+        isRotatable?: boolean;
+        lockAspectRatio?: boolean;
+    };
+    /** Whether this annotation type uses AP rendering before editing (default: true) */
+    useAppearanceStream?: boolean;
+    /** Override resolved isDraggable (e.g., FreeText disables drag while editing) */
+    isDraggable?: (toolDraggable: boolean, context: {
+        isEditing: boolean;
+    }) => boolean;
+    /** Handle double-click on the annotation container */
+    onDoubleClick?: (annotationId: string, setEditingId: (id: string) => void) => void;
+    /** Override default selection behavior (e.g., Link IRT parent resolution) */
+    selectOverride?: (e: AnnotationInteractionEvent, annotation: TrackedAnnotation<T>, helpers: SelectOverrideHelpers) => void;
+    /** Return true to hide the selection menu for this annotation */
+    hideSelectionMenu?: (annotation: T) => boolean;
 }
-/**
- * Props passed to tryRender (everything except annotation which is passed separately)
- */
-export type BoxedRendererProps = Omit<AnnotationRendererProps<PdfAnnotationObject>, 'annotation'>;
 /**
  * Boxed renderer that encapsulates type safety internally.
- * The generic is erased - this is what the registry actually stores.
+ * The generic is erased -- this is what the registry actually stores.
  */
 export interface BoxedAnnotationRenderer {
-    /** Unique identifier for this renderer */
     id: string;
-    /** Combined match + render: returns null if doesn't match, JSX.Element if it does */
-    tryRender: (annotation: TrackedAnnotation, props: BoxedRendererProps) => JSX.Element | null;
+    matches: (annotation: PdfAnnotationObject) => boolean;
+    render: (props: AnnotationRendererProps) => JSX.Element;
+    vertexConfig?: VertexConfig<PdfAnnotationObject>;
+    zIndex?: number;
+    containerStyle?: (annotation: PdfAnnotationObject) => CSSProperties;
+    interactionDefaults?: {
+        isDraggable?: boolean;
+        isResizable?: boolean;
+        isRotatable?: boolean;
+        lockAspectRatio?: boolean;
+    };
+    useAppearanceStream?: boolean;
+    isDraggable?: (toolDraggable: boolean, context: {
+        isEditing: boolean;
+    }) => boolean;
+    onDoubleClick?: (annotationId: string, setEditingId: (id: string) => void) => void;
+    selectOverride?: (e: AnnotationInteractionEvent, annotation: TrackedAnnotation, helpers: SelectOverrideHelpers) => void;
+    hideSelectionMenu?: (annotation: PdfAnnotationObject) => boolean;
 }
 /**
  * Creates a boxed renderer from a typed entry.

package/dist/shared-preact/annotation-bounds.d.ts

@@ -0,0 +1,14 @@
+import { Rotation } from '@embedpdf/models';
+import { TrackedAnnotation } from '../lib/index.ts';
+export interface ScreenBounds {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Compute the screen-space bounding box of an annotation, correctly accounting
+ * for `noZoom` (constant pixel size regardless of zoom) and `noRotate`
+ * (visually upright regardless of page rotation) annotation flags.
+ */
+export declare function getAnnotationScreenBounds(annotation: TrackedAnnotation, scale: number, rotation: Rotation): ScreenBounds;

package/dist/shared-preact/components/annotation-container.d.ts

@@ -1,7 +1,7 @@
-import { PdfAnnotationObject } from '@embedpdf/models';
+import { PdfAnnotationObject, AnnotationAppearances } from '@embedpdf/models';
 import { TrackedAnnotation } from '../../lib/index.ts';
 import { JSX, CSSProperties } from '../../preact/adapter.ts';
-import { CustomAnnotationRenderer, ResizeHandleUI, AnnotationSelectionMenuRenderFn, VertexHandleUI, RotationHandleUI, GroupSelectionMenuRenderFn, BoxedAnnotationRenderer, SelectionOutline } from './types';
+import { CustomAnnotationRenderer, ResizeHandleUI, AnnotationSelectionMenuRenderFn, AnnotationInteractionEvent, VertexHandleUI, RotationHandleUI, GroupSelectionMenuRenderFn, BoxedAnnotationRenderer, SelectionOutline } from './types';
 import { VertexConfig } from '../types';
 interface AnnotationContainerProps<T extends PdfAnnotationObject> {
     scale: number;
@@ -11,8 +11,12 @@ interface AnnotationContainerProps<T extends PdfAnnotationObject> {
     pageWidth: number;
     pageHeight: number;
     trackedAnnotation: TrackedAnnotation<T>;
-    children: JSX.Element | ((annotation: T) => JSX.Element);
+    children: JSX.Element | ((annotation: T, options: {
+        appearanceActive: boolean;
+    }) => JSX.Element);
     isSelected: boolean;
+    /** Whether the annotation is in editing mode (e.g., FreeText text editing) */
+    isEditing?: boolean;
     /** Whether multiple annotations are selected (container becomes passive) */
     isMultiSelected?: boolean;
     isDraggable: boolean;
@@ -25,7 +29,9 @@ interface AnnotationContainerProps<T extends PdfAnnotationObject> {
     /** @deprecated Use `selectionOutline.offset` instead */
     outlineOffset?: number;
     onDoubleClick?: (event: any) => void;
-    onSelect: (event: any) => void;
+    onSelect: (event: AnnotationInteractionEvent) => void;
+    /** Pre-rendered appearance stream images for AP mode rendering */
+    appearance?: AnnotationAppearances<Blob> | null;
     zIndex?: number;
     resizeUI?: ResizeHandleUI;
     vertexUI?: VertexHandleUI;
@@ -47,5 +53,5 @@ interface AnnotationContainerProps<T extends PdfAnnotationObject> {
  * When isMultiSelected is true, the container becomes passive - drag/resize
  * is handled by the GroupSelectionBox instead.
  */
-export declare function AnnotationContainer<T extends PdfAnnotationObject>({ scale, documentId, pageIndex, rotation, pageWidth, pageHeight, trackedAnnotation, children, isSelected, isMultiSelected, isDraggable, isResizable, isRotatable, lockAspectRatio, style, vertexConfig, selectionMenu, outlineOffset, onDoubleClick, onSelect, zIndex, resizeUI, vertexUI, rotationUI, selectionOutlineColor, selectionOutline, customAnnotationRenderer, groupSelectionMenu: _groupSelectionMenu, groupSelectionOutline: _groupSelectionOutline, annotationRenderers: _annotationRenderers, ...props }: AnnotationContainerProps<T>): JSX.Element;
+export declare function AnnotationContainer<T extends PdfAnnotationObject>({ scale, documentId, pageIndex, rotation, pageWidth, pageHeight, trackedAnnotation, children, isSelected, isEditing, isMultiSelected, isDraggable, isResizable, isRotatable, lockAspectRatio, style, vertexConfig, selectionMenu, outlineOffset, onDoubleClick, onSelect, appearance, zIndex, resizeUI, vertexUI, rotationUI, selectionOutlineColor, selectionOutline, customAnnotationRenderer, groupSelectionMenu: _groupSelectionMenu, groupSelectionOutline: _groupSelectionOutline, annotationRenderers: _annotationRenderers, ...props }: AnnotationContainerProps<T>): JSX.Element;
 export {};

package/dist/shared-preact/components/annotations/caret.d.ts

@@ -0,0 +1,24 @@
+import { MouseEvent } from '../../../preact/adapter.ts';
+import { Rect } from '@embedpdf/models';
+interface CaretProps {
+    /** Whether the annotation is selected */
+    isSelected: boolean;
+    /** Stroke colour */
+    strokeColor?: string;
+    /** 0 – 1 */
+    opacity?: number;
+    /** Bounding box of the annotation (PDF units) */
+    rect: Rect;
+    /** Current page zoom factor */
+    scale: number;
+    /** Click handler (used for selection) */
+    onClick?: (e: MouseEvent<SVGElement>) => void;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
+}
+/**
+ * Renders a PDF Caret annotation as an SVG ^ symbol using bezier curves
+ * that mirror the C++ appearance stream.
+ */
+export declare function Caret({ isSelected, strokeColor, opacity, rect, scale, onClick, appearanceActive, }: CaretProps): JSX.Element;
+export {};

package/dist/shared-preact/components/annotations/circle.d.ts

@@ -1,9 +1,9 @@
-import { MouseEvent, TouchEvent } from '../../../preact/adapter.ts';
+import { MouseEvent } from '../../../preact/adapter.ts';
 import { PdfAnnotationBorderStyle, Rect } from '@embedpdf/models';
 interface CircleProps {
     /** Whether the annotation is selected */
     isSelected: boolean;
-    /** Fill colour – defaults to PDFium’s black if omitted */
+    /** Fill colour – defaults to PDFium's black if omitted */
     color?: string;
     /** Stroke colour – defaults to same as fill when omitted */
     strokeColor?: string;
@@ -20,10 +20,12 @@ interface CircleProps {
     /** Current page zoom factor */
     scale: number;
     /** Click handler (used for selection) */
-    onClick?: (e: MouseEvent<SVGElement> | TouchEvent<SVGElement>) => void;
+    onClick?: (e: MouseEvent<SVGElement>) => void;
+    /** When true, AP canvas provides the visual; only render hit area */
+    appearanceActive?: boolean;
 }
 /**
  * Renders a PDF Circle annotation (ellipse) as SVG.
  */
-export declare function Circle({ color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, rect, scale, onClick, isSelected, }: CircleProps): JSX.Element;
+export declare function Circle({ color, strokeColor, opacity, strokeWidth, strokeStyle, strokeDashArray, rect, scale, onClick, isSelected, appearanceActive, }: CircleProps): JSX.Element;
 export {};