feat(extension): prepare Chrome Web Store beta

.changeset/calm-spiders-connect.md

@@ -0,0 +1,8 @@
+---
+"@opencode-ai/browser-control": patch
+---
+
+Prepare an unlisted Chrome Web Store extension with protocol-based relay
+compatibility, deterministic packaging, and more reliable cold-start target
+creation. Session reset and delete now recover relay-owned targets whose
+debugger attachment was permanently lost during an extension update.

.gitignore

@@ -2,4 +2,5 @@
 node_modules/
 dist/
 extension/dist/
+artifacts/
 tmp/

AGENTS.md

@@ -151,6 +151,10 @@ local Node relay.
   navigation timestamps.
 - Session delete/reset must acquire the session's execute permit before closing
   the sandbox, so running scripts are never yanked mid-flight.
+- Reset/delete of an absent persisted relay-owned target waits for protocol-v1
+  inventory reconciliation or a bounded grace, then forgets the dead identity
+  without guessing a physical tab to close. Never apply this dead-target path
+  to adopted user tabs.
 - The version string and build id are injected by `scripts/build-cli.ts`
   (`src/version.ts`; source runs use `0.0.0-dev` and a deterministic source
   and dependency-lock fingerprint). The relay
@@ -238,7 +242,8 @@ browser-control skill
 
 - Load `extension/dist` as the unpacked extension.
 - The relay listens on `127.0.0.1:19989` by default.
-- Current shim version is `0.0.18`.
+- Current shim version is `0.0.22` and extension protocol version is `1`.
+- Store and npm versions may differ when protocol `1` remains compatible.
 - On socket open the shim sends `hello` and then re-announces every tab it still
   has `chrome.debugger` attached to (`debugger.attached` events), so a restarted
   relay rebuilds its target registry without the user re-clicking the toolbar.

CONTEXT.md

@@ -13,7 +13,7 @@ prompt: |
 
 Browser Control is a local browser driver for agents. It lets trusted agents
 operate the user's visible Chromium-family browser through an installed
-extension and a local bridge.
+extension and a local driver daemon.
 
 ## Language
 
@@ -32,6 +32,19 @@ The user's already-running Chromium-family browser with the Browser Control
 extension installed.
 _Avoid_: Chrome-only, managed browser
 
+**Local Driver Daemon**:
+The persistent Node process that owns Playwright execution, Browser Control
+sessions, target ownership, cross-process serialization, artifacts, and the
+transport to the browser extension. It is a deep module, not a pass-through
+message relay.
+_Avoid_: Temporary bridge, extension reload helper
+
+**Extension Protocol**:
+The compatibility version reported by the extension when it connects to the
+Local Driver Daemon. Store and npm release versions may differ while this
+protocol remains compatible.
+_Avoid_: Extension package version, relay build id
+
 **Attached Tab**:
 A browser tab whose debugger connection is active and therefore visible and
 controllable by agents.
@@ -88,6 +101,14 @@ The endpoint-scoped, private relay file that preserves session identity,
 read-only mode, and the exact default-target pointer across relay processes.
 Lifecycle operations acknowledge only after its atomic replacement is durable.
 It does not serialize Execute Sandbox JavaScript state or snapshot refs.
+
+**Dead Persisted Target**:
+A relay-owned target identity retained in the Session Catalog that is absent
+after the current extension finishes reconciling its attached-tab inventory, or
+after a bounded reconnect grace when no inventory arrives. Explicit reset or
+delete may forget this identity but must never guess which physical tab to
+close.
+_Avoid_: Detached tab, closed user tab
 _Avoid_: Current-session store, session journal, sandbox snapshot
 
 **MCP Process Session**:

PLAN.md

@@ -165,13 +165,19 @@ require a new extension capture protocol and permission model.
 - The package is published publicly on npm. Normal setup installs the npm
   artifact; source development uses `pnpm install`, `pnpm build`, and `bun
   link`.
