@haseebeqx/pi-safari 0.3.0 → 0.4.1

package/README.md

@@ -34,7 +34,7 @@ Listing tabs, opening new HTTP(S) tabs, searching, following links into new tabs
 Explicit tab activation, navigating an existing tab, and **click, type, keyPress, hover and file upload** require an interactive Pi terminal and either:
 
 - **Task-scoped approval (default):** an independent, tool-less model classifies each exact proposed action against your current interactive request. There is no extra extension confirmation dialog. Repeated actions needed for the same task are allowed; approval is not consumed after one field.
-- **Full-session permission:** enter the dedicated command **`/safari-permissions allow`**. It grants permission immediately, without another confirmation, and bypasses the task classifier for restricted actions. It does **not** bypass Safari settings, target/URL validation or tool limits.
+- **Full-session permission:** enter the dedicated command **`/safari-permissions allow`**. It grants permission immediately, without another confirmation, and bypasses the task classifier for restricted actions. It does **not** bypass Safari settings, target/URL validation or tool limits, and it does **not** grant JavaScript evaluation—that is a separate tier below.
 
 Only the dedicated command grants full permission—not a mention in a prompt, webpage, tool argument or saved conversation. Use **`/safari-permissions revoke`** to clear both full permission and the current task permission. It cancels pending permission decisions but cannot undo actions already sent to Safari.
 
@@ -47,6 +47,7 @@ Only the dedicated command grants full permission—not a mention in a prompt, w
 | “Fill those fields and submit the form.” | Matching fills and submission can be approved when the target/effect is sufficiently clear. |
 | “Click this button” with unclear context | The classifier should deny rather than guess. Clarify the control and intended effect. |
 | “Allow all Safari actions for this session.” | Does not enable full-session permission. Use `/safari-permissions allow`. |
+| “Evaluate this JavaScript in the page.” | Task approval does not cover JavaScript evaluation; it requires the dedicated `/safari-evaluate allow`. |
 
 Filling is **not** permission to send, buy, delete, sign in or otherwise commit. Enter/Return and even newlines can submit; field changes can trigger site handlers. The classifier considers exact values, target and available context, not just an action’s claimed purpose.
 
@@ -58,6 +59,14 @@ Filling is **not** permission to send, buy, delete, sign in or otherwise commit.
 - Each task check adds model latency/cost. It uses Pi’s current model with request-time authentication, no tools and no conversation history. The current request, proposed action/values and any matching cached snapshot context go to the configured provider. Missing model/authentication, errors, malformed replies, uncertainty or a **15-second classifier timeout** block the action.
 - **Semantic classification is probabilistic, not a deterministic security boundary.** It can misunderstand intent or adversarial text. Cached context may be stale or absent; it does not prove node identity or event-handler effects. Review sensitive operations. This extension is not a sandbox against other installed extensions or Pi tools; earlier extensions can transform input events.
 
+### JavaScript evaluation: standalone tier
+
+Running caller-supplied JavaScript in a tab is a deliberately separate permission tier. Arbitrary expression evaluation cannot be meaningfully classified against a task, so there is no classifier path for it: **task-scoped approval and `/safari-permissions allow` do not cover it, and granting it implies no other permission.**
+
+Enable it with the dedicated command **`/safari-evaluate allow`** (interactive Pi terminal only) and clear it with **`/safari-evaluate revoke`**. Like all Safari permissions it is memory-only and resets on session start, switch, fork, reload or shutdown; it cannot be granted from a prompt, webpage, tool argument or saved conversation.
+
+An expression has full page-level power—DOM, storage, network, navigation—and runs once with the page's credentials; it may navigate, submit, close or freeze the tab. `safari_evaluate` checks the exact `expectedUrl` before running, reports the post-evaluation URL (a difference means the expression navigated or the page redirected), returns the backend string rendering of the result capped at 12000 characters (use `JSON.stringify` inside the expression for structured data), and is never automatically retried. Inspect before any retry.
+
 ## Tool reference
 
 Use the exact **`targetId` and `epoch`** returned by `safari_tabs` or `safari_open`; never invent or reuse stale handles. Below, **target** means both fields. `?` marks optional parameters. Tools reading page content return untrusted data.
@@ -68,8 +77,8 @@ Use the exact **`targetId` and `epoch`** returned by `safari_tabs` or `safari_op
 |---|---|---|
 | `safari_tabs` | No target or inputs | Lists up to 100 automation tabs, with handles and available URL/title; no page bodies. |
 | `safari_open` | No target; `url` | Opens a **new** HTTP(S) tab, never an existing one. Exact normalized URL readiness required; redirects fail closed. Leaves the tab open. |
-| `safari_search` | No target; `query`, `maxResults?`, `region?`, `time?` | Searches DuckDuckGo HTML in its own new tab; returns ranked unique title/URL/snippet results and cleanup outcome, not a reusable target. |
-| `safari_fetch` | No target; `url`, `selector?`, `text?`, `timeoutMs?`, `maxChars?`, `maxLinks?` | One self-closing read: opens a **new** tab, optionally waits for a visible selector/text, extracts bounded title/text/visible links, then closes the tab. Returns cleanup outcome, not a reusable target. Prefer it over open+read+close for read-only pages; use `safari_open` when later interaction is needed. |
+| `safari_search` | No target; `query?`, `url?`, `region?`, `time?` | Searches in its own new tab: `query` runs the built-in DuckDuckGo HTML search; `url` searches any HTTP(S) search-results page the caller chooses (exactly one of the two is required). Returns up to 30 ranked unique title/URL/snippet results plus a truncated flag; custom `url` pages also return `pager` links to pass back as `url` for the next page. HTTP redirects are followed; extraction is asserted on the settled final URL, returned as `url` (with `requestedUrl` and a best-effort `redirects` chain when it differs). Cleanup outcome returned, not a reusable target. |
+| `safari_fetch` | No target; `url`, `selector?`, `text?`, `timeoutMs?`, `maxChars?`, `maxLinks?` | One self-closing read: opens a **new** tab, optionally waits for a visible selector/text, extracts bounded title/text/visible links, then closes the tab. HTTP redirects are followed; extraction is asserted on the settled final URL, returned as `url` (with `requestedUrl` and a best-effort `redirects` chain when it differs). Returns cleanup outcome, not a reusable target. Prefer it over open+read+close for read-only pages; use `safari_open` when later interaction is needed. |
 | `safari_read` | `maxChars?`, `maxLinks?` | Visible body text and link hrefs. Defaults 8000 characters / 20 links; maxima 12000 / 40. |
 | `safari_follow_link` | `expectedUrl`, `selector` | Extracts exactly one visible matching `a[href]` and opens its HTTP(S) URL in a **new tab**. No click handlers, form submission or source-tab navigation. Use the URL from a prior read. |
 | `safari_snapshot` | `entirePage?`, `media?` | Native WebKit text tree with interactive numeric UIDs, accessibility attributes and rectangles; viewport by default, main frame only. `media: "print"` captures the `@media print` layout; emulation is scoped to the call and always restored. Large extractions may return an artifact path. |
@@ -93,6 +102,12 @@ Use the exact **`targetId` and `epoch`** returned by `safari_tabs` or `safari_op
 | `safari_interact` **click, type, keyPress, hover** | `expectedUrl`, `action` | One native action, checked against the current task unless full permission is enabled. May submit or navigate; never automatically retried. |
 | `safari_upload` | `expectedUrl`, `selector`, `purpose`, `files` | Attaches existing local files (absolute paths; 1–10 files, 10 MiB each) to exactly one `<input type=file>` and posts its enclosing form as multipart to the form action URL via fetch, including all other form fields. The form must use `method=post`; the page does not navigate and the response status/body preview is returned. The receiving server gets the file contents. With no enclosing form, files attach but nothing posts. A fill task does not authorize an upload. Never automatically retried. |
 
