Page actions
Page actions read or change one DOM document. The browser-extension runtime delegates them from its service worker to a content script in target.tab_id. The web runtime calls the same class of DOM APIs directly inside its own page and treats its numeric context ID like a tab ID.
The action names are similar, but the delivery boundary differs:
| Concern | Browser extension | Cooperative web page |
|---|---|---|
| target | target.tab_id is required | target may be absent or must equal runtime.contextId |
| execution | content script in the selected tab | the runtime's own JavaScript document |
| reach | permitted http: and https: tabs | only the hosting page |
| delivery failures | content-script readiness, navigation, closure, permission, bridge timeout | page/runtime lifecycle and normal handler errors |
| extra wait | no public wait_settled action | wait_settled is registered |
All selector-taking actions use document.querySelector() or querySelectorAll(). They do not pierce shadow roots, select inside a different frame, or wait for a match unless the action is explicitly wait_for_element.
Change the document
click
Requires string selector. It calls .click() on the first matching HTMLElement and returns clicked: true. It does not calculate screen coordinates or synthesize a physical pointer sequence. Frameworks that require trusted input, special pointer events, shadow-DOM traversal, or application-specific readiness may need a custom action.
type
Requires string selector and string text; optional clear defaults to false. The match must be an HTMLInputElement or HTMLTextAreaElement. The handler focuses it, appends text by default or replaces the value when clear: true, then dispatches one bubbling input event followed by one bubbling change event. It returns typed: true.
This is direct value assignment, not keystroke simulation. It does not support content-editable elements, keyboard shortcuts, composition events, or every framework's internal value tracker. Provide a platform or product handler when those semantics are required.
scroll
Accepts optional selector, numeric x and y (both default 0), and boolean absolute. Without a selector it scrolls the window. With one, it scrolls the selected element's own scroll position. absolute: true uses scrollTo; otherwise the values are deltas passed to scrollBy.
After 50 ms it returns scrolled: true with page URL, title, window scroll position, viewport dimensions, and document dimensions. For element scrolling, those returned scroll coordinates still describe the window, not the selected element. The short delay is not proof that an animated or application-driven layout has settled.
focus and blur
Each requires selector, operates on the first matching HTMLElement, and returns focused: true or blurred: true. Browser and application focus may change again immediately.
Read the document
get_text
With selector, returns that element's textContent as text. Without one, returns at most the first 5,000 characters of document.body.innerText. Selected text is not truncated by the handler, so products should avoid requesting an unbounded container when response size matters.
get_dom
With selector, returns the first match's outerHTML; without one, returns the document element's outerHTML. The extension result also includes page URL and title. The web result contains html only.
DOM HTML can be large and can contain user or application data. The action does not summarize, redact, or interpret it. Prefer a narrower selector or a purpose-built extraction action where privacy, payload size, or a stable semantic contract matters.
get_page_info
Returns page URL, title, document readyState, window scroll offsets, viewport width and height, and document width and height. These are page-side observations at one instant. A complete ready state is not network-idle, framework-hydrated, or business-ready evidence.
get_element_info
Requires selector. It returns lower-case tagName, nullable id and className, up to 200 characters of textContent, a bounding rectangle, and visible. The visibility flag means only that rectangle width and height are positive. It does not test CSS visibility, opacity, occlusion, viewport intersection, or clickability.
query_selector_all
Requires selector; optional numeric limit defaults to 100. The result's count is the full number of matches, while elements contains at most limit summaries. Each summary includes index, lower-case tag, nullable ID and class, up to 100 characters of text, and rectangle.
The current basic schema validator verifies that limit is numeric when supplied but does not enforce an integer or non-negative range. Callers should use a sensible positive bound.
get_attribute
Requires selector and string attribute. It returns value, which is a string when present or null when the first matching element lacks that attribute. DOM properties and live form values are not a general attribute map; use a specific action when the distinction matters.
Wait for a condition
wait_for_element
Requires selector; optional timeout_ms defaults to 5,000. The page polls every 100 ms until a matching node exists and returns found: true, or reports a timeout. Existence is the only condition—it does not require visibility, stability, text, interactivity, or position.
In the extension runtime, the service-worker bridge permits up to 15 seconds for this action's reply. A page-side timeout above that bridge deadline cannot extend the outer call. Use a custom action for a richer readiness condition rather than chaining many weak observations.
wait_settled (web only)
Accepts optional timeout_ms with a 5,000 ms default and polls every 100 ms for document.readyState === 'complete'. It always returns an applied payload with settled, current readyState, and elapsed_ms; reaching its timeout yields settled: false, not a Cheetah handler failure.
The browser content-script implementation has an internal function with this name, but the browser runtime does not advertise or register it as a public page action. Do not dispatch it to extension clients based on internal source presence.
Failure and cancellation boundaries
Web handlers use stable failures such as missing_arg, not_found, not_input, or wrong_context. Extension page handlers surface bridge-specific failures for delivery and use cs_error when the page returns an action failure. Code should branch on the documented machine code rather than parsing a browser error message.
The web handlers check cancellation and lease validity at entry, and their waits recheck while polling. The extension bridge can stop waiting and fence a late reply, but the content script's own DOM wait has no independent abort channel once delivered. Cancellation in either runtime cannot undo a click, value change, focus move, or scroll that already happened. For consequential page operations, design the surrounding application workflow to be idempotent or to observe and reconcile the resulting state.