---
author: 小檬 XMeng · 墨迹 Moji
date: Sep 10, 2026
---

# MengPaw.Browser Development Documentation

> A standalone APK (an Android browser app) that ships with a built-in Playwright-style semantic command surface for semi-automatic control by AI Agents.
> Doc version: v0.10.1 · 2026-09-10 · License: AGPL-3.0-or-later OR LicenseRef-Commercial
> This document has two parts: **Part 1** guides a Shell Agent through controlling the browser over the am bridge and starting to operate it;
> **Part 2** is aimed at developers and explains the directory structure and implementation.
> Companion document: **[MengPaw_Browser_skills.md](article.en?md=articles/mengpaw-browser-skills.en.md)**<a class="md-dl" href="articles/mengpaw-browser-skills.en.md" download="mengpaw-browser-skills.en.md" title="Download MengPaw_Browser_skills.md" aria-label="Download MengPaw_Browser_skills.md"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 10.5V13a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1v-2.5"/><path d="M8 2v9.5"/><path d="M4.5 8 8 11.5 11.5 8"/></svg></a>(the complete Agent operations manual: full command-surface table /
> semi-automatic loop / forms / scraping / troubleshooting / Playwright comparison).

---

## Introduction

### What Is MengPaw.Browser

MengPaw.Browser (package name `com.mengpaw.browser`) is an **Android browser APK that can be programmatically controlled by an AI Agent**: a full WebView-based browser that humans can use directly, which also ships with a Playwright-style semantic command surface (`page.*` — 22 commands + `browser.*` — 21 commands), exposed to **same-signature apps** (MengPaw Shell being one of them) over a Termux-style **am bridge** (`RunCommandService`, protected by a signature permission).

In one sentence: **a browser for humans, and a browser for Agents** — an Agent can drive it just like Playwright to open pages, take full-page screenshots, click at coordinates, fill in forms, extract content, and manage tabs.

### Why Do You Need It