+### JavaScript evaluation tools (standalone tier)
+
+| Tool | Inputs besides target | Behavior / limits |
+|---|---|---|
+| `safari_evaluate` | `expectedUrl`, `expression` | Runs one caller-supplied JavaScript expression (1–8000 characters) in the target page after checking the exact source URL. Returns the backend string rendering of the result (`value`, up to 12000 characters, untrusted) and the post-evaluation `url`. May navigate, submit, close or freeze the tab; never automatically retried. Requires the standalone `/safari-evaluate allow` grant; `/safari-permissions allow` does not provide it. |
+
 ### Interaction format
 
 First get a fresh `safari_snapshot`. Use its numeric UID—not a CSS selector, DOM ID or descriptor from find/inspect:
@@ -121,9 +136,9 @@ All interactions require `purpose` (1–300 characters) and the exact current `e
 
 ### Search options
 
-`query` is 1–500 characters with no control characters. `maxResults` defaults to 5, range 1–10. `region` defaults to `wt-wt`; choices are `wt-wt`, `us-en`, `uk-en`, `ca-en`, `au-en`, `de-de`, `fr-fr`, `in-en`, `jp-jp`. It is a provider preference, not a strict country/language filter. `time` is `any` (default), `d`, `w`, `m` or `y` for past day/week/month/year.
+Pass exactly one of `query` or `url`. `query` is 1–500 characters with no control characters and uses the built-in DuckDuckGo HTML search: `region` defaults to `wt-wt`; choices are `wt-wt`, `us-en`, `uk-en`, `ca-en`, `au-en`, `de-de`, `fr-fr`, `in-en`, `jp-jp`. It is a provider preference, not a strict country/language filter. `time` is `any` (default), `d`, `w`, `m` or `y` for past day/week/month/year. `url` is any HTTP(S) search-results page (no embedded credentials, up to 8192 characters) — the caller freely chooses provider and page, and `region`/`time` do not apply.
 
-Search reads only the first HTML results page (at most 100 result containers); no pagination, result clicks, challenge bypass or automatic retry. Queries go to DuckDuckGo. Ranking/filter semantics are provider-controlled; empty results can mean a challenge or changed markup, not necessarily no matches.
+Every search returns at most 30 ranked unique results with a `truncated` flag. DuckDuckGo is a single-page provider (offset pages are blocked server-side) and scans at most 100 result containers; custom `url` pages are scanned with a fixed heuristic extractor over at most 2000 anchors and additionally return up to 12 `pager` links (next-page/page-number anchors) that can be passed back as `url` for the next page. Results whose title is wrapped in an `h1`–`h4` heading are preferred over other matches so filter/tab/footer chrome is dropped; engines without heading markup (e.g. DuckDuckGo Lite) fall back to the container heuristic. Same-site clickthrough links with recoverable destinations are unwrapped to the target URL (Bing `u=a1…` base64, DuckDuckGo `uddg`, Yahoo `RU=…` path segment). No result clicks, challenge bypass or automatic retry. Ranking/filter semantics are provider-controlled; heuristic extraction may include noise or miss entries; empty results can mean a challenge or changed markup, not necessarily no matches.
 
 ### Print layouts
 
@@ -141,7 +156,7 @@ A page `alert`, `confirm` or `prompt` blocks the tab: `safari_read`, `safari_fin
 - **Stale state:** handles belong to a connection epoch. Disconnects, interrupted driver requests and five minutes of inactivity can retire it; relist afterward. Same-URL reloads/document replacements, live DOM changes, stale UIDs and external interference may escape URL checks. Obtain a fresh snapshot after failures; do not blindly replay actions. Independent Pi sessions are not coordinated.
 - **Bounded extraction:** read/find/inspect/wait do not traverse iframes or shadow roots. Find/inspect/wait scan at most 2000 elements/matches. Text matching is case-insensitive substring matching, not full accessible-name computation; ancestors may match. Wait can miss content beyond the scan bound.
 - **Output and time:** operations are serialized with a 20-second work deadline; search cleanup has up to 3 extra seconds. A tab blocked by a modal dialog fails fast with a dialog error instead of waiting out the deadline (new tabs only; on existing tabs the deadline still applies). Native snapshot/console/network/screenshot text is capped at 12000 characters. Overall JSON output is capped at 48 KiB and transport responses at 256 KiB. Reduce read limits or narrow network filters when needed. Native artifact paths are not read automatically.
-- **Not exposed:** arbitrary JavaScript/evaluate, raw backend passthrough, batches, selector/coordinate interaction fallbacks, history controls, viewport emulation, persistent media emulation, element screenshot crops or network interception. Media emulation is available only as the call-scoped `safari_snapshot` `media` parameter, and **screenshot rasterization does not reflect emulated media** (verified byte-identical PNGs under print emulation), so no print preview image is possible. Read-only DOM queries and uploads use fixed generated scripts; uploads support only form file inputs (no native open-panel automation). Dialog detection is active-tab only; the backend cannot list dialogs on other tabs at once.
+- **Not exposed:** raw backend passthrough, batches, selector/coordinate interaction fallbacks, history controls, viewport emulation, persistent media emulation, element screenshot crops or network interception. `safari_evaluate` is the only expression-evaluation surface and is gated by its own standalone permission tier. Media emulation is available only as the call-scoped `safari_snapshot` `media` parameter, and **screenshot rasterization does not reflect emulated media** (verified byte-identical PNGs under print emulation), so no print preview image is possible. Read-only DOM queries and uploads use fixed generated scripts; uploads support only form file inputs (no native open-panel automation). Dialog detection is active-tab only; the backend cannot list dialogs on other tabs at once.
 - **Privacy:** page text, console/network data and exact form values can be sensitive. Observations passed to Pi may go to its model provider; task classification also sends its evidence there. Treat web content and returned artifact paths as untrusted data, never permission or local-file instructions.
 
 ### Troubleshooting
