safari-pilot 0.1.29 → 0.1.33

package/.claude-plugin/commands/stats.md

@@ -0,0 +1,5 @@
+---
+description: Local metrics summary over ~/.safari-pilot/trace.ndjson — per-tool count/error-rate/p50/p95, top errors, top domains.
+---
+
+!`node "${CLAUDE_PLUGIN_ROOT}/dist/cli/stats.js" $ARGUMENTS`

package/.claude-plugin/plugin.json

@@ -8,7 +8,8 @@
   "components": {
     "commands": [
       "commands/start.md",
-      "commands/stop.md"
+      "commands/stop.md",
+      "commands/stats.md"
     ],
     "mcpServers": {
       "safari": {
@@ -20,7 +21,16 @@
         }
       }
     },
-    "skills": ["skills/safari-pilot/SKILL.md"],
+    "skills": [
+      "skills/safari-pilot/SKILL.md",
+      "skills/login.SKILL.md",
+      "skills/paginate-and-scrape.SKILL.md",
+      "skills/robust-form-fill.SKILL.md",
+      "skills/evidence-grounded-screenshot.SKILL.md",
+      "skills/dismiss-overlays-recovery.SKILL.md",
+      "skills/visible-evidence-grounding.SKILL.md",
+      "skills/temporal-substitution.SKILL.md"
+    ],
     "hooks": [
       {
         "event": "SessionStart",

package/README.md

@@ -120,19 +120,24 @@ Monitor news.ycombinator.com for any post about our company
 Open my X.com bookmarks and extract the top 5 posts with author profiles
 ```
 
-## Tool Catalog (82 Tools)
+## Tool Catalog (88 Tools)
 
 ### Navigation (7)
 `safari_navigate` | `safari_navigate_back` | `safari_navigate_forward` | `safari_reload` | `safari_new_tab` | `safari_close_tab` | `safari_list_tabs`
 
-### Interaction (11)
-`safari_click` | `safari_double_click` | `safari_fill` | `safari_select_option` | `safari_check` | `safari_hover` | `safari_type` | `safari_press_key` | `safari_scroll` | `safari_drag` | `safari_handle_dialog`
+### Interaction (12)
+`safari_click` | `safari_double_click` | `safari_fill` | `safari_select_option` | `safari_check` | `safari_hover` | `safari_type` | `safari_press_key` | `safari_scroll` | `safari_scroll_to_element` | `safari_drag` | `safari_handle_dialog`
+
+`safari_scroll_to_element` (v0.1.31) scrolls a specific element into the visible viewport via {selector, text, role+name}. Open shadow root penetration; same-origin iframe traversal. Returns matched-node descriptor + viewport state + multi-match candidates.
+
+### Overlays (1)
+`safari_dismiss_overlays` — detects and dismisses ~14 known overlay patterns (cookie-consent, registration-wall, app-install, paywall) using a curated allowlist with a two-signal-per-pattern rule. id-only sanitized response. Six safety mitigations including a kill switch (`SAFARI_PILOT_DISABLE_OVERLAY_DISMISS=true`) and paywall opt-IN-by-default flag (`SAFARI_PILOT_ENABLE_PAYWALL_DISMISS=true`). New in v0.1.31.
 
 ### File Upload (1)
 `safari_file_upload` — programmatic upload to standard `<input type=file>` elements, including hidden inputs behind `<label>` (use `force: true`). 25 MiB / file × 4 / call. Path B architecture: out-of-band byte transport via daemon staging → extension fetch. Does NOT support drag-and-drop dropzones, custom pickers, or native OS dialogs.
 
-### Extraction (7)
-`safari_snapshot` | `safari_get_text` | `safari_get_html` | `safari_get_attribute` | `safari_evaluate` | `safari_take_screenshot` | `safari_get_console_messages`
+### Extraction (8)
+`safari_snapshot` | `safari_get_text` | `safari_get_html` | `safari_get_attribute` | `safari_evaluate` | `safari_take_screenshot` | `safari_get_console_messages` | `safari_query_all`
 
 ### Network (10)
 `safari_list_network_requests` | `safari_get_network_request` | `safari_intercept_requests` | `safari_network_throttle` | `safari_network_offline` | `safari_mock_request` | `safari_websocket_listen` | `safari_websocket_filter` | `safari_dump_har` | `safari_route_from_har`
@@ -182,6 +187,31 @@ Open my X.com bookmarks and extract the top 5 posts with author profiles
 ### System (2)
 `safari_health_check` | `safari_emergency_stop`
 
+### Discovery (1)
+`safari_tool_search` — query the registered tool index with natural-language intent strings; returns ranked tool descriptors. Reduces total-tokens cost when the agent needs a specific capability without preloading the full tool surface.
+
+### Skills (2)
+`safari_run_skill` | `safari_list_skills` — invoke or enumerate plugin skills from `skills/`. Sub-step dispatch bypasses the security pipeline (the outer `safari_run_skill` call is fully secured; inner steps are not individually audited — accepted trade-off for nested skill flows).
+
+## Plugin Skills (8)
+
+`safari_run_skill` and `safari_list_skills` consume `skills/*.SKILL.md` files. Eight ship today:
+
+- **safari-pilot** (base) — entry-point overview of the tool surface.
+- **login** — credential-flow strategy.
+- **paginate-and-scrape** — multi-page extraction recipe.
+- **robust-form-fill** — defensive form-fill with verify-on-readback.
+- **evidence-grounded-screenshot** *(v0.1.31)* — procedural workflow: dismiss → scroll → screenshot.
+- **dismiss-overlays-recovery** *(v0.1.31)* — strategy for recovering when extraction returns suspiciously short content.
+- **visible-evidence-grounding** *(v0.1.31)* — strategy for grounding factual answers in current visible page state, not prior knowledge.
+- **temporal-substitution** *(v0.1.31)* — strategy for substituting past-relative dates ("yesterday", "January 2024") with the nearest available equivalent today; pairs with the SessionStart hook's `Current date: YYYY-MM-DD` injection.
+
+## Slash Commands
+
+- `/safari-pilot:start` — start the daemon + open Safari.
+- `/safari-pilot:stop` — graceful shutdown.
+- `/safari-pilot:stats` *(v0.1.31)* — local-only metrics summary over `~/.safari-pilot/trace.ndjson`. Per-tool count/error-rate/p50/p95, top errors, top domains. Supports `--since 7d|24h|all`, `--by-tool`, `--by-error`, `--by-domain`, `--tail`, `--json`. Test-only: `SAFARI_PILOT_TRACE_OVERRIDE=<path>` env var points at a fake trace file for hermeticity.
+
 ## Architecture
 
 ```

package/bin/Safari Pilot.app/Contents/Info.plist

@@ -23,13 +23,13 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.1.29</string>
+	<string>0.1.33</string>
 	<key>CFBundleSupportedPlatforms</key>
 	<array>
 		<string>MacOSX</string>
 	</array>
 	<key>CFBundleVersion</key>
-	<string>202605060230</string>
+	<string>202605121922</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>

package/bin/Safari Pilot.app/Contents/PlugIns/Safari Pilot Extension.appex/Contents/Info.plist

@@ -19,13 +19,13 @@
 	<key>CFBundlePackageType</key>
 	<string>XPC!</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.1.29</string>
+	<string>0.1.33</string>
 	<key>CFBundleSupportedPlatforms</key>
 	<array>
 		<string>MacOSX</string>
 	</array>
 	<key>CFBundleVersion</key>
-	<string>202605060230</string>
+	<string>202605121922</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>

package/bin/Safari Pilot.app/Contents/PlugIns/Safari Pilot Extension.appex/Contents/Resources/background.js

@@ -368,6 +368,56 @@ async function executeCommand(cmd) {
     return result;
   }
 
+  // safari_take_screenshot — capture the visible viewport of the target tab
+  // via browser.tabs.captureVisibleTab. Triggered by the __SP_TAKE_SCREENSHOT__
+  // sentinel from src/tools/extraction.ts. Briefly activates target tab in its
+  // window (no Safari app activation), captures, restores prior active tab.
+  if (cmd.script === '__SP_TAKE_SCREENSHOT__') {
+    let prevActiveTabId = null;
+    try {
+      if (tab.windowId == null) {
+        throw { name: 'WINDOW_CLOSED', message: 'tab.windowId missing' };
+      }
+
+      // Snapshot the previous active tab so we can restore it.
+      const prevActive = await browser.tabs.query({ windowId: tab.windowId, active: true });
+      prevActiveTabId = prevActive[0]?.id ?? null;
+
+      // Activate the target tab if it isn't already active. tabs.update resolves
+      // before Safari's internal active-tab state settles, so we verify by
+      // polling tabs.query before the capture (TOCTOU narrows but doesn't close).
+      if (prevActiveTabId !== tab.id) {
+        await browser.tabs.update(tab.id, { active: true });
+        let activated = false;
+        for (let attempt = 0; attempt < 5; attempt++) {
+          await new Promise((r) => setTimeout(r, 40));
+          const check = await browser.tabs.query({ windowId: tab.windowId, active: true });
+          if (check[0]?.id === tab.id) { activated = true; break; }
+        }
+        if (!activated) {
+          throw { name: 'CAPTURE_RACE', message: 'target tab did not become active within 200ms' };
+        }
+      }
+
+      const dataUrl = await browser.tabs.captureVisibleTab(tab.windowId, { format: 'png' });
+      const commaIdx = dataUrl.indexOf(',');
+      const base64 = commaIdx >= 0 ? dataUrl.slice(commaIdx + 1) : dataUrl;
+
+      const result = { ok: true, value: base64 };
+      await updatePendingEntry(commandId, { status: 'completed', result });
+      return result;
+    } catch (e) {
+      const errName = e?.name && typeof e.name === 'string' ? e.name : 'CAPTURE_FAILED';
+      const result = { ok: false, error: { name: errName, message: e?.message ?? String(e) } };
+      await updatePendingEntry(commandId, { status: 'completed', result });
+      return result;
+    } finally {
+      if (prevActiveTabId != null && prevActiveTabId !== tab.id) {
+        try { await browser.tabs.update(prevActiveTabId, { active: true }); } catch { /* tab may have closed */ }
+      }
+    }
+  }
+
   // 5A.1 phase-0: file upload probe sentinel — dispatched via the storage bus
   // to content-isolated.js (Test A: content-script fetch; Test B: File structured-
   // clone). Unlike cookie/DNR sentinels (which execute entirely in background.js),

