io.github.feedthrough/feedthrough

Click an element by calling its native click(), which fires a click event and runs the default activation: following a link, toggling a checkbox or radio, submitting a form. Prefer an id selector (#submit-btn) for reliable targeting. Note it does NOT synthesize the preceding pointer/mouse sequence (pointerdown / mousedown / mouseup) or move focus, so a handler wired specifically to those events rather than to click won't fire; for keyboard-driven activation use press_key instead. Behavior: if the selector matches nothing the call returns an error; it does not scroll the element into view, and it does not wait for any resulting navigation, network, or re-render to settle, returning as soon as the click is dispatched. Observe the effect with a follow-up get_console_logs / get_network_requests / query_dom. Returns the tag and id of the clicked element.

Check whether a browser with the Feedthrough bridge is currently connected. Returns a connected flag, a list of open tabs (id, url, which is active), and a 'server' block identifying this bridge: its name, version, and the port it actually bound. That port matters — if another agent session's server already held the default 8765, this one moved up, and the page will not find it until the app's dev server is started with FEEDTHROUGH_PORT set to the reported port. When a page is connected but behaving as though someone else is driving it, compare this name with the 'server' field from get_page_info: different names mean the tab is paired with another session's bridge. Call this first — every tool except get_instructions requires a connected browser.

Set the value of an input, textarea, or select element. Focuses the element, assigns the value through the element's native value setter (so React/Vue controlled inputs register the change), then fires bubbling input and change events. The value is set in one shot, not typed character by character, so per-keystroke handlers (keydown / keypress / keyup / beforeinput) do NOT fire; to send Enter to submit or trigger a key shortcut, follow with press_key. Prefer an id selector (#search-input). If the selector matches nothing the call returns an error; it returns as soon as the events are dispatched and does not wait for downstream validation or re-renders. Returns the tag and the value that was set.

Return console output captured since the bridge connected. Covers every console method — log/warn/error/info/debug plus dir, table, assert, trace, count, countReset, time/timeEnd/timeLog, group/groupCollapsed/groupEnd, and clear. Each entry has a 'level' (the closest of the five standard levels); rich methods also carry a 'method' field, and console.trace() plus failing console.assert() entries include a 'stack'. Uncaught exceptions and unhandled promise rejections are also captured (level 'error', method 'uncaught' / 'unhandledrejection') even though the app never logged them. When the app is noisy with framework or deprecation warnings, pass levels: ['error'] (or ['error', 'warn']) so the real errors aren't buried, and use 'match' to narrow by content. Pass 'since' (a ms timestamp from an earlier entry's 'ts', or Date.now() before an action) to see only what happened after that point. Read-only: it returns a passively captured buffer and neither clears the console nor changes the page. Always check this early — app errors and debug output often identify the root cause immediately.

Return the outerHTML of an element (capped at 50 KB). Use this when the summarised query_dom output isn't enough and you need to see the actual markup/structure of a region. Read-only: it only reads the DOM and makes no changes, and it returns an error if the selector matches nothing.

Returns the Feedthrough usage guide as a Markdown text document, with sections for the recommended workflow, tool-ordering tips, and selector advice. Read-only and takes no arguments; it does not touch the page or require a connected browser. Call it at the start of a debugging session if you are unfamiliar with Feedthrough or want a quick refresher.

Return all fetch and XHR requests captured since the bridge connected, including URL, method, HTTP status, duration, request and response headers, and request and response bodies (bodies capped at 10 KB each — anything longer is truncated with a marker; binary responses are summarised). Use this to find failed requests (4xx/5xx), wrong URLs, slow calls, or to inspect what the app actually sent or received. Use 'filter' to narrow by URL/method and 'since' (a ms timestamp) to see only requests that fired after an action. Read-only: it returns a passively captured log and does not issue or modify any requests.

Return basic page context: current URL, document title, readyState, viewport size, scroll position, user agent, and a 'server' block naming which Feedthrough bridge this page is connected to (name, port, version — null against a pre-0.4 bridge). Read-only and non-destructive: it only reads page state and makes no changes. Useful to orient at the start of a session or confirm a navigation happened. If several agent sessions are running on this machine, check 'server.name' against connection_status: a mismatch means this tab is talking to another session's server, so you are driving the wrong app.

