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(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.
• 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

# ① 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

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, 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)

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

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 / 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