image-annotation-drawer 1.3.1 → 1.3.2

package/dist/index.d.ts

@@ -1,3 +1,1075 @@
+/**
+ * 类型定义模块
+ * 包含所有标注库的类型定义
+ */
+/** 点坐标 */
+type Point = {
+    x: number;
+    y: number;
+};
+/** 矩形标注 */
+type Rect = {
+    start: Point;
+    width: number;
+    height: number;
+};
+/** 多边形顶点 */
+type Polygon = {
+    point: Point;
+};
+/** 文本标注 */
+type TextAnnotation = {
+    /** 稳定唯一 ID（入库时生成） */
+    id?: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    text: string;
+    width: number;
+    height: number;
+    /** 文本标注的独立样式 */
+    style?: Pick<TextStyle, 'font' | 'color' | 'backgroundColor'>;
+};
+/** 标注类型联合 */
+type Shape = Rect | Polygon | TextAnnotation;
+/** 边线样式 */
+type LineStyle = 'solid' | 'dashed' | 'dotted';
+/** 顶点样式 */
+type VertexStyle = {
+    size: number;
+    fillColor: string;
+    strokeColor: string;
+    strokeWidth: number;
+    shape: 'circle' | 'square' | 'diamond';
+};
+/** 标题样式 */
+type TitleStyle = {
+    /** 字体样式，如 "bold 12px Arial" */
+    font?: string;
+    /** 文字颜色 */
+    color?: string;
+    /** 背景颜色 */
+    backgroundColor?: string;
+    /** 水平内边距 */
+    paddingX?: number;
+    /** 垂直内边距 */
+    paddingY?: number;
+    /** 圆角半径 */
+    borderRadius?: number;
+    /** 标题输入框的占位提示文本（随标题样式快照存入标注） */
+    placeholder?: string;
+};
+/** 标题位置 */
+type TitlePosition = {
+    /** 垂直位置：top=标注上方, bottom=标注下方, inside-top=标注内部上方 */
+    vertical?: 'top' | 'bottom' | 'inside-top';
+    /** 水平对齐：left/center/right */
+    align?: 'left' | 'center' | 'right';
+    /** 水平偏移（像素，图像坐标） */
+    offsetX?: number;
+    /** 垂直偏移（像素，图像坐标） */
+    offsetY?: number;
+};
+/** 标注样式 */
+type AnnotationStyle = {
+    strokeColor: string;
+    lineWidth: number;
+    lineStyle?: LineStyle;
+    vertexStyle?: VertexStyle;
+    /** 标注标题样式（覆盖全局默认） */
+    titleStyle?: TitleStyle;
+    /** 标注标题位置（覆盖全局默认） */
+    titlePosition?: TitlePosition;
+    /** 标题位置是否由用户显式设置（true 时不参与设置标题时的自动边缘判断） */
+    titlePositionExplicit?: boolean;
+};
+/** 操作记录 */
+type Operate<T extends Shape> = {
+    /** 稳定唯一 ID（入库时生成；绘制中的临时对象无 id） */
+    id?: string;
+    type: "rect" | "polygon" | "drag" | "text" | "";
+    data: T[];
+    status: "fullfilled" | "pending";
+    style?: AnnotationStyle;
+    /** 标注标题 */
+    title?: string;
+};
+/** 绘制类型 */
+type DrawType = "rect" | "polygon" | "drag" | "text" | "";
+/** 抽屉选项 */
+type DrawerOptions = {
+    id: string;
+    drawType?: DrawType;
+    useEvents?: boolean;
+    /** 标注颜色配置 */
+    annotationColor?: string | ColorConfig;
+    /** 边线样式 */
+    lineStyle?: LineStyle;
+    /** 顶点样式 */
+    vertexStyle?: Partial<VertexStyle>;
+    /** 文本样式 */
+    textStyle?: Partial<TextStyle>;
+    /** 是否启用标注标题功能（默认 false，需显式开启） */
+    enableTitle?: boolean;
+    /** 是否将绘制坐标约束在图片边界内（默认 true，图片未加载时自动跳过） */
+    clampToImageBounds?: boolean;
+};
+/** 选中标注信息 */
+type SelectedAnnotation = {
+    index: number;
+    type: "rect" | "polygon" | "text";
+    /** 锁定选中态：true 时无控制点（不可 resize）；可选字段，缺省视为 false */
+    locked?: boolean;
+};
+/** 控制点信息 */
+type ActiveHandle = {
+    type: "rect-corner" | "polygon-vertex";
+    index: number;
+};
+/** 事件处理器类型 */
+type WheelEventListener = (event: WheelEvent) => void;
+type MouseEventListener = (event: MouseEvent) => void;
+type KeyboardEventListener = (event: KeyboardEvent) => void;
+/** 抽屉事件处理器集合 */
+type DrawerEventHandlers = {
+    wheel: WheelEventListener;
+    mousedown: MouseEventListener;
+    mousemove: MouseEventListener;
+    mouseup: MouseEventListener;
+    mouseleave: MouseEventListener;
+    dblclick: MouseEventListener;
+    click: MouseEventListener;
+    keydown: KeyboardEventListener;
+};
+/** 文本输入框样式 */
+type TextInputStyle = {
+    border: string;
+    borderRadius: string;
+    padding: string;
+    fontSize: string;
+    fontFamily: string;
+    backgroundColor: string;
+    color: string;
+    boxShadow: string;
+    minWidth: string;
+    maxWidth: string;
+};
+/** 文本样式配置 */
+type TextStyle = {
+    font: string;
+    color: string;
+    padding: number;
+    backgroundColor: string;
+    borderRadius: number;
+    selectedBorderColor: string;
+    selectedBackgroundColor: string;
+    /** 文本输入框样式 */
+    inputStyle?: Partial<TextInputStyle>;
+};
+/** 选中样式配置 */
+type SelectionStyle = {
+    strokeColor: string;
+    fillColor: string;
+    handleSize: number;
+    handleColor: string;
+};
+/** 颜色配置 */
+type ColorConfig = {
+    rect?: string;
+    polygon?: string;
+    text?: string;
+    default?: string;
+};
+/** 视口尺寸 */
+type ViewportSize = {
+    width: number;
+    height: number;
+};
+/** 视图偏移 */
+type ViewportOffset = {
+    x: number;
+    y: number;
+};
+/** 标注变更事件载荷（create/delete/update 共用） */
+type ShapeChangePayload = {
+    id: string;
+    type: 'rect' | 'polygon';
+    index: number;
+    data: Operate<Rect | Polygon>;
+} | {
+    id: string;
+    type: 'text';
+    index: number;
+    data: TextAnnotation;
+};
+/** Drawer 事件表 */
+type DrawerEventMap = {
+    /** 新标注画完入库 */
+    create: ShapeChangePayload;
+    /** 标注被删除 */
+    delete: ShapeChangePayload;
+    /** 标注数据变化（移动/缩放结束、标题/文本/样式修改） */
+    update: ShapeChangePayload;
+    /** 清空所有标注 */
+    clear: undefined;
+    /** 撤销成功 */
+    undo: undefined;
+};
+type DrawerEventName = keyof DrawerEventMap;
+type DrawerListener<K extends DrawerEventName> = (payload: DrawerEventMap[K]) => void;
+/** 标注变更通知回调（manager 内部上报给 Drawer 使用） */
+type ChangeNotify = (event: 'create' | 'delete' | 'update', payload: ShapeChangePayload) => void;
+
+/**
+ * 工具函数模块
+ * 包含几何计算、坐标转换等通用工具函数
+ */
+
+/**
+ * 检测点是否在矩形内
+ * 支持负宽高的情况（从右下往左上画）
+ */
+declare function isPointInRect(point: Point, rect: Rect): boolean;
+/**
+ * 检测点是否在多边形内（射线法）
+ */
+declare function isPointInPolygon(point: Point, polygon: Polygon[]): boolean;
+/**
+ * 从 URL 解析图片类型
+ * 支持 png, jpg, jpeg, webp, gif, bmp, svg 等常见格式
+ */
+declare function getImageTypeFromUrl(urlString: string): string;
+/**
+ * 将 base64 字符串转换为 File 对象
+ */
+declare function base64ToFile(base64Data: string, filename: string): File;
+/**
+ * 将 base64 字符串转换为 Blob 对象（用于上传）
+ */
+declare function base64ToBlob(base64: string): Promise<Blob>;
+/**
+ * 计算缩放增量
+ */
+declare function getZoomDelta(currentScale: number, zoomIn: boolean): number;
+
+/**
+ * 视图管理模块
+ * 负责视口尺寸、缩放、偏移、边界约束等视图相关功能
+ */
+
+declare class ViewportManager {
+    width: number;
+    height: number;
+    originalWidth: number;
+    originalHeight: number;
+    scale: number;
+    minScale: number;
+    maxScale: number;
+    offset: ViewportOffset;
+    initialScale: number;
+    initialOffset: ViewportOffset;
+    isInitialScale: boolean;
+    minOffsetX: number;
+    minOffsetY: number;
+    maxOffsetX: number;
+    maxOffsetY: number;
+    /**
+     * 设置视口尺寸
+     */
+    setSize(width: number, height: number): void;
+    /**
+     * 设置原始图片尺寸
+     */
+    setOriginalSize(width: number, height: number): void;
+    /**
+     * 计算初始视图参数
+     */
+    calculateInitialView(): void;
+    /**
+     * 计算边界约束
+     */
+    calculateBoundaries(): void;
+    /**
+     * 确保视图在合理范围内
+     */
+    constrainViewport(): void;
+    /**
+     * 将画布坐标转换为图像坐标
+     */
+    toImageCoordinates(canvasX: number, canvasY: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * 将图像坐标转换为画布坐标
+     */
+    toCanvasCoordinates(imgX: number, imgY: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * 更新缩放比例
+     */
+    updateScale(newScale: number, centerX: number, centerY: number): void;
+    /**
+     * 重置视图到初始状态
+     */
+    resetToInitial(): void;
+    /**
+     * 更新偏移量（用于拖拽）
+     */
+    updateOffset(dx: number, dy: number): void;
+    /**
+     * 重置所有状态
+     */
+    reset(): void;
+}
+
+/**
+ * 形状策略接口：每种标注形状（rect/polygon/未来星型）实现一个策略
+ * 策略是无状态的纯逻辑单元，所有共享状态存于 AnnotationStore
+ */
+
+/** resize 所需的原始数据快照（rect 用 Rect 副本，polygon 用 Polygon[] 副本） */
+type ResizeSnapshot = Rect | Polygon[];
+interface ShapeStrategy<T extends Rect | Polygon = Rect | Polygon> {
+    readonly type: 'rect' | 'polygon';
+    /** 开始绘制（point 已由 store 完成 clamp） */
+    startDrawing(store: StrategyStore, point: Point): void;
+    /** 更新绘制中状态（rect: 更新宽高；polygon: 更新临时点） */
+    updateDrawing(store: StrategyStore, point: Point): void;
+    /** 尝试加点（仅 polygon 有意义；rect 空实现返回 false）。返回是否实际添加 */
+    addPoint(store: StrategyStore, point: Point): boolean;
+    /** 完成绘制；满足入库条件则推入 recordList 并 notifyChange('create')。返回是否结束了绘制 */
+    finishDrawing(store: StrategyStore): boolean;
+    /** 取消绘制（polygon ≥2 点保存入库的现有行为在策略内实现） */
+    cancelDrawing(store: StrategyStore): void;
+    /** 撤销绘制中状态（polygon 逐点 pop；rect 整体清）。返回是否有动作 */
+    withdrawInProgress(store: StrategyStore): boolean;
+    hitTest(record: Operate<T>, imgCoords: Point): boolean;
+    /** 返回画布坐标系控制点列表 */
+    getHandles(record: Operate<T>, viewport: ViewportManager, handleSize: number): {
+        x: number;
+        y: number;
+        index: number;
+    }[];
+    move(record: Operate<T>, dx: number, dy: number): void;
+    /** 拍摄 resize 前快照 */
+    snapshotForResize(record: Operate<T>): ResizeSnapshot;
+    /** 执行 resize；如需交换控制点（rect 越过交换）返回新 handle index，否则返回 undefined */
+    resize(record: Operate<T>, handleIndex: number, currentPoint: Point, snapshot: ResizeSnapshot): number | undefined;
+    /** 标题/导出参考边界（图像坐标）：rect 用自身，polygon 用顶点 bbox */
+    getBounds(record: Operate<T>): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** 策略视角的 Store 最小契约（AnnotationStore 实现它） */
+interface StrategyStore {
+    operate: Operate<Rect | Polygon>;
+    isDrawing: boolean;
+    drawStartPoint: Point;
+    tempPolygonPoint: Point | null;
+    recordList: Operate<Rect | Polygon>[];
+    strokeStyle: string;
+    lineWidth: number;
+    getCurrentStyle(): AnnotationStyle;
+    clamp(point: Point): Point;
+    pushRecord(record: Operate<Rect | Polygon>): void;
+}
+
+/**
+ * 标注存储基类
+ * 持有标注的全部共享状态与共享逻辑（选中/删除/撤销编排/样式/颜色/标题/clamp/通知/清空），
+ * 形状特异逻辑通过 ShapeStrategy 委托（见 shapes/ 目录），由子类 AnnotationManager 分发。
+ *
+ * 实现 StrategyStore 契约，供无状态策略读写绘制中状态。
+ */
+
+declare class AnnotationStore implements StrategyStore {
+    protected viewport: ViewportManager;
+    protected container?: HTMLElement | undefined;
+    protected renderCallback?: (() => void) | undefined;
+    protected changeCallback?: ChangeNotify | undefined;
+    recordList: Operate<Rect | Polygon>[];
+    operate: Operate<Rect | Polygon>;
+    isDrawing: boolean;
+    drawStartPoint: Point;
+    tempPolygonPoint: Point | null;
+    selectedAnnotation: SelectedAnnotation | null;
+    isMovingAnnotation: boolean;
+    isResizing: boolean;
+    activeHandle: ActiveHandle | null;
+    annotationMoveStart: Point;
+    originalRect: Rect | null;
+    originalPolygon: Polygon[] | null;
+    protected deleteHistory: {
+        annotation: Operate<Rect | Polygon>;
+        index: number;
+    }[];
+    editingTitleIndex: number | null;
+    titleInput: HTMLInputElement | null;
+    strokeStyle: string;
+    lineWidth: number;
+    lineStyle: LineStyle;
+    vertexStyle: VertexStyle;
+    selectionStyle: SelectionStyle;
+    private colorConfig;
+    titleStyle: TitleStyle;
+    titlePosition: TitlePosition;
+    enableTitle: boolean;
+    measureTitleWidth?: (text: string, font: string) => number;
+    clampEnabled: boolean;
+    constructor(viewport: ViewportManager, container?: HTMLElement | undefined, renderCallback?: (() => void) | undefined, changeCallback?: ChangeNotify | undefined);
+    /**
+     * 按形状类型查找策略（委托默认注册表）
+     */
+    protected strategyOf(type: 'rect' | 'polygon'): ShapeStrategy;
+    /**
+     * 将点约束到图片边界内（StrategyStore 契约；委托 shapes/shared.clampPoint）
+     */
+    clamp(point: Point): Point;
+    /**
+     * 将点约束到图片边界内（原图像素坐标系）
+     * clampEnabled 为 false 或图片未加载（originalWidth/originalHeight 为 0）时跳过 clamp，原样返回
+     */
+    protected clampToImageBounds(point: Point): Point;
+    /**
+     * 把**整个标注**约束到图片边界内 —— 供「移动 / 缩放已有标注」使用。
+     *
+     * 为什么需要单独一个：`strategy.move()` 只是把坐标整体加 dx/dy，`resize()` 直接用鼠标点，
+     * 两者原先都没有边界判断，所以已有标注能被拖到/缩到图外；
+     * 而 `clampToImageBounds(point)` 只作用于绘制入口（startRectDrawing / updateRectDrawing 等）。
+     *
+     * - `clampEnabled` 为 false 或图片未加载时原样返回
+     * - 矩形：按包围盒先把尺寸限制到不超过图片，再把左上角夹到 `[0, w-width] × [0, h-height]`
+     * - 多边形：按包围盒整体平移；比图片还大时贴左上角
+     * - **完全在图内时不做任何改动**（保留调用方原有的坐标表示，例如负宽高）
+     */
+    protected clampRecordToImageBounds(record: Operate<Rect | Polygon>): void;
+    /**
+     * 新标注入库：generateId + 当前样式快照 + push + 清删除历史 + notifyChange('create')
+     * （统一自原 finishRectDrawing / finishPolygonDrawing / cancelDrawing 的入库尾段；
+     *  记录 status 由策略在调用前自行设定，store 不统一改写）
+     */
+    pushRecord(record: Operate<Rect | Polygon>): void;
+    /**
+     * 初始化标题功能（由 Drawer 在设置 enableTitle 后调用）
+     */
+    initTitleSupport(): void;
+    /**
+     * 设置颜色配置
+     */
+    setColorConfig(config: string | ColorConfig): void;
+    /**
+     * 获取颜色配置
+     */
+    getColorConfig(): ColorConfig;
+    /**
+     * 应用颜色配置到当前样式
+     */
+    private applyColorConfig;
+    /**
+     * 获取指定类型的颜色
+     */
+    getColorForType(type: 'rect' | 'polygon' | 'default'): string;
+    /**
+     * 获取当前样式（用于创建新标注时保存）
+     */
+    getCurrentStyle(): AnnotationStyle;
+    /**
+     * 上报标注变更（载荷携带深拷贝快照；委托 shapes/shared.notifyShapeChange）
+     */
+    protected notifyChange(event: 'create' | 'delete' | 'update', index: number, annotation: Operate<Rect | Polygon>): void;
+    /**
+     * 供 Drawer 在程序化移动后触发 update（拖拽路径由 finishMovingAnnotation 触发）
+     */
+    notifyUpdate(index: number): void;
+    /**
+     * 解析标注定位参数：number 按索引，string 按 id
+     */
+    resolveIndex(ref: number | string): number;
+    /**
+     * 按索引或 id 获取单个标注（深拷贝快照）
+     */
+    getAnnotation(ref: number | string): Operate<Rect | Polygon> | undefined;
+    /**
+     * 将当前全局样式应用到指定标注（按索引或 id），保存并通知 update
+     */
+    updateAnnotationStyle(ref: number | string): boolean;
+    /**
+     * 设置边线样式
+     */
+    setLineStyle(style: LineStyle): void;
+    /**
+     * 设置顶点样式
+     */
+    setVertexStyle(style: Partial<VertexStyle>): void;
+    /**
+     * 获取边线样式
+     */
+    getLineStyle(): LineStyle;
+    /**
+     * 获取顶点样式
+     */
+    getVertexStyle(): VertexStyle;
+    /**
+     * 获取标注的样式（如果不存在则返回当前样式）
+     */
+    getAnnotationStyle(annotation: Operate<Rect | Polygon>): AnnotationStyle;
+    /**
+     * 撤销操作（编排顺序：先策略撤销绘制中状态，再 deleteHistory 恢复，再 recordList.pop）
+     */
+    withdraw(): boolean;
+    /**
+     * 选中指定索引或 id 的标注
+     * @param ref - 标注索引或 id
+     * @param options.lock - true 时进入锁定选中态（无控制点，不可 resize）；缺省/false 与现状一致
+     */
+    selectAnnotation(ref: number | string, options?: {
+        lock?: boolean;
+    }): boolean;
+    /**
+     * 取消选中
+     */
+    deselectAnnotation(): void;
+    /**
+     * 删除选中的标注
+     */
+    deleteSelectedAnnotation(): boolean;
+    /**
+     * 开始移动标注（锁定选中态不可交互移动；程序化 moveSelectedAnnotation 不受此限制）
+     */
+    startMovingAnnotation(e: MouseEvent): boolean;
+    /**
+     * 更新移动起始点（供事件层在移动过程中同步鼠标位置，替代越权直写 annotationMoveStart）
+     */
+    updateMoveStart(p: Point): void;
+    /**
+     * 完成标注移动
+     */
+    finishMovingAnnotation(): void;
+    /**
+     * 清除所有标注
+     */
+    clear(): void;
+    /**
+     * 获取所有标注数据
+     */
+    getAnnotations(): Operate<Rect | Polygon>[];
+    /**
+     * 获取当前选中的标注信息
+     */
+    getSelectedAnnotation(): {
+        index: number;
+        type: "rect" | "polygon" | "text";
+        data: Operate<Rect | Polygon>;
+    } | null;
+    /**
+     * 设置标题样式（全局默认）
+     * @param style - 标题样式配置
+     */
+    setTitleStyle(style: Partial<TitleStyle>): void;
+    /**
+     * 获取当前标题样式
+     */
+    getTitleStyle(): TitleStyle;
+    /**
+     * 设置标题位置（全局默认）
+     * @param position - 标题位置配置
+     */
+    setTitlePosition(position: Partial<TitlePosition>): void;
+    /**
+     * 获取当前标题位置
+     */
+    getTitlePosition(): TitlePosition;
+    /**
+     * 获取标注实际使用的标题样式（标注自定义样式优先于全局默认）
+     */
+    getEffectiveTitleStyle(annotation: Operate<Rect | Polygon>): TitleStyle;
+    /**
+     * 获取标注实际使用的标题位置（标注自定义位置优先于全局默认）
+     */
+    getEffectiveTitlePosition(annotation: Operate<Rect | Polygon>): TitlePosition;
+    /**
+     * 将当前全局标题样式/位置快照存入标注（设置标题时自动调用）
+     */
+    private captureTitleStyleSnapshot;
+    /**
+     * 设置标题时按图片初始显示尺寸自动判断标题位置（翻转优先 + 贴边），并写回标注。
+     * 规则：显式设置过位置、图片未加载、空多边形时跳过。
+     */
+    private autoAdjustTitlePosition;
+    /**
+     * 图片加载完成后，对所有「未显式设置位置」的标题补做一次边缘判断。
+     * 用于图片尚未加载时就通过 API 设置了标题的场景。
+     */
+    adjustTitlePositions(): void;
+    /**
+     * 单独修改某个标注的标题样式（不影响全局默认）
+     * @param ref - 标注索引或 id
+     * @param style - 标题样式（部分覆盖）
+     */
+    setAnnotationTitleStyle(ref: number | string, style: Partial<TitleStyle>): boolean;
+    /**
+     * 单独修改某个标注的标题位置（不影响全局默认）
+     * @param ref - 标注索引或 id
+     * @param position - 标题位置（部分覆盖）
+     */
+    setAnnotationTitlePosition(ref: number | string, position: Partial<TitlePosition>): boolean;
+    /**
+     * 创建标题输入框
+     */
+    private createTitleInput;
+    /**
+     * 设置标注标题（API调用）
+     * @param ref - 标注索引或 id
+     * @param title - 标题文本
+     */
+    setTitle(ref: number | string, title: string): boolean;
+    /**
+     * 获取标注标题
+     * @param ref - 标注索引或 id
+     */
+    getTitle(ref: number | string): string | undefined;
+    /**
+     * 开始编辑标题（双击或API触发）
+     * @param index - 标注索引
+     */
+    startTitleEditing(index: number): boolean;
+    /**
+     * 完成标题编辑
+     */
+    finishTitleEditing(): boolean;
+    /**
+     * 取消标题编辑
+     */
+    cancelTitleEditing(): boolean;
+    /**
+     * 重置标题编辑状态
+     */
+    private resetTitleEditingState;
+    /**
+     * 清理标题输入框
+     */
+    destroyTitleInput(): void;
+}
+
+/**
+ * 标注管理模块（兼容层）
+ * 继承 AnnotationStore 获得全部共享状态与共享方法，
+ * 形状特异方法在此按类型委托给 ShapeStrategy（见 shapes/ 目录与 registry.ts）。
+ * 公共 API（构造签名、方法签名、字段名、通知时机）与原实现完全一致。
+ */
+
+declare class AnnotationManager extends AnnotationStore {
+    /**
+     * 开始绘制矩形
+     */
+    startRectDrawing(startPoint: Point): void;
+    /**
+     * 更新矩形绘制
+     */
+    updateRectDrawing(currentPoint: Point): void;
+    /**
+     * 完成矩形绘制
+     */
+    finishRectDrawing(): boolean;
+    /**
+     * 开始绘制多边形
+     */
+    startPolygonDrawing(startPoint: Point): void;
+    /**
+     * 添加多边形点
+     */
+    addPolygonPoint(point: Point): boolean;
+    /**
+     * 更新多边形临时点
+     */
+    updatePolygonTempPoint(point: Point): void;
+    /**
+     * 完成多边形绘制
+     */
+    finishPolygonDrawing(): boolean;
+    /**
+     * 取消当前绘制（按 operate.type 分发；polygon ≥2 点保存入库的行为在策略内；
+     * 非 polygon 一律按 rect 语义复位，与原实现的尾部三行一致）
+     */
+    cancelDrawing(): void;
+    /**
+     * 移动选中的标注
+     */
+    moveSelectedAnnotation(dx: number, dy: number): boolean;
+    /**
+     * 开始调整大小（拍摄一次 resize 快照；拖拽期间策略原地同步快照，store 不重拍）
+     */
+    startResizing(handle: ActiveHandle, _startPoint: Point): boolean;
+    /**
+     * 调整矩形大小（策略返回越过交换后的新 handle index 时写回 activeHandle.index）
+     */
+    resizeRect(currentPoint: Point): boolean;
+    /**
+     * 调整多边形顶点位置
+     */
+    resizePolygon(currentPoint: Point): boolean;
+    /**
+     * 获取点击位置对应的标注（倒序遍历，优先上层）
+     */
+    getAnnotationAtPoint(imgCoords: Point): SelectedAnnotation | null;
+    /**
+     * 获取点击位置的控制点（命中判定在 store：控制点画布坐标 ± handleSize/2）
+     */
+    getHandleAtPoint(offsetX: number, offsetY: number): ActiveHandle | null;
+}
+
+/**
+ * 文本标注模块
+ * 负责文本标注的添加、编辑、移动、删除等功能
+ */
+
+declare class TextAnnotationManager {
+    private viewport;
+    private container;
+    private ctx;
+    private renderCallback?;
+    private changeCallback?;
+    textAnnotations: TextAnnotation[];
+    editingTextIndex: number | null;
+    currentEditingIndex: number | null;
+    movingTextIndex: number | null;
+    isTextMoving: boolean;
+    textMoveStart: Point;
+    textBeforeEditing: string;
+    selectedTextIndex: number | null;
+    clampEnabled: boolean;
+    textInput: HTMLInputElement | null;
+    private deleteHistory;
+    private defaultInputStyle;
+    textStyle: TextStyle;
+    constructor(viewport: ViewportManager, container: HTMLElement, ctx: CanvasRenderingContext2D, renderCallback?: (() => void) | undefined, changeCallback?: ChangeNotify | undefined);
+    /**
+     * 创建文本输入框
+     */
+    private createTextInput;
+    /**
+     * 应用输入框样式
+     */
+    private applyInputStyle;
+    /**
+     * 设置文本样式
+     */
+    setTextStyle(style: Partial<TextStyle>): void;
+    /**
+     * 设置输入框样式
+     */
+    setInputStyle(style: Partial<TextInputStyle>): void;
+    /**
+     * 设置选中态样式
+     */
+    setSelectionStyle(style: {
+        selectedBorderColor?: string;
+        selectedBackgroundColor?: string;
+    }): void;
+    /**
+     * 获取当前文本样式（用于创建新标注时保存）
+     */
+    getCurrentStyle(): Pick<TextStyle, 'font' | 'color' | 'backgroundColor'>;
+    /**
+     * 上报文本标注变更（载荷携带深拷贝快照）
+     */
+    private notifyChange;
+    /**
+     * 解析文本标注定位参数：number 按索引，string 按 id
+     */
+    resolveIndex(ref: number | string): number;
+    /**
+     * 按索引或 id 获取单个文本标注（深拷贝快照）
+     */
+    getTextAnnotation(ref: number | string): TextAnnotation | undefined;
+    /**
+     * 更新指定文本标注的样式（部分覆盖，不影响全局默认和其他标注）
+     * @param ref - 文本标注索引或 id
+     * @param style - 样式（部分覆盖）
+     */
+    updateTextAnnotationStyle(ref: number | string, style: Partial<Pick<TextStyle, 'font' | 'color' | 'backgroundColor'>>): boolean;
+    /**
+     * 将点约束到图片边界内（原图像素坐标系）
+     * clampEnabled 为 false 或图片未加载（originalWidth/originalHeight 为 0）时跳过 clamp，原样返回
+     */
+    private clampToImageBounds;
+    /**
+     * 添加文本标注
+     * @param x - 图像坐标 X（标注背景框左上角）
+     * @param y - 图像坐标 Y（标注背景框左上角）
+     * @param text - 初始文本（可选，默认为空字符串）
+     */
+    addTextAnnotation(x: number, y: number, text?: string): number;
+    /**
+     * 更新文本标注内容
+     */
+    updateTextAnnotation(ref: number | string, text: string): boolean;
+    /**
+     * 移动文本标注位置
+     */
+    moveTextAnnotation(ref: number | string, x: number, y: number): boolean;
+    /**
+     * 删除文本标注
+     */
+    removeTextAnnotation(ref: number | string): boolean;
+    /**
+     * 清除所有文本标注
+     */
+    clearTextAnnotations(): void;
+    /**
+     * 开始编辑文本标注
+     */
+    startEditing(index: number): boolean;
+    /**
+     * 完成编辑
+     */
+    finishEditing(): boolean;
+    /**
+     * 取消编辑
+     */
+    cancelEditing(): boolean;
+    /**
+     * 删除正在编辑的文本标注
+     */
+    deleteEditingAnnotation(): boolean;
+    /**
+     * 重置编辑状态
+     */
+    private resetEditingState;
+    /**
+     * 调整输入框宽度
+     */
+    private adjustInputWidth;
+    /**
+     * 开始移动文本标注
+     */
+    startMoving(e: MouseEvent, index: number): boolean;
+    /**
+     * 移动文本标注
+     */
+    moveAnnotation(e: MouseEvent): boolean;
+    /**
+     * 完成移动
+     */
+    finishMoving(): void;
+    /**
+     * 结束文本移动（不触碰编辑态）
+     */
+    endTextMoving(): void;
+    /**
+     * 当前是否处于 DOM 编辑可见状态（输入框显示中）
+     */
+    isEditingVisible(): boolean;
+    /**
+     * 检查是否点击了文本标注
+     */
+    checkTextClick(offsetX: number, offsetY: number): number | null;
+    /**
+     * 检查是否点击了文本标注（用于移动）
+     */
+    checkTextClickForMove(e: MouseEvent): {
+        index: number;
+        handled: boolean;
+    };
+    /**
+     * 获取所有文本标注
+     */
+    getTextAnnotations(): TextAnnotation[];
+    /**
+     * 撤销文本标注
+     */
+    withdraw(): boolean;
+    /**
+     * 选中文本标注
+     */
+    selectTextAnnotation(index: number): boolean;
+    /**
+     * 取消选中文本标注
+     */
+    deselectTextAnnotation(): void;
+    /**
+     * 删除选中的文本标注
+     */
+    deleteSelectedTextAnnotation(): boolean;
+    /**
+     * 获取选中的文本标注信息
+     */
+    getSelectedTextAnnotation(): {
+        index: number;
+        data: TextAnnotation;
+    } | null;
+    /**
+     * 销毁（清理 DOM）
+     */
+    destroy(): void;
+}
+
+/**
+ * 渲染模块
+ * 渲染管线：背景图片 → 形状标注（策略表分发） → 选中高亮 → 文本标注
+ * 形状特异绘制逻辑已拆至 renderers/ 目录（Task 7）
+ */
+
+declare class Renderer {
+    private ctx;
+    private viewport;
+    private annotationManager;
+    private textManager;
+    /** 形状渲染策略表 */
+    private shapeRenderers;
+    constructor(ctx: CanvasRenderingContext2D, viewport: ViewportManager, annotationManager: AnnotationManager, textManager: TextAnnotationManager);
+    /**
+     * 主渲染方法
+     */
+    render(bgImage: HTMLImageElement | null): void;
+    /**
+     * 绘制背景图片
+     */
+    private drawBackgroundImage;
+    /**
+     * 绘制标注（矩形、多边形）——ctx 状态由管线统一设置，几何绘制委托策略表
+     */
+    private drawAnnotations;
+    /**
+     * 绘制选中状态的标注高亮（读取锁定态：locked 时策略不画控制点）
+     */
+    private drawSelectionHighlight;
+    /**
+     * 绘制标注标题
+     * @param annotation - 标注操作记录
+     */
+    private drawAnnotationTitle;
+    /**
+     * 导出时绘制所有内容到指定上下文
+     */
+    drawForExport(ctx: CanvasRenderingContext2D, bgImage: HTMLImageElement, originalWidth: number, originalHeight: number): void;
+}
+
+/**
+ * 事件处理模块
+ * 负责所有用户交互事件的处理
+ */
+
+declare class EventHandler {
+    private canvas;
+    private viewport;
+    private annotationManager;
+    private textManager;
+    private renderer;
+    private getDrawType;
+    private getBgImage;
+    private renderCallback;
+    private setDrawTypeCallback;
+    private notifyUndo;
+    isDragging: boolean;
+    dragStart: Point;
+    justFinishedMove: boolean;
+    justDeselected: boolean;
+    constructor(canvas: HTMLCanvasElement, viewport: ViewportManager, annotationManager: AnnotationManager, textManager: TextAnnotationManager, renderer: Renderer, getDrawType: () => DrawType, getBgImage: () => HTMLImageElement | null, renderCallback: () => void, setDrawTypeCallback: (type: DrawType) => void, notifyUndo: () => void);
+    /**
+     * 处理滚轮缩放
+     */
+    handleWheel(e: WheelEvent): void;
+    /**
+     * 处理鼠标按下
+     */
+    handleMouseDown(e: MouseEvent): void;
+    /**
+     * 文本模式下的点击处理
+     */
+    private handleTextModeClick;
+    /**
+     * 矩形模式下的点击处理
+     */
+    private handleRectModeClick;
+    /**
+     * 多边形模式下的点击处理
+     */
+    private handlePolygonModeClick;
+    /**
+     * 无模式下的点击处理
+     */
+    private handleNoModeClick;
+    /**
+     * 检查多边形点是否有效（避免重复点）
+     */
+    private checkPolygonPointValid;
+    /**
+     * 处理鼠标移动
+     */
+    handleMouseMove(e: MouseEvent): void;
+    /**
+     * 处理标注移动或调整大小
+     */
+    private handleAnnotationMove;
+    /**
+     * 悬停点是否为锁定选中的标注（锁定态不显示 move 光标）
+     */
+    private isHoverLockedAnnotation;
+    /**
+     * 更新鼠标光标样式
+     */
+    private updateCursor;
+    /**
+     * 更新矩形模式光标
+     */
+    private updateRectModeCursor;
+    /**
+     * 更新多边形模式光标
+     */
+    private updatePolygonModeCursor;
+    /**
+     * 更新拖拽模式光标
+     */
+    private updateDragModeCursor;
+    /**
+     * 更新无模式光标
+     */
+    private updateNoModeCursor;
+    /**
+     * 处理鼠标释放
+     */
+    handleMouseUp(_e: MouseEvent): void;
+    /**
+     * 处理鼠标离开
+     */
+    handleMouseLeave(e: MouseEvent): void;
+    /**
+     * 处理鼠标双击
+     */
+    handleDoubleClick(e: MouseEvent): void;
+    /**
+     * 处理鼠标单击（用于多边形绘制；加点已收敛到 mousedown 通道，
+     * 此处仅保留防误触发的守卫与 justDeselected 消费）
+     */
+    handleClick(_e: MouseEvent): void;
+    /**
+     * 处理键盘按下
+     */
+    handleKeyDown(e: KeyboardEvent): void;
+}
+
+/**
+ * 迷你事件发射器（零依赖）
+ * 供 Drawer 对外提供 on/off 订阅能力
+ */
+
+declare class Emitter {
+    private listeners;
+    on<K extends DrawerEventName>(event: K, listener: DrawerListener<K>): void;
+    off<K extends DrawerEventName>(event: K, listener: DrawerListener<K>): void;
+    emit<K extends DrawerEventName>(event: K, payload: DrawerEventMap[K]): void;
+    /** 清空所有监听器（destroy 时调用） */
+    clear(): void;
+}
+
 /**
  * Image Annotation Drawer
  * 一个轻量级的图片标注库，基于 HTML5 Canvas
@@ -10,16 +1082,7 @@
  * - 图片导出：支持导出标注后的图片
  * - TypeScript 支持：完整的类型定义
  */
-export type { Shape, Point, Rect, Polygon, TextAnnotation, Operate, DrawerOptions, DrawType, SelectedAnnotation, ActiveHandle, TextStyle, TextInputStyle, SelectionStyle, AnnotationStyle, LineStyle, VertexStyle, ColorConfig, ViewportSize, ViewportOffset, DrawerEventHandlers, TitleStyle, TitlePosition, DrawerEventMap, DrawerEventName, DrawerListener, ShapeChangePayload, ChangeNotify, } from './modules/types';
-export { isPointInRect, isPointInPolygon, getImageTypeFromUrl, base64ToFile, base64ToBlob, getZoomDelta, } from './modules/utils';
-export { ViewportManager } from './modules/viewport';
-export { AnnotationManager } from './modules/annotations';
-export { TextAnnotationManager } from './modules/shapes/text-manager';
-export { Renderer } from './modules/renderer';
-export { EventHandler } from './modules/events';
-export { Emitter } from './modules/emitter';
-import type { Rect, Polygon, TextAnnotation, Operate, DrawerOptions, DrawType, ColorConfig, LineStyle, VertexStyle, TextStyle, TextInputStyle, TitleStyle, TitlePosition } from './modules/types';
-import type { DrawerEventName, DrawerListener } from './modules/types';
+
 /**
  * Drawer 类 - 图片标注库的主入口
  *
@@ -32,7 +1095,7 @@ import type { DrawerEventName, DrawerListener } from './modules/types';
  * drawer.drawImage('image.jpg');
  * ```
  */
-export declare class Drawer {
+declare class Drawer {
     private canvas;
     private ctx;
     private container;
@@ -378,4 +1441,6 @@ export declare class Drawer {
      */
     destroy(): void;
 }
-export default Drawer;
+
+export { AnnotationManager, Drawer, Emitter, EventHandler, Renderer, TextAnnotationManager, ViewportManager, base64ToBlob, base64ToFile, Drawer as default, getImageTypeFromUrl, getZoomDelta, isPointInPolygon, isPointInRect };
+export type { ActiveHandle, AnnotationStyle, ChangeNotify, ColorConfig, DrawType, DrawerEventHandlers, DrawerEventMap, DrawerEventName, DrawerListener, DrawerOptions, LineStyle, Operate, Point, Polygon, Rect, SelectedAnnotation, SelectionStyle, Shape, ShapeChangePayload, TextAnnotation, TextInputStyle, TextStyle, TitlePosition, TitleStyle, VertexStyle, ViewportOffset, ViewportSize };