Page Interaction

Tools for interacting with page content. All page interaction tools work on background tabs and support a tabId parameter to target a specific tab.

firefox_get_content

Get the text content of a page or a specific element. HTML is excluded by default and text is truncated at 50K characters.

Parameters

Parameter	Type	Default	Description
tabId	number	active tab	Target tab ID
selector	string	—	CSS selector to extract content from a specific element
includeHtml	boolean	false	Include raw HTML in response (can be very large)
maxLength	number	50000	Max text length before truncation
timeout	number	150000	Request timeout in ms (5000-300000)

Example

// Get full page text
const page = await firefox_get_content({ tabId: 42 });
// Returns: { url, title, text }

// Get text from a specific element
const article = await firefox_get_content({
  tabId: 42,
  selector: "article.main-content"
});

Tips

• Use selector for focused extraction instead of increasing maxLength.
• Set includeHtml: true only when you need to inspect markup structure.

---

firefox_click

Click an element by CSS selector.

Parameters

Parameter	Type	Default	Description
selector	string	required	CSS selector for the element to click
tabId	number	active tab	Target tab ID
timeout	number	150000	Request timeout in ms (5000-300000)

Example

await firefox_click({ selector: "button.submit", tabId: 42 });
// Returns: { text, id, className } of the clicked element

Tips

