@embedpdf/plugin-annotation 2.13.0 → 2.14.1

package/dist/index.js

@@ -207,6 +207,22 @@ function hasLockedFlag(annotation) {
   var _a;
   return ((_a = annotation.flags) == null ? void 0 : _a.includes("locked")) ?? false;
 }
+function hasNoViewFlag(annotation) {
+  var _a;
+  return ((_a = annotation.flags) == null ? void 0 : _a.includes("noView")) ?? false;
+}
+function hasHiddenFlag(annotation) {
+  var _a;
+  return ((_a = annotation.flags) == null ? void 0 : _a.includes("hidden")) ?? false;
+}
+function hasReadOnlyFlag(annotation) {
+  var _a;
+  return ((_a = annotation.flags) == null ? void 0 : _a.includes("readOnly")) ?? false;
+}
+function hasLockedContentsFlag(annotation) {
+  var _a;
+  return ((_a = annotation.flags) == null ? void 0 : _a.includes("lockedContents")) ?? false;
+}
 const getAnnotationsByPageIndex = (s, page) => (s.pages[page] ?? []).map((uid) => s.byUid[uid]);
 const getAnnotations = (s) => {
   const out = {};
@@ -737,6 +753,109 @@ function compensateRotatedVertexEdit(original, vertices, tightRect) {
   if (Math.abs(qx) < 1e-8 && Math.abs(qy) < 1e-8) return vertices;
   return vertices.map((v) => ({ x: v.x + qx, y: v.y + qy }));
 }
+function computeTextBoxFromRD(rect, rd) {
+  if (!rd) return rect;
+  return {
+    origin: { x: rect.origin.x + rd.left, y: rect.origin.y + rd.top },
+    size: {
+      width: Math.max(0, rect.size.width - rd.left - rd.right),
+      height: Math.max(0, rect.size.height - rd.top - rd.bottom)
+    }
+  };
+}
+function computeRDFromTextBox(overallRect, textBox) {
+  return {
+    left: textBox.origin.x - overallRect.origin.x,
+    top: textBox.origin.y - overallRect.origin.y,
+    right: overallRect.origin.x + overallRect.size.width - (textBox.origin.x + textBox.size.width),
+    bottom: overallRect.origin.y + overallRect.size.height - (textBox.origin.y + textBox.size.height)
+  };
+}
+function computeCalloutConnectionPoint(knee, textBox) {
+  const cx = textBox.origin.x + textBox.size.width / 2;
+  const cy = textBox.origin.y + textBox.size.height / 2;
+  const dx = knee.x - cx;
+  const dy = knee.y - cy;
+  if (Math.abs(dx) >= Math.abs(dy)) {
+    return dx > 0 ? { x: textBox.origin.x + textBox.size.width, y: cy } : { x: textBox.origin.x, y: cy };
+  }
+  return dy > 0 ? { x: cx, y: textBox.origin.y + textBox.size.height } : { x: cx, y: textBox.origin.y };
+}
+function computeCalloutOverallRect(textBox, calloutLine, lineEnding, strokeWidth) {
+  const linePoints = [...calloutLine];
+  if (lineEnding && calloutLine.length >= 2) {
+    const handler = LINE_ENDING_HANDLERS[lineEnding];
+    if (handler) {
+      const angle = Math.atan2(
+        calloutLine[1].y - calloutLine[0].y,
+        calloutLine[1].x - calloutLine[0].x
+      );
+      const localPts = handler.getLocalPoints(strokeWidth);
+      const rotationAngle = handler.getRotation(angle + Math.PI);
+      const transformed = localPts.map(
+        (p) => rotateAndTranslatePoint(p, rotationAngle, calloutLine[0])
+      );
+      linePoints.push(...transformed);
+    }
+  }
+  const lineBbox = expandRect(rectFromPoints(linePoints), strokeWidth);
+  const tbRight = textBox.origin.x + textBox.size.width;
+  const tbBottom = textBox.origin.y + textBox.size.height;
+  const lnRight = lineBbox.origin.x + lineBbox.size.width;
+  const lnBottom = lineBbox.origin.y + lineBbox.size.height;
+  const minX = Math.min(textBox.origin.x, lineBbox.origin.x);
+  const minY = Math.min(textBox.origin.y, lineBbox.origin.y);
+  const maxX = Math.max(tbRight, lnRight);
+  const maxY = Math.max(tbBottom, lnBottom);
+  return {
+    origin: { x: minX, y: minY },
+    size: { width: maxX - minX, height: maxY - minY }
+  };
+}
+const calloutVertexConfig = {
+  extractVertices: (a) => {
+    const textBox = computeTextBoxFromRD(a.rect, a.rectangleDifferences);
+    const cl = a.calloutLine;
+    if (!cl || cl.length < 3) {
+      return [
+        { x: a.rect.origin.x, y: a.rect.origin.y },
+        { x: a.rect.origin.x, y: a.rect.origin.y },
+        { x: textBox.origin.x, y: textBox.origin.y },
+        { x: textBox.origin.x + textBox.size.width, y: textBox.origin.y + textBox.size.height }
+      ];
+    }
+    return [
+      cl[0],
+      cl[1],
+      { x: textBox.origin.x, y: textBox.origin.y },
+      { x: textBox.origin.x + textBox.size.width, y: textBox.origin.y + textBox.size.height }
+    ];
+  },
+  transformAnnotation: (a, vertices) => {
+    if (vertices.length < 4) return {};
+    const [arrowTip, knee, tbTL, tbBR] = vertices;
+    const textBox = {
+      origin: { x: Math.min(tbTL.x, tbBR.x), y: Math.min(tbTL.y, tbBR.y) },
+      size: {
+        width: Math.abs(tbBR.x - tbTL.x),
+        height: Math.abs(tbBR.y - tbTL.y)
+      }
+    };
+    const connectionPoint = computeCalloutConnectionPoint(knee, textBox);
+    const calloutLine = [arrowTip, knee, connectionPoint];
+    const overallRect = computeCalloutOverallRect(
+      textBox,
+      calloutLine,
+      a.lineEnding,
+      a.strokeWidth ?? 1
+    );
+    return {
+      calloutLine,
+      rect: overallRect,
+      rectangleDifferences: computeRDFromTextBox(overallRect, textBox)
+    };
+  }
+};
 function createEnding(ending, strokeWidth, rad, px, py) {
   if (!ending) return null;
   const handler = LINE_ENDING_HANDLERS[ending];
@@ -1874,6 +1993,80 @@ const patchFreeText = (orig, ctx) => {
       return ctx.changes;
   }
 };
+function rebuildFromVertices(orig, arrowTip, knee, tbTL, tbBR) {
+  const textBox = {
+    origin: { x: Math.min(tbTL.x, tbBR.x), y: Math.min(tbTL.y, tbBR.y) },
+    size: {
+      width: Math.abs(tbBR.x - tbTL.x),
+      height: Math.abs(tbBR.y - tbTL.y)
+    }
+  };
+  const connectionPoint = computeCalloutConnectionPoint(knee, textBox);
+  const calloutLine = [arrowTip, knee, connectionPoint];
+  const overallRect = computeCalloutOverallRect(
+    textBox,
+    calloutLine,
+    orig.lineEnding,
+    orig.strokeWidth ?? 1
+  );
+  return {
+    calloutLine,
+    rect: overallRect,
+    rectangleDifferences: computeRDFromTextBox(overallRect, textBox)
+  };
+}
+const patchCalloutFreeText = (orig, ctx) => {
+  var _a, _b;
+  switch (ctx.type) {
+    case "vertex-edit": {
+      if (!ctx.changes.calloutLine) return ctx.changes;
+      const verts = ctx.changes.calloutLine;
+      if (verts.length < 4) return ctx.changes;
+      return rebuildFromVertices(orig, verts[0], verts[1], verts[2], verts[3]);
+    }
+    case "move": {
+      if (!ctx.changes.rect) return ctx.changes;
+      const { dx, dy, rects } = baseMoveChanges(orig, ctx.changes.rect);
+      const movedLine = (_a = orig.calloutLine) == null ? void 0 : _a.map((p) => ({ x: p.x + dx, y: p.y + dy }));
+      return {
+        ...rects,
+        ...movedLine && { calloutLine: movedLine }
+      };
+    }
+    case "rotate": {
+      const result = baseRotateChanges(orig, ctx);
+      if (!result) return ctx.changes;
+      const { dx, dy } = rotateOrbitDelta(orig, result);
+      const movedLine = (_b = orig.calloutLine) == null ? void 0 : _b.map((p) => ({ x: p.x + dx, y: p.y + dy }));
+      return {
+        ...result,
+        ...movedLine && { calloutLine: movedLine }
+      };
+    }
+    case "property-update": {
+      if (ctx.changes.lineEnding !== void 0 || ctx.changes.strokeWidth !== void 0) {
+        const merged = { ...orig, ...ctx.changes };
+        if (merged.calloutLine && merged.calloutLine.length >= 3) {
+          const textBox = computeTextBoxFromRD(orig.rect, orig.rectangleDifferences);
+          const overallRect = computeCalloutOverallRect(
+            textBox,
+            merged.calloutLine,
+            merged.lineEnding,
+            merged.strokeWidth ?? 1
+          );
+          return {
+            ...ctx.changes,
+            rect: overallRect,
+            rectangleDifferences: computeRDFromTextBox(overallRect, textBox)
+          };
+        }
+      }
+      return ctx.changes;
+    }
+    default:
+      return ctx.changes;
+  }
+};
 const patchStamp = (orig, ctx) => {
   switch (ctx.type) {
     case "move":
@@ -1901,11 +2094,17 @@ const index = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.definePropert
   calculateAABBFromVertices,
   calculateRotatedRectAABB,
   calculateRotatedRectAABBAroundPoint,
+  calloutVertexConfig,
   clampAnnotationToPage,
   compensateRotatedVertexEdit,
+  computeCalloutConnectionPoint,
+  computeCalloutOverallRect,
+  computeRDFromTextBox,
+  computeTextBoxFromRD,
   createEnding,
   getRectCenter,
   lineRectWithEndings,
+  patchCalloutFreeText,
   patchCircle,
   patchFreeText,
   patchInk,
@@ -2138,6 +2337,232 @@ const freeTextHandlerFactory = {
     };
   }
 };
+const CLICK_THRESHOLD = 5;
+const DEFAULT_TB_WIDTH = 150;
+const DEFAULT_TB_HEIGHT = 40;
+const calloutFreeTextHandlerFactory = {
+  annotationType: PdfAnnotationSubtype.FREETEXT,
+  create(context) {
+    const { onCommit, onPreview, getTool, pageSize, pageIndex } = context;
+    const [getPhase, setPhase] = useState("arrow");
+    const [getArrowTip, setArrowTip] = useState(null);
+    const [getKnee, setKnee] = useState(null);
+    const [getDownPos, setDownPos] = useState(null);
+    const [getTextBoxStart, setTextBoxStart] = useState(null);
+    const [getDragging, setDragging] = useState(false);
+    const clampToPage = (pos) => ({
+      x: clamp(pos.x, 0, pageSize.width),
+      y: clamp(pos.y, 0, pageSize.height)
+    });
+    const clampTextBox = (tb) => ({
+      origin: {
+        x: clamp(tb.origin.x, 0, pageSize.width - tb.size.width),
+        y: clamp(tb.origin.y, 0, pageSize.height - tb.size.height)
+      },
+      size: tb.size
+    });
+    const getDefaults = () => {
+      const tool = getTool();
+      if (!tool) return null;
+      return {
+        ...tool.defaults,
+        fontColor: tool.defaults.fontColor ?? "#000000",
+        opacity: tool.defaults.opacity ?? 1,
+        fontSize: tool.defaults.fontSize ?? 12,
+        fontFamily: tool.defaults.fontFamily ?? PdfStandardFont.Helvetica,
+        color: tool.defaults.color ?? tool.defaults.backgroundColor ?? "transparent",
+        textAlign: tool.defaults.textAlign ?? PdfTextAlignment.Left,
+        verticalAlign: tool.defaults.verticalAlign ?? PdfVerticalAlignment.Top,
+        contents: tool.defaults.contents ?? "Insert text",
+        flags: tool.defaults.flags ?? ["print"],
+        lineEnding: tool.defaults.lineEnding ?? PdfAnnotationLineEnding.OpenArrow,
+        strokeColor: tool.defaults.strokeColor ?? "#000000",
+        strokeWidth: tool.defaults.strokeWidth ?? 1
+      };
+    };
+    const isClick = (a, b) => Math.abs(a.x - b.x) < CLICK_THRESHOLD && Math.abs(a.y - b.y) < CLICK_THRESHOLD;
+    const buildPreview = (cursor) => {
+      const defaults = getDefaults();
+      if (!defaults) return null;
+      const arrowTip = getArrowTip();
+      const knee = getKnee();
+      const phase = getPhase();
+      if (phase === "knee" && arrowTip) {
+        const calloutLine = [arrowTip, cursor];
+        const minX = Math.min(arrowTip.x, cursor.x);
+        const minY = Math.min(arrowTip.y, cursor.y);
+        const w = Math.abs(arrowTip.x - cursor.x);
+        const h = Math.abs(arrowTip.y - cursor.y);
+        const bounds = {
+          origin: { x: minX, y: minY },
+          size: { width: Math.max(w, 1), height: Math.max(h, 1) }
+        };
+        return {
+          type: PdfAnnotationSubtype.FREETEXT,
+          bounds,
+          data: {
+            ...defaults,
+            rect: bounds,
+            calloutLine
+          }
+        };
+      }
+      if (phase === "textbox" && arrowTip && knee) {
+        const tbStart = getTextBoxStart();
+        let textBox;
+        if (getDragging() && tbStart) {
+          textBox = {
+            origin: { x: Math.min(tbStart.x, cursor.x), y: Math.min(tbStart.y, cursor.y) },
+            size: {
+              width: Math.max(Math.abs(cursor.x - tbStart.x), 20),
+              height: Math.max(Math.abs(cursor.y - tbStart.y), 14)
+            }
+          };
+        } else {
+          textBox = {
+            origin: { x: cursor.x - DEFAULT_TB_WIDTH / 2, y: cursor.y - DEFAULT_TB_HEIGHT / 2 },
+            size: { width: DEFAULT_TB_WIDTH, height: DEFAULT_TB_HEIGHT }
+          };
+        }
+        textBox = clampTextBox(textBox);
+        const connectionPoint = computeCalloutConnectionPoint(knee, textBox);
+        const calloutLine = [arrowTip, knee, connectionPoint];
+        const overallRect = computeCalloutOverallRect(
+          textBox,
+          calloutLine,
+          defaults.lineEnding,
+          defaults.strokeWidth
+        );
+        return {
+          type: PdfAnnotationSubtype.FREETEXT,
+          bounds: overallRect,
+          data: {
+            ...defaults,
+            rect: overallRect,
+            calloutLine,
+            textBox
+          }
+        };
+      }
+      return null;
+    };
+    const commitCallout = (tb) => {
+      const defaults = getDefaults();
+      const arrowTip = getArrowTip();
+      const knee = getKnee();
+      if (!defaults || !arrowTip || !knee) return;
+      const textBox = clampTextBox(tb);
+      const connectionPoint = computeCalloutConnectionPoint(knee, textBox);
+      const calloutLine = [arrowTip, knee, connectionPoint];
+      const overallRect = computeCalloutOverallRect(
+        textBox,
+        calloutLine,
+        defaults.lineEnding,
+        defaults.strokeWidth
+      );
+      const rd = computeRDFromTextBox(overallRect, textBox);
+      const anno = {
+        ...defaults,
+        type: PdfAnnotationSubtype.FREETEXT,
+        intent: "FreeTextCallout",
+        rect: overallRect,
+        rectangleDifferences: rd,
+        calloutLine,
+        pageIndex,
+        id: uuidV4(),
+        created: /* @__PURE__ */ new Date()
+      };
+      onCommit(anno);
+      resetState();
+    };
+    const resetState = () => {
+      setPhase("arrow");
+      setArrowTip(null);
+      setKnee(null);
+      setDownPos(null);
+      setTextBoxStart(null);
+      setDragging(false);
+      onPreview(null);
+    };
+    return {
+      onPointerDown: (pos, evt) => {
+        var _a, _b;
+        const clampedPos = clampToPage(pos);
+        const phase = getPhase();
+        if (phase === "arrow" || phase === "knee") {
+          setDownPos(clampedPos);
+          (_a = evt.setPointerCapture) == null ? void 0 : _a.call(evt);
+        } else if (phase === "textbox") {
+          setTextBoxStart(clampedPos);
+          setDragging(true);
+          (_b = evt.setPointerCapture) == null ? void 0 : _b.call(evt);
+        }
+      },
+      onPointerMove: (pos) => {
+        const clampedPos = clampToPage(pos);
+        const phase = getPhase();
+        if (phase === "textbox" && getDragging()) {
+          onPreview(buildPreview(clampedPos));
+        } else if (phase === "knee" || phase === "textbox") {
+          onPreview(buildPreview(clampedPos));
+        }
+      },
+      onPointerUp: (pos, evt) => {
+        var _a, _b, _c, _d;
+        const clampedPos = clampToPage(pos);
+        const phase = getPhase();
+        const downPos = getDownPos();
+        if (phase === "arrow" && downPos && isClick(downPos, clampedPos)) {
+          setArrowTip(clampedPos);
+          setPhase("knee");
+          setDownPos(null);
+          (_a = evt.releasePointerCapture) == null ? void 0 : _a.call(evt);
+          return;
+        }
+        if (phase === "knee" && downPos && isClick(downPos, clampedPos)) {
+          setKnee(clampedPos);
+          setPhase("textbox");
+          setDownPos(null);
+          (_b = evt.releasePointerCapture) == null ? void 0 : _b.call(evt);
+          return;
+        }
+        if (phase === "textbox" && getDragging()) {
+          const tbStart = getTextBoxStart();
+          if (tbStart) {
+            const minX = Math.min(tbStart.x, clampedPos.x);
+            const minY = Math.min(tbStart.y, clampedPos.y);
+            const w = Math.abs(clampedPos.x - tbStart.x);
+            const h = Math.abs(clampedPos.y - tbStart.y);
+            if (w > 5 || h > 5) {
+              const textBox = {
+                origin: { x: minX, y: minY },
+                size: { width: Math.max(w, 20), height: Math.max(h, 14) }
+              };
+              commitCallout(textBox);
+            } else {
+              commitCallout({
+                origin: {
+                  x: tbStart.x - DEFAULT_TB_WIDTH / 2,
+                  y: tbStart.y - DEFAULT_TB_HEIGHT / 2
+                },
+                size: { width: DEFAULT_TB_WIDTH, height: DEFAULT_TB_HEIGHT }
+              });
+            }
+          }
+          (_c = evt.releasePointerCapture) == null ? void 0 : _c.call(evt);
+          return;
+        }
+        setDownPos(null);
+        (_d = evt.releasePointerCapture) == null ? void 0 : _d.call(evt);
+      },
+      onPointerCancel: (_, evt) => {
+        var _a;
+        resetState();
+        (_a = evt.releasePointerCapture) == null ? void 0 : _a.call(evt);
+      }
+    };
+  }
+};
 const lineHandlerFactory = {
   annotationType: PdfAnnotationSubtype.LINE,
   create(context) {
@@ -3665,7 +4090,7 @@ const freeTextTools = [
     name: "Free Text",
     labelKey: "annotation.freeText",
     categories: ["annotation", "markup"],
-    matchScore: (a) => a.type === PdfAnnotationSubtype.FREETEXT ? 1 : 0,
+    matchScore: (a) => a.type === PdfAnnotationSubtype.FREETEXT && a.intent !== "FreeTextCallout" ? 1 : 0,
     interaction: {
       exclusive: false,
       cursor: "crosshair",
@@ -3705,6 +4130,44 @@ const freeTextTools = [
     pointerHandler: freeTextHandlerFactory
   }
 ];
+const calloutFreeTextTools = [
+  {
+    id: "freeTextCallout",
+    name: "Callout",
+    labelKey: "annotation.callout",
+    categories: ["annotation", "markup"],
+    matchScore: (a) => a.type === PdfAnnotationSubtype.FREETEXT && a.intent === "FreeTextCallout" ? 10 : 0,
+    interaction: {
+      exclusive: false,
+      cursor: "crosshair",
+      isDraggable: true,
+      isResizable: false,
+      isRotatable: false
+    },
+    defaults: {
+      type: PdfAnnotationSubtype.FREETEXT,
+      intent: "FreeTextCallout",
+      contents: "Insert text",
+      fontSize: 14,
+      fontColor: "#E44234",
+      fontFamily: PdfStandardFont.Helvetica,
+      textAlign: PdfTextAlignment.Left,
+      verticalAlign: PdfVerticalAlignment.Top,
+      color: "transparent",
+      opacity: 1,
+      lineEnding: PdfAnnotationLineEnding.OpenArrow,
+      strokeColor: "#E44234",
+      strokeWidth: 1
+    },
+    behavior: {
+      insertUpright: true,
+      editAfterCreate: true,
+      selectAfterCreate: true
+    },
+    transform: patchCalloutFreeText,
+    pointerHandler: calloutFreeTextHandlerFactory
+  }
+];
 const stampTools = [
   {
     id: "stamp",
@@ -3771,6 +4234,7 @@ const defaultTools = [
   ...polygonTools,
   ...textCommentTools,
   ...freeTextTools,
+  ...calloutFreeTextTools,
   ...stampTools,
   ...linkTools
 ];
@@ -4301,7 +4765,7 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
       const docState = this.state.documents[documentId];
       if (!docState) return;
       const pageAnnotations = (docState.pages[pageIndex] ?? []).map((uid) => docState.byUid[uid]).filter((ta) => ta !== void 0).filter((ta) => isSelectableAnnotation(ta));
-      const selectedIds = pageAnnotations.filter((ta) => rectsIntersect(rect, ta.object.rect)).filter((ta) => !this.isAnnotationLocked(ta.object, documentId)).map((ta) => ta.object.id);
+      const selectedIds = pageAnnotations.filter((ta) => rectsIntersect(rect, ta.object.rect)).filter((ta) => this.isAnnotationSelectable(ta.object, documentId)).map((ta) => ta.object.id);
       if (selectedIds.length > 0) {
         const expandedIds = /* @__PURE__ */ new Set();
         for (const id of selectedIds) {
@@ -4400,6 +4864,9 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
       setLocked: (mode, documentId) => this.setLocked(mode, documentId),
       getLocked: (documentId) => this.getLocked(documentId),
       isAnnotationLocked: (annotation, documentId) => this.isAnnotationLocked(annotation, documentId),
+      isAnnotationInteractive: (annotation, documentId) => this.isAnnotationInteractive(annotation, documentId),
+      isAnnotationStructurallyLocked: (annotation, documentId) => this.isAnnotationStructurallyLocked(annotation, documentId),
+      isAnnotationContentLocked: (annotation, documentId) => this.isAnnotationContentLocked(annotation, documentId),
       isCategoryLocked: (category, documentId) => this.isCategoryLockedMethod(category, documentId),
       isToolLocked: (toolId, documentId) => this.isToolLockedMethod(toolId, documentId),
       // Sync (lightweight state update without commit)
@@ -4474,6 +4941,9 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
       setLocked: (mode) => this.setLocked(mode, documentId),
       getLocked: () => this.getLocked(documentId),
       isAnnotationLocked: (annotation) => this.isAnnotationLocked(annotation, documentId),
+      isAnnotationInteractive: (annotation) => this.isAnnotationInteractive(annotation, documentId),
+      isAnnotationStructurallyLocked: (annotation) => this.isAnnotationStructurallyLocked(annotation, documentId),
+      isAnnotationContentLocked: (annotation) => this.isAnnotationContentLocked(annotation, documentId),
       isCategoryLocked: (category) => this.isCategoryLockedMethod(category, documentId),
       isToolLocked: (toolId) => this.isToolLockedMethod(toolId, documentId),
       syncAnnotationObject: (id, patch) => this.syncAnnotationObject(id, patch, documentId),
@@ -5016,7 +5486,7 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
   selectAnnotation(pageIndex, id, documentId) {
     const docId = documentId ?? this.getActiveDocumentId();
     const ta = this.getAnnotationById(id, docId);
-    if (ta && this.isAnnotationLocked(ta.object, docId)) return;
+    if (ta && !this.isAnnotationSelectable(ta.object, docId)) return;
     if (this.isInGroupMethod(id, docId)) {
       const members = this.getGroupMembersMethod(id, docId);
       const memberIds = members.map((m) => m.object.id);
@@ -5062,7 +5532,7 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
   toggleSelectionMethod(pageIndex, id, documentId) {
     const docId = documentId ?? this.getActiveDocumentId();
     const ta = this.getAnnotationById(id, docId);
-    if (ta && this.isAnnotationLocked(ta.object, docId)) return;
+    if (ta && !this.isAnnotationSelectable(ta.object, docId)) return;
     const docState = this.getDocumentState(docId);
     if (docState.selectedUids.includes(id)) {
       this.dispatch(removeFromSelection(docId, id));
@@ -5082,7 +5552,7 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
   addToSelectionMethod(pageIndex, id, documentId) {
     const docId = documentId ?? this.getActiveDocumentId();
     const ta = this.getAnnotationById(id, docId);
-    if (ta && this.isAnnotationLocked(ta.object, docId)) return;
+    if (ta && !this.isAnnotationInteractive(ta.object, docId)) return;
     this.dispatch(addToSelection(docId, pageIndex, id));
   }
   removeFromSelectionMethod(id, documentId) {
@@ -5094,7 +5564,7 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
     const docState = this.getDocumentState(docId);
     const filtered = ids.filter((id) => {
       const ta = docState.byUid[id];
-      return !ta || !this.isAnnotationLocked(ta.object, docId);
+      return !ta || this.isAnnotationInteractive(ta.object, docId);
     });
     this.dispatch(setSelection(docId, filtered));
   }
@@ -6082,7 +6552,7 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
     const lockedSelected = updatedDocState.selectedUids.filter((uid) => {
       const ta = updatedDocState.byUid[uid];
       if (!ta) return false;
-      return this.isAnnotationLocked(ta.object, docId);
+      return !this.isAnnotationInteractive(ta.object, docId);
     });
     if (lockedSelected.length > 0) {
       const remaining = updatedDocState.selectedUids.filter((uid) => !lockedSelected.includes(uid));
@@ -6098,6 +6568,47 @@ const _AnnotationPlugin = class _AnnotationPlugin extends BasePlugin {
     const categories = getAnnotationCategories(tool);
     return isCategoryLocked(categories, this.getLocked(documentId));
   }
+  /**
+   * Whether the annotation can be interacted with at all (selected, edited, menu shown).
+   * Returns false for `noView`, `hidden`, `readOnly`, or category-locked annotations.
+   * This is the spec-compliant "can the user do anything with this?" predicate.
+   */
+  isAnnotationInteractive(annotation, documentId) {
+    if (hasNoViewFlag(annotation)) return false;
+    if (hasHiddenFlag(annotation)) return false;
+    if (hasReadOnlyFlag(annotation)) return false;
+    const tool = this.findToolForAnnotation(annotation);
+    const categories = getAnnotationCategories(tool);
+    if (isCategoryLocked(categories, this.getLocked(documentId))) return false;
+    return true;
+  }
+  /**
+   * Whether the annotation's structure (position, size, rotation, vertices) is locked.
+   * Non-interactive annotations are treated as structurally locked. PDF `locked` flag
+   * makes an otherwise-interactive annotation structurally locked while still selectable.
+   */
+  isAnnotationStructurallyLocked(annotation, documentId) {
+    if (!this.isAnnotationInteractive(annotation, documentId)) return true;
+    return hasLockedFlag(annotation);
+  }
+  /**
+   * Whether the annotation's content (e.g. FreeText text) is locked.
+   * Non-interactive annotations are treated as content-locked. PDF `lockedContents`
+   * flag blocks content edits while still allowing move/resize.
+   */
+  isAnnotationContentLocked(annotation, documentId) {
+    if (!this.isAnnotationInteractive(annotation, documentId)) return true;
+    return hasLockedContentsFlag(annotation);
+  }
+  /**
+   * Whether a specific annotation is eligible to be added to the selection store.
+   * Differs from the subtype-based `isSelectableAnnotation` helper: that answers
+   * "is this subtype ever selectable?", while this answers "is this specific
+   * annotation selectable right now given its flags and document lock state?".
+   */
+  isAnnotationSelectable(annotation, documentId) {
+    return this.isAnnotationInteractive(annotation, documentId);
+  }
   isCategoryLockedMethod(category, documentId) {
     return isCategoryLocked([category], this.getLocked(documentId));
   }
@@ -6430,9 +6941,13 @@ export {
   getSidebarAnnotationsWithRepliesGroupedByPage,
   getToolDefaultsById,
   hasAttachedLinks,
+  hasHiddenFlag,
   hasIRTChildren,
+  hasLockedContentsFlag,
   hasLockedFlag,
   hasMultipleSelected,
+  hasNoViewFlag,
+  hasReadOnlyFlag,
   inferRotationCenterFromRects2 as inferRotationCenterFromRects,
   initialDocumentState,
   initialState,