feat(release): ship v2.0.0 annotate+draw workflow update

Promote the annotate and draw dual-capture model with redesigned compact toolbar settings UI, region-aware reporting, and MCP query support. Align landing/docs messaging and bump runtime/package versions to 2.0.0 for release readiness.

Author: iota31

README.md

@@ -27,6 +27,8 @@ Powered by [onLLM.dev](https://onllm.dev).
 - 🧩 No integration into app code
 - 🎛️ Per-tab ON/OFF control (off by default)
 - 🎯 In-page annotation dialog with intent + severity
+- ✍️ Draw mode for region annotations (rectangle + ellipse)
+- ⚙️ Compact toolbar with pop-out settings (output level + clear on copy)
 - 👀 Visual markers and hover targeting
 - 🧾 Export outputs in compact / standard / detailed / forensic formats
 - 🛡️ Shadow DOM isolation for stable styling
@@ -69,11 +71,13 @@ Then load it in Chrome or Edge:
 1. Open any supported website tab.
 2. Click the onUI extension icon.
 3. Enable `This Tab`.
-4. Use the on-page launcher to annotate and manage notes.
-5. Hold `Shift` and click multiple elements to batch-select targets.
-6. Release `Shift` to open a shared annotation dialog for selected targets.
-7. Save once to create one annotation per selected element.
-8. Copy exported output from the toolbar.
+4. Use the on-page launcher to open the compact toolbar.
+5. Toggle **Annotate mode** for element targeting or **Draw mode** for region targeting.
+6. Hold `Shift` and click multiple elements to batch-select targets.
+7. Release `Shift` to open a shared annotation dialog for selected targets.
+8. Save once to create one annotation per selected element (or one region annotation in draw flow).
+9. Open toolbar **Settings** to choose output level and configure **Clear on copy**.
+10. Copy exported output from the toolbar.
 
 ## 🔌 Local MCP Setup
 

docs/mcp-setup.md

@@ -9,6 +9,16 @@ This release supports:
 
 Browser support in this release: **Chrome stable + Edge stable (unpacked)**.
 
+## UI Capture Model (v2.0.0)
+
+This release formalizes two complementary capture flows in the extension UI:
+
+1. **Annotate mode**: target individual elements (or Shift multi-select groups) for precise element-level issues.
+2. **Draw mode**: drag rectangle/ellipse regions for layout, spacing, and grouping issues that span multiple elements.
+3. **Compact toolbar + pop-out settings**: primary controls remain in a compact rail, while output level and clear-on-copy are configured in a readable settings pop-out.
+
+MCP consumers receive these captures through the same local tools (`onui_get_annotations`, `onui_search_annotations`, `onui_get_report`) with region metadata preserved in report output.
+
 ## One-Command Setup
 
 macOS/Linux:
@@ -66,6 +76,57 @@ The local MCP server exposes:
 7. `onui_delete_annotation`
 8. `onui_clear_page_annotations`
 
+## Recommended v2.0.0 Agent Flow
+
+1. Open the page and capture issues with **Annotate mode** for elements or **Draw mode** for regions.
+2. Use toolbar **Settings** to choose the output level your agent needs (`compact`, `standard`, `detailed`, `forensic`).
+3. Query page state through `onui_get_annotations` or generate a page-level summary with `onui_get_report`.
+4. Search region or element issues with `onui_search_annotations` when iterating on a subset of UI work.
+5. After fixes are verified, update or clear annotations through the metadata/delete tools.
+
+## Region-aware MCP Query Examples
+
+### Search for region annotations by shape
+
+```json
+{
+  "tool": "onui_search_annotations",
+  "arguments": {
+    "query": "region ellipse",
+    "pageUrl": "https://example.com/ui"
+  }
+}
+```
+
+### Search by region geometry text
+
+`onui_search_annotations` matches rounded region geometry tokens (`x`, `y`, `width`, `height`) in addition to comment/selector/path/tag text.
+
+```json
+{
+  "tool": "onui_search_annotations",
+  "arguments": {
+    "query": "width 120 height 80",
+    "pageUrl": "https://example.com/ui",
+    "status": "pending"
+  }
+}
+```
+
+### Generate a region-aware report
+
+```json
+{
+  "tool": "onui_get_report",
+  "arguments": {
+    "pageUrl": "https://example.com/ui",
+    "level": "detailed"
+  }
+}
+```
+
+In `detailed` and `forensic` levels, region annotations include target type, shape, and geometry fields in report output.
+
 ## Recommended Agent Cleanup Workflow
 
 If you want agents to process annotations and then remove them:

docs/release.md

@@ -1,5 +1,14 @@
 # onUI Local Release Runbook
 
+## Release Summary (v2.0.0)
+
+- Added a dual capture model with **Annotate mode** for element-level feedback and **Draw mode** for region-level layout and spacing issues.
+- Added draw mode shape selection (`rectangle`/`ellipse`) plus region editing UX with persistent outlines and transform handles.
+- Redesigned the floating toolbar to stay compact while opening output level and clear-on-copy controls in a readable pop-out settings card.
+- Updated report formatters (`compact`, `standard`, `detailed`, `forensic`) to emit explicit region target metadata and geometry.
+- Improved MCP/local search behavior so region annotations are queryable by target type/shape and geometry text, with report generation preserving region fields.
+- Polished toolbar/dialog behavior for mode toggles, escape handling, multi-select hints, and copy/clear settings flow.
+
 ## Preconditions
 
 1. Node 20+

docs/usage.md

@@ -5,11 +5,20 @@
 1. Open the target web page.
 2. Open the extension popup.
 3. Toggle `This Tab` on.
-4. Use the floating onUI launcher to start annotating.
-5. Click normally to annotate a single element.
-6. Hold `Shift` and click multiple elements to build a batch selection.
-7. Release `Shift` to open one dialog for all selected targets.
-8. Save notes and copy output when needed.
+4. Use the floating onUI launcher to open the toolbar.
+5. Choose one annotation path:
+   1. **Element annotation path**
+      1. Toggle **Annotate mode**.
+      2. Click an element to open the element dialog.
+      3. Add comment/intent/severity and save.
+   2. **Region draw path**
+      1. Toggle **Draw mode**.
+      2. Choose shape: **rectangle** or **ellipse**.
+      3. Drag on the page to define region geometry.
+      4. Release pointer to open the region dialog.
+      5. Add comment/intent/severity and save.
+6. Optionally open **Settings** from the toolbar to choose output level and toggle **Clear on copy**.
+7. Copy output from the toolbar when needed.
 
 ## Annotation Dialog
 
@@ -20,11 +29,51 @@ Each annotation supports:
 
 ## Multi-Element Batch Annotation
 
-- Hold `Shift` and click to toggle elements in or out of the current batch.
-- Releasing `Shift` opens a single dialog with the full selected target list.
-- Removing targets in the dialog updates the batch before save.
-- Saving creates one annotation per selected element with shared internal batch metadata.
-- Batch selection is capped at 25 elements.
+1. Toggle **Annotate mode**.
+2. Hold `Shift` and click elements to add/remove them from the pending batch.
+3. Release `Shift` to open one dialog for the current connected targets.
+4. Optionally remove targets in the dialog before save.
+5. Save to create one annotation per selected element with shared batch metadata.
+6. Keep batch size at or below 25 elements.
+
+## Region Editing
+
+1. Click an existing region marker/outline to open it in edit mode.
+2. Move the region by dragging inside the transform box.
+3. Resize using the eight handles (`nw`, `n`, `ne`, `e`, `se`, `s`, `sw`, `w`).
+4. Save to persist updated geometry with the annotation comment/intent/severity.
+5. Use Delete in the region dialog to remove the region annotation.
+
+## Interaction Behavior (Shift, Draw, Escape)
+
+1. `Shift` multi-select applies to **element selection flow**.
+2. Draw mode is exclusive with annotate mode; enabling draw mode exits annotate mode.
+3. `Escape` behavior is state-based:
+   1. During active draw draft: cancel current draft.
+   2. With pending drawn region dialog: close pending region.
+   3. In draw mode (idle): exit draw mode.
+   4. While editing region transform geometry: clear transform edit state.
+   5. During pending Shift multi-select (before dialog): clear pending selection.
+   6. In annotate mode with no higher-priority state: exit annotate mode.
+
+## Toolbar Settings (Compact Pop-out)
+
+1. The floating toolbar remains compact by default.
+2. Click the **Settings** icon to open the pop-out settings card.
+3. Use **Output level** to switch between `compact`, `standard`, `detailed`, and `forensic` export formats.
+4. Use **Clear on copy** to automatically clear annotations after a successful copy action.
+
+## Export and Report Output for Region Annotations
+
+1. Region annotations are exported with `targetType` = `region` and include:
+   1. `shape` (`rectangle` or `ellipse`)
+   2. `geometry` (`x`, `y`, `width`, `height`, coordinate space)
+2. Output-level implications:
+   1. **compact**: includes inline region shape + geometry summary.
+   2. **standard**: includes target type, shape, and geometry fields.
+   3. **detailed**: includes target type/shape/geometry plus compatibility selector/tag/path fields.
+   4. **forensic**: includes region identification fields and region geometry in target identification.
+3. Region edits update geometry used in subsequent report/export output.
 
 ## Notes
 

landing-page/index.html

@@ -63,10 +63,10 @@
         </a>
       </div>
 
-      <h1>Ship cleaner UI products by annotating any UI directly in the browser.</h1>
+      <h1>Annotate elements, draw regions, and ship cleaner UI faster.</h1>
 
       <p class="hero-sub">
-        onUI adds a visual annotation layer to any web app, then exports structured context your agents can use immediately. Annotate single elements or multi-select related UI in one pass. With <code>onui-local</code> MCP connected, your agent can continuously read fresh annotations and keep applying fixes — like UI pair programming. No app code changes. No backend.
+        onUI gives you two capture modes in one workflow: <strong>Annotate mode</strong> for element-level fixes and <strong>Draw mode</strong> for layout or spacing regions. The new compact toolbar design keeps primary actions in a minimal rail, while settings open in a focused pop-out card. With <code>onui-local</code> MCP connected, your agent can read fresh annotations and iterate continuously. No app code changes. No backend.
       </p>
 
       <div class="hero-cta">
@@ -102,8 +102,9 @@ <h1>Ship cleaner UI products by annotating any UI directly in the browser.</h1>
       <div class="hero-chips">
         <span class="chip chip-teal">Chrome Stable</span>
         <span class="chip chip-teal">Edge Stable (Unpacked)</span>
-        <span class="chip chip-teal">Multi-Element Selection</span>
-        <span class="chip chip-blue">Local MCP</span>
+        <span class="chip chip-teal">Annotate + multi-select</span>
+        <span class="chip chip-teal">Draw mode regions</span>
+        <span class="chip chip-blue">Redesigned toolbar UI</span>
         <span class="chip chip-amber">Zero Backend</span>
       </div>
     </section>
@@ -123,8 +124,8 @@ <h2>See onUI in action</h2>
 
     <section id="features" class="section">
       <div class="section-header">
-        <h2>Built for annotation-first agent workflows</h2>
-        <p>Everything you need for AI-assisted UI development</p>
+        <h2>Built for annotate + draw workflows</h2>
+        <p>Element-level and region-level feedback in the redesigned compact toolbar</p>
       </div>
       <div class="feature-grid">
         <article class="feature-card">
@@ -138,22 +139,22 @@ <h3>No integration work</h3>
           <div class="feature-icon feature-icon-blue">
             <svg viewBox="0 0 24 24"><path fill="currentColor" d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"/></svg>
           </div>
-          <h3>Precision context</h3>
-          <p>Capture intent and severity directly on UI elements so agents understand what to fix and how urgent it is.</p>
+          <h3>Annotate mode for precise UI fixes</h3>
+          <p>Target individual elements, attach intent and severity, and use Shift multi-select when one issue spans multiple components.</p>
         </article>
         <article class="feature-card">
           <div class="feature-icon feature-icon-blue">
             <svg viewBox="0 0 24 24"><path fill="currentColor" d="M3 5h8v8H3V5zm10 0h8v8h-8V5zM3 15h8v4H3v-4zm10 2h8v2h-8v-2z"/></svg>
           </div>
-          <h3>Multi-element selection</h3>
-          <p>Select and annotate related elements together when one issue spans multiple UI parts.</p>
+          <h3>Draw mode for layout and spacing</h3>
+          <p>Drag rectangle or ellipse regions to call out spacing, alignment, grouping, and layout problems that are bigger than one element.</p>
         </article>
         <article class="feature-card">
           <div class="feature-icon feature-icon-amber">
             <svg viewBox="0 0 24 24"><path fill="currentColor" d="M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm-5 14H7v-2h7v2zm3-4H7v-2h10v2zm0-4H7V7h10v2z"/></svg>
           </div>
-          <h3>Multiple output formats</h3>
-          <p>Export compact, standard, detailed, or forensic reports depending on your debugging depth.</p>
+          <h3>New compact toolbar design</h3>
+          <p>The redesigned floating rail stays small on-page, while settings open in a readable pop-out card for output level and clear-on-copy controls.</p>
         </article>
         <article class="feature-card">
           <div class="feature-icon feature-icon-teal">
@@ -187,8 +188,8 @@ <h2>The AI pair-programming loop</h2>
       <div class="workflow-grid">
         <div class="workflow-step workflow-step-teal">
           <span class="workflow-num">01</span>
-          <h3>Mark UI issues</h3>
-          <p>Click single elements or multi-select related UI to add annotations with intent (bug, enhancement, question) and severity.</p>
+          <h3>Capture with Annotate or Draw</h3>
+          <p>Use Annotate mode for single or multi-element feedback, or Draw mode to mark regions for layout and spacing issues.</p>
         </div>
         <div class="workflow-step workflow-step-blue">
           <span class="workflow-num">02</span>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "onui",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "private": true,
   "description": "Browser extension for annotating UI elements for AI agents",
   "packageManager": "pnpm@9.15.0",

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onui/core",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "private": true,
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,10 @@
   },
   "scripts": {
     "build": "tsc",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
   }
 }

