@elyracode/browser-tools 0.9.26

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.9.26] - 2026-08-07
+
+### Added
+- Initial release: browser automation via Playwright. One persistent headless tab per session with `browser_navigate`, `browser_snapshot` (accessibility-tree first — token-cheap page state), `browser_interact` (click/fill/press/select/check/hover targeted by role+name, label, text, or css), `browser_screenshot` (element/viewport/full-page with responsive viewport resize), `browser_run_tests` (Playwright suite runner), and `browser_close`. Console errors ride along with every result. Falls back to installed Google Chrome when the bundled Chromium is missing, and every failure names its fix. Ships a `browser-tools` skill and a `/browser <url>` command.

package/README.md

@@ -0,0 +1,52 @@
+# @elyracode/browser-tools
+
+Browser automation for Elyra, built on [Playwright](https://playwright.dev). The agent gets hands in a real browser: navigate, click, fill, verify — with token-cheap accessibility snapshots as the primary way of seeing, and pixel screenshots when looks matter.
+
+This completes Elyra's verification ladder: LSP auto-diagnostics check the *code*, design-tools check the *looks*, browser-tools check the *behavior*.
+
+## Install
+
+```
+elyra install npm:@elyracode/browser-tools
+npx playwright install chromium   # browser binaries (once)
+```
+
+If the bundled Chromium is missing, installed Google Chrome is used as a fallback. Every failure names its fix — nothing degrades silently.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `browser_navigate` | Open a URL; returns title, accessibility snapshot, and console errors |
+| `browser_snapshot` | Re-read the current page (optionally scoped to a css selector) |
+| `browser_interact` | click / fill / press / select / check / uncheck / hover, targeted by role+name, label, text, or css; returns the resulting page state |
+| `browser_screenshot` | Element, viewport, or full-page screenshot; optional viewport resize for responsive checks |
+| `browser_run_tests` | Run `npx playwright test` (a spec path or `--grep` filter) and summarize |
+| `browser_close` | Close the session's tab |
+
+One persistent headless tab per session: login state and SPA state survive across tool calls, so flows chain naturally. The tab closes with the session.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/browser <url>` | Open a URL and describe the page + console state |
+
+## Design notes
+
+- **Snapshot-first**: accessibility snapshots (Playwright's aria snapshot) are the primary page representation — a fraction of a screenshot's token cost, and they name every interactive element precisely for targeting.
+- **Console errors ride along** with every result, drained since the last report.
+- **Screenshots respect provider limits**: oversized captures are downscaled by Elyra core before reaching the model.
+- Interactions auto-wait (Playwright semantics) with a 10s timeout and actionable failure messages.
+
+## Example
+
+```
+> Verify note capture works end to end on https://freddy.test
+
+  browser_navigate https://freddy.test
+  browser_interact fill label="Note" value="Buy more RAM"
+  browser_interact press label="Note" value="Enter"
+  browser_snapshot -> list now contains "Buy more RAM"
+  Console: clean
+```

package/extensions/index.ts

@@ -0,0 +1,445 @@
+/**
+ * Browser automation for Elyra, built on Playwright.
+ *
+ * Design principles:
+ * - Snapshot-first: interactions read the page as an accessibility tree
+ *   (token-cheap, precise) and reach for pixel screenshots only when looks
+ *   matter. Screenshots pass through core's provider image-limit safety net.
+ * - One live browser tab per session: navigate, interact, and screenshot
+ *   share state, so flows chain naturally across tool calls.
+ * - Fail loudly: Playwright is a real dependency, but its browser binaries
+ *   are a separate install step that can be missing. Every failure names the
+ *   fix (npx playwright install chromium) instead of degrading silently.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+
+// ── Structural types for the Playwright surface we use ─────────────────────
+// (Kept minimal and structural so this file type-checks without Playwright's
+// own type packages being resolvable at extension load time.)
+
+interface PWLocator {
+	click(options?: { timeout?: number }): Promise<void>;
+	fill(value: string, options?: { timeout?: number }): Promise<void>;
+	press(key: string, options?: { timeout?: number }): Promise<void>;
+	selectOption(value: string, options?: { timeout?: number }): Promise<unknown>;
+	check(options?: { timeout?: number }): Promise<void>;
+	uncheck(options?: { timeout?: number }): Promise<void>;
+	hover(options?: { timeout?: number }): Promise<void>;
+	ariaSnapshot(): Promise<string>;
+	screenshot(options?: { timeout?: number }): Promise<Buffer>;
+	first(): PWLocator;
+}
+
+interface PWConsoleMessage {
+	type(): string;
+	text(): string;
+}
+
+interface PWPage {
+	goto(url: string, options?: { waitUntil?: string; timeout?: number }): Promise<unknown>;
+	title(): Promise<string>;
+	url(): string;
+	locator(selector: string): PWLocator;
+	getByRole(role: string, options?: { name?: string; exact?: boolean }): PWLocator;
+	getByText(text: string, options?: { exact?: boolean }): PWLocator;
+	getByLabel(text: string, options?: { exact?: boolean }): PWLocator;
+	screenshot(options?: { fullPage?: boolean; timeout?: number }): Promise<Buffer>;
+	setViewportSize(size: { width: number; height: number }): Promise<void>;
+	waitForLoadState(state?: string, options?: { timeout?: number }): Promise<void>;
+	on(event: "console", handler: (message: PWConsoleMessage) => void): void;
+	on(event: "pageerror", handler: (error: Error) => void): void;
+}
+
+interface PWContext {
+	newPage(): Promise<PWPage>;
+	close(): Promise<void>;
+}
+
+interface PWBrowser {
+	newContext(options?: { viewport?: { width: number; height: number } }): Promise<PWContext>;
+	close(): Promise<void>;
+}
+
+interface PWBrowserType {
+	launch(options?: { headless?: boolean; channel?: string }): Promise<PWBrowser>;
+}
+
+interface PlaywrightModule {
+	chromium: PWBrowserType;
+}
+
+// ── Module state ────────────────────────────────────────────────────────────
+
+const require = createRequire(import.meta.url);
+
+let playwright: PlaywrightModule | null | undefined;
+let browser: PWBrowser | null = null;
+let context: PWContext | null = null;
+let page: PWPage | null = null;
+let consoleBuffer: string[] = [];
+
+const SNAPSHOT_MAX_CHARS = 6000;
+const DEFAULT_ACTION_TIMEOUT = 10_000;
+
+function loadPlaywright(): PlaywrightModule | null {
+	if (playwright !== undefined) return playwright;
+	try {
+		playwright = require("playwright") as PlaywrightModule;
+	} catch {
+		playwright = null;
+	}
+	return playwright;
+}
+
+const MISSING_MODULE =
+	"Playwright is not installed alongside @elyracode/browser-tools. Reinstall the extension: elyra install npm:@elyracode/browser-tools";
+
+const MISSING_BROWSER =
+	"Playwright is installed but no browser binary is available. Run: npx playwright install chromium " +
+	"(or install Google Chrome, which is used as a fallback).";
+
+async function ensurePage(): Promise<{ page: PWPage } | { error: string }> {
+	const pw = loadPlaywright();
+	if (!pw) return { error: MISSING_MODULE };
+
+	if (page) return { page };
+
+	let launched: PWBrowser | null = null;
+	try {
+		launched = await pw.chromium.launch({ headless: true });
+	} catch {
+		// Bundled Chromium missing - try the user's Google Chrome.
+		try {
+			launched = await pw.chromium.launch({ headless: true, channel: "chrome" });
+		} catch {
+			return { error: MISSING_BROWSER };
+		}
+	}
+
+	browser = launched;
+	context = await launched.newContext({ viewport: { width: 1280, height: 900 } });
+	const newPage = await context.newPage();
+	newPage.on("console", (message) => {
+		const kind = message.type();
+		if (kind === "error" || kind === "warning") consoleBuffer.push(`${kind}: ${message.text()}`);
+	});
+	newPage.on("pageerror", (error) => consoleBuffer.push(`pageerror: ${error.message}`));
+	page = newPage;
+	return { page: newPage };
+}
+
+async function closeBrowser(): Promise<void> {
+	try {
+		await context?.close();
+		await browser?.close();
+	} catch {
+		// Best-effort cleanup.
+	}
+	page = null;
+	context = null;
+	browser = null;
+	consoleBuffer = [];
+}
+
+/** Drain console errors/warnings collected since the last report. */
+function drainConsole(): string {
+	if (consoleBuffer.length === 0) return "Console: clean";
+	const lines = consoleBuffer.slice(-20);
+	const overflow = consoleBuffer.length > 20 ? ` (+${consoleBuffer.length - 20} earlier)` : "";
+	consoleBuffer = [];
+	return `Console${overflow}:\n${lines.map((l) => `  ${l}`).join("\n")}`;
+}
+
+async function snapshotOf(target: PWPage): Promise<string> {
+	try {
+		const snapshot = await target.locator("body").ariaSnapshot();
+		if (snapshot.length > SNAPSHOT_MAX_CHARS) {
+			return `${snapshot.slice(0, SNAPSHOT_MAX_CHARS)}\n... (snapshot truncated at ${SNAPSHOT_MAX_CHARS} chars; use browser_snapshot with a css scope to narrow)`;
+		}
+		return snapshot || "(empty page)";
+	} catch (error) {
+		return `(could not snapshot: ${error instanceof Error ? error.message : String(error)})`;
+	}
+}
+
+function ok(text: string) {
+	return { content: [{ type: "text" as const, text }], details: {} };
+}
+
+function err(text: string) {
+	return { content: [{ type: "text" as const, text }], details: {}, isError: true as const };
+}
+
+interface Target {
+	role?: string;
+	name?: string;
+	text?: string;
+	label?: string;
+	css?: string;
+}
+
+function resolveTarget(current: PWPage, target: Target): PWLocator | null {
+	if (target.css) return current.locator(target.css).first();
+	if (target.role) return current.getByRole(target.role, target.name ? { name: target.name } : undefined).first();
+	if (target.label) return current.getByLabel(target.label).first();
+	if (target.text) return current.getByText(target.text).first();
+	return null;
+}
+
+function describeTarget(target: Target): string {
+	if (target.css) return `css=${target.css}`;
+	if (target.role) return `role=${target.role}${target.name ? ` name="${target.name}"` : ""}`;
+	if (target.label) return `label="${target.label}"`;
+	if (target.text) return `text="${target.text}"`;
+	return "(no target)";
+}
+
+// ── Extension ───────────────────────────────────────────────────────────────
+
+export default function (elyra: ExtensionAPI): void {
+	// ── Tool: browser_navigate ──
+	elyra.registerTool({
+		name: "browser_navigate",
+		label: "Browser: Navigate",
+		description:
+			"Open a URL in the session's headless browser and return the page as an accessibility snapshot " +
+			"(roles, names, states - far cheaper than a screenshot and precise enough to interact against), " +
+			"plus any console errors. The tab persists: later browser_interact / browser_screenshot calls " +
+			"continue from here. Works with localhost and .test dev URLs.",
+		parameters: Type.Object({
+			url: Type.String({ description: "The URL to open" }),
+			wait_until: Type.Optional(
+				Type.Union([Type.Literal("load"), Type.Literal("domcontentloaded"), Type.Literal("networkidle")], {
+					description: "When navigation counts as done (default: load)",
+				}),
+			),
+		}),
+		execute: async (_id, params) => {
+			const result = await ensurePage();
+			if ("error" in result) return err(result.error);
+			try {
+				await result.page.goto(params.url, { waitUntil: params.wait_until ?? "load", timeout: 30_000 });
+			} catch (error) {
+				return err(`Navigation failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			const title = await result.page.title();
+			const snapshot = await snapshotOf(result.page);
+			return ok(`# ${title}\nURL: ${result.page.url()}\n\n${snapshot}\n\n${drainConsole()}`);
+		},
+	});
+
+	// ── Tool: browser_snapshot ──
+	elyra.registerTool({
+		name: "browser_snapshot",
+		label: "Browser: Snapshot",
+		description:
+			"Re-read the current page as an accessibility snapshot without navigating - use after the page " +
+			"changed on its own (SPA updates, timers) or to scope into part of a large page with a css selector.",
+		parameters: Type.Object({
+			css: Type.Optional(Type.String({ description: "Scope the snapshot to this selector (e.g. 'main', '#results')" })),
+		}),
+		execute: async (_id, params) => {
+			if (!page) return err("No page is open. Use browser_navigate first.");
+			try {
+				if (params.css) {
+					const scoped = await page.locator(params.css).first().ariaSnapshot();
+					const clipped =
+						scoped.length > SNAPSHOT_MAX_CHARS ? `${scoped.slice(0, SNAPSHOT_MAX_CHARS)}\n... (truncated)` : scoped;
+					return ok(`${clipped || "(empty)"}\n\n${drainConsole()}`);
+				}
+				const snapshot = await snapshotOf(page);
+				return ok(`URL: ${page.url()}\n\n${snapshot}\n\n${drainConsole()}`);
+			} catch (error) {
+				return err(`Snapshot failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		},
+	});
+
+	// ── Tool: browser_interact ──
+	elyra.registerTool({
+		name: "browser_interact",
+		label: "Browser: Interact",
+		description:
+			"Act on the current page: click, fill, press, select, check, uncheck, or hover. Target elements " +
+			"the way the accessibility snapshot names them - role+name is the most robust (role='button', " +
+			"name='Save'), or label for form fields, text for links, css as the escape hatch. Returns the " +
+			"page state after the action so the effect is visible immediately.",
+		parameters: Type.Object({
+			action: Type.Union([
+				Type.Literal("click"),
+				Type.Literal("fill"),
+				Type.Literal("press"),
+				Type.Literal("select"),
+				Type.Literal("check"),
+				Type.Literal("uncheck"),
+				Type.Literal("hover"),
+			]),
+			role: Type.Optional(Type.String({ description: "ARIA role, e.g. 'button', 'textbox', 'link'" })),
+			name: Type.Optional(Type.String({ description: "Accessible name to match with role" })),
+			label: Type.Optional(Type.String({ description: "Form field label" })),
+			text: Type.Optional(Type.String({ description: "Visible text (links, buttons)" })),
+			css: Type.Optional(Type.String({ description: "CSS selector (escape hatch)" })),
+			value: Type.Optional(Type.String({ description: "For fill/select: the value. For press: the key (e.g. 'Enter')" })),
+		}),
+		execute: async (_id, params) => {
+			if (!page) return err("No page is open. Use browser_navigate first.");
+			const locator = resolveTarget(page, params);
+			if (!locator) return err("No target given. Provide role(+name), label, text, or css.");
+			const timeout = DEFAULT_ACTION_TIMEOUT;
+			try {
+				switch (params.action) {
+					case "click":
+						await locator.click({ timeout });
+						break;
+					case "fill":
+						if (params.value == null) return err("'fill' needs a value.");
+						await locator.fill(params.value, { timeout });
+						break;
+					case "press":
+						if (!params.value) return err("'press' needs a key in value (e.g. 'Enter').");
+						await locator.press(params.value, { timeout });
+						break;
+					case "select":
+						if (params.value == null) return err("'select' needs a value.");
+						await locator.selectOption(params.value, { timeout });
+						break;
+					case "check":
+						await locator.check({ timeout });
+						break;
+					case "uncheck":
+						await locator.uncheck({ timeout });
+						break;
+					case "hover":
+						await locator.hover({ timeout });
+						break;
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message.split("\n")[0] : String(error);
+				return err(
+					`${params.action} on ${describeTarget(params)} failed: ${message} ` +
+						"(take a browser_snapshot to see what the page actually offers)",
+				);
+			}
+			try {
+				await page.waitForLoadState("load", { timeout: 5_000 });
+			} catch {
+				// SPAs may never fire another load; the snapshot below shows reality.
+			}
+			const snapshot = await snapshotOf(page);
+			return ok(
+				`Did ${params.action} on ${describeTarget(params)}.\nURL now: ${page.url()}\n\n${snapshot}\n\n${drainConsole()}`,
+			);
+		},
+	});
+
+	// ── Tool: browser_screenshot ──
+	elyra.registerTool({
+		name: "browser_screenshot",
+		label: "Browser: Screenshot",
+		description:
+			"Take a pixel screenshot of the current page (or one element) for visual judgement - layout, " +
+			"spacing, contrast. Use snapshots for behavior and structure; screenshots for looks. Optionally " +
+			"resize the viewport first to test responsive layouts (e.g. 390x844 for phone).",
+		parameters: Type.Object({
+			css: Type.Optional(Type.String({ description: "Screenshot only this element" })),
+			full_page: Type.Optional(Type.Boolean({ description: "Capture the full scroll height" })),
+			width: Type.Optional(Type.Number({ description: "Viewport width to set first" })),
+			height: Type.Optional(Type.Number({ description: "Viewport height to set first" })),
+		}),
+		execute: async (_id, params) => {
+			if (!page) return err("No page is open. Use browser_navigate first.");
+			try {
+				if (params.width && params.height) {
+					await page.setViewportSize({ width: params.width, height: params.height });
+					await page.waitForLoadState("load", { timeout: 3_000 }).catch(() => undefined);
+				}
+				const buffer = params.css
+					? await page.locator(params.css).first().screenshot({ timeout: DEFAULT_ACTION_TIMEOUT })
+					: await page.screenshot({ fullPage: params.full_page ?? false, timeout: DEFAULT_ACTION_TIMEOUT });
+
+				const dir = join(tmpdir(), "elyra-browser-tools");
+				mkdirSync(dir, { recursive: true });
+				const filePath = join(dir, `shot-${randomUUID()}.png`);
+				writeFileSync(filePath, buffer);
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Screenshot captured (${params.css ? `element ${params.css}` : params.full_page ? "full page" : "viewport"}): ${filePath}\n${drainConsole()}`,
+						},
+						{ type: "image" as const, data: buffer.toString("base64"), mimeType: "image/png" },
+					],
+					details: {},
+				};
+			} catch (error) {
+				return err(`Screenshot failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		},
+	});
+
+	// ── Tool: browser_run_tests ──
+	elyra.registerTool({
+		name: "browser_run_tests",
+		label: "Browser: Run Playwright Tests",
+		description:
+			"Run the project's Playwright test suite (npx playwright test) and return a concise result. " +
+			"Pass a path to run one spec, or grep to filter by title. Failures include the error lines; " +
+			"traces are kept where Playwright's config puts them.",
+		parameters: Type.Object({
+			path: Type.Optional(Type.String({ description: "A spec file or directory to run" })),
+			grep: Type.Optional(Type.String({ description: "Only run tests matching this title" })),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const args = ["playwright", "test", "--reporter=line"];
+			if (params.path) args.push(params.path);
+			if (params.grep) args.push("--grep", params.grep);
+			const result = await elyra.exec("npx", args, { cwd: ctx.cwd, timeout: 300_000 });
+			const output = `${result.stdout}\n${result.stderr}`.trim();
+			const lines = output.split("\n");
+			const tail = lines.length > 60 ? `...\n${lines.slice(-60).join("\n")}` : output;
+			if (result.code === 0) {
+				return ok(`Playwright tests passed.\n\n${tail}`);
+			}
+			return err(`Playwright tests failed (exit ${result.code}).\n\n${tail}`);
+		},
+	});
+
+	// ── Tool: browser_close ──
+	elyra.registerTool({
+		name: "browser_close",
+		label: "Browser: Close",
+		description: "Close the session's browser tab and free the browser. A later browser_navigate starts fresh.",
+		parameters: Type.Object({}),
+		execute: async () => {
+			if (!browser) return ok("No browser was open.");
+			await closeBrowser();
+			return ok("Browser closed.");
+		},
+	});
+
+	// ── Command: /browser ──
+	elyra.registerCommand("browser", {
+		description: "Open a URL in the agent's browser: /browser <url>",
+		handler: async (args, ctx) => {
+			const url = args.trim();
+			if (!url) {
+				ctx.ui.notify("Usage: /browser <url> \u2014 e.g. /browser https://freddy.test", "error");
+				return;
+			}
+			elyra.sendUserMessage(`Open ${url} with browser_navigate and describe what the page shows and whether the console is clean.`);
+		},
+	});
+
+	// ── Cleanup ──
+	elyra.on("session_shutdown", async () => {
+		await closeBrowser();
+	});
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@elyracode/browser-tools",
+  "version": "0.9.26",
+  "description": "Browser automation for Elyra via Playwright - the agent navigates, clicks, fills, and verifies behavior, with token-cheap accessibility snapshots and screenshots",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "playwright",
+    "browser",
+    "e2e",
+    "testing"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/browser-tools"
+  },
+  "elyra": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "dependencies": {
+    "playwright": "^1.62.1"
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/browser-tools/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: browser-tools
+description: Browser automation via Playwright. Use when the user asks to test UI behavior in a real browser, verify a flow works (forms, navigation, login), reproduce a frontend bug, check responsive layouts, or run Playwright e2e tests.
+---
+
+# Browser Tools
+
+The agent's hands in a real browser: one persistent headless tab per session, driven through accessibility snapshots.
+
+## When to Use
+
+- Verifying behavior after building UI: does the form actually submit? Does the search return results?
+- Reproducing a reported frontend bug step by step
+- Checking responsive layouts at phone/tablet widths
+- Running or debugging Playwright e2e specs
+- Reading console errors that only appear on interaction
+
+## Available Tools
+
+| Tool | Use for |
+|------|---------|
+| `browser_navigate` | Open a URL; returns title + accessibility snapshot + console errors |
+| `browser_snapshot` | Re-read the page (or a css-scoped part) without navigating |
+| `browser_interact` | click / fill / press / select / check / uncheck / hover |
+| `browser_screenshot` | Pixel screenshot (element, viewport, or full page; optional viewport resize) |
+| `browser_run_tests` | Run `npx playwright test`, optionally one spec or a title grep |
+| `browser_close` | Close the tab; next navigate starts fresh |
+
+## Snapshot-First Discipline
+
+**Snapshots for behavior, screenshots for looks.** An accessibility snapshot costs a fraction of a screenshot's tokens and names every interactive element precisely. Only take a screenshot when visual judgement matters (spacing, contrast, layout) — and consider `design_diff` from design-tools for before/after comparisons.
+
+## Targeting Elements
+
+Prefer, in order:
+1. `role` + `name` — `role=button, name=Save` (most robust, matches what the snapshot shows)
+2. `label` — form fields by their label
+3. `text` — links and buttons by visible text
+4. `css` — escape hatch when the page lacks semantics (and consider flagging the missing semantics as an accessibility finding)
+
+If an interaction fails, take a `browser_snapshot` first — the page may not offer what you assumed.
+
+## A Verification Flow
+
+```
+browser_navigate https://freddy.test
+browser_interact fill label="Note" value="Try the swarm on search"
+browser_interact press label="Note" value="Enter"
+browser_snapshot            # is the note in the list?
+browser_screenshot          # only if looks matter
+```
+
+## Responsive Checks
+
+`browser_screenshot` with `width`/`height` resizes the viewport first: 390x844 (phone), 768x1024 (tablet), 1440x900 (desktop). Snapshot again after resizing if behavior (menus collapsing) is the question.
+
+## Setup and Failure Modes
+
+- The package depends on Playwright; browser binaries are a separate step: `npx playwright install chromium`. Google Chrome is used as a fallback when the bundled Chromium is missing.
+- The session keeps one tab: state (login, SPA state) persists across tool calls until `browser_close`.
+- The dev server must be running — the agent must NOT start long-running dev servers itself; ask the user.
+
+## Console Errors Ride Along
+
+Every navigate/interact/snapshot reports console errors and warnings collected since the last report. A visible bug is often a JS error — read them.