@unotest/grounder-client

Consumer-side contract of the unotest semantic UI grounder — the service that resolves a typed intent ("the edit button in the R-00042 row", "the last pending row") to element ref(s) on a captured page.

This package is everything a consumer needs to capture a page and talk to the grounding service:

• Raw capture contract — RawCapture and friends: the dumb visible-DOM tree the grounder consumes. Map any accessibility tree to it, or use the bundled walker.
• DOM walker (@unotest/grounder-client/dom-walker) — a self-contained in-page capture function plus evaluate-ready scripts (ref highlight, node-registry lookups).
• Content hash — hashRawCapture, the "is the page still the same state?" cache key. Semantics-only: bounds/scroll don't flip it.
• Typed intent → resolution — Intent (text + typed ordinal / predicate), Resolution (ref | set | none + diagnostics).
• Wire protocol + HTTP client — GrounderHttpClient over /index, /resolve, /session/close; per-session index isolation.

The grounding engine itself (graph perception, embedding recall, picker models) runs as a service and is not part of this package.

Usage

import { GrounderHttpClient, hashRawCapture, type RawCapture } from "@unotest/grounder-client";
import { domWalkerScript } from "@unotest/grounder-client/dom-walker";

const raw = (await page.evaluate(domWalkerScript())) as RawCapture;
const hash = hashRawCapture(raw);

const client = new GrounderHttpClient({ baseUrl, token });
await client.index(raw, hash);
const { resolution } = await client.resolve({ text: "the login field" }, hash);