/**
 * Types and type guards for flow state and lifecycle events.
 */
import type { CaptureInstanceFeedbackResponse, ListInstanceFeedbackMineResponse } from "../instance-feedback.js";
import { type WidgetFrameAppearance } from "./widget-frame-appearance.js";
import type { WidgetLayoutTimedTransitionPolicy, WidgetLayoutTransitionPolicy, WidgetLayoutTransitionSchedule } from "./widget-layout-transition-plan.js";
/** Durable flow render state: whether it is open, opening, and its dimensions (if known). */
export interface FlowRenderState {
    /** True when the flow is visible. */
    isOpen: boolean;
    /**
     * True after an open request while the flow is not visible yet. Background
     * prefetching or prerendering without open intent must not set this.
     */
    isLoading: boolean;
    /** Flow width in pixels when known. */
    width?: number;
    /** Flow height in pixels when known. */
    height?: number;
}
/** Legacy transport state whose transition policy may be retained and replayed. */
export interface FlowState extends FlowRenderState {
    /**
     * Optional host transition policy. This field does not identify a new
     * transition occurrence by itself; use FlowRenderState for durable state.
     */
    transitionPolicy?: WidgetLayoutTransitionPolicy;
}
export interface FlowStateChangedDetail extends FlowState {
    instanceId: string;
    flowHandleId: string;
}
/** One timed host-owned geometry occurrence. This detail is never replayed. */
export interface FlowLayoutUpdatedDetail {
    instanceId: string;
    flowHandleId: string;
    width: number;
    height: number;
    transitionPolicy: WidgetLayoutTimedTransitionPolicy;
}
export interface InstanceFlowStateChangedDetail extends FlowState {
    instanceId: string;
    /**
     * True when the host container should render for the aggregate instance state.
     * Older emitters omit this field; consumers should use
     * resolveInstanceFlowStateShouldRender to preserve the legacy isOpen/isLoading
     * behavior at compatibility boundaries.
     */
    shouldRender?: boolean;
    /** Flow handle for the currently pinned aggregate flow, when known. */
    flowHandleId?: string;
}
type ViewHostFrameAppearanceState = {
    /** Optional read-only runtime frame appearance serialized as theme CSS values. */
    frameAppearance?: WidgetFrameAppearance;
    /** @internal Shared identity and start time for one host/View transition. */
    transitionSchedule?: WidgetLayoutTransitionSchedule;
};
export type ViewHostFlowRunSnapshot = FlowState & ViewHostFrameAppearanceState & {
    kind: "flowRun";
    flowRunId: string;
    flowHandleId?: string;
};
export type ViewHostPendingFlowHandleSnapshot = FlowState & ViewHostFrameAppearanceState & {
    kind: "pendingFlowHandle";
    flowHandleId: string;
};
export type ViewHostSnapshot = ViewHostFlowRunSnapshot | ViewHostPendingFlowHandleSnapshot;
export interface InstanceViewHostSnapshotsChangedDetail {
    instanceId: string;
    /**
     * Active views in host priority order. Consumers that can present only one
     * view should use the first snapshot without discarding the remaining state.
     */
    snapshots: ViewHostSnapshot[];
}
export declare function areViewHostSnapshotsEqual(a: ViewHostSnapshot | undefined, b: ViewHostSnapshot | undefined): boolean;
export declare function cloneViewHostSnapshots<Snapshot extends ViewHostSnapshot>(snapshots: readonly Snapshot[]): Snapshot[];
export declare function resolveInstanceFlowStateShouldRender(detail: Pick<InstanceFlowStateChangedDetail, "isOpen" | "isLoading"> & {
    shouldRender?: boolean;
}): boolean;
export interface OpenRequestedDetail {
    instanceId: string;
    source: "command" | "targeting";
    flowId: string;
    flowHandleId?: string;
    hideCloseButton?: boolean;
}
/** @internal Trusted host-realm navigation adapter event. */
export declare const NAVIGATION_OUTCOMES: readonly ["succeeded", "failed", "unhandled"];
export type NavigationOutcome = (typeof NAVIGATION_OUTCOMES)[number];
export declare function isNavigationOutcome(value: unknown): value is NavigationOutcome;
export interface NavigationRequestedDetail {
    instanceId: string;
    url: string;
    /**
     * Requested browser target, resolved from the trusted served survey.
     * `_blank` is accepted only on the version 1 rollout event.
     */
    target?: "_blank" | "self" | "blank";
    /** Internal open-url action contract version. */
    version: number;
    /**
     * Synchronous one-shot outcome settlement when negotiated by capability.
     * Only the internal SDK adapter is intended to call this. The browser host
     * remains client-reported; this callback is not trusted execution attestation.
     */
    settle?: (outcome: NavigationOutcome) => void;
}
/** @internal Trusted host-realm adapter event emitted after Core authorization. */
export interface HostActionRequestedDetail {
    instanceId: string;
    definition: {
        key: string;
        version: number;
    };
    settle: (outcome: "success" | "failure" | "unavailable") => void;
}
export declare const HANDLE_INVALIDATED_REASON_CODES: readonly [
    "RESET",
    "CLOSED",
    "STALE_HANDLE",
    "OWNERSHIP_CONFLICT",
    "OWNER_DISPOSED",
    "UPSTREAM_INVALIDATED",
    "INTERNAL"
];
export type HandleInvalidatedReasonCode = (typeof HANDLE_INVALIDATED_REASON_CODES)[number];
export declare const HANDLE_INVALIDATED_SOURCES: readonly ["loader", "core"];
export type HandleInvalidatedSource = (typeof HANDLE_INVALIDATED_SOURCES)[number];
/** Generic handle lifecycle event emitted when a previously issued handle is invalidated upstream. */
export interface HandleInvalidatedDetail {
    instanceId: string;
    handleKind: string;
    handleId: string;
    reasonCode: HandleInvalidatedReasonCode;
    reasonMessage?: string;
    relatedRequestId?: string;
    source: HandleInvalidatedSource;
    at: number;
}
export declare function isFlowStateChangedDetail(detail: unknown): detail is FlowStateChangedDetail;
export declare function isFlowLayoutUpdatedDetail(detail: unknown): detail is FlowLayoutUpdatedDetail;
export declare function isInstanceFlowStateChangedDetail(detail: unknown): detail is InstanceFlowStateChangedDetail;
export declare function isViewHostSnapshot(snapshot: unknown): snapshot is ViewHostSnapshot;
export declare function isInstanceViewHostSnapshotsChangedDetail(detail: unknown): detail is InstanceViewHostSnapshotsChangedDetail;
export declare function isOpenRequestedDetail(detail: unknown): detail is OpenRequestedDetail;
export declare function isNavigationRequestedDetail(detail: unknown): detail is NavigationRequestedDetail;
export declare function isHostActionRequestedDetail(detail: unknown): detail is HostActionRequestedDetail;
export declare function isHandleInvalidatedDetail(detail: unknown): detail is HandleInvalidatedDetail;
export interface CommandSettledSuccessDetail {
    requestId: string;
    instanceId: string | null;
    kind: string;
    ok: true;
    result?: unknown;
}
export interface CommandSettledFailureDetail {
    requestId: string;
    instanceId: string | null;
    kind: string;
    ok: false;
    error: {
        message: string;
        code?: string;
    };
}
export type CommandSettledDetail = CommandSettledSuccessDetail | CommandSettledFailureDetail;
export declare function isCommandSettledDetail(detail: unknown): detail is CommandSettledDetail;
/** Result of extracting a flow handle from a successful open/prerender/prefetch settlement. */
export type FlowHandleFromSettlement = {
    flowHandleId: string;
    flowRunId?: string;
};
/**
 * Host-facing handle result: same shape as FlowHandleFromSettlement.
 * Used when projecting instance:command:settled so the SDK receives flowHandleId (and flowRunId when present).
 */
