instruckt 0.4.26 → 0.4.28

package/README.md

@@ -10,13 +10,106 @@ Framework-agnostic JS core with adapters for Livewire, Vue, Svelte, and React.
 npm install instruckt
 ```
 
-Or load via CDN:
+## Quick Start
+
+### Vite Plugin
+
+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.
 
-```html
-<script src="https://cdn.jsdelivr.net/npm/instruckt/dist/instruckt.iife.js"></script>
+```js
+// vite.config.ts
+import instruckt from 'instruckt/vite'
+
+export default defineConfig({
+  plugins: [instruckt()],
+})
 ```
 
-## Quick Start
+That's it for SPA apps (Vue, React, Svelte with Vite). 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:
+
+```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,
+    }),
+  ],
+})
+```
+
+### 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'
+```
+
+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',
+
+  // 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:
 
 ```js
 import { Instruckt } from 'instruckt'
@@ -26,15 +119,114 @@ const instruckt = new Instruckt({
 })
 ```
 
-Or with the IIFE build:
+### 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>
+```
 
-```html
-<script src="/path/to/instruckt.iife.js"></script>
+```svelte
+<!-- src/routes/+layout.svelte -->
 <script>
-  Instruckt.init({ endpoint: '/instruckt' })
+  import { browser } from '$app/environment';
+
+  let { children } = $props();
 </script>
+
+{#if browser}
+  {#await import('$lib/InstrucktProvider.svelte') then { default: InstrucktProvider }}
+    <InstrucktProvider />
+  {/await}
+{/if}
+
+{@render children()}
 ```
 
+</details>
+
+<details>
+<summary>Nuxt</summary>
+
+```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>
+
+```tsx
+// components/InstrucktProvider.tsx
+'use client'
+
+import { useEffect } from 'react'
+
+export function InstrucktProvider() {
+  useEffect(() => {
+    let instruckt: any
+
+    import('instruckt').then(({ Instruckt }) => {
+      instruckt = new Instruckt({
+        endpoint: '/api/annotations',
+        adapters: ['react'],
+      })
+    })
+
+    return () => instruckt?.destroy()
+  }, [])
+
+  return null
+}
+```
+
+```tsx
+// app/layout.tsx
+import { InstrucktProvider } from '@/components/InstrucktProvider'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <InstrucktProvider />
+      </body>
+    </html>
+  )
+}
+```
+
+</details>
+
 ## How It Works
 
 1. A floating toolbar appears in your app
@@ -56,7 +248,7 @@ Or with the IIFE build:
 - Element: `button.btn-primary` in `pages::auth.login`
 - Classes: `btn btn-primary`
 - Text: "Submit Login"
-- Screenshot: `storage/app/_instruckt/screenshots/01JWXYZ.png`
+- Screenshot: `.instruckt/screenshots/01JWXYZ.png`
 
 ## 2. Make the login card have rounded corners
 - Element: `div.bg-white` in `pages::auth.login`
@@ -67,7 +259,7 @@ Or with the IIFE build:
 
 ```js
 new Instruckt({
-  // Required — URL to your instruckt API (provided by the Laravel package or your own backend)
+  // Required — URL to your instruckt API (provided by the Vite plugin, Laravel package, or your own backend)
   endpoint: '/instruckt',
 
   // Framework adapters to activate (default: all)
@@ -94,6 +286,10 @@ new Instruckt({
     clearPage: 'x',   // clear annotations on this page
   },
 
+  // Whether MCP tools are available (default: false)
+  // Set to true when using with Laravel or another backend that registers MCP tools
+  mcp: false,
+
   // Callbacks
   onAnnotationAdd: (annotation) => {},
 })
@@ -118,7 +314,7 @@ Default shortcuts (customizable via `keys` config):
 - **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
 - **Freeze mode** — pause animations, freeze popovers/dropdowns, and block all navigation
-- **Annotation persistence** — annotations survive page reloads and Vite rebuilds via localStorage fallback; with a backend (Laravel), annotations are loaded from the API on init
+- **Annotation persistence** — annotations survive page reloads via localStorage; with a backend (Vite plugin or Laravel), annotations are stored on disk as JSON
 - **Minimize** — collapse to a small floating button with annotation count badge
 - **Page-scoped markers** — annotation pins reposition on scroll/resize and only appear on the page where they were created
 - **Clear controls** — clear current page (`X` key or trash icon), or clear all pages via flyout
@@ -139,9 +335,23 @@ instruckt.destroy()
 
 ## Backend
 
-instruckt needs a backend to persist annotations. The official Laravel package provides this out of the box:
+### Vite Plugin (Built-in)
+
+The Vite plugin includes a dev API server that saves annotations and screenshots to disk (`.instruckt/` directory). No external backend needed. Screenshots are saved as files instead of base64, keeping clipboard markdown small.
+
+### 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
+
+instruckt expects these endpoints:
+
+```
+GET    {endpoint}/annotations         → list annotations
+POST   {endpoint}/annotations         → create annotation
+PATCH  {endpoint}/annotations/{id}    → update annotation
+```
 
 ## License
 

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";
@@ -3185,6 +3192,7 @@ var _Instruckt = class _Instruckt {
     this.highlightLocked = false;
     this.pollTimer = null;
     this.initialLoadDone = false;
+    this.hasBackend = false;
     this.boundReposition = () => {
       var _a2;
       (_a2 = this.markers) == null ? void 0 : _a2.reposition(this.annotations);
@@ -3304,7 +3312,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));
@@ -3343,7 +3351,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();
@@ -3368,29 +3376,97 @@ var _Instruckt = class _Instruckt {
       (_e = this.markers) == null ? void 0 : _e.setVisible(true);
     }
   }
+  // ── Persistence ─────────────────────────────────────────────────
+  static get STORAGE_KEY() {
+    return `instruckt:${window.location.origin}:annotations`;
+  }
   async loadAnnotations() {
     this.loadFromStorage();
     try {
       const remote = await this.api.getAnnotations();
+      this.hasBackend = true;
       const remoteIds = new Set(remote.map((a) => a.id));
       const localOnly = this.annotations.filter((a) => !remoteIds.has(a.id));
       this.annotations = [...remote, ...localOnly];
       this.saveToStorage();
     } catch (e) {
+      this.hasBackend = false;
     }
     this.initialLoadDone = true;
     this.syncMarkers();
   }
   saveToStorage() {
     try {
-      localStorage.setItem(_Instruckt.STORAGE_KEY, JSON.stringify(this.annotations));
+      const screenshotMap = /* @__PURE__ */ new Map();
+      const stripped = this.annotations.map((a) => {
+        var _a2;
+        if ((_a2 = a.screenshot) == null ? void 0 : _a2.startsWith("data:")) {
+          screenshotMap.set(a.id, a.screenshot);
+          return __spreadProps(__spreadValues({}, a), { screenshot: `idb:${a.id}` });
+        }
+        return a;
+      });
+      localStorage.setItem(_Instruckt.STORAGE_KEY, JSON.stringify(stripped));
+      if (screenshotMap.size > 0) this.saveScreenshotsToIdb(screenshotMap);
     } catch (e) {
     }
   }
   loadFromStorage() {
     try {
       const raw = localStorage.getItem(_Instruckt.STORAGE_KEY);
-      if (raw) this.annotations = JSON.parse(raw);
+      if (raw) {
+        this.annotations = JSON.parse(raw);
+        const idbRefs = this.annotations.filter((a) => {
+          var _a2;
+          return (_a2 = a.screenshot) == null ? void 0 : _a2.startsWith("idb:");
+        });
+        if (idbRefs.length > 0) this.loadScreenshotsFromIdb(idbRefs);
+      }
+    } catch (e) {
+    }
+  }
+  openIdb() {
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open(_Instruckt.IDB_NAME, 1);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains(_Instruckt.IDB_STORE)) {
+          db.createObjectStore(_Instruckt.IDB_STORE);
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+  async saveScreenshotsToIdb(screenshots) {
+    try {
+      const db = await this.openIdb();
+      const tx = db.transaction(_Instruckt.IDB_STORE, "readwrite");
+      const store = tx.objectStore(_Instruckt.IDB_STORE);
+      for (const [id, dataUri] of screenshots) {
+        store.put(dataUri, id);
+      }
+      db.close();
+    } catch (e) {
+    }
+  }
+  async loadScreenshotsFromIdb(annotations) {
+    try {
+      const db = await this.openIdb();
+      const tx = db.transaction(_Instruckt.IDB_STORE, "readonly");
+      const store = tx.objectStore(_Instruckt.IDB_STORE);
+      for (const a of annotations) {
+        const id = a.screenshot.replace("idb:", "");
+        const req = store.get(id);
+        req.onsuccess = () => {
+          if (req.result) a.screenshot = req.result;
+        };
+      }
+      await new Promise((resolve) => {
+        tx.oncomplete = () => resolve();
+      });
+      db.close();
+      this.syncMarkers();
     } catch (e) {
     }
   }
@@ -3863,19 +3939,21 @@ No open annotations.`;
             const screenshotPath = (_e = this.config.screenshotPath) != null ? _e : "storage/app/_instruckt/";
             lines.push(`- Screenshot: \`${screenshotPath}${a.screenshot}\``);
           } else {
-            lines.push(`- Screenshot: attached`);
+            lines.push(`- Screenshot: ![Screenshot](${a.screenshot})`);
           }
         }
         lines.push("");
       });
     }
