fantoma 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. fantoma/__init__.py +4 -0
  2. fantoma/agent.py +333 -0
  3. fantoma/browser/__init__.py +0 -0
  4. fantoma/browser/actions.py +291 -0
  5. fantoma/browser/consent.py +199 -0
  6. fantoma/browser/email_verify.py +199 -0
  7. fantoma/browser/engine.py +425 -0
  8. fantoma/browser/fingerprint.py +218 -0
  9. fantoma/browser/form_assist.py +157 -0
  10. fantoma/browser/form_login.py +809 -0
  11. fantoma/browser/form_memory.py +170 -0
  12. fantoma/browser/humanize.py +78 -0
  13. fantoma/browser/observer.py +200 -0
  14. fantoma/browser/page_state.py +256 -0
  15. fantoma/browser/proxy.py +176 -0
  16. fantoma/browser/stealth.py +130 -0
  17. fantoma/browser/verification.py +224 -0
  18. fantoma/browser_tool.py +469 -0
  19. fantoma/captcha/__init__.py +0 -0
  20. fantoma/captcha/api_solver.py +107 -0
  21. fantoma/captcha/detector.py +103 -0
  22. fantoma/captcha/human_solver.py +65 -0
  23. fantoma/captcha/orchestrator.py +259 -0
  24. fantoma/captcha/pow_solver.py +38 -0
  25. fantoma/captcha/sitekey.py +206 -0
  26. fantoma/captcha/telegram_solver.py +154 -0
  27. fantoma/cli.py +1078 -0
  28. fantoma/config.py +88 -0
  29. fantoma/dom/__init__.py +0 -0
  30. fantoma/dom/accessibility.py +687 -0
  31. fantoma/dom/diff.py +106 -0
  32. fantoma/dom/extractor.py +469 -0
  33. fantoma/dom/frames.py +107 -0
  34. fantoma/dom/selectors.py +149 -0
  35. fantoma/llm/__init__.py +0 -0
  36. fantoma/llm/client.py +209 -0
  37. fantoma/resilience/__init__.py +0 -0
  38. fantoma/resilience/escalation.py +61 -0
  39. fantoma/session.py +136 -0
  40. fantoma-0.7.0.dist-info/METADATA +531 -0
  41. fantoma-0.7.0.dist-info/RECORD +44 -0
  42. fantoma-0.7.0.dist-info/WHEEL +4 -0
  43. fantoma-0.7.0.dist-info/entry_points.txt +2 -0
  44. fantoma-0.7.0.dist-info/licenses/LICENSE +21 -0