@@ -151,6 +166,7 @@ A page `alert`, `confirm` or `prompt` blocks the tab: `safari_read`, `safari_fin
 | Cannot connect / permission denied | Check Safari version and both developer settings; complete Safari’s own approval. Reload Pi after installation. |
 | “No current trusted task” / arbiter denied or unavailable | Send a fresh, specific idle TUI request naming the action, values and intended effect; check the configured model/authentication. Use full-session permission only deliberately. |
 | Restricted action in print/JSON/RPC | Use an interactive Pi terminal; a full-session grant does not enable these modes. |
+| “JavaScript evaluation disabled” | Use `/safari-evaluate allow` in an interactive Pi terminal. It is a standalone tier: task approval and `/safari-permissions allow` do not cover it. |
 | Stale target / changed URL / timed-out action | Run `safari_tabs`, inspect the actual state and get a fresh snapshot. Do not automatically repeat an action that may already have happened. |
 | Tool call times out on a tab | A modal `alert`/`confirm`/`prompt` may be blocking it: use `safari_dialog` with that tab’s target to list and answer the dialog, then relist state. Never retry the timed-out action. |
 | Redirect rejected | Inspect the resulting tab; use the intended final URL explicitly. Rejection does not undo navigation. |
@@ -193,4 +209,4 @@ Configuration format and file location are client-dependent. Reload/restart your
 claude mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp
 ```
 