-    const hasScreenshots = pending.some((a) => a.screenshot && !a.screenshot.startsWith("data:"));
-    lines.push("---");
-    lines.push("");
-    if (hasScreenshots) {
-      lines.push("Use the `instruckt.get_screenshot` MCP tool to view screenshots. After making changes, use `instruckt.resolve` to mark each annotation as resolved.");
-    } else {
-      lines.push("After making changes, use the `instruckt.resolve` MCP tool to mark each annotation as resolved.");
+    if (this.config.mcp) {
+      const hasScreenshots = pending.some((a) => a.screenshot && !a.screenshot.startsWith("data:"));
+      lines.push("---");
+      lines.push("");
+      if (hasScreenshots) {
+        lines.push("Use the `instruckt.get_screenshot` MCP tool to view screenshots. After making changes, use `instruckt.resolve` to mark each annotation as resolved.");
+      } else {
+        lines.push("After making changes, use the `instruckt.resolve` MCP tool to mark each annotation as resolved.");
+      }
     }
     return lines.join("\n").trim();
   }
@@ -3898,8 +3976,8 @@ No open annotations.`;
     if (this.pollTimer !== null) clearInterval(this.pollTimer);
   }
 };
-// ── Persistence ─────────────────────────────────────────────────
-_Instruckt.STORAGE_KEY = `instruckt:${window.location.origin}:annotations`;
+_Instruckt.IDB_NAME = "instruckt";
+_Instruckt.IDB_STORE = "screenshots";
 var Instruckt = _Instruckt;
 
 // src/index.ts