@unotest/web 0.5.0

package/dist/inspection/page-inject.d.ts

@@ -0,0 +1,395 @@
+/**
+ * Discriminator for SemanticRegion. Fixed set of bucket kinds that downstream
+ * consumers (projection, assertion-suggester, etc.) can filter by.
+ * Zone keys in `regions` remain human-readable labels — use `kind` for logic.
+ */
+type SemanticRegionKind = 'navigation' | 'search' | 'form' | 'main' | 'aside' | 'header' | 'footer' | 'dialog' | 'cmp' | 'overlay' | 'recommendations' | 'promo' | 'categoryChips' | 'table' | 'unknown';
+interface CompactAction {
+    tag?: string;
+    type?: string;
+    text?: string;
+    qa?: string;
+    testId?: string;
+    selector?: string;
+    role?: string;
+    href?: string;
+    /** Heuristic stability of the selector: high = id/testid/qa, medium = aria-label/name, low = fallback. */
+    stability?: 'high' | 'medium' | 'low';
+    /**
+     * True when disambiguation ran but couldn't make the selector unique (still
+     * matches >1 live elements). Downstream consumers can use this as a signal
+     * that strict-mode will fail — record as-is in DSL, do NOT mask with .first().
+     */
+    ambiguous?: boolean;
+    /** Name of the strategy that successfully refined to unique. Undefined if initial was unique or disambiguation failed. */
+    disambiguatedBy?: 'ancestor-anchor' | 'has-text' | 'slot-filter';
+    /** Bounding rectangle in viewport CSS pixels at capture time. Outline
+     *  rendering uses this to partition on-screen vs off-screen actions; it
+     *  is dropped from the rendered outline (only `clipped` survives there). */
+    bounds?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** True when bbox intersects a viewport edge (partially visible).
+     *  Distinct from off-screen: clipped means the element IS in the
+     *  viewport but cut by an edge. */
+    clipped?: boolean;
+}
+interface CompactPattern {
+    pattern: string;
+    selectorPattern?: string;
+    count: number;
+    samples?: string[];
+}
+interface TemplateField {
+    tag: string;
+    selector?: string;
+    text?: string;
+    ariaLabel?: string;
+    role?: string;
+    type?: string;
+    interactive: boolean;
+    optional: boolean;
+    sampleValues?: string[];
+}
+interface Collection {
+    count: number;
+    template: TemplateField[];
+    /** First N item texts (title/textContent of anchor element). Index = position in DOM. */
+    itemTexts?: string[];
+}
+/**
+ * Summary of a <table> / role=grid / role=table landmark.
+ * Populated when the algorithm encounters one inside a region.
+ */
+interface TableSummary {
+    selector: string;
+    columnCount: number;
+    rowCount: number;
+    headers: string[];
+}
+interface SemanticRegion {
+    /** Discriminator — fixed enum, consumers filter regions by this. */
+    kind: SemanticRegionKind;
+    /** Human-readable label (heading or landmark tag). Display-only. */
+    label?: string;
+    total: number;
+    actions?: CompactAction[];
+    collections?: Collection[];
+    patterns?: CompactPattern[];
+    tables?: TableSummary[];
+    other?: number;
+}
+interface SemanticDomStats {
+    totalElements: number;
+    filteredElements: number;
+    chars: number;
+    tokens: number;
+}
+interface SemanticDomDiagnostics {
+    collections: number;
+    shadowHosts: number;
+    shadowElements: number;
+    fuzzyMatched: number;
+    totalDomElements: number;
+    visibleDomElements: number;
+    interestingElements: number;
+    customElements: number;
+    pageTitle: string;
+    bodyChildren: number;
+    bodyVisible: boolean;
+    walkVisits: number;
+    actionableHosts: number;
+    suppressedByHost: number;
+    /** Warnings emitted by the algorithm (e.g. "unclassified-heavy" when unknown region >10%). */
+    warnings?: string[];
+}
+interface SemanticDomResult {
+    text: string;
+    rawText?: string;
+    regions: Record<string, SemanticRegion>;
+    stats: SemanticDomStats;
+    diagnostics: SemanticDomDiagnostics;
+    /** Viewport size at capture time (window.innerWidth / innerHeight).
+     *  Outline projection uses this together with CompactAction.bounds to
+     *  decide on-screen vs off-screen for each action. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+
+/**
+ * Semantic DOM Snapshot algorithm v2.
+ * Self-contained function for page.evaluate() — all logic runs in browser context.
+ *
+ * v2 changes (TES-450 follow-up, semantic-dom-v2-cleanup-plan):
+ * - Regions now carry a `kind: SemanticRegionKind` discriminator (R1).
+ * - Extended LANDMARK_SELECTOR: section[aria-label], article, dialog, role=region,
+ *   role=dialog, role=alertdialog, role=complementary (P5 Layer 1).
+ * - Synthetic region detectors: cmp (OneTrust/Cookiebot/Didomi/Usercentrics/TrustArc),
+ *   overlay, recommendations, promo, categoryChips (P5 Layer 2, P4).
+ * - Anti-fragmentation guardrails: min-3 interactives per region (form/search exempt),
+ *   diagnostics warning when unknown > 10% (P5 Layer 4).
+ * - Navigation regions emit each link as a separate action — no pattern collapse (P1).
+ * - Pattern key builder uses href/testid/qa prefixes, never bare tag (P2).
+ * - Stable selector fallback: text-locator `role=button[name="X"]`, never single-tag (P3).
+ * - CompactAction carries `stability: 'high'|'medium'|'low'` (P3, R2 requirement).
+ */
+
+interface BrowserSemanticDomOptions {
+    disambiguate?: boolean;
+}
+declare function semanticDomAlgorithm(options?: BrowserSemanticDomOptions): SemanticDomResult;
+
+/** Position of a region's bounding box relative to the current viewport.
+ *  Omitted on `OutlineRegion` when the region sits entirely inside the
+ *  viewport (i.e. `viewport === undefined` means "in view"). */
+type RegionViewport = 'above' | 'below' | 'partial';
+/** Accessibility state captured per interactive element. Only `true`/`mixed`
+ *  values are populated — `false` is the default and omitted by both
+ *  capture and render to keep the outline compact. Renderer emits flags
+ *  in a fixed order (disabled → checked → pressed → expanded → selected →
+ *  active → level) so diffs across snapshots stay stable. */
+interface OutlineActionState {
+    disabled?: true;
+    checked?: true | 'mixed';
+    pressed?: true | 'mixed';
+    expanded?: true;
+    selected?: true;
+    active?: true;
+    level?: number;
+}
+interface OutlineAction {
+    /** ARIA role or tag if no role attached (`button` / `link` / `textbox` / `heading` / …).
+     *  Omitted by the renderer when generic + name present (compaction
+     *  rule D from the mobile-side outline grammar). */
+    role?: string;
+    /** Visible text or aria-label. The single scalar the agent matches
+     *  against in selector synthesis. */
+    text?: string;
+    /** Stable selector hint — qa attribute or data-testid (#-prefixed in
+     *  the rendered line). */
+    testId?: string;
+    /** A stable app-authored `data-*` identifier (data-id / data-guid / …) —
+     *  the durable handle on grid rows / custom widgets that carry no role+name.
+     *  Rendered as `[data-x=v]`; the resolver can also address by it. */
+    dataId?: {
+        name: string;
+        value: string;
+    };
+    /** `title` / `aria-label` tooltip text when it ADDS information beyond the
+     *  accessible name — the action label of an icon ("Скопировать") or the full
+     *  value behind a truncated cell. Rendered as `title="…"`. */
+    title?: string;
+    /** Set when the element isn't a native/ARIA control but is clickable by
+     *  affordance (cursor:pointer / `hover:` class / onclick) — e.g. a datagrid
+     *  row. Rendered as `[clickable]` so the agent knows it can act on it. */
+    clickable?: true;
+    /** Shortened href fallback for `<a>` elements without an accessible
+     *  name. Carried on every link for tooling; renderer emits it ONLY
+     *  when `text` is absent (token economy — agents address links by
+     *  name when one exists). */
+    href?: string;
+    /** Accessibility state flags — see OutlineActionState. */
+    state?: OutlineActionState;
+    /** Partially clipped by a viewport edge. Off-screen actions never
+     *  carry this flag (off-screen ⇒ not in viewport at all). */
+    clipped?: boolean;
+    /** Opaque per-snapshot identifier of the form `e\d+`. Assigned by
+     *  capture (Commit 2 H); referenced by the wire-only LocatorStep
+     *  `{kind:'ref', ref}` form. Persistent .test.js scenarios cannot
+     *  use refs — they are stale-by-design across snapshots. */
+    ref?: string;
+    /** Bounding rect at capture time (viewport-relative integer px).
+     *  Used by tooling (coverage measurement, golden-test fixture
+     *  comparison); deliberately omitted by `renderOutline` to keep the
+     *  rendered string token-economical. */
+    bounds?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+interface OutlineRegion {
+    /** Landmark role: `banner` / `navigation` / `main` / `complementary` /
+     *  `contentinfo` / `form` / `search` / `region` / `dialog` /
+     *  `alertdialog` / `article`. The synthetic catch-all bucket for
+     *  elements without a landmark ancestor is `body`. */
+    kind: string;
+    /** Optional human-readable label (landmark aria-label, fallback to
+     *  the region's first heading). */
+    label?: string;
+    /** Position relative to the current viewport. Omitted when the
+     *  region's bounding box is entirely inside the viewport. */
+    viewport?: RegionViewport;
+    actions: OutlineAction[];
+}
+interface OutlineTree {
+    regions: OutlineRegion[];
+    _meta: {
+        totalActions: number;
+        totalRegions: number;
+        /** Per-viewport region counts. `inView` covers regions with no
+         *  viewport tag (fully visible). Zero entries are still emitted so
+         *  the shape is stable across snapshots. */
+        regionCounts: {
+            inView: number;
+            above: number;
+            below: number;
+            partial: number;
+        };
+        viewport: {
+            width: number;
+            height: number;
+        };
+        mode: 'outline';
+    };
+}
+
+declare function outlineAlgorithm(assignRefs: boolean): OutlineTree;
+
+/** State flags carried per ARIA node. Fixed render order in
+ *  `renderAriaYaml` keeps diffs stable. */
+interface AriaNodeState {
+    /** Heading level (1..6) or aria-level. Rendered as `[level=N]`. */
+    level?: number;
+    disabled?: true;
+    checked?: true | "mixed";
+    pressed?: true | "mixed";
+    expanded?: true;
+    selected?: true;
+    /** Element has keyboard focus at capture time. Rendered as `[active]`. */
+    active?: true;
+}
+/** A node in the ARIA snapshot tree. */
+interface AriaNode {
+    /** ARIA role — explicit `role=` attribute (first token) when present,
+     *  else implicit role from the host language mapping. `"text"` is a
+     *  pseudo-role for free text leaves. */
+    role: string;
+    /** Accessible name. Empty string when the node has no name; renderer
+     *  omits the trailing `"..."` block in that case. */
+    name: string;
+    /** State flags. Omitted entirely when no flags are set. */
+    state?: AriaNodeState;
+    /** Stable `eN` / `f<N>e<M>` ref shared with outline. Omitted for
+     *  free text leaves and other ref-less nodes. */
+    ref?: string;
+    /** Shortened href for links. Rendered as `/url: <value>`. */
+    url?: string;
+    /** Child nodes in DOM order. */
+    children: AriaNode[];
+}
+/** Top-level snapshot tree. */
+interface AriaTree {
+    /** Root children (no synthetic body wrapper — matches Playwright). */
+    nodes: AriaNode[];
+    _meta: {
+        /** Total nodes in the tree (excluding the implicit root). */
+        totalNodes: number;
+        /** Total refs assigned in this snapshot. */
+        totalRefs: number;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        mode: "aria";
+    };
+}
+
+declare function ariaSnapshotAlgorithm(): AriaTree;
+
+declare function serializeRuntimeDom(): string;
+
+interface FindElementMatch {
+    /** Shared with outline / aria-snapshot via `data-unotest-ref`.
+     *  Composite refs for matches inside same-origin iframes are NOT
+     *  produced here — `find_element` operates on the top document only;
+     *  use `enter_frame` then `find_element` again for iframe content. */
+    ref: string;
+    /** Computed ARIA role of the match. */
+    role: string;
+    /** Accessible name (W3C accname, trimmed/capped per snapshot conventions). */
+    name: string;
+    /** Element index — assigned when many elements match the same query.
+     *  Stable within a single `find_element` response so the agent can
+     *  re-query with `nth: K`. */
+    index: number;
+    /** Closest named ancestors, root-most first. Lets the agent see
+     *  "this row lives inside table inside main" without re-running a
+     *  full snapshot. Each entry is `{ role, name, ref }`; unnamed
+     *  ancestors are skipped. Capped at 4 entries — deeper structure
+     *  rarely informs disambiguation. */
+    ancestors: Array<{
+        role: string;
+        name: string;
+        ref?: string;
+    }>;
+}
+interface FindElementResult {
+    /** All matches; first `nth` (default 20) returned. */
+    matches: FindElementMatch[];
+    /** True count of matches before truncation. */
+    totalCount: number;
+    /** Echoed for cache-bust + diagnostics. */
+    query: {
+        role: string;
+        name?: string;
+        near?: string;
+        nth?: number;
+    };
+}
+
+declare function findElementAlgorithm(args: {
+    role: string;
+    name?: string;
+    near?: string;
+    nth?: number;
+    limit: number;
+}): FindElementResult;
+
+/** Raw element hint read off a live DOM element (mapped to `ElementHint`
+ *  by the caller). Shape mirrors the fields the RefResolver consumes. */
+interface ElementHintRaw {
+    testId?: string;
+    role?: string;
+    name?: string;
+    ariaLabel?: string;
+    placeholder?: string;
+    alt?: string;
+    titleAttr?: string;
+    text?: string;
+    href?: string;
+    elementId?: string;
+    nameAttr?: string;
+    dataAttr?: {
+        name: string;
+        value: string;
+    };
+    tooltipAttr?: {
+        name: string;
+        value: string;
+    };
+    ancestors?: Array<{
+        testId?: string;
+        dataAttr?: {
+            name: string;
+            value: string;
+        };
+        elementId?: string;
+        className?: string;
+    }>;
+}
+/** Set an input/textarea value via the native setter + fire input/change. */
+declare function pasteValue(el: Element, pasted: string): void;
+/** Live outerHTML of an element. */
+declare function readOuterHtml(el: Element): string;
+/** Read every identifying attribute off a live element (role inferred from
+ *  tag + ARIA, accname approximated). Returns a structured raw hint. */
+declare function inspectElementRaw(el: Element): ElementHintRaw;
+
+export { type ElementHintRaw, ariaSnapshotAlgorithm, findElementAlgorithm, inspectElementRaw, outlineAlgorithm, pasteValue, readOuterHtml, semanticDomAlgorithm, serializeRuntimeDom };