import type { ClipboardImage } from "@gajae-code/natives";
/** Thrown when an explicit clipboard transport (currently only `ssh`) fails.
 *
 * Explicit transports never silently fall back to native/OSC52 — the caller
 * must surface this to the user and leave the editor/clipboard unchanged.
 */
export declare class ClipboardTransportError extends Error {
    readonly context?: Record<string, unknown> | undefined;
    constructor(message: string, context?: Record<string, unknown> | undefined);
}
/**
 * Read text from the configured SSH clipboard host (`pbpaste`).
 *
 * Reads with a bounded, fatal-UTF-8-decoding stream drain (never buffers past
 * the 1 MiB cap before checking it) and rejects an inbound NUL byte. Throws
 * `ClipboardTransportError` on any failure — explicit `ssh` mode never falls
 * back to native/OSC52 paste.
 */
export declare function pasteFromClipboardViaSsh(host: string): Promise<string>;
/**
 * Copy text to the clipboard using the configured transport.
 *
 * - `auto` (default): emits OSC 52 over a real terminal, then best-effort
 *   native copy — unchanged from prior behavior.
 * - `native`: native clipboard only, no OSC 52.
 * - `osc52`: OSC 52 only, no native call.
 * - `ssh`: `ssh <clipboard.sshHost> pbcopy` via argv spawn with a 5s hard
 *   timeout covering the whole operation. Never falls back to native/OSC52 on
 *   failure — throws `ClipboardTransportError` instead so the caller can
 *   surface it.
 *
 * @param text - UTF-8 text to place on the clipboard.
 */
export declare function copyToClipboard(text: string): Promise<void>;
/**
 * Paste text from the configured clipboard transport.
 *
 * Only meaningful for `clipboard.transport = ssh` today (the explicit
 * "Paste text from configured clipboard" action) — other transports have no
 * dedicated paste path yet and return null.
 *
 * @returns pasted UTF-8 text, or null when no explicit ssh transport is configured.
 * @throws ClipboardTransportError on ssh failure — never returns stale/empty text silently.
 */
export declare function pasteFromClipboard(): Promise<string | null>;
/**
 * Read an image from the system clipboard.
 *
 * Returns null on Termux (no image clipboard support) or when no display
 * server is available (headless/SSH without forwarding). Under WSL the
 * Windows clipboard is reached through `powershell.exe`, since WSLg's
 * Wayland clipboard does not carry image payloads through to `arboard`.
 *
 * @returns PNG payload or null when no image is available.
 */
export declare function readImageFromClipboard(): Promise<ClipboardImage | null>;