import { type ScreenshotCaptureMeta, type ScreenshotDisplayInfo, type ScreenshotDisplaySelector } from "@aicommander/protocol";
export interface CapturedScreenshot {
    /** Raw image bytes. */
    data: Buffer;
    /** MIME type of `data` (always image/png today). */
    mimeType: string;
    /**
     * What was ACTUALLY captured — echoed to the relay so the caller is told which
     * display it is looking at rather than which one it asked for. Never inferred
     * from the request: `width`/`height` are read out of the returned PNG itself,
     * and `display` is OMITTED whenever the machine could not establish which
     * display the returned pixels belong to (see confirmMacDisplay). An absent
     * `display` means "unknown", never "display 0".
     */
    meta: ScreenshotCaptureMeta;
}
export interface ScreenshotOptions {
    /**
     * 0-based display index, or "all" for the whole virtual desktop. Omitted means
     * the primary display — and, deliberately, the byte-for-byte SAME capture
     * command this module has always run, so the default path cannot regress.
     */
    display?: ScreenshotDisplaySelector;
    /**
     * Displays the caller already knows about. The desktop app passes Electron's
     * `screen.getAllDisplays()`, which is instant; without it macOS falls back to
     * a `system_profiler` probe that costs a second or two (see listDisplays).
     * Windows ignores this — its capture script enumerates authoritatively itself.
     */
    displays?: ScreenshotDisplayInfo[];
}
/** True on platforms where we know how to grab the screen (desktop mac/win). */
export declare function canCaptureScreenshot(): boolean;
/**
 * Capture a display as a PNG using the OS's built-in tooling — no native
 * dependencies. macOS uses `screencapture`; Windows shells out to PowerShell +
 * System.Drawing. Throws on any other platform (headless Linux), on capture
 * failure, on an out-of-range display index, or if the result exceeds
 * SCREENSHOT_MAX_BYTES.
 *
 * On macOS the capture requires the app to hold the "Screen Recording" (TCC)
 * permission; without it the system is documented to yield a black image rather
 * than an error, so the desktop app is responsible for prompting the user to
 * grant it — and the connection layer refuses to even call here when it knows
 * the grant is missing (a black rectangle is a worse answer than a sentence
 * saying why).
 */
export declare function captureScreenshot(options?: ScreenshotOptions): Promise<CapturedScreenshot>;
/** Drop the cached enumeration (tests, and any caller that knows it moved). */
export declare function resetDisplayCache(): void;
/**
 * Enumerate the machine's displays, primary first WHEN the OS said which one is
 * primary (see normalizeDisplays — we never elect one ourselves).
 *
 * Best-effort by design: it returns [] rather than throwing when the OS tooling
 * is unavailable or unparseable, because a failure to COUNT displays must never
 * prevent CAPTURING one. An empty list surfaces as "display count unknown" in
 * the reply — an honest gap, not a claim of one screen.
 */
export declare function listDisplays(): Promise<ScreenshotDisplayInfo[]>;
/**
 * Pixel size straight out of the PNG's IHDR chunk (bytes 16..24 of a valid PNG).
 * Cheap, dependency-free, and — unlike anything computed from the request — it
 * describes the bytes the caller actually receives. Returns null if the buffer
 * is not a PNG we recognise, so metadata degrades instead of lying.
 */
export declare function pngSize(data: Buffer): {
    width: number;
    height: number;
} | null;