@mikuexe/annotator-react 0.1.0 → 0.2.2

package/dist/index.cjs

@@ -22,12 +22,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   SourceAnnotator: () => SourceAnnotator,
+  captureAnnotationTarget: () => captureAnnotationTarget,
   captureElementAnnotation: () => captureElementAnnotation,
   copyTextToClipboard: () => copyTextToClipboard,
   createAnnotationCollection: () => createAnnotationCollection,
   formatAnnotationCollection: () => formatAnnotationCollection,
   formatMarkdown: () => formatMarkdown,
   getElementSelector: () => getElementSelector,
+  getPageContext: () => getPageContext,
   trimText: () => trimText
 });
 module.exports = __toCommonJS(index_exports);
@@ -42,13 +44,18 @@ var MAX_TEXT_LENGTH = 240;
 var MAX_HTML_LENGTH = 640;
 var MAX_SELECTOR_DEPTH = 6;
 async function captureElementAnnotation(element, note, id = createAnnotationId()) {
+  return {
+    id,
+    note,
+    targets: [await captureAnnotationTarget(element)]
+  };
+}
+async function captureAnnotationTarget(element) {
   const elementInfo = await safeResolveElementInfo(element);
   const source = normalizeSource(elementInfo?.source, elementInfo?.componentName);
   const sourceStack = normalizeSourceStack(elementInfo?.stack, source);
   const componentPath = getComponentPath(sourceStack, source);
   return {
-    id,
-    note,
     source,
     sourceStack,
     componentPath,
@@ -202,10 +209,19 @@ async function copyTextToClipboard(text) {
 
 // src/format.ts
 var TASK_FRAMING = "Please update the UI based on these source-linked annotations.";
-function createAnnotationCollection(annotations) {
+function createAnnotationCollection(annotations, page = getPageContext()) {
   return {
     annotations,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    page
+  };
+}
+function getPageContext(targetDocument) {
+  const activeDocument = targetDocument ?? (typeof document === "undefined" ? null : document);
+  const location = activeDocument?.location;
+  return {
+    domain: location?.hostname ?? "",
+    path: location?.pathname ?? ""
   };
 }
 function formatAnnotationCollection(collection, output = "markdown") {
@@ -225,43 +241,28 @@ ${formatJson(collection)}
 \`\`\``;
 }
 function formatMarkdown(collection) {
-  const lines = [TASK_FRAMING, "", `Collected at: ${collection.createdAt}`, ""];
+  const lines = [
+    TASK_FRAMING,
+    "",
+    `Collected at: ${collection.createdAt}`,
+    `Domain: ${collection.page.domain}`,
+    `Path: ${collection.page.path}`,
+    ""
+  ];
   if (collection.annotations.length === 0) {
     lines.push("No annotations were collected.");
     return lines.join("\n");
   }
   collection.annotations.forEach((annotation, index) => {
-    const source = formatSource(annotation);
-    const sourceStack = formatSourceStack(annotation);
-    const nearestComponent = annotation.source?.componentName;
-    const ownerPath = annotation.componentPath.join(" \u203A ");
     lines.push(`## Annotation ${index + 1}`);
     lines.push("");
     lines.push(`ID: ${annotation.id}`);
     lines.push(`Note: ${annotation.note || "(no note provided)"}`);
-    if (source) {
-      lines.push(`Source: ${source}`);
-    }
-    if (nearestComponent) {
-      lines.push(`Nearest React component: ${nearestComponent}`);
-    }
-    if (ownerPath && ownerPath !== nearestComponent) {
-      lines.push(`React owner path: ${ownerPath}`);
-    }
-    if (sourceStack.length) {
-      lines.push("React source stack:");
-      sourceStack.forEach((frame) => lines.push(`- ${frame}`));
-    }
-    lines.push(`Element tag: ${annotation.element.tagName}`);
-    if (annotation.element.html) {
-      lines.push(`Element HTML: ${annotation.element.html}`);
-    }
-    if (annotation.element.text) {
-      lines.push(`Element text: ${annotation.element.text}`);
-    }
-    if (annotation.element.selector) {
-      lines.push(`Selector: ${annotation.element.selector}`);
-    }
+    annotation.targets.forEach((target, targetIndex) => {
+      const isSingleTarget = annotation.targets.length === 1;
+      const label = isSingleTarget ? "" : `Target ${targetIndex + 1} `;
+      appendTargetMarkdown(lines, target, label);
+    });
     lines.push("");
   });
   return lines.join("\n").trimEnd();
@@ -269,8 +270,37 @@ function formatMarkdown(collection) {
 function formatJson(collection) {
   return JSON.stringify(collection, null, 2);
 }
-function formatSource(annotation) {
-  const source = annotation.source;
+function appendTargetMarkdown(lines, target, label) {
+  const source = formatSource(target);
+  const sourceStack = formatSourceStack(target);
+  const nearestComponent = target.source?.componentName;
+  const ownerPath = target.componentPath.join(" \u203A ");
+  if (source) {
+    lines.push(`${label}Source: ${source}`);
+  }
+  if (nearestComponent) {
+    lines.push(`${label}Nearest React component: ${nearestComponent}`);
+  }
+  if (ownerPath && ownerPath !== nearestComponent) {
+    lines.push(`${label}React owner path: ${ownerPath}`);
+  }
+  if (sourceStack.length) {
+    lines.push(`${label}React source stack:`);
+    sourceStack.forEach((frame) => lines.push(`- ${frame}`));
+  }
+  lines.push(`${label}Element tag: ${target.element.tagName}`);
+  if (target.element.html) {
+    lines.push(`${label}Element HTML: ${target.element.html}`);
+  }
+  if (target.element.text) {
+    lines.push(`${label}Element text: ${target.element.text}`);
+  }
+  if (target.element.selector) {
+    lines.push(`${label}Selector: ${target.element.selector}`);
+  }
+}
+function formatSource(target) {
+  const source = target.source;
   if (!source?.filePath) {
     return "";
   }
@@ -278,8 +308,8 @@ function formatSource(annotation) {
   const column = source.columnNumber ? `:${source.columnNumber}` : "";
   return `${source.filePath}${line}${column}`;
 }
-function formatSourceStack(annotation) {
-  return annotation.sourceStack.map((frame) => {
+function formatSourceStack(target) {
+  return target.sourceStack.map((frame) => {
     const location = formatSourceFrame(frame);
     const component = frame.componentName ? ` (${frame.componentName})` : "";
     return location ? `${location}${component}` : frame.componentName || "";
@@ -299,10 +329,22 @@ var import_jsx_runtime = require("react/jsx-runtime");
 var ROOT_ATTR = "data-mikuexe-annotator-root";
 var DEFAULT_HOTKEY = "alt+a";
 var DEFAULT_OUTPUT = "markdown";
+var BLOCKED_INTERACTION_EVENTS = [
+  "pointerdown",
+  "pointerup",
+  "mousedown",
+  "mouseup",
+  "dblclick",
+  "auxclick",
+  "contextmenu",
+  "touchstart",
+  "touchend"
+];
 function SourceAnnotator({
   enabled = true,
   hotkey = DEFAULT_HOTKEY,
   output = DEFAULT_OUTPUT,
+  target,
   onCollect,
   renderToaster = true
 }) {
@@ -311,17 +353,41 @@ function SourceAnnotator({
   const [selected, setSelected] = (0, import_react.useState)(null);
   const [note, setNote] = (0, import_react.useState)("");
   const [annotations, setAnnotations] = (0, import_react.useState)([]);
+  const [previewedAnnotation, setPreviewedAnnotation] = (0, import_react.useState)(null);
   const [status, setStatus] = (0, import_react.useState)(null);
+  const [linkingAnnotationId, setLinkingAnnotationId] = (0, import_react.useState)(null);
   const selectedRef = (0, import_react.useRef)(null);
+  const resolvedTarget = useResolvedTarget(target);
   selectedRef.current = selected;
-  const collection = (0, import_react.useMemo)(
-    () => createAnnotationCollection(annotations.map(({ rect: _rect, targetElement: _targetElement, ...annotation }) => annotation)),
-    [annotations]
-  );
+  (0, import_react.useEffect)(() => {
+    setHoverRect(null);
+    setSelected(null);
+    setAnnotations([]);
+    setPreviewedAnnotation(null);
+    setNote("");
+    setStatus(null);
+    setLinkingAnnotationId(null);
+  }, [resolvedTarget.document, resolvedTarget.frameElement]);
   const refreshTrackedRects = (0, import_react.useCallback)(() => {
     setHoverRect(null);
-    setSelected((current) => current ? { ...current, rect: getRect(current.element) } : current);
-    setAnnotations((existing) => existing.map((annotation) => ({ ...annotation, rect: getRect(annotation.targetElement) })));
+    setSelected(
+      (current) => current ? {
+        ...current,
+        targets: current.targets.map((targetEntry) => ({
+          ...targetEntry,
+          rect: getRect(targetEntry.element, targetEntry.frameElement)
+        }))
+      } : current
+    );
+    setAnnotations(
+      (existing) => existing.map((annotation) => ({
+        ...annotation,
+        targets: annotation.targets.map((targetEntry) => ({
+          ...targetEntry,
+          rect: getRect(targetEntry.targetElement, targetEntry.frameElement)
+        }))
+      }))
+    );
   }, []);
   (0, import_react.useEffect)(() => {
     if (!enabled) {
@@ -336,67 +402,229 @@ function SourceAnnotator({
       event.preventDefault();
       setIsAnnotating((current) => enabled && !current);
     };
+    if (typeof document === "undefined") {
+      return;
+    }
     document.addEventListener("keydown", onKeyDown);
-    return () => document.removeEventListener("keydown", onKeyDown);
-  }, [enabled, hotkey]);
+    if (resolvedTarget.document && resolvedTarget.document !== document) {
+      resolvedTarget.document.addEventListener("keydown", onKeyDown);
+    }
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      if (resolvedTarget.document && resolvedTarget.document !== document) {
+        resolvedTarget.document.removeEventListener("keydown", onKeyDown);
+      }
+    };
+  }, [enabled, hotkey, resolvedTarget.document]);
+  const handleElementSelection = (0, import_react.useCallback)(
+    async (eventTarget, frameElement, extendSelection) => {
+      if (linkingAnnotationId) {
+        const rect2 = getRect(eventTarget, frameElement);
+        setStatus("Resolving linked element\u2026");
+        try {
+          const targetData = await captureAnnotationTarget(eventTarget);
+          setAnnotations(
+            (existing) => existing.map((annotation) => {
+              if (annotation.id !== linkingAnnotationId) {
+                return annotation;
+              }
+              if (annotation.targets.some((targetEntry) => targetEntry.targetElement === eventTarget)) {
+                return annotation;
+              }
+              return {
+                ...annotation,
+                targets: [
+                  ...annotation.targets,
+                  {
+                    targetElement: eventTarget,
+                    rect: rect2,
+                    frameElement,
+                    data: targetData
+                  }
+                ]
+              };
+            })
+          );
+          setLinkingAnnotationId(null);
+          setPreviewedAnnotation(null);
+          setStatus("Element linked to annotation.");
+        } catch {
+          setStatus("Element linked without source info.");
+          setAnnotations(
+            (existing) => existing.map((annotation) => {
+              if (annotation.id !== linkingAnnotationId) {
+                return annotation;
+              }
+              if (annotation.targets.some((targetEntry) => targetEntry.targetElement === eventTarget)) {
+                return annotation;
+              }
+              return {
+                ...annotation,
+                targets: [
+                  ...annotation.targets,
+                  {
+                    targetElement: eventTarget,
+                    rect: rect2,
+                    frameElement,
+                    data: {
+                      source: null,
+                      sourceStack: [],
+                      componentPath: [],
+                      element: {
+                        tagName: eventTarget.tagName.toLowerCase(),
+                        text: eventTarget.textContent?.trim() ?? "",
+                        html: "",
+                        selector: ""
+                      }
+                    }
+                  }
+                ]
+              };
+            })
+          );
+          setLinkingAnnotationId(null);
+        }
+        return;
+      }
+      const rect = getRect(eventTarget, frameElement);
+      const shouldAppend = extendSelection && Boolean(selectedRef.current) && !selectedRef.current?.editingId;
+      setSelected((current) => {
+        if (shouldAppend && current) {
+          if (current.targets.some((targetEntry) => targetEntry.element === eventTarget)) {
+            return current;
+          }
+          return {
+            ...current,
+            targets: [...current.targets, { element: eventTarget, rect, frameElement, target: null, loading: true }]
+          };
+        }
+        return {
+          targets: [{ element: eventTarget, rect, frameElement, target: null, loading: true }]
+        };
+      });
+      if (!shouldAppend) {
+        setNote("");
+      }
+      setStatus("Resolving source\u2026");
+      try {
+        const targetData = await captureAnnotationTarget(eventTarget);
+        setSelected((current) => {
+          if (!current) {
+            return current;
+          }
+          return {
+            ...current,
+            targets: current.targets.map(
+              (targetEntry) => targetEntry.element === eventTarget ? { ...targetEntry, target: targetData, loading: false } : targetEntry
+            )
+          };
+        });
+        setStatus(targetData.source ? "Source captured." : "Element captured without source info.");
+      } catch {
+        setSelected((current) => {
+          if (!current) {
+            return current;
+          }
+          return {
+            ...current,
+            targets: current.targets.map(
+              (targetEntry) => targetEntry.element === eventTarget ? { ...targetEntry, loading: false } : targetEntry
+            )
+          };
+        });
+        setStatus("Element captured without source info.");
+      }
+    },
+    [linkingAnnotationId]
+  );
   (0, import_react.useEffect)(() => {
-    if (!enabled || !isAnnotating) {
+    if (!enabled || !isAnnotating || !resolvedTarget.document) {
       setHoverRect(null);
       return;
     }
+    const activeDocument = resolvedTarget.document;
     const onPointerOver = (event) => {
-      const target = getAnnotatableTarget(event.target);
-      if (!target) {
+      const eventTarget = getAnnotatableTarget(event.target, activeDocument);
+      if (!eventTarget) {
         setHoverRect(null);
         return;
       }
-      setHoverRect(getRect(target));
+      setHoverRect(getRect(eventTarget, resolvedTarget.frameElement));
+    };
+    const suppressInteraction = (event) => {
+      const eventTarget = getAnnotatableTarget(event.target, activeDocument);
+      if (!eventTarget) {
+        return;
+      }
+      event.preventDefault();
+      event.stopPropagation();
+      event.stopImmediatePropagation();
     };
     const onClick = (event) => {
-      const target = getAnnotatableTarget(event.target);
-      if (!target) {
+      const eventTarget = getAnnotatableTarget(event.target, activeDocument);
+      if (!eventTarget) {
         return;
       }
       event.preventDefault();
       event.stopPropagation();
-      const rect = getRect(target);
-      setSelected({ element: target, rect, annotation: null, loading: true });
-      setNote("");
-      setStatus("Resolving source\u2026");
-      captureElementAnnotation(target, "").then((annotation) => {
-        setSelected((current) => {
-          if (current?.element !== target) {
-            return current;
-          }
-          return { ...current, annotation, loading: false };
-        });
-        setStatus(annotation.source ? "Source captured." : "Element captured without source info.");
-      }).catch(() => {
-        setSelected((current) => current?.element === target ? { ...current, loading: false } : current);
-        setStatus("Element captured without source info.");
-      });
+      event.stopImmediatePropagation();
+      void handleElementSelection(eventTarget, resolvedTarget.frameElement, shouldExtendSelection(event));
     };
-    document.addEventListener("pointerover", onPointerOver, true);
-    document.addEventListener("click", onClick, true);
+    const onFramePointerLeave = () => {
+      setHoverRect(null);
+    };
+    activeDocument.addEventListener("pointerover", onPointerOver, true);
+    activeDocument.addEventListener("click", onClick, true);
+    BLOCKED_INTERACTION_EVENTS.forEach((eventName) => activeDocument.addEventListener(eventName, suppressInteraction, true));
+    resolvedTarget.frameElement?.addEventListener("pointerleave", onFramePointerLeave);
     return () => {
-      document.removeEventListener("pointerover", onPointerOver, true);
-      document.removeEventListener("click", onClick, true);
+      activeDocument.removeEventListener("pointerover", onPointerOver, true);
+      activeDocument.removeEventListener("click", onClick, true);
+      BLOCKED_INTERACTION_EVENTS.forEach((eventName) => activeDocument.removeEventListener(eventName, suppressInteraction, true));
+      resolvedTarget.frameElement?.removeEventListener("pointerleave", onFramePointerLeave);
     };
-  }, [enabled, isAnnotating]);
+  }, [enabled, handleElementSelection, isAnnotating, resolvedTarget]);
   (0, import_react.useEffect)(() => {
-    if (!enabled || !isAnnotating) {
+    if (!enabled || !isAnnotating || !resolvedTarget.document) {
       return;
     }
-    document.addEventListener("scroll", refreshTrackedRects, true);
+    const activeDocument = resolvedTarget.document;
+    activeDocument.addEventListener("scroll", refreshTrackedRects, true);
+    if (typeof document !== "undefined" && activeDocument !== document) {
+      document.addEventListener("scroll", refreshTrackedRects, true);
+    }
     window.addEventListener("resize", refreshTrackedRects);
     return () => {
-      document.removeEventListener("scroll", refreshTrackedRects, true);
+      activeDocument.removeEventListener("scroll", refreshTrackedRects, true);
+      if (typeof document !== "undefined" && activeDocument !== document) {
+        document.removeEventListener("scroll", refreshTrackedRects, true);
+      }
       window.removeEventListener("resize", refreshTrackedRects);
     };
-  }, [enabled, isAnnotating, refreshTrackedRects]);
+  }, [enabled, isAnnotating, refreshTrackedRects, resolvedTarget.document]);
+  (0, import_react.useEffect)(() => {
+    if (!previewedAnnotation) {
+      return;
+    }
+    const onKeyDown = (event) => {
+      if (event.key === "Escape") {
+        setPreviewedAnnotation(null);
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    if (resolvedTarget.document && resolvedTarget.document !== document) {
+      resolvedTarget.document.addEventListener("keydown", onKeyDown);
+    }
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      if (resolvedTarget.document && resolvedTarget.document !== document) {
+        resolvedTarget.document.removeEventListener("keydown", onKeyDown);
+      }
+    };
+  }, [previewedAnnotation, resolvedTarget.document]);
   const addAnnotation = (0, import_react.useCallback)(async () => {
     const current = selectedRef.current;
-    if (!current || current.loading) {
+    if (!current || current.targets.some((targetEntry) => targetEntry.loading)) {
       return;
     }
     const trimmedNote = note.trim();
@@ -404,14 +632,67 @@ function SourceAnnotator({
       setStatus("Add a note before saving this annotation.");
       return;
     }
-    const annotation = current.annotation ? { ...current.annotation, note: trimmedNote } : await captureElementAnnotation(current.element, trimmedNote);
-    setAnnotations((existing) => [...existing, { ...annotation, targetElement: current.element, rect: getRect(current.element) }]);
+    const currentTargets = await Promise.all(
+      current.targets.map(async (targetEntry) => {
+        if (targetEntry.target) {
+          return targetEntry;
+        }
+        const annotation = await captureElementAnnotation(targetEntry.element, trimmedNote);
+        return { ...targetEntry, target: annotation.targets[0], loading: false };
+      })
+    );
+    const storedAnnotation = {
+      id: current.editingId ?? createAnnotationId(),
+      note: trimmedNote,
+      targets: currentTargets.map((targetEntry) => ({
+        targetElement: targetEntry.element,
+        rect: getRect(targetEntry.element, targetEntry.frameElement),
+        frameElement: targetEntry.frameElement,
+        data: targetEntry.target
+      }))
+    };
+    setAnnotations((existing) => {
+      if (!current.editingId) {
+        return [...existing, storedAnnotation];
+      }
+      return existing.map((item) => item.id === current.editingId ? storedAnnotation : item);
+    });
     setSelected(null);
     setNote("");
-    setStatus("Annotation saved.");
+    setPreviewedAnnotation(null);
+    setStatus(current.editingId ? "Annotation updated." : "Annotation saved.");
   }, [note]);
+  const editAnnotation = (0, import_react.useCallback)((annotation) => {
+    setLinkingAnnotationId(null);
+    setSelected({
+      editingId: annotation.id,
+      targets: annotation.targets.map((targetEntry) => ({
+        element: targetEntry.targetElement,
+        rect: getRect(targetEntry.targetElement, targetEntry.frameElement),
+        frameElement: targetEntry.frameElement,
+        target: targetEntry.data,
+        loading: false
+      }))
+    });
+    setNote(annotation.note);
+    setPreviewedAnnotation(null);
+    setStatus("Editing annotation.");
+  }, []);
+  const startLinkingAnnotation = (0, import_react.useCallback)((annotationId) => {
+    setSelected(null);
+    setPreviewedAnnotation(null);
+    setLinkingAnnotationId(annotationId);
+    setStatus("Click another element to link it to this annotation.");
+  }, []);
+  const deleteAnnotation = (0, import_react.useCallback)((annotationId) => {
+    setAnnotations((existing) => existing.filter((annotation) => annotation.id !== annotationId));
+    setSelected((current) => current?.editingId === annotationId ? null : current);
+    setPreviewedAnnotation((current) => current?.id === annotationId ? null : current);
+    setLinkingAnnotationId((current) => current === annotationId ? null : current);
+    setStatus("Annotation deleted.");
+  }, []);
   const collect = (0, import_react.useCallback)(async () => {
-    const payload = createAnnotationCollection(annotations.map(({ rect: _rect, targetElement: _targetElement, ...annotation }) => annotation));
+    const payload = createAnnotationCollection(stripStoredAnnotations(annotations), getPageContext(resolvedTarget.document));
     const text = formatAnnotationCollection(payload, output);
     try {
       await copyTextToClipboard(text);
@@ -419,14 +700,17 @@ function SourceAnnotator({
       setIsAnnotating(false);
       setSelected(null);
       setHoverRect(null);
+      setAnnotations([]);
+      setPreviewedAnnotation(null);
       setNote("");
+      setStatus(null);
+      setLinkingAnnotationId(null);
       import_sonner.toast.success("Annotations copied", { description: `${payload.annotations.length} copied to clipboard.` });
-      setStatus(`Copied ${payload.annotations.length} annotation${payload.annotations.length === 1 ? "" : "s"}.`);
     } catch (error) {
       import_sonner.toast.error("Copy failed", { description: error instanceof Error ? error.message : "Clipboard copy failed." });
       setStatus(error instanceof Error ? error.message : "Clipboard copy failed.");
     }
-  }, [annotations, onCollect, output]);
+  }, [annotations, onCollect, output, resolvedTarget.document]);
   if (!enabled) {
     return null;
   }
@@ -444,11 +728,33 @@ function SourceAnnotator({
       }
     ),
     isAnnotating && hoverRect ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Box, { rect: hoverRect, kind: "hover" }) : null,
-    selected ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Box, { rect: selected.rect, kind: "selected" }) : null,
-    isAnnotating ? annotations.map((annotation, index) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Pin, { annotation, index }, annotation.id)) : null,
-    selected ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: getPopoverStyle(selected.rect), role: "dialog", "aria-label": "Add source annotation", children: [
+    selected?.targets.map((targetEntry, index) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Box, { rect: targetEntry.rect, kind: "selected" }, index)),
+    isAnnotating ? annotations.map(
+      (annotation, index) => annotation.targets.map((targetEntry, targetIndex) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        Pin,
+        {
+          annotation,
+          rect: targetEntry.rect,
+          index,
+          isPreviewed: previewedAnnotation?.id === annotation.id,
+          onPreview: setPreviewedAnnotation
+        },
+        `${annotation.id}:${targetIndex}`
+      ))
+    ) : null,
+    isAnnotating && previewedAnnotation ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      AnnotationPreview,
+      {
+        annotation: previewedAnnotation,
+        index: annotations.findIndex((annotation) => annotation.id === previewedAnnotation.id),
+        onEdit: editAnnotation,
+        onDelete: deleteAnnotation,
+        onClose: () => setPreviewedAnnotation(null)
+      }
+    ) : null,
+    selected?.targets.length ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: getPopoverStyle(selected.targets[selected.targets.length - 1].rect), role: "dialog", "aria-label": "Add source annotation", children: [
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.popoverTitle, children: "Annotation" }),
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.metaText, children: selected.loading ? "Resolving source\u2026" : formatSelectedSource(selected.annotation) }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.metaText, children: formatSelectedTargets(selected.targets) }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
         "textarea",
         {
@@ -462,17 +768,33 @@ function SourceAnnotator({
       ),
       /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.popoverActions, children: [
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", onClick: () => setSelected(null), style: styles.secondaryButton, children: "Cancel" }),
-        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", onClick: addAnnotation, style: styles.primaryButton, disabled: selected.loading, children: "Save note" })
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", onClick: addAnnotation, style: styles.primaryButton, disabled: selected.targets.some((targetEntry) => targetEntry.loading), children: selected.editingId ? "Update note" : "Save note" })
       ] })
     ] }) : null,
     isAnnotating ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("section", { style: styles.panel, "aria-label": "Collected annotations", children: [
       /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.panelHeader, children: [
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)("strong", { children: "Annotations" }),
-        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: styles.badge, children: collection.annotations.length })
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: styles.badge, children: annotations.length })
       ] }),
-      annotations.length ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("ol", { style: styles.annotationList, children: annotations.map((annotation) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("li", { style: styles.annotationItem, children: [
-        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.noteText, children: annotation.note }),
-        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.metaText, children: formatSelectedSource(annotation) })
+      annotations.length ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("ol", { style: styles.annotationList, children: annotations.map((annotation, index) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("li", { style: styles.annotationItem, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.annotationContent, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.noteText, children: annotation.note }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.metaText, children: formatStoredAnnotationSummary(annotation) })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.annotationActions, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", onClick: () => startLinkingAnnotation(annotation.id), style: styles.linkButton, children: "Link element" }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "button",
+            {
+              type: "button",
+              onClick: () => deleteAnnotation(annotation.id),
+              style: { ...styles.deleteButton, ...styles.iconButton },
+              "aria-label": `Delete annotation ${index + 1}`,
+              title: `Delete annotation ${index + 1}`,
+              children: "\u{1F5D1}"
+            }
+          )
+        ] })
       ] }, annotation.id)) }) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: styles.emptyText, children: "Hover an element, click it, then add a note." }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", onClick: collect, style: styles.collectButton, disabled: !annotations.length, children: "Collect" }),
       status ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.status, children: status }) : null
