vite-plugin-specter 0.6.0 → 0.7.0

package/README.md

@@ -1,8 +1,8 @@
 # Specter
 
-**Hover any element on your dev site. See its styles. Copy to AI.**
+**Point at any element on your dev site. Mark what to change — with exact values and a source anchor — and hand it to your AI.**
 
-Specter is a Vite plugin that adds an element inspector overlay to your dev server. Toggle it on, hover any element to see its styles, component name, and spacing. Copy with one shortcut and paste into your AI assistant for one-shot edits. Specter is automatically stripped from production builds.
+Specter is a Vite plugin that overlays an element inspector on your dev server. Hover any element to see its styles, component name, and spacing; measure gaps Figma-style; mark elements as **Specs** with a plain-language note; then copy them all to your AI assistant — each one carries the exact current values and a greppable source anchor, so there's no "which element?" and no "what's the current value?". Optionally, push your Specs straight into Claude Code with `/spectify`. Specter is automatically stripped from production builds.
 
 ## Requirements
 
@@ -46,51 +46,84 @@ If you ever need Specter gone entirely, remove `specter()` from the Vite config
 
 ### Toggle on/off
 
-Press **Ctrl+Option+Z** to enter Specter mode. A small zap icon appears at the bottom-left. Press again (or Esc) to exit.
+Press **Ctrl+Option+Z** to activate Specter. A small zap icon appears at the bottom-left. Press again (or **Esc**) to hide it — your Specs are kept and reappear when you reactivate.
 
-### Inspect an element
+### Three modes
 
-Once active, just **hover** any element. A tooltip shows:
+Specter has three modes; switching mode only changes *what's shown on screen* — you can mark a Spec in any of them.
+
+| Mode | Enter | Shows |
+|------|-------|-------|
+| **Properties** (default) | — | Styles tooltip on hover |
+| **Measure** | tap **Option** | Figma-style spacing to neighbors |
+| **Comment** | **C** | Just an outline — for clean design review |
+
+### Inspect an element (Properties mode)
+
+**Hover** any element. A tooltip shows:
 
 - HTML tag + React/Vue component name + dimensions
 - Text content (truncated)
 - Font: family, weight, size, line-height
-- Color (with hex) and background
+- Color (with hex) and background — flagged `(hover)` if the value comes from a `:hover` rule
 - Padding, margin, border-radius (if non-zero)
 - Display + gap + flex direction
 
-### Copy to clipboard
+### Measure spacing (Measure mode)
+
+Tap **Option** to switch to Measure mode. Hover any element to see distances to its surrounding neighbors. Press **M** while hovering to **pin** that element, then hover another to measure the gap or inset between the two; **M** again unpins. Tap **Option** again to return to Properties.
 
-Press **Cmd+C** while hovering. The element info is copied in an AI-optimized format. Paste it into Claude, Cursor, or any AI assistant and say what you want changed.
+### Mark a Spec (and optionally annotate)
 
-### Measure mode
+Press **P** while hovering an element to mark it as a **Spec**. A note box opens on the element — type the change you want ("reduce width to 320", "tighten padding to 8px") and press **Enter**, or just leave it empty for a plain mark. Numbered badges appear on each marked element. Mark as many as you like across the page.
 
