🌐 Browser (structupath.browser)

Supporting visibility capability. Browser lets you launch Chrome or Chromium inside a Herdr pane, attach to an existing automation browser, or share a coding agent's agent-browser session. Choose the connection that matches your workflow; agent-browser is required for shared sessions, recording, and standalone repeatable QA.

Repo: StructuPath/herdr-browser · Detailed reference: the repo README

Pinned evidence

The pinned source includes explicit tab selection, target-loss handling, verbatim text insertion, and standalone repeatable QA. The manifest version remains 0.8.0; the commit identifies the exact implementation behind this guide.

An isolated Herdr 0.9.3/protocol 22 registration exposed all five Browser actions; installed Open created a pane successfully. The standalone Browser QA live fixture passed 14/14 checks, and the real-browser integration command passed Chromium launch and tab/paste scenarios but failed its screencast case: the stream delivered status/tab/navigation events without an image, then the viewer fell back to polling. This is not a passing full streaming compatibility result; retain the published tested-version claim until that failure is diagnosed and rerun. No default server or plugin installation was changed by this isolated test.

Choose a browser connection

q closes the viewer. The plugin's Close action also ends the workspace agent-browser session, so it has a broader effect than quitting an externally attached viewer.

First run: local Chromium

With Herdr, Node 22+, and Chrome or Chromium installed:

herdr plugin install StructuPath/herdr-browser
herdr plugin action invoke structupath.browser.open