package/bin/Safari Pilot.app/Contents/PlugIns/Safari Pilot Extension.appex/Contents/Resources/content-main.js

@@ -550,6 +550,161 @@
             break;
           }
           case 'execute_script': {
+            // ── EARLY INTERCEPT: __SP_SCROLL_TO_ELEMENT__:<json> (v0.1.31 Task 5) ──
+            // Sentinel-routed handler for safari_scroll_to_element. Sits at the
+            // top of the case so it runs before commandId caching and the
+            // _Function compile path. Errors thrown here flow through the outer
+            // catch → respond(false, { error: { message, name } }), which the
+            // daemon (ExtensionBridge.handleResult) maps to error.code on the
+            // Node side via StructuredError.code = error.name.
+            if (typeof params.script === 'string' && params.script.startsWith('__SP_SCROLL_TO_ELEMENT__:')) {
+              const args = JSON.parse(params.script.slice('__SP_SCROLL_TO_ELEMENT__:'.length));
+              const sel = args.selector;
+              const txt = args.text;
+              const role = args.role;
+              const name = args.name;
+              const nth = typeof args.nth === 'number' ? args.nth : 0;
+              const behavior = args.behavior === 'smooth' ? 'smooth' : 'instant';
+              const L = window.__SP_LOCATOR__;
+              if (!L) {
+                throw Object.assign(
+                  new Error('locator.js not loaded in MAIN world'),
+                  { name: 'TARGET_NOT_FOUND' },
+                );
+              }
+              const candidates = L.resolveScrollTargets({ selector: sel, text: txt, role, name });
+              if (candidates.length === 0) {
+                const hidden = L.resolveScrollTargets({ selector: sel, text: txt, role, name, includeHidden: true });
+                if (hidden.length > 0) {
+                  throw Object.assign(
+                    new Error('element exists but is not visible (display:none, hidden, or in closed <details>)'),
+                    { name: 'TARGET_HIDDEN' },
+                  );
+                }
+                throw Object.assign(
+                  new Error('no element matched the provided locator'),
+                  { name: 'TARGET_NOT_FOUND' },
+                );
+              }
+              if (nth >= candidates.length) {
+                throw Object.assign(
+                  new Error('nth=' + nth + ' out of range (matchCount=' + candidates.length + ')'),
+                  { name: 'INVALID_PARAMS' },
+                );
+              }
+              const target = candidates[nth];
+              const fromY = window.scrollY;
+              target.element.scrollIntoView({ behavior, block: 'center', inline: 'nearest' });
+              await L.waitForScrollSettle(500);
+              const matchedNode = L.serializeNode(target.element);
+              const allMatches = candidates.length > 1
+                ? candidates.slice(0, 5).map((c) => L.serializeNode(c.element, true))
+                : undefined;
+              result = {
+                scrolledTo: { strategy: target.strategy, matchedNode, matchCount: candidates.length, allMatches },
+                viewport: { scrollX: window.scrollX, scrollY: window.scrollY, innerWidth: window.innerWidth, innerHeight: window.innerHeight },
+                scrolledFromY: fromY,
+              };
+              break;
+            }
+            // ── EARLY INTERCEPT: __SP_DISMISS_OVERLAYS__:<json> (v0.1.31 Task 10) ──
+            // Sentinel-routed handler for safari_dismiss_overlays. Same Option A shape
+            // as the scroll intercept above: success → result = {...}; break;
+            // failure → throw with error.name → daemon maps to error.code.
+            if (typeof params.script === 'string' && params.script.startsWith('__SP_DISMISS_OVERLAYS__:')) {
+              try {
+                const args = JSON.parse(params.script.slice('__SP_DISMISS_OVERLAYS__:'.length));
+                const { categories, patterns, killSwitchEngaged, paywallEnabled } = args;
+                const L = window.__SP_LOCATOR__;
+                if (!L) {
+                  throw Object.assign(
+                    new Error('locator.js not loaded in MAIN world'),
+                    { name: 'NO_LOCATOR' },
+                  );
+                }
+                if (killSwitchEngaged) {
+                  result = {
+                    dismissed: [],
+                    skipped: [{ reason: 'kill_switch_engaged' }],
+                    overlaysAtStart: 0,
+                    overlaysAtEnd: 0,
+                  };
+                  break;
+                }
+                const dismissed = [];
+                const skipped = [];
+                let overlaysAtStart = 0;
+                const filtered = (patterns || []).filter((p) => !categories || categories.includes(p.category));
+                for (const pattern of filtered) {
+                  // Paywall opt-in gate
+                  if (pattern.category === 'paywall' && !paywallEnabled) {
+                    const root = L.findPatternRoot(pattern);
+                    if (root) {
+                      const sel = pattern.signals.find((s) => s.type === 'selector');
+                      skipped.push({
+                        reason: 'paywall_opt_in_required',
+                        candidate: { selector: sel ? sel.value : undefined, category: 'paywall' },
+                      });
+                    }
+                    continue;
+                  }
+                  const root = L.findPatternRoot(pattern);
+                  if (!root) {
+                    const sel = pattern.signals.find((s) => s.type === 'selector');
+                    skipped.push({
+                      reason: 'allowlist_miss',
+                      candidate: { selector: sel ? sel.value : undefined, category: pattern.category },
+                    });
+                    continue;
+                  }
+                  overlaysAtStart++;
+                  try {
+                    const verifyResult = await L.dismissPattern(pattern, root);
+                    if (!verifyResult.verified) {
+                      const sel = pattern.signals.find((s) => s.type === 'selector');
+                      skipped.push({
+                        reason: 'verify_failed_overlay_persists',
+                        candidate: { selector: sel ? sel.value : undefined, hint: pattern.id },
+                      });
+                    } else {
+                      const sel = pattern.signals.find((s) => s.type === 'selector');
+                      dismissed.push({
+                        category: pattern.category,
+                        id: pattern.id,
+                        selector: sel ? sel.value : '',
+                        action: pattern.dismiss.action,
+                        site: window.location.hostname,
+                        verified: true,
+                      });
+                    }
+                  } catch (e) {
+                    skipped.push({
+                      reason: 'click_failed',
+                      candidate: { hint: String((e && e.message) || e) },
+                    });
+                  }
+                }
+                // Recount remaining
+                let remaining = 0;
+                for (const p of filtered) { if (L.findPatternRoot(p)) remaining++; }
+                result = {
+                  dismissed,
+                  skipped,
+                  overlaysAtStart,
+                  overlaysAtEnd: remaining,
+                };
+                break;
+              } catch (e) {
+                // Re-throw with NO_LOCATOR semantic (any unexpected failure surfaces here).
+                // If it already has a .name, preserve it; otherwise tag NO_LOCATOR.
+                if (e && e.name && e.name !== 'Error') throw e;
+                throw Object.assign(
+                  new Error(String((e && e.message) || e)),
+                  { name: 'NO_LOCATOR' },
+                );
+              }
+            }
+            // ── existing default execute_script path ──
             const commandId = params.commandId;
             if (commandId && window.__safariPilotExecutedCommands.has(commandId)) {
               const cached = window.__safariPilotExecutedCommands.get(commandId);

package/bin/Safari Pilot.app/Contents/PlugIns/Safari Pilot Extension.appex/Contents/Resources/locator.js

@@ -0,0 +1,294 @@
+// extension/locator.js — MAIN-world helpers for safari_scroll_to_element
+// (v0.1.31 Task 5) and forthcoming safari_dismiss_overlays (v0.1.31 Task 10).
+//
+// This file is registered in manifest.json's MAIN-world content_scripts
+// BEFORE content-main.js, so window.__SP_LOCATOR__ is guaranteed to exist
+// by the time content-main.js processes any execute_script sentinel.
+//
+// Helpers:
+//   querySelectorWithShadow(selector, root) — single-element search through
+//     open shadow roots; returns first match or null.
+//   resolveScrollTargets({ selector, text, role, name, includeHidden }) —
+//     precedence selector > role+name > text; same-origin iframe traversal;
+//     visibility filter; returns [{ element, strategy }, ...].
+//   waitForScrollSettle(maxMs) — RAF-driven idle detection (50ms grace, capped
+//     at maxMs). Resolves when window.scrollY stops changing.
+//   serializeNode(el, shallow) — { tagName, role, text(80c), xpath, bbox }.
+
+(function () {
+  'use strict';
+
+  // ── querySelectorWithShadow: traverses open shadow roots ─────────────────
+  function querySelectorWithShadow(selector, root) {
+    root = root || document;
+    const direct = root.querySelector(selector);
+    if (direct) return direct;
+    const stack = [root];
+    while (stack.length) {
+      const node = stack.pop();
+      const children = node.querySelectorAll ? node.querySelectorAll('*') : [];
+      for (const el of children) {
+        if (el.shadowRoot && el.shadowRoot.mode === 'open') {
+          const found = el.shadowRoot.querySelector(selector);
+          if (found) return found;
+          stack.push(el.shadowRoot);
+        }
+      }
+    }
+    return null;
+  }
+
+  // ── resolveInDoc: helper for same-origin iframe traversal ───────────────
+  function resolveInDoc(doc, opts) {
+    const { selector, text, role, name } = opts;
+    const out = [];
+    if (selector) {
+      out.push(...Array.from(doc.querySelectorAll(selector)));
+    } else if (role) {
+      const m = Array.from(doc.querySelectorAll('[role="' + role + '"]'));
+      if (name) {
+        const needle = name.toLowerCase();
+        for (const el of m) {
+          const accName = (el.getAttribute('aria-label') || el.textContent || '').trim().toLowerCase();
+          if (accName.includes(needle)) out.push(el);
+        }
+      } else {
+        out.push(...m);
+      }
+    } else if (text) {
+      const needle = text.toLowerCase().replace(/\s+/g, ' ').trim();
+      const all = doc.querySelectorAll('body *:not(script):not(style)');
+      for (const el of all) {
+        const directText = Array.from(el.childNodes)
+          .filter((n) => n.nodeType === 3)
+          .map((n) => n.textContent || '')
+          .join('')
+          .toLowerCase()
+          .replace(/\s+/g, ' ')
+          .trim();
+        if (directText.includes(needle)) out.push(el);
+      }
+    }
+    return out;
+  }
+
+  // ── resolveScrollTargets: precedence selector > role+name > text ─────────
+  function resolveScrollTargets(opts) {
+    opts = opts || {};
+    const { selector, text, role, name } = opts;
+    const includeHidden = opts.includeHidden === true;
+    let candidates = [];
+    let strategy = null;
+
+    if (selector) {
+      strategy = 'selector';
+      candidates = Array.from(document.querySelectorAll(selector));
+    } else if (role) {
+      strategy = 'role';
+      const roleMatches = Array.from(document.querySelectorAll('[role="' + role + '"]'));
+      if (name) {
+        const needle = name.toLowerCase();
+        candidates = roleMatches.filter((el) => {
+          const accName = (el.getAttribute('aria-label') || el.textContent || '').trim().toLowerCase();
+          return accName.includes(needle);
+        });
+      } else {
+        candidates = roleMatches;
+      }
+    } else if (text) {
+      strategy = 'text';
+      const needle = text.toLowerCase().replace(/\s+/g, ' ').trim();
+      const all = document.querySelectorAll('body *:not(script):not(style)');
+      candidates = Array.from(all).filter((el) => {
+        const directText = Array.from(el.childNodes)
+          .filter((n) => n.nodeType === 3)
+          .map((n) => n.textContent || '')
+          .join('')
+          .toLowerCase()
+          .replace(/\s+/g, ' ')
+          .trim();
+        return directText.includes(needle);
+      });
+    }
+
+    // Same-origin iframe traversal — cross-origin frames silently skip
+    // (yields TARGET_NOT_FOUND when no frame matches, per spec).
+    const frames = document.querySelectorAll('iframe');
+    for (const frame of frames) {
+      let frameDoc = null;
+      try { frameDoc = frame.contentDocument; } catch (_e) { frameDoc = null; }
+      if (!frameDoc) continue;
+      candidates.push(...resolveInDoc(frameDoc, { selector, text, role, name }));
+    }
+
+    // Visibility filter (skipped when includeHidden=true)
+    const filtered = candidates
+      .filter((el) => el && el.nodeType === 1)
+      .filter((el) => {
+        if (includeHidden) return true;
+        if (el.offsetParent === null) return false;
+        const rect = el.getBoundingClientRect();
+        return rect.height > 0 && rect.width > 0;
+      });
+
+    return filtered.map((element) => ({ element, strategy }));
+  }
+
+  // ── waitForScrollSettle: RAF + 50ms grace, capped at maxMs ──────────────
+  function waitForScrollSettle(maxMs) {
+    const cap = typeof maxMs === 'number' ? maxMs : 500;
+    return new Promise((resolve) => {
+      let lastY = window.scrollY;
+      const start = Date.now();
+      function tick() {
+        if (Date.now() - start >= cap) { resolve(); return; }
+        const currentY = window.scrollY;
+        if (currentY === lastY) {
+          setTimeout(resolve, 50);
+        } else {
+          lastY = currentY;
+          requestAnimationFrame(tick);
+        }
+      }
+      requestAnimationFrame(tick);
+    });
+  }
+
+  // ── computeXPath: minimal positional XPath ──────────────────────────────
+  function computeXPath(el) {
+    if (el.id) return '//*[@id="' + el.id + '"]';
+    const parts = [];
+    let cur = el;
+    while (cur && cur.nodeType === 1 && cur !== document.body) {
+      let idx = 1;
+      let sib = cur.previousElementSibling;
+      while (sib) {
+        if (sib.tagName === cur.tagName) idx++;
+        sib = sib.previousElementSibling;
+      }
+      parts.unshift(cur.tagName.toLowerCase() + '[' + idx + ']');
+      cur = cur.parentElement;
+    }
+    return '/html/body/' + parts.join('/');
+  }
+
+  // ── serializeNode: small JSON-safe element descriptor ───────────────────
+  function serializeNode(el, shallow) {
+    const text = (el.textContent || '').trim().slice(0, 80);
+    const role = el.getAttribute('role') || undefined;
+    const out = {
+      tagName: el.tagName.toLowerCase(),
+      role,
+      text,
+    };
+    if (!shallow) {
+      const rect = el.getBoundingClientRect();
+      out.xpath = computeXPath(el);
+      out.bbox = { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+    } else {
+      out.xpath = '';
+    }
+    return out;
+  }
+
+  // ── matchSignal: does element satisfy a single signal? ──────────────────
+  function matchSignal(el, signal) {
+    switch (signal.type) {
+      case 'selector':
+        // Element-matches, not document-querySelector. The latter returns false
+        // for shadow-encapsulated elements because hostDoc is the outer light-DOM
+        // document. el.matches() works in both shadow and light DOM.
+        return !!(el.matches && el.matches(signal.value));
+      case 'aria-label-substring': {
+        const label = (el.getAttribute && el.getAttribute('aria-label')) || '';
+        const v = signal.caseInsensitive ? signal.value.toLowerCase() : signal.value;
+        const l = signal.caseInsensitive ? label.toLowerCase() : label;
+        return l.includes(v);
+      }
+      case 'aria-role':
+        return (el.getAttribute && el.getAttribute('role')) === signal.value;
+      case 'fixed-position': {
+        const cs = el.ownerDocument.defaultView.getComputedStyle(el);
+        return cs.position === 'fixed';
+      }
+      case 'z-index-above': {
+        const cs = el.ownerDocument.defaultView.getComputedStyle(el);
+        const z = parseInt(cs.zIndex, 10);
+        return Number.isFinite(z) && z > parseInt(signal.value, 10);
+      }
+      default:
+        return false;
+    }
+  }
+
+  // ── findPatternRoot: finds the first element matching ALL signals ──────
+  function findPatternRoot(pattern) {
+    // Primary signal is selector if present
+    const primarySignal = pattern.signals.find((s) => s.type === 'selector');
+    const primarySelector = primarySignal ? primarySignal.value : '*';
+    const candidates = [];
+    // Main document (with shadow penetration)
+    const mainCandidate = querySelectorWithShadow(primarySelector);
+    if (mainCandidate) candidates.push(mainCandidate);
+    // Same-origin iframes
+    const frames = document.querySelectorAll('iframe');
+    for (const frame of frames) {
+      let frameDoc = null;
+      try { frameDoc = frame.contentDocument; } catch (_e) { continue; }
+      if (!frameDoc) continue;
+      const c = frameDoc.querySelector(primarySelector);
+      if (c) candidates.push(c);
+    }
+    for (const el of candidates) {
+      const allMatch = pattern.signals.every((s) => matchSignal(el, s));
+      if (allMatch) return el;
+    }
+    return null;
+  }
+
+  // ── dismissPattern: execute the dismiss action, verify removal ─────────
+  async function dismissPattern(pattern, root) {
+    const action = pattern.dismiss.action;
+    let actionExecuted = false;
+    try {
+      if (action === 'click') {
+        const target = (pattern.dismiss.selector
+          ? root.ownerDocument.querySelector(pattern.dismiss.selector) || querySelectorWithShadow(pattern.dismiss.selector)
+          : root);
+        if (target) { target.click(); actionExecuted = true; }
+      } else if (action === 'esc-key') {
+        const evt = new KeyboardEvent('keydown', { key: 'Escape', bubbles: true });
+        document.dispatchEvent(evt); actionExecuted = true;
+      } else if (action === 'remove-node') {
+        const target = pattern.dismiss.selector
+          ? root.ownerDocument.querySelector(pattern.dismiss.selector) || querySelectorWithShadow(pattern.dismiss.selector)
+          : root;
+        if (target && target.parentNode) { target.parentNode.removeChild(target); actionExecuted = true; }
+      }
+    } catch (e) {
+      // try fallback if defined
+      if (pattern.dismiss.fallbackAction) {
+        return dismissPattern({ ...pattern, dismiss: { action: pattern.dismiss.fallbackAction, selector: pattern.dismiss.fallbackSelector } }, root);
+      }
+      throw e;
+    }
+    if (!actionExecuted && pattern.dismiss.fallbackAction) {
+      return dismissPattern({ ...pattern, dismiss: { action: pattern.dismiss.fallbackAction, selector: pattern.dismiss.fallbackSelector } }, root);
+    }
+    // Verify after stabilityMs
+    await new Promise((r) => setTimeout(r, pattern.verify.stabilityMs));
+    const stillThere = findPatternRoot(pattern);
+    return { verified: !stillThere };
+  }
+
+  // Expose on window for content-main.js sentinel intercepts.
+  window.__SP_LOCATOR__ = {
+    querySelectorWithShadow,
+    resolveScrollTargets,
+    waitForScrollSettle,
+    serializeNode,
+    matchSignal,
+    findPatternRoot,
+    dismissPattern,
+  };
+})();

package/bin/Safari Pilot.app/Contents/PlugIns/Safari Pilot Extension.appex/Contents/Resources/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Safari Pilot",
-  "version": "0.1.29",
+  "version": "0.1.33",
   "description": "Native Safari automation for AI agents",
   "permissions": [
     "activeTab",
@@ -44,6 +44,7 @@
         "<all_urls>"
       ],
       "js": [
+        "locator.js",
         "content-main.js"
       ],
       "run_at": "document_idle",