-- The browser extension remains unpacked for v1 and is loaded from
-  the npm package's `extension/dist` directory or a source build. Its current
-  shim version is `0.0.18`.
+- Until the first Store review completes, the browser extension is loaded
+  unpacked from the npm package's `extension/dist` directory or a source build.
+  Its current shim version is `0.0.22`.
+- Extension and npm releases are independently versioned. The extension hello
+  reports an explicit protocol version, and compatibility rather than exact
+  package-version equality determines whether the local driver may use it.
+- Browser data crosses only the loopback connection unless an authorized local
+  caller sends returned data elsewhere.
 - Extension source changes require rebuilding and reloading the unpacked
   extension. Relay-only changes do not.
-- Chrome Web Store distribution is deferred until behavior stabilizes. A
-  bundled unpacked extension belongs to future managed-browser launch flows.
+- `pnpm package:extension` produces the deterministic Chrome Web Store review
+  ZIP. Distribution starts as an unlisted beta before becoming public. A bundled
+  unpacked extension belongs to future managed-browser launch flows.
 
 ## Session And Tab Model
 
@@ -207,6 +213,11 @@ arbitrary tab from the attached pool.
 - Reset, delete, or detach releases an adopted tab without closing it.
 - Reset and delete acquire the execute permit before closing a sandbox, so they
   cannot interrupt a running script.
+- Reset and delete give an absent persisted relay target a bounded opportunity
+  to re-announce. A completed protocol-v1 inventory, or expiry of the reconnect
+  grace, declares that identity dead so recovery cannot require catalog edits.
+  The relay never guesses a physical tab to close when the live target identity
+  is unavailable.
 - Corrupt session catalogs fail relay startup without being overwritten.
 - The relay wins the endpoint port before loading the catalog or enabling
   catalog writes. Lifecycle responses wait for atomic file replacement, file
@@ -458,7 +469,8 @@ These items are accepted directions but are not current priorities:
   relay endpoint, if multiple profiles become a supported workflow.
 - Add stricter workspace or session ownership only if the loose shared attached
   tab pool causes concrete failures.
-- Publish the extension through the Chrome Web Store after behavior stabilizes.
+- Promote the reviewed Chrome Web Store extension from unlisted beta to public
+  after one successful extension/relay compatibility cycle.
 - Bundle an unpacked extension for managed and development browser launch.
 - Add token-authenticated remote relay mode only if the relay must bind beyond
   trusted local interfaces.

README.md

@@ -349,8 +349,8 @@ Control returns them.
 Browser Control trusts the local agent code it executes. It is a driver, not an
 untrusted-code sandbox.
 
-The extension requires broad browser permissions, including `debugger`, `tabs`,
-`tabCapture`, and access to page content on all URLs. Attaching a user tab gives
+The extension requires broad browser permissions, including `debugger`,
+`tabCapture`, and a status content script on all URLs. Attaching a user tab gives
 Browser Control access to that tab through your existing browser profile.
 
 The relay blocks destructive browser-wide CDP commands that clear cookies,
@@ -362,7 +362,9 @@ of Node.js filesystem and network APIs.
 Current limitations:
 
 - The extension is installed unpacked; Chrome Web Store distribution is not
-  available yet.
+  available yet. The repository can produce the review artifact with
+  `pnpm package:extension`; the first Store release will begin as an unlisted
+  beta.
 - Playwright download artifacts are unavailable because Chromium blocks the
   required download commands through `chrome.debugger`. Fetch exposed response
   bytes and write them with the provided `fs` module instead.
@@ -377,8 +379,8 @@ Current limitations:
 - **Extension disconnected**: confirm the unpacked extension is enabled, then
   reload it from the browser's extensions page. The extension reconnects to a
   running relay automatically.
