Extensions

Surfaces & calling the API

Backgrounds, popups, options, side panels, content scripts — and how to call the API and handle errors.

An extension can present several surfaces, all served over the privileged connect-extension://<id>/ origin, each in the extension's own per-profile session.

Surfaces

SurfaceManifestWhat it is
Backgroundbackground.entryA headless page with window.connect — the long-lived logic. Honors its lifecycle.
Action popupui.action.entryThe panel under the toolbar button. Tab-scoped: closes on tab switch. To close it from its own page (after opening the side panel from it, say) call connect.action.openPopup() — on an open popup it toggles it shut.
Optionsui.options.entryA settings window over the app, which the user can make fill the window. Also open it from code with runtime.openOptionsPage().
Side panelui.sidePanel.entryA docked panel; every extension with one gets a tab on the right-edge panel rail so users can open it. Also open/close from code via ui.sidePanel.
New-tab pageui.newTabReplaces the profile's new-tab page (needs newTab).
History viewui.historyPageReplaces the History popup's content (needs historyPage).
Favorites viewui.bookmarksPageReplaces the Favorites popup's content (needs bookmarksPage).
Content scriptscontentScriptsCode injected into pages you're granted host access to — see connect.scripting.

All extension-page surfaces get the full window.connect. Content scripts get a restricted subset (runtime + storage) — see connect.scripting.

Not on the app's own pages. While the tab in front is one of Connect+'s own pages — the extensions manager, Downloads, Files, or the Connect+ site (the store and the account pages) — the toolbar buttons, the panel rail and the side panel are not shown, an open popup closes, and a keyboard shortcut for the action does nothing. The side panel is only hidden: it keeps running and comes back as it was on the next ordinary page. The options window still opens there (the extensions manager is where the user asks for it), and so does a permission prompt.

Matching the app's theme

Popup, options and side-panel surfaces are told the app's theme two ways:

  • Light or dark. prefers-color-scheme is set to match the app.
  • The app's own colours, as CSS variables on your page's root element, updated live when the user changes theme — a custom theme included.
VariableUse it for
--c-bgpage background
--c-surface / --c-surface-altcards, and their hover / raised state
--c-borderhairlines
--c-text / --c-text-sub / --c-text-mutprimary, secondary and faint text
--c-accentthe one accent colour

Always give a fallback so the surface still looks right in a build that sends nothing:

:root { --bg: #ffffff; --text: #111b21; }
@media (prefers-color-scheme: dark) { :root { --bg: #0b141a; --text: #e9edef; } }
body { background: var(--c-bg, var(--bg)); color: var(--c-text, var(--text)); }

Calling the API

Every method returns a Promise. A denied capability rejects with a clean error whose .code you can branch on:

try {
  await connect.history.list();
} catch (err) {
  if (err.code === 'CAPABILITY_DENIED') {
    const { granted } = await connect.capabilities.request(['history.read']);
    if (granted.includes('history.read')) return connect.history.list();
  }
  throw err;
}

Prefer capabilities.contains to branch before calling, so the expected "not granted" path doesn't throw.

Escape hatches

For anything not yet wrapped (or a new action you're entitled to), two primitives back the whole API:

connect.call(ns, action, payload?, opts?);   // dispatch any connect.<ns>.<action>
connect.onEvent(ns, action, cb);              // subscribe to any connect.<ns>.on<Event>

Everything in the API reference is sugar over these two.

Recipes

A few end-to-end patterns:

  • Ad/content blocker — net.block + declarative rules; a popup with the master toggle and per-site tier.
  • Page theming / dark mode — a documentStart content script reading a per-host pref from the origin's localStorage (zero flash), plus a popup that pushes changes with tabs.sendMessage. Per-host truth in storage.
  • Tab session manager — tabs.query + storage to save/restore sets; live-refresh the popup on tabs.onActivated / onUpdated; bookmark all tabs with bookmarks.*.
  • Cross-extension coordination — two extensions share a { channel } grant and exchange state with channel.publish / subscribe.
  • Background that reacts to browsing — a suspendable background subscribing to tabs.onUpdated / webNavigation, re-arming from runtime.onGrantsChanged, using alarms for periodic work so it survives suspension.