@linkurious/ogma-annotations 2.1.2 → 2.1.3

package/dist/types/ui.d.ts

@@ -1,1423 +1,742 @@
-import { default as default_2 } from 'eventemitter3';
-import { Feature } from 'geojson';
-import { FeatureCollection } from 'geojson';
-import { GeometryObject } from 'geojson';
-import { LineString } from 'geojson';
-import { Node as Node_2 } from '@linkurious/ogma';
-import { Ogma } from '@linkurious/ogma';
-import { Point as Point_2 } from 'geojson';
-import { Polygon as Polygon_2 } from 'geojson';
-
-/** Union type of all Annotation features */
-declare type Annotation = Arrow | Box | Text_2 | Comment_2 | Polygon;
-
-/** Collection of Annotations, GeoJSON FeatureCollection */
-declare interface AnnotationCollection extends FeatureCollection {
-    features: Annotation[];
-}
-
-/**
- * Base interface for all annotation features.
- * @template G - Geometry type
- * @template P - Properties type
- */
-declare interface AnnotationFeature<G extends GeometryObject = GeometryObject, P = AnnotationProps> extends Feature<G, P> {
-    /** Unique identifier for the annotation */
-    id: Id;
-}
-
-export declare class AnnotationPanel {
-    private control;
-    private panel;
-    private panelBody;
-    private mode;
-    private currentAnnotation;
-    private currentColor;
-    private recent;
-    private colorCircles;
-    private colorPickerOverlay;
-    private colorPicker;
-    private detachVisibility;
-    private documentClickHandler;
-    constructor(options: AnnotationPanelOptions);
-    private setAnnotation;
-    private renderArrow;
-    private renderText;
-    private renderPolygon;
-    private section;
-    private icon;
-    private colorSelector;
-    private backgroundSelector;
-    private fontSelector;
-    private extremitySelector;
-    private dropdown;
-    private slider;
-    private lineTypeButtons;
-    private bind;
-    private updateColorFromAnnotation;
-    private updateColorCircles;
-    private toggleColorPicker;
-    private closeColorPicker;
-    private updateStyle;
-    setPlacement(placement: PanelPlacement): void;
-    setOrientation(orientation: PanelOrientation): void;
-    show(): void;
-    hide: () => void;
-    destroy(): void;
-}
-
-export declare interface AnnotationPanelOptions {
-    control: Control;
-    /**
-     * Element the panel mounts into. The panel creates and manages its own root
-     * `<div class="annotation-panel">` inside it. Defaults to `document.body`.
-     */
-    container?: HTMLElement;
-    /**
-     * Which screen edge/corner the panel docks to. Defaults to `"right"`
-     * (vertically centered on the right edge — the original look). Change at
-     * runtime with {@link AnnotationPanel.setPlacement}.
-     */
-    placement?: PanelPlacement;
-    /**
-     * Whether panel sections stack vertically or run horizontally as a
-     * toolbar. Defaults to `"vertical"`. Change at runtime with
-     * {@link AnnotationPanel.setOrientation}.
-     */
-    orientation?: PanelOrientation;
-}
-
-/**
- * Base properties for all annotations.
- */
-declare interface AnnotationProps {
-    /** Type of annotation */
-    type: AnnotationType;
-    /** Optional style configuration */
-    style?: unknown;
-}
-
-/**
- * Styled drawing/undo-redo toolbar: add arrow, comment, box, text and
- * polygon annotations, undo/redo, and delete the current selection. The
- * React equivalent is `AddMenu` (`@linkurious/ogma-annotations-react/ui`) -
- * this class mirrors its buttons and defaults for a vanilla consumer.
- */
-export declare class AnnotationToolbar {
-    private control;
-    private root;
-    private activeButton;
-    private undoButton;
-    private redoButton;
-    private handleDrawingEnd;
-    private handleHistory;
-    constructor(options: AnnotationToolbarOptions);
-    private drawingButton;
-    private button;
-    private separator;
-    private setActiveMode;
-    private updateUndoRedo;
-    setPlacement(placement: PanelPlacement): void;
-    setOrientation(orientation: PanelOrientation): void;
-    destroy(): void;
-}
-
-export declare interface AnnotationToolbarOptions {
-    control: Control;
-    /**
-     * Element the toolbar mounts into. The toolbar creates and manages its
-     * own root `<div class="annotation-toolbar">` inside it. Defaults to
-     * `document.body`.
-     */
-    container?: HTMLElement;
-    /**
-     * Which screen edge/corner the toolbar docks to. Defaults to `"bottom"`.
-     * Change at runtime with {@link AnnotationToolbar.setPlacement}.
-     */
-    placement?: PanelPlacement;
-    /**
-     * Whether buttons run left-to-right or stack top-to-bottom. Defaults to
-     * `"horizontal"`. Change at runtime with
-     * {@link AnnotationToolbar.setOrientation}.
-     */
-    orientation?: PanelOrientation;
-    /**
-     * Which drawing tools to show, and in what order. Defaults to all six:
-     * `["arrow", "comment", "sticky-note", "box", "text", "polygon"]`.
-     */
-    enabledTypes?: ToolbarDrawingType[];
-    /** Per-type default style overrides for the drawing tool buttons. */
-    styles?: AnnotationToolbarStyles;
-    /**
-     * Which deletion control(s) to show - the erase tool, the
-     * select-then-trash button, or both. Defaults to `"erase"`.
-     */
-    deleteMode?: DeleteMode;
-    /** Called when the SVG export button is clicked. Omit to hide the button. */
-    onSvgExport?: () => void;
-    /** Called when the JSON export button is clicked. Omit to hide the button. */
-    onJsonExport?: () => void;
-}
-
-/**
- * Per-type default style overrides, merged over the toolbar's own built-in
- * defaults (which stay in effect for anything you don't override). See
- * `Control.enableArrowDrawing` etc. for what each shape configures.
- */
-export declare interface AnnotationToolbarStyles {
-    arrow?: Partial<Arrow["properties"]["style"]>;
-    box?: Partial<Box["properties"]["style"]>;
-    text?: Partial<Text_2["properties"]["style"]>;
-    polygon?: Partial<Polygon["properties"]["style"]>;
-    comment?: {
-        offsetX?: number;
-        offsetY?: number;
-        commentStyle?: Partial<CommentProps>;
-        arrowStyle?: Partial<ArrowProperties>;
-    };
-    stickyNote?: Partial<Text_2["properties"]["style"]>;
-}
-
-/** Types of annotations supported */
-declare type AnnotationType = "arrow" | "text" | "box" | "comment" | "polygon";
-
-/**
- * Arrow annotation feature. Represents a directed line between two points,
- * can connect a textbox to a shape.
- */
-declare interface Arrow extends AnnotationFeature<LineString, ArrowProperties> {
-}
-
-declare interface ArrowProperties extends AnnotationProps {
-    type: "arrow";
-    style?: ArrowStyles;
-    link?: Partial<Record<Side, ExportedLink>>;
-}
-
-/**
- * Styles specific to arrow annotations.
- */
-declare interface ArrowStyles extends StrokeOptions {
-    /** Tail extremity style */
-    tail?: Extremity;
-    /** Head extremity style */
-    head?: Extremity;
-}
-
-/**
- * Wires `control` events to show/hide callbacks. Returns a `detach` function
- * that removes every listener it registered.
- */
-export declare function attachPanelVisibility(control: PanelVisibilityControl, { onShow, onHide }: PanelVisibilityHandlers): () => void;
-
-export declare interface BackgroundOption {
-    value: string;
-    /** Inline style for the swatch's color circle. */
-    style: string;
-}
-
-export declare const BACKGROUNDS: BackgroundOption[];
-
-/**
- * Box annotation feature
- */
-declare interface Box extends AnnotationFeature<Point_2, BoxProperties> {
-}
-
-/**
- * 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 }
- */
-declare type BoxMagnet = {
-    type: "box";
-    nx: number;
-    ny: number;
-};
-
-/** Properties specific to box annotations. */
-declare 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;
-}
-
-/** Styles specific to box annotations. */
-declare 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;
-}
-
-/** Event related to a single annotation feature */
-declare interface ClickEvent {
-    /** Annotation ID involved in the event */
-    id?: Id;
-    /** Mouse position in pixel coordinates */
-    position: {
-        x: number;
-        y: number;
-    };
-}
-
-/**
- * Any valid color format
- */
-declare type Color = HexColor | RgbColor | RgbaColor_2 | "transparent" | "none" | string;
-
-/**
- * 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.
- */
-declare interface Comment_2 extends AnnotationFeature<Point_2, CommentProps> {
-}
-
-declare const COMMENT_MODE_COLLAPSED = "collapsed";
-
-declare const COMMENT_MODE_EXPANDED = "expanded";
-
-/**
- * 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
- */
-declare 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;
-}
-
-/**
- * Style configuration for Comment annotations
- */
-declare 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";
-}
-
-/**
- * Main controller class for managing annotations.
- * It manages rendering and editing of annotations.
- */
-declare class Control extends default_2<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;
-    /**
-     * 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;
-    };
-    /**
-     * 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_2["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_2["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_2 | 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_2, 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_2["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_2): 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_2, 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;
-}
-
-/**
- * Options for the annotations control
- */
-declare 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;
-    /**
-     * 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;
-};
-
-/**
- * Registers `<rgba-color-picker>` if it isn't already, then returns a fresh
- * instance. Safe to call repeatedly and from multiple module copies.
- */
-export declare function createRgbaColorPicker(): RgbaColorPicker;
-
-declare type DeepPartial<T> = {
-    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
-};
-
-export declare const DEFAULT_PANEL_ORIENTATION: PanelOrientation;
-
-/** Preserves the panel's original vertically-centered, right-docked look. */
-export declare const DEFAULT_PANEL_PLACEMENT: PanelPlacement;
-
-/** Default palette used to seed the recent-colors strip. */
-export declare const DEFAULT_RECENT_COLORS: string[];
-
-/**
- * Which deletion control(s) the toolbar shows - `"erase"` (default) deletes
- * on click via the erase tool; `"select"` selects an annotation then deletes
- * it with the trash button; `"both"` shows both, since they serve slightly
- * different workflows.
- */
-export declare type DeleteMode = "select" | "erase" | "both";
-
-/** Event related to a single annotation feature */
-declare interface DragEvent_2 {
-    /** Annotation ID involved in the event */
-    id: Id;
-    /** Current mouse position in pixel coordinates during the drag */
-    position: {
-        x: number;
-        y: number;
-    };
-}
-
-/** Arrow snapped at parametric position t (0–1) along an edge path. */
-declare type EdgeMagnet = {
-    type: "edge";
-    t: number;
-};
-
-declare const EVT_ADD = "add";
-
-declare const EVT_CANCEL_DRAWING = "cancelDrawing";
-
-declare const EVT_CLICK = "click";
-
-declare const EVT_COMPLETE_DRAWING = "completeDrawing";
-
-declare const EVT_DRAG_END = "dragend";
-
-declare const EVT_DRAG_START = "dragstart";
-
-declare const EVT_HISTORY = "history";
-
-declare const EVT_LINK = "link";
-
-declare const EVT_REMOVE = "remove";
-
-declare const EVT_SELECT = "select";
-
-declare const EVT_UNSELECT = "unselect";
-
-declare const EVT_UPDATE = "update";
-
-/**
- * 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().
- */
-declare type ExportedLink = {
-    id: Id;
-    side: Side;
-    type: TargetType;
-    magnet?: Point;
-};
-
-/** Extremity types for arrow annotations. */
-declare type Extremity = "none" | "arrow" | "arrow-plain" | "dot" | "halo-dot";
-
-export declare const EXTREMITY_OPTIONS: ExtremityOption[];
-
-export declare interface ExtremityOption {
-    value: string;
-    label: string;
-    icon: IconName;
-}
-
-/** Event related to a single annotation feature */
-declare interface FeatureEvent {
-    /** Annotation ID involved in the event */
-    id: Id;
-}
-
-declare 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_2) => void;
-    /**
-     * Event triggered when a drag operation ends on an annotation
-     */
-    [EVT_DRAG_END]: (evt: DragEvent_2) => void;
-    /**
-     * Event triggered when a click completes on an annotation (mouseup without drag)
-     */
-    [EVT_CLICK]: (evt: ClickEvent) => void;
-};
-
-/** Event related to multiple annotation features */
-declare interface FeaturesEvent {
-    /** Annotation IDs involved in the event */
-    ids: Id[];
-}
-
-export declare interface FontOption {
-    value: string;
-    label: string;
-    /** Icon name from the shared icon set (see `ui/icons`). */
-    icon: IconName;
-}
-
-export declare const FONTS: FontOption[];
-
-/**
- * Hex color string in format #RGB or #RRGGBB
- * @example "#fff" | "#ffffff" | "#F0A" | "#FF00AA"
- */
-declare type HexColor = `#${string}`;
-
-/** History stack change event */
-declare interface HistoryEvent {
-    /** Indicates if undo operation is available */
-    canUndo: boolean;
-    /** Indicates if redo operation is available */
-    canRedo: boolean;
-}
-
-/** Inner SVG markup for each icon (paths only; no <svg> wrapper). */
-export declare const ICON_PATHS: Record<IconName, string>;
-
-/**
- * Inline SVG icon set shared by the vanilla and React UI.
- *
- * Each entry is the *inner* markup of a 24x24 lucide icon (stroke-based,
- * `currentColor`). The vanilla panel wraps these with `svgIcon()`; the React
- * package wraps the same paths in a small `<Icon>` component. Keeping the path
- * data here means consumers need no icon font and no `lucide-react` runtime
- * dependency.
- *
- * Source: lucide.dev (ISC license).
- */
-export declare type IconName = "chevron-down" | "x" | "arrow-left" | "arrow-right" | "play" | "circle-dot" | "dot" | "circle" | "circle-dashed" | "type" | "italic" | "code" | "trash" | "undo" | "redo" | "pentagon" | "rectangle-horizontal" | "message-square" | "sticky-note" | "eraser" | "download" | "camera" | "rotate-cw" | "rotate-ccw" | "minimize";
-
-/** Unique identifier type for annotations */
-declare type Id = string | number;
-
-export declare function initialRecentColors(): RecentColorsState;
-
-export declare const LINE_TYPES: LineTypeOption[];
-
-export declare interface LineTypeOption {
-    value: string;
-    icon: IconName;
-}
-
-/** Link between an arrow and a text or node */
-declare 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;
-}
-
-declare type Magnet = NodeMagnet | EdgeMagnet | BoxMagnet | PolygonMagnet;
-
-export declare const MAX_RECENT_COLORS = 3;
-
-/** Arrow snapped to the center or perimeter of a node. */
-declare type NodeMagnet = {
-    type: "node";
-    center: boolean;
-};
-
-/** Whether panel sections stack top-to-bottom or run left-to-right. */
-export declare type PanelOrientation = "vertical" | "horizontal";
-
-/**
- * Placement and orientation options shared by the vanilla `AnnotationPanel`
- * and the React panel/controller. Both are applied as `data-placement` /
- * `data-orientation` attributes on the panel root, consumed by the rules in
- * `ui/styles.css` — no inline layout styles are set from JS.
- */
-/** Which screen edge/corner the panel docks to. */
-export declare type PanelPlacement = "left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
-
-/**
- * The slice of `Control` this state machine relies on. Declared structurally so
- * the function does not pull the full `Control` type into the `/ui` entry's
- * rolled declarations (which would otherwise create a duplicate, incompatible
- * `Control` identity for consumers).
- */
-export declare interface PanelVisibilityControl {
-    on(event: string, handler: (...args: any[]) => void): unknown;
-    off(event: string, handler: (...args: any[]) => void): unknown;
-    once(event: string, handler: (...args: any[]) => void): unknown;
-    getAnnotation(id: string | number): Annotation | undefined;
-    isDrawing(): boolean;
-}
-
-export declare interface PanelVisibilityHandlers {
-    /** Called when the panel should be shown for `annotation`. */
-    onShow: (annotation: Annotation) => void;
-    /** Called when the panel should be hidden. */
-    onHide: () => void;
-}
-
-/** 2D coordinate */
-declare type Point = {
-    x: number;
-    y: number;
-};
-
-/**
- * Polygon placed on the graph, use it to highlight areas
- */
-declare interface Polygon extends AnnotationFeature<Polygon_2, PolygonProperties> {
-}
-
-/**
- * Arrow snapped to a polygon annotation.
- * rx/ry are 0–1 fractions of the polygon's bounding box from its top-left corner.
- */
-declare type PolygonMagnet = {
-    type: "polygon";
-    rx: number;
-    ry: number;
-};
-
-declare interface PolygonProperties extends AnnotationProps {
-    type: "polygon";
-    style?: PolygonStyle;
-}
-
-declare interface PolygonStyle extends BoxStyle {
-}
-
-export declare interface RecentColorsState {
-    colors: string[];
-    /** Index of the currently active swatch. */
-    activeIndex: number;
-}
-
-/** Channel-wise rgba, matching the shape emitted by `vanilla-colorful`. */
-export declare interface RgbaChannels {
-    r: number;
-    g: number;
-    b: number;
-    a: number;
-}
-
-/** Channel-wise rgba color, as read/written by the picker's `color` property. */
-export declare interface RgbaColor {
-    r: number;
-    g: number;
-    b: number;
-    a: number;
-}
-
-/**
- * RGBA color string in format rgba(r, g, b, a)
- * @example "rgba(255, 0, 0, 1)" | "rgba(128, 128, 128, 0.5)"
- */
-declare type RgbaColor_2 = `rgba(${number}, ${number}, ${number}, ${number})` | `rgba(${number},${number},${number},${number})`;
-
-/**
- * The public surface of the `<rgba-color-picker>` element we rely on. Declared
- * locally (rather than re-exporting `vanilla-colorful`'s class type) so that
- * consumers don't have to resolve the package's deep `lib/entrypoints` types,
- * which it does not expose via its `exports` map.
- */
-export declare interface RgbaColorPicker extends HTMLElement {
-    color: RgbaColor;
-    addEventListener(type: "color-changed", listener: (event: CustomEvent<{
-        value: RgbaColor;
-    }>) => void): void;
-    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
-}
-
-/** Serializes an rgba object (as emitted by the color picker) to a CSS string. */
-export declare function rgbaToString(color: RgbaChannels): string;
-
-/**
- * RGB color string in format rgb(r, g, b)
- * @example "rgb(255, 0, 0)" | "rgb(128, 128, 128)"
- */
-declare type RgbColor = `rgb(${number}, ${number}, ${number})` | `rgb(${number},${number},${number})`;
-
-declare type Side = typeof SIDE_START | typeof SIDE_END;
-
-declare const SIDE_END: "end";
-
-declare const SIDE_START: "start";
-
-/** Stroke style options for annotations */
-declare 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 */
-declare type StrokeType = "plain" | "dashed" | "none";
-
-/**
- * Returns a complete `<svg>` string for the named icon, ready to drop into
- * `innerHTML`. Used by the vanilla panel.
- */
-export declare function svgIcon(name: IconName, size?: number): string;
-
-/** @private */
-declare const TARGET_TYPES: {
-    TEXT: "text";
-    NODE: "node";
-    BOX: "box";
-    COMMENT: "comment";
-    POLYGON: "polygon";
-    ANNOTATION: "annotation";
-    EDGE: "edge";
-};
-
-declare type TargetType = (typeof TARGET_TYPES)[keyof typeof TARGET_TYPES];
-
-/**
- * Text annotation feature, represents a text box at a specific position
- */
-declare interface Text_2 extends AnnotationFeature<Point_2, TextProperties> {
-}
-
-declare interface TextProperties extends Omit<BoxProperties, "type"> {
-    type: "text";
-    /**text to display*/
-    content: string;
-    /** Width of the text box */
-    width: number;
-    /** Height of the text box */
-    height: number;
-    style?: TextStyle;
-}
-
-declare 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;
-    /**
-     * 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;
-}
-
-/** One of the toolbar's drawing tools - see `enabledTypes`. */
-export declare type ToolbarDrawingType = "arrow" | "comment" | "sticky-note" | "box" | "text" | "polygon";
-
-/**
- * Given the current recent-colors state and a color coming from the selected
- * annotation, returns the next state: if the color is already known it becomes
- * active, otherwise it is unshifted to the front (capped at MAX_RECENT_COLORS).
- *
- * Pure — callers (React/vanilla) hold the state and apply the result.
- */
-export declare function withColorFromAnnotation(state: RecentColorsState, color: string): RecentColorsState;
-
-export { }
+import { Annotation, Control, Arrow, Box, Text, Polygon, CommentProps, ArrowProperties, Id } from './index.js';
+import { Ogma } from '@linkurious/ogma';
+import 'geojson';
+import 'eventemitter3';
+
+/**
+ * Placement and orientation options shared by the vanilla `AnnotationPanel`
+ * and the React panel/controller. Both are applied as `data-placement` /
+ * `data-orientation` attributes on the panel root, consumed by the rules in
+ * `ui/styles.css` — no inline layout styles are set from JS.
+ */
+/** Which screen edge/corner the panel docks to. */
+type PanelPlacement = "left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** Whether panel sections stack top-to-bottom or run left-to-right. */
+type PanelOrientation = "vertical" | "horizontal";
+/** Preserves the panel's original vertically-centered, right-docked look. */
+declare const DEFAULT_PANEL_PLACEMENT: PanelPlacement;
+declare const DEFAULT_PANEL_ORIENTATION: PanelOrientation;
+
+/**
+ * Which selected-annotation *kind* a panel/toolbar responds to - shared
+ * between the vanilla `AnnotationPanel` and the React
+ * `AnnotationPanelController`/`useAnnotationPanel` so both filter selection
+ * the same way (one classification function, not two copies).
+ *
+ * Distinct from `AnnotationToolbar`'s `ToolbarDrawingType`: that one is
+ * about which *drawing tool* to offer (and splits `"sticky-note"` out from
+ * `"text"` since they're different buttons to create), this one is about
+ * which *already-selected annotation's data type* to react to - a sticky
+ * note is still just `"text"` here, same as any other Text annotation,
+ * since the docked panel (and, for Text specifically, the floating
+ * `TextAnnotationToolbar`) don't have a separate UI for it.
+ */
+
+type PanelAnnotationType = "arrow" | "text" | "box" | "comment" | "polygon";
+declare const ALL_PANEL_ANNOTATION_TYPES: PanelAnnotationType[];
+/** `null` for an annotation kind the panel has no UI for at all (none
+ * today, but new annotation types may be added before their panel support
+ * is). Callers should treat `null` the same as "not enabled". */
+declare function classifyPanelAnnotationType(a: Annotation): PanelAnnotationType | null;
+
+interface AnnotationPanelOptions {
+    control: Control;
+    /**
+     * Element the panel mounts into. The panel creates and manages its own root
+     * `<div class="annotation-panel">` inside it. Defaults to `document.body`.
+     */
+    container?: HTMLElement;
+    /**
+     * Which screen edge/corner the panel docks to. Defaults to `"right"`
+     * (vertically centered on the right edge — the original look). Change at
+     * runtime with {@link AnnotationPanel.setPlacement}.
+     */
+    placement?: PanelPlacement;
+    /**
+     * Whether panel sections stack vertically or run horizontally as a
+     * toolbar. Defaults to `"vertical"`. Change at runtime with
+     * {@link AnnotationPanel.setOrientation}.
+     */
+    orientation?: PanelOrientation;
+    /**
+     * Which selected-annotation types the panel responds to. Defaults to all
+     * five (`["arrow", "text", "box", "comment", "polygon"]`). Exclude
+     * `"text"` once you've adopted `TextAnnotationToolbar` for Text
+     * annotations and sticky notes, so the two don't show at once for the
+     * same selection.
+     */
+    enabledTypes?: PanelAnnotationType[];
+    /**
+     * Whether a selected-but-locked (`isEditable: false`) annotation keeps
+     * the panel hidden, same as no selection. Defaults to `true`. See
+     * `attachPanelVisibility`'s `hideWhenNotEditable` for the full contract.
+     */
+    hideWhenNotEditable?: boolean;
+}
+declare class AnnotationPanel {
+    private control;
+    private panel;
+    private panelBody;
+    private mode;
+    private currentAnnotation;
+    private currentColor;
+    private recent;
+    private colorCircles;
+    private colorPickerOverlay;
+    private colorPicker;
+    private detachVisibility;
+    private documentClickHandler;
+    private enabledTypes;
+    constructor(options: AnnotationPanelOptions);
+    private setAnnotation;
+    private renderArrow;
+    private renderText;
+    private renderPolygon;
+    private section;
+    private icon;
+    private colorSelector;
+    private backgroundSelector;
+    private fontSelector;
+    private extremitySelector;
+    private dropdown;
+    private slider;
+    private lineTypeButtons;
+    private bind;
+    private updateColorFromAnnotation;
+    private updateColorCircles;
+    private toggleColorPicker;
+    private closeColorPicker;
+    private updateStyle;
+    setPlacement(placement: PanelPlacement): void;
+    setOrientation(orientation: PanelOrientation): void;
+    show(): void;
+    hide: () => void;
+    destroy(): void;
+}
+
+/** One of the toolbar's drawing tools - see `enabledTypes`. */
+type ToolbarDrawingType = "arrow" | "comment" | "sticky-note" | "box" | "text" | "polygon";
+/**
+ * Which deletion control(s) the toolbar shows - `"erase"` (default) deletes
+ * on click via the erase tool; `"select"` selects an annotation then deletes
+ * it with the trash button; `"both"` shows both, since they serve slightly
+ * different workflows.
+ */
+type DeleteMode = "select" | "erase" | "both";
+/**
+ * Per-type default style overrides, merged over the toolbar's own built-in
+ * defaults (which stay in effect for anything you don't override). See
+ * `Control.enableArrowDrawing` etc. for what each shape configures.
+ */
+interface AnnotationToolbarStyles {
+    arrow?: Partial<Arrow["properties"]["style"]>;
+    box?: Partial<Box["properties"]["style"]>;
+    text?: Partial<Text["properties"]["style"]>;
+    polygon?: Partial<Polygon["properties"]["style"]>;
+    comment?: {
+        offsetX?: number;
+        offsetY?: number;
+        commentStyle?: Partial<CommentProps>;
+        arrowStyle?: Partial<ArrowProperties>;
+    };
+    stickyNote?: Partial<Text["properties"]["style"]>;
+}
+interface AnnotationToolbarOptions {
+    control: Control;
+    /**
+     * Element the toolbar mounts into. The toolbar creates and manages its
+     * own root `<div class="annotation-toolbar">` inside it. Defaults to
+     * `document.body`.
+     */
+    container?: HTMLElement;
+    /**
+     * Which screen edge/corner the toolbar docks to. Defaults to `"bottom"`.
+     * Change at runtime with {@link AnnotationToolbar.setPlacement}.
+     */
+    placement?: PanelPlacement;
+    /**
+     * Whether buttons run left-to-right or stack top-to-bottom. Defaults to
+     * `"horizontal"`. Change at runtime with
+     * {@link AnnotationToolbar.setOrientation}.
+     */
+    orientation?: PanelOrientation;
+    /**
+     * Which drawing tools to show, and in what order. Defaults to all six:
+     * `["arrow", "comment", "sticky-note", "box", "text", "polygon"]`.
+     */
+    enabledTypes?: ToolbarDrawingType[];
+    /** Per-type default style overrides for the drawing tool buttons. */
+    styles?: AnnotationToolbarStyles;
+    /**
+     * Which deletion control(s) to show - the erase tool, the
+     * select-then-trash button, or both. Defaults to `"erase"`.
+     */
+    deleteMode?: DeleteMode;
+    /** Called when the SVG export button is clicked. Omit to hide the button. */
+    onSvgExport?: () => void;
+    /** Called when the JSON export button is clicked. Omit to hide the button. */
+    onJsonExport?: () => void;
+}
+/**
+ * Styled drawing/undo-redo toolbar: add arrow, comment, box, text and
+ * polygon annotations, undo/redo, and delete the current selection. The
+ * React equivalent is `AddMenu` (`@linkurious/ogma-annotations-react/ui`) -
+ * this class mirrors its buttons and defaults for a vanilla consumer.
+ */
+declare class AnnotationToolbar {
+    private control;
+    private root;
+    private activeButton;
+    private undoButton;
+    private redoButton;
+    private handleDrawingEnd;
+    private handleHistory;
+    constructor(options: AnnotationToolbarOptions);
+    private drawingButton;
+    private button;
+    private separator;
+    private setActiveMode;
+    private updateUndoRedo;
+    setPlacement(placement: PanelPlacement): void;
+    setOrientation(orientation: PanelOrientation): void;
+    destroy(): void;
+}
+
+/**
+ * What a cell needs from its host toolbar - small and structural (not the
+ * full `Control`) so cells stay easy to unit test and don't reach past the
+ * annotation they're editing. Mirrors the shape of the React
+ * `*Controller.tsx` components' props, minus the framework.
+ */
+interface ToolbarCellContext {
+    /** The annotation this toolbar instance is currently showing. Read fresh
+     * on every call (not cached by the cell) so it reflects the latest style
+     * after another cell's edit. */
+    getAnnotation(): Text;
+    /** Merges `patch` into the annotation's style via `control.updateStyle`. */
+    updateStyle(patch: Partial<Text["properties"]["style"]>): void;
+    /** Removes the annotation via `control.remove`. */
+    deleteAnnotation(): void;
+}
+/**
+ * One button/control in the floating toolbar's pill. `element` is inserted
+ * directly into the pill's DOM by `AnnotationStyleToolbar`; a divider is
+ * inserted after every cell but the last.
+ */
+interface ToolbarCell {
+    readonly element: HTMLElement;
+    /** Called whenever the shown annotation's data may have changed (initial
+     * render, another cell's edit, or an external update) so the cell can
+     * reflect the current value (e.g. the size cell's displayed number). */
+    update(annotation: Text): void;
+    destroy(): void;
+}
+
+/**
+ * Inline SVG icon set shared by the vanilla and React UI.
+ *
+ * Each entry is the *inner* markup of a 24x24 lucide icon (stroke-based,
+ * `currentColor`). The vanilla panel wraps these with `svgIcon()`; the React
+ * package wraps the same paths in a small `<Icon>` component. Keeping the path
+ * data here means consumers need no icon font and no `lucide-react` runtime
+ * dependency.
+ *
+ * Source: lucide.dev (ISC license).
+ */
+type IconName = "chevron-down" | "x" | "arrow-left" | "arrow-right" | "play" | "circle-dot" | "dot" | "circle" | "circle-dashed" | "type" | "italic" | "bold" | "code" | "trash" | "undo" | "redo" | "pentagon" | "rectangle-horizontal" | "message-square" | "sticky-note" | "eraser" | "download" | "camera" | "rotate-cw" | "rotate-ccw" | "minimize" | "user";
+/** Inner SVG markup for each icon (paths only; no <svg> wrapper). */
+declare const ICON_PATHS: Record<IconName, string>;
+/**
+ * Returns a complete `<svg>` string for the named icon, ready to drop into
+ * `innerHTML`. Used by the vanilla panel.
+ */
+declare function svgIcon(name: IconName, size?: number): string;
+
+/**
+ * Declarative description of one toolbar entry - what `TextStyleToolbar`/
+ * `StickyNoteStyleToolbar`'s `getItems()` returns. A generic renderer turns
+ * each item into a `ToolbarCell`:
+ *
+ * - `"button"` -> `ButtonItemCell` (Bold, Delete, the author toggle - any
+ *   simple action/toggle button).
+ * - `"dropdown"` -> `DropdownItemCell` (Font family, Font size - anything
+ *   that's "pick one of a list").
+ * - `"separator"` -> a plain divider, no cell.
+ * - `"custom"` -> an escape hatch for a cell that doesn't reduce to
+ *   button/dropdown - the color picker is the one case today (a swatch grid
+ *   opening a secondary popover, not a flat option list).
+ *
+ * This is what makes the built-in toolbar configurable from the outside:
+ * `getItems()` builds this list from `TextStyleToolbarOptions` (fonts, font
+ * sizes, swatches - each with a shipped default, all overridable), rather
+ * than hardcoding specific cell classes/values.
+ */
+type ToolbarItem = ToolbarButtonItem | ToolbarDropdownItem | ToolbarSeparatorItem | ToolbarCustomItem;
+interface ToolbarButtonItem {
+    kind: "button";
+    /** Stable identifier for a built-in item (e.g. `"bold"`, `"delete"`) -
+     * lets a `TextStyleToolbarOptions.items` transform address one by
+     * `id` (`filter`/`find`) instead of by array position, so it keeps
+     * working if the built-in list's order or length changes in a later
+     * version. Not read by the toolbar itself; unset on your own items,
+     * which only your own `items` function ever sees. */
+    id?: string;
+    /** Tooltip label, shown on hover via the existing `data-tooltip` CSS. */
+    title: string;
+    icon: IconName;
+    action: (ctx: ToolbarCellContext) => void;
+    /** Toggle state - button gets the `.active` class when this returns
+     * true. Omit for a plain action button (e.g. Delete). */
+    isActive?: (annotation: Text) => boolean;
+    /** Red-on-hover styling, used by Delete. */
+    danger?: boolean;
+}
+/** `value` is `string | number` (not a per-item generic) so a plain object
+ * literal - e.g. an inline font-size preset list - type-checks directly
+ * against `ToolbarItem` without an explicit type argument. */
+type ToolbarDropdownValue = string | number;
+interface ToolbarDropdownOption {
+    value: ToolbarDropdownValue;
+    label: string;
+    /** Inline style hint applied to this option's row - e.g. `{fontFamily:
+     * value}` so a font option previews in its own face. */
+    style?: Partial<CSSStyleDeclaration>;
+}
+interface ToolbarDropdownItem {
+    kind: "dropdown";
+    /** See `ToolbarButtonItem.id`. */
+    id?: string;
+    title: string;
+    options: ToolbarDropdownOption[];
+    getValue: (annotation: Text) => ToolbarDropdownValue;
+    onSelect: (value: ToolbarDropdownValue, ctx: ToolbarCellContext) => void;
+    /** Trigger label shown when closed - defaults to the selected option's
+     * `label`. Override for e.g. font (always shows "Aa", not the font name)
+     * or size (shows the live effective number even between presets). */
+    getLabel?: (value: ToolbarDropdownValue, annotation: Text) => string;
+}
+interface ToolbarSeparatorItem {
+    kind: "separator";
+    /** See `ToolbarButtonItem.id` - lets an `items` transform address a
+     * specific divider (e.g. "the one right before Delete") without
+     * counting positions. Rarely needed; addressing the item next to it is
+     * usually enough. */
+    id?: string;
+}
+interface ToolbarCustomItem {
+    kind: "custom";
+    /** See `ToolbarButtonItem.id`. */
+    id?: string;
+    build: (ctx: ToolbarCellContext) => ToolbarCell;
+}
+
+interface AnnotationStyleToolbarOptions {
+    control: Control;
+}
+/**
+ * Base class for a floating, per-selection style pill: mounts an
+ * `ogma.layers.addOverlay(...)` layer holding a row of cells built from
+ * `getItems()`'s declarative `ToolbarItem[]`, and keeps it anchored above
+ * the annotation's (possibly rotated) top edge.
+ *
+ * Generic over its options type (`TOptions extends
+ * AnnotationStyleToolbarOptions`) so a subclass can add its own
+ * configuration - fonts/sizes/swatches for `TextStyleToolbar`, say - and
+ * read it back via `this.options` from within `getItems()`, which the base
+ * constructor calls before any subclass field initializer would run. Pass
+ * that configuration through the options object itself (as
+ * `TextStyleToolbar` does), not extra constructor parameters.
+ *
+ * Written directly against `Text` rather than also being generic over the
+ * annotation type - `TextStyleToolbar`/`StickyNoteStyleToolbar` are the
+ * only subclasses today. A future non-Text style toolbar (arrows/boxes/
+ * polygons - explicitly undecided, see the toolbar's design notes) would
+ * most likely copy this class's shape (overlay mount + item-driven cell
+ * row + anchor tracking) rather than force a second type parameter through
+ * a base no second subclass has yet exercised.
+ *
+ * One instance is tied to one annotation for its whole lifetime - the host
+ * `TextAnnotationToolbar` destroys and recreates the toolbar when the
+ * selection changes to a different annotation (or between plain-Text and
+ * sticky-note), and calls `update()` on the same instance for everything
+ * else (an edit from one of its own cells, or an external update).
+ */
+declare abstract class AnnotationStyleToolbar<TOptions extends AnnotationStyleToolbarOptions = AnnotationStyleToolbarOptions> {
+    protected control: Control;
+    protected ogma: Ogma;
+    protected options: TOptions;
+    readonly annotationId: Id;
+    private overlay;
+    /** The element handed to `addOverlay` - Ogma writes its own
+     * `style.transform` (translate/rotate/scale, recomputed on every
+     * viewChanged/zoom/rotate/move) directly onto this node to place it at
+     * `position`, so nothing of ours may also set `transform` here or Ogma's
+     * assignment clobbers it (inline style, last writer wins - there's no way
+     * to compose two separate `transform` writers on one element). Zero-size
+     * and otherwise unstyled; it exists purely as the anchor point. */
+    private anchor;
+    /** The actual visible pill - a child of `anchor`, `position: absolute`
+     * with its own `transform: translate(-50%, -100%)` (see `styles.css`) to
+     * center horizontally and sit fully above the anchor point. This is where
+     * our own positioning lives, kept off `anchor` for exactly that reason. */
+    private root;
+    private cells;
+    private documentClickHandler;
+    constructor(options: TOptions, annotation: Text);
+    /** The toolbar's entries, in order - implemented by
+     * `TextStyleToolbar`/`StickyNoteStyleToolbar`. Declarative
+     * (`ToolbarItem[]`) rather than pre-built cells, so a consumer can
+     * reconfigure the built-in items (fonts, sizes, swatches) via
+     * `this.options` without subclassing any cell. */
+    protected abstract getItems(ctx: ToolbarCellContext): ToolbarItem[];
+    /** Turns one `ToolbarItem` into its `ToolbarCell` - `"separator"` has
+     * none (handled by `setItems` directly), `"custom"` calls its own
+     * `build()` (the color picker's escape hatch), `"button"`/`"dropdown"`
+     * go through the two generic cell classes. */
+    private buildCell;
+    private setItems;
+    /**
+     * Top-center of the annotation's box, in graph space, offset outward by
+     * `ANCHOR_GAP` (screen-constant, so divided by zoom) and rotated by the
+     * global annotation-rotation angle - the same `ctx.rotate(rotation)`
+     * transform `Handles.renderOutline` applies to a Text box's outline, so
+     * the pill tracks the box exactly as it visually rotates.
+     */
+    private getAnchor;
+    /** Refreshes every cell and repositions the pill for `annotation` -
+     * called after a select, an own-cell edit, or an external update to the
+     * same annotation. Does not rebuild cells; the host recreates the whole
+     * instance when the annotation identity/kind changes. */
+    update(annotation: Text): void;
+    destroy(): void;
+}
+
+/**
+ * Fixed swatch-grid palette for the floating text toolbar's color cell,
+ * extracted from the Figma "Sticky Note Toolbar" color-picker-dropdown
+ * export. Distinct from `ui/config.ts`'s `BACKGROUNDS`/`DEFAULT_RECENT_COLORS`
+ * (the docked `AnnotationPanel`'s recent-colors strip) - this is a static
+ * palette, not an MRU list.
+ *
+ * The export only fully captured 8 fill/stroke pairs for what reads as a
+ * 3x3(+) grid - the 9th cell (a color, or a "more colors" affordance) was
+ * unconfirmed, so a `"transparent"` swatch (a checkerboard circle in the CSS
+ * - see `.oa-toolbar-swatch-cell-transparent` in `styles.css`, same "no
+ * fill" convention `ui/config.ts`'s `BACKGROUNDS` already uses for the
+ * docked `AnnotationPanel`) fills that slot. `ColorCell` opens the existing
+ * `vanilla-colorful` picker (see `colorPicker.ts`) as a secondary "more
+ * colors" popover for anything not in this fixed set.
+ */
+interface Swatch {
+    /** Fill color, used as both the swatch circle's fill and the annotation's
+     * `color`/`background` style value when picked. The CSS keyword
+     * `"transparent"` is a valid value here - `ColorCell` gives it a
+     * checkerboard swatch instead of a solid (indistinguishable-from-empty)
+     * circle. */
+    fill: string;
+    /** 1px ring stroke color around the swatch circle. */
+    stroke: string;
+}
+declare const STICKY_SWATCHES: Swatch[];
+
+interface ColorCellOptions {
+    /** Fixed swatch-grid palette - defaults to `STICKY_SWATCHES`
+     * (`TextStyleToolbar`'s `swatches` option), overridable per instance. */
+    swatches: Swatch[];
+    /**
+     * Called instead of opening the built-in `vanilla-colorful` popover when
+     * "More colors…" is clicked - use this to hand off to your own color
+     * picker (a native `<input type="color">`, a design-system component,
+     * whatever) instead of the bundled one. Read the current color via
+     * `ctx.getAnnotation().properties.style?.background`, and call
+     * `ctx.updateStyle({ background: yourPickedColor })` (as many times as
+     * you like, e.g. live while the user drags in your own picker) to apply
+     * it - same `ToolbarCellContext` every other cell action gets.
+     * `anchor` is the "More colors…" button itself, there to position your
+     * own popover against if you want to anchor it the same place the
+     * built-in one would have opened. This toolbar's own popover closes
+     * right before this is called either way.
+     */
+    onMoreColors?: (ctx: ToolbarCellContext, anchor: HTMLElement) => void;
+}
+/**
+ * Note-color cell - the toolbar's one hand-built ("custom") item, per its
+ * own edge-case shape (a swatch grid opening a secondary popover, not a
+ * flat option list a `DropdownItemCell` could render). Edits `background`
+ * (the note's fill - the single most visible "color" of a Text/sticky
+ * note, and what the Figma swatch grid's colors are for), not `color` (the
+ * text color, already covered by the docked `AnnotationPanel`'s separate
+ * Color/Background sections).
+ *
+ * Primary UI is the `swatches` grid, matching the Figma dropdown export. A
+ * "More colors…" cell at the end opens the existing `vanilla-colorful`
+ * picker (`colorPicker.ts`) as a secondary popover, so this doesn't
+ * reimplement a full color picker - it wraps the one `AnnotationPanel`
+ * already uses - unless the host supplies `onMoreColors`, in which case
+ * that's called instead and the built-in picker never gets built at all.
+ */
+declare class ColorCell implements ToolbarCell {
+    private ctx;
+    private options;
+    readonly element: HTMLElement;
+    private dropdown;
+    private swatch;
+    private more;
+    private morePicker;
+    private morePickerHost;
+    constructor(ctx: ToolbarCellContext, options: ColorCellOptions);
+    private pick;
+    private openMorePicker;
+    private closeMorePicker;
+    update(annotation: Text): void;
+    destroy(): void;
+}
+
+/** Font options offered by the Font-family cell. Real font names need the
+ * actual webfont loaded by the host page to render as shown (e.g. the demo
+ * at `web/index.html` loads IBM Plex Sans/Mono) - same "best effort, no
+ * bundled font loading" convention `defaultStickyNoteStyle`/
+ * `defaultCommentStyle` already use for `font: "IBM Plex Sans"`. */
+declare const DEFAULT_TOOLBAR_FONTS: ToolbarDropdownOption[];
+/** Preset sizes offered by the Font-size cell - same range as the docked
+ * `AnnotationPanel`'s font-size slider (8-72). */
+declare const DEFAULT_TOOLBAR_FONT_SIZES: number[];
+interface TextStyleToolbarOptions extends AnnotationStyleToolbarOptions {
+    /** Font-family cell options - defaults to `DEFAULT_TOOLBAR_FONTS`. */
+    fonts?: ToolbarDropdownOption[];
+    /** Font-size cell presets - defaults to `DEFAULT_TOOLBAR_FONT_SIZES`. */
+    fontSizes?: number[];
+    /** Color cell's swatch-grid palette - defaults to `STICKY_SWATCHES`. */
+    swatches?: Swatch[];
+    /** Bring your own color picker: called instead of opening the built-in
+     * `vanilla-colorful` popover when the color cell's "More colors…" is
+     * clicked. See `ColorCellOptions.onMoreColors` for the full contract. */
+    onMoreColors?: ColorCellOptions["onMoreColors"];
+    /**
+     * Full control over the pill's contents, beyond `fonts`/`fontSizes`/
+     * `swatches`/`onMoreColors`: called with the built-in item list (color,
+     * font, font size, bold, show-author, delete - each with a stable `id`,
+     * see `ToolbarButtonItem.id`) and returns what actually renders. Add,
+     * remove, reorder or replace freely -
+     * `defaultItems.filter((i) => i.id !== "delete")` drops Delete,
+     * `[{ kind: "custom", build: () => new MyCell(ctx) }, ...defaultItems]`
+     * prepends a cell - same power as subclassing and overriding
+     * `getItems()`, as a plain option instead. Defaults to the identity
+     * function (`defaultItems` unchanged).
+     */
+    items?: (defaultItems: ToolbarItem[], ctx: ToolbarCellContext) => ToolbarItem[];
+}
+/** Floating style pill for a Text annotation (plain text box or sticky
+ * note): Color, Font family, Font size, Bold, Show author, Delete - see the
+ * Figma "Sticky Note Toolbar" export (alignment cell dropped for v1).
+ * `StickyNoteStyleToolbar` extends this with no items of its own for now.
+ *
+ * The built-in items are declarative `ToolbarItem`s (see `cells/types.ts`),
+ * built from `this.options` - override `fonts`/`fontSizes`/`swatches`/
+ * `onMoreColors` at construction to reconfigure them without subclassing. */
+declare class TextStyleToolbar extends AnnotationStyleToolbar<TextStyleToolbarOptions> {
+    protected getItems(ctx: ToolbarCellContext): ToolbarItem[];
+}
+
+/** `fonts`/`fontSizes`/`swatches` (see `TextStyleToolbarOptions`) apply to
+ * both the plain-Text and sticky-note pill - `StickyNoteStyleToolbar`
+ * currently has no items or options of its own, it's a plain subclass. */
+interface TextAnnotationToolbarOptions extends TextStyleToolbarOptions {
+    control: Control;
+    /**
+     * Whether a selected-but-locked (`isEditable: false`) Text annotation
+     * keeps the toolbar hidden, same as no selection. Defaults to `true`.
+     * Set to `false` to keep the toolbar open on a locked selection instead
+     * (e.g. to keep a lock/unlock button in `items` reachable) - see
+     * `attachPanelVisibility`'s `hideWhenNotEditable` for the full contract.
+     */
+    hideWhenNotEditable?: boolean;
+}
+/**
+ * Floating, per-selection style toolbar for Text annotations (plain text
+ * boxes and sticky notes) - the vanilla equivalent of the docked
+ * `AnnotationPanel`, but anchored above the selection instead of docked to
+ * a screen edge. Ignores non-Text selections (arrow/box/polygon/comment
+ * still only get the docked panel, for now).
+ *
+ * Thin by design (`constructor(options)` / `destroy()`, no other public
+ * surface) so a future React wrapper can host it the way
+ * `AnnotationPanelController` hosts `AnnotationPanel`.
+ */
+declare class TextAnnotationToolbar {
+    private control;
+    private options;
+    private current;
+    private detachVisibility;
+    private handleUpdate;
+    constructor(options: TextAnnotationToolbarOptions);
+    private show;
+    private hide;
+    destroy(): void;
+}
+
+/** Sticky-note style pill. Currently just `TextStyleToolbar`'s items
+ * verbatim - the author-visibility toggle that used to be added here has
+ * moved to the base class so plain Text annotations get it too. Kept as a
+ * distinct (empty) subclass, rather than folded away, so `FloatingTextToolbar`
+ * can keep selecting it via `isStickyNote()` without change, and so any
+ * future sticky-note-only cell has an obvious place to go. */
+declare class StickyNoteStyleToolbar extends TextStyleToolbar {
+}
+
+/** Renders a `ToolbarButtonItem` - the generic cell behind Bold, Delete,
+ * and the author-visibility toggle (any simple action/toggle button). */
+declare class ButtonItemCell implements ToolbarCell {
+    private ctx;
+    private item;
+    readonly element: HTMLButtonElement;
+    constructor(ctx: ToolbarCellContext, item: ToolbarButtonItem);
+    private onClick;
+    update(annotation: Text): void;
+    destroy(): void;
+}
+
+/** Renders a `ToolbarDropdownItem` - the generic cell behind Font family
+ * and Font size (anything that's "pick one of a list"). */
+declare class DropdownItemCell implements ToolbarCell {
+    private ctx;
+    private item;
+    readonly element: HTMLElement;
+    private dropdown;
+    constructor(ctx: ToolbarCellContext, item: ToolbarDropdownItem);
+    update(annotation: Text): void;
+    destroy(): void;
+}
+
+/**
+ * Shared, framework-agnostic configuration for the annotation style panel UI.
+ * Consumed by both the vanilla `AnnotationPanel` (core) and the React controllers.
+ */
+
+interface BackgroundOption {
+    value: string;
+    /** Inline style for the swatch's color circle. */
+    style: string;
+}
+declare const BACKGROUNDS: BackgroundOption[];
+interface FontOption {
+    value: string;
+    label: string;
+    /** Icon name from the shared icon set (see `ui/icons`). */
+    icon: IconName;
+}
+declare const FONTS: FontOption[];
+interface ExtremityOption {
+    value: string;
+    label: string;
+    icon: IconName;
+}
+declare const EXTREMITY_OPTIONS: ExtremityOption[];
+interface LineTypeOption {
+    value: string;
+    icon: IconName;
+}
+declare const LINE_TYPES: LineTypeOption[];
+/** Default palette used to seed the recent-colors strip. */
+declare const DEFAULT_RECENT_COLORS: string[];
+
+/** Channel-wise rgba, matching the shape emitted by `vanilla-colorful`. */
+interface RgbaChannels {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Serializes an rgba object (as emitted by the color picker) to a CSS string. */
+declare function rgbaToString(color: RgbaChannels): string;
+interface RecentColorsState {
+    colors: string[];
+    /** Index of the currently active swatch. */
+    activeIndex: number;
+}
+declare const MAX_RECENT_COLORS = 3;
+declare function initialRecentColors(): RecentColorsState;
+/**
+ * Given the current recent-colors state and a color coming from the selected
+ * annotation, returns the next state: if the color is already known it becomes
+ * active, otherwise it is unshifted to the front (capped at MAX_RECENT_COLORS).
+ *
+ * Pure — callers (React/vanilla) hold the state and apply the result.
+ */
+declare function withColorFromAnnotation(state: RecentColorsState, color: string): RecentColorsState;
+
+/** Channel-wise rgba color, as read/written by the picker's `color` property. */
+interface RgbaColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * The public surface of the `<rgba-color-picker>` element we rely on. Declared
+ * locally (rather than re-exporting `vanilla-colorful`'s class type) so that
+ * consumers don't have to resolve the package's deep `lib/entrypoints` types,
+ * which it does not expose via its `exports` map.
+ */
+interface RgbaColorPicker extends HTMLElement {
+    color: RgbaColor;
+    addEventListener(type: "color-changed", listener: (event: CustomEvent<{
+        value: RgbaColor;
+    }>) => void): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+/**
+ * Registers `<rgba-color-picker>` if it isn't already, then returns a fresh
+ * instance. Safe to call repeatedly and from multiple module copies.
+ */
+declare function createRgbaColorPicker(): RgbaColorPicker;
+
+/**
+ * Framework-agnostic visibility state machine for the annotation style panel.
+ *
+ * The panel should appear when a single annotation is selected — but only once
+ * we're sure the interaction is a click/selection and not the start of a drag
+ * or an in-progress drawing. This logic was previously duplicated verbatim in
+ * the vanilla `AnnotationPanel` constructor and the React
+ * `AnnotationPanelController`; it now lives here and is consumed by both.
+ */
+
+interface PanelVisibilityHandlers {
+    /** Called when the panel should be shown for `annotation`. */
+    onShow: (annotation: Annotation) => void;
+    /** Called when the panel should be hidden. */
+    onHide: () => void;
+    /**
+     * Whether a selected-but-non-editable annotation (per the `isEditable`
+     * control option) keeps the panel hidden, same as if nothing were
+     * selected. Defaults to `true` - the original behavior, right for a panel
+     * with nothing safe to change on a locked annotation. Set to `false` for
+     * a panel that stays open on a locked selection instead (e.g. to keep a
+     * lock/unlock toggle reachable) - callers typically also grey out every
+     * other control in that case, since `onShow` still fires for an
+     * annotation nothing else in the panel can safely edit.
+     */
+    hideWhenNotEditable?: boolean;
+}
+/**
+ * The slice of `Control` this state machine relies on. Declared structurally so
+ * the function does not pull the full `Control` type into the `/ui` entry's
+ * rolled declarations (which would otherwise create a duplicate, incompatible
+ * `Control` identity for consumers).
+ */
+interface PanelVisibilityControl {
+    on(event: string, handler: (...args: any[]) => void): unknown;
+    off(event: string, handler: (...args: any[]) => void): unknown;
+    once(event: string, handler: (...args: any[]) => void): unknown;
+    getAnnotation(id: string | number): Annotation | undefined;
+    isDrawing(): boolean;
+    isAnnotationEditable(id: string | number): boolean;
+}
+/**
+ * Wires `control` events to show/hide callbacks. Returns a `detach` function
+ * that removes every listener it registered.
+ */
+declare function attachPanelVisibility(control: PanelVisibilityControl, { onShow, onHide, hideWhenNotEditable }: PanelVisibilityHandlers): () => void;
+
+export { ALL_PANEL_ANNOTATION_TYPES, AnnotationPanel, AnnotationStyleToolbar, AnnotationToolbar, BACKGROUNDS, ButtonItemCell, ColorCell, DEFAULT_PANEL_ORIENTATION, DEFAULT_PANEL_PLACEMENT, DEFAULT_RECENT_COLORS, DEFAULT_TOOLBAR_FONTS, DEFAULT_TOOLBAR_FONT_SIZES, DropdownItemCell, EXTREMITY_OPTIONS, FONTS, ICON_PATHS, LINE_TYPES, MAX_RECENT_COLORS, STICKY_SWATCHES, StickyNoteStyleToolbar, TextAnnotationToolbar, TextStyleToolbar, attachPanelVisibility, classifyPanelAnnotationType, createRgbaColorPicker, initialRecentColors, rgbaToString, svgIcon, withColorFromAnnotation };
+export type { AnnotationPanelOptions, AnnotationStyleToolbarOptions, AnnotationToolbarOptions, AnnotationToolbarStyles, BackgroundOption, ColorCellOptions, DeleteMode, ExtremityOption, FontOption, IconName, LineTypeOption, PanelAnnotationType, PanelOrientation, PanelPlacement, PanelVisibilityControl, PanelVisibilityHandlers, RecentColorsState, RgbaChannels, RgbaColor, RgbaColorPicker, Swatch, TextAnnotationToolbarOptions, TextStyleToolbarOptions, ToolbarButtonItem, ToolbarCell, ToolbarCellContext, ToolbarCustomItem, ToolbarDrawingType, ToolbarDropdownItem, ToolbarDropdownOption, ToolbarItem, ToolbarSeparatorItem };