-Tap **Option** to switch to Measure mode. Hover any element to see distance measurements to its surrounding neighbors (like Figma's spacing view). Tap **Option** again to return to Properties mode.
+### Comment mode
 
-### Pin an element
+Press **C** for Comment mode: the props/measure overlays hide and you get just a hover outline — good for talking through a design without visual noise. Specs still capture full properties underneath, so a Comment-mode Spec copies exactly like any other.
 
-In Measure mode, press **M** while hovering to pin that element. Then hover any other element to measure the gap or inset between the two. Press **Cmd+C** to copy the measurement. Press **Esc** to clear the pin.
+### Specs side panel
 
-### Multi-select
+Press **L** to open the Specs review panel. It lists every Spec; hover a row to scroll to and highlight its element; edit or delete notes inline. Specs survive a reload (saved to `localStorage` per URL).
 
-Press **P** while hovering an element to pick it. Numbered badges appear on each picked element. Press **Cmd+C** to copy all selected elements at once. Press **Esc** to clear the selection.
+### Copy to your AI
 
-### Annotate a change (skip the re-explaining)
+Press **Cmd+C**:
 
-Press **N** while hovering an element to attach a change note to it. A small field opens on the element — type what you want ("reduce width to 320", "tighten padding to 8px"), press **Enter** to save. The element is added to the selection and its badge shows a chip with your note. Annotate as many issues across the page as you like, then press **Cmd+C** once.
+- **With Specs marked** → copies **all** of them at once. Each block leads with your `✏️ CHANGE:` note (if any).
+- **With nothing marked** → copies the hovered element's properties (or, in Measure mode, the measurement).
 
-Each element's copied block now leads with your instruction:
+The copied format is lean and AI-ready — the current values plus a `find:` line that anchors the element in your source (test-id → id → aria-label → unique text → class → CSS path), so the assistant greps straight to the code:
 
 ```
-[Specter 1/3]
-✏️ CHANGE: reduce width to 320, tighten vertical padding
-<button>.btn-primary Button 200×48
-font: Inter 600 14/20
-padding: 12px 20px
-...
+[Specter 1/2]
+✏️ CHANGE: tighten the vertical padding to 8px
+<button> .btn-primary "Book a demo" 200×48
+find: .btn-primary
+font: Inter 600 14/20  ·  color: #fff  ·  bg: #4f46e5  ·  padding: 12px 20px  ·  radius: 10px  ·  display: inline-flex
+
+---
+
+[Specter 2/2]
+✏️ CHANGE: make this text darker — it fails contrast
+<p> .hero-sub "Analytics that…" 560×57
+find: .hero-sub
+font: Inter 400 19/28.5  ·  color: #c7cbd1
 ```
 
-So when you paste into your AI assistant, it already knows both *what* to change and *which element* — no follow-up typing. Notes are ephemeral (cleared on **Esc** or when you toggle Specter off).
+Paste into Claude, Cursor, or any AI assistant — the instructions travel with the elements, so there's nothing left to explain.
+
+## Share comments with another person
+
+Specs aren't only for your AI — you can send them to a **person**. Mark comments on a page, open the Specs panel (**L**), and click **Share**. Specter copies a link; whoever opens it — on the same page, with Specter installed — sees your comments re-anchored on the exact same elements.
+
+- **Comments only.** Only your notes and how to re-find each element travel — never the CSS properties or measurements. You're sharing feedback, not internals.
+- **Same page, same element.** Comments re-anchor by a source locator, not screen coordinates. If the page changed so an element is gone or different, that comment shows as **MISSING** in the panel (with the reason) instead of landing on the wrong spot.
+- **A link, or a file.** Small reviews copy as a normal link (`…/pricing#spx=…`) you paste into Slack or a message — the link is both the destination and the payload, so it opens the right page automatically. A large batch (or a page that uses `#`-routing) downloads a `comments.specter.json` file to send instead; use the **Import** button to open one you receive.
+- **Zero backend.** The comments travel inside the link or file itself — no accounts, no server. One-way (no threads).
+
+**Both people need Specter (v0.7+).** This is where the **browser extension** shines: it works on any deployed or staging URL, so two people looking at the same prototype can trade feedback without a shared dev server. A share link opened without Specter just shows the normal page — nothing breaks.
+
+> Specter also ships as a **browser extension** for Chrome and Firefox, which runs on *any* website (no Vite required). The Share Comments flow above is designed for it. See the [GitHub repo](https://github.com/setugk/vite-plugin-specter) for links.
 
 ## Shortcut reference
 
@@ -98,36 +131,39 @@ So when you paste into your AI assistant, it already knows both *what* to change
 |--------|----------|
 | Toggle Specter | **Ctrl+Option+Z** |
 | Inspect element | Hover (while active) |
-| Copy properties | **Cmd+C** |
-| Switch to Measure mode | **Option** (tap) |
-| Pin element for measuring | **M** (in Measure mode) |
-| Pick element (multi-select) | **P** (in Properties mode) |
-| Annotate a change | **N** (in Properties mode) |
-| Clear pin / clear selection | **Esc** |
-| Exit Specter | **Esc** (when nothing selected/pinned) |
+| Mark a Spec (+ optional note) | **P** |
+| Copy (all Specs, or hovered element) | **Cmd+C** |
+| Measure mode (toggle) | **Option** (tap) |
+| Pin / unpin for measuring | **M** (in Measure mode) |
+| Comment mode (toggle) | **C** |
+| Specs panel (toggle) | **L** |
+| Close panel / hide Specter | **Esc** |
+
+## Optional: push Specs straight to Claude Code (`/spectify`)
 
-## Workflow with AI assistants
+Instead of copy-paste, Specter can auto-sync your Specs to a local bridge that Claude Code reads on demand. Enable it in your Vite config:
+
+```ts
+specter({ claudeBridge: true })
+```
 
-1. Toggle Specter (Ctrl+Option+Z)
-2. Hover the element you want to change
-3. Either press **Cmd+C** to copy its properties, or press **N** to annotate the exact change you want first
-4. Repeat **N** on every element you want to change, then **Cmd+C** once to copy them all
-5. Paste into your AI assistant's chat — the instructions travel with the elements, so there's nothing left to explain
+With it on, every Spec you mark auto-syncs (watch for the sync dot in the panel) to a local bridge at `http://127.0.0.1:8787`. Run the bridge (`node node_modules/vite-plugin-specter/mcp-bridge/server.mjs`, or register it in your project's `.mcp.json` so your IDE launches it), then in Claude Code run **`/spectify`** — it pulls whatever's currently synced and implements it. See [`mcp-bridge/`](https://github.com/setugk/vite-plugin-specter/tree/main/mcp-bridge) for setup. One bridge can serve several projects; `/spectify <port>` scopes to one.
 
-No more "which element?", no more "what's the current value?", and now no more re-typing the change. One paste gives your assistant everything it needs.
+`claudeBridge` is **off by default** — the shipped plugin never opens a connection unless you enable it.
 
 ## Configuration
 
 ```ts
-specter()                              // Default shortcuts
-specter({ shortcuts: { activate: 'ctrl+shift+i' } }) // Custom activate shortcut
+specter()                                             // defaults
+specter({ shortcuts: { activate: 'ctrl+shift+i' } })  // custom activate shortcut
+specter({ claudeBridge: true })                       // enable the Claude Code bridge
 ```
 
 The `activate` shortcut accepts any combination of `ctrl`, `alt`, `shift`, `meta`/`cmd`, and a key. Default is `ctrl+alt+z`.
 
 ## Optional: `data-style` attribute
 
-Tag elements with `data-style="keyName"` to show the style object key in the inspector:
+Tag elements with `data-style="keyName"` to surface the style-object key in the inspector and the copied output:
 
 ```jsx
 <h1 data-style="pageTitle">Welcome</h1>