kviewer 0.0.1

package/dist/runtime/annotation/engine/editor/selector.js

@@ -0,0 +1,594 @@
+import Konva from "konva";
+import { AnnotationType } from "../types.js";
+import { SELECTOR_HOVER_STYLE, SHAPE_GROUP_NAME } from "../const.js";
+import { defaultOptions } from "../config.js";
+import { isStylusTouch } from "../input-device.js";
+export class Selector {
+  onSelected;
+  onChanged;
+  onDelete;
+  onCancel;
+  onMultiSelected;
+  onRequestDeleteConfirm;
+  onFreeTextDoubleClick;
+  getStylusModeEnabled;
+  transformerStore = /* @__PURE__ */ new Map();
+  getAnnotationStore;
+  konvaCanvasStore;
+  _currentTransformerId = null;
+  selectedId = null;
+  selectedIds = [];
+  marqueeRect = null;
+  marqueeStartPos = null;
+  marqueeStage = null;
+  constructor({
+    konvaCanvasStore,
+    getAnnotationStore,
+    onDelete,
+    onSelected,
+    onMultiSelected,
+    onCancel,
+    onChanged,
+    onRequestDeleteConfirm,
+    onFreeTextDoubleClick,
+    getStylusModeEnabled
+  }) {
+    this.konvaCanvasStore = konvaCanvasStore;
+    this.getAnnotationStore = getAnnotationStore;
+    this.onDelete = onDelete;
+    this.onSelected = onSelected;
+    this.onMultiSelected = onMultiSelected;
+    this.onCancel = onCancel;
+    this.onChanged = onChanged;
+    this.onRequestDeleteConfirm = onRequestDeleteConfirm;
+    this.onFreeTextDoubleClick = onFreeTextDoubleClick;
+    this.getStylusModeEnabled = getStylusModeEnabled;
+    this.handleKeyDown = this.handleKeyDown.bind(this);
+    window.addEventListener("keydown", this.handleKeyDown);
+  }
+  /** Returns true if this event should be rejected (finger touch in stylus mode). */
+  isStylusRejected(evt) {
+    if (!this.getStylusModeEnabled?.() || !evt) return false;
+    if (evt instanceof PointerEvent) return evt.pointerType === "touch";
+    if (typeof TouchEvent !== "undefined" && evt instanceof TouchEvent) return !isStylusTouch(evt);
+    return false;
+  }
+  handleKeyDown(e) {
+    const target = e.target;
+    if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target?.isContentEditable) return;
+    if (e.key === "Backspace" || e.key === "Delete") {
+      if (this.selectedIds.length > 0) {
+        e.preventDefault();
+        this.selectedIds.forEach((id) => this.onDelete(id));
+        this.selectedIds = [];
+        this.clearTransformers();
+      } else if (this._currentTransformerId) {
+        e.preventDefault();
+        this.onDelete(this._currentTransformerId);
+        this.clearTransformers();
+      }
+    }
+  }
+  get currentTransformerId() {
+    return this._currentTransformerId;
+  }
+  set currentTransformerId(id) {
+    if (this._currentTransformerId !== id) {
+      this.selectedId = id;
+      this.deactivateTransformer(this._currentTransformerId);
+      this._currentTransformerId = id;
+    }
+  }
+  disableStageEvents(konvaStage) {
+    konvaStage.off(
+      "click mousedown mousemove mouseup touchstart touchmove touchend pointerdown pointermove pointerup"
+    );
+  }
+  bindStageEvents(konvaStage) {
+    konvaStage.on("click tap", (e) => {
+      if (e.target !== konvaStage) return;
+      if (this.isStylusRejected(e.evt)) return;
+      this.clearTransformers();
+    });
+  }
+  getBackgroundLayer(konvaStage) {
+    return konvaStage.getLayers()[0];
+  }
+  getPageShapeGroups(konvaStage) {
+    return this.getBackgroundLayer(konvaStage).getChildren(
+      (node) => node.name() === SHAPE_GROUP_NAME
+    );
+  }
+  getGroupById(konvaStage, groupId) {
+    const pageGroups = this.getPageShapeGroups(konvaStage);
+    return pageGroups.find((group) => group.id() === groupId) || null;
+  }
+  getFirstShapeInGroup(group) {
+    return group.getChildren().find((node) => node instanceof Konva.Shape) || null;
+  }
+  enableShapeGroups(groups, konvaStage) {
+    groups.forEach((group) => {
+      group.getChildren().forEach((shape) => {
+        if (shape instanceof Konva.Shape) {
+          this.removeShapeEvents(shape);
+          this.bindShapeEvents(shape, konvaStage);
+        }
+      });
+    });
+  }
+  disableShapeGroups(groups) {
+    groups.forEach((group) => {
+      group.getChildren().forEach((shape) => {
+        if (shape instanceof Konva.Shape) {
+          this.removeShapeEvents(shape);
+        }
+      });
+    });
+  }
+  bindShapeEvents(shape, konvaStage) {
+    shape.on("pointerdblclick", async (e) => {
+      if (this.isStylusRejected(e.evt)) return;
+      const group = shape.findAncestor(`.${SHAPE_GROUP_NAME}`);
+      if (!group) return;
+      const id = group.id();
+      const store = this.getAnnotationStore(id);
+      if (store?.type === AnnotationType.FREETEXT && this.onFreeTextDoubleClick) {
+        this.onFreeTextDoubleClick(id);
+        return;
+      }
+      if (defaultOptions.setting.DB_CLICK_DELETE) {
+        if (this.onRequestDeleteConfirm) {
+          const confirmed = await this.onRequestDeleteConfirm(this.currentTransformerId);
+          if (confirmed) {
+            this.onDelete(this.currentTransformerId);
+            this.clearTransformers();
+          }
+        } else {
+          this.onDelete(this.currentTransformerId);
+          this.clearTransformers();
+        }
+      }
+    });
+    shape.on("pointerclick", (e) => {
+      if (this.isStylusRejected(e.evt)) return;
+      if (e.evt.button === 0) {
+        this.handleShapeClick(shape, konvaStage, true);
+      }
+    });
+    shape.on("mouseover", (e) => {
+      if (e.evt.button === 0) {
+        this.handleShapeMouseover();
+      }
+    });
+    shape.on("mouseout", (e) => {
+      if (e.evt.button === 0) {
+        this.handleShapeMouseout();
+      }
+    });
+  }
+  removeShapeEvents(shape) {
+    shape.off("pointerclick mouseover mouseout pointerdblclick");
+  }
+  handleShapeClick(shape, konvaStage, isClick = false) {
+    const group = shape.findAncestor(
+      `.${SHAPE_GROUP_NAME}`
+    );
+    if (!group) return;
+    this.clearTransformers();
+    this.createTransformer(group, konvaStage, !isClick);
+    const selectorRect = this.transformerStore.get(group.id()).getClientRect();
+    this.onSelected(group.id(), isClick, selectorRect);
+  }
+  createTransformer(group, konvaStage, flash) {
+    const line = group.children[0];
+    const groupId = group.id();
+    this.currentTransformerId = groupId;
+    const rawAnnotationStore = this.getAnnotationStore(groupId);
+    group.off("dragend");
+    const transformer = new Konva.Transformer({
+      resizeEnabled: rawAnnotationStore.resizable,
+      rotateEnabled: false,
+      borderStrokeWidth: defaultOptions.chooseSetting.STROKEWIDTH,
+      borderStroke: defaultOptions.chooseSetting.COLOR,
+      anchorFill: defaultOptions.chooseSetting.COLOR,
+      anchorStroke: defaultOptions.chooseSetting.COLOR,
+      opacity: defaultOptions.chooseSetting.OPACITY,
+      anchorCornerRadius: 5,
+      anchorStrokeWidth: 2,
+      anchorSize: 8,
+      padding: 1,
+      boundBoxFunc: (_oldBox, newBox) => {
+        newBox.width = Math.max(30, newBox.width);
+        return newBox;
+      }
+    });
+    if (line?.attrs?.id && line.attrs.id === "note") {
+      transformer.resizeEnabled(false);
+    }
+    group.draggable(rawAnnotationStore.draggable);
+    if (this.getStylusModeEnabled?.()) {
+      group.preventDefault(false);
+      transformer.preventDefault(false);
+      let savedPos = null;
+      group.on("dragstart.stylusGuard", (e) => {
+        if (this.isStylusRejected(e.evt)) {
+          savedPos = group.absolutePosition();
+          setTimeout(() => {
+            group.stopDrag();
+            if (savedPos) group.absolutePosition(savedPos);
+            konvaStage.batchDraw();
+          }, 0);
+        }
+      });
+    }
+    transformer.off("transformend");
+    transformer.off("transformstart");
+    transformer.on("transformend", () => {
+      this.onChanged(
+        group.id(),
+        group.toJSON(),
+        { ...rawAnnotationStore },
+        Konva.Node.create(group.toJSON()).getClientRect(),
+        transformer.getClientRect()
+      );
+    });
+    transformer.on("transformstart", () => {
+      this.onCancel();
+    });
+    transformer.on("dragstart", () => {
+      this.onCancel();
+    });
+    transformer.on("dragend", () => {
+      this.onChanged(
+        group.id(),
+        group.toJSON(),
+        { ...rawAnnotationStore },
+        Konva.Node.create(group.toJSON()).getClientRect(),
+        transformer.getClientRect()
+      );
+    });
+    transformer.on("dragmove", () => {
+      const boxes = transformer.nodes().map((node) => node.getClientRect());
+      const box = this.getTotalBox(boxes);
+      transformer.nodes().forEach((shape) => {
+        const absPos = shape.getAbsolutePosition();
+        const offsetX = box.x - absPos.x;
+        const offsetY = box.y - absPos.y;
+        const halfWidth = box.width / 2;
+        const halfHeight = box.height / 2;
+        const newAbsPos = { ...absPos };
+        if (box.x + halfWidth < 0) {
+          newAbsPos.x = -offsetX - halfWidth;
+        }
+        if (box.y + halfHeight < 0) {
+          newAbsPos.y = -offsetY - halfHeight;
+        }
+        if (box.x + halfWidth > konvaStage.width()) {
+          newAbsPos.x = konvaStage.width() - halfWidth - offsetX;
+        }
+        if (box.y + halfHeight > konvaStage.height()) {
+          newAbsPos.y = konvaStage.height() - halfHeight - offsetY;
+        }
+        shape.setAbsolutePosition(newAbsPos);
+      });
+    });
+    transformer.nodes([group]);
+    this.getBackgroundLayer(konvaStage).add(transformer);
+    this.transformerStore.set(groupId, transformer);
+    if (flash) {
+      this.flashNodeWithTransformer(group, transformer, () => {
+        this.onSelected(group.id(), false, transformer.getClientRect());
+      });
+    }
+  }
+  flashNodeWithTransformer(group, transformer, onFinish) {
+    let flashCount = 0;
+    const maxFlashes = 1;
+    const fadeDuration = 0.1;
+    const originalStroke = transformer.borderStroke();
+    const highlightStroke = "red";
+    const fadeOut = () => {
+      const groupTween = new Konva.Tween({
+        node: group,
+        duration: fadeDuration,
+        opacity: 0,
+        onFinish: () => {
+          try {
+            transformer.borderStroke(highlightStroke);
+            transformer.getLayer()?.batchDraw();
+            fadeIn();
+          } catch {
+          }
+        }
+      });
+      groupTween.play();
+    };
+    const fadeIn = () => {
+      const groupTween = new Konva.Tween({
+        node: group,
+        duration: fadeDuration,
+        opacity: 1,
+        onFinish: () => {
+          try {
+            transformer.borderStroke(originalStroke);
+            transformer.getLayer()?.batchDraw();
+            flashCount++;
+            if (flashCount < maxFlashes) {
+              setTimeout(fadeOut, 100);
+            } else if (onFinish) {
+              onFinish();
+            }
+          } catch {
+          }
+        }
+      });
+      groupTween.play();
+    };
+    fadeOut();
+  }
+  getTotalBox(boxes) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    boxes.forEach((box) => {
+      minX = Math.min(minX, box.x);
+      minY = Math.min(minY, box.y);
+      maxX = Math.max(maxX, box.x + box.width);
+      maxY = Math.max(maxY, box.y + box.height);
+    });
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+  }
+  toggleCursorStyle(add) {
+    document.body.classList.toggle(SELECTOR_HOVER_STYLE, add);
+  }
+  handleShapeMouseover() {
+    this.toggleCursorStyle(true);
+  }
+  handleShapeMouseout() {
+    this.toggleCursorStyle(false);
+  }
+  clearTransformers() {
+    this.toggleCursorStyle(false);
+    this.transformerStore.forEach((transformer) => {
+      if (transformer) {
+        transformer.nodes().forEach((group) => {
+          if (group instanceof Konva.Group) {
+            group.draggable(false);
+          }
+        });
+        transformer.nodes([]);
+        transformer.destroy();
+      }
+    });
+    this.transformerStore.clear();
+    this.currentTransformerId = null;
+    this.onCancel();
+  }
+  deactivateTransformer(transformerId) {
+    if (transformerId) {
+      const transformer = this.transformerStore.get(transformerId);
+      if (transformer) {
+        transformer.nodes().forEach((group) => {
+          if (group instanceof Konva.Group) {
+            group.draggable(false);
+          }
+        });
+      }
+    }
+  }
+  selectedShape(id, konvaStage) {
+    const group = this.getGroupById(konvaStage, id);
+    if (!group) return;
+    const shape = this.getFirstShapeInGroup(group);
+    if (!shape) return;
+    this.handleShapeClick(shape, konvaStage, false);
+  }
+  clear() {
+    this.clearTransformers();
+    this.konvaCanvasStore.forEach((konvaCanvas) => {
+      const { konvaStage } = konvaCanvas;
+      const pageGroups = this.getPageShapeGroups(konvaStage);
+      this.disableStageEvents(konvaStage);
+      this.disableShapeGroups(pageGroups);
+    });
+  }
+  activate(pageNumber) {
+    const konvaCanvas = this.konvaCanvasStore.get(pageNumber);
+    if (!konvaCanvas) return;
+    const { konvaStage } = konvaCanvas;
+    const pageGroups = this.getPageShapeGroups(konvaStage);
+    this.disableStageEvents(konvaStage);
+    this.bindStageEvents(konvaStage);
+    this.enableShapeGroups(pageGroups, konvaStage);
+    if (this.selectedId) {
+      this.selectedShape(this.selectedId, konvaStage);
+    }
+  }
+  select(id) {
+    this.selectedId = id;
+  }
+  refreshCurrentSelection() {
+    const id = this._currentTransformerId;
+    if (!id) return null;
+    const transformer = this.transformerStore.get(id);
+    if (!transformer) return null;
+    transformer.forceUpdate();
+    transformer.getLayer()?.batchDraw();
+    return transformer.getClientRect();
+  }
+  delete() {
+    this.selectedIds = [];
+    this.clearTransformers();
+  }
+  activateMarquee(pageNumber) {
+    const konvaCanvas = this.konvaCanvasStore.get(pageNumber);
+    if (!konvaCanvas) return;
+    const { konvaStage } = konvaCanvas;
+    const pageGroups = this.getPageShapeGroups(konvaStage);
+    this.disableStageEvents(konvaStage);
+    this.enableShapeGroups(pageGroups, konvaStage);
+    this.bindMarqueeEvents(konvaStage);
+  }
+  bindMarqueeEvents(konvaStage) {
+    konvaStage.on("mousedown touchstart", (e) => {
+      if (e.target !== konvaStage) return;
+      if (this.isStylusRejected(e.evt)) return;
+      if (this.getStylusModeEnabled?.() && e.evt) e.evt.preventDefault();
+      this.clearTransformers();
+      this.selectedIds = [];
+      const pos = konvaStage.getRelativePointerPosition();
+      if (!pos) return;
+      this.marqueeStartPos = pos;
+      this.marqueeStage = konvaStage;
+      this.marqueeRect = new Konva.Rect({
+        x: pos.x,
+        y: pos.y,
+        width: 0,
+        height: 0,
+        stroke: defaultOptions.chooseSetting.COLOR,
+        strokeWidth: 1,
+        dash: [6, 4],
+        fill: `${defaultOptions.chooseSetting.COLOR}10`,
+        listening: false
+      });
+      this.getBackgroundLayer(konvaStage).add(this.marqueeRect);
+    });
+    konvaStage.on("mousemove touchmove", (e) => {
+      if (!this.marqueeRect || !this.marqueeStartPos || !this.marqueeStage) return;
+      if (this.isStylusRejected(e.evt)) return;
+      if (this.getStylusModeEnabled?.() && e.evt) e.evt.preventDefault();
+      const pos = this.marqueeStage.getRelativePointerPosition();
+      if (!pos) return;
+      const x = Math.min(pos.x, this.marqueeStartPos.x);
+      const y = Math.min(pos.y, this.marqueeStartPos.y);
+      const width = Math.abs(pos.x - this.marqueeStartPos.x);
+      const height = Math.abs(pos.y - this.marqueeStartPos.y);
+      this.marqueeRect.setAttrs({ x, y, width, height });
+      this.marqueeStage.batchDraw();
+    });
+    konvaStage.on("mouseup touchend", (e) => {
+      if (!this.marqueeRect || !this.marqueeStage) return;
+      if (this.isStylusRejected(e.evt)) return;
+      const selectionBox = this.marqueeRect.getClientRect();
+      this.marqueeRect.destroy();
+      this.marqueeRect = null;
+      this.marqueeStartPos = null;
+      if (selectionBox.width < 5 && selectionBox.height < 5) {
+        this.marqueeStage = null;
+        return;
+      }
+      const groups = this.getPageShapeGroups(this.marqueeStage);
+      const matchedIds = [];
+      groups.forEach((group) => {
+        const groupRect = group.getClientRect();
+        if (this.rectsIntersect(selectionBox, groupRect)) {
+          matchedIds.push(group.id());
+        }
+      });
+      if (matchedIds.length > 0) {
+        this.selectedIds = matchedIds;
+        const nodes = matchedIds.map((id) => this.getGroupById(this.marqueeStage, id)).filter((g) => g !== null);
+        if (nodes.length > 0) {
+          const transformer = new Konva.Transformer({
+            resizeEnabled: false,
+            rotateEnabled: false,
+            borderStrokeWidth: defaultOptions.chooseSetting.STROKEWIDTH,
+            borderStroke: defaultOptions.chooseSetting.COLOR,
+            anchorFill: defaultOptions.chooseSetting.COLOR,
+            anchorStroke: defaultOptions.chooseSetting.COLOR,
+            opacity: defaultOptions.chooseSetting.OPACITY,
+            anchorSize: 0,
+            padding: 2
+          });
+          nodes.forEach((node) => node.draggable(true));
+          transformer.nodes(nodes);
+          this.getBackgroundLayer(this.marqueeStage).add(transformer);
+          this.transformerStore.set("__multi__", transformer);
+          nodes.forEach((node) => {
+            node.on("dragstart.marquee", () => {
+              this.onCancel();
+            });
+            node.on("dragmove.marquee", () => {
+              this.onMultiSelected(matchedIds, transformer.getClientRect());
+            });
+            node.on("dragend.marquee", () => {
+              this.onMultiSelected(matchedIds, transformer.getClientRect());
+            });
+          });
+          const combinedRect = transformer.getClientRect();
+          this.onMultiSelected(matchedIds, combinedRect);
+        }
+      }
+      this.marqueeStage = null;
+    });
+  }
+  rectsIntersect(a, b) {
+    return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+  }
+  activateEraser(pageNumber) {
+    const konvaCanvas = this.konvaCanvasStore.get(pageNumber);
+    if (!konvaCanvas) return;
+    const { konvaStage } = konvaCanvas;
+    this.disableStageEvents(konvaStage);
+    this.bindEraserEvents(konvaStage);
+  }
+  eraserLine = null;
+  eraserStage = null;
+  bindEraserEvents(konvaStage) {
+    konvaStage.on("mousedown touchstart", (e) => {
+      if (e.target !== konvaStage && !(e.target instanceof Konva.Shape)) {
+      }
+      if (this.isStylusRejected(e.evt)) return;
+      if (this.getStylusModeEnabled?.() && e.evt) e.evt.preventDefault();
+      const pos = konvaStage.getRelativePointerPosition();
+      if (!pos) return;
+      this.eraserStage = konvaStage;
+      this.eraserLine = new Konva.Line({
+        stroke: "#888888",
+        strokeWidth: 12,
+        opacity: 0.4,
+        lineCap: "round",
+        lineJoin: "round",
+        strokeScaleEnabled: false,
+        listening: false,
+        points: [pos.x, pos.y]
+      });
+      this.getBackgroundLayer(konvaStage).add(this.eraserLine);
+    });
+    konvaStage.on("mousemove touchmove", (e) => {
+      if (!this.eraserLine || !this.eraserStage) return;
+      if (this.isStylusRejected(e.evt)) return;
+      if (this.getStylusModeEnabled?.() && e.evt) e.evt.preventDefault();
+      const pos = this.eraserStage.getRelativePointerPosition();
+      if (!pos) return;
+      const newPoints = this.eraserLine.points().concat([pos.x, pos.y]);
+      this.eraserLine.points(newPoints);
+      this.eraserStage.batchDraw();
+    });
+    konvaStage.on("mouseup touchend", (e) => {
+      if (!this.eraserLine || !this.eraserStage) return;
+      if (this.isStylusRejected(e.evt)) return;
+      const eraserRect = this.eraserLine.getClientRect();
+      this.eraserLine.destroy();
+      this.eraserLine = null;
+      if (eraserRect.width < 3 && eraserRect.height < 3) {
+        this.eraserStage = null;
+        return;
+      }
+      const groups = this.getPageShapeGroups(this.eraserStage);
+      const toDelete = [];
+      groups.forEach((group) => {
+        if (this.rectsIntersect(eraserRect, group.getClientRect())) {
+          toDelete.push(group.id());
+        }
+      });
+      this.eraserStage = null;
+      toDelete.forEach((id) => this.onDelete(id));
+    });
+  }
+  destroy() {
+    this.clear();
+    window.removeEventListener("keydown", this.handleKeyDown);
+  }
+}

