Vantage documentation

Architecture

Vantage is a C++20 GTK4 browser shell around WebKitGTK 6.0. Its architecture keeps browser-owned policy/state separate from the web engine and keeps privileged agent control outside page JavaScript.

GTK applicationWindows, controls, Wayland and desktop identity

→

Vantage modelTabs, sessions, history, policy and agent RPC

→

WebKitGTKDOM, JavaScript, network, media and rendering

Responsibility split

Layer	Owns	Does not own
GTK/native shell	Windows, toolbar, menus, desktop integration	HTML/JS rendering
Vantage model	Tab/window model, local records, policy, orchestration	Web standards implementation
WebKitGTK	Web content, DOM, JS, origins, TLS, media, accessibility	Vantage UI/application policy
Agent RPC	Versioned same-user control surface	Website-accessible automation bridge
SQLite/config	Browser records/preferences	Remote sync service

Not a Chromium fork

Vantage contains no Chromium or Blink code. WebKitGTK supplies the web engine. Familiar tab/address/navigation controls are a UX choice, not inherited Chromium architecture.

Process and thread boundary

Web content executes under WebKit's process model. Native Vantage state remains application-side. Agent RPC clients may arrive concurrently, while WebKit/GTK mutations are marshalled onto the GTK main context; agents should still serialize logically conflicting actions on one tab.

Agent control plane

agent / Cortex / harness
        |
        | local protocol 1
        v
Vantage agent RPC
  | browser.*  lifecycle/navigation
  | page.*     semantic DOM/waits/JS/diagnostics
  | net.*      application-side HTTP
  | webkit.*   engine state/settings
  | events.*   bounded async event stream
        |
        v
same live Vantage windows + WebKitGTK

This is intentionally not a separate automation browser. Human and agent can share the same runtime, so observation/action races are explicit and semantic refs are generation-scoped.

Persistent state

SQLite stores browser records such as history, bookmarks, sessions and downloads. Rendering preferences use a small local configuration file so they can be applied before WebKit starts. Private profiles use ephemeral state where intended.

JS++ boundary

A pinned JS++ dependency provides a bounded native automation/runtime foundation. Normal website JavaScript still executes in WebKit. Page content is not given JS++ host authority.

Why direct `net.fetch` lives application-side

API work does not need a rendered document. Keeping direct HTTP beside the agent RPC avoids fake tabs and page-JavaScript wrappers, while maintaining a clear distinction from page-origin window.fetch(). Browser cookies are not silently attached.

Design invariants

Websites never gain native agent authority merely by loading.
Closed runtime IDs are not silently rebound.
Stale semantic refs fail instead of retargeting.
Protocol discovery is authoritative for additive features.
Browser-owned state remains local unless an explicit browser/web/agent action transmits it.