Sample app

The repository ships one shared sample app, written once in Compose Multiplatform and hosted on Android and iOS. It drives a real WebView/WKWebView with KMPwright while you watch, so you can try selectors, commands and recipes without writing a test harness.

Run itCopy Anchor Link

Requirements: JDK 17, the Android SDK for Android, macOS with Xcode for iOS. Run commands from the repository root.

./gradlew :example-android:installDebug

What is on screenCopy Anchor Link

The app is built with Material 3 Expressive (dynamic color, expressive motion, ButtonGroup-style toggles, LoadingIndicator, MaterialShapes). It has a live browser and three screens: Agent, Recipes and Inspect. They all share one Browser and one page, so whatever you do on one screen is visible on the others. Page operations are serialized, so the console, a running recipe and the ref overlay never interleave actions on the same WebView.

On launch the app loads a bundled playground page (a docs search box, a sign-up form and a counter) and takes an interactive snapshot.

AgentCopy Anchor Link

An agent console for the runCommand grammar. Type a command such as open en.wikipedia.org/wiki/Kotlin, snapshot -i, click @e3 or fill @e3 "hello". Results appear newest first, right under the composer: the command, its text output, how long it took, and, for screenshot, the captured image. Every @eN in an output is tappable and writes click @eN into the composer. Suggestion chips run common commands (snapshot -i, screenshot, get title, scroll down, back, help), and starter cards walk through the loop the first time. Typing clear empties the console.

This is the same loop an LLM runs: snapshot, read refs, act on a ref.

Live ref badgesCopy Anchor Link

After every snapshot and every command that can change the page, the app takes a fresh interactive snapshot and draws a badge with each @e ref over its element in the live page.

• Tap a badge to run click @eN.
• Long-press a badge to switch to the Agent screen with a command prefilled: fill @eN "" for text boxes, search boxes and combo boxes, click @eN for everything else.
• Badges stay glued to their elements while the page scrolls. The # toggle next to the address bar shows or hides them.

The badges are built from public APIs only: page.snapshot(interactive = true) for the refs, then page.locator(ref).boundingBox() for each position. Boxes are stored in document coordinates, and the overlay adds the WebView's native scroll offset every frame, so scrolling never needs a JavaScript round trip.

RecipesCopy Anchor Link

Runnable scripts, each showing the Kotlin code it executes and a step timeline that marks every step as pending, running, done or failed, with its output (text or a screenshot). Pressing Run recipe collapses the panel so you watch the page being driven, with the current step (and then a finished or failed result) shown in a banner. The grid leads with the agent loop, then groups recipes into For agents and Playwright basics:

The code shown for each recipe is kept identical to what its steps run, so you can copy it.

InspectCopy Anchor Link

Tabs for the page's console messages (page.consoleMessages()), recorded network requests (page.network.requests()), storage (cookies, localStorage and sessionStorage), and an accessibility audit (A11y).

Adaptive layoutCopy Anchor Link

• Phones: the browser fills the screen and the active screen lives in a bottom sheet. Collapsed, the sheet always shows the Agent / Recipes / Inspect switcher and the command composer; focusing the composer expands the sheet so the keyboard never covers it.
• Tablets and unfolded foldables (840 dp wide and up): the active screen as a side panel, with the browser filling the rest.

The same WebView instance moves between layouts when the window size changes; it is not recreated.

iOS navigationCopy Anchor Link

On iOS 26, a Kotlin NativeStudio object owns the single WKWebView, Browser and page shared by every tab. Swift asks it for a Compose view controller per tab (tabViewController(tab:)) and per pushed recipe (recipeViewController(id:)); each screen reports screenDidAppear(key:) and the visible screen adopts the shared WKWebView, so the page you are driving follows you between tabs. Compose sends navigation back to Swift through onSelectTab and onOpenRecipe callbacks.

How the sample wires KMPwrightCopy Anchor Link

The integration is small and is a good template for your own app:

1. Each platform creates a PlatformContext around one WebView. On Android that is a WebView with JavaScript and DOM storage enabled, file and content access disabled, and mixed content blocked, wrapped in AndroidPlatformContext(context, webView).
2. Shared code creates Browser(platformContext) and uses browser.page().
3. When the screen leaves composition, it calls browser.dispose() (the non-suspending teardown) and destroys the WebView.

val state = remember(platformContext) {
    StudioState(Browser(platformContext), scope) { releaseWebViewKeyboard(platformContext) }
}
DisposableEffect(state) {
    onDispose {
        state.dispose()                    // calls browser.dispose()
        disposePlatformContext(platformContext)
    }
}

After automation types into the page, the sample hides the soft keyboard the page opened (releaseWebViewKeyboard) without touching its own text fields.

See kmpwright-example-shared/src/commonMain for the full source.