# Topology Graph Schema

This document describes the JSON shape emitted by the engine. It is a practical schema note, not yet a formal JSON Schema file.

## `TopologyGraph`

- `schemaVersion`: currently `0.1`.
- `metadata.entryUrl`: entry URL after Playwright navigation.
- `metadata.mode`: `scan` or `explore`.
- `states`: page states.
- `elements`: actionable elements bound to a state.
- `edges`: observed actions from one state to another.

## `StateNode`

- `stateId`: stable id derived from URL, DOM hash, visible text hash, and actionable signature hash.
- `url`, `route`, `title`: browser-visible state identity.
- `domHash`: hash of full `document.documentElement.outerHTML`.
- `visibleTextHash`: hash of normalized visible body text.
- `actionableSignatureHash`: hash of actionable element signatures.
- `modalStack`: visible dialogs or modal-like surfaces.
- `openedByEdgeId`: edge that opened this state, if known.

## `ActionableElement`

- `elementId`: stable id within the captured state.
- `stateId`: owning state.
- `tag`, `role`, `accessibleName`, `text`, `label`, `placeholder`: semantic identity.
- `attributes`: selected stable attributes such as `data-testid`, `id`, `name`, `type`, `href`, and ARIA fields.
- `bbox`: page-space bounding box.
- `interactability`: visibility, enabled/editable status, and whether the element receives events.
- `locators`: scored locator candidates.

## `LocatorCandidate`

- `descriptor`: structured Playwright locator descriptor.
- `expression`: human-readable locator expression.
- `score`: ranking score.
- `verified`: whether it resolved to exactly one element during capture.
- `matchCount`: observed locator match count.

## `ActionEdge`

- `fromStateId`, `toStateId`: source and resulting states.
- `elementId`: action target.
- `actionType`: currently focused on `click`, with type support for future `fill`, `select`, and navigation actions.
- `preconditions`: reserved for stored open paths.
- `effects`: URL, visible text, network, download, dialog, storage, or DOM effects.
- `riskLevel`: `low`, `medium`, or `high`.
- `confidence`: confidence in observed edge replayability.