browse

Files (2)

• SKILL.md
• advanced-patterns.md · references/

SKILL.md (first lines)

# Browse — Interactive Browser QA

Two backends: `xd://browser` (runtime built-in, zero install, headless only)
or **gstack browse** (97KB binary, headed mode + handoff for CAPTCHA).
The skill auto-detects which is available.

## Setup (run first)

```bash
# Detect gstack browse binary
B=""
[ -x /home/theo/.claude/skills/gstack/browse/dist/browse ] && B="/home/theo/.claude/skills/gstack/browse/dist/browse"
[ -x /home/theo/.codex/skills/gstack/browse/dist/browse ] && B="/home/theo/.codex/skills/gstack/browse/dist/browse"
[ -x "$(git rev-parse --show-toplevel 2>/dev/null)/.agents/skills/gstack/browse/dist/browse" ] && B="$(git rev-parse --show-toplevel 2>/dev/null)/.agents/skills/gstack/browse/dist/browse"
export B
if [ -n "$B" ]; then echo "GSTACK_BROWSE=$B"; else echo "GSTACK_BROWSE=none (using xd://browser)"; fi
```

If `GSTACK_BROWSE=none`, all interactions use `xd://browser` (headless).
If `GSTACK_BROWSE` is set, `$B` works for all gstack browse commands.

## Quick Reference

```bash
# xd://browser (always available — headless only)
xd://browser { "action": "open", "url": "https://app.com", "name": "main" }
run code: tab.ariaSnapshot()   # ARIA YAML with [ref=eN]
run code: tab.fill('aria-ref=e2', 'Alice')
run code: tab.click('aria-ref=e5')

# gstack browse (headed + handoff — when available)
$B goto https://app.com
$B snapshot -i                  # @e1, @e2... refs
$B fill @e2 "Alice"
$B click @e5
$B handoff "solve CAPTCHA"     # visible browser for user
$B resume                       # continue after handoff
```

## Core Workflow

1. **Detect backend** via the Setup block above
2. **Open tab** — `xd://browser open` or `$B goto`
3. **Snapshot** — `tab.ariaSnapshot()` or `$B snapshot -i`
4. **Interact** — fill, click, select by @ref
5. **Verify** — check text, URL, console errors
6. **Handoff if stuck** — `$B handoff` for CAPTCHA/complex auth
7. **Screenshot** — capture evidence
8. **Close** — close tab or `$B stop`

## Patterns using xd://browser (always available)

### Pattern 1: Basic page verification
```
xd://browser { "action": "open", "url": "https://app.com/login" }
xd://browser { "action": "run", "name": "main", "code": "tab.observe()" }
xd://browser { "action": "run", "name": "main",
  "code": "const errs=[]; page.on('console',m=>m.type()==='error'&&errs.push(m.text())); page.on('requestfailed',r=>errs.push('NET: '+r.url())); await tab.goto('https://app.com/login'); errs" }
```

### Pattern 2: Snapshot + interact by @ref
```
xd://browser { "action": "run", "name": "main", "code": "tab.ariaSnapshot()" }
xd://browser { "action": "run", "name": "main",
  "code": "await tab.fill('aria-ref=e2', 'user@test.com'); await tab.click('aria-ref=e5'); tab.screenshot()" }
xd://browser { "action": "run", "name": "main", "code": "tab.observe()" }
```
Refs invalidate on navigation — re-observe after every `goto`.

### Pattern 3: Form fill and submit
```
xd://browser { "action": "run", "name": "main", "code": "
  await tab.fill('input[type=text]', 'Alice');
  await tab.select('select', 'green');
  await tab.click('button');
  await tab.waitForSelector('#result');
  tab.extract('#result')" }
```

### Pattern 4: Screenshot evidence
```
xd://browser { "action": "run", "name": "main",
  "code": "tab.screenshot()" }
xd://browser { "action": "run", "name": "main",
  "code": "tab.screenshot({ selector: '.dashboard' })" }
```

### Pattern 5: Dialog handling
```
xd://browser { "action": "open", "url": "...", "dialogs": "accept", "name": "main" }
xd://browser { "action": "run", "name": "main", "code": "
  page.on('dialog', d => d.accept());
  await tab.click('#delete-btn');" }
```

### Pattern 6: Multi-tab testing
```
xd://browser { "action": "open", "url": "https://app.com/a", "name": "tab1" }
xd://browser { "action": "open", "url": "https://app.com/b", "name": "tab2" }
xd://browser { "action": "run", "name": "tab1", "code": "tab.observe()" }
xd://browser { "action": "close", "name": "tab1" }
```

### Pattern 7: Viewport/responsive
```
xd://browser { "action": "open", "url": "...",
  "viewport": { "width": 375, "height": 812 }, "name": "mobile" }
```

### Pattern 8: Custom JS evaluation
```
xd://browser { "action": "run", "name": "main", "code": "
  const result = await tab.evaluate(() => ({
    title: document.title, url: location.href
  }));
  result" }
```

### Pattern 9: Wait conditions

From TheophilusChinomona/idev, MIT.

More from TheophilusChinomona/idev