-- **After an npm upgrade**: reload the unpacked extension so its browser code
-  matches the newly installed CLI and relay.
+- **After an npm upgrade**: reload the unpacked extension. Extension and relay
+  versions may differ when they use the same reported protocol version.
 - **Stale relay warning**: run `browser-control doctor`, stop the old relay
   process it identifies, then rerun a relay-backed command.
 

docs/CHROME_WEB_STORE.md

@@ -0,0 +1,116 @@
+# Chrome Web Store Submission
+
+This document is the source copy for the Browser Control Chrome Web Store
+listing and review questionnaire. The initial distribution should be
+**unlisted**.
+
+## Single Purpose
+
+Connect user-authorized local browser automation programs to controlled tabs in
+the user's existing Chromium browser.
+
+## Short Description
+
+Connect controlled browser tabs to the local Browser Control driver for
+user-authorized automation.
+
+## Detailed Description
+
+When enabled, trusted local programs can read and modify controlled pages, use
+their signed-in state, create and close tabs, capture matching page network
+activity, and record a controlled tab when requested. Data is sent only to the
+Browser Control driver on this computer at `127.0.0.1:19989`; Anomaly does not
+operate a Browser Control cloud relay.
+
+Browser Control lets trusted agents and programs running on your computer
+control tabs in your existing browser. It uses a local Node driver for
+Playwright execution and a small extension adapter for Chrome debugging APIs.
+
+The extension connects only to `127.0.0.1:19989`. Browser data is not sent to a
+Browser Control cloud service. A visible page indicator identifies controlled
+tabs, and the toolbar button attaches or detaches the active tab. Human handoff
+controls keep authentication, payment confirmation, CAPTCHAs, and other
+user-presence steps with the user rather than bypassing them.
+
+Browser Control is intended for trusted local use. The extension requires the
+local `@opencode-ai/browser-control` package.
+
+## Permission Justifications
+
+- `activeTab`: grants the user-initiated tab access required by
+  `chrome.tabCapture.getMediaStreamId` when recording a toolbar-clicked tab.
+- `alarms`: wakes the Manifest V3 worker periodically so it can reconnect to a
+  local driver that starts after the browser.
+- `debugger`: provides the Chrome DevTools Protocol transport required for
+  Playwright to inspect and control user-authorized tabs.
+- `offscreen`: hosts `MediaRecorder` while recording an authorized tab because
+  a Manifest V3 service worker has no DOM media environment.
+- `tabCapture`: records a controlled user tab only after an explicit local
+  recording request.
+- `tabGroups`: groups session-owned tabs under the visible `control` group and
+  restores their prior ungrouped state when released.
+- Content script on `<all_urls>`: installs the small status and human-handoff control in controlled
+  pages across navigations and origins. It does not collect page content by
+  itself; page access occurs through explicit local driver commands.
+
+## Remote Code Declaration
+
+The extension does not download or execute remotely hosted code in the
+extension runtime. All extension JavaScript is bundled in the submitted
+Manifest V3 package. As its disclosed purpose, the extension relays local
+Chrome DevTools Protocol commands, including page-context evaluation, to tabs
+controlled by the user.
+
+## Data Use Disclosure
+
+Declare access to website content; controlled-page and captured request URLs;
+matching request and response headers and optional bodies; user activity on
+controlled pages; authentication information available to controlled pages;
+and screen or tab recordings requested by an authorized local caller. The data
+is used only to provide the extension's single purpose. It is
+not sold, used for advertising, used for credit decisions, or transferred to
+the publisher. See `docs/PRIVACY.md`.
+
+## Reviewer Instructions
+
+1. Install Node.js 20 or later.
+2. Run `npm install --global @opencode-ai/browser-control`.
+3. Install the submitted Browser Control extension.
+4. Run:
+
+   ```bash
+   browser-control execute 'await page.goto("https://example.com"); return { title: await page.title(), url: page.url() }'
+   ```
+
+5. Confirm that a controlled tab opens and the command returns `Example
+   Domain`.
+6. Open another ordinary web page and click the extension toolbar button once
+   to attach it. Click again to detach it.
+7. Run `browser-control doctor` to see local driver, extension protocol,
+   session, and target diagnostics.
+
+No account credentials are required for review. Recording is optional and
+requires a separate explicit CLI request.
+
+## Submission Artifact
+
+Store assets live under `docs/chrome-web-store/`:
+
+- `icon-128.png`
+- `small-promo-440x280.png`
+
+A 1280x800 or 640x400 product screenshot is still required before submission;
+capture it from the final Store-ID-pinned build rather than staging a mock.
+
+Run:
+
+```bash
+pnpm package:extension
+```
+
+Upload `artifacts/browser-control-extension-<version>.zip`. Record the printed
+SHA-256 digest with the release notes.
+
+Before submission, add the Store-assigned extension ID to the relay's accepted
+production extension origins while preserving an explicit source-development
+path.