Hover over an element by dispatching synthetic, bubbling mouseover and mouseenter events from inside the page. This triggers JavaScript hover handlers (onMouseEnter / onMouseOver), so hover-only UI that mounts on hover (tooltips, popovers, dropdown and submenus) appears in the DOM; follow up with query_dom, get_html, or inspect_element to read what was revealed. Three limits to know: it does NOT activate the CSS :hover pseudo-class (that is driven by the real cursor, not synthetic events), so styles or content shown purely via :hover in CSS will not change; no mouseout / mouseleave is sent, so the hovered state stays until the app tears it down or you interact elsewhere; and the events are dispatched whether or not the element is visible or in the viewport (it is not scrolled into view), so a successful call does not by itself confirm anything rendered. If the selector matches nothing the call returns an error. Returns the tag of the hovered element.

Return full details about a single element: tag, id, classes, all attributes, text content, bounding rect (top/right/bottom/left/width/height + page scroll and an inViewport flag), a compact ancestor 'path' (e.g. 'body > main > div#app > button.cta'), a curated set of computed styles (layout, box model, typography, positioning, flex/grid), an 'overflow' block when content is clipped/overflowing (scroll vs client size + per-axis x/y flags), a 'clipped' block when an ancestor's overflow cuts the element off (the clipping ancestor + which edges), an effective-visibility check ('visible' boolean, with a 'hiddenReason' such as 'ancestor div#modal display:none' or 'opacity:0' when not visible, accounting for ancestors), an occlusion check ('hittable' boolean from a center-point hit-test, with 'occludedBy' naming the element actually on top when something covers it), an 'a11y' block (resolved role, best-effort accessible name, and key states like expanded/checked/selected/disabled/hidden/tabindex), a 'pseudo' block with ::before/::after content when set (icon fonts, generated text), and live form state where applicable (an input's current value, checked, disabled, etc.). Pass 'properties' to additionally read any specific computed CSS properties by name — they come back under 'requested'. Use this to understand why an element looks wrong or isn't behaving as expected. Read-only: it only reads element state and never changes the page, and it returns an error if the selector matches nothing. Note: addEventListener-registered event handlers cannot be read from the page; only inline on* handler attributes appear (in 'attributes').

Dispatch a key press (keydown/keypress/keyup) on an element — e.g. Enter to submit a search, Escape to close a modal, Tab to move focus, or ArrowUp/ArrowDown in a list. Use named keys (Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right) or a single character. Note: this fires key handlers but does NOT insert text into inputs — use 'fill' to set an input's value, then press_key for the submit/shortcut. If the selector matches nothing the call returns an error; it dispatches the key events and returns without waiting for any resulting navigation or re-render.

Query the page with a CSS selector and return a summary of every matching element (tag, id, classes, text content). Good for counting list items, checking what's rendered, or finding the right selector before calling inspect_element or click. Read-only: it only reads the DOM and never changes the page. Returns an empty list (not an error) when nothing matches, so it is also a safe existence check.

Undo every set_style / set_attribute / set_text change the bridge has applied since it connected, restoring the original values. Best effort: elements the framework has since re-created may not roll back (a page reload always fully resets).

Set or remove an attribute on an element to preview a change (toggle disabled, swap a class, set an aria-* attribute). Pass value=null to remove the attribute. Live preview only — not saved to source, resets on reload. If the attribute is one a framework controls (class, value, checked, disabled, …) the result includes a 'frameworkWarning' that it may be reverted on the next render — relay it. Reset with reset_overrides.

Set one or more inline CSS properties on an element to PREVIEW a visual change live (e.g. shrink a label that doesn't fit, adjust padding or width). This edits the running DOM only — it is NOT saved to source and resets on reload — so tell the user it's a preview, and once they're happy, make the real change in the CSS/component source. Inline styles override the stylesheet and usually survive re-renders. The result includes a 'note' to relay; reset with reset_overrides.

Replace an element's text content to preview wording/label changes. Live preview only — not saved to source, resets on reload. textContent is almost always framework-controlled, so the result includes a 'frameworkWarning' that React/Vue/etc. will likely overwrite it on the next render — relay that, and persist real changes in the source. Reset with reset_overrides.