import { useEventBus } from "./useEventBus";
import type { EventPayload } from "@almadar/core";
/**
 * Hook to bridge UI events to state machine dispatch.
 *
 * @param dispatch - The state machine dispatch function
 * @param traitName - Owning trait name; used to construct the qualified
 *   subscription key `UI:{traitName}.{event}`. Required — bare-key
 *   subscriptions were removed when the bus namespace unified on the
 *   listens grammar (gap #13, Phase 4 of the cross-orbital plan).
 * @param validEvents - Local event names (transition triggers) the
 *   trait reacts to. The hook subscribes to `UI:{traitName}.{event}`
 *   for each entry.
 * @param eventBusInstance - Optional event bus instance (for testing)
 */
export declare function useUIEvents<E extends string>(dispatch: (event: E, payload?: EventPayload) => void, traitName: string, validEvents: readonly E[], eventBusInstance?: ReturnType<typeof useEventBus>): void;
/**
 * Hook to subscribe to cross-trait listens (gap #13, Phase 4 codegen).
 *
 * The schema's `listens { Source EVENT -> TRIGGER }` block resolves at
 * lower-time to a typed `ListenSource` enum (intra-orbital `Trait` or
 * cross-orbital `Orbital.Trait`). Codegen materializes one
 * `useTraitListens` call per trait, listing every `(sourceTrait,
 * sourceEvent, localTrigger)` tuple from the listens block. The hook
 * subscribes to the qualified bus key — `UI:Trait.EVENT` (intra-orbital)
 * or `UI:Orbital.Trait.EVENT` (cross-orbital) — and dispatches the
 * local trigger when the source fires.
 *
 * Replaces the old bare-event cross-trait fan-out that lived inside
 * `useUIEvents`. Pre-unification, `useUIEvents` subscribed to bare
 * `EVENT` keys and matched on `source.trait !== own`; post-unification,
 * the qualified bus key carries the source identity directly, no
 * `source` filtering needed.
 */
export interface TraitListenSpec<E extends string> {
    /** Qualified `Trait.EVENT` or `Orbital.Trait.EVENT` source. */
    sourceKey: string;
    /** Local trigger event to dispatch when the source fires. */
    trigger: E;
}
export declare function useTraitListens<E extends string>(dispatch: (event: E, payload?: EventPayload) => void, listens: readonly TraitListenSpec<E>[], eventBusInstance?: ReturnType<typeof useEventBus>): void;
