import type { VisualIntent } from "./gpu/ca-compositor.js";
export type NativeIntentMessage = {
    type: "intent";
    /** CA family NAME (identity|shimmer|reaction|flow|life|chaos). */
    family?: string;
    energy?: number;
    palette?: string;
    paletteMix?: number;
    dim?: number;
};
export type NativeMediaMessage = {
    type: "media";
    path: string;
    fit?: "cover" | "contain";
};
export type NativeClearMediaMessage = {
    type: "clear_media";
};
export type NativeChatReserveMessage = {
    type: "chat_reserve";
    rows: number;
};
export type NativeScreenshotMessage = {
    type: "screenshot";
    path: string;
};
export type NativeMessage = NativeIntentMessage | NativeMediaMessage | NativeClearMediaMessage | NativeChatReserveMessage | NativeScreenshotMessage;
/** An inbound mouse event from the koi-term window (see module doc). */
export type NativeMouseEvent = {
    type: "mouse";
    kind: "move" | "down" | "up" | "scroll";
    /** Physical window pixels. */
    x: number;
    y: number;
    /** PTY-grid cells; row 0 = top of the chat strip, negative above it. */
    col: number;
    row: number;
    /** Only on down/up. */
    button?: "left" | "right" | "middle";
    /** Only on scroll: lines, >0 = up. */
    dy?: number;
};
/** All inbound events the window can stream (mouse today; more later). */
export type NativeEvent = NativeMouseEvent;
/**
 * Subscribe to the window's inbound event stream (mouse). Returns the
 * unsubscribe. Events only ever flow while a koi-term connection is up —
 * outside the native window this never fires.
 */
export declare function onNativeEvent(listener: (evt: NativeEvent) => void): () => void;
/**
 * Whether the koi-term native window is reachable: KOI_TERM_SOCK is set and
 * the socket exists (or we're already connected). Synchronous — this gates
 * protocol detection, so it must never wait on I/O.
 */
export declare function hasNativeWindow(env?: NodeJS.ProcessEnv): boolean;
/**
 * Send one message to the native window, fire-and-forget. Lazily connects on
 * first use, buffers while the connect is in flight, and reconnects after a
 * drop. Returns whether the message was written or queued.
 */
export declare function sendNative(msg: NativeMessage, env?: NodeJS.ProcessEnv): boolean;
/**
 * Build the wire intent from a normalized VisualIntent: family travels as the
 * STRING family name (koi-term resolves names natively); numeric inputs map
 * back to their name and unknown families are dropped. Zeros pass through
 * (energy:0 IS "still").
 */
export declare function nativeIntentMessage(intent: VisualIntent, extra?: {
    dim?: number;
}): NativeIntentMessage;
/** Send a VisualIntent to the native window (fire-and-forget). */
export declare function sendNativeIntent(intent: VisualIntent, extra?: {
    dim?: number;
}): boolean;
/**
 * Ask the koi-term window for a permission-free GPU frame dump to `path`
 * (verification tooling / "what does my canvas look like" checks).
 * Fire-and-forget like everything else on this socket.
 */
export declare function nativeScreenshot(path: string): boolean;
/** Drop the connection and clear all state (tests + teardown). */
export declare function resetNativeWindow(): void;