persistent-browser-bridge 0.1.0__tar.gz

persistent_browser_bridge-0.1.0/.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{md,yml,yaml}]
+indent_size = 2
+

persistent_browser_bridge-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,32 @@
+name: Bug report
+description: Report reproducible incorrect behavior
+body:
+  - type: markdown
+    attributes:
+      value: Never attach profiles, credentials, cookies, or private page content.
+  - type: input
+    id: version
+    attributes:
+      label: PBB version
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options: [Windows 10, Windows 11, macOS, Linux]
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Reproduction steps
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected and actual behavior
+    validations:
+      required: true
+

persistent_browser_bridge-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Propose a focused, safe improvement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What agent workflow is blocked today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+    validations:
+      required: true
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Safety
+      options:
+        - label: This request does not bypass CAPTCHA, authentication, anti-bot controls, or authorization.
+          required: true
+

persistent_browser_bridge-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Summary
+
+Describe the user-visible change and why it belongs in the current scope.
+
+## Verification
+
+- [ ] Tests added or updated
+- [ ] `ruff check .` passes
+- [ ] `pytest` passes
+- [ ] `python -m build` passes
+- [ ] No credentials, profiles, cookies, or private page data included
+- [ ] Documentation updated when behavior changed
+

persistent_browser_bridge-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+

persistent_browser_bridge-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest
+      - run: python -m build
+

persistent_browser_bridge-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+dist/
+build/
+*.log
+logs/
+profiles/
+downloads/
+screenshots/
+browser-data/
+user-data-dir/
+pbb-screenshot.png
+/acceptance.png
+/acceptance-downloads/
+.env
+.env.*
+config.local
+config.local.*
+.idea/
+.vscode/
+*.code-workspace
+.DS_Store
+Thumbs.db
+

persistent_browser_bridge-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

persistent_browser_bridge-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes follow Keep a Changelog. This project uses Semantic Versioning.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-30
+
+### Added
+
+- Persistent Edge, Chrome, and Chromium profiles.
+- Local FastAPI daemon and Typer CLI.
+- Compact safe DOM snapshots and guarded snapshot references.
+- Navigation, click, fill, text, download, and screenshot actions.
+- JSON output, profile locks, stale-lock recovery, tests, and documentation.
+

persistent_browser_bridge-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, experience, education, socioeconomic status, nationality, appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our standards
+
+Positive behavior includes empathy, constructive feedback, respect for differing viewpoints, and accepting responsibility. Unacceptable behavior includes harassment, sexualized language or attention, insults, threats, trolling, and publishing private information without permission.
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject contributions and may temporarily or permanently ban participants for behavior they deem inappropriate. Report conduct issues privately through the repository maintainers. All complaints will be reviewed promptly and fairly, with respect for reporter privacy.
+
+This code is adapted from Contributor Covenant 2.1.
+

persistent_browser_bridge-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+Thanks for helping PBB. Open an issue before substantial changes so scope and safety expectations are clear.
+
+```console
+python -m venv .venv
+.venv\Scripts\activate
+python -m pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+```
+
+On macOS or Linux, activate with `source .venv/bin/activate`. Keep changes typed, focused, and tested. Never add credential extraction, CAPTCHA bypass, fingerprint spoofing, anti-detection, or scraping-evasion features. Do not place real profiles or credentials in fixtures.
+
+Commits should describe coherent changes, for example `feat: add compact DOM snapshot` or `fix: reject stale profile references`. By participating, you agree to follow the Code of Conduct.
+

persistent_browser_bridge-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Persistent Browser Bridge 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.
+

