# 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 reproducibility metadata: browser, viewport, locale, auth mode, crawl session id, input fingerprint, and policy/scoring versions.
- 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, context scopes, identity checks, and verification evidence.
- Optionally run low-risk one-hop click exploration from a clean entry state.
- Replay actions from the entry state and record observed state transitions with snapshot-diff effects.
- Record state-local skipped default-exploration actions when risk policy blocks them.
- Record failed observations instead of turning failed locators or failed actions into successful edges.
- Emit state nodes, elements, locators, action edges, skipped actions, failed observations, and metadata in JSON.

## Non-Goals

- No LLM decision making.
- No natural-language task planner.
- No high-risk automatic actions.
- No full crawler or breadth-first site exploration.
- No general browser agent or workflow orchestration platform.
- No attempt to fully recover frontend business functions in this engine.

## Install

```bash
npm install
```

## Commands

Static scan:

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

Tests:

```bash
npm run test
```

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:

- `TopologyGraph.metadata`: artifact version, input URL, entry URL, generated timestamp, engine version, mode, non-deterministic crawl session id, deterministic input fingerprint, runtime context, site, and policy/scoring versions.
- `StateNode`: URL, route, title, canonical key, language, viewport, state hashes, modal stack, lifecycle, evidence, and first observed `openedByEdgeId`.
- `ActionableElement`: state-local element semantics, visibility/interactability, bounding box, context anchors, parameter surface, evidence, and locator candidates.
- `LocatorCandidate`: Playwright-friendly locator descriptors plus score, verification status, context `scopes`, identity evidence, and failure count.
- `ActionEdge`: low-risk replayed action from one state to another through an element, with `riskCategory`, `riskLevel`, and snapshot-diff `effects`.
- `EffectRecord`: snapshot-diff record for `url`, `dom`, `visibleText`, or `actionableInventory`, with `before` and `after` values.
- `SkippedAction`: risk-policy default exploration refusal with risk category, reason, state id, element id, and evidence.
- `FailedObservation`: locator, actionability, action, or effect failure with machine-readable reason and diagnostic evidence.

## Source Notes

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