Add Browser Context runtime consumer

README.md

@@ -1,13 +1,23 @@
 # bb plugins
 
-Seven bb plugins I use for product design work, kept together with the few build and repository tools they share. [![CI](https://github.com/brsbl/bb-plugins/actions/workflows/ci.yml/badge.svg)](https://github.com/brsbl/bb-plugins/actions/workflows/ci.yml)
+Eight bb plugins I use for product design work, kept together with the few build and repository tools they share. [![CI](https://github.com/brsbl/bb-plugins/actions/workflows/ci.yml/badge.svg)](https://github.com/brsbl/bb-plugins/actions/workflows/ci.yml)
 
 [bb](https://getbb.app) is an agentic IDE for running coding agents across projects, threads, and environments. Its plugins can add UI, commands, skills, and server capabilities; this repository is where I build and maintain mine.
 
 ## Plugins
 
 Each plugin has its own workspace under `plugins/` and a short README with the story behind it.
 
+### Browser Context
+
+Selects and annotates elements or regions in BB's Browser, stages inspectable context mentions, and gives agents an explicit user-visible control mode for the exact tab.
+
+![Browser Context selection and agent-control actions in bb](plugins/browser-context/docs/screenshot.png)
+
+[Source](plugins/browser-context) · [README](plugins/browser-context/README.md)
+
+Install: `bb plugin install git:https://github.com/brsbl/bb-plugins.git@plugin/browser-context --yes`
+
 ### Design Doctrine
 
 Turns recurring product-design feedback into a searchable rule library that agents can apply while designing, building, and critiquing. Its maintenance workflow keeps the rules grounded in real review evidence.

plugins/browser-context/README.md

@@ -0,0 +1,27 @@
+# Browser Context
+
+Select elements or drag over regions in BB's Browser, annotate the numbered captures, then add the batch to the current thread composer. A separate agent-control action lets the user or agent visibly enable control of one exact Browser tab.
+
+![Inspectable Browser Context mention in bb](docs/screenshot.png)
+
+## Install
+
+```bash
+bb plugin install git:https://github.com/brsbl/bb-plugins.git@plugin/browser-context --yes
+```
+
+## Use
+
+Open a Browser tab and click the Browser Context action to enter selection mode. Click an element or drag over a region, add an optional comment, and click the same Browser toolbar action again to build a numbered batch. Hover or focus a staged row to return its target to the live preview, edit any comment in place, or remove one selection without affecting the rest. Choose **Send to agent** once to preserve the existing draft and append one inspectable mention pill followed by its ordinary editable comment for every selection. Activate a pill to reopen its capture preview and exact metadata. Screenshots remain preview-only and are never sent; immutable DOM, React, accessibility, and geometry metadata resolves into hidden agent context at send time. The standard Send or Queue flow remains in control.
+
+Click the AI Browser action to let the current thread's agent control that exact client, window, tab, and navigation epoch. The visible Browser frame marks the active mode; clicking the action again exits it. Navigation changes the target epoch, so stale control requests cannot silently move to a different page.
+
+## Develop
+
+From the monorepo root:
+
+```bash
+npm ci
+npm run check --workspace=bb-plugin-browser-context
+bb plugin install "path:$PWD/plugins/browser-context" --yes
+```

plugins/browser-context/app-registration.test.ts

@@ -0,0 +1,30 @@
+// @vitest-environment jsdom
+
+import { installTestPluginRuntime } from "@get-bb/plugin-sdk/testing/app";
+import { describe, expect, it, vi } from "vitest";
+
+describe("Browser Context registration", () => {
+  it("registers on current hosts and remains inert on older hosts", async () => {
+    installTestPluginRuntime();
+    const { registerBrowserContextApp } = await import("./app.js");
+    const register = vi.fn();
+
+    registerBrowserContextApp({ experimental_browserAction: register });
+    expect(register).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "agent-control",
+        title: "Agent control",
+        component: expect.any(Function),
+      }),
+    );
+    expect(register).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "capture",
+        title: "Select page context",
+        component: expect.any(Function),
+      }),
+    );
+    expect(register).toHaveBeenCalledTimes(2);
+    expect(() => registerBrowserContextApp({})).not.toThrow();
+  });
+});