@quanta-intellect/vessel-browser 0.1.13 → 0.1.14

package/out/main/index.js

@@ -710,7 +710,8 @@ async function highlightOnPage(wc, resolvedSelector, text, label, durationMs, co
   if (text) {
     return wc.executeJavaScript(`
       (function() {
-        var searchText = ${JSON.stringify(text)};
+        var searchText = (${JSON.stringify(text)} || '').trim();
+        var foldedSearchText = searchText.toLowerCase();
         var solidColor = ${JSON.stringify(c.solid)};
         var bgColor = ${JSON.stringify(c.bg)};
         var labelBg = ${JSON.stringify(c.label)};
@@ -748,7 +749,11 @@ async function highlightOnPage(wc, resolvedSelector, text, label, durationMs, co
           });
           var n;
           while ((n = w.nextNode())) {
-            var idx = n.textContent.indexOf(searchText);
+            var haystack = n.textContent || '';
+            var idx = haystack.indexOf(searchText);
+            if (idx === -1 && foldedSearchText) {
+              idx = haystack.toLowerCase().indexOf(foldedSearchText);
+            }
             if (idx !== -1) {
               matches.push({ node: n, idx: idx });
               if (matches.length >= limit) break;
@@ -4571,6 +4576,158 @@ function createProvider(config) {
   }
   return new OpenAICompatProvider(normalized);
 }
+const CORRECT_HINT_RE = /\b(correct|right choice|this is correct|correct answer|pick this|select this|choose this|right answer)\b/i;
+const WRONG_HINT_RE = /\b(wrong|incorrect|not this|don't pick|do not pick|bad option|decoy)\b/i;
+function elementLabel(el) {
+  return el.text?.trim() || el.label?.trim() || el.value?.trim() || el.placeholder?.trim() || void 0;
+}
+function isOverlayAction(el) {
+  if (el.type === "button" || el.type === "link") return true;
+  if (el.type !== "input") return false;
+  return ["button", "submit", "radio", "checkbox"].includes(
+    (el.inputType || "").toLowerCase()
+  );
+}
+function isRadioOption(el) {
+  return el.role === "radio" || el.type === "input" && (el.inputType || "").toLowerCase() === "radio";
+}
+function normalizeAction(el) {
+  return {
+    index: el.index,
+    label: elementLabel(el),
+    selector: el.selector,
+    role: el.role,
+    labelSource: el.labelSource,
+    looksCorrect: el.looksCorrect !== void 0 ? el.looksCorrect : looksLikeCorrectOption(elementLabel(el))
+  };
+}
+function normalizeStoredAction(action) {
+  return {
+    label: action.label,
+    selector: action.selector,
+    role: action.kind === "radio" ? "radio" : void 0
+  };
+}
+function normalizeStoredRadioOption(option) {
+  return {
+    label: option.label,
+    selector: option.selector,
+    role: "radio",
+    labelSource: option.labelSource,
+    looksCorrect: option.looksCorrect !== void 0 ? option.looksCorrect : looksLikeCorrectOption(option.label)
+  };
+}
+function dedupeCandidates(actions) {
+  const seen = /* @__PURE__ */ new Set();
+  return actions.filter((action) => {
+    const key = [
+      action.selector || "",
+      action.label || "",
+      action.role || "",
+      action.labelSource || ""
+    ].join("::");
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function classifyOverlayKind(overlay, radioOptions) {
+  if (overlay.kind) {
+    return overlay.kind;
+  }
+  const haystack = [overlay.label, overlay.text, overlay.role].filter(Boolean).join(" ").toLowerCase();
+  if (/cookie|consent|privacy|gdpr|ccpa|onetrust|trustarc|cookiebot/.test(
+    haystack
+  )) {
+    return "cookie_consent";
+  }
+  if (radioOptions.length > 0) return "selection_modal";
+  if (overlay.role === "alertdialog" || /\b(alert|warning|error)\b/.test(haystack)) {
+    return "alert";
+  }
+  if (overlay.type === "dialog") return "dialog";
+  if (overlay.type === "modal") return "modal";
+  return "overlay";
+}
+function findAction(actions, matcher) {
+  return actions.find(
+    (action) => matcher.test((action.label || "").toLowerCase())
+  );
+}
+function looksLikeCorrectOption(label) {
+  const text = label?.trim();
+  if (!text) return void 0;
+  if (CORRECT_HINT_RE.test(text)) return true;
+  if (WRONG_HINT_RE.test(text)) return false;
+  return void 0;
+}
+function getBlockingOverlaySignature(overlays) {
+  return overlays.filter((overlay) => overlay.blocksInteraction).map(
+    (overlay) => [
+      overlay.kind,
+      overlay.selector || "",
+      overlay.label || "",
+      overlay.text || "",
+      overlay.actions.map((action) => `${action.selector || ""}:${action.label || ""}`).join("|"),
+      overlay.radioOptions.map((option) => `${option.selector || ""}:${option.label || ""}`).join("|")
+    ].join("::")
+  ).join("||");
+}
+function buildOverlayInventory(page) {
+  if (page.overlays.length === 0) return [];
+  return page.overlays.map((overlay) => {
+    const controls = dedupeCandidates([
+      ...page.interactiveElements.filter((el) => {
+        if (overlay.selector && el.parentOverlay === overlay.selector) {
+          return true;
+        }
+        return page.overlays.length === 1 && el.context === "dialog";
+      }).filter(isOverlayAction).map(normalizeAction),
+      ...(overlay.actions || []).map(normalizeStoredAction)
+    ]).filter((action) => action.label || action.selector);
+    const radioOptions = dedupeCandidates([
+      ...page.interactiveElements.filter((el) => {
+        if (!isRadioOption(el)) return false;
+        if (overlay.selector && el.parentOverlay === overlay.selector) {
+          return true;
+        }
+        return page.overlays.length === 1 && el.context === "dialog";
+      }).map(normalizeAction),
+      ...(overlay.radioOptions || []).map(normalizeStoredRadioOption)
+    ]).filter((action) => action.label || action.selector);
+    const kind = classifyOverlayKind(overlay, radioOptions);
+    const dismissAction = findAction(
+      controls,
+      /\b(close|dismiss|skip|cancel|reject|decline|no thanks|not now|maybe later|continue without)\b/
+    );
+    const acceptAction = findAction(
+      controls,
+      /\b(accept|allow|agree|got it|ok|okay|consent)\b/
+    );
+    const submitAction = findAction(
+      controls,
+      /\b(submit|continue|confirm|done|next|save|apply|finish)\b/
+    );
+    const correctOption = radioOptions.find(
+      (option) => option.looksCorrect === true
+    );
+    return {
+      type: overlay.type,
+      kind,
+      role: overlay.role,
+      label: overlay.label,
+      selector: overlay.selector,
+      text: overlay.text,
+      blocksInteraction: overlay.blocksInteraction,
+      actions: controls,
+      radioOptions,
+      dismissAction,
+      acceptAction,
+      submitAction,
+      correctOption
+    };
+  });
+}
 const MAX_CONTENT_LENGTH = 6e4;
 const MAX_STRUCTURED_ITEMS = 100;
 const LARGE_PAGE_HINT_THRESHOLD = 12e3;
@@ -4638,6 +4795,14 @@ function formatElementMeta(el) {
   if (el.pattern) {
     meta.push(`pattern="${el.pattern}"`);
   }
+  if (el.labelSource) {
+    meta.push(`source=${el.labelSource}`);
+  }
+  if (el.looksCorrect === true) {
+    meta.push("likely-correct");
+  } else if (el.looksCorrect === false) {
+    meta.push("likely-wrong");
+  }
   if (el.description) {
     meta.push(`desc="${el.description.slice(0, 80)}"`);
   }
@@ -4867,7 +5032,7 @@ function formatInteractiveElements(elements) {
     const parts = [prefix];
     if (el.type === "button") {
       parts.push(`[${el.text || "Button"}]`);
-      parts.push("button");
+      parts.push(el.role === "radio" ? "radio" : "button");
     } else if (el.type === "link") {
       parts.push(`[${el.text || "Link"}]`);
       parts.push("link");
@@ -4932,7 +5097,7 @@ function formatForms(forms) {
         ];
         if (field.type === "button") {
           fieldParts.push(`[${field.text || "Submit"}]`);
-          fieldParts.push("button");
+          fieldParts.push(field.role === "radio" ? "radio" : "button");
         } else if (field.type === "input") {
           fieldParts.push(`[${field.label || field.placeholder || "Input"}]`);
           fieldParts.push(field.inputType || "text");
@@ -4979,18 +5144,51 @@ function formatLandmarks(landmarks) {
 function formatViewport(page) {
   return `${page.viewport.width}x${page.viewport.height} at scroll (${page.viewport.scrollX}, ${page.viewport.scrollY})`;
 }
-function formatOverlays(overlays) {
-  if (overlays.length === 0) return "None detected";
-  const items = limitItems(overlays, 10);
+function formatOverlays(page) {
+  if (page.overlays.length === 0) return "None detected";
+  const items = limitItems(buildOverlayInventory(page), 10);
   return items.map((overlay) => {
-    const parts = [`- ${overlay.type}`];
-    if (overlay.role) parts.push(`role=${overlay.role}`);
-    if (overlay.blocksInteraction) parts.push("blocking");
-    if (overlay.label) parts.push(`label="${overlay.label.slice(0, 80)}"`);
-    if (overlay.text) parts.push(`text="${overlay.text.slice(0, 100)}"`);
-    return parts.join(" ");
+    const lines = [
+      [
+        `- ${overlay.kind}`,
+        overlay.role ? `role=${overlay.role}` : "",
+        overlay.blocksInteraction ? "blocking" : "",
+        overlay.label ? `label="${overlay.label.slice(0, 80)}"` : "",
+        overlay.text ? `text="${overlay.text.slice(0, 100)}"` : ""
+      ].filter(Boolean).join(" ")
+    ];
+    if (overlay.radioOptions.length > 0) {
+      const options = overlay.radioOptions.slice(0, 4).map((option) => {
+        const tags = [];
+        if (option.labelSource) tags.push(`source=${option.labelSource}`);
+        if (option.looksCorrect === true) tags.push("likely-correct");
+        if (option.looksCorrect === false) tags.push("likely-wrong");
+        const suffix = tags.length > 0 ? ` (${tags.join(", ")})` : "";
+        return `${option.label || option.selector || "radio"}${suffix}`;
+      }).join(" | ");
+      lines.push(`  options: ${options}`);
+    }
+    const actionLabels = [
+      overlay.dismissAction?.label ? `dismiss="${overlay.dismissAction.label}"` : "",
+      overlay.acceptAction?.label ? `accept="${overlay.acceptAction.label}"` : "",
+      overlay.submitAction?.label ? `submit="${overlay.submitAction.label}"` : ""
+    ].filter(Boolean);
+    if (actionLabels.length > 0) {
+      lines.push(`  actions: ${actionLabels.join(" ")}`);
+    }
+    return lines.join("\n");
   }).join("\n");
 }
+function getScrollHints(page) {
+  const candidates = page.interactiveElements.filter(
+    (el) => el.visible !== false && el.inViewport === false && el.context !== "nav" && el.context !== "footer" && el.context !== "sidebar" && el.blockedByOverlay !== true && (el.type === "input" || el.type === "textarea" || el.type === "select" || el.type === "button")
+  );
+  if (candidates.length === 0) return [];
+  const labels = limitItems(candidates, 3).map((el) => el.text || el.label || el.placeholder || el.type).filter(Boolean);
+  return [
+    `Scroll to reveal offscreen controls: ${labels.join(", ")}${candidates.length > labels.length ? ", ..." : ""}`
+  ];
+}
 function formatDormantOverlays(overlays) {
   if (overlays.length === 0) return "None detected";
   const items = limitItems(overlays, 10);
@@ -5327,6 +5525,10 @@ function buildScopedContext(page, mode) {
       if (page.excerpt) sections.push(`**Summary:** ${page.excerpt}`);
       const largePageHint = formatLargePageHint(page);
       if (largePageHint) sections.push(`**Reading Hint:** ${largePageHint}`);
+      const scrollHints = getScrollHints(page);
+      if (scrollHints.length > 0) {
+        sections.push(`**Scroll Hint:** ${scrollHints[0]}`);
+      }
       sections.push("");
       const summaryIntent = analyzePageIntent(page);
       if (summaryIntent) {
@@ -5395,6 +5597,10 @@ function buildScopedContext(page, mode) {
       sections.push(`**URL:** ${page.url}`);
       sections.push(`**Title:** ${page.title}`);
       sections.push(`**Viewport:** ${formatViewport(page)}`);
+      const interactivesScrollHints = getScrollHints(page);
+      if (interactivesScrollHints.length > 0) {
+        sections.push(`**Scroll Hint:** ${interactivesScrollHints[0]}`);
+      }
       sections.push("");
       const interactivesIntent = analyzePageIntent(page);
       if (interactivesIntent) {
@@ -5419,7 +5625,7 @@ function buildScopedContext(page, mode) {
       }
       if (page.overlays.length > 0) {
         sections.push("### Active Overlays");
-        sections.push(formatOverlays(page.overlays));
+        sections.push(formatOverlays(page));
         sections.push("");
       }
       if (dialogFocus) {
@@ -5457,6 +5663,10 @@ function buildScopedContext(page, mode) {
       sections.push(`**URL:** ${page.url}`);
       sections.push(`**Title:** ${page.title}`);
       sections.push(`**Viewport:** ${formatViewport(page)}`);
+      const visibleScrollHints = getScrollHints(page);
+      if (visibleScrollHints.length > 0) {
+        sections.push(`**Scroll Hint:** ${visibleScrollHints[0]}`);
+      }
       sections.push("");
       const formsHighlights = getHighlightsForPage(page.url);
       if (formsHighlights.length > 0) {
@@ -5476,7 +5686,7 @@ function buildScopedContext(page, mode) {
       }
       if (page.overlays.length > 0) {
         sections.push("### Active Overlays");
-        sections.push(formatOverlays(page.overlays));
+        sections.push(formatOverlays(page));
         sections.push("");
       }
       if (page.dormantOverlays.length > 0) {
@@ -5559,7 +5769,7 @@ function buildScopedContext(page, mode) {
       }
       if (page.overlays.length > 0) {
         sections.push("### Active Overlays");
-        sections.push(formatOverlays(page.overlays));
+        sections.push(formatOverlays(page));
         sections.push("");
       }
       if (dialogFocus) {
@@ -5744,6 +5954,10 @@ function buildStructuredContext(page) {
   sections.push(`**Viewport:** ${formatViewport(page)}`);
   if (page.byline) sections.push(`**Author:** ${page.byline}`);
   if (page.excerpt) sections.push(`**Summary:** ${page.excerpt}`);
+  const structuredScrollHints = getScrollHints(page);
+  if (structuredScrollHints.length > 0) {
+    sections.push(`**Scroll Hint:** ${structuredScrollHints[0]}`);
+  }
   sections.push("");
   const pageIntent = analyzePageIntent(page);
   if (pageIntent) {
@@ -5782,7 +5996,7 @@ function buildStructuredContext(page) {
   sections.push(formatLandmarks(page.landmarks));
   sections.push("");
   sections.push("### Active Overlays / Modals");
-  sections.push(formatOverlays(page.overlays));
+  sections.push(formatOverlays(page));
   sections.push("");
   sections.push("### Dormant Consent / Modal UI");
   sections.push(formatDormantOverlays(page.dormantOverlays));
@@ -5861,6 +6075,83 @@ function buildGeneralPrompt(query) {
     user: query
   };
 }
+const WRAPPING_QUOTES = /* @__PURE__ */ new Set(['"', "'", "`"]);
+function stripWrappingQuotes(value) {
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return trimmed;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if (first === last && WRAPPING_QUOTES.has(first)) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+function normalizeArrayItem(value) {
+  if (typeof value === "string") {
+    return stripWrappingQuotes(value).trim();
+  }
+  return String(value).trim();
+}
+function normalizeLooseString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = stripWrappingQuotes(value);
+  return normalized ? normalized : void 0;
+}
+function coerceOptionalNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  const normalized = normalizeLooseString(value);
+  if (!normalized) return void 0;
+  const parsed = Number(normalized);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function coerceStringArray(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalizeArrayItem).filter(Boolean);
+  }
+  const normalized = normalizeLooseString(value);
+  if (!normalized) return [];
+  try {
+    const parsed = JSON.parse(normalized);
+    if (Array.isArray(parsed)) {
+      return parsed.map(normalizeArrayItem).filter(Boolean);
+    }
+  } catch {
+  }
+  const lines = normalized.split(/\r?\n/).map((line) => line.replace(/^\s*[-*]\s+/, "").trim()).filter(Boolean);
+  if (lines.length > 1) {
+    return lines;
+  }
+  return [normalized];
+}
+function optionalNumberLikeSchema() {
+  return zod.z.preprocess(
+    (value) => {
+      if (value == null) return void 0;
+      return coerceOptionalNumber(value) ?? value;
+    },
+    zod.z.number().finite().optional()
+  );
+}
+function normalizedOptionalStringSchema() {
+  return zod.z.preprocess(
+    (value) => {
+      if (value == null) return void 0;
+      return normalizeLooseString(value) ?? value;
+    },
+    zod.z.string().optional()
+  );
+}
+function stringArrayLikeSchema() {
+  return zod.z.preprocess(
+    (value) => {
+      if (value == null) return value;
+      return coerceStringArray(value) ?? value;
+    },
+    zod.z.array(zod.z.string().min(1)).min(1)
+  );
+}
 const TOOL_DEFINITIONS = [
   // --- Tab Management ---
   {
@@ -5989,7 +6280,9 @@ const TOOL_DEFINITIONS = [
     description: "Scroll the page up or down.",
     inputSchema: {
       direction: zod.z.enum(["up", "down"]).describe("Scroll direction"),
-      amount: zod.z.number().optional().describe("Pixels to scroll (default 500)")
+      amount: optionalNumberLikeSchema().describe(
+        "Pixels to scroll (default 500)"
+      )
     },
     tier: 0,
     relevance: ["ARTICLE", "SEARCH_RESULTS", "PAGINATED_LIST"]
@@ -6034,6 +6327,17 @@ const TOOL_DEFINITIONS = [
     description: "Dismiss a modal, popup, newsletter gate, cookie banner, or overlay using common close/decline actions.",
     tier: 1
   },
+  {
+    name: "clear_overlays",
+    title: "Clear Overlays",
+    description: "Work through blocking overlays and modals until the page is unblocked, using overlay-specific heuristics for consent banners and radio-selection dialogs.",
+    inputSchema: {
+      strategy: zod.z.enum(["auto", "interactive"]).optional().describe(
+        'How aggressively to clear overlays. "auto" uses heuristics; "interactive" stops earlier when human judgment may be needed.'
+      )
+    },
+    tier: 1
+  },
   {
     name: "inspect_element",
     title: "Inspect Element",
@@ -6233,7 +6537,9 @@ const TOOL_DEFINITIONS = [
     inputSchema: {
       index: zod.z.number().optional().describe("Element index from page content to highlight"),
       selector: zod.z.string().optional().describe("CSS selector of element to highlight"),
-      text: zod.z.string().optional().describe("Text to find and highlight on the page (all occurrences)"),
+      text: normalizedOptionalStringSchema().describe(
+        "Text to find and highlight on the page (all occurrences)"
+      ),
       label: zod.z.string().optional().describe("Annotation label to display near the highlight"),
       durationMs: zod.z.number().optional().describe(
         "Auto-clear after this many milliseconds (omit for permanent)"
@@ -6258,7 +6564,7 @@ const TOOL_DEFINITIONS = [
       goal: zod.z.string().describe(
         "What this workflow accomplishes (e.g. 'Purchase item from Amazon')"
       ),
-      steps: zod.z.array(zod.z.string()).describe(
+      steps: stringArrayLikeSchema().describe(
         "Ordered list of step labels (e.g. ['Log in', 'Search', 'Select item', 'Checkout'])"
       )
     },
@@ -6495,6 +6801,7 @@ const ALWAYS_FAST_TOOL_NAMES = /* @__PURE__ */ new Set([
   "search",
   "scroll",
   "dismiss_popup",
+  "clear_overlays",
   "accept_cookies",
   "wait_for",
   "read_page",
@@ -6518,6 +6825,9 @@ function inferIntent(query) {
   }
   if (/\b(highlight|mark|annotate)\b/.test(lowered)) intents.add("highlight");
   if (/\b(table|csv|rows|columns)\b/.test(lowered)) intents.add("table");
+  if (/\b(overlay|modal|popup|consent|cookie|blocking ui)\b/.test(lowered)) {
+    intents.add("debug");
+  }
   if (/\b(debug|diagnose|what should i do|stuck|inspect)\b/.test(lowered)) {
     intents.add("debug");
   }
@@ -8683,6 +8993,93 @@ async function dismissPopup$1(wc) {
   }
   return initialBlocking > 0 ? "Could not dismiss the blocking popup automatically" : initialDormant > 0 ? `No active blocking popup detected. Found ${initialDormant} dormant consent/modal surface(s) in the DOM, likely geo-gated or inactive in this session.` : "No blocking popup detected";
 }
+function describeOverlayState(page) {
+  const inventory = buildOverlayInventory(page);
+  return {
+    inventory,
+    blocking: inventory.filter((overlay) => overlay.blocksInteraction).length,
+    total: inventory.length,
+    signature: getBlockingOverlaySignature(inventory)
+  };
+}
+async function clickOverlayCandidate(wc, action) {
+  if (!action?.selector) return null;
+  const result = await clickResolvedSelector$1(wc, action.selector);
+  return `${action.label || action.selector}: ${result}`;
+}
+async function clearOverlays(wc, strategy = "auto") {
+  const steps = [];
+  let cleared = 0;
+  const maxIterations = 8;
+  for (let iteration = 0; iteration < maxIterations; iteration += 1) {
+    const before = await extractContent(wc);
+    const beforeState = describeOverlayState(before);
+    const blockingOverlays = beforeState.inventory.filter(
+      (overlay2) => overlay2.blocksInteraction
+    );
+    if (blockingOverlays.length === 0) {
+      if (cleared === 0) return "No blocking overlays detected";
+      steps.push(`Overlays remaining: ${beforeState.total}`);
+      steps.push("Page still blocked: false");
+      return steps.join("\n");
+    }
+    const overlay = blockingOverlays[0];
+    let actionMessage = null;
+    if (overlay.kind === "cookie_consent") {
+      actionMessage = await clickOverlayCandidate(
+        wc,
+        overlay.acceptAction || overlay.dismissAction || overlay.actions[0]
+      );
+    } else if (overlay.kind === "selection_modal") {
+      if (!overlay.correctOption?.selector) {
+        if (strategy === "interactive") {
+          steps.push(
+            "Stopped: selection modal needs human judgment because no likely-correct option was detected."
+          );
+          steps.push(`Overlays remaining: ${beforeState.total}`);
+          steps.push("Page still blocked: true");
+          return steps.join("\n");
+        }
+      } else {
+        const optionResult = await clickOverlayCandidate(
+          wc,
+          overlay.correctOption
+        );
+        if (optionResult) {
+          actionMessage = `Selected likely-correct option: ${optionResult}`;
+          await sleep$1(120);
+          const submitResult = await clickOverlayCandidate(
+            wc,
+            overlay.submitAction || overlay.acceptAction
+          );
+          if (submitResult) {
+            actionMessage += `
+Submitted modal: ${submitResult}`;
+          }
+        }
+      }
+    }
+    if (!actionMessage) {
+      actionMessage = `Fallback popup handling: ${await dismissPopup$1(wc)}`;
+    }
+    steps.push(actionMessage);
+    await sleep$1(250);
+    const after = await extractContent(wc);
+    const afterState = describeOverlayState(after);
+    steps.push(`Overlays remaining: ${afterState.total}`);
+    steps.push(`Page still blocked: ${afterState.blocking > 0}`);
+    if (afterState.blocking === 0) {
+      return steps.join("\n");
+    }
+    const progressMade = afterState.blocking < beforeState.blocking || afterState.total !== beforeState.total || afterState.signature !== beforeState.signature;
+    if (progressMade) {
+      cleared += 1;
+      continue;
+    }
+    return steps.join("\n");
+  }
+  return steps.join("\n");
+}
 async function resolveSelector$1(wc, index, selector) {
   if (selector) return selector;
   if (index == null) return null;
@@ -9589,7 +9986,8 @@ async function getPostActionState$1(ctx, name) {
     "hover",
     "focus",
     "fill_form",
-    "inspect_element"
+    "inspect_element",
+    "clear_overlays"
   ];
   const tabActions = [
     "create_tab",
@@ -9639,6 +10037,7 @@ const KNOWN_TOOLS = /* @__PURE__ */ new Set([
   "focus",
   "set_ad_blocking",
   "dismiss_popup",
+  "clear_overlays",
   "read_page",
   "wait_for",
   "create_checkpoint",
@@ -9866,7 +10265,7 @@ async function executeAction(name, args, ctx) {
         }
         case "scroll": {
           if (!wc) return "Error: No active tab";
-          const pixels = args.amount || 500;
+          const pixels = coerceOptionalNumber(args.amount) ?? 500;
           const dir = args.direction === "up" ? -pixels : pixels;
           const result2 = await scrollPage$1(wc, dir);
           return `Scrolled ${args.direction} by ${pixels}px (moved ${Math.abs(result2.movedY)}px, now at y=${Math.round(result2.afterY)})`;
@@ -9911,6 +10310,11 @@ async function executeAction(name, args, ctx) {
           if (!wc) return "Error: No active tab";
           return dismissPopup$1(wc);
         }
+        case "clear_overlays": {
+          if (!wc) return "Error: No active tab";
+          const strategy = args.strategy === "interactive" ? "interactive" : "auto";
+          return clearOverlays(wc, strategy);
+        }
         case "read_page": {
           if (!wc) return "Error: No active tab";
           console.log("[Vessel read_page] starting extraction with 6s timeout");
@@ -10277,9 +10681,9 @@ ${truncated}`;
           if (!wc) return "Error: No active tab";
           const selector = await resolveSelector$1(wc, args.index, args.selector);
           const highlightColor = args.color || "yellow";
+          const highlightText = normalizeLooseString(args.text);
           const url = wc.getURL();
           if (url && url !== "about:blank") {
-            const highlightText = typeof args.text === "string" ? args.text : void 0;
             addHighlight(
               url,
               typeof selector === "string" ? selector : void 0,
@@ -10292,7 +10696,7 @@ ${truncated}`;
           return highlightOnPage(
             wc,
             selector,
-            args.text,
+            highlightText,
             args.label,
             args.durationMs,
             highlightColor
@@ -10305,7 +10709,7 @@ ${truncated}`;
         // --- Speedee System ---
         case "flow_start": {
           const goal = typeof args.goal === "string" ? args.goal : "";
-          const steps = Array.isArray(args.steps) ? args.steps.map(String) : [];
+          const steps = coerceStringArray(args.steps) ?? [];
           if (!goal || steps.length === 0)
             return "Error: goal and steps are required";
           const flow = ctx.runtime.startFlow(goal, steps, wc?.getURL());
@@ -10365,9 +10769,8 @@ ${flow.steps.map((s, i) => `  ${i === 0 ? "→" : " "} ${s.label}`).join("\n")}`
           const hasOverlays = page.overlays.some((o) => o.blocksInteraction);
           if (hasOverlays) {
             suggestions.push("BLOCKING OVERLAY detected — dismiss it first:");
-            suggestions.push(
-              "  → dismiss_popup or click on close/accept button"
-            );
+            suggestions.push("  → clear_overlays for stacked modals");
+            suggestions.push("  → or dismiss_popup for a single popup");
             suggestions.push("");
           }
           if (hasPasswordField) {
@@ -10931,6 +11334,8 @@ Instructions:
 - When you only need detail on one product/result/card/form section, use inspect_element instead of reading the page.
 - Escalate page reads progressively: read_page(mode="visible_only"), read_page(mode="results_only"), read_page(mode="forms_only"), read_page(mode="summary"), or read_page(mode="text_only") depending on what you need.
 - Use read_page(mode="debug") only as a last resort when the narrower modes are insufficient.
+- VIEWPORT SYNC: Treat scrolling as a real, user-visible browser action. If you say you are going to scroll, call scroll or scroll_to_element so the human sees the page move too.
+- read_page inspects the page without moving the human-visible viewport. Do not describe read_page as scrolling. If you want more context without changing the user's view, say you're reading the page; if you want the user to follow along lower on the page, actually scroll first.
 - After clicking or submitting a form, prefer wait_for on a specific result signal or a narrow read_page mode. Do not jump straight to read_page(mode="debug").
 - If the user says they highlighted or selected text, use read_page before falling back to screenshots because it includes active selection and visible unsaved highlights.
 - If a page behaves abnormally or key UI fails to load, consider disabling ad blocking for that tab and reloading before retrying.
@@ -13995,7 +14400,9 @@ ${buildScopedContext(pageContent, mode)}`;
       description: "Scroll the page up or down.",
       inputSchema: {
         direction: zod.z.enum(["up", "down"]).describe("Scroll direction"),
-        amount: zod.z.number().optional().describe("Pixels to scroll (default 500)")
+        amount: optionalNumberLikeSchema().describe(
+          "Pixels to scroll (default 500)"
+        )
       }
     },
     async ({ direction, amount }) => {
@@ -14007,7 +14414,7 @@ ${buildScopedContext(pageContent, mode)}`;
         "scroll",
         { direction, amount },
         async () => {
-          const pixels = amount || 500;
+          const pixels = coerceOptionalNumber(amount) ?? 500;
           const dir = direction === "up" ? -pixels : pixels;
           const result = await scrollPage(tab.view.webContents, dir);
           return `Scrolled ${direction} by ${pixels}px (moved ${Math.abs(result.movedY)}px, now at y=${Math.round(result.afterY)})`;
@@ -14033,6 +14440,32 @@ ${buildScopedContext(pageContent, mode)}`;
       );
     }
   );
+  server.registerTool(
+    "vessel_clear_overlays",
+    {
+      title: "Clear Overlays",
+      description: "Work through blocking overlays and modals until the page is unblocked, using overlay-specific heuristics for consent banners and radio-selection dialogs.",
+      inputSchema: {
+        strategy: zod.z.enum(["auto", "interactive"]).optional().describe(
+          'How aggressively to clear overlays. "auto" uses heuristics; "interactive" stops earlier when human judgment may be needed.'
+        )
+      }
+    },
+    async ({ strategy }) => {
+      const tab = tabManager.getActiveTab();
+      if (!tab) return asTextResponse("Error: No active tab");
+      return withAction(
+        runtime,
+        tabManager,
+        "clear_overlays",
+        { strategy: strategy || "auto" },
+        async () => clearOverlays(
+          tab.view.webContents,
+          strategy === "interactive" ? "interactive" : "auto"
+        )
+      );
+    }
+  );
   server.registerTool(
     "vessel_wait_for",
     {
@@ -14332,7 +14765,7 @@ To analyze visually, call vision_analyze with image_url="${screenshotPath}"`
       inputSchema: {
         index: zod.z.number().optional().describe("Element index from extracted content to highlight"),
         selector: zod.z.string().optional().describe("CSS selector of element to highlight"),
-        text: zod.z.string().optional().describe(
+        text: normalizedOptionalStringSchema().describe(
           "Text to find and highlight on the page (highlights all occurrences)"
         ),
         label: zod.z.string().optional().describe("Optional annotation label to display near the highlight"),
@@ -14350,18 +14783,27 @@ To analyze visually, call vision_analyze with image_url="${screenshotPath}"`
     async ({ index, selector, text, label, durationMs, persist, color }) => {
       const tab = tabManager.getActiveTab();
       if (!tab) return asTextResponse("Error: No active tab");
+      const normalizedText = normalizeLooseString(text);
       return withAction(
         runtime,
         tabManager,
         "highlight",
-        { index, selector, text, label, durationMs, persist, color },
+        {
+          index,
+          selector,
+          text: normalizedText,
+          label,
+          durationMs,
+          persist,
+          color
+        },
         async () => {
           const wc = tab.view.webContents;
           const resolvedSelector = await resolveSelector(wc, index, selector);
           const result = await highlightOnPage(
             wc,
             resolvedSelector,
-            text,
+            normalizedText,
             label,
             durationMs,
             color
@@ -14371,7 +14813,7 @@ To analyze visually, call vision_analyze with image_url="${screenshotPath}"`
             addHighlight(
               url,
               resolvedSelector ?? void 0,
-              text,
+              normalizedText,
               label,
               color,
               "agent"
@@ -15243,16 +15685,17 @@ ${JSON.stringify(otherHighlights, null, 2)}`
         goal: zod.z.string().describe(
           "What this workflow accomplishes (e.g. 'Purchase item from Amazon')"
         ),
-        steps: zod.z.array(zod.z.string()).describe(
+        steps: stringArrayLikeSchema().describe(
           "Ordered list of step labels (e.g. ['Log in', 'Search', 'Select item', 'Checkout'])"
         )
       }
     },
     async ({ goal, steps }) => {
+      const normalizedSteps = coerceStringArray(steps) ?? [];
       const tab = tabManager.getActiveTab();
       const flow = runtime.startFlow(
         goal,
-        steps,
+        normalizedSteps,
         tab?.view.webContents.getURL()
       );
       return asTextResponse(
@@ -15348,9 +15791,8 @@ ${flow.steps.map((s, i) => `  ${i === 0 ? "→" : " "} ${s.label}`).join("\n")}`
       const hasOverlays = page.overlays.some((o) => o.blocksInteraction);
       if (hasOverlays) {
         suggestions.push("⚠ BLOCKING OVERLAY detected — dismiss it first:");
-        suggestions.push(
-          "  → vessel_dismiss_popup or vessel_click on close/accept button"
-        );
+        suggestions.push("  → vessel_clear_overlays for stacked modals");
+        suggestions.push("  → or vessel_dismiss_popup for a single popup");
         suggestions.push("");
       }
       if (hasPasswordField) {