persistent_browser_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: persistent-browser-bridge
+Version: 0.1.0
+Summary: Give AI coding agents a real persistent browser.
+Author: Persistent Browser Bridge contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,browser-automation,persistent-profile,playwright
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: platformdirs<5,>=4.2
+Requires-Dist: playwright<2,>=1.48
+Requires-Dist: psutil<8,>=6
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: rich<15,>=13.9
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: uvicorn<1,>=0.30
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Requires-Dist: types-psutil<8,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Persistent Browser Bridge
+
+> Give AI coding agents a real persistent browser.
+
+Persistent Browser Bridge (PBB) is a local browser-control layer built on Playwright. Instead of forcing AI agents to repeatedly inspect screenshots, PBB exposes lightweight DOM-first browser actions while preserving real browser sessions across runs.
+
+**Persistent. DOM-first. Local-first. Agent-friendly. Low-context.**
+
+PBB is an early v0.1 release for normal, authorized browser automation. It is not a CAPTCHA bypass, anti-detection toolkit, credential collector, or scraping-evasion framework.
+
+## Why PBB
+
+Visual automation remains valuable when a page cannot be understood through the DOM. For routine forms, links, text, and downloads, a compact DOM snapshot is faster to inspect and less dependent on screen coordinates. A dedicated persistent browser profile also keeps cookies, local storage, IndexedDB, and login state between runs without touching your everyday browser profile.
+
+| Feature | Computer Use | PBB |
+|---|---|---|
+| Interaction | Visual | DOM-first |
+| Browser state | Depends on environment | Dedicated persistent profile |
+| Login reuse | Environment dependent | Reuses its PBB profile |
+| Element targeting | Vision and coordinates | DOM locators and snapshot references |
+| Downloads | UI dependent | Playwright download events |
+| Agent context | Visual-heavy | Compact DOM snapshot |
+| Recovery | Agent dependent | Basic page and stale-lock recovery |
+| Local-first | Depends | Yes |
+
+PBB complements visual browser automation rather than replacing every use case.
+
+## Architecture
+
+```text
+AI agent -> pbb CLI -> localhost daemon -> Playwright
+         -> real Edge/Chrome -> dedicated persistent profile -> website
+```
+
+The daemon binds to `127.0.0.1` by default and owns the Playwright process, active page, snapshot references, and download handling. CLI commands talk only to that local daemon, so a browser is not restarted for each action.
+
+## Installation
+
+PBB requires Python 3.11 or newer. Edge is preferred, Chrome is supported, and Playwright Chromium is the fallback.
+
+```console
+cd persistent-browser-bridge
+python -m pip install -e .
+```
+
+If no system browser is available, install Playwright Chromium with `python -m playwright install chromium`. The package has not been published to PyPI yet; do not use `pip install persistent-browser-bridge` until a release announcement says otherwise.
+
+## Quick start
+
+```console
+pbb doctor
+pbb profile create default
+pbb start --profile default
+pbb open https://example.com
+pbb snapshot
+pbb text h1
+pbb close
+```
+
+The first start opens a visible browser. Sign in manually when needed. PBB never asks for or stores account passwords; CAPTCHA, 2FA, device confirmation, and reauthentication remain user actions.
+
+## Profiles
+
+PBB profiles are separate from daily Edge and Chrome profiles:
+
+```console
+pbb profile create work
+pbb profile list
+pbb profile path work
+pbb profile delete work
+```
+
+Deletion requires confirmation (or explicit `--yes`) and only removes directories carrying PBB's own profile marker. PBB never deletes native Edge or Chrome lock files.
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `pbb start --profile NAME` | Start the daemon and persistent browser |
+| `pbb status` | Show process, profile, browser, page, and tabs |
+| `pbb open URL` | Navigate and wait for `domcontentloaded` |
+| `pbb snapshot` | Return a compact DOM snapshot |
+| `pbb click TARGET` | Click a reference, selector, or semantic target |
+| `pbb fill TARGET VALUE` | Fill a field; password values are never returned |
+| `pbb text TARGET` | Read visible element text |
+| `pbb download TARGET` | Wait for a real download event and save the file |
+| `pbb screenshot [PATH]` | Capture a supporting screenshot |
+| `pbb recover` | Clear stale PBB-owned locks |
+| `pbb close` | Close browser and daemon |
+
+Every action supports `--json`. Failures use a stable shape:
+
+```json
+{"success": false, "error": "element_not_found", "message": "...", "details": {}}
+```
+
+## Snapshots and targets
+
+`pbb snapshot --json` returns the page title, URL, headings, bounded visible text, and interactive elements. It excludes scripts, styles, hidden elements, cookies, password values, and hidden tokens. Internal selectors remain inside the daemon.
+
+```json
+{
+  "success": true,
+  "snapshot_id": "s_123abc",
+  "elements": [
+    {"id": 1, "role": "textbox", "name": "Email", "placeholder": "you@example.com"},
+    {"id": 2, "role": "button", "name": "Sign in"}
+  ]
+}
+```
+
+Use `@1`, `@2`, or the explicit `s_123abc:@2` form. PBB rejects stale references after navigation or when element identity changes. It resolves targets conservatively: snapshot reference, unique selector, exact button/link role, label, placeholder, then exact text. Multiple matches return `ambiguous_target`; PBB never chooses one at random.
+
+PowerShell reserves `@` syntax, so quote references there: `pbb click '@2'`. Bash and similar shells accept `pbb click @2`.
+
+## Downloads
+
+```console
+pbb download "Download PDF"
+pbb download @5 --output ./downloads
+```
+
+PBB waits for Playwright's download event and uses `save_as`. A click that does not emit a download returns `download_not_triggered` rather than reporting false success. The default destination is `~/Downloads/PBB`.
+
+## Configuration
+
+PBB reads `config.toml` from the platform's application config directory. Supported keys are `browser`, `default_profile`, `daemon_host`, `daemon_port`, `download_dir`, `timeout`, `headless`, and `snapshot_max_chars`. v0.1 rejects non-loopback daemon hosts.
+
+Environment overrides: `PBB_BROWSER`, `PBB_PROFILE`, `PBB_PORT`, `PBB_DOWNLOAD_DIR`, and `PBB_TIMEOUT`.
+
+## Privacy and security
+
+PBB runs locally and includes no telemetry. Browser profiles remain on the device. PBB does not upload browsing history, cookies, credentials, or profiles; does not export cookies; and does not access a password manager. Treat the profile directory as sensitive local data. See [SECURITY.md](SECURITY.md).
+
+## Agent integration
+
+Recommended flow: check status, start if needed, inspect `snapshot --json`, use DOM actions, and only fall back to screenshots or Computer Use when the DOM is insufficient. Full guidance is in [docs/agent-integration.md](docs/agent-integration.md).
+
+### Codex integration
+
+Copy this prompt into a project instruction:
+
+```text
+Always prefer Persistent Browser Bridge for browser automation when it is available.
+
+Browser strategy:
+1. Run `pbb status` and start PBB if needed.
+2. Use `pbb snapshot --json` to inspect the current page.
+3. Prefer `pbb click`, `pbb fill`, `pbb text`, and `pbb download`.
+4. Reuse the existing persistent browser profile. Do not launch another browser unless necessary.
+5. Use screenshots or Computer Use only when DOM-based interaction fails.
+6. Never request or store account passwords.
+7. Let the user manually complete authentication, CAPTCHA, 2FA, or device verification.
+8. Continue using the same profile after authentication.
+```
+
+## Python SDK and MCP
+
+A stable Python SDK and MCP server are planned for v0.2. The daemon's local HTTP API is an implementation detail in v0.1 and may change. No SDK or MCP support is claimed in this release.
+
+## Limitations
+
+- Snapshot references are daemon-memory state and do not survive daemon restarts.
+- Shadow DOM, canvas-only controls, cross-origin frames, and highly virtualized UIs may need direct selectors or visual automation.
+- Recovery covers closed pages and stale PBB locks; full crash replay is planned.
+- One daemon controls one profile at a time in v0.1.
+- Benchmarks are not published. PBB is designed to reduce repeated visual context usage, but no token or cost savings are claimed.
+
+## Benchmark framework
+
+The [benchmarks](benchmarks/README.md) directory defines a future comparison schema. Results are coming soon; no fabricated figures are included.
+
+## Roadmap, contributing, and license
+
+See [ROADMAP.md](ROADMAP.md), [CONTRIBUTING.md](CONTRIBUTING.md), and the [MIT License](LICENSE).
+