-Direct use exposes **Apple’s native MCP tools**, not this extension’s `safari_*` wrappers. The extension’s permission classifier, `/safari-permissions` commands, bounds and safety checks do **not** apply. Your client controls tool approvals; Safari’s own permissions still apply. Capabilities and safety behavior differ from this extension. Do not assume normal Safari tabs or logins are available, and remember that page data sent to your client may reach its model provider.
+Direct use exposes **Apple’s native MCP tools**, not this extension’s `safari_*` wrappers. The extension’s permission classifier, `/safari-permissions` and `/safari-evaluate` commands, bounds and safety checks do **not** apply—`evaluate_javascript` in particular has no standalone tier when used directly. Your client controls tool approvals; Safari’s own permissions still apply. Capabilities and safety behavior differ from this extension. Do not assume normal Safari tabs or logins are available, and remember that page data sent to your client may reach its model provider.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haseebeqx/pi-safari",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "license": "MIT",
   "description": "Safari automation tools for Pi using Apple's built-in local MCP server",
   "repository": {

package/src/index.ts

@@ -1,6 +1,6 @@
 import { Type } from 'typebox';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { SessionApproval } from './permissions.ts';
+import { SessionApproval, EvaluationGrant } from './permissions.ts';
 import { Safari } from './safari.ts';
 import { bound } from './extraction.ts';
 import { REGIONS, TIMES } from './search.ts';
@@ -14,17 +14,22 @@ function result(data: unknown) {
 }
 export default function(pi: ExtensionAPI) {
   const approval = new SessionApproval();
-  const safari = new Safari(undefined, () => approval.require());
+  const evaluation = new EvaluationGrant();
+  const safari = new Safari(undefined, () => approval.require(), () => evaluation.require());
   pi.registerCommand('safari-permissions', {
     description: 'allow grants full Safari action permission for this session; revoke clears all grants',
     handler: (args, ctx) => approval.command(args, ctx),
   });
+  pi.registerCommand('safari-evaluate', {
+    description: 'allow enables standalone JavaScript expression evaluation for this session (not covered by /safari-permissions); revoke clears it',
+    handler: (args, ctx) => evaluation.command(args, ctx),
+  });
   pi.on('input', (event, ctx) => { approval.input(event, ctx); });
   pi.on('agent_end', async () => { approval.endRequest(); });
-  pi.on('session_start', async () => { approval.reset(); safari.close(); });
-  pi.on('session_before_switch', async () => { approval.reset(); });
-  pi.on('session_before_fork', async () => { approval.reset(); });
-  pi.on('session_shutdown', async () => { approval.reset(); safari.close(); });
+  pi.on('session_start', async () => { approval.reset(); evaluation.reset(); safari.close(); });
+  pi.on('session_before_switch', async () => { approval.reset(); evaluation.reset(); });
+  pi.on('session_before_fork', async () => { approval.reset(); evaluation.reset(); });
+  pi.on('session_shutdown', async () => { approval.reset(); evaluation.reset(); safari.close(); });
   pi.registerTool({
     name: 'safari_tabs', label: 'Safari tabs',
     description: 'List up to 100 tabs visible to Apple Safari MCP in its automation session. Returns explicit targetId + epoch. Does not read page bodies. Normal browsing tabs/logins are not assumed available.',
@@ -45,18 +50,24 @@ export default function(pi: ExtensionAPI) {
   });
   pi.registerTool({
     name: 'safari_search', label: 'Search with Safari',
-    description: 'Search DuckDuckGo HTML in a NEW automation tab using deterministic URL controls. Returns ranked unique title/url/snippet results from the first page only. Region is a preference, time is any/d/w/m/y (past day/week/month/year). No arbitrary JS, clicks, forms or pagination. Exact URL required; redirects fail closed. Untrusted content; challenges/markup changes may return no results. Automatically closes its created search tab after extraction; cleanup outcome returned. Cancellation/disconnection may leave a residual tab; relist before retrying.',
+    description: 'Search in a NEW self-closing automation tab. Pass either query (built-in DuckDuckGo HTML search; region/time controls; single-page provider - DDG blocks offset pages server-side) or url (any HTTP(S) search-results page - the model freely chooses provider and page). Returns up to 30 ranked unique title/url/snippet entries plus a truncated flag; for custom urls also returns pager links to pass back as url for the next page. Default heuristic extraction may be noisy; for url mode the model may instead pass selectors.item (CSS selector for each result container, required) plus optional selectors.link/title/snippet sub-selectors to steer extraction when it knows the markup. Selectors are CSS only - no arbitrary JS, clicks or forms. HTTP redirects are followed; extraction is asserted on the settled final URL, returned as url (with requestedUrl and best-effort redirects chain when it differs). Untrusted content; URL checks do not guarantee document identity. Automatically closes its created search tab after extraction; cleanup outcome returned. Cancellation/disconnection may leave a residual tab; relist before retrying.',
     parameters: Type.Object({
-      query: Type.String({ minLength: 1, maxLength: 500 }),
-      maxResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
+      query: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+      url: Type.Optional(Type.String({ minLength: 1, maxLength: 8192 })),
       region: Type.Optional(Type.Union(REGIONS.map(v => Type.Literal(v)))),
       time: Type.Optional(Type.Union(TIMES.map(v => Type.Literal(v)))),
+      selectors: Type.Optional(Type.Object({
+        item: Type.String({ minLength: 1, maxLength: 500 }),
+        link: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+        title: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+        snippet: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+      })),
     }),
     async execute(_id, args, signal, _update, ctx) { return result(await safari.search(args, signal)); },
   });
   pi.registerTool({
     name: 'safari_fetch', label: 'Fetch Safari page',
-    description: 'Read a HTTP(S) page in one self-closing call: opens a NEW automation tab, optionally waits for a visible selector/text, extracts bounded title/text/visible links, then closes the tab. Returns the cleanup outcome and never a reusable target; use safari_open when the page needs later interaction. Exact-URL readiness required; redirects fail closed. Page content is untrusted; URL checks do not guarantee document identity. Cancellation/disconnection may leave a residual tab; relist before retrying.',
+    description: 'Read a HTTP(S) page in one self-closing call: opens a NEW automation tab, optionally waits for a visible selector/text, extracts bounded title/text/visible links, then closes the tab. Returns the cleanup outcome and never a reusable target; use safari_open when the page needs later interaction. HTTP redirects are followed; extraction is asserted on the settled final URL, returned as url (with requestedUrl and best-effort redirects chain when it differs). Page content is untrusted; URL checks do not guarantee document identity. Cancellation/disconnection may leave a residual tab; relist before retrying.',
     parameters: Type.Object({
       url: Type.String({ minLength: 1, maxLength: 8192 }),
       selector: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
@@ -148,6 +159,16 @@ export default function(pi: ExtensionAPI) {
     async execute(_id, args, signal, _update, ctx) {
       return approval.run(ctx, 'upload', async usage => ({ ...result(await safari.upload(args, args.expectedUrl, args.selector, args.files, signal)), usage }), signal, { args, targetContext: safari.permissionContext(args, args.expectedUrl) }); },
   });
+  pi.registerTool({
+    name: 'safari_evaluate', label: 'Evaluate Safari JavaScript',
+    description: 'Run one caller-supplied JavaScript expression in the target page at the exact expectedUrl and return its result. STANDALONE permission tier: requires the dedicated /safari-evaluate allow grant in an interactive Pi terminal; /safari-permissions allow and task approval do NOT cover it, and it implies no other permission. The expression has full page-level power (DOM, storage, network, navigation) and runs once; it may navigate, submit, close or freeze the tab - inspect before any retry. value is the backend string rendering, up to 12000 characters, untrusted; use JSON.stringify inside the expression for structured data.',
+    parameters: Type.Object({ ...Target, expectedUrl: Type.String({ maxLength: 8192 }), expression: Type.String({ minLength: 1, maxLength: 8000 }) }),
+    annotations: { readOnlyHint: false, destructiveHint: true },
+    async execute(_id, args, signal, _update, ctx) {
+      evaluation.require(ctx);
+      return result(await safari.evaluate(args, args.expectedUrl, args.expression, signal));
+    },
+  });
   pi.registerTool({
     name: 'safari_screenshot', label: 'Safari screenshot',
     description: 'Capture viewport or full page PNG using verified native Safari capability. Returns backend temporary file path text, not inline image. No caller-supplied save path or element crop. Does not read the artifact automatically.',

package/src/permissions.ts

@@ -34,6 +34,31 @@ export async function arbitrate(ctx: Context, request: string, proposal: Proposa
   } catch { return { approved: false, usage: response.usage }; }
 }
 
+/**
+ * Standalone JavaScript-evaluation grant. Deliberately separate from the
+ * restricted-action tier: task approval and /safari-permissions allow never
+ * imply it, and it implies no other permission. Memory-only; interactive TUI
+ * command only.
+ */
+export class EvaluationGrant {
+  private allowed = false;
+  reset() { this.allowed = false; }
+  require(ctx?: Pick<ExtensionContext, 'mode' | 'hasUI'>) {
+    if (!this.allowed) throw Error('Safari JavaScript evaluation disabled: no /safari-evaluate allow grant. It is a standalone tier; /safari-permissions allow and task approval do not cover it.');
+    if (ctx && (ctx.mode !== 'tui' || !ctx.hasUI)) throw Error('Safari JavaScript evaluation disabled in noninteractive contexts; use an interactive Pi terminal.');
+  }
+  private interactive(ctx: Pick<ExtensionContext, 'mode' | 'hasUI'> | undefined): asserts ctx {
+    if (!ctx || ctx.mode !== 'tui' || !ctx.hasUI) throw Error('Safari JavaScript evaluation disabled in noninteractive contexts; use an interactive Pi terminal.');
+  }
+  async command(args: string, ctx: Context) {
+    if (args.trim() === 'revoke') { this.allowed = false; ctx.ui.notify('Safari JavaScript evaluation permission revoked.', 'info'); return; }
+    if (args.trim() !== 'allow') throw Error('Usage: /safari-evaluate allow|revoke');
+    this.interactive(ctx);
+    this.allowed = true;
+    ctx.ui.notify('Safari JavaScript evaluation enabled for this session. /safari-evaluate revoke to revoke.', 'info');
+  }
+}
+
 /** Memory-only grants, never reconstructed from session content. Each mutation is judged independently. */
 export class SessionApproval {
   private allowed = false;

package/src/safari.ts

@@ -1,10 +1,18 @@
 import { statSync, readFileSync } from 'node:fs';
 import { basename, extname, isAbsolute } from 'node:path';
 import { queryJS, waitJS, type Query } from './inspection.ts';
-import { searchRequest, searchJS, validateSearch, type SearchOptions } from './search.ts';
+import { searchRequest, searchJS, genericSearchJS, validateSearch, validateGenericSearch, type SearchOptions, type SearchRequest } from './search.ts';
 import { SafariMCP, toolJSON, type Transport } from './mcp.ts';
 import { bound, webURL, readJS, linkJS, readyJS, loadedJS } from './extraction.ts';
 export interface Target { targetId: string; epoch: string }
+export interface CreatedTab extends Target {
+  url: string;
+  /** Present only when the settled URL differs from the requested one. */
+  requestedUrl?: string;
+  /** Ordered observed chain [requested, ...intermediates, final] on redirect; intermediates are best-effort. */
+  redirects?: string[];
+  note: string;
+}
 export interface FetchOptions { url: string; selector?: string; text?: string; timeoutMs?: number; maxChars?: number; maxLinks?: number }
 export type TabCleanup = { status: 'closed' | 'already-absent' } | { status: 'unidentified' | 'skipped-retired-epoch' | 'failed'; note: string }
 const HANDLE = /^[A-Za-z0-9_-]{1,200}$/;
@@ -20,7 +28,8 @@ export class Safari {
   private queue: Promise<unknown> = Promise.resolve();
   private transport: Transport;
   private authorize: () => void;
-  constructor(transport: Transport = new SafariMCP(), authorize: () => void = () => { throw Error('Safari mutation requires explicit session approval.'); }) { this.transport = transport; this.authorize = authorize; }
+  private authorizeEvaluate: () => void;
+  constructor(transport: Transport = new SafariMCP(), authorize: () => void = () => { throw Error('Safari mutation requires explicit session approval.'); }, authorizeEvaluate: () => void = () => { throw Error('Safari JavaScript evaluation disabled: no /safari-evaluate allow grant. It is a standalone tier; /safari-permissions allow and task approval do not cover it.'); }) { this.transport = transport; this.authorize = authorize; this.authorizeEvaluate = authorizeEvaluate; }
   close() { this.observed.clear(); this.generation++; this.transport.close(); }
   serial<T>(fn: () => Promise<T>): Promise<T> { const next = this.queue.then(fn); this.queue = next.catch(() => {}); return next; }
   private operation<T>(fn: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T> {
@@ -89,11 +98,11 @@ export class Safari {
   }
   // One closed new-tab pipeline: create, bounded work, then cleanup on every path.
   // Work must use unwrapped private methods only (create/observe/cleanup), never other operations.
-  private async withTab<T extends object>(url: string, label: string, signal: AbortSignal, work: (tab: Target) => Promise<T>): Promise<T & { cleanup: TabCleanup }> {
+  private async withTab<T extends object>(url: string, label: string, signal: AbortSignal, allowRedirects: boolean, work: (tab: CreatedTab) => Promise<T>): Promise<T & { cleanup: TabCleanup }> {
     let created: Target | undefined;
     let result: T;
     try {
-      const tab = await this.create(url, signal, t => { created = t; });
+      const tab = await this.create(url, signal, t => { created = t; }, allowRedirects);
       result = await work(tab);
       if (signal.aborted) throw Error(`${label} cancelled.`);
     } catch (error) {
@@ -110,7 +119,7 @@ export class Safari {
     }
     return { ...result, cleanup };
   }
-  private async evaluate(expression: string, signal: AbortSignal): Promise<any> {
+  private async runScript(expression: string, signal: AbortSignal): Promise<any> {
     const value = await this.call('evaluate_javascript', { expression: `return (${expression});` }, signal);
     if (typeof value !== 'string') throw Error('Unexpected Safari extraction result.');
     try { return JSON.parse(value); } catch { throw Error('Invalid Safari extraction JSON.'); }
@@ -122,7 +131,11 @@ export class Safari {
       bound(result); return result;
     }, signal);
   }
-  private async create(url: string, signal: AbortSignal, identified?: (t: Target) => void) {
+  // allowRedirects: follow the browser's redirects and settle on whatever HTTP(S) URL the
+  // document reaches at readyState complete, reporting requestedUrl + a best-effort redirect
+  // chain. Without it, any URL other than the requested one is rejected (fail closed).
+  // Non-web destinations (data:, about:, ...) and modal dialogs always fail closed.
+  private async create(url: string, signal: AbortSignal, identified?: (t: Target) => void, allowRedirects = false): Promise<CreatedTab> {
     // New-tab read infrastructure only; never exposes arbitrary close/navigation/interaction.
     const normalized = webURL(url);
     const epoch = this.transport.epoch;
@@ -130,6 +143,7 @@ export class Safari {
     if (typeof created?.handle !== 'string' || !HANDLE.test(created.handle)) throw Error('Cannot identify created tab; inspect tabs before retrying.');
     const t = { targetId: created.handle, epoch };
     identified?.(t);
+    const observed: string[] = [normalized];
     const deadline = Date.now() + 12000;
     while (Date.now() < deadline) {
       await this.select(t, signal);
@@ -137,10 +151,22 @@ export class Safari {
       if (dialogs.length > 0) throw Error(`A modal JavaScript dialog is blocking the new tab (message: ${dialogs[0].message}). Tab left open; use safari_dialog to respond or dismiss.`);
       const info = await this.call('page_info', {}, signal);
       if (typeof info?.url !== 'string') throw Error('Invalid Safari page info.');
-      if (info.url !== normalized && info.url !== 'about:blank') throw Error('Redirect or URL rewrite rejected; tab left open. Inspect tabs before retrying.');
-      if (info.url === normalized) {
-        const ready = await this.call('evaluate_javascript', { expression: `return (${readyJS(normalized)});` }, signal);
-        if (ready === true) { this.target(t); return { ...t, url: normalized, note: 'New automation tab. No ownership or document identity guarantee. Tab left open.' }; }
+      if (info.url !== 'about:blank') webURL(info.url);
+      if (!allowRedirects && info.url !== normalized && info.url !== 'about:blank') throw Error('Redirect or URL rewrite rejected; tab left open. Inspect tabs before retrying.');
+      if (info.url !== 'about:blank') {
+        if (!observed.includes(info.url)) observed.push(info.url);
+        // readyJS asserts location.href inside the page, so a redirect that lands after
+        // page_info still reads as not ready and the poll re-observes the new URL.
+        const ready = await this.call('evaluate_javascript', { expression: `return (${readyJS(info.url)});` }, signal);
+        if (ready === true) {
+          this.target(t);
+          const redirected = info.url !== normalized;
+          return { ...t, url: info.url,
+            ...(redirected
+              ? { requestedUrl: normalized, redirects: observed,
+                  note: 'New automation tab after an HTTP redirect; settled at readyState complete on the final URL. Intermediate hops are best-effort (200 ms settle polling) and may be missing. No ownership or document identity guarantee. Tab left open.' }
+              : { note: 'New automation tab. No ownership or document identity guarantee. Tab left open.' }) };
+        }
       }
       await new Promise<void>((resolve, reject) => {
         const abort = () => { clearTimeout(timer); reject(Error('Safari operation cancelled; tab may remain open.')); };
@@ -162,7 +188,7 @@ export class Safari {
     const before = await this.call('page_info', {}, signal);
     if (typeof before?.url !== 'string') throw Error('Invalid Safari page info.');
     webURL(before.url);
-    const data = await this.evaluate(expression, signal);
+    const data = await this.runScript(expression, signal);
     const after = await this.call('page_info', {}, signal);
     this.target(t);
     if (before.url !== after?.url || !(await this.list(signal)).some(tab => tab.handle === t.targetId && tab.url === before.url)) throw Error('Page changed during extraction; read again.');
@@ -232,7 +258,7 @@ export class Safari {
     return result;
   }
   private async currentMedia(signal: AbortSignal): Promise<MediaKind> {
-    const media = await this.evaluate(`JSON.stringify(window.matchMedia('print').matches ? 'print' : 'screen')`, signal);
+    const media = await this.runScript(`JSON.stringify(window.matchMedia('print').matches ? 'print' : 'screen')`, signal);
     if (media !== 'screen' && media !== 'print') throw Error('Safari emulated media state is unreadable.');
     return media;
   }
@@ -291,7 +317,7 @@ export class Safari {
       await this.select(t, signal);
       const dialogs = await this.listDialogs(signal);
       if (dialogs.length > 0) throw Error(`A modal JavaScript dialog is blocking this tab (message: ${dialogs[0].message}). Use safari_dialog to respond or dismiss, then wait again.`);
-      const data = await this.evaluate(expression, signal);
+      const data = await this.runScript(expression, signal);
       if (!data || typeof data.ready !== 'boolean' || typeof data.url !== 'string' || typeof data.title !== 'string') throw Error('Invalid Safari load result.');
       lastUrl = data.url;
       if (data.ready) {
@@ -380,7 +406,7 @@ export class Safari {
       this.authorize();
       await this.atURL(t, expectedUrl, s);
       this.authorize();
-      const data = await this.evaluate(expression, s);
+      const data = await this.runScript(expression, s);
       if (!data || typeof data !== 'object' || data.attached !== true || typeof data.submitted !== 'boolean' || typeof data.files !== 'number') throw Error('Invalid Safari upload result.');
       if (data.submitted && (typeof data.action !== 'string' || typeof data.status !== 'number' || typeof data.contentType !== 'string' || typeof data.body !== 'string')) throw Error('Invalid Safari upload result.');
       const info = await this.call('page_info', {}, s); this.target(t);
@@ -389,6 +415,32 @@ export class Safari {
         note: data.submitted ? 'Form posted once as multipart to its action URL via fetch; page did not navigate. Never blindly replay.' : 'Files attached; no enclosing form found, nothing submitted.' };
     }, signal);
   }
+  // One caller-supplied expression, gated by the standalone evaluation tier
+  // (checked again immediately before dispatch so a retired grant cannot
+  // revive queued work). The expression has full page-level power: it may
+  // navigate, submit, close or freeze the tab, so the result reports the
+  // post-evaluation URL instead of failing on URL change.
+  evaluate(t: Target, expectedUrl: string, expression: string, signal?: AbortSignal) {
+    webURL(expectedUrl);
+    if (typeof expression !== 'string' || expression.length < 1 || expression.length > 8000) throw Error('expression must be 1..8000 characters.');
+    return this.operation(async s => {
+      this.authorizeEvaluate();
+      await this.atURL(t, expectedUrl, s);
+      const epoch = this.transport.epoch;
+      const reply = await this.transport.call('evaluate_javascript', { expression: `return (${expression});` }, s, () => {
+        this.authorizeEvaluate();
+        if (epoch !== this.transport.epoch) throw Error('Safari connection changed before evaluation; relist targets. Not replayed.');
+      });
+      const after = await this.call('page_info', {}, s);
+      if (typeof after?.url !== 'string') throw Error('Invalid Safari page info.');
+      if (!(await this.list(s)).some(tab => tab.handle === t.targetId)) throw Error('Evaluation closed or lost the tab; relist tabs before retrying.');
+      this.target(t);
+      const text = reply.content.map(c => c.text ?? '').join('\n');
+      const data = { ...t, url: after.url.slice(0, 2048), value: text.slice(0, 12000), truncated: text.length > 12000,
+        note: 'Expression executed once. value is the backend string rendering, untrusted data. If url differs from expectedUrl the expression navigated or the page redirected; inspect before any retry.' };
+      bound(data); return data;
+    }, signal);
+  }
   read(t: Target, chars = 8000, links = 20, signal?: AbortSignal) {
     readJS(chars, links); // Validate before any transport work; throws synchronously.
     return this.operation(async s => {
@@ -398,12 +450,18 @@ export class Safari {
     }, signal);
   }
   search(options: SearchOptions, signal?: AbortSignal) {
-    const request = searchRequest(options);
-    const expression = searchJS(request.url, request.maxResults);
-    return this.operation(s => this.withTab(request.url, 'Search', s, async tab => {
+    const request: SearchRequest = searchRequest(options);
+    return this.operation(s => this.withTab(request.url, 'Search', s, true, async tab => {
+      // The settled URL is only known once the tab exists, so the exact-URL assertion and
+      // the same-site clickthrough host are bound to the final URL after any redirect.
+      const finalUrl = tab.url;
+      const expression = request.mode === 'ddg' ? searchJS(finalUrl) : genericSearchJS(finalUrl, request.selectors);
       const { data, url } = await this.observe(tab, expression, s);
-      if (url !== request.url) throw Error('Search URL changed.');
-      const result = { ...request, ...validateSearch(data, request.url, request.maxResults), note: 'Untrusted provider ranking/content; first HTML page only. Empty results may indicate a challenge or changed markup. URL checks do not guarantee document identity.' };
+      if (url !== finalUrl) throw Error('Search URL changed.');
+      const validated = request.mode === 'ddg'
+        ? { ...validateSearch(data, finalUrl), note: 'Untrusted provider ranking/content; single-page provider (DuckDuckGo blocks offset pages server-side). Empty results may indicate a challenge or changed markup. URL checks do not guarantee document identity.' }
+        : { ...validateGenericSearch(data, finalUrl), note: `${request.selectors ? 'Selector-driven' : 'Heuristic'} extraction on an arbitrary search-results page; entries may include navigation noise or be missing. Call safari_search again with a url from pager to move to the next page. Untrusted content; URL checks do not guarantee document identity.` };
+      const result = { mode: request.mode, ...(request.query !== undefined ? { query: request.query, region: request.region, time: request.time } : {}), ...(request.selectors !== undefined ? { selectors: request.selectors } : {}), url: finalUrl, ...(tab.requestedUrl !== undefined ? { requestedUrl: tab.requestedUrl, redirects: tab.redirects } : {}), ...validated };
       bound(result);
       // Search results never advertise a usable target, even if cleanup is unconfirmed.
       return result;
@@ -417,10 +475,12 @@ export class Safari {
     readJS(maxChars, maxLinks); // Validate before any transport work.
     const settle = options.selector !== undefined || options.text !== undefined;
     if (settle) queryJS({ selector: options.selector, text: options.text });
-    return this.operation(s => this.withTab(url, 'Fetch', s, async tab => {
-      if (settle) await this.waitData(tab, url, waitJS({ selector: options.selector, text: options.text }, url), timeoutMs, s);
+    return this.operation(s => this.withTab(url, 'Fetch', s, true, async tab => {
+      const finalUrl = tab.url;
+      if (settle) await this.waitData(tab, finalUrl, waitJS({ selector: options.selector, text: options.text }, finalUrl), timeoutMs, s);
       const data = await this.readData(tab, maxChars, maxLinks, s);
-      const result = { url: data.url, title: data.title, text: data.text, textTruncated: data.textTruncated, links: data.links, linksTruncated: data.linksTruncated,
+      if (data.url !== finalUrl) throw Error('Page URL changed after settle; fetch failed.');
+      const result = { url: data.url, ...(tab.requestedUrl !== undefined ? { requestedUrl: tab.requestedUrl, redirects: tab.redirects } : {}), title: data.title, text: data.text, textTruncated: data.textTruncated, links: data.links, linksTruncated: data.linksTruncated,
         note: 'New automation tab closed after extraction; no reusable target. Use safari_open when later interaction is needed. Untrusted page content; URL checks only, not document identity.' };
       bound(result);
       // Fetch results never advertise a usable target, even if cleanup is unconfirmed.

package/src/search.ts

@@ -3,20 +3,57 @@ import { webURL } from './extraction.ts';
 // DuckDuckGo HTML's documented URL controls; deliberately not arbitrary provider parameters.
 export const REGIONS = ['wt-wt', 'us-en', 'uk-en', 'ca-en', 'au-en', 'de-de', 'fr-fr', 'in-en', 'jp-jp'] as const;
 export const TIMES = ['any', 'd', 'w', 'm', 'y'] as const;
-export interface SearchOptions { query: string; maxResults?: number; region?: string; time?: string }
-export function searchRequest(options: SearchOptions) {
-  const { query, maxResults = 5, region = 'wt-wt', time = 'any' } = options;
-  if (typeof query !== 'string' || !query.trim() || query.length > 500 || /[\u0000-\u001f\u007f]/.test(query)) throw Error('Search query must be 1..500 characters without control characters.');
-  if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 10) throw Error('maxResults must be 1..10.');
-  if (!(REGIONS as readonly string[]).includes(region) || !(TIMES as readonly string[]).includes(time)) throw Error('Unsupported search region or time filter.');
-  const url = new URL('https://html.duckduckgo.com/html/');
-  url.searchParams.set('q', query.trim()); url.searchParams.set('kl', region);
-  if (time !== 'any') url.searchParams.set('df', time);
-  return { query: query.trim(), maxResults, region, time, url: url.href };
+export const PAGE_LIMIT = 30;
+const PAGER_LIMIT = 12;
+// Caller-supplied CSS selectors that steer the generic extractor. CSS only: no JS, no attributes beyond :(), no forms/clicks.
+export interface SearchSelectors { item: string; link?: string; title?: string; snippet?: string }
+export interface SearchOptions { query?: string; url?: string; region?: string; time?: string; selectors?: SearchSelectors }
+export interface SearchRequest {
+  mode: 'ddg' | 'generic';
+  url: string;
+  query?: string;
+  region?: string;
+  time?: string;
+  selectors?: SearchSelectors;
+}
+export function validateSelectors(selectors: unknown): SearchSelectors {
+  if (typeof selectors !== 'object' || selectors === null || Array.isArray(selectors)) throw Error('selectors must be an object with an item CSS selector.');
+  const s = selectors as Record<string, unknown>;
+  if (typeof s.item !== 'string' || s.item.trim().length < 1) throw Error('selectors.item is required when selectors are supplied.');
+  const out: SearchSelectors = { item: s.item.trim() };
+  for (const key of ['link', 'title', 'snippet'] as const) {
+    if (s[key] === undefined) continue;
+    if (typeof s[key] !== 'string') throw Error(`selectors.${key} must be a CSS selector string.`);
+    out[key] = (s[key] as string).trim();
+  }
+  for (const [key, value] of Object.entries(out)) {
+    if (value.length < 1 || value.length > 500) throw Error(`selectors.${key} must be 1..500 characters.`);
+    if (/[^a-zA-Z0-9 _~.,:#\[\]>'"*\\()=^$|&%!\-?+]/.test(value)) throw Error(`selectors.${key} contains disallowed characters.`);
+  }
+  return out;
+}
+export function searchRequest(options: SearchOptions): SearchRequest {
+  const { query, url, region = 'wt-wt', time = 'any' } = options;
+  const hasQuery = typeof query === 'string';
+  const hasURL = typeof url === 'string';
+  if (hasQuery === hasURL) throw Error('Pass exactly one of query (built-in DuckDuckGo HTML search) or url (any HTTP(S) search-results page).');
+  if (hasQuery) {
+    const q = query as string;
+    if (!q.trim() || q.length > 500 || /[\u0000-\u001f\u007f]/.test(q)) throw Error('Search query must be 1..500 characters without control characters.');
+    if (!(REGIONS as readonly string[]).includes(region) || !(TIMES as readonly string[]).includes(time)) throw Error('Unsupported search region or time filter.');
+    const u = new URL('https://html.duckduckgo.com/html/');
+    u.searchParams.set('q', q.trim()); u.searchParams.set('kl', region);
+    if (time !== 'any') u.searchParams.set('df', time);
+    if (options.selectors !== undefined) throw Error('selectors are only for url mode; the built-in DuckDuckGo search uses fixed markup.');
+    return { mode: 'ddg', query: q.trim(), region, time, url: u.href };
+  }
+  const generic: SearchRequest = { mode: 'generic', url: webURL(url as string) };
+  if (options.selectors !== undefined) generic.selectors = validateSelectors(options.selectors);
+  return generic;
 }
 export interface SearchResult { rank: number; title: string; url: string; snippet: string }
-export function validateSearch(data: any, expectedUrl: string, maxResults: number): { results: SearchResult[]; truncated: boolean } {
-  if (!data || data.url !== expectedUrl || !Array.isArray(data.results) || data.results.length > maxResults || typeof data.truncated !== 'boolean') throw Error('Invalid Safari search result.');
+export function validateSearch(data: any, expectedUrl: string): { results: SearchResult[]; truncated: boolean } {
+  if (!data || data.url !== expectedUrl || !Array.isArray(data.results) || data.results.length > PAGE_LIMIT || typeof data.truncated !== 'boolean') throw Error('Invalid Safari search result.');
   const seen = new Set<string>();
   for (const [i, r] of data.results.entries()) {
     if (!r || r.rank !== i + 1 || typeof r.title !== 'string' || !r.title.trim() || r.title.length > 300 || typeof r.snippet !== 'string' || r.snippet.length > 600 || typeof r.url !== 'string' || r.url.length > 2048 || webURL(r.url) !== r.url || seen.has(r.url)) throw Error('Invalid Safari search entry.');
@@ -24,10 +61,23 @@ export function validateSearch(data: any, expectedUrl: string, maxResults: numbe
   }
   return { results: data.results, truncated: data.truncated };
 }
+export function validateGenericSearch(data: any, expectedUrl: string): { results: SearchResult[]; pager: string[]; truncated: boolean } {
+  if (!data || data.url !== expectedUrl || !Array.isArray(data.results) || data.results.length > PAGE_LIMIT || !Array.isArray(data.pager) || data.pager.length > PAGER_LIMIT || typeof data.truncated !== 'boolean') throw Error('Invalid Safari search result.');
+  const seen = new Set<string>();
+  for (const [i, r] of data.results.entries()) {
+    if (!r || r.rank !== i + 1 || typeof r.title !== 'string' || !r.title.trim() || r.title.length > 300 || typeof r.snippet !== 'string' || r.snippet.length > 300 || typeof r.url !== 'string' || r.url.length > 2048 || webURL(r.url) !== r.url || seen.has(r.url)) throw Error('Invalid Safari search entry.');
+    seen.add(r.url);
+  }
+  const pages = new Set<string>();
+  for (const p of data.pager) {
+    if (typeof p !== 'string' || p.length > 8192 || webURL(p) !== p || pages.has(p)) throw Error('Invalid Safari search pager link.');
+    pages.add(p);
+  }
+  return { results: data.results, pager: data.pager, truncated: data.truncated };
+}
 // Fixed, read-only selectors. No raw query, arbitrary selector, click, form or provider script execution.
-export function searchJS(expectedUrl: string, maxResults: number): string {
+export function searchJS(expectedUrl: string): string {
   webURL(expectedUrl);
-  if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 10) throw Error('maxResults must be 1..10.');
   return `JSON.stringify((()=>{
     if(location.href!==${JSON.stringify(expectedUrl)})throw Error('Search URL changed');
     const visible=e=>e&&e.getClientRects().length&&getComputedStyle(e).visibility==='visible'&&getComputedStyle(e).display!=='none';
@@ -42,10 +92,134 @@ export function searchJS(expectedUrl: string, maxResults: number): string {
       }catch{continue;}
       if(!/^https?:$/.test(u.protocol)||u.username||u.password||u.href.length>2048||['duckduckgo.com','html.duckduckgo.com'].includes(u.hostname)||seen.has(u.href))continue;
       const title=text(a,300); if(!title)continue; seen.add(u.href);
-      if(results.length===${maxResults}){truncated=true;break;}
+      if(results.length===${PAGE_LIMIT}){truncated=true;break;}
       const snippet=node.querySelector('.result__snippet');
       results.push({rank:results.length+1,title,url:u.href,snippet:visible(snippet)?text(snippet,600):''});
     }
     return {url:location.href,results,truncated};
   })())`;
 }
+// Shared read-only guards: exact-URL assertion, visibility and text helpers, and same-site
+// clickthrough unwrapping (Bing a1 base64, DuckDuckGo uddg, Yahoo RU=). Same-site: same host,
+// or same last two dot labels.
+function searchHelpersJS(serpHost: string): string {
+  return `const visible=e=>e&&e.getClientRects().length&&getComputedStyle(e).visibility==='visible'&&getComputedStyle(e).display!=='none';
+    const text=e=>(e?.innerText||'').replace(/\\s+/g,' ');
+    const siteOf=h=>h.split('.').slice(-2).join('.');
+    const unwrap=a=>{
+      let u; try { u=new URL(a.href,location.href); } catch { return null; }
+      if(/^https?:$/.test(u.protocol)&&siteOf(u.hostname.toLowerCase())===${JSON.stringify(serpHost)}){
+        let d=null;
+        const enc=u.searchParams.get('u')||'';
+        if(enc.startsWith('a1')){
+          try {
+            let b=enc.slice(2).replace(/-/g,'+').replace(/_/g,'/'); while(b.length%4)b+='=';
+            const c=new URL(atob(b));
+            if(/^https?:$/.test(c.protocol)&&!c.username&&!c.password&&c.href.length<=2048)d=c;
+          } catch {}
+        }
+        if(!d){
+          const ud=u.searchParams.get('uddg');
+          if(ud){
+            try {
+              const c=new URL(decodeURIComponent(ud),location.href);
+              if(/^https?:$/.test(c.protocol)&&!c.username&&!c.password&&c.href.length<=2048)d=c;
+            } catch {}
+          }
+        }
+        if(!d){
+          for(const seg of u.pathname.split('/')){
+            if(!seg.startsWith('RU='))continue;
+            try {
+              const c=new URL(decodeURIComponent(seg.slice(3)));
+              if(/^https?:$/.test(c.protocol)&&!c.username&&!c.password&&c.href.length<=2048)d=c;
+            } catch {}
+            break;
+          }
+        }
+        if(d)u=d;
+      }
+      if(!/^https?:$/.test(u.protocol)||u.username||u.password||u.href.length>2048)return null;
+      return u;
+    };`;
+}
+// Pager detection shared by both generic paths: exact next/numbered labels, 12 unique URLs.
+function pagerJS(): string {
+  return `const pager=[]; const pages=new Set();
+    for(const a of anchors){
+      if(!visible(a))continue;
+      const t=text(a).trim();
+      if(!pagerRe.test(t))continue;
+      let u; try { u=new URL(a.href,location.href); } catch { continue; }
+      if(!/^https?:$/.test(u.protocol)||u.username||u.password||pages.has(u.href))continue;
+      pages.add(u.href);
+      if(pager.length===${PAGER_LIMIT})break;
+      pager.push(u.href);
+    }`;
+}
+// Fixed heuristic extractor for arbitrary search-results pages chosen by the caller as a URL.
+// Same safety style as searchJS: read-only, exact-URL assertion, safe helpers only.
+// Without selectors: two-tier anchor heuristic (heading-anchored results first, then all
+// anchors) for minimal markup. With caller-supplied selectors (generic mode only): item
+// selects each result container; link/title/snippet select sub-parts and are optional,
+// falling back to the anchor, an inner heading and the box tail. Both paths share the
+// same URL guards, dedupe, 30-result cap and pager detection.
+export function genericSearchJS(expectedUrl: string, selectors?: SearchSelectors): string {
+  webURL(expectedUrl);
+  const selectorJS = selectors ? `
+    const items=Array.from(document.querySelectorAll(${JSON.stringify(selectors.item)})).slice(0,300);
+    const results=[]; const seen=new Set(); let truncated=items.length>300;
+    for(const node of items){
+      if(!visible(node))continue;
+      const a=node.querySelector(${JSON.stringify(selectors.link ?? 'a[href]')});
+      if(!a||!a.href||!visible(a))continue;
+      const u=unwrap(a); if(!u||seen.has(u.href))continue; seen.add(u.href);
+      if(results.length===${PAGE_LIMIT}){truncated=true;break;}
+      let title='';
+      ${selectors.title ? `const tEl=node.querySelector(${JSON.stringify(selectors.title)}); if(tEl)title=text(tEl).trim().slice(0,300);` : ''}
+      if(!title){ const heading=a.querySelector('h1,h2,h3,h4'); title=((heading&&text(heading).trim().length>=8)?text(heading):text(a)).trim().slice(0,300); }
+      if(!title)continue;
+      let snippet='';
+      ${selectors.snippet ? `const sEl=node.querySelector(${JSON.stringify(selectors.snippet)}); if(sEl)snippet=text(sEl).trim().slice(0,300);` : ''}
+      if(!snippet){ const box=a.closest('article,li'); const raw=box?text(box):''; const at=raw.indexOf(title); if(at>=0)snippet=raw.slice(at+title.length).trim().slice(0,300); }
+      results.push({rank:results.length+1,title,url:u.href,snippet});
+    }
+    const anchors=Array.from(document.querySelectorAll('a[href]')).slice(0,2000);
+    ` : `
+    const anchors=Array.from(document.querySelectorAll('a[href]')).slice(0,2000);
+    // Tier 1: anchors whose organic title is an h1..h4 (wrapping or wrapped). Tier 2 fallback:
+    // generic container heuristic for minimal markup (e.g. DuckDuckGo Lite).
+    const headingOf=a=>a.querySelector('h1,h2,h3,h4')||a.closest('h1,h2,h3,h4');
+    const tier1=anchors.filter(a=>visible(a)&&!pagerRe.test(text(a).trim())&&headingOf(a));
+    const pool=tier1.length?tier1:anchors;
+    const results=[]; const seen=new Set(); let truncated=anchors.length>2000;
+    for(const a of pool){
+      if(!visible(a))continue;
+      const label0=text(a).trim();
+      if(pagerRe.test(label0))continue;
+      const heading=headingOf(a);
+      const label=((heading&&text(heading).trim().length>=8)?text(heading).trim():label0);
+      if(label.length<8||label.length>300)continue;
+      if(/https?:\\/\\//i.test(label)||/^[\\w.-]+\\.[a-z]{2,}(:\\d+)?(\\/\\S*)?$/i.test(label))continue;
+      if(!a.closest('article,li,main,section,td')||a.closest('nav,footer,aside,form'))continue;
+      const u=unwrap(a); if(!u||seen.has(u.href))continue;
+      seen.add(u.href);
+      if(results.length===${PAGE_LIMIT}){truncated=true;break;}
+      const box=a.closest('article,li');
+      let snippet='';
+      if(box){
+        const raw=text(box); const at=raw.indexOf(label);
+        if(at>=0)snippet=raw.slice(at+label.length).trim().slice(0,300);
+      }
+      results.push({rank:results.length+1,title:label,url:u.href,snippet});
+    }
+    `;
+  return `JSON.stringify((()=>{
+    if(location.href!==${JSON.stringify(expectedUrl)})throw Error('Search URL changed');
+    ${searchHelpersJS(new URL(expectedUrl).hostname.toLowerCase())}
+    const pagerRe=/^(next|next page|\\u203a|\\u00bb|\\u2026|\\d{1,3})$/i;
+    ${selectorJS}
+    ${pagerJS()}
+    return {url:location.href,results,pager,truncated};
+  })())`;
+}