agent-device 0.12.3 → 0.12.5

package/dist/src/commands/index.d.ts

@@ -0,0 +1,908 @@
+declare type AgentDeviceBackend = {
+    platform: AgentDeviceBackendPlatform;
+    capabilities?: BackendCapabilitySet;
+    escapeHatches?: BackendEscapeHatches;
+    captureSnapshot?(context: BackendCommandContext, options?: BackendSnapshotOptions): Promise<BackendSnapshotResult>;
+    captureScreenshot?(context: BackendCommandContext, outPath: string, options?: BackendScreenshotOptions): Promise<BackendScreenshotResult | void>;
+    readText?(context: BackendCommandContext, node: SnapshotNode): Promise<BackendReadTextResult>;
+    findText?(context: BackendCommandContext, text: string): Promise<BackendFindTextResult>;
+    tap?(context: BackendCommandContext, point: Point, options?: BackendTapOptions): Promise<BackendActionResult>;
+    fill?(context: BackendCommandContext, point: Point, text: string, options?: BackendFillOptions): Promise<BackendActionResult>;
+    typeText?(context: BackendCommandContext, text: string, options?: {
+        delayMs?: number;
+    }): Promise<BackendActionResult>;
+    pressKey?(context: BackendCommandContext, key: string, options?: {
+        modifiers?: string[];
+    }): Promise<BackendActionResult>;
+    openApp?(context: BackendCommandContext, target: BackendOpenTarget): Promise<BackendActionResult>;
+    closeApp?(context: BackendCommandContext, app?: string): Promise<BackendActionResult>;
+    installApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendActionResult>;
+};
+
+declare type AgentDeviceBackendPlatform = 'ios' | 'android' | 'macos' | 'linux';
+
+export declare type AgentDeviceCommands = {
+    capture: {
+        screenshot: RuntimeCommand<ScreenshotCommandOptions, ScreenshotCommandResult>;
+        diffScreenshot: RuntimeCommand<DiffScreenshotCommandOptions, DiffScreenshotCommandResult>;
+        snapshot: RuntimeCommand<SnapshotCommandOptions, SnapshotCommandResult>;
+        diffSnapshot: RuntimeCommand<DiffSnapshotCommandOptions, DiffSnapshotCommandResult>;
+    };
+    selectors: {
+        find: RuntimeCommand<FindReadCommandOptions, FindReadCommandResult>;
+        get: RuntimeCommand<GetCommandOptions, GetCommandResult>;
+        getText: RuntimeCommand<GetTextCommandOptions, Extract<GetCommandResult, {
+            kind: 'text';
+        }>>;
+        getAttrs: RuntimeCommand<GetAttrsCommandOptions, Extract<GetCommandResult, {
+            kind: 'attrs';
+        }>>;
+        is: RuntimeCommand<IsCommandOptions, IsCommandResult>;
+        isVisible: RuntimeCommand<IsSelectorCommandOptions, IsCommandResult>;
+        isHidden: RuntimeCommand<IsSelectorCommandOptions, IsCommandResult>;
+        wait: RuntimeCommand<WaitCommandOptions, WaitCommandResult>;
+        waitForText: RuntimeCommand<WaitForTextCommandOptions, Extract<WaitCommandResult, {
+            kind: 'text';
+        }>>;
+    };
+    interactions: {
+        click: RuntimeCommand<ClickCommandOptions, PressCommandResult>;
+        press: RuntimeCommand<PressCommandOptions, PressCommandResult>;
+        fill: RuntimeCommand<FillCommandOptions, FillCommandResult>;
+        typeText: RuntimeCommand<TypeTextCommandOptions, TypeTextCommandResult>;
+    };
+};
+
+declare type AgentDeviceRuntime = {
+    backend: AgentDeviceBackend;
+    artifacts: ArtifactAdapter;
+    sessions: CommandSessionStore;
+    policy: CommandPolicy;
+    diagnostics?: DiagnosticsSink;
+    clock?: CommandClock;
+    signal?: AbortSignal;
+};
+
+declare type ArtifactAdapter = {
+    resolveInput(ref: FileInputRef, options: ResolveInputOptions): Promise<ResolvedInputFile>;
+    reserveOutput(ref: FileOutputRef | undefined, options: ReserveOutputOptions): Promise<ReservedOutputFile>;
+    createTempFile(options: CreateTempFileOptions): Promise<TemporaryFile>;
+};
+
+declare type ArtifactDescriptor = {
+    kind: 'localPath';
+    field: string;
+    path: string;
+    fileName?: string;
+    metadata?: Record<string, unknown>;
+} | {
+    kind: 'artifact';
+    field: string;
+    artifactId: string;
+    fileName?: string;
+    url?: string;
+    clientPath?: string;
+    metadata?: Record<string, unknown>;
+};
+
+declare const BACKEND_CAPABILITY_NAMES: readonly ["android.shell", "ios.runnerCommand", "macos.desktopScreenshot"];
+
+declare type BackendActionResult = Record<string, unknown> | void;
+
+declare type BackendCapabilityName = (typeof BACKEND_CAPABILITY_NAMES)[number];
+
+declare type BackendCapabilitySet = readonly BackendCapabilityName[];
+
+declare type BackendCommandContext = {
+    session?: string;
+    requestId?: string;
+    appId?: string;
+    appBundleId?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+};
+
+declare type BackendEscapeHatches = {
+    androidShell?(context: BackendCommandContext, args: readonly string[]): Promise<BackendShellResult>;
+    iosRunnerCommand?(context: BackendCommandContext, command: BackendRunnerCommand): Promise<BackendActionResult>;
+    macosDesktopScreenshot?(context: BackendCommandContext, outPath: string, options?: BackendScreenshotOptions): Promise<BackendScreenshotResult | void>;
+};
+
+declare type BackendFillOptions = {
+    delayMs?: number;
+};
+
+declare type BackendFindTextResult = {
+    found: boolean;
+};
+
+declare type BackendInstallTarget = {
+    app: string;
+    artifactPath: string;
+};
+
+declare type BackendOpenTarget = {
+    app?: string;
+    url?: string;
+    activity?: string;
+};
+
+declare type BackendReadTextResult = {
+    text: string;
+};
+
+declare type BackendRunnerCommand = {
+    command: string;
+    args?: readonly string[];
+    payload?: Record<string, unknown>;
+};
+
+declare type BackendScreenshotOptions = {
+    fullscreen?: boolean;
+    overlayRefs?: boolean;
+    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+};
+
+declare type BackendScreenshotResult = {
+    path?: string;
+    overlayRefs?: ScreenshotOverlayRef[];
+};
+
+declare type BackendShellResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+
+declare type BackendSnapshotAnalysis = {
+    rawNodeCount?: number;
+    maxDepth?: number;
+};
+
+declare type BackendSnapshotFreshness = {
+    action: string;
+    retryCount: number;
+    staleAfterRetries: boolean;
+    reason?: 'empty-interactive' | 'sharp-drop' | 'stuck-route';
+};
+
+declare type BackendSnapshotOptions = SnapshotOptions & {
+    outPath?: string;
+};
+
+declare type BackendSnapshotResult = {
+    nodes?: SnapshotNode[];
+    truncated?: boolean;
+    backend?: string;
+    snapshot?: SnapshotState;
+    analysis?: BackendSnapshotAnalysis;
+    freshness?: BackendSnapshotFreshness;
+    warnings?: string[];
+    appName?: string;
+    appBundleId?: string;
+};
+
+declare type BackendTapOptions = {
+    button?: 'primary' | 'secondary' | 'middle';
+    count?: number;
+    intervalMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    doubleTap?: boolean;
+};
+
+export declare function bindCommands(runtime: AgentDeviceRuntime): BoundAgentDeviceCommands;
+
+export declare type BoundAgentDeviceCommands = {
+    capture: {
+        screenshot: BoundRuntimeCommand<ScreenshotCommandOptions, ScreenshotCommandResult>;
+        diffScreenshot: BoundRuntimeCommand<DiffScreenshotCommandOptions, DiffScreenshotCommandResult>;
+        snapshot: BoundRuntimeCommand<SnapshotCommandOptions, SnapshotCommandResult>;
+        diffSnapshot: BoundRuntimeCommand<DiffSnapshotCommandOptions, DiffSnapshotCommandResult>;
+    };
+    selectors: {
+        find: BoundRuntimeCommand<FindReadCommandOptions, FindReadCommandResult>;
+        get: BoundRuntimeCommand<GetCommandOptions, GetCommandResult>;
+        getText: (target: ElementTarget, options?: Omit<GetTextCommandOptions, 'target'>) => Promise<Extract<GetCommandResult, {
+            kind: 'text';
+        }>>;
+        getAttrs: (target: ElementTarget, options?: Omit<GetAttrsCommandOptions, 'target'>) => Promise<Extract<GetCommandResult, {
+            kind: 'attrs';
+        }>>;
+        is: BoundRuntimeCommand<IsCommandOptions, IsCommandResult>;
+        isVisible: (target: SelectorTarget, options?: Omit<IsSelectorCommandOptions, 'target'>) => Promise<IsCommandResult>;
+        isHidden: (target: SelectorTarget, options?: Omit<IsSelectorCommandOptions, 'target'>) => Promise<IsCommandResult>;
+        wait: BoundRuntimeCommand<WaitCommandOptions, WaitCommandResult>;
+        waitForText: (text: string, options?: Omit<WaitForTextCommandOptions, 'text'>) => Promise<Extract<WaitCommandResult, {
+            kind: 'text';
+        }>>;
+    };
+    interactions: {
+        click: (target: InteractionTarget, options?: Omit<ClickCommandOptions, 'target'>) => Promise<PressCommandResult>;
+        press: (target: InteractionTarget, options?: Omit<PressCommandOptions, 'target'>) => Promise<PressCommandResult>;
+        fill: (target: InteractionTarget, text: string, options?: Omit<FillCommandOptions, 'target' | 'text'>) => Promise<FillCommandResult>;
+        typeText: (text: string, options?: Omit<TypeTextCommandOptions, 'text'>) => Promise<TypeTextCommandResult>;
+    };
+};
+
+export declare type BoundRuntimeCommand<TOptions = Record<string, unknown>, TResult = CommandResult> = (options: TOptions) => Promise<TResult>;
+
+export declare type ClickCommandOptions = PressCommandOptions;
+
+export declare const commandCatalog: readonly CommandCatalogEntry[];
+
+export declare type CommandCatalogEntry = {
+    command: string;
+    category: 'portable-runtime' | 'backend-admin' | 'transport-session' | 'environment' | 'capability-gated';
+    status: 'implemented' | 'planned';
+};
+
+declare type CommandClock = {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+};
+
+declare type CommandContext = {
+    session?: string;
+    requestId?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+};
+
+declare type CommandPolicy = {
+    allowLocalInputPaths: boolean;
+    allowLocalOutputPaths: boolean;
+    maxImagePixels: number;
+    allowNamedBackendCapabilities: readonly BackendCapabilityName[];
+};
+
+export declare type CommandResult = Record<string, unknown>;
+
+export declare type CommandRouter<TContext = unknown> = {
+    dispatch(request: CommandRouterRequest<TContext>): Promise<CommandRouterResponse>;
+};
+
+export declare type CommandRouterConfig<TContext = unknown> = {
+    createRuntime(request: CommandRouterRequest<TContext>): AgentDeviceRuntime | Promise<AgentDeviceRuntime>;
+    beforeDispatch?(request: CommandRouterRequest<TContext>): void | Promise<void>;
+    formatError?(error: unknown, request: CommandRouterRequest<TContext>): NormalizedError;
+};
+
+export declare type CommandRouterRequest<TContext = unknown> = {
+    command: 'capture.screenshot';
+    options: ScreenshotCommandOptions;
+    context?: TContext;
+} | {
+    command: 'capture.diffScreenshot';
+    options: DiffScreenshotCommandOptions;
+    context?: TContext;
+} | {
+    command: 'capture.snapshot';
+    options: SnapshotCommandOptions;
+    context?: TContext;
+} | {
+    command: 'capture.diffSnapshot';
+    options: DiffSnapshotCommandOptions;
+    context?: TContext;
+} | {
+    command: 'selectors.find';
+    options: FindReadCommandOptions;
+    context?: TContext;
+} | {
+    command: 'selectors.get';
+    options: GetCommandOptions;
+    context?: TContext;
+} | {
+    command: 'selectors.is';
+    options: IsCommandOptions;
+    context?: TContext;
+} | {
+    command: 'selectors.wait';
+    options: WaitCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.click';
+    options: ClickCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.press';
+    options: PressCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.fill';
+    options: FillCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.typeText';
+    options: TypeTextCommandOptions;
+    context?: TContext;
+};
+
+export declare type CommandRouterResponse = {
+    ok: true;
+    data: CommandRouterResult;
+} | {
+    ok: false;
+    error: NormalizedError;
+};
+
+export declare type CommandRouterResult = ScreenshotCommandResult | DiffScreenshotCommandResult | SnapshotCommandResult | DiffSnapshotCommandResult | FindReadCommandResult | GetCommandResult | IsCommandResult | WaitCommandResult | PressCommandResult | FillCommandResult | TypeTextCommandResult;
+
+export declare const commands: AgentDeviceCommands;
+
+declare type CommandSessionRecord = {
+    name: string;
+    appId?: string;
+    appBundleId?: string;
+    appName?: string;
+    backendSessionId?: string;
+    snapshot?: SnapshotState;
+    metadata?: Record<string, unknown>;
+};
+
+declare type CommandSessionStore = {
+    get(name: string): CommandSessionRecord | undefined | Promise<CommandSessionRecord | undefined>;
+    set(record: CommandSessionRecord): void | Promise<void>;
+    delete?(name: string): void | Promise<void>;
+    list?(): readonly CommandSessionRecord[] | Promise<readonly CommandSessionRecord[]>;
+};
+
+export declare function createCommandRouter<TContext = unknown>(config: CommandRouterConfig<TContext>): CommandRouter<TContext>;
+
+declare type CreateTempFileOptions = {
+    prefix: string;
+    ext: string;
+};
+
+declare type DiagnosticsSink = {
+    emit(event: {
+        level: 'debug' | 'info' | 'warn' | 'error';
+        message: string;
+        data?: unknown;
+    }): void;
+};
+
+export declare type DiffScreenshotCommandOptions = CommandContext & {
+    baseline: FileInputRef;
+    current?: FileInputRef | LiveScreenshotInputRef;
+    out?: FileOutputRef;
+    currentOverlayOut?: FileOutputRef;
+    threshold?: number;
+    overlayRefs?: boolean;
+    surface?: BackendScreenshotOptions['surface'];
+};
+
+export declare type DiffScreenshotCommandResult = ScreenshotDiffResult & {
+    artifacts?: ArtifactDescriptor[];
+};
+
+export declare type DiffSnapshotCommandOptions = SnapshotCommandOptions;
+
+export declare type DiffSnapshotCommandResult = {
+    mode: 'snapshot';
+    baselineInitialized: boolean;
+    summary: SnapshotDiffSummary;
+    lines: SnapshotDiffLine[];
+    warnings?: string[];
+};
+
+export declare type ElementTarget = SelectorTarget | RefTarget;
+
+declare type FileInputRef = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'uploadedArtifact';
+    id: string;
+};
+
+declare type FileOutputRef = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'downloadableArtifact';
+    clientPath?: string;
+    fileName?: string;
+};
+
+export declare type FillCommandOptions = CommandContext & {
+    target: InteractionTarget;
+    text: string;
+    delayMs?: number;
+};
+
+export declare type FillCommandResult = ResolvedInteractionTarget & {
+    text: string;
+    warning?: string;
+    backendResult?: Record<string, unknown>;
+};
+
+declare type FindAction = {
+    kind: 'click';
+} | {
+    kind: 'focus';
+} | {
+    kind: 'fill';
+    value: string;
+} | {
+    kind: 'type';
+    value: string;
+} | {
+    kind: 'get_text';
+} | {
+    kind: 'get_attrs';
+} | {
+    kind: 'exists';
+} | {
+    kind: 'wait';
+    timeoutMs?: number;
+};
+
+declare type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
+
+export declare type FindReadCommandOptions = CommandContext & {
+    locator?: FindLocator;
+    query: string;
+    action: Extract<FindAction['kind'], 'exists' | 'wait' | 'get_text' | 'get_attrs'>;
+    timeoutMs?: number;
+} & SelectorSnapshotOptions;
+
+export declare type FindReadCommandResult = {
+    kind: 'found';
+    found: true;
+    waitedMs?: number;
+} | {
+    kind: 'text';
+    ref: string;
+    text: string;
+    node: SnapshotNode;
+} | {
+    kind: 'attrs';
+    ref: string;
+    node: SnapshotNode;
+};
+
+export declare type GetAttrsCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    target: ElementTarget;
+};
+
+export declare type GetCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    property: 'text' | 'attrs';
+    target: ElementTarget;
+};
+
+export declare type GetCommandResult = {
+    kind: 'text';
+    target: ResolvedTarget;
+    text: string;
+    node: SnapshotNode;
+    selectorChain?: string[];
+} | {
+    kind: 'attrs';
+    target: ResolvedTarget;
+    node: SnapshotNode;
+    selectorChain?: string[];
+};
+
+export declare type GetTextCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    target: ElementTarget;
+};
+
+export declare type InteractionTarget = ElementTarget | PointTarget;
+
+export declare type IsCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected' | 'text';
+    selector: string;
+    expectedText?: string;
+};
+
+export declare type IsCommandResult = {
+    predicate: IsCommandOptions['predicate'];
+    pass: true;
+    selector: string;
+    matches?: number;
+    text?: string;
+    selectorChain?: string[];
+};
+
+export declare type IsSelectorCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    target: SelectorTarget;
+};
+
+export declare type LiveScreenshotInputRef = {
+    kind: 'live';
+};
+
+declare type NormalizedError = {
+    code: string;
+    message: string;
+    hint?: string;
+    diagnosticId?: string;
+    logPath?: string;
+    details?: Record<string, unknown>;
+};
+
+declare type OutputVisibility = 'client-visible' | 'internal';
+
+declare type Point = {
+    x: number;
+    y: number;
+};
+
+export declare type PointTarget = {
+    kind: 'point';
+    x: number;
+    y: number;
+};
+
+export declare type PressCommandOptions = CommandContext & {
+    target: InteractionTarget;
+    button?: 'primary' | 'secondary' | 'middle';
+    count?: number;
+    intervalMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    doubleTap?: boolean;
+};
+
+export declare type PressCommandResult = ResolvedInteractionTarget & {
+    backendResult?: Record<string, unknown>;
+};
+
+declare type RawSnapshotNode = {
+    index: number;
+    type?: string;
+    role?: string;
+    subrole?: string;
+    label?: string;
+    value?: string;
+    identifier?: string;
+    rect?: Rect;
+    enabled?: boolean;
+    selected?: boolean;
+    hittable?: boolean;
+    depth?: number;
+    parentIndex?: number;
+    pid?: number;
+    bundleId?: string;
+    appName?: string;
+    windowTitle?: string;
+    surface?: string;
+    hiddenContentAbove?: boolean;
+    hiddenContentBelow?: boolean;
+};
+
+declare type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+export declare function ref(refInput: string, options?: {
+    fallbackLabel?: string;
+}): RefTarget;
+
+export declare type RefTarget = {
+    kind: 'ref';
+    ref: string;
+    fallbackLabel?: string;
+};
+
+declare type ReservedOutputFile = {
+    path: string;
+    visibility: OutputVisibility;
+    publish: () => Promise<ArtifactDescriptor | undefined>;
+    cleanup?: () => Promise<void>;
+};
+
+declare type ReserveOutputOptions = {
+    field: string;
+    ext: string;
+    requestedClientPath?: string;
+    visibility?: OutputVisibility;
+};
+
+declare type ResolvedInputFile = {
+    path: string;
+    cleanup?: () => Promise<void>;
+};
+
+declare type ResolvedInteractionTarget = {
+    kind: 'point';
+    point: Point;
+} | {
+    kind: 'ref';
+    point: Point;
+    target: Extract<ResolvedTarget, {
+        kind: 'ref';
+    }>;
+    node: SnapshotNode;
+    selectorChain: string[];
+    refLabel?: string;
+} | {
+    kind: 'selector';
+    point: Point;
+    target: Extract<ResolvedTarget, {
+        kind: 'selector';
+    }>;
+    node: SnapshotNode;
+    selectorChain: string[];
+    refLabel?: string;
+};
+
+export declare type ResolvedTarget = {
+    kind: 'selector';
+    selector: string;
+} | {
+    kind: 'ref';
+    ref: string;
+};
+
+declare type ResolveInputOptions = {
+    usage: string;
+    field?: string;
+};
+
+export declare type RuntimeCommand<TOptions = Record<string, unknown>, TResult = CommandResult> = (runtime: AgentDeviceRuntime, options: TOptions) => Promise<TResult>;
+
+export declare type ScreenshotCommandOptions = CommandContext & {
+    out?: FileOutputRef;
+    fullscreen?: boolean;
+    overlayRefs?: boolean;
+    appId?: string;
+    appBundleId?: string;
+    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+};
+
+export declare type ScreenshotCommandResult = {
+    path: string;
+    artifacts?: ArtifactDescriptor[];
+    message?: string;
+};
+
+declare type ScreenshotDiffRegion = {
+    index: number;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    normalizedRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    differentPixels: number;
+    shareOfDiffPercentage: number;
+    densityPercentage: number;
+    shape: 'compact' | 'horizontal-band' | 'vertical-band' | 'large-area';
+    size: 'small' | 'medium' | 'large';
+    location: string;
+    averageBaselineColorHex: string;
+    averageCurrentColorHex: string;
+    baselineLuminance: number;
+    currentLuminance: number;
+    dominantChange: 'brighter' | 'darker' | 'color-shift' | 'mixed';
+    currentOverlayMatches?: ScreenshotDiffRegionOverlayMatch[];
+};
+
+declare type ScreenshotDiffRegionOverlayMatch = {
+    ref: string;
+    label?: string;
+    regionCoveragePercentage: number;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+
+declare type ScreenshotDiffResult = {
+    diffPath?: string;
+    totalPixels: number;
+    differentPixels: number;
+    mismatchPercentage: number;
+    match: boolean;
+    dimensionMismatch?: ScreenshotDimensionMismatch;
+    regions?: ScreenshotDiffRegion[];
+    currentOverlayPath?: string;
+    currentOverlayRefCount?: number;
+    ocr?: ScreenshotOcrSummary;
+    nonTextDeltas?: ScreenshotNonTextDelta[];
+};
+
+declare type ScreenshotDimensionMismatch = {
+    expected: {
+        width: number;
+        height: number;
+    };
+    actual: {
+        width: number;
+        height: number;
+    };
+};
+
+declare type ScreenshotNonTextDelta = {
+    index: number;
+    regionIndex?: number;
+    slot: 'leading' | 'trailing' | 'background' | 'separator' | 'unknown';
+    likelyKind: 'icon' | 'toggle' | 'chevron' | 'separator' | 'visual';
+    rect: Rect;
+    nearestText?: string;
+};
+
+declare type ScreenshotOcrMovementCluster = {
+    texts: string[];
+    xRange: {
+        min: number;
+        max: number;
+    };
+    yRange: {
+        min: number;
+        max: number;
+    };
+};
+
+declare type ScreenshotOcrSummary = {
+    provider: 'tesseract';
+    baselineBlocks: number;
+    currentBlocks: number;
+    matches: ScreenshotOcrTextMatch[];
+    movementClusters?: ScreenshotOcrMovementCluster[];
+};
+
+declare type ScreenshotOcrTextMatch = {
+    text: string;
+    baselineRect: Rect;
+    currentRect: Rect;
+    delta: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    confidence: number;
+    possibleTextMetricMismatch: boolean;
+};
+
+declare type ScreenshotOverlayRef = {
+    ref: string;
+    label?: string;
+    rect: Rect;
+    overlayRect: Rect;
+    center: Point;
+};
+
+export declare function selector(expression: string): SelectorTarget;
+
+export declare type SelectorSnapshotOptions = {
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+
+export declare type SelectorTarget = {
+    kind: 'selector';
+    selector: string;
+};
+
+declare type SnapshotBackend = 'xctest' | 'android' | 'macos-helper' | 'linux-atspi';
+
+export declare type SnapshotCommandOptions = CommandContext & {
+    interactiveOnly?: boolean;
+    compact?: boolean;
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+
+export declare type SnapshotCommandResult = {
+    nodes: SnapshotNode[];
+    truncated: boolean;
+    appName?: string;
+    appBundleId?: string;
+    visibility?: SnapshotVisibility;
+    warnings?: string[];
+};
+
+export declare type SnapshotDiffLine = {
+    kind: 'added' | 'removed' | 'unchanged';
+    text: string;
+};
+
+export declare type SnapshotDiffSummary = {
+    additions: number;
+    removals: number;
+    unchanged: number;
+};
+
+declare type SnapshotNode = RawSnapshotNode & {
+    ref: string;
+};
+
+declare type SnapshotOptions = {
+    interactiveOnly?: boolean;
+    compact?: boolean;
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+
+declare type SnapshotState = {
+    nodes: SnapshotNode[];
+    createdAt: number;
+    truncated?: boolean;
+    backend?: SnapshotBackend;
+    comparisonSafe?: boolean;
+};
+
+declare type SnapshotVisibility = {
+    partial: boolean;
+    visibleNodeCount: number;
+    totalNodeCount: number;
+    reasons: SnapshotVisibilityReason[];
+};
+
+declare type SnapshotVisibilityReason = 'offscreen-nodes' | 'scroll-hidden-above' | 'scroll-hidden-below';
+
+declare type TemporaryFile = {
+    path: string;
+    visibility: 'internal';
+    cleanup: () => Promise<void>;
+};
+
+export declare type TypeTextCommandOptions = CommandContext & {
+    text: string;
+    delayMs?: number;
+};
+
+export declare type TypeTextCommandResult = {
+    kind: 'text';
+    text: string;
+    delayMs: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type WaitCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    target: {
+        kind: 'sleep';
+        durationMs: number;
+    } | {
+        kind: 'text';
+        text: string;
+        timeoutMs?: number | null;
+    } | {
+        kind: 'ref';
+        ref: string;
+        timeoutMs?: number | null;
+    } | {
+        kind: 'selector';
+        selector: string;
+        timeoutMs?: number | null;
+    };
+};
+
+export declare type WaitCommandResult = {
+    kind: 'sleep';
+    waitedMs: number;
+} | {
+    kind: 'text';
+    waitedMs: number;
+    text: string;
+} | {
+    kind: 'selector';
+    waitedMs: number;
+    selector: string;
+};
+
+export declare type WaitForTextCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    text: string;
+    timeoutMs?: number | null;
+};
+
+export { }