@weavetab/mcp 2.5.0-beta.2 → 2.5.0-beta.5

package/dist/tools/pdf.js

@@ -1,7 +1,7 @@
 import { getOutputDir } from "../config/loader.js";
 import fs from "node:fs";
 import path from "node:path";
-import { hideWeaveTabOverlay, restoreWeaveTabOverlay } from "../cdp/helpers.js";
+import { hideWeaveTabOverlay, restoreWeaveTabOverlay, maskSecretFieldsForCapture, restoreSecretFieldsAfterCapture } from "../cdp/helpers.js";
 export async function browserPdf(session, options, config) {
     // Always hide the overlay before generating PDF (agent must never see it).
     // Set hideOverlay: false explicitly to keep overlays visible.
@@ -9,18 +9,26 @@ export async function browserPdf(session, options, config) {
     if (shouldHide) {
         await hideWeaveTabOverlay(session);
     }
-    const { data } = await session.Page.printToPDF({
-        landscape: options.landscape ?? false,
-        scale: options.scale ?? 1.0,
-        pageRanges: options.pageRanges ?? "",
-        marginTop: 0.4, // 1cm ish
-        marginBottom: 0.4,
-        marginLeft: 0.4,
-        marginRight: 0.4,
-        printBackground: true
-    });
-    if (shouldHide) {
-        await restoreWeaveTabOverlay(session);
+    await maskSecretFieldsForCapture(session);
+    let data;
+    try {
+        const pdfRes = await session.Page.printToPDF({
+            landscape: options.landscape ?? false,
+            scale: options.scale ?? 1.0,
+            pageRanges: options.pageRanges ?? "",
+            marginTop: 0.4, // 1cm ish
+            marginBottom: 0.4,
+            marginLeft: 0.4,
+            marginRight: 0.4,
+            printBackground: true
+        });
+        data = pdfRes.data;
+    }
+    finally {
+        await restoreSecretFieldsAfterCapture(session);
+        if (shouldHide) {
+            await restoreWeaveTabOverlay(session);
+        }
     }
     // Use configured PDF directory or default
     const pdfsDir = getOutputDir("pdfs", config);

package/dist/tools/pointer.d.ts

@@ -19,8 +19,18 @@ export interface PointerResult {
     url: string;
     dom_changed?: boolean;
 }
-export declare function browserPointer(session: CDP.Client, args: {
-    action: "click" | "double_click" | "hover" | "drag_and_drop";
+export interface PointerStep {
+    action?: "hover" | "click" | "double_click";
+    ref?: string;
+    selector?: string;
+    target?: string;
+    label?: string;
+    x?: number;
+    y?: number;
+    holdMs?: number;
+}
+export interface PointerArgs {
+    action?: "click" | "double_click" | "hover" | "drag_and_drop" | "hover_chain";
     ref?: string;
     selector?: string;
     target?: string;
@@ -32,4 +42,9 @@ export declare function browserPointer(session: CDP.Client, args: {
     end_y?: number;
     waitForChild?: string;
     holdMs?: number;
-}, config: Config): Promise<PointerResult>;
+    hover_chain?: Array<string | PointerStep>;
+    chain?: Array<string | PointerStep>;
+    clickFinal?: boolean;
+    [key: string]: unknown;
+}
+export declare function browserPointer(session: CDP.Client, args: PointerArgs, config: Config): Promise<PointerResult>;

package/dist/tools/pointer.js

@@ -117,7 +117,95 @@ async function resolveRefToCoords(session, targetId, ref, currentUrl) {
     return null;
 }
 export async function browserPointer(session, args, config) {
-    let { action, ref, selector, label, x, y, end_ref, end_x, end_y, waitForChild, holdMs = 300 } = args;
+    let { action = "click", ref, selector, label, x, y, end_ref, end_x, end_y, waitForChild, holdMs = 200 } = args;
+    // ── HOVER CHAIN / SUBMENU NAVIGATION (Photopea, Figma, Photoshop, Flyout Menus) ──
+    const rawChain = args.hover_chain || args.chain;
+    if (action === "hover_chain" || (rawChain && rawChain.length > 0)) {
+        const chainItems = (rawChain || []).map((step, idx, arr) => {
+            if (typeof step === "string") {
+                const isLast = idx === arr.length - 1;
+                return {
+                    action: isLast && args.clickFinal !== false ? "click" : "hover",
+                    ref: step,
+                    label: step,
+                    target: step
+                };
+            }
+            return step;
+        });
+        const startMs = Date.now();
+        const { Page, Input } = session;
+        let targetId = "default";
+        const active = sessionRegistry.getActive(getConfigAgentId(config));
+        if (active)
+            targetId = active.targetId;
+        let lastX = 0, lastY = 0;
+        for (let i = 0; i < chainItems.length; i++) {
+            const step = chainItems[i];
+            const stepTarget = step.ref || step.selector || step.target || step.label;
+            let stepCoords = null;
+            if (step.x !== undefined && step.y !== undefined) {
+                stepCoords = { x: step.x, y: step.y, selector: step.selector || '' };
+            }
+            else if (stepTarget) {
+                stepCoords = await resolveRefToCoords(session, targetId, stepTarget).catch(() => null);
+                if (!stepCoords) {
+                    // Submenu might have rendered after previous hover; quick retry with fresh map
+                    await new Promise(r => setTimeout(r, 80));
+                    await buildActionMap(session, { lite: true }, targetId).then(m => cacheActionMap(targetId, m)).catch(() => { });
+                    stepCoords = await resolveRefToCoords(session, targetId, stepTarget).catch(() => null);
+                }
+            }
+            if (!stepCoords) {
+                throw new Error(`[browser_pointer hover_chain] Could not resolve coordinates for chain step [${i}]: '${stepTarget}'`);
+            }
+            lastX = stepCoords.x;
+            lastY = stepCoords.y;
+            // Move pointer smoothly to element
+            await ghostMove(session, stepCoords.x, stepCoords.y, config, step.label, "fast");
+            await Input.dispatchMouseEvent({ type: "mouseMoved", x: stepCoords.x, y: stepCoords.y, pointerType: "mouse" });
+            // Dispatch mouseenter/mouseover events for dynamic flyout/hover menus
+            if (stepCoords.selector) {
+                await session.Runtime.evaluate({
+                    expression: `(function(sel, cx, cy) {
+            const el = document.querySelector(sel) || (window.__Weavetab_shadowQuery ? window.__Weavetab_shadowQuery(sel) : null);
+            if (!el) return;
+            el.dispatchEvent(new MouseEvent('mouseenter', { bubbles: false, cancelable: true, clientX: cx, clientY: cy }));
+            el.dispatchEvent(new MouseEvent('mouseover',  { bubbles: true,  cancelable: true, clientX: cx, clientY: cy }));
+            el.dispatchEvent(new MouseEvent('mousemove',  { bubbles: true,  cancelable: true, clientX: cx, clientY: cy }));
+          })(${JSON.stringify(stepCoords.selector)}, ${stepCoords.x}, ${stepCoords.y})`,
+                    returnByValue: false
+                }).catch(() => { });
+            }
+            const stepHold = step.holdMs ?? (i === chainItems.length - 1 ? 40 : 100);
+            await new Promise(r => setTimeout(r, stepHold));
+            // If action is click (e.g. final step in chain)
+            if (step.action === "click") {
+                await Input.dispatchMouseEvent({ type: "mousePressed", x: stepCoords.x, y: stepCoords.y, button: "left", clickCount: 1, pointerType: "mouse" });
+                await new Promise(r => setTimeout(r, 40));
+                await Input.dispatchMouseEvent({ type: "mouseReleased", x: stepCoords.x, y: stepCoords.y, button: "left", clickCount: 1, pointerType: "mouse" });
+            }
+            else if (step.action === "double_click") {
+                await Input.dispatchMouseEvent({ type: "mousePressed", x: stepCoords.x, y: stepCoords.y, button: "left", clickCount: 1, pointerType: "mouse" });
+                await Input.dispatchMouseEvent({ type: "mouseReleased", x: stepCoords.x, y: stepCoords.y, button: "left", clickCount: 1, pointerType: "mouse" });
+                await new Promise(r => setTimeout(r, 60));
+                await Input.dispatchMouseEvent({ type: "mousePressed", x: stepCoords.x, y: stepCoords.y, button: "left", clickCount: 2, pointerType: "mouse" });
+                await Input.dispatchMouseEvent({ type: "mouseReleased", x: stepCoords.x, y: stepCoords.y, button: "left", clickCount: 2, pointerType: "mouse" });
+            }
+        }
+        const execMs = Date.now() - startMs;
+        const { frameTree: postFrameTree } = await Page.getFrameTree().catch(() => ({ frameTree: { frame: { url: '' } } }));
+        return {
+            success: true,
+            action: "hover_chain",
+            x: lastX,
+            y: lastY,
+            execution_ms: execMs,
+            tab_id: targetId,
+            url: postFrameTree.frame.url,
+            dom_changed: true,
+        };
+    }
     if (selector && !ref) {
         ref = selector;
     }

package/dist/tools/read.d.ts

@@ -4,7 +4,25 @@
  * Weavetab by fy2ne
  */
 import CDP from "chrome-remote-interface";
+import { type MarkEntry } from "../intelligence/marks.js";
 import type { Config } from "../config/loader.js";
+export interface VisualMark {
+    mark: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    ref?: string;
+    label?: string;
+    type?: MarkEntry["type"];
+}
+export interface BrowserMapResult {
+    text: string;
+    /** Base64 JPEG of the page annotated with numbered SoM badges. Only present in visual mode. */
+    imageBase64?: string;
+    /** Structured mark list — numbers match badges visible on the screenshot. */
+    marks?: VisualMark[];
+}
 export interface ReadOptions {
     lite?: boolean;
     full?: boolean;
@@ -14,17 +32,19 @@ export interface ReadOptions {
     delta?: boolean;
     intent?: string;
     ax_tree?: boolean;
-    /** Debug: draws colored element borders via extension. The screen glow (blue edge fade) is the standard visual indicator, shown automatically during reading states. */
+    /** Debug: draws colored element borders via extension. */
     show_overlays?: boolean;
-    /** Force deep shadow DOM traversal (crosses all shadow boundaries to find elements). Auto-enabled when flat query returns sparse results. */
+    /** Force deep shadow DOM traversal. */
     deep?: boolean;
+    /** Semantic DOM pruning. Defaults to true to drop non-interactive noise and SVGs. */
+    prune?: boolean;
     /**
-     * Run one-shot semantic DOM pruning before returning elements.
-     * Drops hidden elements with no interactive descendants and no known toggle-trigger.
-     * Replaces SVG icons with [SVG Icon: label] tokens.
-     * NOTE: distinct from delta — delta diffs across time, prune compresses the current snapshot once.
+     * Visual grounding mode (Set-of-Marks).
+     * - true  → always inject numbered badges + screenshot.
+     * - "auto" → activate only when DOM interactive count < 5 (canvas/WebGL pages).
+     * Use browser_click({ mark: N }) to interact with numbered marks.
      */
-    prune?: boolean;
+    visual?: boolean | "auto";
 }
-export declare function browserMap(session: CDP.Client, options: ReadOptions | undefined, targetId: string | undefined, config: Config): Promise<string>;
+export declare function browserMap(session: CDP.Client, options: ReadOptions | undefined, targetId: string | undefined, config: Config): Promise<string | BrowserMapResult>;
 export { browserMap as weaveRead };

package/dist/tools/read.js

@@ -9,10 +9,13 @@ import { cacheActionMap, getCachedActionMap, getRawCachedActionMap } from "../st
 import { startReadingSimulation } from "../overlay/ghost.js";
 import { suppressOverlays, restoreOverlays } from "../cdp/extension.js";
 import { sendToExtension } from "../cdp/helpers.js";
+import { hideWeaveTabOverlay, restoreWeaveTabOverlay } from "../cdp/helpers.js";
 import { analyzeVisualFallback } from "../intelligence/vision.js";
+import { marksSet } from "../intelligence/marks.js";
 import { getConfigAgentId } from "../config/loader.js";
-// Cap at 80 elements; form/modal groups are always kept, utility trimmed last.
-const MAX_ELEMENTS = 80;
+// Cap at 35 elements by default to keep prompt tokens lean.
+// Form, modal, and primary interactive elements are prioritized first.
+const MAX_ELEMENTS = 35;
 function withTimeout(p, ms) {
     return Promise.race([
         p,
@@ -26,33 +29,121 @@ function formatLite(el, activeElementId, changedIds) {
         parts.push("disabled");
     if (activeElementId && el.id === activeElementId)
         parts.push("FOCUSED");
-    if (el.viewport && el.viewport !== "visible")
-        parts.push(`offscreen:${el.viewport}`);
+    if (el.viewport && el.viewport !== "visible" && el.viewport !== "in-viewport") {
+        parts.push(el.viewport);
+    }
     // ── Value / checked / placeholder ──────────────────────────────────────────
     const role = (el.role || '').toLowerCase();
     const type = (el.type || '').toLowerCase();
-    // Radio / checkbox checked state — critical for quiz forms
+    // Radio / checkbox checked state
     if ((role === 'radio' || role === 'checkbox' || type === 'radio' || type === 'checkbox') && el.value !== undefined) {
         parts.push(el.value === 'true' || el.value === 'checked' ? '✓ checked' : '○ unchecked');
     }
     else if (el.value) {
-        // Truncate long values to avoid token waste
-        const v = el.value.length > 60 ? el.value.slice(0, 57) + '…' : el.value;
-        parts.push(`"${v}"`);
+        const v = el.value.length > 45 ? el.value.slice(0, 42) + '…' : el.value;
+        parts.push(`val:"${v}"`);
     }
     else if (el.placeholder) {
-        parts.push(`placeholder: "${el.placeholder}"`);
+        const p = el.placeholder.length > 35 ? el.placeholder.slice(0, 32) + '…' : el.placeholder;
+        parts.push(`ph:"${p}"`);
     }
-    // ── Type suffix for inputs (e.g. input[email], input[date]) ────────────────
-    const typeLabel = (role === 'textbox' || role === 'searchbox' || role === 'combobox') && type
+    // ── Type suffix for inputs ──────────────────────────────────────────────────
+    const typeLabel = (role === 'textbox' || role === 'searchbox' || role === 'combobox') && type && type !== 'text'
         ? `/${type}` : '';
-    // ── Link hint ───────────────────────────────────────────────────────────────
-    if (role === 'link' && el.hrefType && el.hrefType !== 'same-origin') {
-        parts.push(el.hrefType);
+    // ── Link hint (only if external) ───────────────────────────────────────────
+    if (role === 'link' && el.hrefType === 'external') {
+        parts.push('ext');
     }
     const state = parts.length > 0 ? ` (${parts.join(', ')})` : '';
     const changed = changedIds?.has(el.id) ? ' ★' : '';
-    return `[${el.id}] ${el.role}${typeLabel} "${el.label}"${state}${changed}`;
+    const label = el.label.length > 50 ? el.label.slice(0, 47) + '…' : el.label;
+    return `[${el.id}] ${el.role}${typeLabel} "${label}"${state}${changed}`;
+}
+// ─── 3.0 High-density formatter helpers ──────────────────────────────────────
+/** Collapse a cluster of nav/footer links into a compact summary token. */
+function collapseNavCluster(cluster) {
+    if (cluster.length === 0)
+        return '';
+    if (cluster.length === 1)
+        return formatLite(cluster[0]);
+    const first = cluster[0].label.slice(0, 20);
+    const last = cluster[cluster.length - 1].label.slice(0, 20);
+    const ids = `${cluster[0].id}…${cluster[cluster.length - 1].id}`;
+    return `[${ids}] ${cluster.length} links: "${first}" … "${last}"`;
+}
+/**
+ * Format the main element list using 3.0 semantics:
+ * - Active modals hoisted to the top
+ * - Items under shared container headings grouped
+ * - Nav link clusters (4+ consecutive) collapsed
+ */
+function formatMap3(elements, activeElementId, changedIds) {
+    const lines = [];
+    // ── 1. Hoist active modal elements ───────────────────────────────────────
+    const modalEls = elements.filter(e => e.isModal);
+    const mainEls = elements.filter(e => !e.isModal);
+    if (modalEls.length > 0) {
+        const modalTitle = modalEls[0].modalTitle || 'Dialog';
+        lines.push(`╔═ ACTIVE DIALOG: "${modalTitle}" ${'═'.repeat(Math.max(0, 30 - modalTitle.length))}╗`);
+        for (const el of modalEls) {
+            lines.push('  ' + formatLite(el, activeElementId, changedIds));
+        }
+        lines.push(`╚${'═'.repeat(42)}╝`);
+        if (mainEls.length > 0)
+            lines.push('');
+    }
+    // ── 2. Main elements with entity grouping + nav cluster collapsing ────────
+    const SECTION_LABEL = {
+        navigation: "── NAV ──────────────────",
+        main_content: "── MAIN ─────────────────",
+        form: "── FORM ─────────────────",
+        sidebar: "── SIDEBAR ──────────────",
+        modal: "── MODAL ────────────────",
+        utility: "── OTHER ────────────────",
+    };
+    let currentSection = null;
+    let currentContainer = null;
+    let navCluster = [];
+    const flushNavCluster = () => {
+        if (navCluster.length >= 4) {
+            lines.push(collapseNavCluster(navCluster));
+        }
+        else {
+            for (const ne of navCluster) {
+                lines.push(formatLite(ne, activeElementId, changedIds));
+            }
+        }
+        navCluster = [];
+    };
+    for (const el of mainEls) {
+        // Section header
+        if (el.group !== currentSection) {
+            flushNavCluster();
+            currentSection = el.group;
+            currentContainer = null;
+            lines.push(SECTION_LABEL[currentSection]);
+        }
+        // Accumulate nav/utility link cluster for potential collapsing
+        const isNavLink = (el.group === 'navigation' || el.group === 'utility') && el.role === 'link';
+        if (isNavLink) {
+            navCluster.push(el);
+            continue;
+        }
+        else {
+            flushNavCluster();
+        }
+        // Container/entity heading
+        const ctx = el.containerContext || null;
+        if (ctx && ctx !== currentContainer) {
+            currentContainer = ctx;
+            const header = ctx.length > 55 ? ctx.slice(0, 52) + '…' : ctx;
+            lines.push(`  ┌ ${header}`);
+        }
+        const indent = ctx ? '  │ ' : '';
+        lines.push(indent + formatLite(el, activeElementId, changedIds));
+    }
+    flushNavCluster();
+    return lines;
 }
 /** Full markdown table mode — only used when full:true is explicitly passed */
 function formatFull(elements, url, title, hint) {
@@ -83,6 +174,99 @@ function formatFull(elements, url, title, hint) {
     }
     return lines.join('\n');
 }
+/**
+ * Inject numbered Set-of-Marks badges over all interactive elements,
+ * take a screenshot, then strip the badges. Returns structured mark data
+ * and the annotated image. Zero page pollution after completion.
+ */
+async function buildVisualGrounding(session, targetId, elements) {
+    try {
+        // Build mark data from DOM elements that have coordinates
+        const domMarks = [];
+        for (const el of elements) {
+            if (el.x === undefined || el.y === undefined)
+                continue;
+            const w = el.width ?? 80;
+            const h = el.height ?? 24;
+            domMarks.push({
+                mark: domMarks.length + 1,
+                x: el.x,
+                y: el.y,
+                width: w,
+                height: h,
+                ref: el.id,
+                label: el.label || undefined,
+                type: el.role === "link" ? "link"
+                    : el.role === "button" ? "button"
+                        : (el.role === "textbox" || el.role === "searchbox" || el.role === "combobox") ? "input"
+                            : el.role === "canvas" ? "canvas_region"
+                                : "unknown",
+            });
+        }
+        // Also discover canvas elements that may not be in the DOM map
+        const { result: canvasRes } = await session.Runtime.evaluate({
+            expression: `(function(){
+        var canvases = [...document.querySelectorAll('canvas')];
+        return JSON.stringify(canvases.map(function(c){
+          var r = c.getBoundingClientRect();
+          return r.width > 0 && r.height > 0 ? {
+            x: Math.round(r.left + r.width/2), y: Math.round(r.top + r.height/2),
+            w: Math.round(r.width), h: Math.round(r.height)
+          } : null;
+        }).filter(Boolean));
+      })()`,
+            returnByValue: true,
+        }).catch(() => ({ result: { value: '[]' } }));
+        const extraCanvas = JSON.parse(canvasRes.value ?? '[]');
+        // Add canvas regions not already covered by a nearby DOM mark
+        for (const c of extraCanvas) {
+            const alreadyCovered = domMarks.some(m => Math.abs(m.x - c.x) < 40 && Math.abs(m.y - c.y) < 40);
+            if (!alreadyCovered) {
+                domMarks.push({ mark: domMarks.length + 1, x: c.x, y: c.y, width: c.w, height: c.h, type: "canvas_region" });
+            }
+        }
+        if (domMarks.length === 0)
+            return null;
+        // Inject badges — fixed-position, shadow-safe, above everything
+        const injectExpr = `(function(marks){
+      var BADGE_KEY = '__wt_som_badges__';
+      if (window[BADGE_KEY]) window[BADGE_KEY].forEach(function(d){ d.parentNode && d.parentNode.removeChild(d); });
+      window[BADGE_KEY] = [];
+      marks.forEach(function(m){
+        var d = document.createElement('div');
+        d.setAttribute('data-wt-som', String(m.mark));
+        d.style.cssText = 'position:fixed;left:'+(m.x - 10)+'px;top:'+(m.y - 10)+'px;width:20px;height:20px;z-index:2147483647;pointer-events:none;background:#7c3aed;color:#fff;font:bold 11px/20px monospace;text-align:center;border-radius:50%;box-shadow:0 1px 4px rgba(0,0,0,.5);';
+        d.textContent = String(m.mark);
+        document.documentElement.appendChild(d);
+        window[BADGE_KEY].push(d);
+      });
+      return true;
+    })(${JSON.stringify(domMarks)})`;
+        await session.Runtime.evaluate({ expression: injectExpr, returnByValue: true }).catch(() => { });
+        // Hide Weavetab overlay so badges are the only overlay in the shot
+        await hideWeaveTabOverlay(session).catch(() => { });
+        // Capture screenshot
+        const { data } = await session.Page.captureScreenshot({ format: 'jpeg', quality: 75 });
+        // Restore overlay
+        await restoreWeaveTabOverlay(session).catch(() => { });
+        // Strip badges immediately
+        await session.Runtime.evaluate({
+            expression: `(function(){ var b=window['__wt_som_badges__']; if(b) b.forEach(function(d){ d.parentNode&&d.parentNode.removeChild(d); }); window['__wt_som_badges__']=[]; })()`,
+            returnByValue: true,
+        }).catch(() => { });
+        // Persist in mark cache for browser_click({ mark: N }) resolution
+        const markMap = new Map();
+        for (const m of domMarks) {
+            markMap.set(m.mark, { x: m.x, y: m.y, width: m.width, height: m.height, ref: m.ref, label: m.label, type: m.type });
+        }
+        marksSet(targetId, markMap);
+        return { marks: domMarks, imageBase64: data };
+    }
+    catch (err) {
+        logDebug(`[buildVisualGrounding] failed: ${err}`);
+        return null;
+    }
+}
 export async function browserMap(session, options = {}, targetId = "default", config) {
     logDebug(`[browserMap] Initiating read for targetId: ${targetId}, options: ${JSON.stringify(options)}`);
     // ── Wait for DOM and Visual Stability ──────────────────────────────────────
@@ -174,7 +358,7 @@ export async function browserMap(session, options = {}, targetId = "default", co
                 query: options.query,
                 limit: options.limit,
                 deep: options.deep,
-                prune: options.prune,
+                prune: options.prune !== false,
             }, targetId), 8000).catch(() => _emptyMap);
             logDebug(`[browserMap] buildActionMap completed. Elements found: ${map.elements.length}`);
             // Auto-fallback to AX tree when DOM walker returns sparse or unlabeled-heavy results
@@ -335,19 +519,24 @@ export async function browserMap(session, options = {}, targetId = "default", co
     if (map.elements.length > 0 && newRefs.length === 0) {
         newRefs.push(...toRefEntries(map.elements));
     }
-    // ── Delta mode ─────────────────────────────────────────────────────────────
-    if (options.delta) {
+    // ── Delta / Auto-Delta mode ────────────────────────────────────────────────
+    // If delta is explicit OR if the user is re-reading the same page without full/force options,
+    // auto-delta returns only what changed (saving up to 95% prompt tokens).
+    const autoDeltaEligible = options.delta === true || (options.delta !== false &&
+        !options.full &&
+        !options.query &&
+        !options.scope);
+    if (autoDeltaEligible) {
         const richDiff = await computeRichDelta(targetId, map.url, map.elements);
-        if (richDiff) {
-            if ("delta_timeout" in richDiff) {
-                // Delta mode timed out — fall through to full read
-            }
-            else {
+        if (richDiff && !("delta_timeout" in richDiff)) {
+            const totalChanges = richDiff.added.length + richDiff.changed.length + richDiff.removed.length;
+            // Auto-delta: if 0 changes or <= 15 changes, return the diff directly
+            if (options.delta === true || totalChanges <= 15) {
                 const lines = [];
                 const header = `Page: ${map.title || map.url} | ${map.elements.length} elements`;
                 lines.push(header);
-                if (richDiff.added.length === 0 && richDiff.changed.length === 0 && richDiff.removed.length === 0 && (!richDiff.iframes || richDiff.iframes.length === 0)) {
-                    lines.push("stable — no changes detected");
+                if (totalChanges === 0 && (!richDiff.iframes || richDiff.iframes.length === 0)) {
+                    lines.push("stable — no DOM changes since last map (use existing refs)");
                 }
                 else {
                     for (const r of richDiff.added)
@@ -372,7 +561,6 @@ export async function browserMap(session, options = {}, targetId = "default", co
                 return lines.join("\n");
             }
         }
-        // No prior snapshot → fall through to full read
     }
     storeSnapshot(targetId, map.url, newRefs);
     seedRichSnapshot(targetId, map.url, map.elements);
@@ -428,15 +616,7 @@ export async function browserMap(session, options = {}, targetId = "default", co
             ? ` (pruned ${beforePruneCount - map.elements.length})`
             : ""));
     lines.push("");
-    // ── Semantic section grouping ────────────────────────────────────────────────
-    const SECTION_LABEL = {
-        navigation: "── NAV ──────────────────",
-        main_content: "── MAIN ─────────────────",
-        form: "── FORM ─────────────────",
-        sidebar: "── SIDEBAR ──────────────",
-        modal: "── MODAL ────────────────",
-        utility: "── OTHER ────────────────",
-    };
+    // ── Semantic section grouping (3.0) ────────────────────────────────────────
     let activeElementId;
     try {
         const { result } = await session.Runtime.evaluate({
@@ -452,36 +632,30 @@ export async function browserMap(session, options = {}, targetId = "default", co
         }
     }
     catch { }
-    let currentSection = null;
-    for (const el of capped) {
-        if (el.group !== currentSection) {
-            currentSection = el.group;
-            lines.push(SECTION_LABEL[currentSection]);
-        }
-        lines.push(formatLite(el, activeElementId, changedIds));
-    }
+    lines.push(...formatMap3(capped, activeElementId, changedIds));
     if (overflowCount > 0) {
         lines.push(`(+${overflowCount} more below fold — call browser_scroll down to reveal)`);
     }
     if (visualFallback)
         lines.push(visualFallback);
-    // Context-scoped tool hint — collapse 34-tool surface to ~12 relevant tools.
-    // Detected from map elements already computed above — zero extra latency.
-    const hasForm = map.elements.some(e => e.group === "form" || e.role === "input" || e.role === "combobox" || e.role === "checkbox" || e.role === "radio");
-    const hasSelect = map.elements.some(e => e.role === "combobox" || e.role === "listbox");
-    const hasCanvas = map.url?.includes("canvas") || false;
-    const isGithub = map.url?.includes("github.com") ?? false;
-    const baseTools = ["browser_click", "browser_type", "browser_key", "browser_scroll", "browser_wait", "browser_navigate", "browser_tabs"];
-    const formTools = hasForm ? ["browser_select", "browser_type_secret", "browser_find"] : [];
-    const githubTools = isGithub ? ["github_analyze", "github_read", "github_issues", "github_get_pr"] : [];
-    const canvasTools = hasCanvas ? ["browser_canvas", "browser_screenshot"] : ["browser_screenshot"];
-    const diagTools = ["browser_inspect", "browser_highlight", "browser_scrape", "browser_burst"];
-    const contextTools = [...new Set([...baseTools, ...formTools, ...githubTools, ...canvasTools, ...diagTools])];
-    lines.push(`\n_tools [${contextTools.join(", ")}]`);
     const output = lines.join("\n");
     const wordCount = output.split(/\s+/).length;
     startReadingSimulation(session, wordCount, config);
     sendToExtension(session, { type: 'Weavetab_STATE', hud: { action: '' } }).catch(() => { });
+    // ── Visual Grounding (Set-of-Marks) ────────────────────────────────────────
+    // Trigger when: visual:true (always) OR visual:"auto" (DOM element count < 5).
+    const shouldVisual = options.visual === true ||
+        (options.visual === "auto" && capped.length < 5);
+    if (shouldVisual) {
+        const vg = await buildVisualGrounding(session, targetId, map.elements);
+        if (vg) {
+            const markSummary = vg.marks
+                .map(m => `  [${m.mark}] ${m.type ?? "unknown"}${m.ref ? ` ${m.ref}` : ""} "${m.label ?? ""}" @(${m.x},${m.y})`)
+                .join("\n");
+            const annotatedText = output + `\n\n── Visual Marks (use browser_click({ mark: N })) ──\n${markSummary}`;
+            return { text: annotatedText, imageBase64: vg.imageBase64, marks: vg.marks };
+        }
+    }
     return output;
 }
 // Backward-compat alias