@weavetab/mcp 2.5.0 → 2.5.1

package/dist/plugin/extension_bridge.js

@@ -43,51 +43,51 @@ export class PluginExtensionBridge {
         const safeText = JSON.stringify(text);
         try {
             await session.Runtime.evaluate({
-                expression: `(function() {
-          var existing = document.getElementById('__wt_plugin_thought_${this.pluginName}');
-          if (existing) existing.remove();
-
-          var bubble = document.createElement('div');
-          bubble.id = '__wt_plugin_thought_${this.pluginName}';
-          bubble.className = 'wt-bubble';
-          bubble.setAttribute('data-wt-internal', 'true');
-          bubble.style.cssText = [
-            'position: fixed',
-            'bottom: 24px',
-            'right: 24px',
-            'background: linear-gradient(135deg, rgba(17, 24, 39, 0.95), rgba(30, 41, 59, 0.95))',
-            'color: #f8fafc',
-            'padding: 12px 18px',
-            'border-radius: 12px',
-            'font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-            'font-size: 13px',
-            'font-weight: 500',
-            'box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.5), 0 0 0 1px rgba(255, 255, 255, 0.1)',
-            'z-index: 2147483647',
-            'backdrop-filter: blur(8px)',
-            'pointer-events: none',
-            'animation: wtThoughtFade 0.25s cubic-bezier(0.16, 1, 0.3, 1)',
-            'display: flex',
-            'align-items: center',
-            'gap: 8px'
-          ].join(';');
-
-          var icon = document.createElement('span');
-          icon.textContent = '✨';
-          var textSpan = document.createElement('span');
-          textSpan.textContent = ${safeText};
-
-          bubble.appendChild(icon);
-          bubble.appendChild(textSpan);
-          document.body.appendChild(bubble);
-
-          setTimeout(function() {
-            if (bubble && bubble.parentNode) {
-              bubble.style.opacity = '0';
-              bubble.style.transition = 'opacity 0.3s ease';
-              setTimeout(function() { bubble.remove(); }, 300);
-            }
-          }, ${duration});
+                expression: `(function() {
+          var existing = document.getElementById('__wt_plugin_thought_${this.pluginName}');
+          if (existing) existing.remove();
+
+          var bubble = document.createElement('div');
+          bubble.id = '__wt_plugin_thought_${this.pluginName}';
+          bubble.className = 'wt-bubble';
+          bubble.setAttribute('data-wt-internal', 'true');
+          bubble.style.cssText = [
+            'position: fixed',
+            'bottom: 24px',
+            'right: 24px',
+            'background: linear-gradient(135deg, rgba(17, 24, 39, 0.95), rgba(30, 41, 59, 0.95))',
+            'color: #f8fafc',
+            'padding: 12px 18px',
+            'border-radius: 12px',
+            'font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+            'font-size: 13px',
+            'font-weight: 500',
+            'box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.5), 0 0 0 1px rgba(255, 255, 255, 0.1)',
+            'z-index: 2147483647',
+            'backdrop-filter: blur(8px)',
+            'pointer-events: none',
+            'animation: wtThoughtFade 0.25s cubic-bezier(0.16, 1, 0.3, 1)',
+            'display: flex',
+            'align-items: center',
+            'gap: 8px'
+          ].join(';');
+
+          var icon = document.createElement('span');
+          icon.textContent = '✨';
+          var textSpan = document.createElement('span');
+          textSpan.textContent = ${safeText};
+
+          bubble.appendChild(icon);
+          bubble.appendChild(textSpan);
+          document.body.appendChild(bubble);
+
+          setTimeout(function() {
+            if (bubble && bubble.parentNode) {
+              bubble.style.opacity = '0';
+              bubble.style.transition = 'opacity 0.3s ease';
+              setTimeout(function() { bubble.remove(); }, 300);
+            }
+          }, ${duration});
         })()`,
                 returnByValue: false,
             });
@@ -101,9 +101,9 @@ export class PluginExtensionBridge {
             return;
         try {
             await session.Runtime.evaluate({
-                expression: `(function() {
-          var existing = document.getElementById('__wt_plugin_thought_${this.pluginName}');
-          if (existing) existing.remove();
+                expression: `(function() {
+          var existing = document.getElementById('__wt_plugin_thought_${this.pluginName}');
+          if (existing) existing.remove();
         })()`,
                 returnByValue: false,
             });
@@ -118,12 +118,12 @@ export class PluginExtensionBridge {
             return;
         const safeCss = JSON.stringify(css);
         await session.Runtime.evaluate({
-            expression: `(function() {
-        var styleId = '__wt_plugin_styles_${this.pluginName}';
-        var style = document.getElementById(styleId) || document.createElement('style');
-        style.id = styleId;
-        style.textContent = ${safeCss};
-        if (!style.parentNode) document.head.appendChild(style);
+            expression: `(function() {
+        var styleId = '__wt_plugin_styles_${this.pluginName}';
+        var style = document.getElementById(styleId) || document.createElement('style');
+        style.id = styleId;
+        style.textContent = ${safeCss};
+        if (!style.parentNode) document.head.appendChild(style);
       })()`,
             returnByValue: false,
         });

package/dist/plugin/interface.d.ts

@@ -7,6 +7,11 @@ export interface WeavetabToolDefinition {
     name: string;
     description: string;
     schema: Record<string, z.ZodType<any>>;
+    /**
+     * When `false`, the host does NOT establish a browser/CDP session before
+     * invoking this tool. Use for API-only tools. Defaults to `true`.
+     */
+    requiresSession?: boolean;
     handler: (args: Record<string, any>, session: CDP.Client, config: Config) => Promise<Record<string, any>>;
 }
 export interface WeavetabToolOverride {
@@ -146,6 +151,8 @@ export interface WeavetabPluginTool<TArgs = any> {
     schema?: Record<string, any> | Record<string, z.ZodType<any>>;
     inputSchema?: Record<string, any>;
     parameters?: Record<string, any>;
+    /** See {@link WeavetabToolDefinition.requiresSession}. Defaults to `true`. */
+    requiresSession?: boolean;
     handler: (args: TArgs, session?: any, config?: any) => Promise<any>;
 }
 export interface DOMMutationDelta {

package/dist/plugin/loader.js

@@ -17,7 +17,6 @@ function getNodeModulesDirs(customDir) {
         join(cwd, "MCP", "node_modules"),
         join(cwd, "..", "node_modules"),
         join(os.homedir(), ".weavetab", "plugins", "node_modules"),
-        join(os.homedir(), ".weavetab-system", "plugins", "node_modules"),
     ];
     return Array.from(new Set(dirs.filter((d) => existsSync(d))));
 }
@@ -152,7 +151,7 @@ export function listInstalledPlugins(pluginDir) {
                 if (!entry.isDirectory() && !entry.isSymbolicLink())
                     continue;
                 if (entry.name.startsWith("@")) {
-                    // Scoped packages (@weavetab/plugin-xyz, @scope/xyz, @fy2ne/wt-youtube)
+                    // Scoped packages (@weavetab/plugin-xyz, @scope/xyz, @acme/weavetab-plugin)
                     const scopeDir = join(modulesDir, entry.name);
                     try {
                         const scopeEntries = readdirSync(scopeDir, { withFileTypes: true });
@@ -419,7 +418,7 @@ export function discoverPlugins(pluginDir) {
                 if (!entry.isDirectory() && !entry.isSymbolicLink())
                     continue;
                 if (entry.name.startsWith("@")) {
-                    // Scoped package directory (e.g. @weavetab, @fy2ne, @mycompany)
+                    // Scoped package directory (e.g. @weavetab, @acme, @mycompany)
                     const scopeDir = join(modulesDir, entry.name);
                     try {
                         const scopeEntries = readdirSync(scopeDir, { withFileTypes: true });
@@ -436,7 +435,7 @@ export function discoverPlugins(pluginDir) {
                     catch { /* scope dir unreadable */ }
                 }
                 else {
-                    // Top-level package — any name works: wt-youtube, my-plugin, etc.
+                    // Top-level package — any name works: my-plugin, wt-github, custom-plugin, etc.
                     const plugin = tryLoadPlugin(join(modulesDir, entry.name));
                     if (plugin && !seenPluginNames.has(plugin.name)) {
                         seenPluginNames.add(plugin.name);

package/dist/plugin/schema.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Weavetab by fy2ne
+ * @file schema.ts — Plugin tool schema normalizer.
+ *
+ * Converts a plugin-provided tool schema into a Zod raw shape accepted by
+ * `McpServer.tool()`. Supports the three shapes plugin authors may provide:
+ *   1. Zod raw shape        — { field: z.string() }            (preferred)
+ *   2. Zod object schema    — z.object({ field: z.string() })
+ *   3. Plain JSON Schema    — { type: "object", properties: { field: { type: "string" } } }
+ */
+export declare function toPluginInputShape(schema: any): Record<string, any>;

package/dist/plugin/schema.js

@@ -0,0 +1,59 @@
+/**
+ * Weavetab by fy2ne
+ * @file schema.ts — Plugin tool schema normalizer.
+ *
+ * Converts a plugin-provided tool schema into a Zod raw shape accepted by
+ * `McpServer.tool()`. Supports the three shapes plugin authors may provide:
+ *   1. Zod raw shape        — { field: z.string() }            (preferred)
+ *   2. Zod object schema    — z.object({ field: z.string() })
+ *   3. Plain JSON Schema    — { type: "object", properties: { field: { type: "string" } } }
+ */
+import { z } from "zod";
+export function toPluginInputShape(schema) {
+    if (!schema || typeof schema !== "object")
+        return {};
+    // A Zod object/schema instance (e.g. z.object({...})) — use its shape.
+    if (schema._def || schema._zod) {
+        const shape = typeof schema.shape === "function" ? schema.shape() : schema.shape;
+        return shape && typeof shape === "object" ? shape : {};
+    }
+    // A raw shape: an object whose values are Zod schemas.
+    const values = Object.values(schema);
+    if (values.some((v) => v && typeof v === "object" && (v._def || v._zod || typeof v.parse === "function"))) {
+        return schema;
+    }
+    // A plain JSON Schema object — convert its properties into a Zod raw shape.
+    if (schema.properties && typeof schema.properties === "object") {
+        const required = Array.isArray(schema.required) ? schema.required : [];
+        const shape = {};
+        for (const [key, prop] of Object.entries(schema.properties)) {
+            let field;
+            switch (prop?.type) {
+                case "number":
+                case "integer":
+                    field = z.number();
+                    break;
+                case "boolean":
+                    field = z.boolean();
+                    break;
+                case "array":
+                    field = z.array(z.any());
+                    break;
+                case "object":
+                    field = z.record(z.string(), z.any());
+                    break;
+                default:
+                    field = z.string();
+            }
+            if (typeof prop?.description === "string")
+                field = field.describe(prop.description);
+            if (prop?.default !== undefined)
+                field = field.default(prop.default);
+            if (!required.includes(key))
+                field = field.optional();
+            shape[key] = field;
+        }
+        return shape;
+    }
+    return {};
+}

package/dist/security/guard.js

@@ -4,24 +4,24 @@ export function assertNotRoot() {
         throw new Error("[!] Weave failed: Running as root is not allowed. Start Weavetab as a normal user.");
     }
 }
-const STORAGE_BLOCK_SCRIPT = `
-(function() {
-  // Only block cookie WRITES for known tracking domains, not reads.
-  // Fully blocking storage breaks site rendering (GitHub, etc.)
-  var _origCookieDesc = Object.getOwnPropertyDescriptor(document, 'cookie');
-  if (_origCookieDesc) {
-    Object.defineProperty(document, 'cookie', {
-      get: function() { return _origCookieDesc.get.call(document); },
-      set: function(v) {
-        // Block cookies from known trackers
-        if (/(_ga|_gid|_fbp|_fbc|__utm|fr|_gcl)/.test(v)) return;
-        _origCookieDesc.set.call(document, v);
-      },
-      configurable: true
-    });
-  }
-  // Do NOT block localStorage/sessionStorage — sites need them to render
-})();
+const STORAGE_BLOCK_SCRIPT = `
+(function() {
+  // Only block cookie WRITES for known tracking domains, not reads.
+  // Fully blocking storage breaks site rendering (GitHub, etc.)
+  var _origCookieDesc = Object.getOwnPropertyDescriptor(document, 'cookie');
+  if (_origCookieDesc) {
+    Object.defineProperty(document, 'cookie', {
+      get: function() { return _origCookieDesc.get.call(document); },
+      set: function(v) {
+        // Block cookies from known trackers
+        if (/(_ga|_gid|_fbp|_fbc|__utm|fr|_gcl)/.test(v)) return;
+        _origCookieDesc.set.call(document, v);
+      },
+      configurable: true
+    });
+  }
+  // Do NOT block localStorage/sessionStorage — sites need them to render
+})();
 `;
 export async function blockStorageAccess(session) {
     await session.Page.addScriptToEvaluateOnNewDocument({

package/dist/sensors/actionability.js

@@ -48,137 +48,137 @@ function buildPageExpression(selector, scrollOptions, fingerprint, stabilityMs)
     const selectorLiteral = JSON.stringify(selector);
     const scrollLiteral = scrollOptions ? JSON.stringify(scrollOptions) : "null";
     const fingerprintLiteral = fingerprint ? JSON.stringify(fingerprint) : "null";
-    return `(async function() {
-    // ── Helper: is this node owned by WeaveTab? ────────────────────────────
-    function isWtOwned(el) {
-      if (!el) return false;
-      // Attribute-based markers: data-wt-ignore and data-wt-internal both signal
-      // WeaveTab-owned UI that must not block page interactions.
-      if (el.getAttribute && (
-        el.getAttribute('data-wt-ignore') !== null ||
-        el.getAttribute('data-wt-internal') !== null ||
-        el.getAttribute('data-wt-overlay') !== null
-      )) return true;
-      const wtIds = ['Weavetab-hud', '__Weavetab_controlled_indicator', 'wt-main-container', 'wt-system-icon', 'wt-f3-host', 'Weavetab-root'];
-      if (el.id && wtIds.includes(el.id)) return true;
-      if (el.closest) {
-        if (el.closest('[data-wt-ignore],[data-wt-internal],[data-wt-overlay]')) return true;
-        if (wtIds.some(id => el.closest('#' + id))) return true;
-      }
-      return false;
-    }
-
-    // ── Step 1: Resolve element ────────────────────────────────────────────
-    let el = document.querySelector(${selectorLiteral});
-    if (!el && window.__Weavetab_shadowQuery) {
-      el = window.__Weavetab_shadowQuery(${selectorLiteral});
-    }
-    if (!el) return { status: 'NOT_FOUND' };
-
-    // ── Step 2: Fingerprint check ──────────────────────────────────────────
-    const fp = ${fingerprintLiteral};
-    if (fp) {
-      if (fp.tag && el.tagName.toLowerCase() !== fp.tag.toLowerCase())
-        return { status: 'FINGERPRINT_MISMATCH' };
-      if (fp.role && el.getAttribute('role') !== fp.role)
-        return { status: 'FINGERPRINT_MISMATCH' };
-    }
-
-    // ── Step 3: Basic visibility ───────────────────────────────────────────
-    // Use checkVisibility() (Chrome 105+) as the most reliable single check.
-    // Falls back to manual computed-style + rect checks for older runtimes.
-    if (typeof el.checkVisibility === 'function') {
-      if (!el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }))
-        return { status: 'INVISIBLE' };
-    } else {
-      const cs = window.getComputedStyle(el);
-      if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0')
-        return { status: 'INVISIBLE' };
-    }
-
-    let rect = el.getBoundingClientRect();
-    if (rect.width === 0 || rect.height === 0) return { status: 'INVISIBLE' };
-    // Off-screen by more than 2× viewport dimension in any direction
-    if (rect.right < -window.innerWidth || rect.bottom < -window.innerHeight ||
-        rect.left > 2 * window.innerWidth || rect.top > 2 * window.innerHeight)
-      return { status: 'INVISIBLE' };
-
-    // ── Step 4: Scroll into view (using provided alignment) ────────────────
-    const scrollOpts = ${scrollLiteral};
-    if (scrollOpts) {
-      el.scrollIntoView(scrollOpts);
-      await new Promise(r => setTimeout(r, 120));
-    } else if (rect.top < 0 || rect.bottom > window.innerHeight ||
-               rect.left < 0 || rect.right > window.innerWidth) {
-      el.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-      await new Promise(r => setTimeout(r, 120));
-    }
-    rect = el.getBoundingClientRect();
-
-    // ── Step 5: RAF-stability gate ─────────────────────────────────────────
-    const stabilityDeadline = Date.now() + ${stabilityMs};
-    let prevRect = el.getBoundingClientRect();
-    let stable = false;
-    while (Date.now() < stabilityDeadline) {
-      await new Promise(r => requestAnimationFrame(r));
-      const cur = el.getBoundingClientRect();
-      if (
-        Math.abs(cur.x - prevRect.x) < 0.5 &&
-        Math.abs(cur.y - prevRect.y) < 0.5 &&
-        Math.abs(cur.width - prevRect.width) < 0.5 &&
-        Math.abs(cur.height - prevRect.height) < 0.5
-      ) {
-        stable = true;
-        break;
-      }
-      prevRect = cur;
-    }
-    if (!stable) return { status: 'UNSTABLE' };
-    rect = el.getBoundingClientRect();
-
-    // ── Step 6: Compute click centre (clamped to viewport) ─────────────────
-    const cx = Math.round(Math.min(Math.max(rect.left + rect.width / 2, 0), window.innerWidth - 1));
-    const cy = Math.round(Math.min(Math.max(rect.top + rect.height / 2, 0), window.innerHeight - 1));
-
-    // ── Step 7: Strict hit-target check ───────────────────────────────────
-    // elementsFromPoint returns the full composited stack, topmost first.
-    const stack = document.elementsFromPoint(cx, cy);
-    if (!stack || stack.length === 0) return { status: 'ACTIONABLE', x: cx, y: cy };
-
-    // Walk from the topmost element. Anything that is WeaveTab-owned is
-    // transparent — skip it. The first non-WT element must be el or its descendant.
-    let blocker = null;
-    for (const hit of stack) {
-      if (isWtOwned(hit)) continue;  // WeaveTab transparency
-      blocker = hit;
-      break;
-    }
-
-    if (!blocker || blocker === el || el.contains(blocker)) {
-      return { status: 'ACTIONABLE', x: cx, y: cy };
-    }
-
-    // Check composed tree (shadow DOM + slots)
-    let ancestor = blocker;
-    while (ancestor) {
-      if (ancestor === el) return { status: 'ACTIONABLE', x: cx, y: cy };
-      ancestor = ancestor.assignedSlot || ancestor.parentElement ||
-                 (ancestor.getRootNode && ancestor.getRootNode({ composed: true }) !== ancestor
-                   ? ancestor.getRootNode({ composed: true }).host : null);
-    }
-
-    return {
-      status: 'OCCLUDED',
-      x: cx, y: cy,
-      occludedBy: {
-        tag: blocker.tagName.toLowerCase(),
-        id: blocker.id || '',
-        className: (blocker.className && typeof blocker.className === 'string')
-          ? blocker.className.slice(0, 60) : '',
-        ariaLabel: blocker.getAttribute('aria-label') || blocker.getAttribute('title') || null,
-        isWeavetabOwned: isWtOwned(blocker)
-      }
-    };
+    return `(async function() {
+    // ── Helper: is this node owned by WeaveTab? ────────────────────────────
+    function isWtOwned(el) {
+      if (!el) return false;
+      // Attribute-based markers: data-wt-ignore and data-wt-internal both signal
+      // WeaveTab-owned UI that must not block page interactions.
+      if (el.getAttribute && (
+        el.getAttribute('data-wt-ignore') !== null ||
+        el.getAttribute('data-wt-internal') !== null ||
+        el.getAttribute('data-wt-overlay') !== null
+      )) return true;
+      const wtIds = ['Weavetab-hud', '__Weavetab_controlled_indicator', 'wt-main-container', 'wt-system-icon', 'wt-f3-host', 'Weavetab-root'];
+      if (el.id && wtIds.includes(el.id)) return true;
+      if (el.closest) {
+        if (el.closest('[data-wt-ignore],[data-wt-internal],[data-wt-overlay]')) return true;
+        if (wtIds.some(id => el.closest('#' + id))) return true;
+      }
+      return false;
+    }
+
+    // ── Step 1: Resolve element ────────────────────────────────────────────
+    let el = document.querySelector(${selectorLiteral});
+    if (!el && window.__Weavetab_shadowQuery) {
+      el = window.__Weavetab_shadowQuery(${selectorLiteral});
+    }
+    if (!el) return { status: 'NOT_FOUND' };
+
+    // ── Step 2: Fingerprint check ──────────────────────────────────────────
+    const fp = ${fingerprintLiteral};
+    if (fp) {
+      if (fp.tag && el.tagName.toLowerCase() !== fp.tag.toLowerCase())
+        return { status: 'FINGERPRINT_MISMATCH' };
+      if (fp.role && el.getAttribute('role') !== fp.role)
+        return { status: 'FINGERPRINT_MISMATCH' };
+    }
+
+    // ── Step 3: Basic visibility ───────────────────────────────────────────
+    // Use checkVisibility() (Chrome 105+) as the most reliable single check.
+    // Falls back to manual computed-style + rect checks for older runtimes.
+    if (typeof el.checkVisibility === 'function') {
+      if (!el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }))
+        return { status: 'INVISIBLE' };
+    } else {
+      const cs = window.getComputedStyle(el);
+      if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0')
+        return { status: 'INVISIBLE' };
+    }
+
+    let rect = el.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return { status: 'INVISIBLE' };
+    // Off-screen by more than 2× viewport dimension in any direction
+    if (rect.right < -window.innerWidth || rect.bottom < -window.innerHeight ||
+        rect.left > 2 * window.innerWidth || rect.top > 2 * window.innerHeight)
+      return { status: 'INVISIBLE' };
+
+    // ── Step 4: Scroll into view (using provided alignment) ────────────────
+    const scrollOpts = ${scrollLiteral};
+    if (scrollOpts) {
+      el.scrollIntoView(scrollOpts);
+      await new Promise(r => setTimeout(r, 120));
+    } else if (rect.top < 0 || rect.bottom > window.innerHeight ||
+               rect.left < 0 || rect.right > window.innerWidth) {
+      el.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+      await new Promise(r => setTimeout(r, 120));
+    }
+    rect = el.getBoundingClientRect();
+
+    // ── Step 5: RAF-stability gate ─────────────────────────────────────────
+    const stabilityDeadline = Date.now() + ${stabilityMs};
+    let prevRect = el.getBoundingClientRect();
+    let stable = false;
+    while (Date.now() < stabilityDeadline) {
+      await new Promise(r => requestAnimationFrame(r));
+      const cur = el.getBoundingClientRect();
+      if (
+        Math.abs(cur.x - prevRect.x) < 0.5 &&
+        Math.abs(cur.y - prevRect.y) < 0.5 &&
+        Math.abs(cur.width - prevRect.width) < 0.5 &&
+        Math.abs(cur.height - prevRect.height) < 0.5
+      ) {
+        stable = true;
+        break;
+      }
+      prevRect = cur;
+    }
+    if (!stable) return { status: 'UNSTABLE' };
+    rect = el.getBoundingClientRect();
+
+    // ── Step 6: Compute click centre (clamped to viewport) ─────────────────
+    const cx = Math.round(Math.min(Math.max(rect.left + rect.width / 2, 0), window.innerWidth - 1));
+    const cy = Math.round(Math.min(Math.max(rect.top + rect.height / 2, 0), window.innerHeight - 1));
+
+    // ── Step 7: Strict hit-target check ───────────────────────────────────
+    // elementsFromPoint returns the full composited stack, topmost first.
+    const stack = document.elementsFromPoint(cx, cy);
+    if (!stack || stack.length === 0) return { status: 'ACTIONABLE', x: cx, y: cy };
+
+    // Walk from the topmost element. Anything that is WeaveTab-owned is
+    // transparent — skip it. The first non-WT element must be el or its descendant.
+    let blocker = null;
+    for (const hit of stack) {
+      if (isWtOwned(hit)) continue;  // WeaveTab transparency
+      blocker = hit;
+      break;
+    }
+
+    if (!blocker || blocker === el || el.contains(blocker)) {
+      return { status: 'ACTIONABLE', x: cx, y: cy };
+    }
+
+    // Check composed tree (shadow DOM + slots)
+    let ancestor = blocker;
+    while (ancestor) {
+      if (ancestor === el) return { status: 'ACTIONABLE', x: cx, y: cy };
+      ancestor = ancestor.assignedSlot || ancestor.parentElement ||
+                 (ancestor.getRootNode && ancestor.getRootNode({ composed: true }) !== ancestor
+                   ? ancestor.getRootNode({ composed: true }).host : null);
+    }
+
+    return {
+      status: 'OCCLUDED',
+      x: cx, y: cy,
+      occludedBy: {
+        tag: blocker.tagName.toLowerCase(),
+        id: blocker.id || '',
+        className: (blocker.className && typeof blocker.className === 'string')
+          ? blocker.className.slice(0, 60) : '',
+        ariaLabel: blocker.getAttribute('aria-label') || blocker.getAttribute('title') || null,
+        isWeavetabOwned: isWtOwned(blocker)
+      }
+    };
   })()`;
 }
 // ── Main export ───────────────────────────────────────────────────────────────
@@ -255,42 +255,42 @@ export async function verifyActionability(session, selector, opts = {}) {
  * Used for lightweight pre-dispatch validation inside click.ts.
  */
 export async function quickHitCheck(session, x, y, selectorOfTarget) {
-    const expr = `(function() {
-    function isWtOwned(el) {
-      if (!el) return false;
-      if (el.getAttribute && (
-        el.getAttribute('data-wt-ignore') !== null ||
-        el.getAttribute('data-wt-internal') !== null ||
-        el.getAttribute('data-wt-overlay') !== null
-      )) return true;
-      const ids = ['Weavetab-hud','__Weavetab_controlled_indicator','wt-main-container','wt-system-icon','wt-f3-host','Weavetab-root'];
-      if (el.id && ids.includes(el.id)) return true;
-      return !!(el.closest && (el.closest('[data-wt-ignore],[data-wt-internal],[data-wt-overlay]') || ids.some(id => el.closest('#' + id))));
-    }
-    const target = document.querySelector(${JSON.stringify(selectorOfTarget)})
-      || (window.__Weavetab_shadowQuery ? window.__Weavetab_shadowQuery(${JSON.stringify(selectorOfTarget)}) : null);
-    const stack = document.elementsFromPoint(${x}, ${y});
-    if (!stack || !stack.length) return { clear: true };
-    for (const hit of stack) {
-      if (isWtOwned(hit)) continue;
-      if (!target || hit === target || target.contains(hit)) return { clear: true };
-      // Walk composed tree for shadow DOM
-      let ancestor = hit;
-      while (ancestor) {
-        if (ancestor === target) return { clear: true };
-        ancestor = ancestor.assignedSlot || ancestor.parentElement ||
-          (ancestor.getRootNode && ancestor.getRootNode({composed:true}) !== ancestor
-            ? ancestor.getRootNode({composed:true}).host : null);
-      }
-      return {
-        clear: false,
-        blockerDescription: hit.tagName.toLowerCase() +
-          (hit.id ? '#' + hit.id : '') +
-          (hit.className && typeof hit.className === 'string' ? '.' + hit.className.split(' ')[0] : '') +
-          ' intercepts pointer events'
-      };
-    }
-    return { clear: true };
+    const expr = `(function() {
+    function isWtOwned(el) {
+      if (!el) return false;
+      if (el.getAttribute && (
+        el.getAttribute('data-wt-ignore') !== null ||
+        el.getAttribute('data-wt-internal') !== null ||
+        el.getAttribute('data-wt-overlay') !== null
+      )) return true;
+      const ids = ['Weavetab-hud','__Weavetab_controlled_indicator','wt-main-container','wt-system-icon','wt-f3-host','Weavetab-root'];
+      if (el.id && ids.includes(el.id)) return true;
+      return !!(el.closest && (el.closest('[data-wt-ignore],[data-wt-internal],[data-wt-overlay]') || ids.some(id => el.closest('#' + id))));
+    }
+    const target = document.querySelector(${JSON.stringify(selectorOfTarget)})
+      || (window.__Weavetab_shadowQuery ? window.__Weavetab_shadowQuery(${JSON.stringify(selectorOfTarget)}) : null);
+    const stack = document.elementsFromPoint(${x}, ${y});
+    if (!stack || !stack.length) return { clear: true };
+    for (const hit of stack) {
+      if (isWtOwned(hit)) continue;
+      if (!target || hit === target || target.contains(hit)) return { clear: true };
+      // Walk composed tree for shadow DOM
+      let ancestor = hit;
+      while (ancestor) {
+        if (ancestor === target) return { clear: true };
+        ancestor = ancestor.assignedSlot || ancestor.parentElement ||
+          (ancestor.getRootNode && ancestor.getRootNode({composed:true}) !== ancestor
+            ? ancestor.getRootNode({composed:true}).host : null);
+      }
+      return {
+        clear: false,
+        blockerDescription: hit.tagName.toLowerCase() +
+          (hit.id ? '#' + hit.id : '') +
+          (hit.className && typeof hit.className === 'string' ? '.' + hit.className.split(' ')[0] : '') +
+          ' intercepts pointer events'
+      };
+    }
+    return { clear: true };
   })()`;
     try {
         const { result } = await session.Runtime.evaluate({ expression: expr, returnByValue: true });