1. Press l in the pane to launch a browser.
2. Press u, enter your development URL (for example http://localhost:3000), and press Enter.
3. Click the page, use i to enter or paste text, or press o to stop forwarding pane input while you watch.
4. Press q when finished. The browser launched by this pane closes.

The launcher probes common Chrome/Chromium executables and macOS app bundles. If it cannot find yours, set HERDR_BROWSER_CHROMIUM to its executable path in the pane's environment or write the path to the plugin's chromium config file. Set HERDR_BROWSER_LAUNCH=1 (or the launch config file to 1) to launch automatically on open. A configured CDP endpoint takes precedence over launch mode.

No extra bundled Chromium build is needed when a supported browser is already installed. The launched browser uses a persistent per-workspace profile under plugin state.

Actions

Share a coding agent's session

npm install -g agent-browser
agent-browser install
herdr plugin action invoke structupath.browser.open

Start agent-browser with the exact session shown in the pane header. Replace the example session below with that name:

agent-browser --session herdr-ws-w123456 open http://localhost:3000

A modified click on a localhost URL in Herdr can route it to the workspace browser. The link handler accepts only HTTP(S) localhost, 127.0.0.1, or [::1] URLs.

The viewer inherits daemon settings unchanged. If you explicitly configure AGENT_BROWSER_IDLE_TIMEOUT_MS, use the same value for the agent and pane: changing daemon configuration can restart the session.

Attach and observe

Press a and enter an existing browser's CDP endpoint, such as http://127.0.0.1:9222. Your automation client must expose that endpoint first; a browser using only a pipe transport cannot be reached by port. To attach on pane startup, set HERDR_BROWSER_CDP_URL or the plugin's cdp-url config file.

The pane does not create or close external targets or override their viewport. t opens a tab picker. Its console feed is observable by the page, so attachment is not a stealth or zero-footprint operation. Use a local HTTP endpoint or a verified browser WebSocket URL; HTTPS discovery is a known follow-up in the pinned implementation.

For a workspace dedicated to watching an agent, set HERDR_BROWSER_OBSERVE=1 or write 1 to the observe config file before opening the pane. This blocks pane input and link-triggered navigation. The runtime o toggle blocks pane input, but in agent-browser mode a modified link click can navigate through the launcher outside the pane. Observe-only is an interaction setting, not an access-control boundary.

Choose a tab

In attach and local launch modes, press t to list tabs by title and URL. Use the arrow keys or j/k to highlight a tab, then Enter to select it. Press t again to refresh the list or Esc to cancel. Selection uses a stable tab identity, so duplicate titles and changes to the list order do not redirect your choice.

On the first connection, a single available tab is selected automatically. With multiple tabs, page input waits for an explicit selection. The picker changes this pane's view without activating the tab in another client's UI, and it remains available in observe-only mode. Shared agent-browser mode continues following that session's active tab.

If the selected tab closes or detaches, Browser clears the cached image and pending text, drops queued input, and keeps the browser connection open. It does not switch to a surviving tab automatically. Press t to select another tab, even if only one remains. Reconnection restores a selection only when both the browser identity and tab identity still match.

Paste text verbatim

1. Click the page field you want to edit.
2. Press i and type or paste text into the pane's text prompt.
3. Review the preview, then press Enter to insert the text or Esc to cancel.

The prompt preserves leading and trailing spaces, Unicode, tabs, and newlines. Multiline paste requires a terminal that supports bracketed paste; pasted newlines appear as \n in the preview and remain text until you confirm insertion. Enter confirms insertion into the focused page field; it does not send an Enter key to the page or submit a form. The page field's own editing rules still apply.

Each paste is limited to 1 MiB. Paste outside a prompt is ignored, and pasted text is never interpreted as pane shortcuts. URL and endpoint prompts still trim whitespace. Verbatim insertion is available in shared agent-browser sessions as well as attach/launch mode.

Requirements and rendering

• Herdr >= 0.7.0; the pinned README records testing with 0.7.4.
• Node.js >= 20 for shared-session polling; Node 22+ enables streaming, CDP attach, and local Chromium launch.
• Chrome/Chromium is required for local launch; agent-browser plus its engine is required for shared sessions and recording.
• chafa and carbonyl@next are optional rendering/browse dependencies.

# Optional ANSI image rendering on macOS
brew install chafa

The viewer selects Kitty graphics, ANSI symbols through chafa, or text-only mode. Chafa is needed for streamed JPEGs in Kitty mode. Shared sessions fall back to screenshot polling if streaming is unavailable, disconnects, or sends no usable image within five seconds. That startup fallback does not guarantee recovery from every later stream stall.

Recording and session privacy

Recording actions support agent-browser sessions only. They refuse in direct attach/launch mode rather than recording an unrelated browser. Starting a recording creates a fresh browser context and reloads the page while preserving cookies and localStorage; start before the flow you want to capture.

Each recording produces a run-scoped bundle under <plugin state>/runs/run-<run-id>/browser/, containing recording.webm and evidence.json. A successful Stop records the WebM's size and SHA-256. This is an unreviewed observation, not proof that a test passed or a reviewer accepted the result. Interrupted or ambiguous stops require inspection; they are not marked complete automatically.

The default shared session is herdr-ws-<workspace-id>. Sessions and persistent launch profiles are trusted local state: same-user processes can access them. Recordings remain in plugin state and may contain sensitive content. Quitting the pane does not delete recordings or the local Chromium profile.

Viewer controls

Repeatable desktop and mobile QA

The standalone QA runner executes a saved scenario in a fresh, private agent-browser session. It needs Node.js 20 or newer, Git with a committed SHA-1 HEAD, and agent-browser 0.33.0 or newer with Chromium installed; it does not require a running Herdr server. Install the browser dependency with npm install -g agent-browser and agent-browser install. See the pinned QA contract for complete step fields, bounds, and failure handling.

Save and commit a scenario such as .herdr-browser-qa.json in the project you are testing:

{
  "schemaVersion": 1,
  "name": "Home page smoke",
  "baseUrl": "http://127.0.0.1:3000",
  "viewports": [
    {"name": "desktop", "width": 1440, "height": 900},
    {"name": "mobile", "width": 390, "height": 844}
  ],
  "steps": [
    {"type": "navigate", "path": "/"},
    {"type": "assertVisible", "selector": "h1"},
    {"type": "assertText", "selector": "h1", "contains": "Welcome"},
    {"type": "screenshot", "name": "home"}
  ]
}

Replace the heading assertion with text your app must show. Build and serve the intended candidate yourself, then run from a trusted Browser checkout:

node bin/qa.mjs check --config /project/.herdr-browser-qa.json
node bin/qa.mjs run --config /project/.herdr-browser-qa.json \
  --repo /project --output /private/new-qa-run \
  --base-url http://127.0.0.1:3000 --json

The output directory must be new, outside the tested repository, with an existing parent. Omitting --output creates a private temporary directory. check validates the scenario without running a browser. run emits result.json, screenshots, and bounded diagnostics. It closes its own session and does not reuse your shared session or profile.

Scenarios support navigate, click, fill, waitFor, assertText, assertVisible, assertUrl, assertTitle, and screenshot; they do not accept arbitrary JavaScript or shell commands. Configure 1–4 named viewports and 1–40 steps. Mobile means viewport geometry, not touch, user-agent, or physical-device emulation.

The top-level failOnConsoleError, failOnPageError, and failOnFailedRequest options default to true. Results record these choices in scenario.policy. Disabling one relaxes the test: Console labels the policy as relaxed, and Swarm's direct QA evidence import requires all three enabled.

The result has schemaVersion: 1, kind: "herdr-browser-qa", overall status, Git commit/branch/dirty state and changedDuringRun, summary counts, and per-viewport runs. Assertions, console errors, page errors, and failed requests provide evidence for the configured scenario. They do not certify untested behavior, accessibility, security, or production readiness. A recorded Git commit does not prove the served app was built from that commit. A dirty tree or changes during the run weaken the association with the candidate.

Review private screenshots and diagnostics before sharing them. Console can read the explicit result.json path and compare its recorded Git identity with the project. Swarm can include a bounded validation summary in an operator-requested draft PR handoff; evidence never approves or merges a candidate automatically.

Troubleshooting and development checks

• No Chromium found: install Chrome/Chromium or configure its executable path.
• Waiting for a session: press l, attach with a, or start the exact agent-browser session in the header.
• Text-only pane: install chafa or configure a compatible terminal for Kitty graphics.
• Attach cannot connect: confirm the automation browser exposes a CDP endpoint and that Node 22+ is available to the pane.
• Selected tab closed or detached: press t, refresh if needed, and explicitly select another tab before sending input.
• Pasted newlines do not stay in the prompt: check that the terminal forwards bracketed paste; always open the i prompt first.
• A linked plugin still shows old behavior: close and reopen its pane after updating the checkout.

From a herdr-browser checkout, run:

npm run doctor
npm run build
npm run validate
npm run test:integration

Doctor checks prerequisites without launching browsers or contacting endpoints; it does not verify engine downloads, Herdr's version, or endpoint reachability. The integration command requires Node 22+, local Chromium, and agent-browser with its engine installed, and fails rather than skipping missing browser prerequisites. See the pinned readiness assessment for remaining recommendations.