# Native tabs: implementation and security integration

`apps/browser/tab-registry.cjs` supplies native view ownership, UUID sessions, lookup by WebContents ID, per-tab navigation and visual state, bounded capacity, context snapshots, all-tab quarantine and explicit destruction. Seven lifecycle/security tests pass. It is a foundation, **not yet wired into the running browser**.

## Exact integration map

1. **main.cjs globals / startup (currently lines 12, 55, 364):** replace the single `view` plus global visual fields with registry records. The injected factory creates each `WebContentsView` with the existing sandboxed session and site preload. Before any HTTP navigation, install native site hooks, clipboard controls and `attachPageClipboardGuard`; initialise about:blank and await guard readiness. Failure quarantines every tab and closes the affected view. Store one visual scanner per record; capture/describe closures must close over that record rather than the active view.
2. **hooks() (currently lines 277–340):** split session hooks, installed exactly once, from `installSiteHooks(tab)`, installed for every newly created WebContents. Resolve visual checks via `details.webContentsId`; unknown or destroyed tab requests fail closed. Requests with no page identity, including permitted service-worker traffic, still receive destination/body/DNS enforcement and may never inherit foreground visual approval. `will-download` must capture the originating tab; current `getContext()` always uses the active single view and rejects legitimate background downloads. Change download gate to accept an explicit origin context with captured native identity; require both policy and registry context before scan/save/release.
3. **navigation/layout/theme/state (lines 116–126, 195, 227):** native `create`, `activate`, `close` IPC returns authoritative `tabs`/`activeTabId`. Navigation targets a validated UUID and never reloads on activation. All main-frame navigations, including same-document changes, invalidate that record's navigation token. Theme/title events update their own tab only; active chrome takes that record's color. Attach only the active child view, leave others alive and hidden. Quarantine stops every WebContents; policy resume revalidates destinations and visual protection for every tab before the relevant page is displayed, rather than reloading only the active page. Policy restrictions close DevTools for all tabs.
4. **clipboard / password fill / link inspection (lines 367, 418, 465):** resolve native source WebContents through registry. Foreground-only actions require the same captured tab ID, native object, URL, navigation counter, policy version and activation epoch across asynchronous inspection. Switch-away-and-back must invalidate the old operation even at the same URL. UI clipboard remains a separate trusted-chrome context. Password fill and AI page-linked work must bind a captured tab rather than reading the global active view after `await`.
5. **visual/content IPC (lines 384, 386, 484):** resolve sender WebContents to a tab; require sender's own main frame and current URL/token/revision. An event from hidden tab B must never alter tab A's scanner or approval. A block can remain whole-browser quarantine initially, but must store the offending tab and must not be cleared by selecting another tab. Policy revocation/security failure always quarantines all tabs.
6. **agent-adapters.cjs and main startAgents():** replace hardcoded `managed` with opaque UUID IDs returned by native session inventory. `getContext(args.sessionId)` resolves explicit tab identity; absent ID may choose foreground once at operation start, then must be pinned. Navigation callback accepts that captured tab; read/click/type and visual checks refer to it throughout. Background read may be separately authorized; interaction should require foreground activation unless a deliberate policy and UX permit background interaction. Agent host authorization uses the requested target tab, not the active page. Changes in navigation or policy invalidate async read/AI results. Agent session listing requires its scope but cannot require a navigated active HTTP page; otherwise an empty start page cannot discover populated background tabs.
7. **preload.cjs / renderer.js (lines 2, 19–21):** expose fixed tab-create/activate/close calls only to trusted chrome. Remove renderer-owned UUID creation and navigation-on-select. Render authoritative native state; renderer tab groups use centrally bounded strings accepted by native module. Browser back/forward/reload target active native history. Close-last-tab creates a fresh guarded start tab. Correct overview and sidebar updates without stale async UI writes.
8. **shutdown (lines 509–530):** detach guards and close every WebContents explicitly, even hidden tabs; close registry before window teardown. A page cannot veto destruction with beforeunload. Never preserve live WebContents or credentials in renderer localStorage.

## Required native proof before claiming tabs complete

Use real Electron views and controlled HTTP pages. Page A retains DOM/input/scroll and its own back/forward history while B navigates and switches; no reload counter increments on selection. Hold asynchronous clipboard inspection, switch A→B→A, then verify no clipboard release or DOM mutation; repeat password fill and agent read. A hidden-tab phishing or content event must not approve another tab. Malicious/blocked background upload and download must be blocked. Revoke or expire policy while two views issue requests: both must stop and none may transmit. Close a tab during an agent action: the action cannot return its content. Validate actual main-frame and subframe preload guard installation for each new view. These native proofs complement, rather than replace, registry unit tests.

## API evidence

Electron documents multiple independent child [WebContentsViews](https://www.electronjs.org/docs/latest/api/web-contents-view), [navigation history per WebContents](https://www.electronjs.org/docs/latest/tutorial/navigation-history), and [explicit WebContents disposal responsibilities](https://www.electronjs.org/docs/latest/api/base-window). Same browser session intentionally shares enterprise cookies/proxy/network policy; independent tabs do not imply separate user profiles or tenant sessions.