• If a click triggers navigation, follow up with firefox_wait_for to confirm the page loaded.
• Use specific selectors (#login-btn) over generic ones (button) when multiple matches exist.

---

firefox_type

Type text into an input field. Compatible with React and Angular controlled inputs.

Parameters

Parameter	Type	Default	Description
selector	string	required	CSS selector for the input element
text	string	required	Text to type into the input
tabId	number	active tab	Target tab ID
clear	boolean	true	Clear existing text before typing
timeout	number	150000	Request timeout in ms (5000-300000)

Example

// Type into a search box
await firefox_type({
  selector: "input[name='search']",
  text: "Claude Code",
  tabId: 42
});

// Append to existing text
await firefox_type({
  selector: "#notes",
  text: " additional text",
  clear: false
});

---

firefox_press_key

Send a keyboard event. More reliable than clicking for form submission and keyboard navigation.

Parameters

Parameter	Type	Default	Description
key	string	required	Key to press (see supported keys below)
tabId	number	active tab	Target tab ID
selector	string	—	CSS selector for target element (default: focused element)
ctrlKey	boolean	false	Hold Ctrl key
shiftKey	boolean	false	Hold Shift key
altKey	boolean	false	Hold Alt key
metaKey	boolean	false	Hold Meta/Cmd key (Mac)
timeout	number	150000	Request timeout in ms (5000-300000)

Supported keys

Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, and single characters (a-z, 0-9).

Example

// Submit a form
await firefox_press_key({ key: "Enter", tabId: 42 });

// Select all text
await firefox_press_key({ key: "a", ctrlKey: true });

// Focus a specific element and press Escape
await firefox_press_key({ key: "Escape", selector: ".modal" });

---

firefox_screenshot

Capture a screenshot with dynamic page readiness detection. Automatically waits for network idle and render settlement before capture. Requests are serialized via mutex to prevent tab-switching collisions.

Parameters

Parameter	Type	Default	Description
tabId	number	active tab	Tab to capture (switches to it)
purpose	string	read-text	Quality preset (see below)
quality	number	60	JPEG quality 1-100 (overrides preset)
scale	number	0.5	Resolution scale 0.25-1.0 (overrides preset)
format	string	jpeg	Image format: jpeg or png
maxWait	number	10000	Max ms to wait for page readiness
waitForImages	boolean	true	Wait for images/fonts to load
skipReadiness	boolean	false	Skip readiness detection (instant capture)
annotate	boolean	false	Overlay numbered badges on interactive elements
timeout	number	150000	Request timeout in ms (5000-300000)

Purpose presets

Preset	Quality	Scale	Use case
quick-glance	30	0.25	Layout and navigation confirmation
read-text	60	0.5	Reading content (default)
inspect-ui	80	0.75	UI details and small text
full-detail	95	1.0	Pixel-perfect inspection

Example

// Default screenshot
const shot = await firefox_screenshot({ tabId: 42 });
// Returns: { tabId, dataUrl, readiness: { waitMs, timedOut, timeline } }

// Annotated screenshot for element identification
const annotated = await firefox_screenshot({
  tabId: 42,
  annotate: true,
  purpose: "inspect-ui"
});
// Returns labels map: { 1: { selector, text, role }, 2: ... }

// Fast capture of a known-ready page
await firefox_screenshot({ tabId: 42, skipReadiness: true });

Tips

• Use firefox_get_page_state instead when you only need structured data — it is much faster and uses no mutex.
• The annotate option is useful for vision models to reference elements by number.
• If you get a MUTEX_BUSY error, another agent is mid-screenshot. Retry after a short delay or use getPageState.

---

firefox_scroll

Scroll to an element or position on the page.

Parameters

Parameter	Type	Default	Description
tabId	number	active tab	Target tab ID
selector	string	—	CSS selector to scroll to
x	number	—	X coordinate to scroll to
y	number	—	Y coordinate to scroll to
behavior	string	smooth	Scroll behavior: smooth or instant
timeout	number	150000	Request timeout in ms (5000-300000)

Example

// Scroll to an element
await firefox_scroll({ selector: "#footer", tabId: 42 });

// Scroll to top instantly
await firefox_scroll({ x: 0, y: 0, behavior: "instant" });

---

firefox_wait_for

Wait for a condition on the page. Supports waiting for a CSS selector, body text, or URL match. Only one condition can be specified per call.

Parameters

Parameter	Type	Default	Description
tabId	number	active tab	Target tab ID
selector	string	—	CSS selector to wait for
text	string	—	Wait until body text contains this string
url	string	—	Wait until URL matches this glob pattern
timeout	number	10000	Maximum time to wait in ms

Example

// Wait for a loading spinner to disappear and content to appear
await firefox_wait_for({ selector: ".results-loaded", tabId: 42 });

// Wait for navigation after form submit
await firefox_wait_for({ url: "**/dashboard", timeout: 15000 });

// Wait for dynamic text content
await firefox_wait_for({ text: "Order confirmed", tabId: 42 });

Tips

• Only one of selector, text, or url can be used per call.
• Useful after firefox_click or firefox_navigate to wait for the page to settle.
• The url parameter supports glob patterns (e.g., **/dashboard).

---

firefox_handle_consent

Detect and dismiss GDPR/cookie consent overlays. Tries multiple strategies: CMP-specific selectors (Google, OneTrust, Cookiebot), text pattern matching, shadow DOM traversal, and ARIA dialogs. Non-fatal — returns found: false if no overlay detected rather than throwing errors.

Parameters

Parameter	Type	Default	Description
tabId	number	active tab	Target tab ID
scanTimeout	number	3000	Max ms to spend scanning for consent elements (500-10000)
timeout	number	150000	Request timeout in ms (5000-300000)

Return value

{
  found: boolean,          // Was a consent button found?
  clicked: boolean,        // Was it successfully clicked?
  buttonText: string|null, // Text content of the button that was clicked
  method: string|null,     // Detection method: 'cmp-selector' | 'text-match' | 'shadow-dom' | 'aria-dialog'
  elapsed: number          // Time taken in ms
}

If no consent overlay is found: { found: false, clicked: false, buttonText: null, method: null, elapsed: N }

Example

// Explicitly dismiss a consent overlay after navigation
await firefox_navigate({ url: "https://example.com" });
const result = await firefox_handle_consent({ tabId: 42 });
if (result.found) {
  console.log(`Dismissed consent via ${result.method}: "${result.buttonText}"`);
}

// Enable auto-consent for all navigations
await firefox_set_config({ handleConsent: true });
// Now every firefox_navigate and firefox_create_window will auto-dismiss consent overlays 800ms after the page loads

Tips

• Explicit mode: Call firefox_handle_consent after firefox_navigate or when you suspect a consent overlay.
• Auto-trigger mode: Enable handleConsent: true via firefox_set_config for automatic dismissal after every navigation (see Configuration tools).
• 4-pass detection: Pass 1 tries known CMP selectors (fastest), Pass 2 text-matches buttons, Pass 3 scans shadow DOM hosts, Pass 4 checks ARIA dialogs.
• Known limitations: TrustArc renders inside cross-origin iframes (inaccessible), and closed-mode Shadow DOM roots return null (silently skipped). Custom obfuscated consent mechanics are out of scope.
• Google consent timing: Google’s consent.google.com button may not appear until after JavaScript runs. The auto-trigger uses 800ms delay to account for this. For explicit calls, use firefox_wait_for first if needed.