opencode-browser-kit 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rishikesh Joshi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,96 @@
1
- # Temporary Holding Version
1
+ # opencode-browser-kit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A headless browser + visual element picker for [OpenCode](https://opencode.ai). Gives any session seven `browser_*` tools — including **`browser_inspect`**, which opens a *visible* browser window where **you click an element and type what you want changed**; the agent receives a precise selector, the element's text/HTML/styles, a React source hint, and your note, then makes the change and verifies with screenshots.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ opencode plugin opencode-browser-kit -g
9
+ ```
10
+
11
+ That's it — deps are installed automatically on next startup. Or add it manually to `opencode.json`:
12
+
13
+ ```json
14
+ {
15
+ "plugin": ["opencode-browser-kit"]
16
+ }
17
+ ```
18
+
19
+ Restart OpenCode so the tools load.
20
+
21
+ ### Browser binary
22
+
23
+ On first use the plugin tries the bundled Playwright Chromium. If missing, install it once:
24
+
25
+ ```bash
26
+ bunx playwright install chromium
27
+ ```
28
+
29
+ If that's not present, it automatically falls back to your system **Chrome**, then **Edge** — no download needed in that case.
30
+
31
+ ## Tools
32
+
33
+ | Tool | What it does |
34
+ | --- | --- |
35
+ | `browser_navigate` | Go to a URL; returns title + screenshot path |
36
+ | `browser_snapshot` | Read page text (optionally scoped by selector) |
37
+ | `browser_click` | Click by CSS / `text=` / xpath target |
38
+ | `browser_type` | Fill a field, optional Enter to submit |
39
+ | `browser_screenshot` | Viewport or full-page screenshot |
40
+ | `browser_close` | Close the browser, release resources |
41
+ | `browser_inspect` | **Interactive picker**: visible window, you hover/click an element and type the desired change → returns selector + styles + React source + your note |
42
+
43
+ ## The `/pick` command (recommended)
44
+
45
+ Add this to `~/.config/opencode/commands/pick.md` (create the folder if needed):
46
+
47
+ ```markdown
48
+ ---
49
+ description: Open the visual element picker (browser_inspect) so you can click an element and describe the change
50
+ agent: build
51
+ ---
52
+
53
+ Call the `browser_inspect` tool NOW with exactly these args:
54
+
55
+ - url: $ARGUMENTS
56
+ - timeoutSeconds: 300
57
+
58
+ If $ARGUMENTS is empty, use `http://localhost:3000` instead.
59
+
60
+ A visible browser window will open for the user to hover, click an element, and type what they want changed. WAIT for the tool to return (it can take several minutes — do not call other tools meanwhile).
61
+
62
+ When the result arrives, use the returned selector, text, classes, styles, React source hint and the user's note to:
63
+ 1. Locate the responsible component in this codebase (grep by text, class names or the React source hint).
64
+ 2. Make the requested change.
65
+ 3. Verify by calling `browser_navigate` on the same URL, then `browser_screenshot`, and view the screenshot with the read tool.
66
+ 4. Summarize what you changed, with file paths.
67
+ ```
68
+
69
+ Then in any session:
70
+
71
+ ```
72
+ /pick http://localhost:3000
73
+ ```
74
+
75
+ ## The visual-edit workflow
76
+
77
+ 1. Run your dev server (`npm run dev`)
78
+ 2. `/pick http://localhost:3000`
79
+ 3. A browser window opens — hover to outline elements, **click** the one you want changed
80
+ 4. A panel appears — **type what you want changed** (e.g. "make this heading bigger and dark") → **Apply**
81
+ 5. The agent locates the component, edits it, and shows you a verification screenshot — all inside the OpenCode session
82
+
83
+ ## Notes
84
+
85
+ - Screenshots are saved to `/tmp/opencode-browser-screenshots/` and their paths are returned so the agent can view them inline.
86
+ - Works best in projects with `data-testid` attributes; the picker prefers them for stable selectors.
87
+
88
+ ## Troubleshooting
89
+
90
+ - **"Could not install playwright"**: the plugin tries `bun add playwright` (45s cap, cache pointed at the OS tmpdir), then `npm install playwright`. If both fail, or bun's resolver hangs on a slow/network-backed home cache, install manually next to the plugin: `cd <plugin folder> && bun add playwright && bunx playwright install chromium`.
91
+ - **No bundled Chromium**: the plugin falls back to system Chrome, then Edge automatically. `bunx playwright install chromium` only matters for the bundled-browser path.
92
+ - **Plugin fails to load with "Plugin export is not a function"** (older versions, 0.1.0): the module exported a non-function. Fixed in 0.1.1 — only function exports are allowed in an opencode plugin module.
93
+
94
+ ## License
95
+
96
+ MIT