- **Agents need a "real browser"**: plain HTTP fetching cannot reach post-login content / JS-rendered pages / pages with strong anti-scraping measures; a real browser brings its own sessions, cookies, and a JS execution environment.
- **Playwright semantics, zero learning cost**: command names and arguments align with the Playwright API most familiar in LLM training corpora, so the Agent needs no extra learning of custom commands.
- **Standalone APK, already decoupled from Shell**: the browser is a **neutral, independent project** (its own version cadence, repository and releases); Shell driving it over the am bridge is an **external consumer's behaviour** that requires no dedicated plugin for the browser and does not hinder the project's independent evolution.
- **Semi-automatic collaboration**: `page.load` completes "navigation + full-page segmented screenshots + coordinate system" in one call; the Agent looks at the images and clicks by coordinates — fewer round trips, less context used.
- **Safe and controllable**: the am bridge is guarded by a signature permission (same-signature apps only), plus a command whitelist and output-path confinement; the 9880 bridge and open mode are retired (decision #7) and third-party integration is no longer supported.

### How to Read This Document

- **Goal: have a Shell Agent control the browser over the am bridge and start operating** → read **Part 1 Quick Start** (§1–4); the full operating capabilities after a successful connection are covered by the companion document [`MengPaw_Browser_skills.md`](article.en?md=articles/mengpaw-browser-skills.en.md)<a class="md-dl" href="articles/mengpaw-browser-skills.en.md" download="mengpaw-browser-skills.en.md" title="Download MengPaw_Browser_skills.md" aria-label="Download MengPaw_Browser_skills.md"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 10.5V13a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1v-2.5"/><path d="M8 2v9.5"/><path d="M4.5 8 8 11.5 11.5 8"/></svg></a>.
- **Goal: understand/modify the browser from the source, do secondary development, or integrate your own framework** → jump straight to **Part 2 Starting from the Source** (§5–12); the directory structure and implementation details are all there.

---

## Part 1 Quick Start — Controlling the Browser over the am Bridge

### 1. Prerequisites

- The device has the MengPaw.Browser APK installed (package name `com.mengpaw.browser`) together with **MengPaw Shell (same signature)**
- The control channel is a **Termux-style am bridge** (`RunCommandService`), protected by the signature permission
  `com.mengpaw.permission.RUN_BROWSER_COMMAND` — **callable only by same-signature apps**;
  calls from third-party apps are rejected by the system (the 9880 HTTP bridge and open mode are retired, so third-party integration is no longer supported)
- The Agent needs two capabilities: executing `am` commands (to wake the browser and issue commands) and
  reading files from public directories (to view screenshots and output)

### 2. Two-Step Invocation

```bash
# ① Wake the browser (when it is not running or was killed the am bridge is unreachable — it must be woken first)
am start -a com.mengpaw.action.OPEN_URL --es url "https://example.com"

# ② Execute a browser command: output lands in the public directory for the Shell to read back via agent.read / grep / head / tail
am startservice -n com.mengpaw.browser/.service.RunCommandService \
  --es com.mengpaw.browser.RUN_COMMAND_ARGUMENTS "-c,page.content --head 20" \
  --es com.mengpaw.browser.RUN_COMMAND_OUTPUT /storage/emulated/0/MengPaw/out.txt
```

If the browser process is killed the am bridge becomes unreachable; waking it again restores it. While it is not
running, calls report "browser not ready (open the MP browser first and retry)".

### 3. Security Model

| Layer | Protection |
|----|------|
| Caller authentication | am bridge signature permission `RUN_BROWSER_COMMAND`; same-signature apps only |
| Command surface | am bridge payload whitelist `page.*`/`browser.*`; arbitrary shell commands are rejected |
| Output path | output files are confined to the public directory `MengPaw/`; system paths are forbidden |
| Storage | `MANAGE_EXTERNAL_STORAGE`, permission dialog on first launch; after denial, every `page.load` prompts to re-grant |

### 4. Operating After a Successful Connection

Once the connection is established, all of the browser's operating capabilities (the full 43-command table / semi-automatic loop / form automation / web scraping / troubleshooting quick reference / Playwright comparison) are covered by the companion document
**[MengPaw_Browser_skills.md](article.en?md=articles/mengpaw-browser-skills.en.md)**<a class="md-dl" href="articles/mengpaw-browser-skills.en.md" download="mengpaw-browser-skills.en.md" title="Download MengPaw_Browser_skills.md" aria-label="Download MengPaw_Browser_skills.md"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 10.5V13a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1v-2.5"/><path d="M8 2v9.5"/><path d="M4.5 8 8 11.5 11.5 8"/></svg></a>, and this development document does not repeat them.

---

## Part 2 Starting from the Source — Directory Structure and Implementation

### 5. Repository and Build

This repository is an **independent browser project** (rootProject `MengPawBrowser`, with `:mengpaw-browser` as its only module), split out of the main MengPaw repository as an APK artifact and **now evolving independently**. The shared foundation (micro-kernel / Android adaptation / design system) does not live here; it is consumed from main-repository artifacts via **JitPack**: `com.github.WowBlueStudio.MengPaw:<module>:<tag>`.

**Coupling boundary with Shell / the main repository (only two items, everything else decoupled)**: ① the command manual
`docs/MengPaw_Browser_skills.md` must be synced to the Shell side; ② Android engineering notes are shared in the main
repository's `docs/lessons.md`. Decoupled: version line / releases / update path / roadmap / documentation ownership.
**This project is a neutral tool** — Shell using the Browser as a tool, or even checking for and installing its updates, is
Shell's own behaviour and does not conflict with this project's independent evolution; third-party shell-style software
can adapt by following the same command manual.

- Module: `mengpaw-browser` (Gradle Android application, standalone APK `com.mengpaw.browser`)
- Version: independent cadence v0.10.x, with a **single source of truth** in `gradle.properties`'s `mengpaw.browser.version`
  (kept in sync with `mengpaw-browser/build.gradle.kts`, where versionCode also lives)
- Shared foundation version: `gradle.properties`'s `mengpaw.foundation.version` (pointing at a main-repository kernel tag;
  local validation can use `mengpaw.useLocal=true` to resolve from mavenLocal, while production uses JitPack)
