import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
import { B as Bridge } from '../types-D_TzdBsK.js';
import '../types-ITRQFAir.js';

/**
 * One interactive element the agent can act on, addressed by a STABLE handle
 * (not a CSS selector) so the agent drives the page the Human+ way — never DOM
 * scraping. The host builds these in `describe()` (data-co-handle → name/id →
 * ARIA role + accessible name).
 */
type PageAction = {
    /** Stable, opaque handle the agent passes back to act on this element. */
    handle: string;
    /** ARIA-ish role: "link" | "button" | "textbox" | "checkbox" | "select" | … */
    role: string;
    /** Accessible name / label. */
    label: string;
    /** Current value for inputs (omitted/masked for sensitive fields). */
    value?: unknown;
    /** True when activating this is destructive / submits (agent should stage). */
    destructive?: boolean;
};
/** The page as the agent sees it: where it is + what it can do. */
type PageSnapshot = {
    url: string;
    title: string;
    actions: PageAction[];
    /** Monotonic host revision. Human input advances it and invalidates stale agent intent. */
    revision?: number;
};
/**
 * Structured page text. Preferred over a plain string from `read()`: the bridge
 * can then put every page-supplied string on its own single line and keep the
 * outline. A plain string is untrusted as a whole and is rendered as ONE line.
 */
type PageReadout = {
    title: string;
    headings: Array<{
        level: number;
        text: string;
    }>;
    text: string;
};
/** A write the host may want the human to confirm (trust-but-verify). */
type NavigationConfirmRequest = {
    action: "submit" | "click";
    handle: string;
    label: string;
};
type MaybePromise<T> = T | Promise<T>;
/**
 * Host-provided adapter. In the sandbox this is backed by Inertia's `router` +
 * the DOM walker from `@particle-academy/agent-integrations/dom-navigation`.
 * Every method works on stable handles, never raw selectors.
 *
 * Any method may return a Promise: a host driving a page it does not run in
 * (an Electron WebContentsView, via `createRemoteNavigationAdapter`) can only
 * answer asynchronously. The bridge awaits every call.
 */
type NavigationBridgeAdapter = {
    /** Optional fancy-screens screen id for presence targeting. */
    screenId?: string;
    /** Current location. */
    getLocation: () => MaybePromise<{
        url: string;
        title: string;
    }>;
    /** Current human-control revision. Omit to disable stale-intent protection. */
    getRevision?: () => MaybePromise<number>;
    /** Snapshot of the page's actionable elements (stable handles + labels). */
    describe: () => MaybePromise<PageSnapshot>;
    /** Visible text / heading outline for grounding (optional). Prefer a {@link PageReadout}. */
    read?: () => MaybePromise<string | PageReadout>;
    /** Navigate to a URL (host wires to router.visit). */
    visit: (url: string) => void | Promise<void>;
    back?: () => void | Promise<void>;
    forward?: () => void | Promise<void>;
    /** Scroll to coords or to a handle's element. */
    scrollTo: (opts: {
        x?: number;
        y?: number;
        handle?: string;
    }) => void | Promise<void>;
    scrollBy: (dy: number) => void | Promise<void>;
    /** Set a field's value by handle (host dispatches input/change for React). */
    setField: (handle: string, value: unknown) => MaybePromise<{
        ok: boolean;
        error?: string;
    }>;
    /** Activate an element by handle. */
    click: (handle: string) => MaybePromise<{
        ok: boolean;
        error?: string;
    }>;
    /** Submit a form by handle. */
    submit: (handle: string) => Promise<{
        ok: boolean;
        error?: string;
    }> | {
        ok: boolean;
        error?: string;
    };
    /**
     * Viewport rect of a handle's element, for agent-presence rendering (cursor +
     * highlight). Returned in tool `meta.rect` so `<CoBrowseCursorLayer>` can show
     * the agent acting on the page. Optional — omit and there's just no cursor.
     */
    rectFor?: (handle: string) => MaybePromise<{
        x: number;
        y: number;
        width: number;
        height: number;
    } | null>;
    /**
     * Trust-but-verify hook. When `pendingMode` is on, `page_submit` and
     * destructive `page_click` route through this; the host shows a prompt and
     * resolves true (proceed) / false (declined).
     */
    confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;
};
type NavigationBridgeOptions = {
    adapter: NavigationBridgeAdapter;
    /** Identity tagged into activity events (so the human sees who's driving). */
    agent?: {
        id: string;
        name?: string;
        color?: string;
    };
    /** Route submit + destructive clicks through `adapter.confirm`. Default true. */
    pendingMode?: boolean;
};
/**
 * registerNavigationBridge — site-wide co-browsing. Lets a connected agent
 * navigate, scroll, and (with staged confirm) fill + click any page, addressed
 * by stable handles. Pairs with `useCoBrowseSession` (server + relay) and
 * `<CoBrowsePresence>` (the human's view of the agent). The 12th Fancy bridge.
 */
declare function registerNavigationBridge(host: ToolHost, options: NavigationBridgeOptions): Bridge;

export { type NavigationBridgeAdapter, type NavigationBridgeOptions, type NavigationConfirmRequest, type PageAction, type PageReadout, type PageSnapshot, registerNavigationBridge };