instruckt 0.4.27 → 0.4.29

package/README.md

@@ -10,15 +10,24 @@ Framework-agnostic JS core with adapters for Livewire, Vue, Svelte, and React.
 npm install instruckt
 ```
 
-Or load via CDN:
+## Quick Start
 
-```html
-<script src="https://cdn.jsdelivr.net/npm/instruckt/dist/instruckt.iife.js"></script>
-```
+> **Pick your framework below** -- each section is self-contained.
+
+| 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 |
+
+---
 
-## Quick Start: Vite Plugin
+### SPA (Vue, React, Svelte with Vite)
 
-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.
+Add the Vite plugin — it handles client injection and provides a built-in dev API server. No backend required.
 
 ```js
 // vite.config.ts
@@ -29,171 +38,59 @@ export default defineConfig({
 })
 ```
 
-That's it for SPA apps (Vue, React, Svelte with Vite). The plugin auto-injects the client via `transformIndexHtml`.
-
-### SSR Frameworks (SvelteKit, Nuxt, etc.)
-
-For frameworks that don't use `index.html`, import the virtual module in your layout:
+That's it. The plugin auto-injects the client via `transformIndexHtml`.
 
-```js
-// SvelteKit: src/routes/+layout.svelte
-import 'virtual:instruckt'
+---
 
-// Nuxt: plugins/instruckt.client.ts
-import 'virtual:instruckt'
-```
+### SvelteKit
 
-The virtual module is SSR-safe — it only initializes in the browser.
-
-### Laravel
-
-The Vite plugin works alongside the Laravel package. Set `server: false` so Laravel handles the backend:
+Two steps — add the Vite plugin, then import the virtual module in your layout:
 
 ```js
 // vite.config.ts
-import laravel from 'laravel-vite-plugin'
 import instruckt from 'instruckt/vite'
 
 export default defineConfig({
-  plugins: [
-    laravel({ input: ['resources/js/app.js'] }),
-    instruckt({
-      server: false,
-      adapters: ['livewire', 'blade'],
-      mcp: true,
-    }),
-  ],
-})
-```
-
-Then in your app entry:
-
-```js
-// resources/js/app.js
-import 'virtual:instruckt'
-```
-
-### 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,
+  plugins: [sveltekit(), instruckt()],
 })
 ```
 
-## Manual Setup
-
-If you're not using Vite, you can initialize instruckt directly:
-
-```js
-import { Instruckt } from 'instruckt'
-
-const instruckt = new Instruckt({
-  endpoint: '/instruckt',
-})
-```
-
-Or with the IIFE build:
-
-```html
-<script src="/path/to/instruckt.iife.js"></script>
+```svelte
+<!-- src/routes/+layout.svelte -->
 <script>
-  Instruckt.init({ endpoint: '/instruckt' })
+  import 'virtual:instruckt'
 </script>
 ```
 
-### Framework-Specific Manual Setup
+The virtual module is SSR-safe — it only initializes in the browser.
 
-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>
+### Nuxt
 
-```svelte
-<!-- src/lib/InstrucktProvider.svelte -->
-<script>
-  import { onMount } from 'svelte';
+Same idea — add the Vite plugin, then import the virtual module in a client plugin:
 
