@linkurious/ogma-annotations 2.1.2 → 2.1.4

package/dist/types/Control-Cv1I3e3C.d.ts

@@ -0,0 +1,1621 @@
+import { GeometryObject, Feature, LineString, Geometry, Point as Point$2, Polygon as Polygon$1, FeatureCollection } from 'geojson';
+import { Point as Point$1, Size, Ogma, Node } from '@linkurious/ogma';
+import EventEmitter from 'eventemitter3';
+
+/** Types of annotations supported */
+type AnnotationType = "arrow" | "text" | "box" | "comment" | "polygon";
+/**
+ * Base properties for all annotations.
+ */
+interface AnnotationProps {
+    /** Type of annotation */
+    type: AnnotationType;
+    /** Optional style configuration */
+    style?: unknown;
+}
+/** Unique identifier type for annotations */
+type Id = string | number;
+/**
+ * Base interface for all annotation features.
+ * @template G - Geometry type
+ * @template P - Properties type
+ */
+interface AnnotationFeature<G extends GeometryObject = GeometryObject, P = AnnotationProps> extends Feature<G, P> {
+    /** Unique identifier for the annotation */
+    id: Id;
+}
+
+/**
+ * Hex color string in format #RGB or #RRGGBB
+ * @example "#fff" | "#ffffff" | "#F0A" | "#FF00AA"
+ */
+type HexColor = `#${string}`;
+/**
+ * RGB color string in format rgb(r, g, b)
+ * @example "rgb(255, 0, 0)" | "rgb(128, 128, 128)"
+ */
+type RgbColor = `rgb(${number}, ${number}, ${number})` | `rgb(${number},${number},${number})`;
+/**
+ * RGBA color string in format rgba(r, g, b, a)
+ * @example "rgba(255, 0, 0, 1)" | "rgba(128, 128, 128, 0.5)"
+ */
+type RgbaColor = `rgba(${number}, ${number}, ${number}, ${number})` | `rgba(${number},${number},${number},${number})`;
+/**
+ * Any valid color format
+ */
+type Color = HexColor | RgbColor | RgbaColor | "transparent" | "none" | string;
+/**
+ * Type guard to check if a string is a valid hex color
+ */
+declare function isHexColor(color: string): color is HexColor;
+/**
+ * Type guard to check if a string is a valid RGB color
+ */
+declare function isRgbColor(color: string): color is RgbColor;
+/**
+ * Type guard to check if a string is a valid RGBA color
+ */
+declare function isRgbaColor(color: string): color is RgbaColor;
+/**
+ * Type guard to check if a string is a valid color
+ */
+declare function isColor(color: string): color is Color;
+/**
+ * Safely cast a string to a Color type with runtime validation
+ * @throws {Error} if the color format is invalid
+ */
+declare function asColor(color: string): Color;
+/**
+ * Safely cast a string to a HexColor type with runtime validation
+ * @throws {Error} if the color format is invalid
+ */
+declare function asHexColor(color: string): HexColor;
+/**
+ * Safely cast a string to an RgbColor type with runtime validation
+ * @throws {Error} if the color format is invalid
+ */
+declare function asRgbColor(color: string): RgbColor;
+/**
+ * Safely cast a string to an RgbaColor type with runtime validation
+ * @throws {Error} if the color format is invalid
+ */
+declare function asRgbaColor(color: string): RgbaColor;
+
+/** Stroke style options for annotations */
+type StrokeOptions = {
+    /** Type of stroke: plain, dashed, or none */
+    strokeType?: StrokeType;
+    /** Stroke color: #f00, yellow... */
+    strokeColor?: Color;
+    /** Stroke width */
+    strokeWidth?: number;
+};
+/** Stroke types available for annotations */
+type StrokeType = "plain" | "dashed" | "none";
+/** Stroke style for arrow annotations */
+type Stroke = {
+    /** Stroke type */
+    type: StrokeType;
+    /** Stroke color */
+    color: Color;
+    /** Stroke width */
+    width: number;
+};
+type StrokeStyle = Stroke;
+
+declare const NONE = -1;
+declare const EVT_DRAG = "dragging";
+declare const EVT_DRAG_START = "dragstart";
+declare const EVT_DRAG_END = "dragend";
+declare const EVT_CLICK = "click";
+declare const EVT_SELECT = "select";
+declare const EVT_UNSELECT = "unselect";
+declare const EVT_HOVER = "hover";
+declare const EVT_UNHOVER = "unhover";
+declare const EVT_REMOVE = "remove";
+declare const EVT_ADD = "add";
+declare const EVT_CANCEL_DRAWING = "cancelDrawing";
+declare const EVT_COMPLETE_DRAWING = "completeDrawing";
+declare const EVT_UPDATE = "update";
+declare const EVT_LINK = "link";
+declare const EVT_HISTORY = "history";
+declare const DATA_ATTR = "data-annotation";
+declare const handleDetectionThreshold = 5;
+declare const handleRadius = 3;
+/** @private */
+declare const LAYERS: {
+    SHAPES: number;
+    EDITOR: number;
+    HANDLES: number;
+};
+declare const SIDE_START: "start";
+declare const SIDE_END: "end";
+/** @private */
+declare const cursors: Record<string, Cursor>;
+declare const COMMENT_MODE_COLLAPSED = "collapsed";
+declare const COMMENT_MODE_EXPANDED = "expanded";
+declare const TEXT_LINE_HEIGHT = 1.2;
+declare const HL_BRIGHTEN = 0.2;
+/** @private */
+declare const TARGET_TYPES: {
+    TEXT: "text";
+    NODE: "node";
+    BOX: "box";
+    COMMENT: "comment";
+    POLYGON: "polygon";
+    ANNOTATION: "annotation";
+    EDGE: "edge";
+};
+/** Default send button icon (paper plane) */
+declare const DEFAULT_SEND_ICON = "<svg viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n  <path d=\"M22 2L11 13M22 2L15 22L11 13M22 2L2 9L11 13\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>";
+declare const DEFAULT_EDIT_ICON = "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M12 6.00015H7.33333C6.97971 6.00015 6.64057 6.14063 6.39052 6.39068C6.14048 6.64072 6 6.97986 6 7.33348V16.6668C6 17.0204 6.14048 17.3596 6.39052 17.6096C6.64057 17.8597 6.97971 18.0002 7.33333 18.0002H16.6667C17.0203 18.0002 17.3594 17.8597 17.6095 17.6096C17.8595 17.3596 18 17.0204 18 16.6668V12.0002M16.25 5.75015C16.5152 5.48493 16.8749 5.33594 17.25 5.33594C17.6251 5.33594 17.9848 5.48493 18.25 5.75015C18.5152 6.01537 18.6642 6.37508 18.6642 6.75015C18.6642 7.12522 18.5152 7.48493 18.25 7.75015L12.2413 13.7595C12.083 13.9176 11.8875 14.0334 11.6727 14.0962L9.75733 14.6562C9.69997 14.6729 9.63916 14.6739 9.58127 14.6591C9.52339 14.6442 9.47055 14.6141 9.4283 14.5719C9.38604 14.5296 9.35593 14.4768 9.3411 14.4189C9.32627 14.361 9.32727 14.3002 9.344 14.2428L9.904 12.3275C9.96702 12.1129 10.083 11.9175 10.2413 11.7595L16.25 5.75015Z\" stroke=\"#1A70E5\" stroke-width=\"1.33333\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n";
+
+/** 2D coordinate */
+type Point = {
+    x: number;
+    y: number;
+};
+/** @private */
+type Vector = Point;
+/**
+ * Bounding box object, with the following properties:
+ * - [0]: min x
+ * - [1]: min y
+ * - [2]: max x
+ * - [3]: max y
+ */
+type Bounds = [number, number, number, number];
+
+type TargetType = (typeof TARGET_TYPES)[keyof typeof TARGET_TYPES];
+type Side = typeof SIDE_START | typeof SIDE_END;
+/** Arrow snapped to the center or perimeter of a node. */
+type NodeMagnet = {
+    type: "node";
+    center: boolean;
+};
+/** Arrow snapped at parametric position t (0–1) along an edge path. */
+type EdgeMagnet = {
+    type: "edge";
+    t: number;
+};
+/**
+ * Arrow snapped to a rectangular annotation (text, box, comment).
+ * nx/ny are center-relative fractions multiplied by width/height:
+ *   left-center  = { nx: -0.5, ny: 0 }
+ *   right-center = { nx:  0.5, ny: 0 }
+ *   center       = { nx:  0,   ny: 0 }
+ */
+type BoxMagnet = {
+    type: "box";
+    nx: number;
+    ny: number;
+};
+/**
+ * Arrow snapped to a polygon annotation.
+ * rx/ry are 0–1 fractions of the polygon's bounding box from its top-left corner.
+ */
+type PolygonMagnet = {
+    type: "polygon";
+    rx: number;
+    ry: number;
+};
+type Magnet = NodeMagnet | EdgeMagnet | BoxMagnet | PolygonMagnet;
+/** Link between an arrow and a text or node */
+interface Link {
+    /** arrow attached to the text or node */
+    arrow: Id;
+    /** id of the text the arrow is attached to */
+    id: Id;
+    /**  On which end the arrow is tighten to the text */
+    side: Side;
+    /** id of the text or node  the arrow is attached to */
+    target: Id;
+    /** Text or node */
+    targetType: TargetType;
+    /** Typed snap point — semantics depend on targetType, see Magnet union. */
+    magnet: Magnet;
+}
+/**
+ * Serialized link stored inside arrow.properties.link.
+ * Uses plain { x, y } for backward compatibility with saved annotations.
+ * Converted to the internal Magnet type by Links.add().
+ */
+type ExportedLink = {
+    id: Id;
+    side: Side;
+    type: TargetType;
+    magnet?: Point;
+};
+
+/** Extremity types for arrow annotations. */
+type Extremity = "none" | "arrow" | "arrow-plain" | "dot" | "halo-dot";
+/**
+ * Styles specific to arrow annotations.
+ */
+interface ArrowStyles extends StrokeOptions {
+    /** Tail extremity style */
+    tail?: Extremity;
+    /** Head extremity style */
+    head?: Extremity;
+}
+interface ArrowProperties extends AnnotationProps {
+    type: "arrow";
+    style?: ArrowStyles;
+    link?: Partial<Record<Side, ExportedLink>>;
+}
+/**
+ * Arrow annotation feature. Represents a directed line between two points,
+ * can connect a textbox to a shape.
+ */
+interface Arrow extends AnnotationFeature<LineString, ArrowProperties> {
+}
+declare const isArrow: (a: AnnotationFeature<Geometry, AnnotationProps>) => a is Arrow;
+/**
+ * @private
+ * @param a Arrow annotation
+ * @param point Point to test
+ * @param threshold Detection threshold
+ * @returns True if the point is on the arrow line within the given threshold
+ */
+declare function detectArrow(a: Arrow, point: Point$1, threshold: number): boolean;
+/**
+ * Default style configuration for arrow annotations.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   strokeType: "plain",
+ *   strokeColor: "#202020",
+ *   strokeWidth: 1,
+ *   head: "none",
+ *   tail: "none"
+ * }
+ * ```
+ */
+declare const defaultArrowStyle: ArrowStyles;
+/**
+ * Default options for creating new Arrow annotations.
+ * Contains the default arrow structure with {@link defaultArrowStyle}.
+ */
+declare const defaultArrowOptions: Arrow;
+declare const createArrow: (x0?: number, y0?: number, x1?: number, y1?: number, styles?: {
+    /** Tail extremity style */
+    tail?: Extremity | undefined;
+    /** Head extremity style */
+    head?: Extremity | undefined;
+    strokeType?: StrokeType | undefined;
+    strokeColor?: string | undefined;
+    strokeWidth?: number | undefined;
+}) => Arrow;
+
+/** Styles specific to box annotations. */
+interface BoxStyle extends StrokeOptions {
+    /** background color: empty for transparent #f00, yellow...*/
+    background?: Color;
+    /** padding around the box */
+    padding?: number;
+    /** border radius */
+    borderRadius?: number;
+    /** if true, the box scales with zoom. Default is true */
+    scaled?: boolean;
+    /** box shadow in CSS format, e.g. "0px 4px 6px rgba(0, 0, 0, 0.1)" */
+    boxShadow?: string;
+}
+/** Properties specific to box annotations. */
+interface BoxProperties extends AnnotationProps {
+    type: "box";
+    /** Width of the box */
+    width: number;
+    /** Height of the box */
+    height: number;
+    /** Style options for the box */
+    style?: BoxStyle;
+}
+/**
+ * Box annotation feature
+ */
+interface Box extends AnnotationFeature<Point$2, BoxProperties> {
+}
+declare const isBox: (a: AnnotationFeature<Geometry, AnnotationProps>) => a is Box;
+/** @private */
+declare function detectBox(a: Box, p: Point, sin?: number, cos?: number, threshold?: number): boolean;
+/**
+ * Default style configuration for box annotations.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   background: "#f5f5f5",
+ *   strokeWidth: 0,
+ *   borderRadius: 8,
+ *   padding: 16,
+ *   strokeType: "plain"
+ * }
+ * ```
+ */
+declare const defaultBoxStyle: BoxStyle;
+/**
+ * Default options for creating new Box annotations.
+ * Contains the default box structure with {@link defaultBoxStyle}.
+ */
+declare const defaultBoxOptions: Box;
+declare const createBox: (x?: number, y?: number, width?: number, height?: number, styles?: Partial<BoxStyle>) => Box;
+
+interface TextStyle extends BoxStyle {
+    /** Helvetica, sans-serif...  */
+    font?: string;
+    /** Font size, in pixels */
+    fontSize?: number | string;
+    /** text color: #f00, yellow...*/
+    color?: Color;
+    /** background color: empty for transparent #f00, yellow...*/
+    background?: Color;
+    /** padding around the text */
+    padding?: number;
+    /** Text box border radius */
+    borderRadius?: number;
+    /** When true, text maintains constant size regardless of zoom level */
+    fixedSize?: boolean;
+    /** Opt-in: when true, corner/edge-drag resize also updates fontScale, so
+     * the rendered font size scales with the box instead of the text
+     * rewrapping/truncating. Only set by defaultStickyNoteStyle. */
+    scaleFontOnResize?: boolean;
+    /** Accumulated multiplier applied to fontSize at render time:
+     * effectiveFontSize = fontSize * (fontScale ?? 1). Updated incrementally
+     * by TextHandler's corner/edge drag when scaleFontOnResize is true;
+     * absent (≡ 1) for every annotation that doesn't opt in. */
+    fontScale?: number;
+    /**
+     * Ghost text shown (via the textarea's native `placeholder` attribute)
+     * while `content` is empty - disappears the instant the user types, no
+     * selection/focus tricks needed. Overrides the global
+     * `ControllerOptions.textPlaceholder` for this annotation.
+     */
+    placeholder?: string;
+    /** Bold the rendered/edited text. Absent (≡ "normal") for every
+     * annotation that doesn't opt in - no italic, no other weights for v1. */
+    fontWeight?: "normal" | "bold";
+    /**
+     * Whether to render `properties.author` as a one-line, ellipsis-truncated
+     * signature at the bottom of the box. Toggled by `TextStyleToolbar`'s
+     * author-visibility cell. No-op when `properties.author` is unset or
+     * blank. Hidden (≡ false) by default.
+     */
+    showAuthor?: boolean;
+    /**
+     * Per-annotation override for the author line's appearance. Overrides
+     * the global `ControllerOptions.authorStyle` for this annotation only -
+     * same precedence pattern as `placeholder` vs
+     * `ControllerOptions.textPlaceholder`. Falls back to a small built-in
+     * default (`DEFAULT_AUTHOR_STYLE` in `renderer/shapes/text.ts`) for any
+     * field neither this nor the global option sets.
+     */
+    authorStyle?: Partial<AuthorLineStyle>;
+}
+/** Style overrides for the author line rendered under a Text's content
+ * when `showAuthor` is true and `properties.author` is non-empty. Only
+ * the line-level subset of `TextStyle` - box properties (background,
+ * padding, borderRadius...) don't apply to it. */
+type AuthorLineStyle = Pick<TextStyle, "font" | "fontSize" | "color" | "fontWeight">;
+interface TextProperties extends Omit<BoxProperties, "type"> {
+    type: "text";
+    /**text to display*/
+    content: string;
+    /** Author/signature line shown under the content when `style.showAuthor`
+     * is true. Set by the host app (via `properties.author` at creation or
+     * `control.update()`) - no built-in UI writes this string. */
+    author?: string;
+    /** Width of the text box */
+    width: number;
+    /** Height of the text box */
+    height: number;
+    style?: TextStyle;
+}
+/**
+ * Text annotation feature, represents a text box at a specific position
+ */
+interface Text extends AnnotationFeature<Point$2, TextProperties> {
+}
+declare const isText: (a: AnnotationFeature<Geometry, AnnotationProps>) => a is Text;
+/**
+ * Heuristic "is this Text a sticky note" check. Sticky notes are not a
+ * distinct annotation type - they're `Text` created via
+ * `Control.enableStickyNoteDrawing()` with `defaultStickyNoteStyle` (see
+ * `api/drawing.ts`) - so there is no dedicated marker to check yet.
+ *
+ * Checks two of that preset's characteristic style values rather than just
+ * `scaleFontOnResize` alone: that flag's own doc comment above notes it's
+ * "only set by defaultStickyNoteStyle", but a host app is free to set it
+ * manually on a plain Text too, so pairing it with `placeholder` (which -
+ * unlike `content` - never gets cleared by typing) cuts down on that
+ * false-positive risk. Still a heuristic: a host that overrides
+ * `styles.stickyNote.placeholder` when calling `enableStickyNoteDrawing`/
+ * `AnnotationToolbar` will miss here.
+ *
+ * Kept as a single function (not inlined at each call site) so swapping in
+ * a dedicated marker later - e.g. a `style.preset` field - is a one-place
+ * change.
+ */
+declare const isStickyNote: (a: Text) => boolean;
+/**
+ * Default style configuration for text annotations.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   font: "sans-serif",
+ *   fontSize: 18,
+ *   color: "#505050",
+ *   background: "#f5f5f5",
+ *   strokeWidth: 0,
+ *   borderRadius: 8,
+ *   padding: 16,
+ *   strokeType: "plain",
+ *   fixedSize: false
+ * }
+ * ```
+ */
+declare const defaultTextStyle: TextStyle;
+/**
+ * Default options for creating new Text annotations.
+ * Contains the default text structure with {@link defaultTextStyle}.
+ */
+declare const defaultTextOptions: Text;
+declare const createText: (x?: number, y?: number, width?: number, height?: number, content?: string, styles?: Partial<TextStyle>) => Text;
+/**
+ * Detects whether a point is within a text annotation's bounds.
+ * @private
+ * @param a Text annotation
+ * @param p Point to test
+ * @param threshold  Detection threshold
+ * @param sin Rotation sine
+ * @param cos Rotation cosine
+ * @param zoom Current zoom level
+ * @returns True if the point is within the text bounds, false otherwise
+ */
+declare function detectText(a: Text, p: Point, threshold?: number, sin?: number, cos?: number, zoom?: number): boolean;
+
+/**
+ * Style configuration for Comment annotations
+ */
+interface CommentStyle extends TextStyle {
+    /** Background color for collapsed icon (default: "#FFD700") */
+    iconColor?: Color;
+    /** Icon to display when collapsed (default: "💬") */
+    iconSymbol?: string;
+    /** Border color for collapsed icon */
+    iconBorderColor?: Color;
+    /** Border width for collapsed icon */
+    iconBorderWidth?: number;
+    /** Minimum height (default: 60px) */
+    minHeight?: number;
+    /** Maximum height before scrolling (default: 480px, undefined = no limit) */
+    maxHeight?: number;
+    /** Size when collapsed (default: 32px) */
+    iconSize?: number;
+    /** Zoom threshold below which comment auto-collapses (default: 0.5) */
+    collapseZoomThreshold?: number;
+    /** Show "send" button in edit mode (default: true) */
+    showSendButton?: boolean;
+    /** Auto-grow height with content (default: true) */
+    autoGrow?: boolean;
+    /** Show drop shadow on comment box (default: true) */
+    shadow?: boolean;
+    /** Expand to full width when selected (default: false) */
+    expandOnSelect?: boolean;
+    /**
+     * Connector-line behavior when the attachment point moves (default: "rigid").
+     * - "rigid": the comment translates by the same offset as the moved
+     *   attachment point — the arrow keeps its length/angle, whole callout moves.
+     * - "elastic": the comment stays put; the arrow re-anchors to the nearest
+     *   point on the comment box, so the line can stretch/rotate.
+     */
+    connectorMode?: "rigid" | "elastic";
+}
+/**
+ * Properties for Comment annotations
+ *
+ * Comments are specialized annotations that:
+ * - Always maintain fixed screen-space size
+ * - Always have at least one arrow pointing TO them
+ * - Can be collapsed (icon) or expanded (text box)
+ * - Support multiple arrows pointing to them
+ */
+interface CommentProps extends AnnotationProps {
+    type: "comment";
+    /** Text content (similar to text annotation) */
+    content: string;
+    /** Display mode: collapsed (icon) or expanded (text box) */
+    mode: typeof COMMENT_MODE_COLLAPSED | typeof COMMENT_MODE_EXPANDED;
+    /** Width in expanded mode (pixels) */
+    width: number;
+    /** Height (auto-grows with content, pixels) */
+    height: number;
+    /** Optional metadata */
+    author?: string;
+    timestamp?: Date;
+    /** Styling */
+    style?: CommentStyle;
+}
+/**
+ * Comment annotation type
+ * Geometry: Point (center position of comment box/icon)
+ *
+ * Note: Arrows are stored separately in Arrow features.
+ * Arrows reference comments via their link.start or link.end properties.
+ */
+interface Comment extends AnnotationFeature<Point$2, CommentProps> {
+}
+/**
+ * Type guard to check if an annotation is a Comment
+ */
+declare const isComment: (a: AnnotationFeature<Geometry, AnnotationProps>) => a is Comment;
+/**
+ * Default style for Comment annotations
+ *
+ * @example
+ * ```typescript
+ * {
+ *   // Box styling
+ *   background: "#FFFACD", // Light yellow (sticky note color)
+ *   padding: 8,
+ *   borderRadius: 4,
+ *   strokeColor: "#DDD",
+ *   strokeWidth: 1,
+ *   strokeType: "plain",
+ *
+ *   // Icon styling (collapsed mode)
+ *   iconColor: "#FFCB2F", // Gold
+ *   iconSymbol: "💬",
+ *   iconBorderColor: "#aaa",
+ *   iconBorderWidth: 2,
+ *
+ *   // Size properties
+ *   minHeight: 60,
+ *   iconSize: 32,
+ *
+ *   // Text styling
+ *   color: "#333",
+ *   font: "Arial, sans-serif",
+ *   fontSize: 12,
+ *
+ *   // Editing UI
+ *   showSendButton: true,
+ *   autoGrow: true,
+ *
+ *   // Visual effects
+ *   shadow: true,
+ *   expandOnSelect: false,
+ *
+ *   // Fixed size (always screen-aligned)
+ *   fixedSize: true
+ * }
+ * ```
+ */
+declare const defaultCommentStyle: CommentStyle;
+/**
+ * Default options for creating new Comments.
+ * Contains the default comment configuration with {@link defaultCommentStyle}.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   mode: "expanded",
+ *   width: 200,
+ *   height: 120,
+ *   content: "",
+ *   style: defaultCommentStyle
+ * }
+ * ```
+ */
+declare const defaultCommentOptions: Partial<CommentProps>;
+/**
+ * Create a new Comment annotation
+ *
+ * @param x - X coordinate of the comment box/icon center
+ * @param y - Y coordinate of the comment box/icon center
+ * @param content - Text content
+ * @param options - Optional configuration
+ * @returns New Comment feature
+ *
+ * @important This creates ONLY the comment box without an arrow. Since comments
+ * require at least one arrow, you should use {@link createCommentWithArrow}
+ * instead for programmatic creation. This function is primarily used internally
+ * by the interactive drawing handlers.
+ *
+ * @see createCommentWithArrow for creating comments programmatically
+ */
+declare function createComment(x: number, y: number, content: string, options?: Partial<CommentProps>): Comment;
+/**
+ * Toggle comment mode between collapsed and expanded
+ *
+ * @param comment - Comment to toggle
+ * @returns Updated comment with toggled mode
+ */
+declare function toggleCommentMode(comment: Comment): Comment;
+/**
+ * Detect if a point is within a comment's bounds
+ * @private
+ * @param comment - Comment to test
+ * @param point - Point to test
+ * @param threshold - Detection threshold in pixels
+ * @param zoom - Current zoom level
+ * @returns True if point is within comment bounds
+ */
+declare function detectComment(comment: Comment, point: Point, threshold: number | undefined, sin: number, cos: number, zoom?: number): boolean;
+/**
+ * Get the position (center) of a comment
+ *
+ * @param comment - Comment annotation
+ * @returns Center position
+ */
+declare function getCommentPosition(comment: Comment): Point;
+/**
+ * Get the dimensions of a comment based on its mode
+ *
+ * @param comment - Comment annotation
+ * @returns Width and height
+ */
+declare function getCommentSize(comment: Comment): Size;
+/**
+ * Calculate optimal zoom threshold for auto-collapse based on comment dimensions
+ *
+ * The threshold is computed so that the comment collapses when its screen-space
+ * size would be smaller than a minimum readable size.
+ *
+ * @param comment - Comment annotation
+ * @param minReadableWidth - Minimum readable width in pixels (default: 80)
+ * @returns Zoom threshold below which comment should collapse
+ *
+ * @example
+ * // A 200px wide comment with minReadable=80 will collapse at zoom < 0.4
+ * // because 200 * 0.4 = 80
+ */
+declare function calculateCommentZoomThreshold(comment: Comment, minReadableWidth?: number): number;
+/**
+ * Whether a comment's connector line should rigidly follow its attachment
+ * point (translate the comment by the same offset) rather than elastically
+ * re-anchoring to the nearest point on the comment box.
+ *
+ * @param comment - Comment annotation
+ * @returns True unless the comment's style explicitly sets `connectorMode: "elastic"`
+ */
+declare function isRigidConnector(comment: Comment): boolean;
+/**
+ * Get the effective zoom threshold for a comment
+ * Uses explicit threshold if set, otherwise calculates from dimensions
+ *
+ * @param comment - Comment annotation
+ * @returns Effective zoom threshold
+ */
+declare function getCommentZoomThreshold(comment: Comment): number;
+/**
+ * Create a comment with an arrow pointing to a target location
+ *
+ * This is the recommended way to create comments programmatically, as it ensures
+ * that the comment always has at least one arrow (which is required).
+ *
+ * @param targetX - X coordinate where the arrow points to
+ * @param targetY - Y coordinate where the arrow points to
+ * @param commentX - X coordinate of the comment box center
+ * @param commentY - Y coordinate of the comment box center
+ * @param content - Text content of the comment
+ * @param options - Optional configuration
+ * @param options.commentStyle - Style options for the comment
+ * @param options.arrowStyle - Style options for the arrow
+ * @returns Object containing the comment and arrow features
+ *
+ * @example
+ * ```typescript
+ * import { createCommentWithArrow } from '@linkurious/ogma-annotations';
+ *
+ * // Create a comment pointing to a node at (100, 100)
+ * const { comment, arrow } = createCommentWithArrow(
+ *   100, 100,           // Target position (where arrow points)
+ *   300, 50,            // Comment position
+ *   "Important node!",  // Comment text
+ *   {
+ *     commentStyle: {
+ *       style: {
+ *         background: "#FFFACD",
+ *         color: "#333"
+ *       }
+ *     },
+ *     arrowStyle: {
+ *       strokeColor: "#3498db",
+ *       strokeWidth: 2,
+ *       head: "arrow"
+ *     }
+ *   }
+ * );
+ *
+ * // Add both to the controller
+ * controller.add(comment);
+ * controller.add(arrow);
+ *
+ * // The arrow is automatically linked to the comment
+ * ```
+ */
+declare function createCommentWithArrow(targetX: number, targetY: number, commentX: number, commentY: number, content?: string, options?: {
+    commentStyle?: Partial<CommentProps>;
+    arrowStyle?: Partial<ArrowStyles>;
+}): {
+    comment: Comment;
+    arrow: Arrow;
+};
+
+interface PolygonStyle extends BoxStyle {
+}
+interface PolygonProperties extends AnnotationProps {
+    type: "polygon";
+    style?: PolygonStyle;
+}
+/**
+ * Polygon placed on the graph, use it to highlight areas
+ */
+interface Polygon extends AnnotationFeature<Polygon$1, PolygonProperties> {
+}
+declare const isPolygon: (a: AnnotationFeature<Geometry, AnnotationProps>) => a is Polygon;
+/**
+ * Point-in-polygon detection using ray casting algorithm
+ * @private
+ * @param polygon The polygon annotation
+ * @param point The point to test
+ * @param threshold Detection threshold in pixels
+ * @return True if the point is inside the polygon or within the threshold distance from its edges
+ */
+declare function detectPolygon(polygon: Polygon, point: Point, threshold?: number): boolean;
+/**
+ * Create a polygon annotation
+ */
+declare function createPolygon(coordinates: [number, number][][], properties?: Partial<Omit<PolygonProperties, "type">> & {
+    id?: Id;
+}): Polygon;
+/**
+ * Default style configuration for polygon annotations.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   background: "transparent",
+ *   strokeWidth: 2,
+ *   borderRadius: 8,
+ *   padding: 16,
+ *   strokeType: "plain",
+ *   strokeColor: "#000000"
+ * }
+ * ```
+ */
+declare const defaultPolygonStyle: PolygonStyle;
+/**
+ * Default polygon properties for creating new Polygon annotations.
+ * Contains the default polygon configuration with {@link defaultPolygonStyle}.
+ */
+declare const defaultPolygonProperties: PolygonProperties;
+
+/** Union type of all Annotation features */
+type Annotation = Arrow | Box | Text | Comment | Polygon;
+/** Collection of Annotations, GeoJSON FeatureCollection */
+interface AnnotationCollection extends FeatureCollection {
+    features: Annotation[];
+}
+/** Helper to check if a feature collection is an annotation collection */
+declare const isAnnotationCollection: (a: AnnotationFeature<Geometry, AnnotationProps> | FeatureCollection) => a is AnnotationCollection;
+/** Function type to get an Annotation by its id */
+type AnnotationGetter = (id: Id) => Annotation | undefined;
+
+/** Event related to multiple annotation features */
+interface FeaturesEvent {
+    /** Annotation IDs involved in the event */
+    ids: Id[];
+}
+/** Event related to a single annotation feature */
+interface FeatureEvent {
+    /** Annotation ID involved in the event */
+    id: Id;
+}
+/** Event related to a single annotation feature */
+interface ClickEvent {
+    /** Annotation ID involved in the event */
+    id?: Id;
+    /** Mouse position in pixel coordinates */
+    position: {
+        x: number;
+        y: number;
+    };
+}
+/** Event related to a single annotation feature */
+interface DragEvent {
+    /** Annotation ID involved in the event */
+    id: Id;
+    /** Current mouse position in pixel coordinates during the drag */
+    position: {
+        x: number;
+        y: number;
+    };
+}
+/** History stack change event */
+interface HistoryEvent {
+    /** Indicates if undo operation is available */
+    canUndo: boolean;
+    /** Indicates if redo operation is available */
+    canRedo: boolean;
+}
+type FeatureEvents = {
+    /**
+     * Event trigerred when selecting an annotation
+     * @param evt The annotation selected
+     */
+    [EVT_SELECT]: (evt: FeaturesEvent) => void;
+    /**
+     * Event trigerred when unselecting an annotation
+     * @param evt The annotation unselected
+     */
+    [EVT_UNSELECT]: (evt: FeaturesEvent) => void;
+    /**
+     * Event trigerred when removing an annotation
+     * @param evt The annotation removed
+     */
+    [EVT_REMOVE]: (evt: FeatureEvent) => void;
+    /**
+     * Event trigerred when adding an annotation
+     * @param evt The annotation added
+     */
+    [EVT_ADD]: (evt: FeatureEvent) => void;
+    /**
+     * Event trigerred when canceling drawing mode
+     */
+    [EVT_CANCEL_DRAWING]: () => void;
+    /**
+     * Event trigerred when completing a drawing operation
+     * @param evt Contains the ID of the completed annotation
+     */
+    [EVT_COMPLETE_DRAWING]: (evt: FeatureEvent) => void;
+    /**
+     * Event trigerred when updating an annotation.
+     * This fires after any modification including drag operations, style changes, scaling, etc.
+     * @param evt The updated annotation with all changes applied
+     */
+    [EVT_UPDATE]: (evt: Annotation) => void;
+    /**
+     * Event trigerred when linking an arrow to a node or annotation
+     * @param evt Contains the arrow and link details
+     */
+    [EVT_LINK]: (evt: {
+        arrow: Arrow;
+        link: Link;
+    }) => void;
+    /**
+     * Event trigerred when history state changes (after undo/redo operations)
+     * @param evt Contains boolean flags for undo/redo availability
+     */
+    [EVT_HISTORY]: (evt: HistoryEvent) => void;
+    /**
+     * Event triggered when a drag operation starts on an annotation
+     */
+    [EVT_DRAG_START]: (evt: DragEvent) => void;
+    /**
+     * Event triggered when a drag operation ends on an annotation
+     */
+    [EVT_DRAG_END]: (evt: DragEvent) => void;
+    /**
+     * Event triggered when a click completes on an annotation (mouseup without drag)
+     */
+    [EVT_CLICK]: (evt: ClickEvent) => void;
+};
+
+/**
+ * Options for the annotations control
+ */
+type ControllerOptions = {
+    /**
+     * The radius in which arrows are attracted
+     */
+    magnetRadius: number;
+    /**
+     * The margin in which the Texts are detected when looking for magnet points
+     */
+    detectMargin: number;
+    /**
+     * Display size of the magnet point
+     */
+    magnetHandleRadius: number;
+    /**
+     * Placeholder for the text input
+     */
+    textPlaceholder: string;
+    /**
+     * Editor-wide default style for every Text annotation's author line. Only
+     * applied when an annotation's `style.showAuthor` is true and
+     * `properties.author` is set; a given field here is overridden by that
+     * annotation's own `style.authorStyle` if set (see `TextStyle.authorStyle`).
+     */
+    authorStyle?: Partial<AuthorLineStyle>;
+    /**
+     * Minimum on-screen font size, in pixels, for a scalable (non-fixedSize)
+     * Text annotation's content or author line to actually be rendered.
+     * Below this, the text is skipped entirely (the box/background still
+     * renders) - avoids illegible sub-pixel text and the layout work that
+     * produces it. Ignored for `fixedSize` text (its on-screen size never
+     * shrinks with zoom) and during SVG/PNG export (export always renders
+     * in full, same as viewport culling). Set to 0 to disable.
+     */
+    minReadableFontSize: number;
+    /**
+     * Show send button in text editor
+     */
+    showSendButton: boolean;
+    /**
+     * Show edit button in text editor
+     */
+    showEditButton: boolean;
+    /**
+     * SVG icon for the send button in text editor
+     * Should be a complete SVG string (e.g., '<svg>...</svg>')
+     */
+    sendButtonIcon: string;
+    /**
+     * SVG icon for the edit button in text editor
+     * Should be a complete SVG string (e.g., '<svg>...</svg>')
+     */
+    editButtonIcon: string;
+    /**
+     * Minimum height of the arrow in units
+     */
+    minArrowHeight: number;
+    /**
+     * Maximum height of the arrow in units
+     */
+    maxArrowHeight: number;
+    /**
+     * Called to decide whether an annotation can be dragged, resized, restyled,
+     * text-edited, deleted, or re-linked. Defaults to always `true`. Selection
+     * (click to highlight, `getSelectedAnnotations()`) is unaffected - a
+     * non-editable annotation stays fully selectable, just not mutable.
+     *
+     * Keep this cheap and synchronous - it can run once per affected
+     * annotation on every relevant edit attempt. To react to a change that
+     * isn't reflected in the annotation's own data (e.g. a host-side
+     * "read-only mode" toggle), call `control.setOptions({ isEditable })`
+     * again with a new function reference - passing the same reference is a
+     * no-op.
+     */
+    isEditable: (annotation: Annotation) => boolean;
+    /**
+     * Called to decide whether an annotation is rendered (including in SVG
+     * export) and hit-testable (hover/select/drag via the mouse). Defaults to
+     * always `true`. A hidden annotation stays fully present in
+     * `getAnnotations()`, `getAnnotation()`, and `getSelectedAnnotations()` -
+     * visibility only controls what's drawn and clickable, not data access.
+     *
+     * Keep this cheap and synchronous - it can run once per annotation on
+     * every render pass while the view is changing (drag, pan, zoom). Same
+     * reactivity note as `isEditable` applies to changing this after the fact.
+     */
+    isVisible: (annotation: Annotation) => boolean;
+};
+type AnnotationOptions = {
+    handleSize: number;
+    placeholder?: string;
+};
+/** @private */
+type Cursor = "default" | "pointer" | "move" | "grab" | "grabbing" | "auto" | "resize" | "col-resize" | "row-resize" | "all-scroll" | "n-resize" | "e-resize" | "s-resize" | "w-resize" | "ne-resize" | "nw-resize" | "se-resize" | "sw-resize" | "ew-resize" | "ns-resize" | "nesw-resize" | "nwse-resize" | "alias" | "crosshair";
+type ClientMouseEvent = {
+    clientX: number;
+    clientY: number;
+};
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+/**
+ * Main controller class for managing annotations.
+ * It manages rendering and editing of annotations.
+ */
+declare class Control extends EventEmitter<FeatureEvents> {
+    private ogma;
+    private store;
+    private renderers;
+    private interactions;
+    private editor;
+    private links;
+    private index;
+    private drawing;
+    private snapping;
+    private selectionManager;
+    private historyManager;
+    private updateManager;
+    private commentManager;
+    constructor(ogma: Ogma, options?: Partial<ControllerOptions>);
+    private initializeRenderers;
+    private setupEvents;
+    private onRotate;
+    private onZoom;
+    private onLayout;
+    /**
+     * The underlying Ogma instance this controller was created with. Needed by
+     * UI built on top of `Control`'s public API (e.g. `TextAnnotationToolbar`)
+     * that must mount its own `ogma.layers.addOverlay(...)` layer rather than
+     * going through a renderer/handler internal to `Control`.
+     */
+    getOgma(): Ogma;
+    /**
+     * Current global annotation-rotation angle (radians) - see
+     * `TextStyle`/`Handles`' `counterRotation`. Needed alongside `getZoom()` by
+     * `TextAnnotationToolbar` to anchor its pill above a (possibly rotated)
+     * Text box's world-space bounds.
+     */
+    getRotation(): number;
+    /** Current zoom level - needed by `TextAnnotationToolbar` to convert a
+     * `fixedSize` Text annotation's screen-pixel dimensions back to graph
+     * units for its anchor-point math (same conversion `Handles` does). */
+    getZoom(): number;
+    /**
+     * Set the options for the controller
+     * @param options new Options
+     * @returns the updated options
+     */
+    setOptions(options?: Partial<ControllerOptions>): {
+        showSendButton: boolean;
+        showEditButton: boolean;
+        sendButtonIcon: string;
+        editButtonIcon: string;
+        minArrowHeight: number;
+        maxArrowHeight: number;
+        detectMargin: number;
+        magnetRadius: number;
+        magnetHandleRadius: number;
+        textPlaceholder: string;
+        authorStyle?: Partial<AuthorLineStyle> | undefined;
+        minReadableFontSize: number;
+        isEditable: (annotation: Annotation) => boolean;
+        isVisible: (annotation: Annotation) => boolean;
+    };
+    /** Can `id` be dragged/resized/restyled/text-edited/deleted/re-linked
+     * right now, per the `isEditable` option? `false` for an unknown id. */
+    isAnnotationEditable(id: Id): boolean;
+    /** Is `id` rendered and hit-testable right now, per the `isVisible`
+     * option? `false` for an unknown id. */
+    isAnnotationVisible(id: Id): boolean;
+    /**
+     * (Re-)apply `id`'s handler attachment (drag/resize/text-edit) to match
+     * `isEditable` right now, instead of waiting for a deselect/reselect -
+     * this is the same call a selection change makes internally. Call it
+     * directly after changing whatever external state your `isEditable`
+     * predicate depends on (e.g. a `locked` flag kept outside the
+     * annotation - see the lock-toolbar-item.ts example): closes any open
+     * text editor and detaches the handler if `id` just became
+     * non-editable, or attaches it if `id` is selected and just became
+     * editable again.
+     */
+    editFeature(id: Id): this;
+    /**
+     * Add an annotation to the controller
+     * @param annotation The annotation to add
+     */
+    add(annotation: Annotation | AnnotationCollection): this;
+    /**
+     * Remove an annotation or an array of annotations from the controller
+     * @param annotation The annotation(s) to remove
+     */
+    remove(annotation: Annotation | AnnotationCollection): this;
+    /**
+     * Undo the last change
+     * @returns true if undo was successful, false if no changes to undo
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone change
+     * @returns true if redo was successful, false if no changes to redo
+     */
+    redo(): boolean;
+    /**
+     * Check if there are changes to undo
+     * @returns true if undo is possible
+     */
+    canUndo(): boolean;
+    /**
+     * Check if there are changes to redo
+     * @returns true if redo is possible
+     */
+    canRedo(): boolean;
+    /**
+     * Clear the undo/redo history
+     */
+    clearHistory(): void;
+    /**
+     * Get all annotations in the controller
+     * @returns A FeatureCollection containing all annotations
+     */
+    getAnnotations(): AnnotationCollection;
+    /**
+     * Select one or more annotations by id
+     * @param annotations The id(s) of the annotation(s) to select
+     * @returns this for chaining
+     */
+    select(annotations: Id | Id[]): this;
+    /**
+     * Unselect one or more annotations, or all if no ids provided
+     * @param annotations The id(s) of the annotation(s) to unselect, or undefined to unselect all
+     * @returns this for chaining
+     */
+    unselect(annotations?: Id | Id[]): this;
+    /**
+     * Cancel the current drawing operation
+     * @returns this for chaining
+     */
+    cancelDrawing(): this;
+    /**
+     * Enable arrow drawing mode - the recommended way to add arrows.
+     *
+     * Call this method when the user clicks an "Add Arrow" button. The control will:
+     * 1. Wait for the next mousedown event
+     * 2. Create an arrow at that position with the specified style
+     * 3. Start the interactive drawing process
+     * 4. Clean up automatically when done
+     *
+     * **This is the recommended API for 99% of use cases.** Only use `startArrow()`
+     * if you need to implement custom mouse handling or positioning logic.
+     *
+     * @example
+     * ```ts
+     * addArrowButton.addEventListener('click', () => {
+     *   control.enableArrowDrawing({ strokeColor: '#3A03CF', strokeWidth: 2 });
+     * });
+     * ```
+     *
+     * @param style Arrow style options
+     * @returns this for chaining
+     * @see startArrow for low-level programmatic control
+     */
+    enableArrowDrawing(style?: Partial<Arrow["properties"]["style"]>): this;
+    /**
+     * Enable text drawing mode - the recommended way to add text annotations.
+     *
+     * Call this method when the user clicks an "Add Text" button. The control will:
+     * 1. Wait for the next mousedown event
+     * 2. Create a text box at that position with the specified style
+     * 3. Start the interactive drawing/editing process
+     * 4. Clean up automatically when done
+     *
+     * **This is the recommended API for 99% of use cases.** Only use `startText()`
+     * if you need to implement custom mouse handling or positioning logic.
+     *
+     * @example
+     * ```ts
+     * addTextButton.addEventListener('click', () => {
+     *   control.enableTextDrawing({ color: '#3A03CF', fontSize: 24 });
+     * });
+     * ```
+     *
+     * @param style Text style options
+     * @returns this for chaining
+     * @see startText for low-level programmatic control
+     */
+    enableTextDrawing(style?: Partial<Text["properties"]["style"]>): this;
+    /**
+     * Enable box drawing mode - the recommended way to add boxes.
+     *
+     * Call this method when the user clicks an "Add Box" button. The control will:
+     * 1. Wait for the next mousedown event
+     * 2. Create a box at that position with the specified style
+     * 3. Start the interactive drawing process (drag to size)
+     * 4. Clean up automatically when done
+     *
+     * **This is the recommended API for 99% of use cases.** Only use `startBox()`
+     * if you need to implement custom mouse handling or positioning logic.
+     *
+     * @example
+     * ```ts
+     * addBoxButton.addEventListener('click', () => {
+     *   control.enableBoxDrawing({ background: '#EDE6FF', borderRadius: 8 });
+     * });
+     * ```
+     *
+     * @param style Box style options
+     * @returns this for chaining
+     * @see startBox for low-level programmatic control
+     */
+    enableBoxDrawing(style?: Partial<Box["properties"]["style"]>): this;
+    /**
+     * Enable polygon drawing mode - the recommended way to add polygons.
+     *
+     * Call this method when the user clicks an "Add Polygon" button. The control will:
+     * 1. Wait for the next mousedown event
+     * 2. Create a polygon starting at that position with the specified style
+     * 3. Start the interactive drawing process (click points to draw shape)
+     * 4. Clean up automatically when done
+     *
+     * **This is the recommended API for 99% of use cases.** Only use `startPolygon()`
+     * if you need to implement custom mouse handling or positioning logic.
+     *
+     * @example
+     * ```ts
+     * addPolygonButton.addEventListener('click', () => {
+     *   control.enablePolygonDrawing({ strokeColor: '#3A03CF', background: 'rgba(58, 3, 207, 0.15)' });
+     * });
+     * ```
+     *
+     * @param style Polygon style options
+     * @returns this for chaining
+     * @see startPolygon for low-level programmatic control
+     */
+    enablePolygonDrawing(style?: Partial<Polygon["properties"]["style"]>): this;
+    /**
+     * Enable comment drawing mode - the recommended way to add comments.
+     *
+     * Call this method when the user clicks an "Add Comment" button. The control will:
+     * 1. Wait for the next mousedown event
+     * 2. Create a comment with an arrow pointing to that position
+     * 3. Smart positioning: automatically finds the best placement for the comment box
+     * 4. Start the interactive editing process
+     * 5. Clean up automatically when done
+     *
+     * **This is the recommended API for 99% of use cases.** Only use `startComment()`
+     * if you need to implement custom mouse handling or positioning logic.
+     *
+     * @example
+     * ```ts
+     * addCommentButton.addEventListener('click', () => {
+     *   control.enableCommentDrawing({
+     *     commentStyle: { color: '#3A03CF', background: '#EDE6FF' },
+     *     arrowStyle: { strokeColor: '#3A03CF', head: 'halo-dot' }
+     *   });
+     * });
+     * ```
+     *
+     * @param options Drawing options including offsets and styles
+     * @param options.offsetX Manual X offset for comment placement (overrides smart positioning)
+     * @param options.offsetY Manual Y offset for comment placement (overrides smart positioning)
+     * @param options.commentStyle Style options for the comment box
+     * @param options.arrowStyle Style options for the arrow
+     * @returns this for chaining
+     * @see startComment for low-level programmatic control
+     */
+    enableCommentDrawing(options?: {
+        offsetX?: number;
+        offsetY?: number;
+        commentStyle?: Partial<CommentProps>;
+        arrowStyle?: Partial<ArrowProperties>;
+    }): this;
+    /**
+     * Enable sticky note drawing mode - drops a plain, resizable text box
+     * (empty content, "Quick note…" ghost placeholder, no connector arrow)
+     * like a Miro sticky note, unlike `enableCommentDrawing`. It's a regular
+     * `text` annotation, so it's placed the same interactive way as
+     * `enableBoxDrawing`/`enableTextDrawing`: click for a default-size square,
+     * or drag to size it - either way it keeps the usual corner/edge drag
+     * handles to resize it afterward.
+     *
+     * Call this method when the user clicks an "Add sticky note" button. The
+     * control will:
+     * 1. Wait for the next mousedown event
+     * 2. Create the note at that position and start the interactive
+     *    corner-drag, already selected
+     * 3. On release: a plain click (no drag) gets a default square size, a
+     *    drag gets sized to match instead - either way it drops straight
+     *    into editing (the placeholder is just ghost text, so typing
+     *    immediately replaces it)
+     * 4. Clean up automatically when done
+     *
+     * @example
+     * ```ts
+     * addStickyNoteButton.addEventListener('click', () => {
+     *   control.enableStickyNoteDrawing({ background: '#FFEB99' });
+     * });
+     * ```
+     *
+     * @param style Sticky note style options (merged over the sticky note defaults)
+     * @returns this for chaining
+     * @see startStickyNote for low-level programmatic control
+     */
+    enableStickyNoteDrawing(style?: Partial<Text["properties"]["style"]>): this;
+    /**
+     * Enable erase mode: every click on an annotation deletes it immediately.
+     * Stays armed across multiple clicks until `disableEraseMode()` is called,
+     * or another drawing tool is enabled / `cancelDrawing()` is called.
+     *
+     * @returns this for chaining
+     * @see disableEraseMode to turn erase mode off
+     */
+    enableEraseMode(): this;
+    /** Turn erase mode off. No-op if it isn't active. */
+    disableEraseMode(): this;
+    /** Whether erase mode is currently active. */
+    isEraseModeActive(): boolean;
+    /**
+     * Place a pre-created annotation by moving it with the cursor.
+     * The annotation follows the mouse until the user clicks to place it.
+     * Press Escape to cancel.
+     *
+     * @param annotation The text or box annotation to place
+     * @returns this for chaining
+     */
+    enablePlacement(annotation: Text | Box): this;
+    /**
+     * **Advanced API:** Programmatically start drawing a comment at specific coordinates.
+     *
+     * This is a low-level method that gives you full control over the drawing process.
+     * You must handle mouse events and create the comment object yourself.
+     *
+     * **For most use cases, use `enableCommentDrawing()` instead** - it handles all
+     * mouse events and annotation creation automatically.
+     *
+     * Use this method only when you need:
+     * - Custom mouse event handling (e.g., custom cursors, right-click menus)
+     * - Programmatic placement without user interaction
+     * - Integration with custom UI frameworks
+     *
+     * @example
+     * ```ts
+     * // Custom cursor example
+     * ogma.setOptions({ cursor: { default: 'crosshair' } });
+     * ogma.events.once('mousedown', (evt) => {
+     *   const { x, y } = ogma.view.screenToGraphCoordinates(evt);
+     *   const comment = createComment(x, y, 'My comment', { color: '#3A03CF' });
+     *   control.startComment(x, y, comment);
+     * });
+     * ```
+     *
+     * @param x X coordinate to start drawing
+     * @param y Y coordinate to start drawing
+     * @param comment The comment annotation to add
+     * @param options Drawing options including offsets and styles
+     * @returns this for chaining
+     * @see enableCommentDrawing for the recommended high-level API
+     */
+    startComment(x: number, y: number, comment: Comment, options?: {
+        offsetX?: number;
+        offsetY?: number;
+        commentStyle?: Partial<CommentProps>;
+        arrowStyle?: Partial<ArrowProperties>;
+    }): this;
+    /**
+     * **Advanced API:** Programmatically start drawing a sticky note at
+     * specific coordinates - same interactive corner-drag as `startBox`.
+     * You must handle mouse events yourself (or immediately release/complete
+     * it via the same events `enableStickyNoteDrawing` would).
+     *
+     * **For most use cases, use `enableStickyNoteDrawing()` instead.**
+     *
+     * @param x X coordinate for the note's top-left corner
+     * @param y Y coordinate for the note's top-left corner
+     * @param style Sticky note style options
+     * @returns this for chaining
+     * @see enableStickyNoteDrawing for the recommended high-level API
+     */
+    startStickyNote(x: number, y: number, style?: Partial<Text["properties"]["style"]>): this;
+    /**
+     * **Advanced API:** Programmatically start drawing a box at specific coordinates.
+     *
+     * This is a low-level method that gives you full control over the drawing process.
+     * You must handle mouse events and optionally create the box object yourself.
+     *
+     * **For most use cases, use `enableBoxDrawing()` instead** - it handles all
+     * mouse events and annotation creation automatically.
+     *
+     * Use this method only when you need:
+     * - Custom mouse event handling (e.g., custom cursors, right-click menus)
+     * - Programmatic placement without user interaction
+     * - Integration with custom UI frameworks
+     *
+     * @example
+     * ```ts
+     * // Custom cursor example
+     * ogma.setOptions({ cursor: { default: 'crosshair' } });
+     * ogma.events.once('mousedown', (evt) => {
+     *   const { x, y } = ogma.view.screenToGraphCoordinates(evt);
+     *   const box = createBox(x, y, 100, 50, { background: '#EDE6FF' });
+     *   control.startBox(x, y, box);
+     * });
+     * ```
+     *
+     * @param x X coordinate for the box origin
+     * @param y Y coordinate for the box origin
+     * @param box The box annotation to add (optional, will be created if not provided)
+     * @returns this for chaining
+     * @see enableBoxDrawing for the recommended high-level API
+     */
+    startBox(x: number, y: number, box?: Box): this;
+    /**
+     * **Advanced API:** Programmatically start drawing an arrow at specific coordinates.
+     *
+     * This is a low-level method that gives you full control over the drawing process.
+     * You must handle mouse events and optionally create the arrow object yourself.
+     *
+     * **For most use cases, use `enableArrowDrawing()` instead** - it handles all
+     * mouse events and annotation creation automatically.
+     *
+     * Use this method only when you need:
+     * - Custom mouse event handling (e.g., custom cursors, right-click menus)
+     * - Programmatic placement without user interaction
+     * - Integration with custom UI frameworks
+     *
+     * @example
+     * ```ts
+     * // Custom cursor example
+     * ogma.setOptions({ cursor: { default: 'crosshair' } });
+     * ogma.events.once('mousedown', (evt) => {
+     *   const { x, y } = ogma.view.screenToGraphCoordinates(evt);
+     *   const arrow = createArrow(x, y, x, y, { strokeColor: '#3A03CF' });
+     *   control.startArrow(x, y, arrow);
+     * });
+     * ```
+     *
+     * @param x X coordinate for the arrow start
+     * @param y Y coordinate for the arrow start
+     * @param arrow The arrow annotation to add (optional, will be created if not provided)
+     * @returns this for chaining
+     * @see enableArrowDrawing for the recommended high-level API
+     */
+    startArrow(x: number, y: number, arrow?: Arrow): this;
+    /**
+     * **Advanced API:** Programmatically start drawing a text annotation at specific coordinates.
+     *
+     * This is a low-level method that gives you full control over the drawing process.
+     * You must handle mouse events and optionally create the text object yourself.
+     *
+     * **For most use cases, use `enableTextDrawing()` instead** - it handles all
+     * mouse events and annotation creation automatically.
+     *
+     * Use this method only when you need:
+     * - Custom mouse event handling (e.g., custom cursors, right-click menus)
+     * - Programmatic placement without user interaction
+     * - Integration with custom UI frameworks
+     *
+     * @example
+     * ```ts
+     * // Custom cursor example
+     * ogma.setOptions({ cursor: { default: 'crosshair' } });
+     * ogma.events.once('mousedown', (evt) => {
+     *   const { x, y } = ogma.view.screenToGraphCoordinates(evt);
+     *   const text = createText(x, y, 0, 0, 'Hello', { color: '#3A03CF' });
+     *   control.startText(x, y, text);
+     * });
+     * ```
+     *
+     * @param x X coordinate for the text
+     * @param y Y coordinate for the text
+     * @param text The text annotation to add (optional, will be created if not provided)
+     * @returns this for chaining
+     * @see enableTextDrawing for the recommended high-level API
+     */
+    startText(x: number, y: number, text?: Text): this;
+    /**
+     * **Advanced API:** Programmatically start drawing a polygon at specific coordinates.
+     *
+     * This is a low-level method that gives you full control over the drawing process.
+     * You must handle mouse events and create the polygon object yourself.
+     *
+     * **For most use cases, use `enablePolygonDrawing()` instead** - it handles all
+     * mouse events and annotation creation automatically.
+     *
+     * Use this method only when you need:
+     * - Custom mouse event handling (e.g., custom cursors, right-click menus)
+     * - Programmatic placement without user interaction
+     * - Integration with custom UI frameworks
+     *
+     * @example
+     * ```ts
+     * // Custom cursor example
+     * ogma.setOptions({ cursor: { default: 'crosshair' } });
+     * ogma.events.once('mousedown', (evt) => {
+     *   const { x, y } = ogma.view.screenToGraphCoordinates(evt);
+     *   const polygon = createPolygon([[[x, y]]], { strokeColor: '#3A03CF' });
+     *   control.startPolygon(x, y, polygon);
+     * });
+     * ```
+     *
+     * @param x X coordinate to start drawing
+     * @param y Y coordinate to start drawing
+     * @param polygon The polygon annotation to add
+     * @returns this for chaining
+     * @see enablePolygonDrawing for the recommended high-level API
+     */
+    startPolygon(x: number, y: number, polygon: Polygon): this;
+    /**
+     * Get the currently selected annotations as a collection
+     * @returns A FeatureCollection of selected annotations
+     */
+    getSelectedAnnotations(): AnnotationCollection;
+    /**
+     * Get the first selected annotation (for backwards compatibility)
+     * @returns The currently selected annotation, or null if none selected
+     */
+    getSelected(): Annotation | null;
+    /**
+     * Get a specific annotation by id
+     * @param id The id of the annotation to retrieve
+     * @returns The annotation with the given id, or undefined if not found
+     */
+    getAnnotation<T = Annotation>(id: Id): T | undefined;
+    /**
+     * Scale an annotation by a given factor around an origin point
+     * @param id The id of the annotation to scale
+     * @param scale The scale factor
+     * @param ox Origin x coordinate
+     * @param oy Origin y coordinate
+     * @returns this for chaining
+     */
+    setScale(id: Id, scale: number, ox: number, oy: number): this;
+    /**
+     * Toggle a comment between collapsed and expanded mode
+     * @param id The id of the comment to toggle
+     * @returns this for chaining
+     */
+    toggleComment(id: Id): this;
+    /**
+     * Destroy the controller and its elements
+     */
+    destroy(): void;
+    /**
+     * Update the style of the annotation with the given id
+     * @param id The id of the annotation to update
+     * @param style The new style
+     */
+    updateStyle<A extends Annotation>(id: Id, style: A["properties"]["style"]): this;
+    /**
+     * Update an annotation with partial updates
+     *
+     * This method allows you to update any properties of an annotation, including
+     * geometry, properties, and style. Updates are merged with existing data.
+     *
+     * @param annotation Partial annotation object with id and properties to update
+     * @returns this for chaining
+     *
+     * @example
+     * ```ts
+     * // Update arrow geometry
+     * controller.update({
+     *   id: arrowId,
+     *   geometry: {
+     *     type: 'LineString',
+     *     coordinates: [[0, 0], [200, 200]]
+     *   }
+     * });
+     *
+     * // Update text content and position
+     * controller.update({
+     *   id: textId,
+     *   geometry: {
+     *     type: 'Point',
+     *     coordinates: [100, 100]
+     *   },
+     *   properties: {
+     *     content: 'Updated text'
+     *   }
+     * });
+     *
+     * // Update style only (prefer updateStyle for style-only updates)
+     * controller.update({
+     *   id: boxId,
+     *   properties: {
+     *     style: {
+     *       background: '#ff0000'
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    update<A extends Annotation>(annotation: DeepPartial<A> & {
+        id: Id;
+    }): this;
+    /**
+     * Attach an arrow to a node at the specified side
+     * @param arrowId
+     * @param targetNode
+     * @param side
+     */
+    link(arrowId: Id, targetNode: Node, side: Side): this;
+    /**
+     * Attach an arrow to an annotation at the specified side
+     * @param arrowId
+     * @param target
+     * @param side
+     */
+    link(arrowId: Id, target: Id, side: Side): this;
+    isDrawing(): boolean;
+}
+
+export { EVT_UNSELECT as $, DATA_ATTR as D, DEFAULT_EDIT_ICON as E, DEFAULT_SEND_ICON as F, EVT_ADD as K, EVT_CANCEL_DRAWING as L, EVT_CLICK as M, EVT_COMPLETE_DRAWING as N, EVT_DRAG as O, EVT_DRAG_END as Q, EVT_DRAG_START as U, EVT_HISTORY as V, EVT_HOVER as W, EVT_LINK as X, EVT_REMOVE as Y, EVT_SELECT as Z, EVT_UNHOVER as _, isBox as a$, EVT_UPDATE as a0, HL_BRIGHTEN as a7, LAYERS as a9, createComment as aA, createCommentWithArrow as aB, createPolygon as aC, createText as aD, cursors as aE, defaultArrowOptions as aF, defaultArrowStyle as aG, defaultBoxOptions as aH, defaultBoxStyle as aI, defaultCommentOptions as aJ, defaultCommentStyle as aK, defaultPolygonProperties as aL, defaultPolygonStyle as aM, defaultTextOptions as aN, defaultTextStyle as aO, detectArrow as aP, detectBox as aQ, detectComment as aR, detectPolygon as aS, detectText as aT, getCommentPosition as aU, getCommentSize as aV, getCommentZoomThreshold as aW, handleDetectionThreshold as aX, handleRadius as aY, isAnnotationCollection as aZ, isArrow as a_, NONE as ac, SIDE_END as ah, SIDE_START as ai, TARGET_TYPES as an, TEXT_LINE_HEIGHT as ao, asColor as at, asHexColor as au, asRgbColor as av, asRgbaColor as aw, calculateCommentZoomThreshold as ax, createArrow as ay, createBox as az, isColor as b0, isComment as b1, isHexColor as b2, isPolygon as b3, isRgbColor as b4, isRgbaColor as b5, isRigidConnector as b6, isStickyNote as b7, isText as b8, toggleCommentMode as b9, COMMENT_MODE_COLLAPSED as r, COMMENT_MODE_EXPANDED as s, Control as x };
+export type { AnnotationCollection as A, Bounds as B, Color as C, DeepPartial as G, HexColor as H, Id as I, DragEvent as J, Polygon as P, RgbaColor as R, Side as S, Text as T, Point as a, EdgeMagnet as a1, ExportedLink as a2, Extremity as a3, FeatureEvent as a4, FeatureEvents as a5, FeaturesEvent as a6, HistoryEvent as a8, Link as aa, Magnet as ab, NodeMagnet as ad, PolygonMagnet as ae, PolygonProperties as af, PolygonStyle as ag, Stroke as aj, StrokeOptions as ak, StrokeStyle as al, StrokeType as am, TargetType as ap, TextProperties as aq, TextStyle as ar, Vector as as, ClientMouseEvent as b, Arrow as c, Annotation as d, RgbColor as e, Box as f, AnnotationFeature as g, AnnotationGetter as h, AnnotationOptions as i, AnnotationProps as j, AnnotationType as k, ArrowProperties as l, ArrowStyles as m, AuthorLineStyle as n, BoxMagnet as o, BoxProperties as p, BoxStyle as q, ClickEvent as t, Comment as u, CommentProps as v, CommentStyle as w, ControllerOptions as y, Cursor as z };