docs/PRIVACY.md

@@ -0,0 +1,74 @@
+# Browser Control Extension Privacy Policy
+
+Effective July 20, 2026
+
+Browser Control is a local browser driver for user-authorized automation. This
+policy describes the Browser Control browser extension distributed by Anomaly
+and the local Browser Control driver it connects to.
+
+## Data The Extension Can Access
+
+Trusted programs using the local driver can
+control attached tabs and tabs they create. Depending on the command you run,
+that access can include:
+
+- Page URLs, titles, visible and programmatically available page content.
+- Form fields and interactions performed on controlled pages.
+- The signed-in state available to the controlled page.
+- Browser debugging events and network activity associated with controlled
+  pages, including matching cross-origin requests and responses.
+- Images or recordings of a controlled tab when an authorized local caller
+  requests them.
+
+Browser Control does not collect this data for advertising, analytics, credit
+decisions, or sale to third parties.
+
+Browser Control's use of information received from Google APIs complies with
+the Chrome Web Store User Data Policy, including the Limited Use requirements.
+
+## Local Processing
+
+The extension connects to the Browser Control driver at
+`127.0.0.1:19989` on the same computer. Browser data handled by the extension is
+sent only over this loopback connection to the local driver. Anomaly does not
+operate a Browser Control cloud relay and does not receive page contents,
+browsing history, credentials, debugging events, screenshots, or recordings.
+
+Programs and agents you authorize to call the local driver may receive data
+returned by the commands they run. Their handling of that data is governed by
+the software and services you chose to run, not by Browser Control.
+
+## Local Storage
+
+The extension does not store browsing data. The local driver stores relay state,
+session descriptors, access-restricted secret profiles, and execution journals
+under `~/.browser-control`. Journals can include agent code, bounded result
+previews, page URLs, navigations, errors, and handoff summaries. Screenshots,
+recordings, and network exports are written to the path selected by the caller.
+Disabling or removing the extension does not automatically delete these local
+files. You can delete sessions through the Browser Control CLI and remove
+user-selected artifacts normally. Local sessions, journals, captures, and
+secret profiles remain until the user deletes their corresponding files or
+Browser Control data.
+
+## Your Controls
+
+The extension visibly marks controlled tabs. Its toolbar button attaches or
+detaches the active tab, subject to safeguards for active operations. You can
+reset or delete Browser Control sessions with the local CLI. You can stop all
+extension activity by disabling or removing Browser Control from your
+browser's extensions page.
+
+## Security
+
+Browser Control is intended for trusted local use. Only enable it on a computer
+where you trust the programs and agents that can access the local driver. The
+driver rejects cross-origin browser requests, limits its listener to local
+interfaces by default, and blocks destructive browser-wide debugging commands,
+but a trusted caller controlling a tab can still read and modify that tab.
+
+## Changes And Contact
+
+Material changes to Browser Control's data handling will be reflected in this
+policy and the Chrome Web Store listing. Questions and reports can be filed at
+<https://github.com/anomalyco/browser-control/issues>.