- Dependencies: `mengpaw-kernel` (CLI execution / port table / error codes), `mengpaw-core` (DataPaths/Logger),
  `mengpaw-design-system` (ArcoTheme)
- Build: `.\gradlew.bat :mengpaw-browser:assembleDebug` /
  `.\gradlew.bat :mengpaw-browser:assembleRelease` (release disables minification and resource shrinking — see build.gradle.kts)
- Test: `.\gradlew.bat :mengpaw-browser:testDebugUnitTest` (pure JVM unit tests)
- Artifacts: `mengpaw-browser/build/outputs/apk/{debug,release}/mengpaw-browser-v<ver>-{debug,release}.apk`
  (this repository **releases independently**: every Release ships the release APK; whether the Shell side picks it up is that side's own behaviour, and this project does not depend on it)

### 6. Directory Structure (File Map)

```
com.mengpaw.browser
├── BrowserActivity.kt         # APK entry: status bridge / permission guidance / am bridge shared instance
├── BrowserApp.kt              # Compose main UI (tabs / address bar / dialog state)
├── BrowserAppDialogs.kt       # Dialog rendering layer (state hoisted, parameters passed explicitly)
├── BrowserContentArea.kt      # Content area (NewTabPage / multi-tab WebView)
├── BrowserDarkMode.kt         # Dark mode injection
├── bridge/                    # BrowserBridge / BrowserScripts / FullPageScreenshotter
├── data/                      # BrowserPrefs / BrowserTypes / HistoryStore
├── plugin/                    # BuiltinBrowserPlugin + 4 command groups + BrowserCommandContext
├── service/                   # RunCommandService (am bridge) / GoogleTranslate
├── ui/                        # TopBar / Settings / Bookmarks / History / Tabs and other Compose UI
├── util/                      # AdBlocker / BrowserStorage / DownloadUtil / PdfUtil / SmartNavigate
└── web/                       # WebViewFactory / MdViewer* / PdfViewer*
```

> **Document viewers**: `.md` goes through `MdViewer*` + `assets/markdown_viewer` (commonmark → HTML);
> `.pdf` goes through `PdfViewer*` + `assets/pdf_viewer` (pdf.js 2.16 + CMaps, supporting zoom in/out and text selection,
> for both remote `.pdf` URLs and local file/content VIEW intents). Both are near-full-screen WebView dialogs.

Key lifecycle events:

- `BrowserActivity.onCreate`: initializes DataPaths/Logger → binds Quick Click / screenshot settings to
  `BuiltinBrowserPlugin` → `BuiltinBrowserPlugin.shared` is reused by the am bridge →
  requests "All files access" on first launch.
- `BrowserActivity.onDestroy`: destroys all WebViews and clears the status bridge.
- The 9880 HTTP bridge (`McpHttpServer`/`McpAuthPolicy`/`BrowserMcpTools`) was retired and deleted with decision #7.

### 7. Command-Surface Implementation

Registration source: `BuiltinBrowserPlugin.commands` =
`BrowserTabCommands` + `BrowserPageCommands` + `BrowserQueryCommands` +
`BrowserPlaywrightCommands`. 43 commands in total (page.* 22 + browser.* 21).

- `BrowserPlaywrightCommands`: `page.*` — 22 commands; argument parsing supports positional arguments +
  `--flag` values (`wait/max-height/grep/head/tail/timeout`) + boolean flags (`-i` etc.)
- `BrowserTabCommands`: `tabs` / `tab` / `tab.open` / `tab.close` / `tab.all`
- `BrowserPageCommands`: `inject` / `diff` / `preload` / `wait` / `wait.nav` /
  `cookies` / `cookies.set` / `cookies.clear` / `dialog.accept` / `dialog.dismiss`
- `BrowserQueryCommands`: `visible` / `enabled` / `storage` / `viewport` /
  `userAgent` / `version`

All command implementations uniformly receive `(List<String>, ExecutionContext) -> ExecutionResult`, and access the
WebView bridge (`BrowserBridge`) / tab state / screenshotter through `BrowserCommandContext`.

### 8. Invocation-Channel Implementation — the am Bridge (`RunCommandService`)

```text
action:  com.mengpaw.browser.RUN_COMMAND
extra:   com.mengpaw.browser.RUN_COMMAND_ARGUMENTS = "-c,<command-string>"
extra:   com.mengpaw.browser.RUN_COMMAND_OUTPUT    = <output-file-path, public directory>
extra:   com.mengpaw.browser.RUN_COMMAND_BACKGROUND = true
permission: com.mengpaw.permission.RUN_BROWSER_COMMAND (signature)
whitelist: only page.* / browser.* prefixes
```

`RunCommandService` performs quote-aware tokenization, executes commands through `BuiltinBrowserPlugin.shared`, and the
output is written to disk for the caller to read. If the browser is not running, it reports "browser not ready (open the MP browser first and retry)".

> The 9880 HTTP bridge (`McpHttpServer`) and MCP open mode were retired and deleted under decision #7:
> the browser side no longer has an HTTP bridge, token, `GET /health` or `POST /mcp`;
> cleaning up the kernel-side documentation tables / prompt sections and mengpaw-connectors' browser-mcp-plugin
> is left to the main repository (see browser-autopilot-plan.md §9).

### 9. Security Model

| Layer | Protection |
|---|------|
| am bridge | signature permission `RUN_BROWSER_COMMAND`; same-signature apps only |
| Command surface | am bridge payload whitelist `page.*`/`browser.*`; arbitrary shell is rejected |
| Output path | am bridge output is restricted to the public directory `MengPaw/` |
| Storage | `MANAGE_EXTERNAL_STORAGE`, permission dialog on first launch; after denial, every `page.load` prompts to re-grant |

The 9880 bridge and open mode are retired (decision #7) — there is no longer a token or authentication-free channel,
and the attack surface converges on a single am bridge plus a signature permission.

### 10. Storage and Screenshots

- Screenshots/output are written to: `/storage/emulated/0/MengPaw/截图存档` (public directory)
- Over-long pages are segmented: each segment ≈ one viewport height, up to 30 segments, marked `partial:true` beyond that
- Coordinate system: segment-image coordinates → page coordinates are restored automatically by the browser (zoom ratio / segment offset)
- Settings persistence: `BrowserPrefs` (SharedPreferences `mp_browser`)

### 11. Testing

`src/test/kotlin/com/mengpaw/browser/`:

- `util/SmartNavigateTest.kt` / `util/AdBlockerTest.kt` / `util/PdfUtilTest.kt`
  (26 test cases: 13 + 8 + 5, v0.10.0 snapshot)

Changes to the command surface / bridge / security logic must add matching unit tests; changes to core paths must keep
`:mengpaw-browser:testDebugUnitTest` fully green.

### 12. Development Conventions

- Verify command listings against the registration source (`BuiltinBrowserPlugin.commands` aggregation — don't rely on grep impressions)
- Adding a command requires four-source sync: command registration / [`MengPaw_Browser_skills.md`](article.en?md=articles/mengpaw-browser-skills.en.md)<a class="md-dl" href="articles/mengpaw-browser-skills.en.md" download="mengpaw-browser-skills.en.md" title="Download MengPaw_Browser_skills.md" aria-label="Download MengPaw_Browser_skills.md"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 10.5V13a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1v-2.5"/><path d="M8 2v9.5"/><path d="M4.5 8 8 11.5 11.5 8"/></svg></a> / the development guide / the prompt
- Single source of truth for ports: `Ports.kt` (9876 kernel reserved / 9881 MCP gateway; the 9880 browser MCP is retired,
  and the constant is being cleaned up together with the main-repository kernel)
- Every new `.kt` must carry the SPDX dual-license header; single files ≤ 400 lines; no `!!`
- Dual license: `AGPL-3.0-or-later OR LicenseRef-Commercial`