@unotest/grounder-client 0.10.0

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+import { a as RawCapture, B as Bounds } from './types-CMkcL3q9.js';
+export { b as RawElement, c as RawNode, R as RawState, d as RawText } from './types-CMkcL3q9.js';
+
+/** Stable hex content hash of a capture (url + semantic tree). */
+declare function hashRawCapture(raw: RawCapture): string;
+
+type Ordinal = {
+    kind: "nth";
+    n: number;
+} | {
+    kind: "last";
+};
+interface PredicateSpec {
+    /** Column description in the user's words ("price", "цена") — resolved
+     *  to an actual column by embedding, multilingually. */
+    field: string;
+    op: "gt" | "lt" | "eq";
+    value: number | string;
+}
+interface Intent {
+    /** The full intent text — the semantic channel (embeddings + picker). */
+    text: string;
+    /** Positional component, typed ("the third row" → { kind: "nth", n: 3 }). */
+    ordinal?: Ordinal;
+    /** Column predicate ("rows with price > 99") — answered deterministically
+     *  with a SET of record refs, no picker involved. */
+    predicate?: PredicateSpec;
+    /** What class of unit the consumer needs back:
+     *
+     *  - `"control"` — an ACTIONABLE element. When a resolution lands on a
+     *    record (row/item unit — no DOM handle by design), the grounder runs
+     *    the record→control second hop instead of returning the record: the
+     *    picker chooses among the record's inner controls. Set by consumers
+     *    whose targets get clicked/filled (web explore_step click/fill path).
+     *  - `"unit"` — the semantic unit ITSELF (heading / record / text), even
+     *    when it is not actionable. Suppresses the record→control hop —
+     *    including under `ordinal` (the n-th ROW is the answer, not a control
+     *    inside it). Set by consumers whose targets get READ, not clicked
+     *    (web assert steps); the consumer materializes a DOM handle from the
+     *    resolution's nodeId when it needs one.
+     *  - omitted — like `"unit"` without intent: a record is a valid answer
+     *    (reading, highlighting), but ordinal intents still hop when the text
+     *    names a control inside the row. */
+    prefer?: "control" | "unit";
+}
+/** A resolved element with everything a consumer needs to act on it:
+ *  ref for the driver, bounds for screenshot overlays, nodeId for the
+ *  live-node registry (in-page highlight). */
+interface ResolvedTarget {
+    ref: string;
+    bounds: Bounds | null;
+    nodeId: number | null;
+}
+interface ResolveDiagnostics {
+    /** Refs offered to the picker (recall surface), in prompt order. */
+    candidateRefs: string[];
+    /** Raw picker output (null when the picker wasn't consulted). */
+    pickerText: string | null;
+    /** Ref parsed from the picker output BEFORE the known-ref guard —
+     *  differs from the resolution when the picker hallucinated. */
+    pickerRef: string | null;
+    latencyMs: number;
+    pickerLatencyMs?: number;
+    /** Ordinal pool size, when an ordinal pool was assembled. */
+    poolSize?: number;
+    /** Lexical channel hits (intent ∩ typed page values). */
+    lexicalHits?: number;
+    /** Predicate only: the column the field resolved to. */
+    column?: string;
+    /** Reranker path: the winning candidate's relevance score. */
+    rerankScore?: number;
+    /** Name-evidence gate: page strings the intent quoted verbatim, and
+     *  whether the answer owned one of them. Absent when the intent quotes
+     *  nothing (gate silent) — see the grounder's name-evidence module. */
+    nameEvidence?: {
+        phrases: string[];
+        carried: boolean;
+    };
+    /** Typed ordinal resolved deterministically inside a value-filtered
+     *  subset (e.g. "the last Pending row" over the 48 Pending rows of a
+     *  295-row table): the matched value, the subset size and the 0-based
+     *  index taken. Absent when the picker decided the position. */
+    ordinalSubset?: {
+        value: string;
+        size: number;
+        index: number;
+    };
+    /** Ordinal record→control second hop (when the intent names a control
+     *  inside the row the ordinal picked): raw hop picker output + parsed
+     *  ref, plus the exact user message the hop picker saw (debug surface —
+     *  the eval console prints it verbatim). Absent when no hop ran. */
+    recordHop?: {
+        pickerText: string | null;
+        ref: string | null;
+        prompt?: string;
+    };
+}
+type Resolution = {
+    kind: "ref";
+    target: ResolvedTarget;
+    diagnostics: ResolveDiagnostics;
+} | {
+    kind: "set";
+    targets: ResolvedTarget[];
+    diagnostics: ResolveDiagnostics;
+} | {
+    kind: "none";
+    diagnostics: ResolveDiagnostics;
+};
+
+interface GroundLines {
+    /** pickerLine for every candidate ref, in prompt order. */
+    candidateLines: string[];
+    /** pickerLine for the resolved target(s): ref → 1, set → up to 10, none → []. */
+    targetLines: string[];
+}
+
+/** Header carrying the client-chosen session id — the index isolation key. */
+declare const SESSION_HEADER = "x-unotest-session";
+interface IndexRequest {
+    rawCapture: RawCapture;
+    /** Client-computed content hash — the per-session index key. Lets one
+     *  session hold several live indexes (page + iframe, LRU-capped). */
+    contentHash: string;
+}
+interface IndexResponse {
+    units: number;
+    indexMs: number;
+}
+interface ResolveRequest {
+    intent: Intent;
+    /** Which of the session's indexes to resolve against. Unknown hash →
+     *  409 `no-index` (evicted or never sent) — client re-sends /index. */
+    contentHash: string;
+}
+interface ResolveResponse extends GroundLines {
+    resolution: Resolution;
+}
+interface ErrorResponse {
+    error: string;
+    /** Machine code for control flow. `no-index` → client must re-`/index`. */
+    code?: "no-index" | "unauthorized" | "bad-request" | "internal";
+}
+declare const ROUTES: {
+    readonly index: "/index";
+    readonly resolve: "/resolve";
+    readonly close: "/session/close";
+    readonly health: "/health";
+};
+
+declare class GrounderRemoteError extends Error {
+    readonly status: number;
+    readonly code: ErrorResponse["code"] | undefined;
+    constructor(message: string, status: number, code: ErrorResponse["code"] | undefined);
+}
+interface GrounderHttpClientOptions {
+    baseUrl: string;
+    token: string;
+    /** Override the generated session id (tests). */
+    sessionId?: string;
+    /** Injected fetch (tests). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+declare class GrounderHttpClient {
+    readonly sessionId: string;
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(opts: GrounderHttpClientOptions);
+    index(rawCapture: RawCapture, contentHash: string): Promise<IndexResponse>;
+    resolve(intent: Intent, contentHash: string): Promise<ResolveResponse>;
+    close(): Promise<void>;
+    private post;
+}
+
+/** Parse an integer env var with range validation; unset/empty → default.
+ *  Shared by the consumer side (web perception env) and the grounder server
+ *  env so the `UNOTEST_GROUNDER_*` parsing rules stay identical on both
+ *  sides of the service boundary. */
+declare function intEnvInRange(env: NodeJS.ProcessEnv, name: string, def: number, min: number, max: number): number;
+
+export { Bounds, type ErrorResponse, type GroundLines, GrounderHttpClient, type GrounderHttpClientOptions, GrounderRemoteError, type IndexRequest, type IndexResponse, type Intent, type Ordinal, type PredicateSpec, ROUTES, RawCapture, type Resolution, type ResolveDiagnostics, type ResolveRequest, type ResolveResponse, type ResolvedTarget, SESSION_HEADER, hashRawCapture, intEnvInRange };

package/dist/index.js

@@ -0,0 +1,124 @@
+// src/hash.ts
+var FNV_OFFSET = 0xcbf29ce484222325n;
+var FNV_PRIME = 0x100000001b3n;
+var MASK64 = 0xffffffffffffffffn;
+function fnv1a(prev, s) {
+  let h = prev;
+  for (let i = 0; i < s.length; i++) {
+    h = (h ^ BigInt(s.charCodeAt(i))) * FNV_PRIME & MASK64;
+  }
+  return h;
+}
+function feedNode(h, node) {
+  if (node.kind === "text") {
+    return fnv1a(h, "t" + node.text);
+  }
+  const el = node;
+  const state = el.state ? [
+    el.state.disabled ? "d" : "",
+    el.state.checked ? `c${el.state.checked}` : "",
+    el.state.pressed ? `p${el.state.pressed}` : "",
+    el.state.expanded ? "x" : "",
+    el.state.selected ? "s" : "",
+    el.state.active ? "a" : "",
+    el.state.level !== void 0 ? `l${el.state.level}` : ""
+  ].join("") : "";
+  const parts = "e" + el.tag + "" + (el.role ?? "") + "" + el.name + "" + (el.value ?? "") + "" + state + "" + (el.ref ?? "") + "" + (el.testId ?? "") + "" + (el.dataId ? el.dataId.name + "=" + el.dataId.value : "") + "" + (el.href ?? "");
+  h = fnv1a(h, parts);
+  for (const child of el.children) h = feedNode(h, child);
+  return fnv1a(h, "/");
+}
+function hashRawCapture(raw) {
+  let h = FNV_OFFSET;
+  h = fnv1a(h, raw.url);
+  h = feedNode(h, raw.tree);
+  return h.toString(16).padStart(16, "0");
+}
+
+// src/protocol.ts
+var SESSION_HEADER = "x-unotest-session";
+var ROUTES = {
+  index: "/index",
+  resolve: "/resolve",
+  close: "/session/close",
+  health: "/health"
+};
+
+// src/http-client.ts
+import { randomUUID } from "crypto";
+var GrounderRemoteError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "GrounderRemoteError";
+  }
+  status;
+  code;
+};
+var GrounderHttpClient = class {
+  sessionId;
+  baseUrl;
+  token;
+  fetchImpl;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.token = opts.token;
+    this.sessionId = opts.sessionId ?? randomUUID();
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+  index(rawCapture, contentHash) {
+    return this.post(ROUTES.index, { rawCapture, contentHash });
+  }
+  resolve(intent, contentHash) {
+    return this.post(ROUTES.resolve, { intent, contentHash });
+  }
+  async close() {
+    await this.post(ROUTES.close, {});
+  }
+  async post(path, body) {
+    let res;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.token}`,
+          [SESSION_HEADER]: this.sessionId
+        },
+        body: JSON.stringify(body)
+      });
+    } catch (e) {
+      throw new GrounderRemoteError(
+        `cannot reach grounder server at ${this.baseUrl} (${e instanceof Error ? e.message : String(e)})`,
+        0,
+        void 0
+      );
+    }
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new GrounderRemoteError(json.error ?? `${path} \u2192 ${res.status}`, res.status, json.code);
+    }
+    return json;
+  }
+};
+
+// src/env-util.ts
+function intEnvInRange(env, name, def, min, max) {
+  const raw = env[name];
+  if (raw === void 0 || raw === "") return def;
+  const n = Number.parseInt(raw, 10);
+  if (Number.isNaN(n) || n < min || n > max) {
+    throw new Error(`${name} must be an integer in [${min}, ${max}], got "${raw}"`);
+  }
+  return n;
+}
+export {
+  GrounderHttpClient,
+  GrounderRemoteError,
+  ROUTES,
+  SESSION_HEADER,
+  hashRawCapture,
+  intEnvInRange
+};
+//# sourceMappingURL=index.js.map

package/dist/types-CMkcL3q9.d.ts

@@ -0,0 +1,69 @@
+interface Bounds {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface RawState {
+    disabled?: true;
+    checked?: true | "mixed";
+    pressed?: true | "mixed";
+    expanded?: true;
+    selected?: true;
+    active?: true;
+    level?: number;
+}
+interface RawElement {
+    kind: "element";
+    tag: string;
+    /** ARIA role (explicit or implicit), null for generic containers. */
+    role: string | null;
+    /** W3C accname — computed only when role is non-null ("" otherwise). */
+    name: string;
+    /** Control value: input/textarea value, select's selected option label. */
+    value?: string;
+    state?: RawState;
+    /** `eN` — minted by the capture adapter for interactive elements. Non-
+     *  interactive nodes have no ref; the builder assigns `rN` to record
+     *  roots later. */
+    ref?: string;
+    /** Index into the capture-side live-node registry (highlight handle for
+     *  ANY captured element, including rN record roots that never get a DOM
+     *  ref attribute). Optional: non-live producers (fixtures) omit it. */
+    nodeId?: number;
+    testId?: string;
+    dataId?: {
+        name: string;
+        value: string;
+    };
+    href?: string;
+    /** Rendered font weight when it deviates from normal (400) — emphasis
+     *  inside the element counts, so `<a><b>X</b></a>` reports 700. Absent
+     *  = ordinary weight. A bold entry among plain siblings is how a flat
+     *  list shows its top level; see the walker. */
+    fontWeight?: number;
+    bounds: Bounds;
+    children: RawNode[];
+}
+interface RawText {
+    kind: "text";
+    /** Trimmed, whitespace-collapsed, UNCAPPED — cell values must survive. */
+    text: string;
+}
+type RawNode = RawElement | RawText;
+interface RawCapture {
+    url: string;
+    title: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    tree: RawElement;
+    stats: {
+        elements: number;
+        textNodes: number;
+        refs: number;
+    };
+}
+
+export type { Bounds as B, RawState as R, RawCapture as a, RawElement as b, RawNode as c, RawText as d };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@unotest/grounder-client",
+  "version": "0.10.0",
+  "description": "Client contract for the unotest semantic UI grounder: typed intent/resolution types, the injectable DOM walker (RawCapture), the content hash, and the HTTP client + wire protocol of the grounding service. The grounding engine itself is a private service; this package is everything a consumer needs to capture a page and talk to it.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Ivan Volkov <ivan@volkov.io>",
+  "homepage": "https://www.npmjs.com/package/@unotest/grounder-client",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./dom-walker": {
+      "types": "./dist/dom-walker/index.d.ts",
+      "import": "./dist/dom-walker/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test --test-reporter=spec 'src/**/*.test.ts'",
+    "compile": "tsup",
+    "verify": "pnpm typecheck && pnpm check:no-cyrillic && pnpm test",
+    "build": "pnpm verify && pnpm compile && pnpm check:tarball",
+    "check:no-cyrillic": "node scripts/check-no-cyrillic.mjs",
+    "check:tarball": "node scripts/check-tarball.mjs"
+  }
+}