@mikuexe/annotator-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 - Initial MVP
+
+### Added
+
+- React `SourceAnnotator` overlay for selecting live DOM elements and attaching notes.
+- Clipboard output as Markdown, JSON, or both.
+- Source-aware capture through `@mikuexe/annotator-react/register`, `bippy`, and `element-source`.
+- Graceful fallback output when React source data is unavailable.
+- Sonner copy success/error toasts, with `renderToaster={false}` for host-owned toaster setups.
+- ESM and CommonJS package entrypoints for the main API and `./register`.
+
+### Package behavior
+
+- Published files are limited to `dist/`, `README.md`, `CHANGELOG.md`, `LICENSE`, and `package.json`.
+- Runtime dependencies are externalized to avoid bundling React or host app dependencies.
+- Built main entrypoints include a `"use client"` directive for React Server Component/client-boundary tooling.
+
+### Known constraints
+
+- Vite-first support; Next.js usage is documented but not fully validated.
+- `@mikuexe/annotator-react/register` must import before React loads.
+- Source capture quality depends on React owner/source metadata availability.
+- No persistence, accounts, screenshots, backend sync, or collaboration features in this MVP.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ExecMD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @mikuexe/annotator-react
+
+React devtool overlay for source-aware UI annotations. Select live DOM elements, write notes, then copy an agent-ready Markdown prompt.
+
+## Install
+
+```bash
+npm install @mikuexe/annotator-react
+```
+
+Peer deps:
+
+```bash
+npm install react react-dom
+```
+
+## Quick start
+
+`register` must be the first import in your app entry, before React loads.
+
+```tsx
+// src/main.tsx
+import "@mikuexe/annotator-react/register";
+
+import { createRoot } from "react-dom/client";
+import { SourceAnnotator } from "@mikuexe/annotator-react";
+import { App } from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <>
+    <App />
+    <SourceAnnotator />
+  </>,
+);
+```
+
+`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"`.
+
+Click **Annotate**, select an element, write a note, then click **Collect**.
+
+## API
+
+```ts
+type SourceAnnotatorProps = {
+  enabled?: boolean;
+  hotkey?: string; // default: "alt+a"
+  output?: "markdown" | "json" | "both"; // default: "markdown"
+  onCollect?: (payload: AnnotationCollection) => void;
+  renderToaster?: boolean; // default: true
+};
+```
+
+`onCollect(payload)` fires after the clipboard write succeeds.
+
+### Sonner toaster ownership
+
+By default, `SourceAnnotator` renders its own Sonner `<Toaster />` so copy success and failure toasts work without host setup. If your app already renders a Sonner toaster, disable the internal one to avoid duplicate toaster roots:
+
+```tsx
+<SourceAnnotator renderToaster={false} />
+```
+
+## Output modes
+
+Default output is Markdown only:
+
+```tsx
+<SourceAnnotator />
+```
+
+Opt into structured JSON:
+
+```tsx
+<SourceAnnotator output="both" />
+<SourceAnnotator output="json" />
+```
+
+Markdown includes available fields only. Missing source data is omitted instead of printed as `Unavailable`.
+
+Example copied Markdown:
+
+```md
+Please update the UI based on these source-linked annotations.
+
+Collected at: 2026-04-25T00:00:00.000Z
+
+## Annotation 1
+
+ID: ann-1
+Note: Make this CTA full width.
+Source: src/App.tsx:42:7
+Nearest React component: ActionButton
+React owner path: ActionButton › HeroSection › App
+React source stack:
+- src/App.tsx:42:7 (ActionButton)
+- src/App.tsx:18:3 (HeroSection)
+Element tag: button
+Element HTML: <button class="primary-cta" type="button">Start annotation pass</button>
+Element text: Start annotation pass
+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"][];
+  componentPath: string[];
+  element: {
+    tagName: string;
+    text: string;
+    html: string;
+    selector: string;
+  };
+};
+```
+
+## 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.
+
+## Local example
+
+```bash
+cd examples/vite-react
+npm install
+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.
+- React-first API; not framework agnostic.
+- No backend, accounts, persistence, screenshots, or collaboration in v1.
+- Next.js support is not validated yet.
+- Source capture depends on `register` running before React imports.