@@ -483,6 +805,7 @@ function Box({ rect, kind }) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
     "div",
     {
+      "data-mikuexe-annotator-box": kind,
       style: {
         ...styles.box,
         ...kind === "selected" ? styles.selectedBox : styles.hoverBox,
@@ -494,37 +817,170 @@ function Box({ rect, kind }) {
     }
   );
 }
-function Pin({ annotation, index }) {
+function Pin({
+  annotation,
+  rect,
+  index,
+  isPreviewed,
+  onPreview
+}) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-    "div",
+    "button",
     {
-      style: { ...styles.pin, top: Math.max(8, annotation.rect.top - 10), left: Math.max(8, annotation.rect.left - 10) },
+      type: "button",
+      style: { ...styles.pin, top: Math.max(8, rect.top - 10), left: Math.max(8, rect.left - 10) },
       title: annotation.note,
+      "aria-label": `Show annotation ${index + 1}`,
+      "aria-haspopup": "dialog",
+      "aria-expanded": isPreviewed,
+      onClick: () => onPreview(annotation),
+      onMouseOver: () => onPreview(annotation),
+      onFocus: () => onPreview(annotation),
       children: index + 1
     }
   );
 }
-function getAnnotatableTarget(target) {
-  if (!(target instanceof Element)) {
+function AnnotationPreview({
+  annotation,
+  index,
+  onEdit,
+  onDelete,
+  onClose
+}) {
+  const displayIndex = index >= 0 ? index + 1 : 1;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "div",
+    {
+      role: "dialog",
+      "aria-label": `Annotation ${displayIndex}`,
+      style: getPreviewStyle(annotation.targets[0]?.rect ?? { top: 8, left: 8, width: 0, height: 0 }),
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.previewHeader, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.previewTitle, children: [
+            "Annotation ",
+            displayIndex
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.previewActions, children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "button",
+              {
+                type: "button",
+                onClick: onClose,
+                style: { ...styles.secondaryButton, ...styles.iconButton },
+                "aria-label": `Close annotation ${displayIndex}`,
+                title: `Close annotation ${displayIndex}`,
+                children: "\xD7"
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "button",
+              {
+                type: "button",
+                onClick: () => onEdit(annotation),
+                style: { ...styles.secondaryButton, ...styles.iconButton },
+                "aria-label": `Edit annotation ${displayIndex}`,
+                title: `Edit annotation ${displayIndex}`,
+                children: "\u270E"
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "button",
+              {
+                type: "button",
+                onClick: () => onDelete(annotation.id),
+                style: { ...styles.deleteButton, ...styles.iconButton },
+                "aria-label": `Delete annotation ${displayIndex}`,
+                title: `Delete annotation ${displayIndex}`,
+                children: "\u{1F5D1}"
+              }
+            )
+          ] })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.noteText, children: annotation.note }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.metaText, children: formatStoredAnnotationSummary(annotation) })
+      ]
+    }
+  );
+}
+function stripStoredAnnotations(annotations) {
+  return annotations.map((annotation) => ({
+    id: annotation.id,
+    note: annotation.note,
+    targets: annotation.targets.map((targetEntry) => targetEntry.data)
+  }));
+}
+function getAnnotatableTarget(target, ownerDocument) {
+  if (!isElement(target, ownerDocument)) {
     return null;
   }
   if (target.closest(`[${ROOT_ATTR}]`)) {
     return null;
   }
-  if (target === document.body || target === document.documentElement) {
+  if (target === ownerDocument.body || target === ownerDocument.documentElement) {
     return null;
   }
   return target;
 }
-function getRect(element) {
+function getRect(element, frameElement) {
   const rect = element.getBoundingClientRect();
+  const frameRect = frameElement?.getBoundingClientRect();
   return {
-    top: rect.top,
-    left: rect.left,
+    top: rect.top + (frameRect?.top ?? 0),
+    left: rect.left + (frameRect?.left ?? 0),
     width: rect.width,
     height: rect.height
   };
 }
+function useResolvedTarget(target) {
+  const [navigationVersion, setNavigationVersion] = (0, import_react.useState)(0);
+  const resolvedTarget = (0, import_react.useMemo)(() => resolveTarget(target), [target, navigationVersion]);
+  const currentDocumentRef = (0, import_react.useRef)(resolvedTarget.document);
+  currentDocumentRef.current = resolvedTarget.document;
+  (0, import_react.useEffect)(() => {
+    if (typeof HTMLIFrameElement !== "undefined" && target instanceof HTMLIFrameElement) {
+      const updateTarget = () => {
+        const nextTarget = resolveTarget(target);
+        if (nextTarget.document !== currentDocumentRef.current) {
+          setNavigationVersion((version) => version + 1);
+        }
+      };
+      target.addEventListener("load", updateTarget);
+      return () => target.removeEventListener("load", updateTarget);
+    }
+  }, [target]);
+  return resolvedTarget;
+}
+function resolveTarget(target) {
+  const hostDocument = typeof document === "undefined" ? null : document;
+  if (typeof HTMLIFrameElement !== "undefined" && target instanceof HTMLIFrameElement) {
+    const frameDocument = target.contentDocument;
+    if (!frameDocument) {
+      console.warn("@mikuexe/annotator-react: SourceAnnotator target iframe must be same-origin; iframe contentDocument is not accessible.");
+      return {
+        document: null,
+        frameElement: target
+      };
+    }
+    return {
+      document: frameDocument,
+      frameElement: target
+    };
+  }
+  if (typeof Document !== "undefined" && target instanceof Document) {
+    return {
+      document: target,
+      frameElement: null
+    };
+  }
+  return {
+    document: hostDocument,
+    frameElement: null
+  };
+}
+function isElement(target, ownerDocument) {
+  const elementConstructor = ownerDocument.defaultView?.Element ?? Element;
+  return target instanceof elementConstructor;
+}
 function getPopoverStyle(rect) {
   const top = Math.min(window.innerHeight - 260, rect.top + rect.height + 8);
   const left = Math.min(window.innerWidth - 340, Math.max(8, rect.left));
@@ -534,17 +990,45 @@ function getPopoverStyle(rect) {
     left
   };
 }
-function formatSelectedSource(annotation) {
-  const componentPath = annotation?.componentPath.length ? annotation.componentPath.join(" \u203A ") : null;
-  if (!annotation) {
+function getPreviewStyle(rect) {
+  const top = Math.min(window.innerHeight - 120, rect.top + rect.height + 8);
+  const left = Math.min(window.innerWidth - 260, Math.max(8, rect.left));
+  return {
+    ...styles.preview,
+    top: Math.max(8, top),
+    left
+  };
+}
+function formatSelectedTargets(targets) {
+  if (!targets.length) {
+    return "Source unavailable";
+  }
+  if (targets.length === 1) {
+    return formatTargetSource(targets[0].target);
+  }
+  const resolvedCount = targets.filter((targetEntry) => targetEntry.target).length;
+  return `${targets.length} elements selected \xB7 ${resolvedCount}/${targets.length} resolved`;
+}
+function formatStoredAnnotationSummary(annotation) {
+  const firstTarget = annotation.targets[0]?.data;
+  const targetSummary = formatTargetSource(firstTarget);
+  const linkedSummary = annotation.targets.length > 1 ? ` \xB7 ${annotation.targets.length} linked elements` : "";
+  return `${targetSummary}${linkedSummary}`;
+}
+function formatTargetSource(target) {
+  const componentPath = target?.componentPath.length ? target.componentPath.join(" \u203A ") : null;
+  if (!target) {
     return "Source unavailable";
   }
-  if (!annotation.source?.filePath) {
-    return `${annotation.element.selector} \xB7 source unavailable`;
+  if (!target.source?.filePath) {
+    return `${target.element.selector} \xB7 source unavailable`;
   }
-  const line = annotation.source.lineNumber ? `:${annotation.source.lineNumber}` : "";
+  const line = target.source.lineNumber ? `:${target.source.lineNumber}` : "";
   const component = componentPath ? ` \xB7 ${componentPath}` : "";
-  return `${annotation.source.filePath}${line}${component}`;
+  return `${target.source.filePath}${line}${component}`;
+}
+function shouldExtendSelection(event) {
+  return event.metaKey || event.ctrlKey;
 }
 function matchesHotkey(event, hotkey) {
   const parts = hotkey.toLowerCase().split("+").map((part) => part.trim()).filter(Boolean);
@@ -606,6 +1090,7 @@ var styles = {
   },
   popover: {
     position: "fixed",
+    zIndex: 2,
     width: 320,
     pointerEvents: "auto",
     background: "#ffffff",
@@ -658,6 +1143,7 @@ var styles = {
   },
   panel: {
     position: "fixed",
+    zIndex: 1,
     right: 16,
     bottom: 68,
     width: 300,
@@ -694,11 +1180,23 @@ var styles = {
     overflow: "auto"
   },
   annotationItem: {
+    display: "grid",
+    gap: 8,
+    alignItems: "start",
     marginBottom: 8
   },
+  annotationContent: {
+    minWidth: 0
+  },
+  annotationActions: {
+    display: "flex",
+    gap: 8,
+    flexWrap: "wrap"
+  },
   noteText: {
     color: "#0f172a",
-    fontWeight: 650
+    fontWeight: 650,
+    overflowWrap: "anywhere"
   },
   emptyText: {
     color: "#64748b",
@@ -719,31 +1217,91 @@ var styles = {
     color: "#475569",
     fontSize: 12
   },
+  linkButton: {
+    border: "1px solid #bfdbfe",
+    borderRadius: 999,
+    background: "#eff6ff",
+    color: "#1d4ed8",
+    padding: "4px 7px",
+    fontSize: 11,
+    fontWeight: 750,
+    cursor: "pointer"
+  },
+  deleteButton: {
+    border: "1px solid #fecaca",
+    borderRadius: 999,
+    background: "#fff1f2",
+    color: "#be123c",
+    padding: "4px 7px",
+    fontSize: 11,
+    fontWeight: 750,
+    cursor: "pointer"
+  },
+  preview: {
+    position: "fixed",
+    maxWidth: 240,
+    pointerEvents: "auto",
+    background: "#ffffff",
+    border: "1px solid #cbd5e1",
+    borderRadius: 10,
+    padding: 10,
+    boxShadow: "0 14px 35px rgba(15, 23, 42, 0.18)"
+  },
+  previewHeader: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 8,
+    marginBottom: 6
+  },
+  previewTitle: {
+    color: "#475569",
+    fontSize: 12,
+    fontWeight: 800
+  },
+  previewActions: {
+    display: "inline-flex",
+    gap: 6
+  },
+  iconButton: {
+    width: 26,
+    height: 26,
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    padding: 0,
+    lineHeight: 1
+  },
   pin: {
     position: "fixed",
+    border: 0,
     width: 20,
     height: 20,
     borderRadius: 999,
     display: "inline-flex",
     alignItems: "center",
     justifyContent: "center",
-    pointerEvents: "none",
+    pointerEvents: "auto",
     background: "#f97316",
     color: "#ffffff",
     fontSize: 12,
     fontWeight: 800,
-    boxShadow: "0 8px 18px rgba(15, 23, 42, 0.2)"
+    boxShadow: "0 8px 18px rgba(15, 23, 42, 0.2)",
+    cursor: "pointer",
+    padding: 0
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SourceAnnotator,
+  captureAnnotationTarget,
   captureElementAnnotation,
   copyTextToClipboard,
   createAnnotationCollection,
   formatAnnotationCollection,
   formatMarkdown,
   getElementSelector,
+  getPageContext,
   trimText
 });
 //# sourceMappingURL=index.cjs.map