persistent_browser_bridge-0.1.0/README.md

@@ -0,0 +1,176 @@
+# Persistent Browser Bridge
+
+> Give AI coding agents a real persistent browser.
+
+Persistent Browser Bridge (PBB) is a local browser-control layer built on Playwright. Instead of forcing AI agents to repeatedly inspect screenshots, PBB exposes lightweight DOM-first browser actions while preserving real browser sessions across runs.
+
+**Persistent. DOM-first. Local-first. Agent-friendly. Low-context.**
+
+PBB is an early v0.1 release for normal, authorized browser automation. It is not a CAPTCHA bypass, anti-detection toolkit, credential collector, or scraping-evasion framework.
+
+## Why PBB
+
+Visual automation remains valuable when a page cannot be understood through the DOM. For routine forms, links, text, and downloads, a compact DOM snapshot is faster to inspect and less dependent on screen coordinates. A dedicated persistent browser profile also keeps cookies, local storage, IndexedDB, and login state between runs without touching your everyday browser profile.
+
+| Feature | Computer Use | PBB |
+|---|---|---|
+| Interaction | Visual | DOM-first |
+| Browser state | Depends on environment | Dedicated persistent profile |
+| Login reuse | Environment dependent | Reuses its PBB profile |
+| Element targeting | Vision and coordinates | DOM locators and snapshot references |
+| Downloads | UI dependent | Playwright download events |
+| Agent context | Visual-heavy | Compact DOM snapshot |
+| Recovery | Agent dependent | Basic page and stale-lock recovery |
+| Local-first | Depends | Yes |
+
+PBB complements visual browser automation rather than replacing every use case.
+
+## Architecture
+
+```text
+AI agent -> pbb CLI -> localhost daemon -> Playwright
+         -> real Edge/Chrome -> dedicated persistent profile -> website
+```
+
+The daemon binds to `127.0.0.1` by default and owns the Playwright process, active page, snapshot references, and download handling. CLI commands talk only to that local daemon, so a browser is not restarted for each action.
+
+## Installation
+
+PBB requires Python 3.11 or newer. Edge is preferred, Chrome is supported, and Playwright Chromium is the fallback.
+
+```console
+cd persistent-browser-bridge
+python -m pip install -e .
+```
+
+If no system browser is available, install Playwright Chromium with `python -m playwright install chromium`. The package has not been published to PyPI yet; do not use `pip install persistent-browser-bridge` until a release announcement says otherwise.
+
+## Quick start
+
+```console
+pbb doctor
+pbb profile create default
+pbb start --profile default
+pbb open https://example.com
+pbb snapshot
+pbb text h1
+pbb close
+```
+
+The first start opens a visible browser. Sign in manually when needed. PBB never asks for or stores account passwords; CAPTCHA, 2FA, device confirmation, and reauthentication remain user actions.
+
+## Profiles
+
+PBB profiles are separate from daily Edge and Chrome profiles:
+
+```console
+pbb profile create work
+pbb profile list
+pbb profile path work
+pbb profile delete work
+```
+
+Deletion requires confirmation (or explicit `--yes`) and only removes directories carrying PBB's own profile marker. PBB never deletes native Edge or Chrome lock files.
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `pbb start --profile NAME` | Start the daemon and persistent browser |
+| `pbb status` | Show process, profile, browser, page, and tabs |
+| `pbb open URL` | Navigate and wait for `domcontentloaded` |
+| `pbb snapshot` | Return a compact DOM snapshot |
+| `pbb click TARGET` | Click a reference, selector, or semantic target |
+| `pbb fill TARGET VALUE` | Fill a field; password values are never returned |
+| `pbb text TARGET` | Read visible element text |
+| `pbb download TARGET` | Wait for a real download event and save the file |
+| `pbb screenshot [PATH]` | Capture a supporting screenshot |
+| `pbb recover` | Clear stale PBB-owned locks |
+| `pbb close` | Close browser and daemon |
+
+Every action supports `--json`. Failures use a stable shape:
+
+```json
+{"success": false, "error": "element_not_found", "message": "...", "details": {}}
+```
+
+## Snapshots and targets
+
+`pbb snapshot --json` returns the page title, URL, headings, bounded visible text, and interactive elements. It excludes scripts, styles, hidden elements, cookies, password values, and hidden tokens. Internal selectors remain inside the daemon.
+
+```json
+{
+  "success": true,
+  "snapshot_id": "s_123abc",
+  "elements": [
+    {"id": 1, "role": "textbox", "name": "Email", "placeholder": "you@example.com"},
+    {"id": 2, "role": "button", "name": "Sign in"}
+  ]
+}
+```
+
+Use `@1`, `@2`, or the explicit `s_123abc:@2` form. PBB rejects stale references after navigation or when element identity changes. It resolves targets conservatively: snapshot reference, unique selector, exact button/link role, label, placeholder, then exact text. Multiple matches return `ambiguous_target`; PBB never chooses one at random.
+
+PowerShell reserves `@` syntax, so quote references there: `pbb click '@2'`. Bash and similar shells accept `pbb click @2`.
+
+## Downloads
+
+```console
+pbb download "Download PDF"
+pbb download @5 --output ./downloads
+```
+
+PBB waits for Playwright's download event and uses `save_as`. A click that does not emit a download returns `download_not_triggered` rather than reporting false success. The default destination is `~/Downloads/PBB`.
+
+## Configuration
+
+PBB reads `config.toml` from the platform's application config directory. Supported keys are `browser`, `default_profile`, `daemon_host`, `daemon_port`, `download_dir`, `timeout`, `headless`, and `snapshot_max_chars`. v0.1 rejects non-loopback daemon hosts.
+
+Environment overrides: `PBB_BROWSER`, `PBB_PROFILE`, `PBB_PORT`, `PBB_DOWNLOAD_DIR`, and `PBB_TIMEOUT`.
+
+## Privacy and security
+
+PBB runs locally and includes no telemetry. Browser profiles remain on the device. PBB does not upload browsing history, cookies, credentials, or profiles; does not export cookies; and does not access a password manager. Treat the profile directory as sensitive local data. See [SECURITY.md](SECURITY.md).
+
+## Agent integration
+
+Recommended flow: check status, start if needed, inspect `snapshot --json`, use DOM actions, and only fall back to screenshots or Computer Use when the DOM is insufficient. Full guidance is in [docs/agent-integration.md](docs/agent-integration.md).
+
+### Codex integration
+
+Copy this prompt into a project instruction:
+
+```text
+Always prefer Persistent Browser Bridge for browser automation when it is available.
+
+Browser strategy:
+1. Run `pbb status` and start PBB if needed.
+2. Use `pbb snapshot --json` to inspect the current page.
+3. Prefer `pbb click`, `pbb fill`, `pbb text`, and `pbb download`.
+4. Reuse the existing persistent browser profile. Do not launch another browser unless necessary.
+5. Use screenshots or Computer Use only when DOM-based interaction fails.
+6. Never request or store account passwords.
+7. Let the user manually complete authentication, CAPTCHA, 2FA, or device verification.
+8. Continue using the same profile after authentication.
+```
+
+## Python SDK and MCP
+
+A stable Python SDK and MCP server are planned for v0.2. The daemon's local HTTP API is an implementation detail in v0.1 and may change. No SDK or MCP support is claimed in this release.
+
+## Limitations
+
+- Snapshot references are daemon-memory state and do not survive daemon restarts.
+- Shadow DOM, canvas-only controls, cross-origin frames, and highly virtualized UIs may need direct selectors or visual automation.
+- Recovery covers closed pages and stale PBB locks; full crash replay is planned.
+- One daemon controls one profile at a time in v0.1.
+- Benchmarks are not published. PBB is designed to reduce repeated visual context usage, but no token or cost savings are claimed.
+
+## Benchmark framework
+
+The [benchmarks](benchmarks/README.md) directory defines a future comparison schema. Results are coming soon; no fabricated figures are included.
+
+## Roadmap, contributing, and license
+
+See [ROADMAP.md](ROADMAP.md), [CONTRIBUTING.md](CONTRIBUTING.md), and the [MIT License](LICENSE).
+

