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.
Compile scoped locator descriptors for row/dialog/form/list-item contexts when they can make duplicated targets executable.
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 navigation failures as failed observations when a graph can still be emitted.
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, metadata, and summary counts 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

npm install

Commands

Static scan:

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

Tests:

npm run test

Entry-state low-risk exploration:

npm run example

Timeout tuning for slow sites:

npm run explore -- --url https://www.gov.cn/ --out artifacts/govcn.json --max-actions 2 --navigation-timeout-ms 60000 --action-timeout-ms 3000

Build:

npm run build

Output Model

The output JSON follows the schema described in schemas/topology-graph.schema.md. A machine-checkable JSON Schema is available at schemas/topology-graph.schema.json.

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.
summary: count totals and grouped counts for edges, skipped actions, and failed observations.

Source Notes

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