@unotest/grounder-client 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to `@unotest/grounder-client` are documented in this file.
+
+## [0.10.0] - 2026-08-06
+
+### Minor Changes
+
+- 7324966: `createDomHelpers()` grows shared accname/state building blocks, so injected algorithms with divergent naming policies stop hand-copying the identical parts: `makeAccname(hostLanguageName)` (fixed prologue: cycle guard → aria-labelledby → aria-label → form-control labels; the per-tag chain is supplied by the caller), plus `nameFromLabelledby`, `svgAccname`, `formControlName`, `formFieldRole`, `ariaStateFlags`, `headingLevel` and the `AriaStateFlags` type. `accname`/`collectState`/`implicitRole` behavior is unchanged — they are now built on the same blocks.
+- b5b9710: Assert steps ground as whole units. `Intent.prefer` gains `"unit"`: the
+  grounder returns the semantic unit itself (heading / record / text) and
+  suppresses the record→control hop — the profile for read-only targets.
+  Web assert actions (`assert_text/visible/hidden/value/count`) declare
+  `intentTarget: "unit"` on their plugins, and the intent resolver
+  materializes a DOM ref for unit resolutions via the new
+  `materializeRefScript(nodeId)` (grounder-client dom-walker): one lazy
+  attribute write on the unit's own element, reused by later captures.
+  Previously an assert intent like "the page heading" was rejected with a
+  RECORD error and forced a `find_element` detour. Control-target errors
+  now name the unit kind correctly (heading / record / text block) and
+  point at assert steps for check-not-click intents.
+
+  Materialized record containers now resolve to a stable locator. A record
+  row / card / tree-item (`<li>`, `<tr>`, `<article>`) carries no accessible
+  name of its own — its text lives in children — so `RefResolver` gains a
+  container strategy: `getByRole(role).filter({hasText})`, keyed off the
+  container's short descendant text (capped so a whole table is never
+  captured) and verified for uniqueness + ref identity. Fixes `assert_visible`
+  on a grounded tree item failing with `no stable identifier`.
+
+- 574841f: Dedup pass across the tree (jscpd 0 clones, ratchet threshold 0). New public export in `@unotest/grounder-client`: `intEnvInRange(env, name, def, min, max)` — the `UNOTEST_GROUNDER_*` integer-env parser shared by the consumer side and the grounder server. Everything else is internal refactoring with no behavior change: protocol gains a shared fs-safe-name validator behind `validateCollectionName` / `validateSegmentName` and a shared env-file assignment iterator; core's `RuntimeInspection` becomes a `Pick` of `RuntimeStateFile`; dsl's `ExecutionWalker` threads one `WalkCtx` object instead of an eight-argument clump and AST nodes use constructor parameter properties; web deduplicates the MCP tool scaffolds, action plugins, DSL contracts, perception LRU caches, and semantic-dom grouping passes.
+- 65eb77c: Shared injected DOM helpers: one `createDomHelpers()` factory (visibility, ARIA roles, W3C accname, state flags, ref minting) now backs the grounder-client DOM walker and the web snapshot/find algorithms, composed into the page by `composeInjectedScript` — replaces four hand-maintained copies of the same in-page logic.
+
+  **Breaking (`@unotest/grounder-client`):** `captureRawTree` takes the helpers object as its first parameter, so passing it straight to `page.evaluate(captureRawTree)` no longer works (evaluate arguments are JSON-serialized and cannot carry the helpers). Migration: inject the serialized script instead — `page.evaluate(domWalkerScript())` — which composes the helpers automatically. New exports: `createDomHelpers`, `composeInjectedScript`, `InjectedDomHelpers`, `DomHelperOptions`, `InjectedScriptOptions`.
+
+  `@unotest/web` behavior deltas from unifying on the walker's ARIA mapping: `get_aria_snapshot` now maps `dl` to `list` (`dt`/`dd` stay name-only) and `tbody`/`thead`/`tfoot` to `rowgroup`, and never names structural containers from their text content; `find_element` matches against the full W3C accname (label-for lookup, composed multi-child names) instead of a reduced approximation.
+
+- f106cf8: The DOM walker records `fontWeight` on captured elements when it deviates
+  from normal (400), looking a few levels down so emphasis wrapped inside
+  the element counts (`<a><b>Technic</b></a>` reports 700).
+
+  Weight is a LEVEL cue: in a flat list the bold entry heads the plain ones
+  below it. Unlike indentation it survives multi-column layouts, where a
+  subtree continues in the next column at the same offset — the case that
+  made five same-named links in a 1200-link catalog tree indistinguishable.
+  Consumers reading `RawCapture` see one optional numeric field; nothing
+  else changes.
+
+- 856f087: `ResolveDiagnostics` gains `nameEvidence` — the page strings an intent
+  quoted verbatim plus whether the resolved unit owned one of them. The
+  grounder now answers NONE when an intent quotes page text that the
+  picked unit does not own (its own name/value or its record's identity
+  and fields); a collection label or region name counts as context, not
+  ownership. Consumers that surface grounding diagnostics can report the
+  new field; the shape is additive and optional.
+- 78f850f: `ResolveDiagnostics` gains `ordinalSubset` — set when a typed ordinal was
+  resolved deterministically inside a value-filtered subset ("the last
+  Pending row" over the 48 Pending rows of a 295-row table) instead of by
+  the picker. Carries the matched value, the subset size and the 0-based
+  index taken; absent when the picker decided the position.
+
+### Patch Changes
+
+- 1bd55ba: `ResolveDiagnostics.recordHop` gains an optional `prompt` — the exact
+  user message the record→control hop picker saw. Debug surface: the eval
+  console prints it verbatim; no behavior change.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Volkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @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
+
+```ts
+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);
+```

package/dist/dom-walker/index.d.ts

@@ -0,0 +1,115 @@
+import { R as RawState, a as RawCapture } from '../types-CMkcL3q9.js';
+
+interface DomHelperOptions {
+    /** Accname length cap (default 80). */
+    maxName?: number;
+    /** Where `aria-hidden="true"` hides an element: "ancestors" walks the
+     *  composed tree up (snapshot captures), "self" checks only the element
+     *  itself — the walker's recursive visibility gate already prunes hidden
+     *  subtrees, and the per-element ancestor climb would be O(depth²) on
+     *  its hot path. Default "ancestors". */
+    ariaHidden?: "ancestors" | "self";
+}
+/** Subset of accessibility state shared by the walker's `RawState` and
+ *  outline capture in @unotest/web (`disabled` and `level` handling
+ *  deliberately differ per side and stay out). */
+interface AriaStateFlags {
+    checked?: true | "mixed";
+    pressed?: true | "mixed";
+    expanded?: true;
+    selected?: true;
+    active?: true;
+}
+declare function createDomHelpers(opts?: DomHelperOptions): {
+    parentOrHost: (node: Node) => Element | null;
+    rootForScope: (el: Node) => Document | ShadowRoot;
+    getElementByIdInScope: (el: Element, id: string) => Element | null;
+    deepWalk: (root: Document | Element | ShadowRoot) => Generator<Element>;
+    isVisible: (el: Element) => boolean;
+    trim: (s: string | null | undefined) => string;
+    cap: (s: string) => string;
+    cssEscape: (s: string) => string;
+    textContentVisible: (el: Element) => string;
+    interactiveRoles: Set<string>;
+    formFieldRole: (el: Element, tag: string) => string | null;
+    implicitRole: (el: Element) => string | null;
+    computeRole: (el: Element) => string | null;
+    nameFromLabelledby: (el: Element, seen: Set<Element>, resolve: (ref: Element, seen: Set<Element>) => string) => string;
+    svgAccname: (svg: Element, seen: Set<Element>, resolve: (ref: Element, seen: Set<Element>) => string) => string;
+    formControlName: (el: Element) => string;
+    makeAccname: (hostLanguageName: (el: Element, tag: string, seen: Set<Element>, self: (el: Element, visited?: Set<Element>) => string) => string) => (el: Element, visited?: Set<Element>) => string;
+    accname: (el: Element, visited?: Set<Element>) => string;
+    ariaStateFlags: (el: Element) => AriaStateFlags;
+    headingLevel: (el: Element) => number | undefined;
+    collectState: (el: Element, role: string) => RawState | undefined;
+    pageOrigin: string;
+    normaliseHref: (raw: string | null) => string | undefined;
+    isInteractive: (el: Element, role: string | null) => boolean;
+    idStable: (id: string) => boolean;
+    stableDataAttr: (el: Element) => {
+        name: string;
+        value: string;
+    } | undefined;
+    clickAffordance: (el: Element) => boolean;
+    testIdOf: (el: Element) => string | undefined;
+    fontWeight: (el: Element) => number;
+    refRegex: RegExp;
+    ensureRef: (el: Element, kind: "i" | "n") => string;
+    persistRefCounter: () => void;
+};
+type InjectedDomHelpers = ReturnType<typeof createDomHelpers>;
+interface InjectedScriptOptions {
+    helperOpts?: DomHelperOptions;
+    /** JS expression literals appended as algorithm arguments after the
+     *  helpers object (already-serialized, e.g. `JSON.stringify(args)`). */
+    argLiterals?: string[];
+}
+/** Evaluate-ready expression running `algorithm(h, ...args)` in the page.
+ *  The `__name` shim neutralizes esbuild/tsx keepNames helper calls that
+ *  may be injected into the serialized function bodies. */
+declare function composeInjectedScript(algorithm: (h: InjectedDomHelpers, ...rest: never[]) => unknown, opts?: InjectedScriptOptions): string;
+
+declare function captureRawTree(h: InjectedDomHelpers): RawCapture;
+
+/** DOM attribute carrying an element's `eN` ref (interactive elements). */
+declare const REF_ATTRIBUTE = "data-unotest-ref";
+/** <html> attribute persisting the ref counter across captures. */
+declare const REF_COUNTER_ATTRIBUTE = "data-unotest-ref-counter";
+/** window global holding the live-node registry of the LAST capture:
+ *  `window.__unotestGrounderNodes[nodeId] === Element`. This is the
+ *  highlight handle for graph units — including `rN` record roots, which
+ *  have no DOM ref attribute. Replaced wholesale on every capture.
+ *  Must match the literal used inside walker.ts (the function is
+ *  serialized and cannot reference module scope). */
+declare const NODE_REGISTRY_GLOBAL = "__unotestGrounderNodes";
+/** Serialized walker as an evaluate-ready expression. `ariaHidden: "self"`
+ *  keeps the walker's original visibility semantics: its recursive walk
+ *  already prunes hidden subtrees, so the per-element ancestor climb is
+ *  redundant on this hot path. */
+declare function domWalkerScript(): string;
+/** Evaluate-ready expression resolving a nodeId to its live element —
+ *  building block for consumer-side highlight overlays. Returns null when
+ *  the registry is stale (page re-rendered) or the id is unknown. */
+declare function nodeByIdScript(nodeId: number): string;
+/** Evaluate-ready script materializing a `data-unotest-ref` (eN) on the
+ *  element behind `nodeId` — the DOM handle for graph units that never get
+ *  a ref at capture time (headings, record roots, text blocks; the walker
+ *  only stamps interactive elements). Lazy by design: one attribute write
+ *  per resolve, instead of stamping thousands of non-interactive elements
+ *  on every capture. Mirrors the walker's `ensureRef` conventions exactly
+ *  (same attribute, same <html> counter, owner kind `n` = named
+ *  non-interactive), so the next capture reuses the ref instead of
+ *  re-minting. Returns the eN, or null when the registry is stale (page
+ *  re-rendered since the capture). */
+declare function materializeRefScript(nodeId: number): string;
+/** Evaluate-ready script drawing outline overlays over the elements behind
+ *  `nodeIds` (live-node registry of the LAST capture). Overlays are
+ *  position:fixed and TRACK their elements — recomputed on every scroll
+ *  (capture phase, so inner scroll containers count) and resize; the first
+ *  target is scrolled into view BEFORE the boxes are placed. Re-running
+ *  replaces the previous highlight. Returns the number of elements found. */
+declare function highlightByNodeIdScript(nodeIds: number[], color?: string): string;
+/** Evaluate-ready script removing the highlight overlay, if any. */
+declare function clearHighlightScript(): string;
+
+export { type DomHelperOptions, type InjectedDomHelpers, type InjectedScriptOptions, NODE_REGISTRY_GLOBAL, REF_ATTRIBUTE, REF_COUNTER_ATTRIBUTE, RawCapture, captureRawTree, clearHighlightScript, composeInjectedScript, createDomHelpers, domWalkerScript, highlightByNodeIdScript, materializeRefScript, nodeByIdScript };