persistent_browser_bridge-0.1.0/ROADMAP.md

@@ -0,0 +1,18 @@
+# Roadmap
+
+## v0.1.0
+
+Persistent profiles, browser detection, localhost daemon, CLI, compact snapshots, guarded locators, click, fill, text, navigation, downloads, screenshots, JSON output, basic recovery, docs, tests, and release automation.
+
+## v0.2.0
+
+Stable Python SDK, MCP server, tabs, stronger crash recovery, shadow-DOM and iframe snapshot improvements, and richer smart locators.
+
+## v0.3.0
+
+Optional Computer Use fallback adapter, visual fallback, browser event stream, and action recorder.
+
+## v0.4.0
+
+Multi-agent sessions, opt-in authenticated remote mode, session replay, and opt-in telemetry design.
+

persistent_browser_bridge-0.1.0/SECURITY.md

@@ -0,0 +1,16 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the latest released minor version.
+
+## Design boundaries
+
+PBB binds to loopback only, has no remote mode in v0.1, and includes no telemetry. It does not upload profiles, export cookies, read password managers, bypass CAPTCHA or 2FA, spoof fingerprints, or provide anti-detection behavior. Authentication must be completed by the user.
+
+Dedicated PBB profiles contain sensitive browser state. Protect them using normal operating-system account controls. Do not sync or publish these directories. PBB lock recovery only removes `profile.lock`, a file created by PBB; it never removes browser-native lock files.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use GitHub's private security advisory flow for the repository. Include affected version, reproduction steps, impact, and any proposed mitigation. Maintainers should acknowledge a report within seven days.
+