gsd-browser

<essential_principles> **The daemon auto-starts.** Never run `gsd-browser daemon start`. It launches on first command. Only use `daemon stop` to clean up when finished. **Always re-snapshot after page changes.** Refs are versioned (`@v1:e1`, `@v2:e3`). After navigation, form submission, or dynamic content loading, old refs are stale. Run `gsd-browser snapshot` to get fresh refs before interacting. **Use `--json` when parsing output.** Use text mode when reading output yourself. Use `--json` when you need to extract values programmatically. **Positional args have no flag prefix.** Commands like `click`, `type`, `hover` take positional args. Do NOT add `--selector`: - `gsd-browser click "button.submit"` (correct) - `gsd-browser click --selector "button.submit"` (WRONG) **Core workflow pattern:** Every browser automation follows: navigate -> snapshot -> interact -> re-snapshot (after DOM changes). ```bash gsd-browser navigate https://example.com gsd-browser snapshot # Read snapshot output: @v1:e1 [input type="email"], @v1:e2 [button] "Submit" gsd-browser fill-ref @v1:e1 "user@example.com" gsd-browser click-ref @v1:e2 gsd-browser wait-for --condition network_idle gsd-browser snapshot # REQUIRED - old refs are now stale ``` **Command chaining:** Use `&&` when you don't need intermediate output. Run separately when you need to parse output first (e.g., snapshot to discover refs, then interact). **Global options** available on all commands: | Flag | Purpose | | ----------------------- | ------------------------------------ | | `--json` | Structured JSON output | | `--browser-path <path>` | Path to Chrome/Chromium | | `--session <name>` | Named session for parallel instances | </essential_principles> <routing> Based on what the user needs, read the appropriate workflow: | User intent | Workflow | | ----------------------------------------------------------- | ------------------------------------ | | Navigate, click, type, fill forms, interact with pages | `workflows/navigate-and-interact.md` | | Scrape data, extract content, read page structure | `workflows/scrape-and-extract.md` | | Test pages, run assertions, visual regression, mock network | `workflows/test-and-assert.md` | | Debug issues, check logs, diagnose problems | `workflows/debug-and-diagnose.md` | | Install, configure, set up sessions | `workflows/setup-and-configure.md` | **After reading the workflow, follow it. Load references only when the workflow directs you to.** </routing> <reference_index> All domain knowledge in `references/`: **Commands:** command-reference.md (all 63 commands with exact syntax) **Snapshots:** snapshot-and-refs.md (versioned refs, snapshot modes) **Intents:** semantic-intents.md (15 predefined intents for find-best/act) **Errors:** error-recovery.md (common errors and fixes) **Config:** configuration.md (TOML config, env vars, 5-layer merge) </reference_index> <workflows_index> | Workflow | Purpose | | ------------------------ | --------------------------------------------------------------- | | navigate-and-interact.md | Page navigation, clicking, typing, forms, intents | | scrape-and-extract.md | Data extraction, accessibility tree, page source | | test-and-assert.md | Assertions, visual regression, network mocking, test generation | | debug-and-diagnose.md | Console/network logs, timeline, debug bundles | | setup-and-configure.md | Installation, configuration, sessions, daemon management | </workflows_index> <success_criteria> Browser automation task is complete when: - Target page state is achieved and verified (via assertions or visual confirmation) - Daemon is stopped if no further browser work is needed (`gsd-browser daemon stop`) - Extracted data is returned in the expected format - Any saved state (auth, cookies) is persisted for reuse if appropriate </success_criteria>