@visulima/dev-toolbar 1.0.0-alpha.5 → 1.0.0-alpha.7

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+## @visulima/dev-toolbar [1.0.0-alpha.7](https://github.com/visulima/visulima/compare/@visulima/dev-toolbar@1.0.0-alpha.6...@visulima/dev-toolbar@1.0.0-alpha.7) (2026-03-26)
+
+### Features
+
+* **web:** auto-generate packages page from workspace metadata ([623e520](https://github.com/visulima/visulima/commit/623e5207693a7fe720f5f2f179593a3654c880e3))
+
+## @visulima/dev-toolbar [1.0.0-alpha.6](https://github.com/visulima/visulima/compare/@visulima/dev-toolbar@1.0.0-alpha.5...@visulima/dev-toolbar@1.0.0-alpha.6) (2026-03-26)
+
+### Features
+
+* **dev-toolbar:** add accessibility info capture to inspector ([2b98ee6](https://github.com/visulima/visulima/commit/2b98ee6249759d1d2c42504354ebf3a92db4a6e6))
+* **dev-toolbar:** add custom Select component replacing native <select> ([c9c8685](https://github.com/visulima/visulima/commit/c9c8685ea3a05c28ea89d5f5d852d56bc8cbcad0))
+* **dev-toolbar:** add viewport rulers with draggable guidelines to inspector ([9df079a](https://github.com/visulima/visulima/commit/9df079a83563b1afc617d76df78259082ea98817))
+* **dev-toolbar:** add visual annotation system with MCP agent integration ([be88cfe](https://github.com/visulima/visulima/commit/be88cfe30f3f624075167762e9c9780653dd34e9))
+* **dev-toolbar:** redesign annotation popups, add toast notifications, improve docs ([cca080f](https://github.com/visulima/visulima/commit/cca080fc6098a692e681ee5b140f8c5c3a810a2c))
+
+### Bug Fixes
+
+* **api-platform:** use workspace:* for internal [@visulima](https://github.com/visulima) deps ([daa2b0b](https://github.com/visulima/visulima/commit/daa2b0bfb491b42bc83c369fec2dcd7950f082b0))
+* **dev-toolbar:** address code review findings across toolbar components ([449a300](https://github.com/visulima/visulima/commit/449a300226e4ccaee52ad258d5eccf6f77a72343))
+* **dev-toolbar:** align inspector floating badge with main toolbar styling ([8ea1814](https://github.com/visulima/visulima/commit/8ea1814b596126b71231fd124c036f1e450275ef))
+* **dev-toolbar:** audit Select component, add tests, fix pre-existing type error ([c8452d3](https://github.com/visulima/visulima/commit/c8452d3b495e9707579490155e6689c40cff9568))
+* **dev-toolbar:** auto-detect TanStack Start and shield Preact from React Compiler ([6e9fa57](https://github.com/visulima/visulima/commit/6e9fa571ded1ff53d8809cee47fb404897320e9f))
+* **dev-toolbar:** fix coordinate bugs, orphaned elements, and doc inaccuracies ([efa9c54](https://github.com/visulima/visulima/commit/efa9c544c9a8591c6efe6fd4a9995b411c054f54))
+* **dev-toolbar:** open inspector popup at click point and add visible drag handle ([c012aed](https://github.com/visulima/visulima/commit/c012aed47eeabf2047d5a7a7e46cab807de902f3))
+* **dev-toolbar:** prevent querySelector crash on area selection element paths ([ecd64d4](https://github.com/visulima/visulima/commit/ecd64d4b418e74cc582da0cd5efdb9f5e8e95d2b))
+* **dev-toolbar:** resolve all TypeScript, ESLint, and Prettier errors in annotation system ([2fae465](https://github.com/visulima/visulima/commit/2fae4658017d61262293a41bef13348bbfc70e41))
+* **dev-toolbar:** use correct ARIA role in select search tests ([2e1ddfe](https://github.com/visulima/visulima/commit/2e1ddfed1b49697a2d772c5a6b61bf3b6538a43b))
+* **dev-toolbar:** use workspace:* for internal [@visulima](https://github.com/visulima) deps ([26ea008](https://github.com/visulima/visulima/commit/26ea00878218a34f89587fb9a2157cb379e98733))
+* **web:** improve build setup with incremental stats caching and prod install ([fe33e75](https://github.com/visulima/visulima/commit/fe33e75827586779b4b3a0c6d57b39f889ee6207))
+
+### Documentation
+
+* **dev-toolbar:** update examples to use native Vite 8 resolve.tsconfigPaths ([d54d3f7](https://github.com/visulima/visulima/commit/d54d3f71714fc600e4b965e1ab2bdbe0cc442ba6))
+
+### Miscellaneous Chores
+
+* **dev-toolbar:** migrate deps to pnpm catalogs ([a43badc](https://github.com/visulima/visulima/commit/a43badcc8cd19d9c3c9cda4b2d75e272d76d51c8))
+* **dev-toolbar:** update dependencies ([8cac2a2](https://github.com/visulima/visulima/commit/8cac2a2068d902ee8196f8e1f50d658644be7e70))
+* update gen file ([8794258](https://github.com/visulima/visulima/commit/87942584bc22cab96a14094d2ec46ec667179490))
+* visulima website ([#591](https://github.com/visulima/visulima/issues/591)) ([59ab2e2](https://github.com/visulima/visulima/commit/59ab2e2befb03e51cd2088956f83d9b87de6d033))
+
+### Code Refactoring
+
+* **dev-toolbar:** use native Vite 8 tsconfigPaths in cloudflare example ([fb15d1d](https://github.com/visulima/visulima/commit/fb15d1df62040853a36e7926382765e902380d3a))
+* **dev-toolbar:** use native Vite 8 tsconfigPaths in tanstack-start example ([d89aef7](https://github.com/visulima/visulima/commit/d89aef7c2ba4a8443897d3f7cb9ada494d38d2c4))
+* **docs:** migrate Nextra components to fumadocs-ui, remove Nextra stripping ([484878f](https://github.com/visulima/visulima/commit/484878f01879363ef5e9a0282904dc4627d6060c))
+
 ## @visulima/dev-toolbar [1.0.0-alpha.5](https://github.com/visulima/visulima/compare/@visulima/dev-toolbar@1.0.0-alpha.4...@visulima/dev-toolbar@1.0.0-alpha.5) (2026-03-06)
 
 ### Features

package/bin/mcp.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * MCP server for @visulima/dev-toolbar annotations.
+ *
+ * Usage:
+ *   npx visulima-dev-toolbar-mcp
+ *
+ * Configure in .mcp.json:
+ *   {
+ *     "mcpServers": {
+ *       "dev-toolbar": {
+ *         "command": "npx",
+ *         "args": ["visulima-dev-toolbar-mcp"],
+ *         "cwd": "/absolute/path/to/project"
+ *       }
+ *     }
+ *   }
+ *
+ * Requires @modelcontextprotocol/sdk to be installed.
+ */
+
+// eslint-disable-next-line antfu/no-import-dist -- bin entry point runs after build
+import { startMcpServer } from "../dist/mcp/server.js";
+
+startMcpServer().catch((error) => {
+    console.error("Failed to start MCP server:", error);
+    process.exit(1);
+});

package/dist/apps/annotations/annotations-app.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentChildren } from "preact";
+import type { AppComponentProps } from "../../types/app.d.ts";
+declare const AnnotationsApp: ({ helpers }: AppComponentProps) => ComponentChildren;
+export default AnnotationsApp;

package/dist/apps/annotations/index.d.ts

@@ -0,0 +1,3 @@
+import type { DevToolbarApp } from "../../types/app.d.ts";
+declare const annotationsApp: DevToolbarApp;
+export default annotationsApp;

package/dist/apps/annotations/index.js

@@ -0,0 +1,18 @@
+var j=Object.defineProperty;var z=(t,s)=>j(t,"name",{value:s,configurable:!0});import{addHookName as c}from"preact/devtools";import{clsx as h}from"../../packem_shared/clsx-wGlvpUfw.js";import{useState as p,useCallback as S,useEffect as q}from"preact/hooks";import{s as Q,M as H,l as K}from"../../packem_shared/annotation-settings-DOyUbJ_T.js";import{jsx as e,jsxs as r}from"preact/jsx-runtime";import g from"../../packem_shared/Button-Bkx66Co7.js";import U from"../../packem_shared/Textarea-Yfg3dLZi.js";const V=`<!-- @license lucide-static v0.577.0 - ISC -->
+<svg
+  class="lucide lucide-message-square-plus"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z" />
+  <path d="M12 8v6" />
+  <path d="M9 11h6" />
+</svg>
+`;var G=Object.defineProperty,a=z((t,s)=>G(t,"name",{value:s,configurable:!0}),"o");const I={approve:"Approve",change:"Change",fix:"Fix",question:"Question"},M={approve:"bg-green-500/20 text-green-400 border-green-500/30",change:"bg-yellow-500/20 text-yellow-400 border-yellow-500/30",fix:"bg-destructive/20 text-destructive border-destructive/30",question:"bg-blue-500/20 text-blue-400 border-blue-500/30"},F={blocking:"Blocking",important:"Important",suggestion:"Suggestion"},$={blocking:"text-destructive",important:"text-warning-foreground",suggestion:"text-muted-foreground"},A={acknowledged:"Acknowledged",dismissed:"Dismissed",pending:"Pending",resolved:"Resolved"},Y=a(({active:t,counts:s,onFilter:i})=>e("div",{class:"flex gap-1.5",children:["all","pending","acknowledged","resolved","dismissed"].map(n=>r("button",{class:h("px-2.5 py-1 text-[0.65rem] font-medium border cursor-pointer transition-colors",t===n?"bg-primary/10 border-primary/30 text-primary":"bg-foreground/3 border-border text-muted-foreground hover:bg-foreground/6"),onClick:a(()=>i(n),"onClick"),type:"button",children:[n==="all"?"All":A[n]," (",s[n],")"]},n))}),"StatusFilters"),_=a(({annotation:t,isSelected:s,onClick:i,onDelete:n,onDismiss:d,onResolve:m})=>r("div",{class:h("p-3 border cursor-pointer transition-colors",s?"bg-foreground/6 border-primary/30":"border-border hover:bg-foreground/3"),onClick:i,children:[r("div",{class:"flex items-start gap-2 mb-1.5",children:[e("span",{class:h("text-[0.6rem] font-bold uppercase px-1.5 py-0.5 border shrink-0",M[t.intent]),children:I[t.intent]}),e("span",{class:h("text-[0.6rem] font-semibold uppercase tracking-wide shrink-0",$[t.severity]),children:F[t.severity]}),e("span",{class:"flex-1"}),t.resolvedBy&&r("span",{class:"text-[0.58rem] text-muted-foreground/60",children:["by ",t.resolvedBy]}),e("span",{class:"text-[0.58rem] text-muted-foreground/60",children:A[t.status]})]}),e("p",{class:"text-[0.7rem] text-foreground leading-relaxed mb-1.5 line-clamp-2",children:t.comment}),e("div",{class:"flex items-center gap-2 mb-1.5",children:r("code",{class:"text-[0.62rem] text-foreground/60 font-mono bg-foreground/5 px-1.5 py-0.5 truncate",children:[t.elementTag,t.elementPath?` · ${t.elementPath}`:""]})}),t.source&&e("div",{class:"mb-1.5",children:e("code",{class:"text-[0.6rem] text-primary/60 font-mono",children:t.source})}),e("div",{class:"text-[0.58rem] text-muted-foreground/50 truncate mb-2",children:t.url}),t.thread&&t.thread.length>0&&r("div",{class:"text-[0.6rem] text-muted-foreground/60 mb-2",children:[t.thread.length," message",t.thread.length===1?"":"s"," in thread"]}),t.status==="pending"&&r("div",{class:"flex items-center gap-1.5",onClick:a(u=>u.stopPropagation(),"onClick"),children:[e(g,{class:"h-auto py-0.5 px-2 text-[0.6rem]",onClick:m,size:"sm",variant:"outline",children:"Resolve"}),e(g,{class:"h-auto py-0.5 px-2 text-[0.6rem]",onClick:d,size:"sm",variant:"outline",children:"Dismiss"}),e("span",{class:"flex-1"}),e(g,{class:"h-auto py-0.5 px-2 text-[0.6rem] text-destructive hover:text-destructive",onClick:n,size:"sm",variant:"ghost",children:"Delete"})]})]}),"AnnotationCard"),J=a(({annotation:t,helpers:s,onBack:i,onRefresh:n})=>{const[d,m]=c(p(""),"message"),u=S(async()=>{const l=d.trim();l&&(await s.rpc.updateAnnotation?.(t.id,{threadMessage:{content:l,role:"human",timestamp:new Date().toISOString()}}),m(""),n())},[t.id,s,d,n]);return r("div",{class:"p-4 space-y-3",children:[e(g,{class:"h-auto py-0.5 px-2 text-[0.65rem]",onClick:i,size:"sm",variant:"ghost",children:"← Back"}),r("div",{class:"flex items-center gap-2 flex-wrap",children:[e("span",{class:h("text-[0.65rem] font-bold uppercase px-2 py-0.5 border",M[t.intent]),children:I[t.intent]}),e("span",{class:h("text-[0.65rem] font-semibold",$[t.severity]),children:F[t.severity]}),e("span",{class:"text-[0.6rem] text-muted-foreground ml-auto",children:A[t.status]})]}),e("div",{class:"text-[0.75rem] text-foreground leading-relaxed border border-border p-3",children:t.comment}),r("div",{class:"space-y-1 text-[0.65rem]",children:[r("div",{class:"flex gap-2",children:[e("span",{class:"text-muted-foreground w-16 shrink-0",children:"Element"}),r("code",{class:"text-foreground/70 font-mono",children:[t.elementTag,t.cssClasses?` .${t.cssClasses}`:""]})]}),t.source&&r("div",{class:"flex gap-2",children:[e("span",{class:"text-muted-foreground w-16 shrink-0",children:"Source"}),e("code",{class:"text-primary/70 font-mono",children:t.source})]}),r("div",{class:"flex gap-2",children:[e("span",{class:"text-muted-foreground w-16 shrink-0",children:"URL"}),e("span",{class:"text-foreground/60 truncate",children:t.url})]}),r("div",{class:"flex gap-2",children:[e("span",{class:"text-muted-foreground w-16 shrink-0",children:"Created"}),e("span",{class:"text-foreground/60",children:new Date(t.createdAt).toLocaleString()})]})]}),r("div",{children:[r("div",{class:"text-[0.65rem] font-bold uppercase tracking-[0.1em] text-muted-foreground mb-2",children:[e("span",{"aria-hidden":"true",class:"text-primary/50",children:"// "}),"Thread (",t.thread?.length??0,")"]}),t.thread&&t.thread.length>0&&e("div",{class:"space-y-2 mb-3",children:t.thread.map(l=>r("div",{class:"border border-border p-2",children:[r("div",{class:"flex items-center gap-2 mb-1",children:[e("span",{class:"text-[0.62rem] font-semibold text-primary/70",children:l.role}),e("span",{class:"text-[0.55rem] text-muted-foreground/50",children:new Date(l.timestamp).toLocaleString()})]}),e("p",{class:"text-[0.68rem] text-foreground/80 leading-relaxed whitespace-pre-wrap",children:l.content})]},`${l.role}-${l.timestamp}`))}),r("div",{class:"space-y-2",children:[e(U,{class:"text-[0.7rem] min-h-[60px]",onChange:a(l=>m(l.target.value),"onChange"),placeholder:"Add a message to the thread...",value:d}),e(g,{class:"text-[0.65rem]",disabled:!d.trim(),onClick:u,size:"sm",variant:"outline",children:"Send"})]})]})]})},"AnnotationDetail"),W=a(({onChange:t,settings:s})=>{const i=a(n=>{const d={...s,...n};Q(d),t(d)},"update");return r("div",{class:"space-y-3 p-4 border-t border-border",children:[r("div",{class:"text-[0.65rem] font-bold uppercase tracking-[0.1em] text-muted-foreground",children:[e("span",{"aria-hidden":"true",class:"text-primary/50",children:"// "}),"Settings"]}),r("label",{class:"flex items-center gap-2 text-[0.7rem] text-foreground",children:[e("span",{class:"text-muted-foreground w-24 shrink-0",children:"Output Detail"}),r("select",{class:"flex-1 bg-card border border-border text-foreground text-[0.65rem] px-1.5 py-1 cursor-pointer",onChange:a(n=>i({outputDetail:n.target.value}),"onChange"),style:"color-scheme: dark",value:s.outputDetail,children:[e("option",{value:"compact",children:"Compact"}),e("option",{value:"standard",children:"Standard"}),e("option",{value:"detailed",children:"Detailed"}),e("option",{value:"forensic",children:"Forensic"})]})]}),r("div",{class:"flex items-center gap-2 text-[0.7rem]",children:[e("span",{class:"text-muted-foreground w-24 shrink-0",children:"Marker Color"}),e("div",{class:"flex gap-1.5",children:H.map(n=>e("button",{class:h("w-5 h-5 rounded-full border-2 cursor-pointer p-0 transition-all",n.name===s.markerColorName?"border-foreground scale-110":"border-transparent hover:scale-110"),onClick:a(()=>i({markerColorName:n.name}),"onClick"),style:{background:n.bg},title:n.label,type:"button"},n.name))})]}),r("label",{class:"flex items-center gap-2 text-[0.7rem] text-foreground",children:[e("span",{class:"text-muted-foreground w-24 shrink-0",children:"Marker Click"}),r("select",{class:"flex-1 bg-card border border-border text-foreground text-[0.65rem] px-1.5 py-1 cursor-pointer",onChange:a(n=>i({markerClickBehavior:n.target.value}),"onChange"),style:"color-scheme: dark",value:s.markerClickBehavior,children:[e("option",{value:"detail",children:"Show Detail"}),e("option",{value:"edit",children:"Edit"}),e("option",{value:"delete",children:"Delete"})]})]}),r("label",{class:"flex items-center gap-2 text-[0.7rem] text-foreground cursor-pointer",children:[e("input",{checked:s.blockInteractions,class:"cursor-pointer",onChange:a(n=>i({blockInteractions:n.target.checked}),"onChange"),type:"checkbox"}),e("span",{children:"Block page interactions while inspecting"})]})]})},"AnnotationSettingsPanel"),X=a(({helpers:t})=>{const[s,i]=c(p([]),"annotations"),[n,d]=c(p(!1),"loading"),[m,u]=c(p(),"error"),[l,E]=c(p("pending"),"filterStatus"),[b,P]=c(p("all"),"filterIntent"),[k,D]=c(p(),"selectedId"),[y,L]=c(p(!1),"showSettings"),[N,O]=c(p(()=>K()),"settings"),x=S(async()=>{d(!0),u(void 0);try{const o=await t.rpc.getAnnotations?.();i(o??[])}catch(o){u(o instanceof Error?o.message:String(o))}finally{d(!1)}},[t]);q(()=>{x().catch(()=>{})},[x]);const R=s.filter(o=>!(l!=="all"&&o.status!==l||b!=="all"&&o.intent!==b)),f=a(o=>s.filter(v=>v.status===o).length,"countByStatus"),T={acknowledged:f("acknowledged"),all:s.length,dismissed:f("dismissed"),pending:f("pending"),resolved:f("resolved")},B=k?s.find(o=>o.id===k):void 0,C=S(async(o,v)=>{try{await(v==="delete"?t.rpc.deleteAnnotation?.(o):t.rpc.updateAnnotation?.(o,{status:v==="resolve"?"resolved":"dismissed"})),await x()}catch(w){console.error(`[annotations] ${v} failed for ${o}:`,w),u(w instanceof Error?w.message:`Failed to ${v} annotation`)}},[t,x]);return B?e(J,{annotation:B,helpers:t,onBack:a(()=>D(void 0),"onBack"),onRefresh:a(()=>x().catch(()=>{}),"onRefresh")}):r("div",{class:"flex flex-col h-full",children:[r("div",{class:"shrink-0 flex items-center gap-2 px-4 py-2.5 border-b border-border bg-foreground/2 flex-wrap",children:[e(g,{disabled:n,onClick:a(()=>x().catch(()=>{}),"onClick"),size:"sm",variant:"outline",children:n?"Loading…":"Refresh"}),e(g,{class:h("text-[0.65rem]",y&&"bg-primary/10 text-primary"),onClick:a(()=>L(!y),"onClick"),size:"sm",variant:"ghost",children:"Settings"}),e("span",{class:"flex-1"}),r("select",{class:"bg-card border border-border text-foreground text-[0.65rem] px-1.5 py-1 cursor-pointer",onChange:a(o=>P(o.target.value),"onChange"),style:"color-scheme: dark",value:b,children:[e("option",{value:"all",children:"All intents"}),e("option",{value:"fix",children:"Fix"}),e("option",{value:"change",children:"Change"}),e("option",{value:"question",children:"Question"}),e("option",{value:"approve",children:"Approve"})]})]}),r("div",{class:"flex-1 overflow-y-auto devtools-content-scroll",children:[m&&e("div",{class:"p-3 text-[0.7rem] text-destructive bg-destructive/10 border-b border-destructive/20",children:m}),r("div",{class:"p-4 space-y-3",children:[e(Y,{active:l,counts:T,onFilter:E}),R.length===0?r("div",{class:"p-6 text-center border border-border",children:[e("p",{class:"text-[0.8125rem] font-medium text-foreground/70",children:s.length===0?"No annotations yet":"No annotations match filters"}),e("p",{class:"mt-1 text-[0.7rem] text-muted-foreground",children:s.length===0?'Use the Inspector to click an element and select "Annotate".':"Try changing the status or intent filter."})]}):e("div",{class:"space-y-2",children:R.map(o=>e(_,{annotation:o,isSelected:k===o.id,onClick:a(()=>D(o.id),"onClick"),onDelete:a(()=>C(o.id,"delete").catch(()=>{}),"onDelete"),onDismiss:a(()=>C(o.id,"dismiss").catch(()=>{}),"onDismiss"),onResolve:a(()=>C(o.id,"resolve").catch(()=>{}),"onResolve")},o.id))})]})]}),y&&e(W,{onChange:O,settings:N})]})},"AnnotationsApp"),le={component:X,icon:V,id:"dev-toolbar:annotations",name:"Annotations"};export{le as default};

package/dist/apps/inspector/a11y-capture.d.ts

@@ -0,0 +1,12 @@
+interface A11yInfo {
+    ariaAttributes: Record<string, string>;
+    focusable: boolean;
+    role: string | null;
+    tabindex: number | null;
+}
+/** Collect accessibility-relevant attributes from an element. */
+declare const captureA11yInfo: (element: Element) => A11yInfo;
+/** Format A11yInfo as a plain-text summary for clipboard. */
+declare const formatA11yText: (info: A11yInfo) => string;
+export { captureA11yInfo, formatA11yText };
+export type { A11yInfo };

package/dist/apps/inspector/annotation-overlay.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Annotation overlay — renders annotation markers on the page canvas,
+ * provides inline annotation form, detail popup, edit mode, screenshot capture,
+ * freeze mode, markdown export, and SPA navigation persistence.
+ *
+ * All DOM elements are injected into document.body (outside Shadow DOM)
+ * to match the inspector's rendering approach.
+ */
+import type { Annotation } from "../../types/annotations.d.ts";
+/**
+ * Returns true when the Annotations panel app is registered in the toolbar.
+ */
+export declare const isAnnotationsAppEnabled: () => boolean;
+/**
+ * Convert viewport click coords to page-absolute coords for storage.
+ * x = percentage of viewport width, y = absolute page Y (scrollY + clientY).
+ * For fixed elements, y stays as viewport-relative (no scrollY offset).
+ */
+export declare const toPageCoords: (clientX: number, clientY: number, fixed?: boolean) => {
+    x: number;
+    y: number;
+};
+/** Load annotations from server and render markers. */
+export declare const loadAndShowMarkers: () => Promise<void>;
+/** Remove all annotation markers and detach listeners. */
+export declare const removeAllMarkers: () => void;
+/** Close all annotation popups (form, detail) and area outline, but keep markers. */
+export declare const closeAnnotationPopups: () => void;
+/** Whether the annotation form popup is currently open. */
+export declare const isAnnotationFormOpen: () => boolean;
+/** Shake the annotation form to draw attention. */
+export declare const shakeAnnotationForm: () => void;
+/**
+ * Show annotation form popup. Captures selectedText, nearbyText, framework context,
+ * and generates a smart CSS selector.
+ */
+export declare const showAnnotationForm: (element: Element, rect: DOMRect, source: string | undefined, editAnnotation?: Annotation, clickPoint?: {
+    x: number;
+    y: number;
+}) => void;
+/**
+ * Show annotation form for a multi-select (drag) region.
+ * Creates a single annotation covering multiple elements.
+ */
+export declare const showMultiSelectForm: (elements: Element[], selectionRect: DOMRect, boundingBoxes: import("../../types/annotations").BoundingBox[]) => void;
+/**
+ * Show annotation form for an empty area selection (no elements found in drag region).
+ * Like agentation: creates an "Area selection" annotation with the region as bounding box.
+ * Shows a green dashed outline around the selected region.
+ */
+export declare const showAreaSelectionForm: (selectionRect: DOMRect) => void;
+export declare const attachMarkdownShortcut: () => void;
+export declare const detachMarkdownShortcut: () => void;
+/** Check if a target is over an annotation overlay element. */
+export declare const isOverAnnotationOverlay: (target: Element | undefined) => boolean;

package/dist/apps/inspector/annotation-settings.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Annotation-specific settings — output detail level, marker appearance,
+ * interaction behavior. Persisted in localStorage.
+ */
+export type OutputDetailLevel = "compact" | "detailed" | "forensic" | "standard";
+export type MarkerClickBehavior = "delete" | "detail" | "edit";
+export interface MarkerColor {
+    /** Solid background for the marker */
+    bg: string;
+    /** Slightly darker ring / shadow tint */
+    border: string;
+    /** Text color inside the marker (white or dark for contrast) */
+    fg: string;
+    /** Translucent version for hover highlight overlay on elements */
+    highlightBg: string;
+    label: string;
+    name: string;
+}
+export declare const MARKER_COLORS: MarkerColor[];
+export interface AnnotationSettings {
+    /** Block clicks on interactive elements (buttons, links, inputs) while active */
+    blockInteractions: boolean;
+    /** What happens when you click a marker */
+    markerClickBehavior: MarkerClickBehavior;
+    /** Marker color name (from MARKER_COLORS) */
+    markerColorName: string;
+    /** Output detail level for markdown export */
+    outputDetail: OutputDetailLevel;
+}
+export declare const DEFAULT_SETTINGS: AnnotationSettings;
+export declare const loadSettings: () => AnnotationSettings;
+export declare const saveSettings: (settings: AnnotationSettings) => void;
+export declare const getMarkerColor: (settings?: AnnotationSettings) => MarkerColor;

package/dist/apps/inspector/element-utils.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Element utility functions for annotation — shadow DOM piercing, CSS selector
+ * generation, smart naming, text extraction, a11y capture, computed styles,
+ * framework detection, screenshot, freeze, markdown export.
+ */
+import type { AccessibilityInfo, BoundingBox, FrameworkContext } from "../../types/annotations.d.ts";
+export declare const deepElementFromPoint: (x: number, y: number) => Element | null;
+/**
+ * Get the viewport-relative bounding rect for an element, accounting for
+ * it potentially being inside nested iframes.
+ */
+export declare const getViewportRect: (element: Element) => DOMRect;
+/**
+ * Pierce mode: Cmd+hover to find the actual element underneath invisible
+ * overlays, animation wrappers, and empty container divs.
+ *
+ * Two-pass approach:
+ *   1. Find elements with direct text content (skips empty wrappers)
+ *   2. If no text found, return the smallest visible element (catches
+ *      visual-only elements like timeline bars, chart segments, swatches)
+ */
+export declare const pierceElementFromPoint: (x: number, y: number) => Element | null;
+export declare const getParentElement: (element: Element) => Element | null;
+/**
+ * Check if element or any ancestor has fixed or sticky positioning.
+ */
+export declare const isElementFixed: (element: Element) => boolean;
+/**
+ * Generate a human-readable element label like agentation:
+ * button "Submit", link to /page, image "alt text", input[type=email]
+ */
+export declare const getElementLabel: (element: Element) => string;
+/**
+ * Generate a unique CSS selector for an element.
+ * Strategy: ID → unique class combo → nth-of-type fallback.
+ */
+export declare const generateSelector: (element: Element) => string;
+/**
+ * Clean CSS classes by stripping module hash suffixes.
+ */
+export declare const cleanCssClasses: (classes: DOMTokenList) => string;
+/**
+ * Build full DOM ancestry path (body > main > article > section > p).
+ * Marks shadow DOM boundary crossings with ⟨shadow⟩.
+ */
+export declare const getFullDomPath: (element: Element) => string;
+/**
+ * Get sibling elements as context (up to 5 siblings).
+ */
+export declare const getNearbyElements: (element: Element) => string;
+/**
+ * Extract nearby text content from an element (up to maxLength chars).
+ */
+export declare const getNearbyText: (element: Element, maxLength?: number) => string;
+/**
+ * Capture currently selected text (up to maxLength chars).
+ */
+export declare const getSelectedText: (maxLength?: number) => string;
+/**
+ * Capture accessibility attributes from an element.
+ */
+export declare const captureAccessibility: (element: Element) => AccessibilityInfo;
+/**
+ * Capture key computed styles for forensic context.
+ */
+export declare const captureComputedStyles: (element: Element) => string;
+/**
+ * Detect framework component for an element.
+ */
+export declare const detectFrameworkComponent: (element: Element) => FrameworkContext | undefined;
+/**
+ * Capture a screenshot of an element's bounding area.
+ *
+ * Uses the Screen Capture API (getDisplayMedia) to capture a frame from the
+ * screen, then crops to the element's bounding rect. This is the most reliable
+ * approach — works with external CSS, images, shadow DOM, and canvas content.
+ *
+ * Falls back to null if the user denies permission or the API is unavailable.
+ */
+export declare const captureElementScreenshot: (element: Element) => Promise<string | null>;
+/**
+ * Get all elements within a rectangular region.
+ * Searches across shadow DOM and same-origin iframes.
+ */
+export declare const getElementsInRect: (rect: DOMRect) => Element[];
+/**
+ * Get bounding boxes from a list of elements (iframe-aware).
+ */
+export declare const getElementBoundingBoxes: (elements: Element[]) => BoundingBox[];
+/**
+ * Output detail levels:
+ * - compact: "Element: comment (re: "selected text...")"
+ * - standard: Element + location + component + feedback
+ * - detailed: + classes, position, context text
+ * - forensic: + full DOM path, styles, accessibility, nearby elements
+ */
+export declare const annotationsToMarkdown: (annotations: {
+    accessibility?: AccessibilityInfo;
+    comment: string;
+    computedStyles?: string;
+    cssClasses?: string;
+    elementLabel?: string;
+    elementPath?: string;
+    elementTag: string;
+    frameworkContext?: FrameworkContext;
+    fullPath?: string;
+    intent: string;
+    nearbyElements?: string;
+    nearbyText?: string;
+    selectedText?: string;
+    severity: string;
+    source?: string;
+    status: string;
+    url: string;
+}[], detail?: "compact" | "detailed" | "forensic" | "standard") => string;

package/dist/apps/inspector/freeze-animations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Freeze Animations — comprehensive animation/timer freeze system.
+ *
+ * Monkey-patches setTimeout, setInterval, and requestAnimationFrame so that
+ * callbacks are silently queued while frozen. Also injects CSS to pause
+ * CSS animations/transitions, pauses WAAPI animations, and pauses videos.
+ *
+ * Patches are installed as a side effect of importing this module.
+ * Toolbar/popup code must import `originalSetTimeout` to bypass the patch.
+ *
+ * Based on agentation's freeze-animations.ts pattern.
+ */
+/** Original (unpatched) setTimeout — use for toolbar/popup animations */
+export declare const originalSetTimeout: typeof setTimeout;
+/** Whether animations are currently frozen */
+export declare const isFrozen: () => boolean;
+/** Freeze all animations, timers, and videos */
+export declare const freezeAll: () => void;
+/** Unfreeze — resume everything and replay queued callbacks */
+export declare const unfreezeAll: () => void;
+/** Toggle freeze state */
+export declare const toggleFreeze: () => boolean;