Browser control actions
Browser control actions run in the Chrome extension service worker through the browser facade. They manage tabs, windows, navigation, downloads, and worker-tab presentation. They do not run inside the page, although set_worker_overlay delegates its final UI change to a content script.
Resource addresses belong in the command target:
{
"command_type": "navigate",
"target": { "tab_id": 412 },
"params": { "url": "https://example.com/jobs/17" }
}Chrome permissions, resource existence, client-local policy, approval, and worker-ownership rules remain effective after the server has selected the client.
Discover and focus tabs
list_tabs
list_tabs takes no required parameters. It queries all visible tabs and returns tabs, where each item contains id, windowId, url, title, active, index, pinned, and optional status. The result is a point-in-time observation; IDs can disappear or be reused by Chrome after the query. A Chrome query failure becomes list_tabs_failed.
focus_tab
focus_tab requires target.tab_id. It activates that tab and brings its containing window to the foreground, returning success, tab_id, and window_id. Missing addressing becomes missing_target; a Chrome failure becomes focus_tab_failed.
Focusing is a visible user-interface effect. An applied result proves that both Chrome calls returned, not that the user saw or retained focus after another application or browser event.
Create ordinary or worker tabs
create_tab accepts either params.url for one tab or params.urls for a batch. The single-tab URL defaults to about:blank. params.active defaults to true for a single tab and false for a batch. Optional target.window_id selects the window.
Single results contain tab_id, url, window_id, and worker. Batch results add a tabs array and retain the first tab's fields for compatibility. If a batch fails partway through, ordinary tabs already created are not rolled back. Worker-tab creation attempts to unmark and close tabs it created before reporting create_tab_failed; cleanup failures are included in the error details.
Set params.worker: true only for server-managed tabs. A worker tab must be created in an explicitly worker-owned window. The target may name one, or the tracker may select a preferred worker window. Absence of one fails with worker_window_required. Configured per-window and total capacities are checked before the batch and can produce worker_tab_capacity_exceeded.
create_tab passes its URL to Chrome; it does not apply the stricter URL-scheme validation used by navigate. Products that accept untrusted tab-creation URLs should constrain or validate them before invocation.
Establish worker-owned windows
create_worker_window
create_worker_window creates a normal, non-incognito Chrome window, marks it as worker-owned, and returns window_id, worker_owned: true, optional initial_tab, and capacity figures. params.url defaults to about:blank, and params.focused defaults to false.
Window creation is serialized with other worker-window mutations. The configured maximum is checked first; exhaustion produces worker_window_capacity_exceeded. Chrome or tracker failure produces create_worker_window_failed.
set_worker_window
set_worker_window changes ownership of an existing window. Prefer target.window_id; legacy params.window_id is also accepted. params.worker_owned is a required boolean.
The handler refuses to:
- mark a missing, non-normal, or incognito window;
- exceed worker-window capacity;
- mark a window containing any tab not already tracked as a worker tab;
- unmark a window while tracked worker tabs remain.
These conditions produce window_not_found, unsupported_window_type, worker_window_capacity_exceeded, user_content_window, or worker_tabs_present. Missing inputs produce window_id_required or worker_owned_required. An applied result contains the window ID, new ownership flag, and tracked worker-tab IDs.
This conservative transition prevents a normal browsing window from silently becoming an unattended automation surface.
Navigate and close
navigate requires target.tab_id and params.url. The URL must parse and use http: or https:; invalid input becomes invalid_url or invalid_url_scheme. An applied result means Chrome accepted the tab update and returns success, tab_id, and url. It does not mean the page loaded, its content script became ready, or the application settled. Use state reporting or a page action to observe those later conditions.
close_tab requires target.tab_id and returns success and tab_id after Chrome accepts removal. Closing a tab can terminate page work without a final page-side callback. Product workflows should treat the close result as resource removal, not proof that every in-page effect completed.
Download through Chrome
Browser download_files accepts one url or an array urls, optional single filename or parallel filenames, optional suggested_dir, and optional save_as (default false). The extension manifest needs the Chrome downloads permission.
The handler invokes Chrome once per URL and returns per-item url, download_id, success, and optional error. If at least one starts, the action is applied with total, succeeded, failed, partial, and results. If all fail, the action is failed with download_failed and still includes the per-item results.
A Chrome download ID proves that Chrome accepted the download request. It is not the final file contents, completion, integrity, or a server-side transaction. Suggested directories and names remain subject to Chrome's download behavior and policy.
Protect worker tabs with an overlay
set_worker_overlay requires a worker target.tab_id and boolean params.active. When active, it accepts transparency from 0 to 1 by convention, display text, optional progress, and an opaque custom data object. Defaults are 0.3 transparency and “Worker Tab — Reserved.” The result reports the resulting active flag.
The handler rejects a non-worker target with not_worker_tab. Delivery failures use the content-script bridge's specific error where available. The overlay darkens the page and blocks pointer, scroll, and focused keyboard interaction. It can become visually transparent during screenshot capture while continuing to block pointers.
The overlay reduces accidental user interference; it is not a security boundary. Worker tracking, local policy, Chrome permission, and action authorization remain the controlling mechanisms.