Chrome MV3 APIs (standalone)

createChromeApi(connection, options?) returns MV3-shaped namespaces backed by CDP and the browser's own profile files — no extension required.

import { createChromeApi } from "omowright";

const chrome = createChromeApi(connection, {
  profilePath: "/path/to/user-data-dir",  // enables bookmarks/history/topSites/downloads.search
  downloadDir: "/path/to/downloads",      // optional, defaults to a temp dir
});

PROFILE-BACKED METHODS THROW UnsupportedOperationError WITHOUT profilePath. A connectPipe browser gets a fresh profile, so bookmarks and history are empty there — these APIs matter when attaching to a real user browser via connect() or reading a real profile directory. Profile reads are read-only and WAL-safe against a running browser.

tabs — CDP Target.getTargets

• chrome.tabs.query({ url?: string | string[], title?, windowId? }) — url takes MV3 match patterns (*://*.example.com/*), title is a substring match. THESE THREE ARE THE ONLY HONORED FILTERS.
• chrome.tabs.get(tabId) — tabId is a string; throws when no tab has it.
• Returns { id, url, title, windowId, active, pinned, audible, discarded, groupId, index }. IDS ARE CDP TARGET-ID STRINGS, NOT MV3 NUMBERS, and the last six fields are fixed defaults — they are not observable over CDP.

Tab lifecycle stays on connection.newTab(url) / page.close(); interaction on page.goto() / page.locator().

windows — CDP Browser.getWindowForTarget

get(windowId, queryOptions?), getCurrent(queryOptions?), getLastFocused(queryOptions?), getAll(queryOptions?).

• queryOptions: { populate?: boolean } — populate: true adds a tabs array.
• Returns { id, focused, type, state, alwaysOnTop, incognito, tabs? }.
• Headless sessions have exactly one window; getCurrent/getLastFocused return the first.

bookmarks — profile Bookmarks JSON, read-only

get(idOrIdList), getChildren(id), getRecent(numberOfItems), getSubTree(id), getTree(), search(query) where query is a string or { query?, url?, title? }.

Nodes: { id, title, type: "url" | "folder", url?, dateAdded?, children? }.

history — profile History SQLite, read-only

• search({ text, startTime?, endTime?, maxResults? }) — times are Unix ms. Returns [{ id, url, title, visitCount, lastVisitTime }], newest first.
• getVisits({ url }) — returns [{ id, url, visitTime, transition }].

downloads — History SQLite + Browser.setDownloadBehavior

• search({ url?, filename?, limit? }) — returns [{ id, url, filename, startTime, bytesReceived, totalBytes, state }]; state is complete | canceled | interrupted | in_progress. Needs profilePath.
• download({ url, filename? }) — downloads through the real browser and resolves { id, url, filename, state: "complete" } with filename as the absolute saved path. 30s timeout; rejects when the URL starts no download. It uses an in-page anchor click rather than Page.navigate, which hangs on download navigations, and re-asserts the download behavior on every call because tab initialization resets it.

topSites — profile Top Sites SQLite

get() returns [{ url, title }] ordered by rank, max 50.

Write methods require the extension bridge

These throw UnsupportedOperationError because they would mutate the user's own browser state: bookmarks.create/update/move/remove/removeTree, history.addUrl/deleteUrl/deleteRange, downloads.pause/resume/cancel/erase, and all of chrome.tabGroups.