npm package: @soonit/domstat
Description: Query browser runtime state for AI agents via Chrome DevTools Protocol
Author: SoonIter
Latest version: 0.2.1

# domstat

> Turn a running browser into a low‑entropy, queryable state machine.

`domstat` is a tiny CLI that lets **AI agents and developers** query the _actual runtime state_ of a front‑end page (DOM, console, network) without screenshots, DevTools dumps, or high token overhead.

It is designed for **fast feedback loops** during local development, especially when an AI is writing front‑end code and needs to self‑verify.

---

## Installation

```bash
npm install -g @soonit/domstat
```

---

## Quick Start

### 1. Launch Chrome with Remote Debugging

```bash
domstat launch
```

Or start Chrome manually:

```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-debug
```

### 2. Check Connection

```bash
domstat ping
```

### 3. Query the DOM

```bash
domstat query ".nav-bar > span"
```

---

## Usage

```
domstat <command> [options]

Commands:
  launch              Launch Chrome with remote debugging enabled
  ping                Check if Chrome CDP is reachable
  query <selector>    Query DOM elements matching the CSS selector

Options:
  --port <number>     Chrome debugging port (default: 9222)
  --host <string>     Chrome debugging host (default: localhost)
  --help              Show help message
  --version           Show version
```

---

## Why domstat exists

Modern AI coding workflows break down on the front end because feedback is:

- Slow (human inspection)
- Noisy (screenshots, full DOM, DevTools protocol)
- Expensive (large context → high token cost)

`domstat` solves this by exposing **only stable, low‑entropy facts**:

- Does an element exist?
- Is it visible?
- What text does it render?
- Are there runtime errors?

No UI interpretation. No automation flows. Just facts.

---

## Core idea

> **The browser is not a UI. It is a state database.**

Humans look at pixels.
AI should assert state.

`domstat` turns a live browser session into something you can query and assert against — cheaply and repeatedly.

---

## What domstat is (and is not)

### It **is**:

- A read‑only browser state inspector
- Optimized for AI self‑testing
- Deterministic and scriptable
- Extremely low token overhead

### It is **not**:

- A test runner
- A Playwright / Puppeteer replacement
- A DevTools wrapper
- A UI automation tool

---

## Example usage

Launch Chrome and check connection:

```bash
$ domstat launch
Chrome launched with remote-debugging-port 9222

$ domstat ping
{
  "connected": true,
  "url": "http://localhost:3000/",
  "title": "My App"
}
```

Query DOM state (jQuery‑like):

```bash
$ domstat query ".nav-bar > span"
{
  "exists": true,
  "count": 1,
  "text": "Dashboard",
  "visible": true
}
```

These outputs are intentionally short, stable, and machine‑friendly.

---

## Typical workflow

```text
AI writes code
↓
devServer hot reloads
↓
domstat queries runtime state
↓
AI fixes code based on facts
```

This loop is fast enough to run multiple times per minute.

---

## AI Skill

Copy this to your AI assistant's prompt to enable browser state verification:

````markdown
## Browser State Verification with domstat

You have access to `domstat` - a CLI tool that queries the actual runtime state of the browser via Chrome DevTools Protocol.

### Setup (one-time)

Before querying, ensure Chrome is running with remote debugging:

```bash
domstat launch
```

### Commands

```bash
# Check connection
domstat ping

# Query DOM elements
domstat query "<css-selector>"
```

### Query Response Format

```json
{
  "exists": true,      // Element(s) found
  "count": 1,          // Number of matches
  "text": "Dashboard", // First element's textContent
  "visible": true      // First element's visibility
}
```

### When to Use

After modifying front-end code and the dev server hot reloads, use `domstat query` to verify:

- Element exists: `domstat query "#submit-btn"` → check `exists: true`
- Text content: `domstat query ".error-message"` → check `text` field
- Visibility: `domstat query ".modal"` → check `visible` field
- Element count: `domstat query "li.item"` → check `count` field

### Workflow

1. Write/modify front-end code
2. Wait for hot reload
3. Run `domstat query "<selector>"` to verify changes
4. If verification fails, fix the code and repeat

### Best Practices

- Use specific selectors (IDs, unique classes) for reliable results
- Query after state changes (clicks, form submissions) to verify outcomes
- Check `exists: false` to confirm elements are properly removed
- Use `visible` to verify show/hide logic works correctly
````

---

## License

MIT