packages/core/src/formatters/compact.ts

@@ -1,11 +1,15 @@
 import type { Annotation, ReportContext } from '../types.js';
-import { truncate } from './shared.js';
+import { formatRegionGeometry, isRegionAnnotation, truncate } from './shared.js';
 
 export function formatCompact(annotations: Annotation[], context: ReportContext): string {
   const lines: string[] = [`# ${context.title}`, `URL: ${context.url}`, ''];
 
   annotations.forEach((annotation, index) => {
-    let line = `${index + 1}. \`${annotation.selector}\` > ${annotation.comment}`;
+    const location = isRegionAnnotation(annotation)
+      ? `${annotation.region.shape}(${formatRegionGeometry(annotation.region.geometry)})`
+      : `\`${annotation.selector}\``;
+
+    let line = `${index + 1}. ${location} > ${annotation.comment}`;
 
     if (annotation.selectedText) {
       line += ` (selected: "${truncate(annotation.selectedText, 50)}")`;

packages/core/src/formatters/detailed.ts

@@ -1,5 +1,5 @@
 import type { Annotation, ReportContext } from '../types.js';
-import { truncate } from './shared.js';
+import { formatRegionGeometry, isRegionAnnotation, truncate } from './shared.js';
 
 export function formatDetailed(annotations: Annotation[], context: ReportContext): string {
   const lines: string[] = [
@@ -11,22 +11,34 @@ export function formatDetailed(annotations: Annotation[], context: ReportContext
   ];
 
   annotations.forEach((annotation, index) => {
-    lines.push(`## ${index + 1}. ${annotation.elementPath}`);
+    const isRegion = isRegionAnnotation(annotation);
+    lines.push(`## ${index + 1}. ${isRegion ? `${annotation.region.shape} region` : annotation.elementPath}`);
     lines.push('');
-    lines.push('### Element Info');
-    lines.push(`- **Selector:** \`${annotation.selector}\``);
-    lines.push(`- **Tag:** \`${annotation.tagName}\``);
-    lines.push(`- **Path:** \`${annotation.elementPath}\``);
+    lines.push('### Target Info');
 
-    if (annotation.role) {
-      lines.push(`- **Role:** ${annotation.role}`);
-    }
+    if (isRegion) {
+      lines.push('- **Target type:** `region`');
+      lines.push(`- **Shape:** \`${annotation.region.shape}\``);
+      lines.push(`- **Geometry:** ${formatRegionGeometry(annotation.region.geometry)}`);
+      lines.push(`- **Selector (compat):** \`${annotation.selector}\``);
+      lines.push(`- **Tag (compat):** \`${annotation.tagName}\``);
+      lines.push(`- **Path (compat):** \`${annotation.elementPath}\``);
+    } else {
+      lines.push('- **Target type:** `element`');
+      lines.push(`- **Selector:** \`${annotation.selector}\``);
+      lines.push(`- **Tag:** \`${annotation.tagName}\``);
+      lines.push(`- **Path:** \`${annotation.elementPath}\``);
 
-    if (annotation.attributes && Object.keys(annotation.attributes).length > 0) {
-      lines.push('');
-      lines.push('### Attributes');
-      for (const [key, value] of Object.entries(annotation.attributes)) {
-        lines.push(`- \`${key}\`: \`${truncate(value, 80)}\``);
+      if (annotation.role) {
+        lines.push(`- **Role:** ${annotation.role}`);
+      }
+
+      if (annotation.attributes && Object.keys(annotation.attributes).length > 0) {
+        lines.push('');
+        lines.push('### Attributes');
+        for (const [key, value] of Object.entries(annotation.attributes)) {
+          lines.push(`- \`${key}\`: \`${truncate(value, 80)}\``);
+        }
       }
     }