instruckt 0.4.28 → 0.4.30

package/README.md

@@ -12,9 +12,22 @@ npm install instruckt
 
 ## Quick Start
 
-### Vite Plugin
+> **Pick your framework below** -- each section is self-contained.
 
-The easiest way to use instruckt is with the Vite plugin. It handles client injection and provides a built-in dev API server — no backend required.
+| Framework | Setup |
+|-----------|-------|
+| [SPA (Vue, React, Svelte)](#spa-vue-react-svelte-with-vite) | Vite plugin only |
+| [SvelteKit](#sveltekit) | Vite plugin + virtual import |
+| [Nuxt](#nuxt) | Vite plugin + virtual import |
+| [Next.js](#nextjs) | Client component |
+| [Laravel](#laravel) | Composer package |
+| [Astro](#astro) | Community integration |
+
+---
+
+### SPA (Vue, React, Svelte with Vite)
+
+Add the Vite plugin — it handles client injection and provides a built-in dev API server. No backend required.
 
 ```js
 // vite.config.ts
@@ -25,165 +38,59 @@ export default defineConfig({
 })
 ```
 
-That's it for SPA apps (Vue, React, Svelte with Vite). The plugin auto-injects the client via `transformIndexHtml`.
+That's it. The plugin auto-injects the client via `transformIndexHtml`.
 
-### Laravel
+---
 
-Use the **[instruckt-laravel](https://github.com/joshcirre/instruckt-laravel)** package — it provides the backend API, MCP tools, JSON file storage, and handles install/uninstall automatically:
+### SvelteKit
 
-```bash
-composer require joshcirre/instruckt-laravel --dev
-php artisan instruckt:install
-```
-
-The install command adds the Vite plugin to your `vite.config.js` with `server: false` (Laravel owns the backend), configures MCP for your AI agent, and adds the virtual import to your JS entry point.
+Two steps — add the Vite plugin, then import the virtual module in your layout:
 
 ```js
-// vite.config.js (added automatically by install command)
+// vite.config.ts
 import instruckt from 'instruckt/vite'
 
 export default defineConfig({
-  plugins: [
-    laravel({ input: ['resources/js/app.js'] }),
-    instruckt({
-      server: false,
-      adapters: ['livewire', 'blade'],
-      mcp: true,
-    }),
-  ],
+  plugins: [sveltekit(), instruckt()],
 })
 ```
 
-### SSR Frameworks (SvelteKit, Nuxt, etc.)
-
-For frameworks that don't use `index.html`, import the virtual module in your layout:
-
-```js
-// SvelteKit: src/routes/+layout.svelte
-import 'virtual:instruckt'
-
-// Nuxt: plugins/instruckt.client.ts
-import 'virtual:instruckt'
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import 'virtual:instruckt'
+</script>
 ```
 
 The virtual module is SSR-safe — it only initializes in the browser.
 
-### Astro
-
-See **[instruckt-astro](https://github.com/sgasser/instruckt-astro)** for a community-maintained Astro integration.
-
-## Vite Plugin Options
-
-```js
-instruckt({
-  // Framework adapters to activate (default: auto-detect)
-  adapters: ['svelte'],
-
-  // Theme: 'light' | 'dark' | 'auto' (default: 'auto')
-  theme: 'auto',
+---
 
-  // Toolbar position (default: 'bottom-right')
-  position: 'bottom-right',
+### Nuxt
 
-  // Customize marker pin colors
-  colors: { default: '#6366f1', screenshot: '#22c55e', dismissed: '#71717a' },
-
-  // Customize keyboard shortcuts
-  keys: { annotate: 'a', freeze: 'f', screenshot: 'c', clearPage: 'x' },
-
-  // Storage directory for annotations + screenshots (default: '.instruckt')
-  dir: '.instruckt',
-
-  // API endpoint prefix (default: '/instruckt')
-  endpoint: '/instruckt',
-
-  // Enable built-in dev API server (default: true)
-  // Set to false when your framework provides its own backend (e.g. Laravel)
-  server: true,
-
-  // Show MCP tool instructions in clipboard markdown (default: false)
-  // Set to true when using with a backend that registers MCP tools
-  mcp: false,
-})
-```
-
-## Manual Setup
-
-If you're not using Vite, you can initialize instruckt directly:
+Same idea — add the Vite plugin, then import the virtual module in a client plugin:
 
 ```js
-import { Instruckt } from 'instruckt'
+// nuxt.config.ts — add the Vite plugin
+import instruckt from 'instruckt/vite'
 
-const instruckt = new Instruckt({
-  endpoint: '/instruckt',
+export default defineNuxtConfig({
+  vite: {
+    plugins: [instruckt()],
+  },
 })
 ```
 
-### Framework-Specific Manual Setup
-
-instruckt is a browser-only library. In SSR frameworks without the Vite plugin, make sure it only loads on the client.
-
-<details>
-<summary>SvelteKit</summary>
-
-```svelte
-<!-- src/lib/InstrucktProvider.svelte -->
-<script>
-  import { onMount } from 'svelte';
-
-  onMount(async () => {
-    const { Instruckt } = await import('instruckt');
-    const instruckt = new Instruckt({
-      endpoint: '/api/annotations',
-      adapters: ['svelte'],
-    });
-
-    return () => instruckt.destroy();
-  });
-</script>
-```
-
-```svelte
-<!-- src/routes/+layout.svelte -->
-<script>
-  import { browser } from '$app/environment';
-
-  let { children } = $props();
-</script>
-
-{#if browser}
-  {#await import('$lib/InstrucktProvider.svelte') then { default: InstrucktProvider }}
-    <InstrucktProvider />
-  {/await}
-{/if}
-
-{@render children()}
+```ts
+// plugins/instruckt.client.ts
+import 'virtual:instruckt'
 ```
 
-</details>
+---
 
-<details>
-<summary>Nuxt</summary>
+### Next.js
 
-```vue
-<!-- plugins/instruckt.client.ts -->
-<script>
-// The .client.ts suffix ensures Nuxt only runs this in the browser
-export default defineNuxtPlugin(async () => {
-  const { Instruckt } = await import('instruckt')
-
-  const instruckt = new Instruckt({
-    endpoint: '/api/annotations',
-    adapters: ['vue'],
-  })
-})
-</script>
-```
-
-</details>
-
-<details>
-<summary>Next.js (App Router)</summary>
+Next.js doesn't use Vite, so initialize instruckt directly in a client component:
 
 ```tsx
 // components/InstrucktProvider.tsx
@@ -225,7 +132,77 @@ export default function RootLayout({ children }) {
 }
 ```
 
-</details>
+---
+
+### Laravel
+
+Use the **[instruckt-laravel](https://github.com/joshcirre/instruckt-laravel)** package — it provides the backend API, MCP tools, JSON file storage, and handles install/uninstall automatically:
+
+```bash
+composer require joshcirre/instruckt-laravel --dev
+php artisan instruckt:install
+```
+
+The install command adds the Vite plugin to your `vite.config.js` with `server: false` (Laravel owns the backend), configures MCP for your AI agent, and adds the virtual import to your JS entry point.
+
+```js
+// vite.config.js (added automatically by install command)
+import instruckt from 'instruckt/vite'
+
+export default defineConfig({
+  plugins: [
+    laravel({ input: ['resources/js/app.js'] }),
+    instruckt({
+      server: false,
+      adapters: ['livewire', 'blade'],
+      mcp: true,
+    }),
+  ],
+})
+```
+
+---
+
+### Astro
+
+See **[instruckt-astro](https://github.com/sgasser/instruckt-astro)** for a community-maintained Astro integration.
+
+---
+
+## Vite Plugin Options
+
+```js
+instruckt({
+  // Framework adapters to activate (default: auto-detect)
+  adapters: ['svelte'],
+
+  // Theme: 'light' | 'dark' | 'auto' (default: 'auto')
+  theme: 'auto',
+
+  // Toolbar position (default: 'bottom-right')
+  position: 'bottom-right',
+
+  // Customize marker pin colors
+  colors: { default: '#6366f1', screenshot: '#22c55e', dismissed: '#71717a' },
+
+  // Customize keyboard shortcuts
+  keys: { annotate: 'a', freeze: 'f', screenshot: 'c', clearPage: 'x' },
+
+  // Storage directory for annotations + screenshots (default: '.instruckt')
+  dir: '.instruckt',
+
+  // API endpoint prefix (default: '/instruckt')
+  endpoint: '/instruckt',
+
+  // Enable built-in dev API server (default: true)
+  // Set to false when your framework provides its own backend (e.g. Laravel)
+  server: true,
+
+  // Show MCP tool instructions in clipboard markdown (default: false)
+  // Set to true when using with a backend that registers MCP tools
+  mcp: false,
+})
+```
 
 ## How It Works
 
@@ -242,16 +219,22 @@ export default function RootLayout({ children }) {
 ### Example Output
 
 ```markdown
-# UI Feedback: /auth/login
+# UI Feedback: /dashboard
 
 ## 1. Change the submit button color to green
-- Element: `button.btn-primary` in `pages::auth.login`
+- Element: `button.btn-primary` in `LoginForm`
+- Source: `src/components/LoginForm.tsx:42:5`
+- Component stack:
+  - LoginForm `src/components/LoginForm.tsx:42:5`
+  - AuthPage `src/pages/AuthPage.tsx:18:3`
+  - App `src/App.tsx:8:7`
 - Classes: `btn btn-primary`
 - Text: "Submit Login"
 - Screenshot: `.instruckt/screenshots/01JWXYZ.png`
 
 ## 2. Make the login card have rounded corners
-- Element: `div.bg-white` in `pages::auth.login`
+- Element: `div.bg-white` in `LoginCard`
+- Source: `src/components/LoginCard.tsx:15:3`
 - Classes: `bg-white dark:bg-white/10 border`
 ```
 
@@ -309,7 +292,7 @@ Default shortcuts (customizable via `keys` config):
 
 ## Features
 
-- **Framework detection** — automatically identifies Livewire, Vue, Svelte, and React components
+- **Framework detection** — automatically identifies Livewire, Vue, Svelte, and React components with full component stacks and precise source locations (file:line:column) via [element-source](https://github.com/aidenybai/element-source)
 - **Screenshots** — capture element or region screenshots; uses DOM-to-image on standard apps, automatically falls back to Screen Capture API on shadow DOM frameworks (Flux UI, etc.)
 - **Shadow DOM isolation** — all UI renders in shadow roots so it never conflicts with your styles
 - **Copy as markdown** — annotations auto-copy as structured markdown optimized for AI agents

package/dist/instruckt.cjs.js

@@ -2951,6 +2951,9 @@ function getPageBoundingBox(el) {
   };
 }
 
+// src/instruckt.ts
+var import_element_source = require("element-source");
+
 // src/adapters/livewire.ts
 function isAvailable() {
   return typeof window.Livewire !== "undefined";
@@ -3250,7 +3253,7 @@ var _Instruckt = class _Instruckt {
       e.stopImmediatePropagation();
     };
     this.boundClick = (e) => {
-      var _a2, _b, _c;
+      var _a2, _b;
       const target = e.target;
       if (this.isInstruckt(target)) return;
       e.preventDefault();
@@ -3263,23 +3266,24 @@ var _Instruckt = class _Instruckt {
       const cssClasses = getCssClasses(target);
       const nearbyText = getNearbyText(target) || void 0;
       const boundingBox = getPageBoundingBox(target);
-      const framework = (_b = this.detectFramework(target)) != null ? _b : void 0;
-      (_c = this.highlight) == null ? void 0 : _c.show(target);
+      (_b = this.highlight) == null ? void 0 : _b.show(target);
       this.highlightLocked = true;
-      const pending = {
-        element: target,
-        elementPath,
-        elementName,
-        elementLabel,
-        cssClasses,
-        boundingBox,
-        x: e.clientX,
-        y: e.clientY,
-        selectedText,
-        nearbyText,
-        framework
-      };
-      this.showAnnotationPopup(pending);
+      this.detectFramework(target).then((framework) => {
+        const pending = {
+          element: target,
+          elementPath,
+          elementName,
+          elementLabel,
+          cssClasses,
+          boundingBox,
+          x: e.clientX,
+          y: e.clientY,
+          selectedText,
+          nearbyText,
+          framework: framework != null ? framework : void 0
+        };
+        this.showAnnotationPopup(pending);
+      });
     };
     this.config = __spreadValues({
       adapters: ["livewire", "vue", "svelte", "react", "blade"],
@@ -3685,7 +3689,7 @@ var _Instruckt = class _Instruckt {
   }
   // ── Region screenshot ────────────────────────────────────────
   async startRegionCapture() {
-    var _a2, _b;
+    var _a2;
     const wasAnnotating = this.isAnnotating;
     if (wasAnnotating) this.setAnnotating(false);
     const rect = await selectRegion();
@@ -3701,6 +3705,7 @@ var _Instruckt = class _Instruckt {
     const centerX = rect.x + rect.width / 2;
     const centerY = rect.y + rect.height / 2;
     const target = (_a2 = document.elementFromPoint(centerX, centerY)) != null ? _a2 : document.body;
+    const framework = await this.detectFramework(target);
     const pending = {
       element: target,
       elementPath: getElementSelector(target),
@@ -3712,18 +3717,60 @@ var _Instruckt = class _Instruckt {
       y: centerY,
       nearbyText: getNearbyText(target) || void 0,
       screenshot,
-      framework: (_b = this.detectFramework(target)) != null ? _b : void 0
+      framework: framework != null ? framework : void 0
     };
     this.showAnnotationPopup(pending);
   }
   // ── Framework detection ───────────────────────────────────────
-  detectFramework(el) {
-    var _a2;
+  /**
+   * Use element-source as the primary resolver for React/Vue/Svelte,
+   * then layer our adapters on top for props/state/framework-specific metadata.
+   * Livewire and Blade are handled by our adapters only (element-source doesn't support them).
+   */
+  async detectFramework(el) {
+    var _a2, _b, _c, _d, _e, _f, _g;
     const adapters = (_a2 = this.config.adapters) != null ? _a2 : [];
     if (adapters.includes("livewire")) {
       const ctx = getContext(el);
       if (ctx) return ctx;
     }
+    const esAdapters = ["vue", "svelte", "react"];
+    if (esAdapters.some((a) => adapters.includes(a))) {
+      try {
+        const info = await (0, import_element_source.resolveElementInfo)(el);
+        if (info.source) {
+          const stack = info.stack.map((f) => ({
+            filePath: f.filePath,
+            lineNumber: f.lineNumber,
+            columnNumber: f.columnNumber,
+            componentName: f.componentName
+          }));
+          let adapterCtx = null;
+          if (adapters.includes("vue")) adapterCtx = getContext2(el);
+          if (!adapterCtx && adapters.includes("svelte")) adapterCtx = getContext3(el);
+          if (!adapterCtx && adapters.includes("react")) adapterCtx = getContext4(el);
+          if (adapterCtx) {
+            return __spreadProps(__spreadValues({}, adapterCtx), {
+              component: (_b = info.componentName) != null ? _b : adapterCtx.component,
+              source_file: info.source.filePath,
+              source_line: (_c = info.source.lineNumber) != null ? _c : adapterCtx.source_line,
+              source_column: (_d = info.source.columnNumber) != null ? _d : void 0,
+              component_stack: stack.length > 0 ? stack : void 0
+            });
+          }
+          return {
+            framework: "react",
+            // element-source defaults to React resolver
+            component: (_e = info.componentName) != null ? _e : "Component",
+            source_file: info.source.filePath,
+            source_line: (_f = info.source.lineNumber) != null ? _f : void 0,
+            source_column: (_g = info.source.columnNumber) != null ? _g : void 0,
+            component_stack: stack.length > 0 ? stack : void 0
+          };
+        }
+      } catch (e) {
+      }
+    }
     if (adapters.includes("vue")) {
       const ctx = getContext2(el);
       if (ctx) return ctx;
@@ -3915,17 +3962,33 @@ No open annotations.`;
       lines.push("");
       const hPrefix = multiPage ? "###" : "##";
       annotations.forEach((a, i) => {
-        var _a2, _b, _c, _d, _e;
+        var _a2, _b, _c, _d, _e, _f;
         const componentSuffix = ((_a2 = a.framework) == null ? void 0 : _a2.component) ? ` in \`${a.framework.component}\`` : "";
         lines.push(`${hPrefix} ${i + 1}. ${a.comment}`);
         lines.push(`- ID: \`${a.id}\``);
         lines.push(`- Element: \`${a.element}\`${componentSuffix}`);
         if ((_b = a.framework) == null ? void 0 : _b.source_file) {
-          const loc = a.framework.source_line ? `${a.framework.source_file}:${a.framework.source_line}` : a.framework.source_file;
+          let loc = a.framework.source_file;
+          if (a.framework.source_line) {
+            loc += `:${a.framework.source_line}`;
+            if (a.framework.source_column) loc += `:${a.framework.source_column}`;
+          }
           lines.push(`- Source: \`${loc}\``);
         } else if ((_d = (_c = a.framework) == null ? void 0 : _c.data) == null ? void 0 : _d.file) {
           lines.push(`- File: \`${a.framework.data.file}\``);
         }
+        if (((_e = a.framework) == null ? void 0 : _e.component_stack) && a.framework.component_stack.length > 1) {
+          lines.push(`- Component stack:`);
+          for (const frame of a.framework.component_stack) {
+            let frameLoc = frame.filePath;
+            if (frame.lineNumber) {
+              frameLoc += `:${frame.lineNumber}`;
+              if (frame.columnNumber) frameLoc += `:${frame.columnNumber}`;
+            }
+            const name = frame.componentName ? `${frame.componentName} ` : "";
+            lines.push(`  - ${name}\`${frameLoc}\``);
+          }
+        }
         if (a.cssClasses) {
           lines.push(`- Classes: \`${a.cssClasses}\``);
         }
@@ -3936,7 +3999,7 @@ No open annotations.`;
         }
         if (a.screenshot) {
           if (!a.screenshot.startsWith("data:")) {
-            const screenshotPath = (_e = this.config.screenshotPath) != null ? _e : "storage/app/_instruckt/";
+            const screenshotPath = (_f = this.config.screenshotPath) != null ? _f : "storage/app/_instruckt/";
             lines.push(`- Screenshot: \`${screenshotPath}${a.screenshot}\``);
           } else {
             lines.push(`- Screenshot: ![Screenshot](${a.screenshot})`);