/**
 * Weavetab — cdp/walker.ts
 * Accessibility tree walker: builds w:N ref IDs, viewport culling, and heuristic pointer sweep.
 * Weavetab by fy2ne
 */
import CDP from "chrome-remote-interface";
import { type RefEntry } from "../state/delta.js";
export declare const WT_REGISTRY_INIT_EXPR = "\n  window.__weavetab = window.__weavetab || {};\n  window.__weavetab.registry = window.__weavetab.registry || new WeakMap();\n";
export type HrefType = "same-origin" | "external" | "anchor" | "email" | "unknown";
export interface ActionElement {
    id: string;
    role: string;
    label: string;
    value?: string;
    backendNodeId?: number;
    selector?: string;
    group: "navigation" | "main_content" | "sidebar" | "form" | "modal" | "utility";
    type?: string;
    href?: string;
    hrefType?: HrefType;
    placeholder?: string;
    testId?: string;
    textContent?: string;
    className?: string;
    frameUrl?: string;
    fingerprint: string;
    isFixed?: boolean;
    disabled?: boolean;
    depth: number;
    x?: number;
    y?: number;
    viewport?: string;
    structuralIdiom?: string;
    containerContext?: string;
    isModal?: boolean;
    modalTitle?: string;
}
export interface ActionMap {
    url: string;
    title: string;
    elements: ActionElement[];
    pageType?: string;
    targetId?: string;
    domHash?: number;
}
export interface WalkerOptions {
    scope?: ActionElement["group"];
    query?: string;
    limit?: number;
    lite?: boolean;
    fast?: boolean;
    /** If true, returns delta info instead of full element list (caller handles) */
    forDelta?: boolean;
    /** Viewport dimensions — used for culling. Defaults fetched from browser if not passed. */
    viewport?: {
        width: number;
        height: number;
        scrollX: number;
        scrollY: number;
    };
    /** If true, skip the flat-first optimization and go straight to deep shadow DOM traversal */
    deep?: boolean;
    /** Pre-resolved page URL — avoids redundant Page.getFrameTree() call */
    url?: string;
    /** Pre-resolved page title */
    title?: string;
    /**
     * If true, run semantic DOM pruning before returning elements.
     * Drops hidden elements with no interactive descendants and no known toggle-trigger.
     * Replaces SVG icons with [SVG Icon: label] tokens.
     * NOTE: distinct from delta (which diffs across time). Pruning compresses the
     * current snapshot once, before it is returned.
     */
    prune?: boolean;
}
export declare function clearViewportCache(targetId: string): void;
export declare function resetFallbackIdCounter(): void;
export declare function setShadowDomCache(targetId: string, hasShadow: boolean): void;
export declare function clearShadowDomCache(targetId: string): void;
export declare function buildActionMap(session: CDP.Client, options?: WalkerOptions, targetId?: string): Promise<ActionMap>;
export declare function toRefEntries(elements: ActionElement[]): RefEntry[];
export declare function findAllMatches(elements: ActionElement[], query: string): ActionElement[];
export declare function findBestMatch(elements: ActionElement[], query: string): ActionElement | undefined;
export declare function toMarkdownTable(elements: ActionElement[], url: string, title: string, hint?: string): string;
export declare function safeSelector(el?: ActionElement): string | undefined;
export declare function resolveByAria(session: CDP.Client, query: string): Promise<{
    id: string;
    label: string;
    x: number;
    y: number;
    selector: string;
} | null>;
export declare function clearAXTreeCache(targetId: string): void;
export declare function buildAXTreeMap(session: CDP.Client, _options?: WalkerOptions, targetId?: string): Promise<ActionMap>;
/**
 * Sanitizes element IDs in an ActionElement list, replacing empty or malformed
 * IDs with sequential fallback IDs.
 */
export declare function sanitizeElementIds(els: ActionElement[], counter: {
    value: number;
}): number;
export interface RecoveredRefResult {
    recovered: boolean;
    element?: ActionElement;
    strategy?: "connected_existing" | "stored_selector" | "exact_label" | "placeholder_or_name" | "fuzzy_label";
    warning?: string;
}
/**
 * Recovers a detached or invalidated w:NN ref on reactive SPAs.
 * When hydration or DOM re-renders detach an element, this helper executes a sub-5ms
 * multi-tier recovery heuristic (connected node verification, stored CSS selector,
 * exact label/aria, placeholder/name match, and fuzzy substring) and re-stamps
 * data-wt-id="NN" onto the live DOM node so subsequent interaction succeeds.
 */
export declare function recoverDetachedRef(session: CDP.Client, targetId: string, ref: string, preferredCandidate?: Partial<ActionElement>): Promise<RecoveredRefResult>;