@akccakcctw/vue-grab 1.0.0

package/.github/release-please-config.json

@@ -0,0 +1,9 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "package-name": "@akccakcctw/vue-grab",
+      "changelog-path": "CHANGELOG.md"
+    }
+  }
+}

package/.github/release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.0"
+}

package/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: .github/release-please-config.json
+          manifest-file: .github/release-please-manifest.json
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/AGENTS.md

@@ -0,0 +1,75 @@
+# AI Agent Interaction Guide: vue-grab
+
+This document provides instructions for AI agents on how to utilize `vue-grab` to inspect and modify Vue/Nuxt applications.
+
+## 1. Overview for Agents
+
+`vue-grab` exposes a global bridge in the browser's `window` object that allows you to query the internal structure of a Vue application directly from the DOM. This is particularly useful when combined with `chrome-devtools-mcp`.
+
+Quickstart: see `README.md` for Vue/Nuxt install examples.
+
+## 2. Global API Bridge
+
+When `vue-grab` is active in a development environment, it exposes `window.__VUE_GRAB__`.
+
+### Methods
+
+| Method | Description | Parameters | Return Type |
+| :--- | :--- | :--- | :--- |
+| `grabAt(x, y)` | Get component info at viewport coordinates. | `x: number, y: number` | `ComponentInfo \| null` |
+| `grabFromSelector(selector)` | Get component info from a CSS selector. | `selector: string` | `ComponentInfo \| null` |
+| `grabFromElement(element)` | Get component info from a DOM element. | `element: Element` | `ComponentInfo \| null` |
+| `activate()` | Enable visual inspection mode (highlights on hover). | N/A | `void` |
+| `deactivate()` | Disable visual inspection mode. | N/A | `void` |
+| `highlight(selector)` | Programmatically highlight an element. | `selector: string` | `void` |
+| `enable()` | Alias for `activate()`. | N/A | `void` |
+| `disable()` | Alias for `deactivate()`. | N/A | `void` |
+| `getComponentDetails(selectorOrElement)` | Alias for grab via selector or element. | `selectorOrElement: string \| Element` | `ComponentInfo \| null` |
+| `setOverlayStyle(style)` | Update overlay styling at runtime. | `style: Record<string, string>` | `void` |
+
+### Data Structures
+
+#### `ComponentInfo`
+```json
+{
+  "name": "MyButton",
+  "file": "/Users/user/project/src/components/MyButton.vue",
+  "props": { "label": "Click Me" },
+  "data": { "count": 0 },
+  "line": 12,
+  "column": 8,
+  "vnode": { ... } // Internal Vue vnode structure
+}
+```
+
+## 3. Interaction Patterns with MCP
+
+### Scenario: Find source code for a button
+1.  **Step 1:** Use MCP's `inspect_element` or `get_dom_tree` to find the coordinates or selector of the button.
+2.  **Step 2:** Execute a JS snippet via MCP to call `vue-grab`:
+    ```javascript
+    const info = window.__VUE_GRAB__.grabFromSelector('.my-button');
+    console.log(JSON.stringify(info));
+    ```
+3.  **Step 3:** Use the returned `file` path to read the source code using your file system tools.
+
+### Scenario: Debugging State
+1.  **Step 1:** Query the component:
+    ```javascript
+    const info = window.__VUE_GRAB__.grabAt(100, 250);
+    ```
+2.  **Step 2:** Analyze `props` and `data` to understand why the UI is rendering a certain way.
+
+## 4. Nuxt Support
+In Nuxt applications, `vue-grab` is automatically injected via a Nuxt Module. The API remains identical.
+Configuration: `vueGrab` accepts `enabled`, optional `overlayStyle` (CSS style map), and `copyOnClick`.
+
+Note: `onCopy` is only supported when using the Vue plugin directly.
+
+## 5. Development Tips for Agents
+*   **Absolute Paths:** `vue-grab` provides absolute file paths in development mode, allowing you to immediately open the correct file without guessing.
+*   **Anonymous Components:** If a component doesn't have a name, `vue-grab` defaults to `AnonymousComponent`. Try to look at the `file` property to identify it.
+*   **Package Manager:** Use `pnpm` instead of `npm` for all package scripts and installs.
+*   **Types:** `VueGrabOptions`, `OverlayOptions`, and `OverlayStyle` are exported from the package.
+*   **UI:** A floating toggle button is injected in dev to enable/disable grab mode.
+*   **Hover:** Tooltip shows `file:line:column` when available.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,116 @@
+# vue-grab
+
+Developer-only bridge for inspecting Vue/Nuxt component context from the DOM.
+
+## Install
+
+```bash
+pnpm add -D vue-grab
+```
+
+## Vue Usage
+
+```ts
+import { createApp } from 'vue'
+import VueGrab from 'vue-grab'
+
+const app = createApp(App)
+
+// Use import.meta.env.DEV for Vite, or process.env.NODE_ENV === 'development' for Webpack
+if (import.meta.env.DEV) {
+  app.use(VueGrab, {
+    overlayStyle: {
+      border: '2px dashed #111'
+    },
+    onCopy(payload) {
+      console.log('vue-grab payload', payload)
+    },
+    copyOnClick: true
+  })
+}
+
+app.mount('#app')
+```
+
+## Nuxt Usage
+
+```ts
+export default defineNuxtConfig({
+  modules: ['vue-grab'],
+  vueGrab: {
+    enabled: true,
+    overlayStyle: {
+      border: '2px dashed #111'
+    },
+    copyOnClick: true
+  }
+})
+```
+
+## Browser API
+
+When active, `window.__VUE_GRAB__` exposes:
+
+- `activate()` / `deactivate()`
+- `grabAt(x, y)`
+- `grabFromSelector(selector)`
+- `grabFromElement(element)`
+- `highlight(selector)`
+- `setOverlayStyle(style)`
+- Aliases: `enable()` / `disable()` / `getComponentDetails(selectorOrElement)`
+
+A floating toggle button is injected in dev to switch grab mode on/off. Hover shows file:line:column.
+
+## MCP Example
+
+```js
+const info = window.__VUE_GRAB__.grabFromSelector('.my-button');
+console.log(JSON.stringify(info));
+```
+
+## Development
+
+For maintainers of this package (local dev + manual testing):
+
+```bash
+pnpm install
+pnpm test
+```
+
+To test in a real app, link this package into a separate Vue/Nuxt project:
+
+```bash
+# In this repo
+pnpm link --global
+
+# In your app repo
+pnpm link --global vue-grab
+```
+
+Note: `pnpm link --global vue-grab` does not update your app's `package.json` by default.
+If you want it recorded in dependencies, use one of the following in your app repo:
+
+```bash
+pnpm add -D link:vue-grab
+# or
+pnpm add -D link:/Users/rex.tsou/vbox/vue-grab
+```
+
+Then run your app and verify `window.__VUE_GRAB__` in the browser console.
+
+Cleanup when finished:
+
+```bash
+# In your app repo
+pnpm unlink --global vue-grab
+```
+
+Manual verification checklist:
+- Hover highlights appear when `activate()` is called.
+- Clicking copies metadata (or triggers `onCopy` if configured).
+- `grabFromSelector` returns component info for a known element.
+
+## Acknowledgment
+
+Special thanks to [react-grab](https://www.react-grab.com/) ([GitHub](https://github.com/aidenybai/react-grab)). This project was inspired by and references the excellent work done by the `react-grab` team. `vue-grab` aims to bring a similar developer experience to the Vue and Nuxt ecosystem.
+

package/docs/SDD.md

@@ -0,0 +1,188 @@
+# Software Design Document: vue-grab
+
+## 1. Introduction
+
+`vue-grab` is a development tool designed to bridge the gap between Vue.js applications and AI coding agents. Inspired by `react-grab`, it allows developers (and AI agents) to inspect the UI of a running Vue application and instantly retrieve context about the underlying components. This context includes the component name, file path, current props, and state.
+
+This tool is specifically designed to work with `chrome-devtools-mcp` to facilitate seamless interaction for AI agents.
+
+## 2. Goals & Requirements
+
+### 2.1 Functional Requirements
+*   **Component Inspection:** Ability to identify the Vue component associated with a specific DOM element.
+*   **Context Extraction:** Retrieve component metadata:
+    *   Component Name
+    *   Source File Path (absolute path for direct IDE opening/reading)
+    *   Line/Column numbers (if available)
+    *   Current Props
+    *   Current Data/State
+    *   VNode (if available)
+*   **Visual Feedback:** Highlight components on hover when "Grab Mode" is active.
+*   **Toggle Widget:** Provide a floating UI to toggle Grab Mode in the browser.
+*   **Hover Tooltip:** Show component file location (file:line:column) on hover.
+*   **Clipboard Integration:** Copy component details to clipboard on click.
+*   **Framework Support:**
+    *   Vue 3 (Composition & Options API)
+    *   Vue 2 (Legacy support if feasible, primarily focusing on Vue 3)
+    *   Nuxt 3 (via Nuxt Module/Plugin)
+*   **MCP Integration:** Expose a global API accessible by `chrome-devtools-mcp` (via Puppeteer/Console) to allow AI agents to programmatically "grab" or query the page.
+
+### 2.2 Non-Functional Requirements
+*   **Performance:** Minimal impact on the application performance when inactive.
+*   **Dev-Only:** Should only be active in development mode.
+*   **Zero-Config (Ideal):** Should work with standard Vite/Webpack setups out of the box.
+
+## 3. Architecture
+
+### 3.1 High-Level Overview
+`vue-grab` consists of a client-side library that injects itself into the Vue application. It listens for user interactions (hover/click) and leverages Vue's internal properties on DOM elements to traverse the component tree.
+
+### 3.2 Component Identification Strategy
+Vue applications attach internal instance data to DOM elements.
+*   **Vue 3:** Look for properties starting with `__vueParentComponent` or `__vnode` on the DOM element.
+*   **Vue 2:** Look for `__vue__` on the DOM element.
+
+### 3.3 Source Code Mapping
+Modern build tools (Vite/Webpack) inject location metadata into components during development.
+*   **`__file`**: The absolute file path of the SFC.
+*   **`__name`**: The component name.
+
+We will traverse the fiber/component tree to find the nearest component boundary for a given DOM node.
+
+### 3.4 MCP Integration
+To allow `chrome-devtools-mcp` (which uses Puppeteer) to interact with `vue-grab`, we will expose a global object on the window: `window.__VUE_GRAB__`.
+
+**Contract:**
+*   `window.__VUE_GRAB__.activate()`: Turn on inspection mode.
+*   `window.__VUE_GRAB__.deactivate()`: Turn off inspection mode.
+*   `window.__VUE_GRAB__.grabFromSelector(selector)`: Return a JSON object with component info.
+*   `window.__VUE_GRAB__.highlight(selector)`: Programmatically highlight an element.
+*   `window.__VUE_GRAB__.enable()`/`disable()` and `getComponentDetails(...)` are supported as aliases.
+
+## 4. API Design
+
+### 4.1 Global API (Window)
+```typescript
+interface VueGrabAPI {
+  // Activation
+  activate(): void;
+  deactivate(): void;
+  isActive: boolean;
+
+  // Direct Query (for AI Agents)
+  grabAt(x: number, y: number): ComponentInfo | null;
+  grabFromSelector(selector: string): ComponentInfo | null;
+  grabFromElement(element: Element): ComponentInfo | null;
+  highlight(selector: string): void;
+  setOverlayStyle(style: Record<string, string>): void;
+}
+
+Overlay options:
+- `overlayStyle`: override overlay CSS styles.
+- `onCopy`: optional callback invoked instead of clipboard copy (Vue plugin only).
+- `copyOnClick`: disable click-to-copy behavior when set to `false`.
+```
+
+### 4.2 Component Info Structure
+```typescript
+interface ComponentInfo {
+  name: string;
+  file: string; // Absolute path
+  props: Record<string, any>;
+  data: Record<string, any>;
+  element: HTMLElement; // Reference to the root DOM element
+  line?: number;
+  column?: number;
+  vnode?: any;
+}
+```
+
+## 5. Integration Modules
+
+### 5.1 Vue 3 Plugin
+A simple Vue plugin `VueGrab` that installs the global handler and sets up the event listeners.
+
+```javascript
+import { createApp } from 'vue'
+import VueGrab from 'vue-grab'
+import type { VueGrabOptions } from 'vue-grab'
+
+const vueGrabOptions: VueGrabOptions = {
+  overlayStyle: {
+    border: '2px dashed #111'
+  }
+}
+
+const app = createApp(App)
+if (process.env.NODE_ENV === 'development') {
+  app.use(VueGrab, vueGrabOptions)
+}
+app.mount('#app')
+```
+
+### 5.2 Nuxt Module
+A Nuxt module that automatically injects the plugin in development mode.
+Configuration key: `vueGrab` (example below).
+
+```ts
+export default defineNuxtConfig({
+  modules: ['vue-grab'],
+  vueGrab: {
+    enabled: true,
+    overlayStyle: {
+      border: '2px dashed #111'
+    }
+  }
+})
+```
+
+## 6. Development Plan (TDD)
+
+We will follow Test-Driven Development.
+
+1.  **Phase 1: Core Logic (Unit Tests)**
+    *   Create a dummy Vue 3 component tree in JSDOM environment.
+    *   Test `identifyComponent(domNode)`: Verify it finds the correct component instance.
+    *   Test `extractMetadata(componentInstance)`: Verify it extracts file path and name.
+
+2.  **Phase 2: Interaction (E2E/Integration)**
+    *   Implement the overlay/highlight logic.
+    *   Implement the click-to-copy logic.
+
+3.  **Phase 3: Integration**
+    *   Build the Vue Plugin.
+    *   Build the Nuxt Module.
+    *   Verify `window.__VUE_GRAB__` API.
+
+4.  **Phase 4: MCP Verification**
+    *   Simulate MCP calls to ensure the API returns data in the expected format.
+
+## 7. Quickstart
+
+### 7.1 Vue
+```ts
+import { createApp } from 'vue'
+import VueGrab from 'vue-grab'
+
+const app = createApp(App)
+if (process.env.NODE_ENV === 'development') {
+  app.use(VueGrab)
+}
+app.mount('#app')
+```
+
+### 7.2 Nuxt
+```ts
+export default defineNuxtConfig({
+  modules: ['vue-grab'],
+  vueGrab: {
+    enabled: true
+  }
+})
+```
+
+### 7.3 Browser API
+```js
+const info = window.__VUE_GRAB__.grabFromSelector('.my-button');
+console.log(JSON.stringify(info));
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@akccakcctw/vue-grab",
+  "version": "1.0.0",
+  "description": "",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./module": "./src/nuxt/module.ts"
+  },
+  "nuxt": "src/nuxt/module.ts",
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@nuxt/kit": "^4.2.2",
+    "@vitejs/plugin-vue": "^6.0.3",
+    "@vue/test-utils": "^2.4.6",
+    "jsdom": "^27.4.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17",
+    "vue": "^3.5.26"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/__tests__/plugin.spec.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import * as api from '../core/api'
+import { createVueGrabPlugin } from '../plugin'
+
+describe('Vue plugin', () => {
+  const originalWindow = globalThis.window
+
+  beforeEach(() => {
+    ;(globalThis as any).window = originalWindow || ({} as Window)
+  })
+
+  afterEach(() => {
+    ;(globalThis as any).window = originalWindow
+    vi.restoreAllMocks()
+  })
+
+  it('installs when enabled', () => {
+    const installSpy = vi.spyOn(api, 'installVueGrab').mockReturnValue({
+      activate: vi.fn(),
+      deactivate: vi.fn(),
+      isActive: false,
+      grabAt: vi.fn(),
+      grabFromSelector: vi.fn(),
+      grabFromElement: vi.fn(),
+      highlight: vi.fn(),
+      enable: vi.fn(),
+      disable: vi.fn(),
+      getComponentDetails: vi.fn(),
+      setOverlayStyle: vi.fn(),
+      setDomFileResolver: vi.fn()
+    })
+    const onCopy = vi.fn()
+
+    const plugin = createVueGrabPlugin({
+      enabled: true,
+      overlayStyle: {
+        border: '1px solid red'
+      },
+      onCopy,
+      copyOnClick: false
+    })
+    plugin.install()
+
+    expect(installSpy).toHaveBeenCalledTimes(1)
+    expect(installSpy).toHaveBeenCalledWith(window, {
+      overlayStyle: {
+        border: '1px solid red'
+      },
+      onCopy,
+      copyOnClick: false
+    })
+  })
+
+  it('skips install when disabled', () => {
+    const installSpy = vi.spyOn(api, 'installVueGrab')
+    const plugin = createVueGrabPlugin({ enabled: false })
+    plugin.install()
+    expect(installSpy).not.toHaveBeenCalled()
+  })
+})