package/dist/runtime/annotation/engine/import-normalize.d.ts

@@ -0,0 +1,5 @@
+import { type IAnnotationStore } from './types.js';
+export declare function normalizeImportedAnnotations(input: unknown, fallbackTitle?: string): {
+    annotations: IAnnotationStore[];
+    skipped: number;
+};

package/dist/runtime/annotation/engine/import-normalize.js

@@ -0,0 +1,99 @@
+import { annotationDefinitions } from "./config.js";
+import {
+  AnnotationType
+} from "./types.js";
+import { formatTimestamp, generateUUID } from "./utils.js";
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function isBoolean(value) {
+  return typeof value === "boolean";
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function normalizeComment(comment, fallbackTitle) {
+  if (!isRecord(comment)) return null;
+  const content = comment.content;
+  if (!isString(content)) return null;
+  return {
+    id: isString(comment.id) && comment.id.length > 0 ? comment.id : generateUUID(),
+    title: isString(comment.title) && comment.title.length > 0 ? comment.title : fallbackTitle,
+    date: isString(comment.date) && comment.date.length > 0 ? comment.date : formatTimestamp(Date.now()),
+    content,
+    status: isString(comment.status) ? comment.status : void 0
+  };
+}
+function normalizeContentsObj(value) {
+  if (!isRecord(value)) return null;
+  const text = value.text;
+  if (!isString(text)) return null;
+  const image = isString(value.image) ? value.image : void 0;
+  return { text, image };
+}
+const validAnnotationTypes = new Set(
+  Object.values(AnnotationType).filter((value) => typeof value === "number")
+);
+function normalizeAnnotation(raw, fallbackTitle) {
+  if (!isRecord(raw)) return null;
+  const id = raw.id;
+  const pageNumber = raw.pageNumber;
+  const konvaString = raw.konvaString;
+  const konvaClientRect = raw.konvaClientRect;
+  const type = raw.type;
+  if (!isString(id) || id.length === 0) return null;
+  if (!isNumber(pageNumber) || pageNumber < 1) return null;
+  if (!isString(konvaString) || konvaString.length === 0) return null;
+  if (!isNumber(type) || !validAnnotationTypes.has(type)) return null;
+  if (!isRecord(konvaClientRect)) return null;
+  const x = konvaClientRect.x;
+  const y = konvaClientRect.y;
+  const width = konvaClientRect.width;
+  const height = konvaClientRect.height;
+  if (!isNumber(x) || !isNumber(y) || !isNumber(width) || !isNumber(height)) return null;
+  const def = annotationDefinitions.find((item) => item.type === type);
+  const subtype = isString(raw.subtype) ? raw.subtype : def?.subtype ?? "Text";
+  const pdfjsType = isNumber(raw.pdfjsType) ? raw.pdfjsType : def?.pdfjsAnnotationType;
+  const pdfjsEditorType = isNumber(raw.pdfjsEditorType) ? raw.pdfjsEditorType : def?.pdfjsEditorType;
+  if (!isNumber(pdfjsType) || !isNumber(pdfjsEditorType)) return null;
+  const commentsInput = Array.isArray(raw.comments) ? raw.comments : [];
+  const comments = commentsInput.map((comment) => normalizeComment(comment, fallbackTitle)).filter((comment) => !!comment);
+  const normalized = {
+    id,
+    pageNumber,
+    konvaString,
+    konvaClientRect: { x, y, width, height },
+    title: isString(raw.title) && raw.title.length > 0 ? raw.title : fallbackTitle,
+    type,
+    subtype,
+    pdfjsType,
+    pdfjsEditorType,
+    color: isString(raw.color) || raw.color === null ? raw.color : def?.style?.color ?? null,
+    fontSize: isNumber(raw.fontSize) ? raw.fontSize : def?.style?.fontSize ?? null,
+    date: isString(raw.date) && raw.date.length > 0 ? raw.date : formatTimestamp(Date.now()),
+    contentsObj: normalizeContentsObj(raw.contentsObj),
+    comments,
+    resizable: isBoolean(raw.resizable) ? raw.resizable : def?.resizable ?? false,
+    draggable: isBoolean(raw.draggable) ? raw.draggable : def?.draggable ?? false
+  };
+  return normalized;
+}
+export function normalizeImportedAnnotations(input, fallbackTitle = "User") {
+  if (!Array.isArray(input)) {
+    return { annotations: [], skipped: 0 };
+  }
+  const annotations = [];
+  let skipped = 0;
+  for (const item of input) {
+    const normalized = normalizeAnnotation(item, fallbackTitle);
+    if (normalized) {
+      annotations.push(normalized);
+    } else {
+      skipped++;
+    }
+  }
+  return { annotations, skipped };
+}