Browser Grounding Agent

The Browser Grounding Agent (atelier-browser-grounding) is an internal subagent used by Explore for feature-demo walkthroughs and by Verify for UI verification.

Do not invoke it directly. Atelier calls it when a parent skill needs browser-backed evidence from a locally running web application.

When it is used

• Explore is creating a feature-demo walkthrough that should include screenshots
• Verify needs UI evidence for acceptance criteria that affect the interface
• A skill has a demo plan with visible user actions and expected DOM signals
• The evidence should include screenshots, DOM summaries, console warnings, and settled state

Input

The agent receives a demo request with:

• app_url — Local URL where the app is available.
• start_command — Optional shell command used to start the app if the URL is not already responding.
• screenshot_dir — Workspace-relative directory where PNG screenshots should be written.
• demo_plan — Ordered natural-language steps, each with an id, action, and expected DOM signal.

What it does

1. Starts or checks the app — Runs the start command when provided, then polls the app URL for a successful response.
2. Opens a fresh browser tab — Navigates Chrome to the app and captures an initial load state.
3. Performs each step — Locates targets, clicks, types, or navigates according to the demo plan.
4. Waits for settling — Checks for the expected DOM signal before capturing evidence.
5. Captures screenshots — Writes viewport screenshots into the requested screenshot directory.
6. Returns a manifest — Reports the URL, action, screenshot path, DOM summary, console warnings, and settled status for each step.

Output

The parent skill receives a markdown manifest with one block per demo step:

• Step — The demo step ID, or s0 for the initial page load.
• URL — The current browser URL after the action.
• Action — The user-visible action performed.
• Screenshot — Workspace-relative PNG path, or null if capture failed.
• DOM summary — A short post-action summary of the relevant page state.
• Console warnings — A concise summary of warning or error messages.
• Settled — Whether the expected signal matched before the wait window ended.

If the app cannot start or the first navigation fails, the agent returns a single failure block so the parent skill can fall back to a non-demo walkthrough.

Quality standards

The agent keeps runs bounded and deterministic: it waits for expected signals, captures viewport screenshots only, summarizes DOM state instead of pasting full page output, and stops any dev server it started.