feat: browser run playwright sandbox

NOTICE

@@ -1 +1,35 @@
 webcmd is based on opencli (https://github.com/jackwener/opencli), Copyright 2025 jackwener, licensed under Apache-2.0.
+
+The browser-run QuickJS lifecycle is derived from dev-browser
+(https://github.com/SawyerHood/dev-browser), Copyright Sawyer Hood,
+licensed under the MIT License.
+
+The browser-run Playwright QuickJS client includes Playwright code from
+https://github.com/microsoft/playwright, licensed under Apache-2.0.
+
+The browser snapshot capture, model, renderer, diff, and page-stability modules
+in src/browser/snapshot/capture.ts, types.ts, render.ts, diff.ts, and
+wait-for-page-stable.ts are derived from libretto-browser-tools
+(https://github.com/Skyvern-AI/libretto).
+
+MIT License
+
+Copyright (c) 2026 Libretto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -34,6 +34,15 @@ On top of live browser control, WebCMD adds 3 layers of learnings. Each layer co
 | 3. CLI authoring | The action space is known, but the path is still too variable for one fixed sequence. | Explicitly author a reusable `webcmd <site>` adapter with structured output, so future agents spend tokens on the task instead of navigation. |
 | 4. Extend existing CLIs | The workflow is deterministic enough to stop browsing. | Extend the `webcmd <site>` adapter with a tailored command so the workflow runs instantly with the least amount of tokens. |
 
+For local, multi-step browser exploration, agents can send one sandboxed
+Playwright-style program to an existing CloakBrowser session:
+
+```bash
+webcmd browser work run --file explore.js
+printf 'const page = await browser.currentPage(); return await page.title();' \
+  | webcmd browser work run --stdin
+```
+
 ## Demo
 
 https://github.com/user-attachments/assets/04eceadc-d398-4303-984d-ae3197bfa664

docs/cli-reference.mdx

@@ -55,6 +55,39 @@ webcmd web fetch-browser --url https://example.com/app-shell
 
 The old `web read` command has been renamed to `web fetch-browser`.
 
+## Local Browser Programs
+
+`browser run` executes one Playwright-style JavaScript program against an
+existing local CloakBrowser session:
+
+```bash
+webcmd browser work snapshot --snapshot-mode act
+webcmd browser work snapshot --snapshot-mode read
+webcmd browser work run --stdin --timeout 45
+webcmd browser work run --stdin --no-snapshot-diff
+```
+
+Use `snapshot` for explicit page inspection. `act` is the default
+action-first mode, `tree` preserves fuller page structure, and `read` extracts readable article/content text. Exactly one of `--file
+<path>` or `--stdin` is required for `run`. The CLI reads files locally and
+sends source—not the path—to the local daemon. `--timeout` is in seconds and
+`--max-output` bounds returned results and logs. Successful runs return a
+`snapshotDiff` by default; pass `--no-snapshot-diff` only when the program is
+pure read-only and its result already contains the needed state.
+
+The program runs in a fresh QuickJS sandbox with `page`, `context`, `browser`,
+and `console` globals. `page.snapshotForAI()` is not available. It can use the
+supported Page/Frame/Locator methods and passively inspect request and response
+events. It cannot access Node.js, the filesystem, environment variables, raw
+CDP endpoints, browser launch/connect APIs, or browser-context ownership.
+Screenshot bytes are written to a Webcmd-owned cache directory and returned as
+a receipt.
+
+The public browser surface is `tabs`, `bind`, `run`, `snapshot`, and `close`.
+Reusable adapters continue to use the existing `IPage` API. Playwright-style
+programs are for reconnaissance and ad-hoc multi-step work; they are not pasted
+into adapter modules.
+
 ## Top-Level Commands
 
 | Command | Purpose |
@@ -148,6 +181,7 @@ Register our internal `releasectl` binary as a Webcmd external CLI with a short
 | `~/.webcmd/` | User-level Webcmd state. |
 | `~/.webcmd/clis/` | Private adapters and local overrides. |
 | `~/.webcmd/cache/browser-network/` | Browser network capture cache. |
+| `~/.webcmd/cache/browser-run/` | Host-owned browser-run screenshot artifacts. |
 | `~/.webcmd/external-clis.yaml` | User external CLI registry. |
 | `skills/` | Bundled agent skills shipped with the package. |
 

package.json

@@ -21,6 +21,9 @@
     "./browser/ax-snapshot": "./dist/src/browser/ax-snapshot.js",
     "./browser/cdp": "./dist/src/browser/cdp.js",
     "./browser/page": "./dist/src/browser/page.js",
+    "./browser/run": "./dist/src/browser/run/index.js",
+    "./browser/snapshot": "./dist/src/browser/snapshot/index.js",
+    "./browser/article-extract": "./dist/src/browser/article-extract.js",
     "./browser/utils": "./dist/src/browser/utils.js",
     "./download": "./dist/src/download/index.js",
     "./download/article-download": "./dist/src/download/article-download.js",
@@ -54,6 +57,7 @@
     "sync-community-plugins": "tsx scripts/sync-community-plugins.ts",
     "generate-release-notes": "tsx scripts/generate-release-notes.ts",
     "docs-sync-review": "tsx scripts/docs-sync-review.ts",
+    "benchmark:snapshot": "tsx scripts/benchmark-snapshot-render.ts",
     "start": "node dist/src/main.js",
     "start:bun": "bun dist/src/main.js",
     "preuninstall": "node -e \"fetch('http://127.0.0.1:9777/shutdown',{method:'POST',headers:{'X-Webcmd':'1'},signal:AbortSignal.timeout(3000)}).catch(()=>{})\" || true",
@@ -97,19 +101,22 @@
     "js-yaml": "^4.3.0",
     "jsdom": "^29.0.2",
     "playwright-core": "1.61.1",
+    "quickjs-emscripten": "0.32.0",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
     "undici": "^6.27.0",
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@emnapi/core": "^1.11.2",
     "@emnapi/runtime": "^1.11.2",
     "@google/genai": "^2.10.0",
     "@types/js-yaml": "^4.0.9",
     "@types/jsdom": "^27.0.0",
     "@types/node": "^25.5.2",
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.5.13",
+    "esbuild": "^0.28.1",
     "tsx": "^4.19.3",
     "typescript": "^6.0.2",
     "vitest": "^4.1.0"