fantoma/__init__.py ADDED
@@ -0,0 +1,4 @@
1
+ """Fantoma — The undetectable AI browser agent."""
2
+ __version__ = "0.7.0"
3
+ from fantoma.browser_tool import Fantoma
4
+ from fantoma.agent import Agent, AgentResult
fantoma/agent.py ADDED
@@ -0,0 +1,333 @@
1
+ """Fantoma Agent — convenience wrapper for vibe coders.
2
+
3
+ Provides run() — describe a task in English, the agent does it.
4
+ Delegates all browser operations to the Fantoma tool class.
5
+ """
6
+ import logging
7
+ import re
8
+ import threading
9
+ import time
10
+ from dataclasses import dataclass
11
+ from typing import Any
12
+
13
+ from fantoma.browser_tool import Fantoma
14
+ from fantoma.llm.client import LLMClient
15
+ from fantoma.resilience.escalation import EscalationChain
16
+
17
+ log = logging.getLogger("fantoma")
18
+
19
+
20
+ @dataclass
21
+ class AgentResult:
22
+ """Result of an agent.run() call."""
23
+ success: bool
24
+ data: Any = None
25
+ steps_taken: int = 0
26
+ steps_detail: list = None
27
+ error: str = ""
28
+ tokens_used: int = 0
29
+ escalations: int = 0
30
+
31
+
32
+ # ── LLM prompts (orchestrator concerns) ─────────────────────
33
+
34
+ REACTIVE_PROMPT = """\
35
+ You control a browser. Your job is to COMPLETE the task, not just observe the page.
36
+
37
+ Pick 1-5 actions from this list (one per line):
38
+ CLICK [number]
39
+ TYPE [number] "text"
40
+ SELECT [number] "option"
41
+ SCROLL down
42
+ SCROLL up
43
+ NAVIGATE https://example.com
44
+ PRESS Enter
45
+ DONE
46
+
47
+ Rules:
48
+ - Match [number] to the element list shown after the task.
49
+ - Elements marked with * are NEW (just appeared from your last action) — focus on these.
50
+ - You may return multiple actions (one per line) to execute in sequence.
51
+ - To fill a form: TYPE each field, then CLICK submit — all in one response.
52
+ - After typing in a search field, add PRESS Enter.
53
+ - NAVIGATE and DONE end the sequence — any actions after them are ignored.
54
+ - Only say DONE when the task is fully COMPLETED.
55
+ - Do NOT say DONE just because you can see a form or page — you must interact with it first.
56
+ - If secrets are available, use them with <secret:name> syntax.
57
+ - After each action you'll see an outcome. Use this feedback.
58
+ - Reply with ONLY action lines, nothing else.\
59
+ """
60
+
61
+ EXTRACTION_PROMPT = """\
62
+ Extract ONLY the answer from the page content below. No code. No explanation. Just the data.\
63
+ """
64
+
65
+ COMPACTION_PROMPT = """\
66
+ Summarize what has been accomplished so far in this browser automation task.
67
+ Include: pages visited, forms filled, buttons clicked, data found, errors encountered.
68
+ Be specific. Keep it under 200 words.\
69
+ """
70
+
71
+ # ── Action parsing ───────────────────────────────────────────
72
+
73
+
74
+ def _parse_actions(raw: str) -> list[tuple[str, dict]]:
75
+ """Parse LLM response into (action_type, params) tuples."""
76
+ results = []
77
+ for line in (raw or "").strip().split("\n"):
78
+ line = line.strip()
79
+ if not line:
80
+ continue
81
+
82
+ # CLICK [N]
83
+ m = re.match(r'CLICK\s*\[?(\d+)\]?', line, re.IGNORECASE)
84
+ if m:
85
+ results.append(("click", {"element_id": int(m.group(1))}))
86
+ continue
87
+ # TYPE [N] "text"
88
+ m = re.match(r'TYPE\s*\[?(\d+)\]?\s*["\'](.+?)["\']', line, re.IGNORECASE)
89
+ if m:
90
+ results.append(("type_text", {"element_id": int(m.group(1)), "text": m.group(2)}))
91
+ continue
92
+ # SELECT [N] "value"
93
+ m = re.match(r'SELECT\s*\[?(\d+)\]?\s*["\'](.+?)["\']', line, re.IGNORECASE)
94
+ if m:
95
+ results.append(("select", {"element_id": int(m.group(1)), "value": m.group(2)}))
96
+ continue
97
+ # SCROLL
98
+ m = re.match(r'SCROLL\s*(UP|DOWN)', line, re.IGNORECASE)
99
+ if m:
100
+ results.append(("scroll", {"direction": m.group(1).lower()}))
101
+ continue
102
+ # NAVIGATE
103
+ m = re.match(r'NAVIGATE\s+["\']?(https?://\S+?)["\']?\s*$', line, re.IGNORECASE)
104
+ if m:
105
+ results.append(("navigate", {"url": m.group(1)}))
106
+ break # Terminator
107
+ # PRESS
108
+ m = re.match(r'PRESS\s+(\w+)', line, re.IGNORECASE)
109
+ if m:
110
+ results.append(("press_key", {"key": m.group(1)}))
111
+ continue
112
+ # DONE
113
+ if re.match(r'DONE', line, re.IGNORECASE):
114
+ results.append(("done", {}))
115
+ break # Terminator
116
+
117
+ # Fallback: bare [N] → click
118
+ m = re.search(r'\[(\d+)\]', line)
119
+ if m:
120
+ results.append(("click", {"element_id": int(m.group(1))}))
121
+
122
+ if len(results) >= 5:
123
+ break
124
+
125
+ return results
126
+
127
+
128
+ class Agent:
129
+ """Convenience wrapper — describe a task, the agent does it.
130
+
131
+ Usage:
132
+ agent = Agent(llm_url="http://localhost:8080/v1")
133
+ result = agent.run("Go to HN and find the top post about AI")
134
+ """
135
+
136
+ def __init__(
137
+ self,
138
+ llm_url: str = "http://localhost:8080/v1",
139
+ api_key: str = "",
140
+ model: str = "auto",
141
+ escalation: list[str] = None,
142
+ escalation_keys: list[str] = None,
143
+ max_steps: int = 50,
144
+ sensitive_data: dict = None,
145
+ **kwargs,
146
+ ):
147
+ self.fantoma = Fantoma(llm_url=llm_url, api_key=api_key, model=model, **kwargs)
148
+ self._max_steps = max_steps
149
+ self._sensitive_data = sensitive_data or {}
150
+
151
+ endpoints = escalation or [llm_url]
152
+ keys = escalation_keys or [api_key] + [""] * (len(endpoints) - 1)
153
+ self.escalation = EscalationChain(endpoints, keys)
154
+ self._llm = LLMClient(base_url=llm_url, api_key=api_key, model=model)
155
+
156
+ def run(self, task: str, start_url: str = None) -> AgentResult:
157
+ """Run a browser task described in English."""
158
+ log.info("Task: %s", task)
159
+ history = []
160
+ steps_detail = []
161
+
162
+ try:
163
+ state = self.fantoma.start(start_url)
164
+ except Exception as e:
165
+ return AgentResult(success=False, error=f"Browser start failed: {e}")
166
+
167
+ # Timeout via threading.Event (safe with Playwright greenlets)
168
+ timeout_event = threading.Event()
169
+ timer = threading.Timer(self.fantoma.config.browser.timeout, timeout_event.set)
170
+ timer.daemon = True
171
+ timer.start()
172
+
173
+ try:
174
+ for step_num in range(1, self._max_steps + 1):
175
+ if timeout_event.is_set():
176
+ return AgentResult(success=bool(steps_detail), data=state.get("aria_tree", ""),
177
+ steps_taken=step_num - 1, steps_detail=steps_detail,
178
+ error=f"Timeout after {step_num - 1} steps",
179
+ escalations=self.escalation.total_escalations)
180
+
181
+ # Mask secrets in the ARIA tree
182
+ aria = state["aria_tree"]
183
+ for name, value in self._sensitive_data.items():
184
+ aria = aria.replace(value, f"<secret:{name}>")
185
+
186
+ # Build LLM messages
187
+ messages = [{"role": "system", "content": REACTIVE_PROMPT}]
188
+ if history:
189
+ messages.append({"role": "assistant", "content": "\n".join(history[-10:])})
190
+ messages.append({"role": "user", "content": f"Task: {task}\n\nPage ({state['url']}):\n{aria}"})
191
+
192
+ # Ask LLM
193
+ raw = self._llm.chat(messages, max_tokens=500)
194
+ if not raw:
195
+ continue
196
+
197
+ actions = _parse_actions(raw)
198
+ if not actions:
199
+ continue
200
+
201
+ for action_type, params in actions:
202
+ if action_type == "done":
203
+ data = self._extract_answer(task, state)
204
+ return AgentResult(success=True, data=data, steps_taken=step_num,
205
+ steps_detail=steps_detail,
206
+ escalations=self.escalation.total_escalations)
207
+
208
+ # Unmask secrets before executing
209
+ if "text" in params:
210
+ for name, value in self._sensitive_data.items():
211
+ params["text"] = params["text"].replace(f"<secret:{name}>", value)
212
+
213
+ # Call the Fantoma tool method
214
+ method = getattr(self.fantoma, action_type)
215
+ result = method(**params)
216
+ state = result.get("state", state)
217
+
218
+ action_desc = f"{action_type}({params})"
219
+ outcome = "OK" if result["success"] else "FAILED"
220
+ history.append(f"Step {step_num}: {action_desc} → {outcome}")
221
+ steps_detail.append({"step": step_num, "action": action_desc,
222
+ "success": result["success"], "url": state["url"]})
223
+
224
+ if not result["success"]:
225
+ break # Let LLM re-evaluate on next iteration
226
+
227
+ # Loop detection: last 5 actions identical
228
+ if len(history) >= 5 and len(set(history[-5:])) == 1:
229
+ if self.escalation.can_escalate():
230
+ new_ep = self.escalation.escalate()
231
+ self._llm = LLMClient(base_url=new_ep,
232
+ api_key=self.escalation.current_api_key())
233
+ history.clear()
234
+ else:
235
+ return AgentResult(success=False, error="Action loop detected",
236
+ steps_taken=step_num, steps_detail=steps_detail,
237
+ escalations=self.escalation.total_escalations)
238
+
239
+ return AgentResult(success=False, error="Max steps reached",
240
+ steps_taken=self._max_steps, steps_detail=steps_detail,
241
+ escalations=self.escalation.total_escalations)
242
+ except Exception as e:
243
+ return AgentResult(success=False, error=str(e))
244
+ finally:
245
+ timer.cancel()
246
+ self.fantoma.stop()
247
+
248
+ def login(self, url: str, **creds) -> AgentResult:
249
+ """Log into a site. Delegates to Fantoma."""
250
+ try:
251
+ self.fantoma.start()
252
+ result = self.fantoma.login(url, **creds)
253
+ return AgentResult(
254
+ success=result.get("success", False),
255
+ data=result,
256
+ steps_taken=result.get("steps", 0),
257
+ )
258
+ except Exception as e:
259
+ return AgentResult(success=False, error=str(e))
260
+ finally:
261
+ self.fantoma.stop()
262
+
263
+ def extract(self, url: str, query: str, schema: dict = None):
264
+ """Navigate to a URL and extract data. Delegates to Fantoma."""
265
+ try:
266
+ self.fantoma.start(url)
267
+ return self.fantoma.extract(query, schema)
268
+ except Exception as e:
269
+ log.error("Extract failed: %s", e)
270
+ return [] if schema else ""
271
+ finally:
272
+ self.fantoma.stop()
273
+
274
+ def session(self, start_url: str):
275
+ """Create a step-by-step session."""
276
+ return _Session(self, start_url)
277
+
278
+ def _extract_answer(self, task: str, state: dict) -> str:
279
+ """Try to extract a concise answer from the current page."""
280
+ try:
281
+ messages = [
282
+ {"role": "system", "content": EXTRACTION_PROMPT},
283
+ {"role": "user", "content": f"Task: {task}\n\nPage content:\n{state['aria_tree'][:4000]}"},
284
+ ]
285
+ return self._llm.chat(messages, max_tokens=1000) or ""
286
+ except Exception:
287
+ return state.get("aria_tree", "")[:2000]
288
+
289
+
290
+ class _Session:
291
+ """Step-by-step session using Fantoma tool directly."""
292
+
293
+ def __init__(self, agent: Agent, start_url: str):
294
+ self.agent = agent
295
+ self.start_url = start_url
296
+
297
+ def __enter__(self):
298
+ self.agent.fantoma.start(self.start_url)
299
+ return self
300
+
301
+ def __exit__(self, *args):
302
+ self.agent.fantoma.stop()
303
+
304
+ def act(self, instruction: str) -> dict:
305
+ """Execute one instruction. Sends to LLM, executes result via Fantoma."""
306
+ state = self.agent.fantoma.get_state()
307
+ messages = [
308
+ {"role": "system", "content": REACTIVE_PROMPT},
309
+ {"role": "user", "content": f"Task: {instruction}\n\nPage ({state['url']}):\n{state['aria_tree']}"},
310
+ ]
311
+ raw = self.agent._llm.chat(messages, max_tokens=200)
312
+ actions = _parse_actions(raw or "")
313
+ result = state
314
+ for action_type, params in actions:
315
+ if action_type == "done":
316
+ break
317
+ method = getattr(self.agent.fantoma, action_type)
318
+ r = method(**params)
319
+ result = r.get("state", result)
320
+ return result
321
+
322
+ def extract(self, query: str) -> str:
323
+ """Extract info from current page."""
324
+ return self.agent.fantoma.extract(query)
325
+
326
+ def new_tab(self, url: str, name: str = None) -> dict:
327
+ return self.agent.fantoma.new_tab(url)
328
+
329
+ def switch_tab(self, tab: int | str) -> dict:
330
+ return self.agent.fantoma.switch_tab(tab)
331
+
332
+ def close_tab(self, tab: int | str = None) -> dict:
333
+ return self.agent.fantoma.close_tab(tab)
File without changes
@@ -0,0 +1,291 @@
1
+ """High-level browser actions used by the executor.
2
+
3
+ type_into uses a unified fill approach inspired by Bitwarden's autofill engine:
4
+ one sequence that covers React, Vue, vanilla HTML, and any other framework.
5
+ No detection, no branching — just fires everything in one shot.
6
+
7
+ Backup of previous version: actions.py.backup-20260326
8
+ """
9
+
10
+ import logging
11
+ import random
12
+ import time
13
+
14
+ log = logging.getLogger("fantoma.actions")
15
+
16
+
17
+ def click_element(engine, element_or_selector):
18
+ """Activate an element via focus + keyboard — no mouse events.
19
+
20
+ Uses the accessibility interaction model: focus the element, then
21
+ press Enter (links, buttons) or Space (checkboxes, radios). This
22
+ produces zero mouse telemetry. Falls back to JS el.click() if
23
+ keyboard activation doesn't work.
24
+ """
25
+ page = engine.get_page()
26
+ if isinstance(element_or_selector, str):
27
+ element = page.query_selector(element_or_selector)
28
+ else:
29
+ element = element_or_selector
30
+
31
+ if not element:
32
+ return False
33
+
34
+ # Get element role/type to pick the right key
35
+ tag_and_type = element.evaluate("""el => ({
36
+ tag: el.tagName.toLowerCase(),
37
+ type: (el.getAttribute('type') || '').toLowerCase(),
38
+ role: (el.getAttribute('role') || '').toLowerCase(),
39
+ })""")
40
+ tag = tag_and_type["tag"]
41
+ el_type = tag_and_type["type"]
42
+ role = tag_and_type["role"]
43
+
44
+ # Focus the element
45
+ try:
46
+ element.focus()
47
+ except Exception:
48
+ # Some elements reject focus — try JS
49
+ try:
50
+ element.evaluate("el => el.focus()")
51
+ except Exception:
52
+ pass
53
+
54
+ is_checkbox = el_type in ("checkbox", "radio") or role in ("checkbox", "radio", "switch")
55
+
56
+ # Activate via keyboard
57
+ key = "Space" if is_checkbox else "Enter"
58
+ try:
59
+ page.keyboard.press(key)
60
+ except Exception:
61
+ # Keyboard failed — fall back to JS click (no mouse events)
62
+ try:
63
+ element.evaluate("el => el.click()")
64
+ except Exception:
65
+ return False
66
+
67
+ if engine.humanizer:
68
+ engine.humanizer.action_pause()
69
+
70
+ return True
71
+
72
+
73
+ def _focus_element(page, element):
74
+ """Focus an input element — no mouse events."""
75
+ try:
76
+ element.focus()
77
+ except Exception:
78
+ try:
79
+ element.evaluate("el => el.focus()")
80
+ except Exception:
81
+ # Focus failed — try dismissing consent overlay first
82
+ from fantoma.browser.consent import dismiss_consent
83
+ dismiss_consent(page)
84
+ time.sleep(0.5)
85
+ try:
86
+ element.focus()
87
+ except Exception:
88
+ return False
89
+ time.sleep(0.2)
90
+ return True
91
+
92
+
93
+ def type_into(engine, element_or_selector, text: str, clear_first: bool = True):
94
+ """Type text into any input element. One sequence that works everywhere.
95
+
96
+ Combines techniques from Bitwarden's autofill engine and React issue #11488:
97
+ 1. Click + focus the element
98
+ 2. Reset React's _valueTracker (if present — costs nothing if not)
99
+ 3. Set value via nativeSetter (bypasses React's override, works on vanilla too)
100
+ 4. Fire the full event sequence: keydown, keyup, input, change
101
+ 5. Verify the value stuck
102
+ 6. If it didn't — fall back to keyboard character-by-character
103
+
104
+ No framework detection needed. The same sequence handles React, Vue, Angular,
105
+ vanilla HTML, and every other framework because it covers all event paths.
106
+ """
107
+ page = engine.get_page()
108
+ if isinstance(element_or_selector, str):
109
+ element = page.query_selector(element_or_selector)
110
+ else:
111
+ element = element_or_selector
112
+
113
+ if not element:
114
+ return False
115
+
116
+ if not _focus_element(page, element):
117
+ return False
118
+
119
+ # Human-like path: type character by character with realistic key-pair delays.
120
+ # Sites like X detect instant DOM value injection as automation.
121
+ if engine.humanizer:
122
+ # Reset React's _valueTracker first — without this, React controlled
123
+ # inputs silently discard keystrokes during re-renders
124
+ element.evaluate('''(el) => {
125
+ const tracker = el._valueTracker;
126
+ if (tracker) tracker.setValue('');
127
+ }''')
128
+
129
+ if clear_first:
130
+ page.keyboard.press("Control+a")
131
+ page.keyboard.press("Backspace")
132
+ time.sleep(0.1)
133
+
134
+ prev_char = ""
135
+ for char in text:
136
+ delay = engine.humanizer.type_char_delay(prev_char, char)
137
+ time.sleep(delay)
138
+ page.keyboard.type(char)
139
+ prev_char = char
140
+
141
+ # Verify
142
+ try:
143
+ actual = element.input_value()
144
+ if actual == text:
145
+ return True
146
+ except Exception:
147
+ pass
148
+
149
+ # If keyboard typing didn't stick (rare), fall through to DOM injection
150
+ log.info("Keyboard typing didn't stick — falling back to DOM injection")
151
+
152
+ # Fast path: instant DOM injection via nativeSetter.
153
+ # Used when humanizer is disabled (speed over stealth) or as fallback.
154
+ element.evaluate('''(el, args) => {
155
+ const [text, clear] = args;
156
+
157
+ // Focus properly
158
+ el.blur();
159
+ el.focus();
160
+
161
+ // Reset React's _valueTracker (harmless on non-React)
162
+ const tracker = el._valueTracker;
163
+ if (tracker) {
164
+ tracker.setValue('');
165
+ }
166
+
167
+ // Clear if needed
168
+ if (clear) {
169
+ const proto = Object.getPrototypeOf(el);
170
+ const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
171
+ if (setter) setter.call(el, '');
172
+ else el.value = '';
173
+ el.dispatchEvent(new Event('input', { bubbles: true }));
174
+ }
175
+
176
+ // Set value via native prototype setter (bypasses React override)
177
+ const proto = Object.getPrototypeOf(el);
178
+ const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
179
+ if (setter) setter.call(el, text);
180
+ else el.value = text;
181
+
182
+ // Fire all events
183
+ el.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true }));
184
+ el.dispatchEvent(new KeyboardEvent('keyup', { bubbles: true }));
185
+ el.dispatchEvent(new Event('input', { bubbles: true }));
186
+ el.dispatchEvent(new Event('change', { bubbles: true }));
187
+ }''', [text, clear_first])
188
+
189
+ # Verify the value stuck
190
+ try:
191
+ actual = element.input_value()
192
+ if actual == text:
193
+ return True
194
+ except Exception:
195
+ pass
196
+
197
+ return False
198
+
199
+
200
+ def scroll_page(engine, direction: str = "down", amount: int = None):
201
+ """Scroll via keyboard — no mouse wheel events.
202
+
203
+ Uses PageDown/PageUp like a screen reader user would.
204
+ """
205
+ page = engine.get_page()
206
+ key = "PageUp" if direction == "up" else "PageDown"
207
+ page.keyboard.press(key)
208
+
209
+ if engine.humanizer:
210
+ time.sleep(random.uniform(*engine.humanizer.scroll_delay))
211
+
212
+ return True
213
+
214
+
215
+ def wait_for_navigation(engine, timeout: int = 10000):
216
+ """Wait for page to finish loading."""
217
+ try:
218
+ engine.get_page().wait_for_load_state("domcontentloaded", timeout=timeout)
219
+ return True
220
+ except Exception:
221
+ return False
222
+
223
+
224
+ def wait_for_network_idle(engine, timeout: int = 15000):
225
+ """Wait for network activity to settle — catches SPA transitions (React, Vue, etc).
226
+
227
+ Use after actions that trigger navigation or heavy loading (login, form submit).
228
+ Falls back to domcontentloaded if networkidle times out.
229
+ """
230
+ try:
231
+ engine.get_page().wait_for_load_state("networkidle", timeout=timeout)
232
+ return True
233
+ except Exception:
234
+ try:
235
+ engine.get_page().wait_for_load_state("domcontentloaded", timeout=5000)
236
+ except Exception:
237
+ pass
238
+ return False
239
+
240
+
241
+ def search_page(page, query: str) -> list[dict]:
242
+ """Find all visible text matches on the page. Like Ctrl+F. Free — no LLM cost."""
243
+ try:
244
+ results = page.evaluate("""(query) => {
245
+ const matches = [];
246
+ const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
247
+ let idx = 0;
248
+ const queryLower = query.toLowerCase();
249
+ while (walker.nextNode()) {
250
+ const text = walker.currentNode.textContent;
251
+ if (text.toLowerCase().includes(queryLower)) {
252
+ const el = walker.currentNode.parentElement;
253
+ if (el && el.offsetParent !== null) {
254
+ const full = el.innerText || text;
255
+ const pos = full.toLowerCase().indexOf(queryLower);
256
+ const start = Math.max(0, pos - 30);
257
+ const end = Math.min(full.length, pos + query.length + 30);
258
+ matches.push({text: full.substring(start, end).trim(), index: idx});
259
+ idx++;
260
+ }
261
+ }
262
+ }
263
+ return matches.slice(0, 20);
264
+ }""", query)
265
+ return results or []
266
+ except Exception as e:
267
+ log.warning("search_page failed: %s", e)
268
+ return []
269
+
270
+
271
+ def find_elements(page, selector: str) -> list[dict]:
272
+ """Query elements by CSS selector. Like browser DevTools. Free — no LLM cost."""
273
+ try:
274
+ results = page.evaluate("""(selector) => {
275
+ const els = document.querySelectorAll(selector);
276
+ return Array.from(els)
277
+ .filter(el => el.offsetParent !== null)
278
+ .slice(0, 20)
279
+ .map(el => ({
280
+ tag: el.tagName.toLowerCase(),
281
+ type: el.getAttribute('type') || '',
282
+ name: el.getAttribute('name') || '',
283
+ id: el.getAttribute('id') || '',
284
+ text: (el.innerText || el.value || '').substring(0, 100).trim(),
285
+ href: el.getAttribute('href') || '',
286
+ }));
287
+ }""", selector)
288
+ return results or []
289
+ except Exception as e:
290
+ log.warning("find_elements failed: %s", e)
291
+ return []