Content
# Vitre
**WebView automation for Kotlin Multiplatform.** Describe what you want done to a page as a list of
steps, then run it inside an embedded WebView on Android, iOS and the desktop: from your app, from
a test, or from an LLM agent over the Model Context Protocol or Koog.
[](LICENSE)
```kotlin
val workflow = workflow("hn-top-story", "Hacker News top story") {
navigate("https://news.ycombinator.com/")
waitFor(".titleline > a", timeoutMs = 15_000)
extract(".titleline > a", into = "headline")
extract(".titleline > a", into = "url", from = Source.Attribute("href"))
}
WorkflowEngine(controller).run(workflow).collect { event ->
if (event is WorkflowEvent.Completed) println(event.variables["headline"])
}
```
The same vocabulary is available four ways: as the Kotlin DSL above, as a Compose composable you
drop into a screen, and, for an agent that has never seen the page, as MCP tools or as Koog tools.
Those last two are two deliveries of one set of semantics rather than two implementations of them.
The block is a builder rather than a script. It runs once, up front, to assemble the step list that
`WorkflowEngine` then walks, so ordinary Kotlin `if` inside it chooses what the workflow *contains*.
When the decision belongs to the run instead — an element that is only sometimes there, a value an
earlier step extracted — `runIf` appends a step the engine evaluates against the page. The
`WorkflowStep` constructors remain public and equivalent; they are what `vitre-mcp` uses, since
an agent's steps arrive as JSON rather than as Kotlin.
## Why
Mobile apps already embed WebViews, and everything people want to do with them (read a page, fill a
form, talk to the page's own script, scrape a table, run four sites at once) ends up as one-off
`evaluateJavascript` calls glued to a callback. Those calls race each other, they race the UI, and
none of it is shared between Android, iOS and the desktop.
Vitre makes the page something you can drive: one ordering guarantee, one step vocabulary, one
codebase for every platform, and a snapshot format an agent can read.
- The steps are declarative: `Navigate`, `LoadHtml`, `WaitFor`, `Click`, `Input`, `Extract`,
`ExtractRows`, `Snapshot`, `EvaluateJs`, `PostMessage`, `AwaitMessage`, `If` for the branches
the page decides rather than the builder, and `ForEach` to visit every page an earlier step
found — search results in, one product page each out.
- Elements are addressed three ways: CSS, XPath, and handles issued by a page snapshot.
- `evaluateJs` returns a script's result JSON-encoded on every platform, so
`controller.evaluate<Boolean>(…)` decodes it instead of comparing it against `"true"`.
- `postMessage` works in both directions, with an inbox so a message that arrives before you wait
for it is not lost. Payloads are typed on both ends: `bridge.request<Ack, Token>(…)` for a round
trip, `decodePayload<Token>(…)` for a workflow's.
- `controller.cookies` reads, writes and clears the WebView's cookie jar, including the `HttpOnly`
cookie the site keeps its session in and `document.cookie` cannot see, with
host/path/`Secure`/`SameSite` scoping applied the way a request would apply it. Android and iOS
have this today; the desktop reports `null` until CEF's two jars are reconciled.
- A lane pool drives up to four sites at once: one WebView per lane, borrowed by whichever
workflow needs a page next, so six workflows on a two-lane device run three deep instead of
losing four, and a workflow that fans out spreads its pages over every lane.
- `vitre-mcp` exposes the whole vocabulary as MCP tools over an in-process transport, and
`vitre-koog` exposes it as native [Koog](https://github.com/JetBrains/koog) tools with a plugin
that holds the page for the length of an agent run. Both read one set of semantics out of
`vitre-agent`, so neither can drift into telling a model something the other does not.
- Every platform call is confined to the WebView thread and totally ordered, so the engine, your UI,
and an agent can drive the same page without special-casing each other.
> **Web is out of scope as a target.** Browser CORS rules make a general-purpose web automation
> framework impractical there; see [docs/PLAN.md](docs/PLAN.md).
## What it looks like
The sample gallery on Android. The same screens run on iOS and the desktop from the same
`composeApp`; past 720dp wide the list and the runner sit side by side instead of taking turns.
<table>
<tr>
<td width="50%"><img src="docs/images/gallery.png" alt="The Vitre gallery index" width="420"></td>
<td width="50%"><img src="docs/images/workflow-run.png" alt="A completed workflow and its step trace" width="420"></td>
</tr>
<tr>
<td width="50%"><b>The index.</b> The agent chat, the parallel-lane scenarios, then one card per single-page workflow.</td>
<td width="50%"><b>A workflow, run.</b> The page on top, every step underneath with what it actually did. Steps 4 and 5 address elements by the handles <code>Snapshot</code> issued, not by selectors.</td>
</tr>
<tr>
<td width="50%"><img src="docs/images/price-scout.png" alt="Price scout comparing four shops by delivered price" width="420"></td>
<td width="50%"><img src="docs/images/agent-chat.png" alt="The agent chat showing an MCP tool result and the answer derived from it" width="420"></td>
</tr>
<tr>
<td width="50%"><b>Price scout.</b> An example workflow to retrieve info from third-party websites.</td>
<td width="50%"><b>Agent chat.</b> A mocked model over a real MCP server: each action on the page is a <code>tools/call</code>, shown with the JSON that came back rather than hidden behind the answer.</td>
</tr>
</table>
What each entry demonstrates is spelled out in
[What's in the sample gallery](#whats-in-the-sample-gallery); to run it yourself, see
[Running the sample](#running-the-sample).
## Requirements
| | |
|---|---|
| Kotlin | 2.3.10 (Multiplatform) |
| Android | minSdk 24, compileSdk 36 |
| iOS | 15.0+ (`WKWebView`) |
| Desktop | [JetBrains Runtime](https://github.com/JetBrains/JetBrainsRuntime) with JCEF (`jbr_jcef`) 21, on macOS, Linux and Windows; Chromium is part of that runtime, started with `CefRuntime.init` |
| UI layer | Compose Multiplatform, optional; `vitre-core` has no Compose dependency |
## Installation
Published to Maven Central, so `mavenCentral()` in your repositories is all the setup there is:
```kotlin
// build.gradle.kts
kotlin {
sourceSets {
commonMain.dependencies {
implementation("dev.ggoggam.vitre:vitre-core:0.2.0")
implementation("dev.ggoggam.vitre:vitre-compose:0.2.0") // optional
implementation("dev.ggoggam.vitre:vitre-mcp:0.2.0") // optional
implementation("dev.ggoggam.vitre:vitre-koog:0.2.0") // optional
}
}
}
```
Or consume it as a source dependency: clone the repo next to your project, add
`includeBuild("../vitre")` to `settings.gradle.kts` and drop the versions above. If you vendor the
sources instead, add the modules directly with `include(":vitre-core")`.
## Quick start
Mount a WebView, take its controller, run a workflow against it:
```kotlin
@Composable
fun Screen() {
val state = rememberVitreWebViewState("https://example.com")
val controller = state.controller
LaunchedEffect(controller) {
val page = controller ?: return@LaunchedEffect
WorkflowEngine(page).run(SampleWorkflows.ExampleDotComTitle).collect { event ->
when (event) {
is WorkflowEvent.StepStarted -> log("→ ${event.step}")
is WorkflowEvent.Completed -> log(event.variables["title"])
is WorkflowEvent.Failed -> log("step ${event.stepIndex}: ${event.message}")
else -> Unit
}
}
}
VitreWebView(state = state, modifier = Modifier.fillMaxSize())
}
```
`state.controller` is null before the WebView mounts and null again after it leaves the composition,
so an effect keyed on it starts when the page arrives and tears down when it goes away, and nothing
runs against a dead WebView.
## Example use cases
### 1. Read a page your app doesn't own
The smallest thing worth doing: navigate, wait for the element that means the page is ready, read
what you came for. Text is `textContent`; `href` is genuinely an attribute, so it is read as one.
```kotlin
workflow("hn-top-story", "Hacker News top story") {
navigate("https://news.ycombinator.com/")
waitFor(".titleline > a", timeoutMs = 15_000)
extract(".titleline > a", into = "headline")
extract(".titleline > a", into = "url", from = Source.Attribute("href"))
}
```
### 2. Pull a whole table out in one step
`ExtractRows` returns one JSON record per matching row, with each column resolved within that row.
That scoping is the point: a row missing a price yields an empty string in that record instead of
shifting every later record onto the wrong product.
```kotlin
extractRows(rows = xpath("//li[@data-sku]"), into = "results", limit = 10) {
// "." is the row itself — read its own attribute.
column("sku", xpath("."), from = Source.Attribute("data-sku"))
column("price", xpath(".//span[@class='price']"))
// Matched on the text a human reads, not on a class hook.
column("stock", xpath(".//*[normalize-space()='In stock']"))
// Up to the row and back down — CSS has no parent combinator.
column("seller", xpath(".//span[@class='price']/ancestor::li[1]//span[@class='seller']"))
}
```
### 3. Then go into each result
A search page names the products; the answers are one page further in, and there is one per row.
`forEach` runs its body once per element of the array `ExtractRows` left behind, binding each as
`product`, so `template("{product.url}")` is the address that row carried. Items run on lanes
borrowed from the engine's `LaneSource` — one after another on a single WebView, several at once
on a pool — and each leaves what it extracted in `details`, in row order, with a failing item
recorded rather than fatal.
```kotlin
forEach(over = "results", item = "product", into = "details", limit = 4) {
navigate(template("{product.url}"))
waitFor("#productTitle", timeoutMs = 25_000)
extract("#productTitle", into = "title")
extract("#availability", into = "availability")
}
// Afterwards:
val details = completed.decode<List<FanOutResult>>("details")
```
A fan-out is a page barrier: the workflow gives its lane back before the first item starts and
borrows a fresh one afterwards, so the step after a `forEach` starts on a blank page with the
variables intact. That is what makes a pool of any size safe from a parent holding the lane its
children are waiting for — see [PARALLEL-LANES.md](docs/PARALLEL-LANES.md).
### 4. Talk to a page you do own (hybrid apps)
If the page is yours, the bridge beats scraping it. `PostMessage` sends a
`MessageEvent('vitre')` into the page; `AwaitMessage` waits for `window.vitre.postMessage`
coming back. The inbox buffers, so a handler that posts synchronously on click is still matched by
an `AwaitMessage` that starts afterwards, which is the case that silently loses messages elsewhere.
```kotlin
@Serializable data class Ack(val seen: Boolean)
@Serializable data class Token(val value: String, val expiresAt: Long)
loadHtml(html = checkoutHtml, baseUrl = "https://app.example.com")
waitFor("#pay")
click("#pay")
awaitMessage(type = "payment-token", into = "token", timeoutMs = 5_000)
postMessage(type = "ack", payload = Ack(seen = true), id = "ack-1")
```
`click` requires exactly one connected, enabled target with visible layout and rejects hidden or
inert targets. Validation and dispatch run in one JavaScript turn. It dispatches a synthetic DOM
click; it does not scroll, check viewport intersection or occlusion, create trusted user input, or prove the site's operation
completed. Use `waitFor`, extraction, or a bridge acknowledgement to verify the result.
`WorkflowEvent.Failed.kind` and `PageDriverException.kind` distinguish `ActionRejected` (validation
stopped dispatch), `OutcomeUnknown` (the script may already have taken effect), and general `Failure`.
Inspect state before retrying an unknown outcome. Scripts are never automatically replayed.
Payloads are classes rather than hand-typed envelope strings. `id` and `type` stay arguments because
they are protocol. The reply arrives in a variable, and the typing picks up again where the values
are:
```kotlin
if (event is WorkflowEvent.Completed) use(event.decodePayload<Token>("token"))
```
The split is deliberate. A workflow block is a builder: it runs once to assemble the step list, and
the steps run later, so there is no point in the block at which a reply could be returned to it.
When you want a round trip as one expression, you want the host API rather than a workflow.
`request` posts, correlates the answer by `replyTo`, and gives it back typed:
```kotlin
val token: Token = controller.bridge.request<Ack, Token>("issue-token", Ack(seen = true))
```
Post-then-await does not race here either: the inbox buffers the reply from a page handler that
answers synchronously, which is the normal case, until the wait starts.
The same applies to a script's own result. `evaluateJs` hands back the JSON encoding of what the
expression produced, the one contract every platform was made to agree on, so a value read out of a
page can be decoded rather than string-matched:
```kotlin
val ready: Boolean = controller.evaluate("document.readyState==='complete'")
val rows: List<Product> = controller.evaluate("Array.from(document.querySelectorAll('li')).map(toRow)")
```
### 5. Handle the page that is only sometimes there
A cookie banner, an interstitial, a login form that appears when the session lapsed. `waitFor` is
the wrong tool for all of them — it fails the run when the thing legitimately is not there — and a
Kotlin `if` in the builder cannot help, because it has already finished running by the time the page
loads.
`runIf` appends a `WorkflowStep.If` the engine evaluates in place. Conditions are values, not JS
strings, so a failure can name what went wrong: `exists`, `variableEquals`, `variableMatches`,
`jsTruthy`, combined with `and` / `or` / `not`.
```kotlin
navigate("https://shop.example.com/cart")
// Neither outcome is a failure. The banner is dismissed if it is there, and skipped if it is not.
runIf(exists("#cookie-banner")) {
click("#cookie-banner .accept")
}
extract("#checkout-status", into = "status")
// Branching on a value the run itself produced — nothing at build time knows what this says.
runIf(variableMatches("status", "session expired"), otherwise = { click("#pay") }) {
click("#sign-in")
input("#password", secret)
waitFor("#checkout-status")
}
```
Branches nest, and step numbering nests with them: a failure inside one reports a `StepPath` like
`3.then.1` rather than a flat index that would point at the `If` — the one step that did not fail.
`Exists` is deliberately the one condition where a missing element is an answer instead of an error,
including for a stale snapshot handle, which every other step rejects outright.
### 6. Search four sites at once
One WebView per lane, each loading its site as a top-level document, which is what keeps sessions
first-party and `X-Frame-Options` out of the picture. Hand the pool every workflow and it drains
them across however many lanes the device could carry.
```kotlin
var pool by remember { mutableStateOf<FramePool?>(null) }
VitreFrameHost(
laneCount = 4,
policy = InterceptionPolicy(permissiveCors = true, handlers = shopFixtures),
onPoolReady = { pool = it },
)
// Six workflows on a two-lane device run three deep — nothing is dropped.
pool?.run(shops.map { it.workflow(query) })?.collect { (taskIndex, laneId, _, event) ->
if (event is WorkflowEvent.Completed) merge(event.variables["results"])
}
```
The sample's Price scout does exactly this: four synthetic shops at four distinct origins, merged
and ranked by delivered price, which for most of the catalogue is a different shop from the cheapest
sticker price.
For work that must survive an observer disconnecting, submit it once to a host-owned
[`WorkflowQueue`](docs/WORKFLOW-JOBS.md). Its job handles expose hot state: another collector
observes the same execution. Admission is bounded, and deadlines include time spent waiting.
```kotlin
val queue = WorkflowQueue(hostScope, readyPool, capacity = 32)
val job = queue.submit(shop.workflow(query), timeoutMs = 60_000)
hostJobs[job.id] = job // retain the handle for your UI or agent session
when (val state = job.await()) {
is WorkflowJobState.Completed -> merge(state.result.variables["results"])
is WorkflowJobState.Failed -> log(state.message)
is WorkflowJobState.Cancelled -> log("cancelled: ${state.reason}")
else -> Unit
}
// When the host shuts down: queue.closeAndJoin()
```
### 7. Offline, deterministic page tests
A `RequestHandler` answers requests from memory, so a test drives a real WebView against a real
origin with no network and no flake. This is how the parallel-lane demo stays a usable smoke test.
```kotlin
val fixtures = RequestHandler { request ->
when (request.host) {
"shop-a.test" -> InterceptedResponse(body = shopAHtml.encodeToByteArray())
else -> null // fall through to the network
}
}
VitreFrameHost(policy = InterceptionPolicy(handlers = listOf(fixtures)), …)
```
Handlers are the one part of interception that is on by default, and the only part a fixture needs:
a default-constructed `InterceptionPolicy` answers from them and otherwise leaves the network
alone, so a lane pointed at a real site gets the document the browser would have fetched rather
than one this library refetched. `InterceptionPolicy.AUTOMATION` opts into the rest — CORS and CSP
relaxation, the network tap, documents and data taken off the network — for a pool driving sites
the app deliberately automates.
Interception is real on Android and the desktop, which both let an application answer a request
outright: `shouldInterceptRequest` on one, CEF's resource pipeline on the other. iOS is the
exception, since `WKURLSchemeHandler` refuses to register for `https`, so fixtures there are served
from a private scheme and nothing can rewrite a response header. The failure modes, and why the
default reversed, are spelled out in [docs/PARALLEL-LANES.md](docs/PARALLEL-LANES.md).
### 8. Let an agent drive the page
`Snapshot` answers the question a hand-written workflow never has to ask: what is on this page? It
returns the interactive and text-bearing elements as an indented outline with a handle each, the
same information as the HTML at roughly a third of the tokens.
```
Vitre fixture — https://fixture.vitre.test/
heading "Vitre fixture" [ref=e1]
textbox value="typed by handle" [ref=e3]
button "Send pong to native" [ref=e4]
```
Refs in this example are abbreviated. Actual refs include a document namespace: copy them verbatim
from the snapshot and treat them as opaque. Passwords, one-time codes and card autocomplete values
are redacted; other form values are bounded. Hosts can configure additional subtree redaction using
`SnapshotPolicy` on `WorkflowEngine`, `PageDriver`, or `McpServer`.
Hosts can disable tool operations or suspend them for user approval with `PageAccessPolicy`.
MCP and Koog expose `capabilities` to report enabled operations and limitations. See
[host action authorization](docs/ACTION-POLICY.md) for examples and the enforcement boundary.
From there the agent uses the returned refs (shown abbreviated below):
```kotlin
snapshot(into = "page")
input(handle("e3"), text = "typed by handle")
click(handle("e4"))
extract(handle("e5"), into = "status")
```
`vitre-mcp` puts that behind an MCP server: `snapshot`, `navigate`, `click`, `type`,
`wait_for`, `extract`, `extract_rows`, `evaluate`, `send_message`, `await_message`, plus
`acquire_lease` / `release_lease` for holding a page across several calls. The host registers its
WebViews and the server drives exactly those:
```kotlin
val sessions = WebViewSessions().apply { register("main", controller, "the shopping tab") }
val server = McpServer(sessions, scope)
val transport = InProcessMcpTransport(server)
```
It ships an in-process transport only, on purpose: a loopback socket would expose page automation to
anything on the device that can reach the port, and on a WebView signed into the user's accounts
that leaks the session, not merely the automation. See [docs/MCP.md](docs/MCP.md).
### 9. Give a Koog agent the same page
If the agent is written with [Koog](https://github.com/JetBrains/koog), `vitre-koog` hands it the
same thirteen tools as Kotlin objects, with typed arguments, no server, and the same names, so a
system prompt written for one adapter works against the other:
```kotlin
val driver = PageDriver(sessions, scope)
val agent = AIAgent(
promptExecutor = executor,
llmModel = OpenAIModels.Chat.GPT4_1,
systemPrompt = PageToolDocs.INSTRUCTIONS,
toolRegistry = ToolRegistry { vitreWebView(driver) },
)
```
A host that already runs the MCP server can bridge that instead. `vitreMcpToolRegistry(server)`
reads `tools/list` and translates the schemas, so there is one description of the toolset rather
than two. Point the typed tools at `server.driver` if you want both against one lease registry.
The plugin is `VitrePageLease`. Ordering already stops two callers corrupting each other's
individual steps, but it cannot make a sequence indivisible, and an agent is nothing but sequences.
A user tapping "next page" between the agent's `wait_for` and its `extract` yields a price read off
the wrong page, with every operation correctly serialised. `acquire_lease` fixes that, at the cost
of requiring the model to remember to use it. The plugin takes the lease itself, for the length of
the run, and the model never sees it:
```kotlin
val agent = AIAgent(
promptExecutor = executor,
llmModel = OpenAIModels.Chat.GPT4_1,
systemPrompt = PageToolDocs.INSTRUCTIONS,
// Lease tools off: the run already holds the page, and a model that asks for it again is
// queueing behind itself until its own lease expires.
toolRegistry = ToolRegistry { vitreWebView(driver, includeLeaseTools = false) },
) {
install(VitrePageLease) { driver = pageDriver; ttlMs = 120_000 }
}
```
The lease is bounded by a TTL, because the page is held while the agent waits on an LLM, and a
WebView the user can see is a UI that has stopped responding to its own app. See
[docs/KOOG.md](docs/KOOG.md).
## Locators
Every element-addressing step takes a `Locator`: `css("#results .item")`, `xpath("//li[@data-sku]")`
or `handle("e7")`. A bare string still means CSS.
| | Use it for |
|---|---|
| `css(…)` | The common case. Short, familiar, fast. |
| `xpath(…)` | Matching on visible text, walking *up* the tree with `ancestor::`, selecting an attribute as a node, positional predicates, `count()`. |
| `handle(…)` | Addressing an element a `Snapshot` already found; the agent's locator. |
Neither CSS nor XPath pierces shadow DOM; that is the page's doing, not the query language's.
A handle is the third kind and behaves differently by design: the other two describe how to search,
a handle names an element. It is issued by the page, dies with the document that issued it, and is
never recycled, so a handle from the previous page fails loudly instead of resolving against a
same-shaped element on the new one.
## Threading
A WebView owns a thread, the platform main thread, and that is not negotiable: `WKWebView` is UIKit,
and an Android `WebView` must be used on the thread that built it. So callers do not synchronise
with each other, they queue. One object, `WebViewSerializer`, confines every platform call to that
thread and totally orders them, which is what lets the workflow engine, the UI, and an agent drive
the same page without special-casing each other. The engine itself runs on `Dispatchers.Default` and
never sees the WebView thread.
See [docs/CONCURRENCY.md](docs/CONCURRENCY.md) for the model and the bugs it fixed.
## Modules
| Module | Purpose |
|---|---|
| `vitre-core` | Pure KMP library: workflow DSL, engine, bridge protocol, `WebViewController` actuals, lane pool, network interception. |
| `vitre-compose` | Compose Multiplatform layer: `VitreWebView` and `VitreFrameHost`. |
| `vitre-agent` | What every agent adapter shares: `PageDriver`, the session registry, leases, and the prose each tool is described to a model with. |
| `vitre-mcp` | MCP server over one or more WebViews: JSON-RPC, tool schemas, transport. |
| `vitre-koog` | Koog tools over the same WebViews, plus a bridge for an MCP server you already run and a plugin that leases the page for an agent run. |
| `sample/composeApp` | Shared sample UI: a workflow gallery demonstrating the library. |
| `sample/androidApp` | Sample Android launcher hosting `composeApp`. |
| `sample/iosApp` | Sample iOS Xcode project hosting `composeApp` via the KMP framework. |
| `sample/desktopApp` | Sample desktop launcher hosting `composeApp`; starts Chromium before the window opens. |
## Building
```bash
mise install # ktlint (mise.toml) + the android CLI (mise.local.toml)
mise run test # library + sample allTests
mise run test:android # the on-device Koog agent test (needs a device or emulator)
mise run build # library artifacts + Android sample APK + iOS debug framework
mise run lint # ktlint
mise run fmt # ktlint --format
```
A JDK is not declared in `mise.toml`. Gradle uses whatever JDK is on your machine, and the
toolchain is resolved via foojay. CI installs its own from `mise.ci.toml`. `mise run wrapper`
regenerates the Gradle wrapper and is the one task that needs a system `gradle`; you only need it
when bumping Gradle.
### Running the sample
```bash
mise run dev:android # build + install + launch on a phone, or boot an AVD
mise run dev:ios # build + install + launch on a simulator
mise run dev:desktop # build + launch the desktop window
```
All three build and launch in one step, so none of them needs Android Studio or Xcode open.
`dev:android` prefers a plugged-in device over an emulator and boots the first AVD if nothing is
attached; `dev:ios` reuses a booted simulator, or set `VITRE_SIM` to pick one by name. They
live in `mise.local.toml` (dev only, and CI never runs them). `mise run android:install` is the
plain fallback: `gradlew installDebug` onto whatever adb already sees, without the android CLI.
You can also open `sample/iosApp/iosApp.xcodeproj` in Xcode and hit Run, since the target's "Compile
Kotlin Framework" phase builds the KMP framework first either way.
`dev:desktop` runs on a JetBrains Runtime with JCEF rather than whatever JDK Gradle itself uses,
because that runtime is where Chromium comes from. Gradle's toolchain resolver downloads it into
`~/.gradle/jdks` the first time, a few hundred megabytes once per machine, and every later launch
goes straight to the window. `./gradlew :sample:desktopApp:createDistributable` packages the app
with that runtime, Chromium included.
### What's in the sample gallery
The gallery opens on the agent chat: a WebView with a conversation under it, where every action on
the page arrives as an MCP tool call and the calls and their results are shown rather than hidden
behind the answer. The model is mocked, with no LLM API and no key, but nothing downstream of it is.
Each turn issues a real `tools/call` over JSON-RPC and the answer is computed from what came back.
One scripted exchange guesses a CSS selector that does not match, so the transcript shows a tool
failure arriving as an `isError` result the model reads and corrects, rather than as an exception
that ends the run.
Below it are two parallel-lane scenarios: Price scout (four synthetic cross-origin shops, ranked
by delivered price) and Live pages probe (four real sites, reporting from inside each, including
whether a cross-origin `fetch` got through).
Then the single-page workflows. Two of them drive a page the sample ships, loaded straight into the
WebView with no network. Those are the only ones that can demonstrate the bridge at all, since
`AwaitMessage` waits for `window.vitre.postMessage` and no third-party site will ever call it, and
they double as the smoke test: a failure means the library broke rather than that a website was
redesigned. The rest hit the live web to show the same steps against real pages, and are the ones
that will eventually rot. Among them, "Amazon search → product pages" is the fan-out: it searches,
then visits the first four results one after another on the gallery's single WebView, and the
`For each` row in the timeline counts the product pages as they land.
### Releasing
`VERSION_NAME` in `gradle.properties` is the released version, and the only place it is written
down. Changing it on `main` is the release, so a release is a reviewable pull request like anything
else, and what reaches Maven Central is the value someone approved:
```diff
# gradle.properties
-VERSION_NAME=0.1.0
+VERSION_NAME=0.2.0
```
Merging that fires [`.github/workflows/release.yml`](.github/workflows/release.yml), which runs the
full CI suite against the merge commit, publishes all five library modules to Maven Central as one
atomic deployment and releases it, with no button to press afterwards. Only then does it tag the
commit `v0.2.0` and open a GitHub release for it, with notes generated from the pull requests merged
since the last one. The tag records a release that happened rather than causing one; pushing one by
hand publishes nothing.
A version with a prerelease component (`0.3.0-rc.1`, `1.0.0-beta.2`) publishes to Maven Central
like any other, but its GitHub release is flagged so it does not show up as *Latest*.
`gradle.properties` also holds Kotlin, Gradle, Android and POM settings, so most edits to it are not
releases. The workflow diffs `VERSION_NAME` against the previous commit and exits quietly when it
has not moved. It refuses outright, before Gradle starts, on a malformed version, on the
`0.0.0-LOCAL` placeholder, and on any version already tagged, because a Maven Central version can be
superseded but never withdrawn.
It publishes from macOS because the iOS targets need it: Kotlin/Native only builds Apple klibs on a
Mac, and on Linux they are skipped silently rather than reported, which would ship module metadata
advertising variants that are not there.
Publishing needs four secrets on the repository's `maven-central` environment: a
[Central Portal](https://central.sonatype.com/) user token for the verified `dev.ggoggam` namespace,
and a GPG key to sign with.
| Secret | What it is |
|---|---|
| `MAVEN_CENTRAL_USERNAME` / `MAVEN_CENTRAL_PASSWORD` | Central Portal user token, from Account → Generate User Token. Not the portal login. |
| `SIGNING_IN_MEMORY_KEY` | The armoured private key: `gpg --armor --export-secret-keys <key-id>`, newlines included. |
| `SIGNING_IN_MEMORY_KEY_PASSWORD` | That key's passphrase. |
| `SIGNING_IN_MEMORY_KEY_ID` | Only needed if the exported ring holds more than one key; leave unset otherwise. |
The public half has to be on a keyserver Central checks (`gpg --keyserver keyserver.ubuntu.com
--send-keys <key-id>`), or validation rejects every signature.
To try the modules from another project without releasing anything, `mise run publish:local` puts
them in `~/.m2` at whatever `VERSION_NAME` currently says.
## Documentation
| Doc | What's in it |
|---|---|
| [docs/PLAN.md](docs/PLAN.md) | Architecture, module layout, bridge design, the TDD use-case matrix. |
| [docs/CONCURRENCY.md](docs/CONCURRENCY.md) | The threading model, the bugs it fixed, how MCP slots in on top. |
| [docs/PARALLEL-LANES.md](docs/PARALLEL-LANES.md) | Lanes, interception, CORS, the traffic tap, platform differences. |
| [docs/MCP.md](docs/MCP.md) | Tool list, handle lifetime, leases, protocol and transport decisions. |
| [docs/KOOG.md](docs/KOOG.md) | The Koog tools, the MCP bridge, the lease plugin, and why the semantics sit under both adapters. |
| [docs/ASYNC-BRIDGE.md](docs/ASYNC-BRIDGE.md) | The `postMessage` bridge protocol end to end. |
## Contributing
Issues and pull requests are welcome.
```bash
mise install
mise run fmt:check # ktlint, same check CI runs
mise run test
```
The repo uses [prek](https://github.com/j178/prek) pre-commit hooks (`mise run pre-commit`), and
ktlint with the official Kotlin code style. A few conventions worth knowing before you send a patch:
- Comments explain *why*. Much of this codebase's value is in the reasoning recorded next to
non-obvious decisions: platform seams, ordering guarantees, failure modes. Keep that up.
- Tests come first for anything in `vitre-core`. The engine, bridge and pool are covered by
`commonTest` against a fake controller; a behaviour change should show up there before it shows up
in a WebView.
- Both platforms or neither. If a change can only work on one, say so where a caller will read it,
the way interception does.
## License
[MIT](LICENSE) © 2026 Joon Kwon
Connection Info
You Might Also Like
No recommendations available