# Action Topology Engine

Small deterministic tool for building a website action topology graph.

The project intentionally does not include an LLM, a generic browser agent, or a large workflow platform. Its job is to observe a site, describe states and actionable elements, generate verifiable locator candidates, and record action edges with observable effects.

## Current Scope

- Open a URL or local HTML file with Playwright.
- Capture one page state with DOM and visible-text fingerprints.
- Extract actionable elements: buttons, links, inputs, selects, textareas, roles, tab stops, and click handlers.
- Generate locator candidates with scores.
- Optionally explore low-risk click actions from the entry state.
- Record state nodes, elements, locators, action edges, and basic effects in JSON.

## Non-Goals

- No LLM decision making.
- No natural-language task planner.
- No high-risk automatic actions.
- No attempt to fully recover frontend business functions in the first version.

## Install

```bash
npm install
```

## Commands

Static scan:

```bash
npm run scan -- --url ./examples/simple.html --out artifacts/simple-scan.json
```

Entry-state low-risk exploration:

```bash
npm run example
```

Build:

```bash
npm run build
```

## Output Model

The output JSON follows the schema described in [schemas/topology-graph.schema.md](schemas/topology-graph.schema.md).

Key objects:

- `StateNode`: URL, route, title, state hashes, modal stack, and entry metadata.
- `ActionableElement`: element semantics, visibility, bounding box, and locator candidates.
- `LocatorCandidate`: Playwright-friendly locator descriptors plus score and verification status.
- `ActionEdge`: action from one state to another through an element, with effects and risk.

## Source Notes

The originating ChatGPT share conversation is preserved in [docs/source/chatgpt-share-6a30e583.md](docs/source/chatgpt-share-6a30e583.md).