export type HostHandleSettlementResult = FlowHandleFromSettlement;
/**
 * Return the host-facing handle result for a command settlement, or null.
 * Use in the loader when projecting instance:command:settled; keeps the host contract in one place (no zod).
 */
export declare function getHostHandleResultFromSettlement(detail: {
    ok: boolean;
    kind: string;
    result?: unknown;
}): HostHandleSettlementResult | null;
/** Return a validated feedback receipt from a successful capture settlement. */
export declare function getFeedbackSubmissionFromSettlementDetail(detail: {
    ok: boolean;
    kind: string;
    result?: unknown;
}): CaptureInstanceFeedbackResponse | null;
/** Return a validated authenticated-feedback read result from a settlement. */
export declare function getFeedbackReadFromSettlementDetail(detail: {
    ok: boolean;
    kind: string;
    result?: unknown;
}): ListInstanceFeedbackMineResponse | null;
/**
 * Extract flow handle from a successful command settlement when the command
 * is one that can return a handle (open, prerender, prefetch). Uses plain
 * checks only (no Zod). Returns null if detail is not ok, kind is not one of
 * those, or result does not contain a non-empty flowHandleId.
 */
export declare function getFlowHandleFromSettlementDetail(detail: {
    ok: boolean;
    kind: string;
    result?: unknown;
}): FlowHandleFromSettlement | null;
/** Normalized allocation from a handle-returning settlement: handle + instanceId for state. */
export type FlowHandleAllocationFromSettlement = {
    flowHandleId: string;
    flowRunId: string | null;
    instanceId: string | null;
};
/**
 * Parse a command settlement into a single allocation object when the command
 * returned a flow handle (open/prerender/prefetch). Returns null otherwise.
 */
export declare function getFlowHandleAllocationFromSettlement(detail: {
    ok: boolean;
    kind: string;
    result?: unknown;
    instanceId?: string | null;
}): FlowHandleAllocationFromSettlement | null;
export {};
//# sourceMappingURL=host-event-contract.d.ts.map