@mikuexe/annotator-react 0.1.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.2.2
+
+### Patch Changes
+
+- 24b4250: Show editable annotation popovers from collapsed pins and use icon-only delete controls.
+
+## 0.2.1
+
+### Patch Changes
+
+- 41c21a6: Clarify README positioning, upstream credit, and support expectations.
+
+## 0.2.0
+
+### Minor Changes
+
+- d9ab7b3: Add collection page context, multi-element annotations, and link-element follow-up selection for existing notes.
+- 533db2a: Add same-origin iframe target support so parent review shells can annotate elements inside framed prototypes.
+
+## 0.1.2
+
+### Patch Changes
+
+- cb4043a: Improve annotation mode interactions: block host pointer events while selecting, edit/delete saved annotations, preview pins on hover, and clear copied annotations after collect.
+
+## 0.1.1
+
+### Patch Changes
+
+- be9d607: update naming around package
+
 ## 0.1.0 - Initial MVP
 
 ### Added

package/README.md

@@ -2,6 +2,19 @@
 
 React devtool overlay for source-aware UI annotations. Select live DOM elements, write notes, then copy an agent-ready Markdown prompt.
 
+## Start here first
+
+If you want a polished, supported tool in this space, look at these first:
+
+- [react-grab](https://www.react-grab.com/)
+- [Agentation](https://www.agentation.com/)
+
+This package exists for my own local-agent UI workflow. It is intentionally small, experimental, and likely to change whenever my needs change.
+
+Important credit: Aiden Bai created [react-grab](https://www.react-grab.com/) and [`element-source`](https://github.com/aidenybai/element-source), the source-resolution library this package builds on.
+
+I made this repo because I wanted custom UI behavior on top of `element-source`. You are welcome to use it, but please treat it as personal tooling, not a supported product. I am not committing to issue triage, feature requests, roadmap stability, or compatibility guarantees. Requests are fine, but this package will continue to follow my own needs first.
+
 ## Install
 
 ```bash
@@ -16,7 +29,7 @@ npm install react react-dom
 
 ## Quick start
 
-`register` must be the first import in your app entry, before React loads.
+`register` must load before React.
 
 ```tsx
 // src/main.tsx
@@ -34,10 +47,12 @@ createRoot(document.getElementById("root")!).render(
 );
 ```
 
-`SourceAnnotator` is a client component: render it only from browser/client React trees. In Next.js, place it behind a client boundary such as a file with `"use client"`.
+`SourceAnnotator` is a client component: render it only from browser/client React trees.
 
 Click **Annotate**, select an element, write a note, then click **Collect**.
 
+Desktop multi-select: while annotating, hold **Ctrl** (Windows/Linux) or **⌘ Cmd** (macOS) and click more elements to attach them to the same note. You can also use **Link element** on an existing annotation to attach one more element to that same comment.
+
 ## API
 
 ```ts
@@ -45,12 +60,35 @@ type SourceAnnotatorProps = {
   enabled?: boolean;
   hotkey?: string; // default: "alt+a"
   output?: "markdown" | "json" | "both"; // default: "markdown"
+  target?: Document | HTMLIFrameElement | null; // default: document
   onCollect?: (payload: AnnotationCollection) => void;
   renderToaster?: boolean; // default: true
 };
 ```
 
-`onCollect(payload)` fires after the clipboard write succeeds.
+`onCollect(payload)` fires after the clipboard write succeeds. The payload includes collection-level page context as `page: { domain, path }`.
+
+### Annotating same-origin iframes
+
+Pass a same-origin iframe element as `target` when the annotator UI lives in a parent shell but users need to select elements inside the framed app. The annotator listens inside the iframe document, captures the actual clicked element, and offsets highlights, pins, and popovers into the parent viewport.
+
+```tsx
+import { useState } from "react";
+import { SourceAnnotator } from "@mikuexe/annotator-react";
+
+export function ReviewShell() {
+  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);
+
+  return (
+    <>
+      <iframe ref={setIframe} src="/prototype/" />
+      <SourceAnnotator target={iframe} />
+    </>
+  );
+}
+```
+
+The iframe must be same-origin so the browser allows access to `iframe.contentDocument`. Cross-origin iframes cannot expose their internal DOM to the parent page.
 
 ### Sonner toaster ownership
 
@@ -83,6 +121,8 @@ Example copied Markdown:
 Please update the UI based on these source-linked annotations.
 
 Collected at: 2026-04-25T00:00:00.000Z
+Domain: example.com
+Path: /prototype
 
 ## Annotation 1
 
@@ -103,16 +143,16 @@ Selector: #root main.app-shell section.hero button.primary-cta:nth-of-type(1)
 ## Captured data
 
 ```ts
-type Annotation = {
-  id: string;
-  note: string;
-  source: {
-    filePath: string;
-    lineNumber: number | null;
-    columnNumber: number | null;
-    componentName: string | null;
-  } | null;
-  sourceStack: Annotation["source"][];
+type AnnotationSource = {
+  filePath: string;
+  lineNumber: number | null;
+  columnNumber: number | null;
+  componentName: string | null;
+};
+
+type AnnotationTarget = {
+  source: AnnotationSource | null;
+  sourceStack: AnnotationSource[];
   componentPath: string[];
   element: {
     tagName: string;
@@ -121,13 +161,28 @@ type Annotation = {
     selector: string;
   };
 };
+
+type Annotation = {
+  id: string;
+  note: string;
+  targets: AnnotationTarget[];
+};
+
+type AnnotationCollection = {
+  createdAt: string;
+  page: {
+    domain: string;
+    path: string;
+  };
+  annotations: Annotation[];
+};
 ```
 
 ## How source capture works
 
 `@mikuexe/annotator-react/register` installs the React DevTools hook through `bippy/install-hook-only`. `element-source` then uses React ownership data to resolve selected DOM elements back to React components/source.
 
-If source resolution fails, annotations still include DOM context: tag, HTML, text, selector, and any nearest React component/owner path that could be resolved.
+If source resolution fails, annotations still include DOM context: tag, HTML, text, selector, and any nearest React component/owner path that could be resolved. Copied/exported payloads contain only serializable data and never internal DOM references.
 
 ## Local example
 
@@ -139,19 +194,6 @@ npm run dev
 
 The example app aliases linked source to one React copy in Vite to avoid duplicate-React invalid hook errors during local development.
 
-## Package scripts
-
-```bash
-npm run check          # typecheck + unit tests + build
-npm run check:all      # check + example build + npm pack dry-run
-npm run pack:dry-run   # inspect npm package contents
-```
-
-## Publish support
-
-Package support links currently target `https://github.com/mikuexe/annotator-react`. Confirm `repository`, `homepage`, and `bugs` in `package.json` point at the final public repo before publishing.
-
-
 ## Current constraints
 
 - Vite-first support.