connect.webNavigation

Navigation-lifecycle events for the profile's tabs. Same consent as tab events (tabs.read) — identical disclosure — and covering all frames.

• Capability: tabs.read
• Namespace: connect.webNavigation

Every payload is { tabId, url, frameId, timeStamp }. frameId is 0 for the main frame; a sub-frame uses its routing id (stable for that frame's lifetime).

Walkthrough

React to a page finishing load, top frame only.

1. Declare tabs.read (same consent as tab events):

   { "capabilities": ["tabs.read"] }

2. Subscribe to the event you care about — usually onCompleted.
3. Filter to the top frame with if (e.frameId !== 0) return; unless you want sub-frames.
4. Act on e.url / e.tabId.

connect.webNavigation.onCompleted((e) => {
  if (e.frameId !== 0) return; // sub-frame — ignore
  index(e.url);
});

Events

Each returns an unsubscribe function and needs tabs.read.

webNavigation.onCommitted(cb)

Fires when a navigation commits (the browser has decided to load the new document).

How to use it

1. Subscribe to know a navigation has started in a tab.
2. Check frameId to tell main frame from sub-frame.

Payload — { tabId, url, frameId, timeStamp }.

webNavigation.onCompleted(cb)

Fires when the page finished loading.

How to use it

1. Subscribe to run work once the page is ready (e.g. index it, inject UI).
2. Filter to frameId === 0 for the top frame.

Payload — { tabId, url, frameId, timeStamp }.

webNavigation.onHistoryStateUpdated(cb)

Fires on an SPA history change — pushState / replaceState — where the document doesn't reload.

How to use it

1. Subscribe to follow route changes in single-page apps that never reload.

Payload — { tabId, url, frameId, timeStamp }.

Notes

• These mirror the tab lifecycle at the navigation level; pair them with connect.tabs events when you need the tab object too.
• There is no onBeforeNavigate/onErrorOccurred in v1 — commit and complete are the two anchors, plus the SPA hook.