/**
 * Reading the system clipboard, for when the terminal's own paste will not do.
 *
 * Pasting into a terminal is not one mechanism, it is several: bracketed paste if the terminal
 * offers it, a plain burst of characters if not, a middle-click that KONECK may have taken over for
 * its own mouse handling, and on Windows a Ctrl+V that some hosts deliver as a control code rather
 * than as text. Somebody trying to put an API key into a prompt does not care which of those their
 * terminal does, and telling them to type a sixty-character secret by hand is not an answer.
 *
 * So the prompt can go and fetch it. Every desktop already has a command for this, and KONECK
 * already shells out to their write-side counterparts for /copy; this is the same list read the
 * other way round.
 */
export interface ClipboardRead {
    ok: boolean;
    text: string;
    /** Which command answered, so it can be named. */
    by?: string;
    /** Why nothing came back, when nothing did. */
    reason?: string;
}
/**
 * What is on the clipboard, or why it could not be read.
 *
 * Each reader gets a short deadline: a clipboard tool that hangs — xclip waiting on an X server
 * that is not there is the usual way — must not hold a keystroke open. Failure is ordinary and is
 * reported rather than thrown: a machine reached over SSH has no clipboard, and that is a fact
 * about the machine rather than an error in the program.
 */
export declare function readClipboard(readers?: ReadonlyArray<{
    file: string;
    args: string[];
}>, timeoutMs?: number): Promise<ClipboardRead>;
/**
 * A value typed or pasted into a field, with what cannot be seen taken out.
 *
 * Only characters that are invisible or cannot legally appear: nothing that changes what a person
 * meant. A value that still fails after this failed for a reason they can see.
 */
export declare function stripInvisible(text: string): string;
/**
 * What a value actually is, when what it looks like is not the problem.
 *
 * An error that rejects a value without showing it is undiagnosable the moment the value looks
 * correct — which is exactly when somebody asks for help. Invisible characters are written out as
 * their code points, so a string that reads right on screen and is wrong in memory can be told
 * apart from one that is simply wrong.
 */
export declare function revealValue(text: string, limit?: number): string;
/**
 * A pasted secret, made safe to use as one.
 *
 * Three things go, each for its own reason. Surrounding whitespace, because a key copied out of a
 * file or a password manager carries a trailing newline that is not part of it. Bracketed paste
 * markers, because a terminal that announces a paste mid-chunk can leave the literal text "[200~"
 * in the field, and a key with that in front of it fails at the provider with an authentication
 * error that says nothing about where it came from. And control characters, which are invalid in an
 * HTTP header — a key carrying one is rejected by the transport before the provider ever sees it,
 * which is the least informative way for this to go wrong.
 */
export declare function cleanPastedSecret(text: string): string;
/** Read a binary PNG before trying text; never decode image bytes as UTF-8. */
export declare function readClipboardImage(): Promise<{
    path?: string;
    reason?: string;
}>;
/** A selection must change while this terminal owns focus, and settle before copying. */
export declare class SelectionCopyState {
    private previous;
    private candidate;
    /** A changed selection needs one quick confirmation before it is copied. */
    get awaitingSettle(): boolean;
    observe(text: string, focused: boolean): string | null;
}
/**
 * Bridge native X11 selection to CLIPBOARD only in this process's terminal window.
 * No mouse capture: selection, right-click and scrollback stay with the terminal.
 * Unsupported desktops keep their terminal's native copy behavior.
 */
export declare function startSelectionCopy(onCopy: (count: number) => void): () => void;
/**
 * Put text on the clipboard by asking the terminal, rather than the operating system.
 *
 * OSC 52 is handed to the terminal in the output stream, so it is the one copy that works over
 * SSH: the text reaches the clipboard of the machine the person is sitting at, not the machine
 * the process is running on. That is the common case here — a Raspberry Pi reached from a laptop
 * — where writing to a clipboard on the far end would put the text somewhere nobody can paste
 * from.
 *
 * Best-effort by nature. A terminal that does not implement it ignores the sequence, and some
 * implement it but refuse writes until switched on. There is nothing to detect and no reply to
 * wait for, so the caller can only say what it attempted.
 */
export declare function copyViaTerminal(text: string, stream?: {
    write?: (s: string) => unknown;
}): boolean;
//# sourceMappingURL=clipboard.d.ts.map