-  onMount(async () => {
-    const { Instruckt } = await import('instruckt');
-    const instruckt = new Instruckt({
-      endpoint: '/api/annotations',
-      adapters: ['svelte'],
-    });
+```js
+// nuxt.config.ts — add the Vite plugin
+import instruckt from 'instruckt/vite'
 
-    return () => instruckt.destroy();
-  });
-</script>
+export default defineNuxtConfig({
+  vite: {
+    plugins: [instruckt()],
+  },
+})
 ```
 
-```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
@@ -235,12 +132,78 @@ 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
 
 1. A floating toolbar appears in your app
@@ -355,7 +318,7 @@ The Vite plugin includes a dev API server that saves annotations and screenshots
 
 ### Laravel
 
-**[instruckt-laravel](https://github.com/joshcirre/instruckt-laravel)** — Laravel package with JSON file storage, MCP tools, Blade component, and API routes.
+**[instruckt-laravel](https://github.com/joshcirre/instruckt-laravel)** — Laravel package with JSON file storage, MCP tools, Blade component, and API routes. Includes `artisan instruckt:install` which auto-configures the Vite plugin, MCP, and agent skills.
 
 ### Custom Backend
 

package/dist/instruckt.cjs.js

@@ -549,7 +549,7 @@ var ICONS = {
   logo: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"/><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z"/></svg>`
 };
 var Toolbar = class {
-  constructor(position, callbacks, keys) {
+  constructor(position, callbacks, keys, tools) {
     this.position = position;
     this.callbacks = callbacks;
     this.fabBadge = null;
@@ -560,9 +560,15 @@ var Toolbar = class {
     this.dragging = false;
     this.dragOffset = { x: 0, y: 0 };
     this.keys = keys != null ? keys : {};
+    this.tools = tools != null ? tools : {};
     this.build();
     this.setupDrag();
   }
+  /** Whether a built-in tool should be shown (default true if not specified). */
+  show(id) {
+    const v = this.tools[id];
+    return v !== false;
+  }
   build() {
     var _a2, _b, _c, _d, _e;
     this.host = document.createElement("div");
@@ -621,17 +627,18 @@ var Toolbar = class {
       d.className = "divider";
       return d;
     };
-    this.toolbarEl.append(
-      this.annotateBtn,
-      screenshotBtn,
-      mkDiv(),
-      this.freezeBtn,
-      mkDiv(),
-      this.copyBtn,
-      clearWrap,
-      mkDiv(),
-      minimizeBtn
-    );
+    const toAppend = [];
+    const add = (el) => {
+      if (toAppend.length > 0) toAppend.push(mkDiv());
+      toAppend.push(el);
+    };
+    if (this.show("annotate")) add(this.annotateBtn);
+    if (this.show("screenshot")) add(screenshotBtn);
+    if (this.show("freeze")) add(this.freezeBtn);
+    if (this.show("copy")) add(this.copyBtn);
+    if (this.show("clear_page") || this.show("clear_all")) add(clearWrap);
+    if (this.show("minimize")) add(minimizeBtn);
+    this.toolbarEl.append(...toAppend);
     this.shadow.appendChild(this.toolbarEl);
     this.fab = document.createElement("button");
     this.fab.className = "fab";
@@ -2944,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";
@@ -3243,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();
@@ -3256,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"],
@@ -3305,7 +3316,7 @@ var _Instruckt = class _Instruckt {
       onClearPage: () => this.clearPage(),
       onClearAll: () => this.clearEverything(),
       onMinimize: (min) => this.onMinimize(min)
-    }, this.config.keys);
+    }, this.config.keys, this.config.tools);
     this.highlight = new ElementHighlight();
     this.popup = new AnnotationPopup();
     this.markers = new AnnotationMarkers((annotation) => this.onMarkerClick(annotation));
@@ -3344,7 +3355,7 @@ var _Instruckt = class _Instruckt {
     this.isAnnotating = false;
     this.isFrozen = false;
     document.querySelectorAll("[data-instruckt]").forEach((el) => el.remove());
-    this.toolbar = new Toolbar(this.config.position, this.makeToolbarCallbacks());
+    this.toolbar = new Toolbar(this.config.position, this.makeToolbarCallbacks(), this.config.keys, this.config.tools);
     if (wasMinimized) this.toolbar.minimize();
     this.markers = new AnnotationMarkers((annotation) => this.onMarkerClick(annotation));
     this.highlight = new ElementHighlight();
@@ -3678,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();
@@ -3694,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),
@@ -3705,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;
@@ -3908,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}\``);
         }
@@ -3929,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})`);