@almadar/ui 5.79.1 → 5.80.0

package/dist/hooks/useGitHub.d.ts

@@ -0,0 +1,58 @@
+/**
+ * GitHub connection status
+ */
+export interface GitHubStatus {
+    connected: boolean;
+    username?: string;
+    avatarUrl?: string;
+    scopes?: string[];
+    connectedAt?: number;
+    lastUsedAt?: number;
+}
+/**
+ * GitHub repository
+ */
+export interface GitHubRepo {
+    id: number;
+    name: string;
+    fullName: string;
+    owner: string;
+    isPrivate: boolean;
+    description: string | null;
+    defaultBranch: string;
+    url: string;
+}
+/**
+ * Hook to get GitHub connection status
+ */
+export declare function useGitHubStatus(): import("@tanstack/react-query").UseQueryResult<GitHubStatus, Error>;
+/**
+ * Hook to connect GitHub (initiate OAuth flow)
+ */
+export declare function useConnectGitHub(): {
+    connectGitHub: () => void;
+};
+/**
+ * Hook to disconnect GitHub
+ */
+export declare function useDisconnectGitHub(): import("@tanstack/react-query").UseMutationResult<unknown, Error, void, unknown>;
+/**
+ * Hook to list GitHub repositories
+ */
+export declare function useGitHubRepos(page?: number, perPage?: number): import("@tanstack/react-query").UseQueryResult<{
+    repos: GitHubRepo[];
+    page: number;
+    perPage: number;
+}, Error>;
+/**
+ * Hook to get repository details
+ */
+export declare function useGitHubRepo(owner: string, repo: string, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<{
+    repo: GitHubRepo;
+}, Error>;
+/**
+ * Hook to list repository branches
+ */
+export declare function useGitHubBranches(owner: string, repo: string, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<{
+    branches: string[];
+}, Error>;

package/dist/hooks/useInfiniteScroll.d.ts

@@ -0,0 +1,13 @@
+export interface InfiniteScrollOptions {
+    /** Root margin for IntersectionObserver (default: "200px") */
+    rootMargin?: string;
+    /** Whether more items are available to load */
+    hasMore?: boolean;
+    /** Whether a load is currently in progress */
+    isLoading?: boolean;
+}
+export interface InfiniteScrollResult {
+    /** Ref to attach to the sentinel element */
+    sentinelRef: React.RefCallback<HTMLElement>;
+}
+export declare function useInfiniteScroll(onLoadMore: () => void, options?: InfiniteScrollOptions): InfiniteScrollResult;

package/dist/hooks/useLongPress.d.ts

@@ -0,0 +1,16 @@
+import type React from 'react';
+export interface LongPressOptions {
+    /** Hold duration in ms before triggering (default: 500) */
+    duration?: number;
+    /** Movement tolerance in px before canceling (default: 10) */
+    moveThreshold?: number;
+}
+export interface LongPressHandlers {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: () => void;
+    onPointerCancel: () => void;
+    /** Whether the long press is currently active (held down, timer running) */
+    isPressed: boolean;
+}
+export declare function useLongPress(onLongPress: () => void, options?: LongPressOptions): LongPressHandlers;

package/dist/hooks/useOrbitalHistory.d.ts

@@ -0,0 +1,39 @@
+import type { OrbitalSchema } from '@almadar/core';
+export interface HistoryChangeSummary {
+    added: number;
+    modified: number;
+    removed: number;
+}
+export interface HistoryTimelineItem {
+    id: string;
+    type: 'changeset' | 'snapshot';
+    version: number;
+    timestamp: number;
+    description: string;
+    source?: string;
+    summary?: HistoryChangeSummary;
+    reason?: string;
+}
+export interface RevertResult {
+    success: boolean;
+    error?: string;
+    restoredSchema?: OrbitalSchema;
+}
+export interface UseOrbitalHistoryOptions {
+    appId: string | null;
+    /** Firebase auth token for authenticated API requests */
+    authToken?: string | null;
+    /** User ID for x-user-id header (required for Firestore path) */
+    userId?: string | null;
+    onHistoryChange?: (timeline: HistoryTimelineItem[]) => void;
+    onRevertSuccess?: (restoredSchema: OrbitalSchema) => void;
+}
+export interface UseOrbitalHistoryResult {
+    timeline: HistoryTimelineItem[];
+    currentVersion: number;
+    isLoading: boolean;
+    error: string | null;
+    revertToSnapshot: (snapshotId: string) => Promise<RevertResult>;
+    refresh: () => Promise<void>;
+}
+export declare function useOrbitalHistory(options: UseOrbitalHistoryOptions): UseOrbitalHistoryResult;

package/dist/hooks/usePreview.d.ts

@@ -0,0 +1,57 @@
+import type { OrbitalSchema } from '@almadar/core';
+export interface PreviewApp {
+    id: string;
+    name: string;
+    status: 'loading' | 'ready' | 'error';
+    schema?: OrbitalSchema;
+    graphView: {
+        version: string;
+    };
+}
+export interface Notification {
+    id: string;
+    type: 'info' | 'warning' | 'error' | 'success';
+    title: string;
+    message: string;
+    timestamp: number;
+    read?: boolean;
+    actionLabel?: string;
+    onAction?: () => void;
+    autoDismiss?: boolean;
+    dismissAfter?: number;
+}
+export interface NotificationsState {
+    notifications: Notification[];
+    isPanelOpen: boolean;
+    closePanel: () => void;
+    dismissNotification: (id: string) => void;
+    markAsRead: (id: string) => void;
+    clearAll: () => void;
+}
+export interface ErrorToast {
+    message: string;
+}
+export interface UsePreviewResult {
+    previewUrl: string | null;
+    isLoading: boolean;
+    error: string | null;
+    loadError: string | null;
+    app: PreviewApp | null;
+    isFullscreen: boolean;
+    isExecutingEvent: boolean;
+    errorToast: ErrorToast | null;
+    currentStateName: string | null;
+    notifications: NotificationsState;
+    startPreview: () => Promise<void>;
+    stopPreview: () => Promise<void>;
+    refresh: () => Promise<void>;
+    handleRefresh: () => Promise<void>;
+    handleReset: () => Promise<void>;
+    toggleFullscreen: () => void;
+    setErrorToast: (toast: ErrorToast | null) => void;
+    dismissErrorToast: () => void;
+}
+export interface UsePreviewOptions {
+    appId?: string;
+}
+export declare function usePreview(options?: UsePreviewOptions): UsePreviewResult;

package/dist/hooks/usePullToRefresh.d.ts

@@ -0,0 +1,25 @@
+import type React from 'react';
+export interface PullToRefreshOptions {
+    /** Distance in px to pull before triggering refresh (default: 60) */
+    threshold?: number;
+    /** Maximum pull distance in px (default: 120) */
+    maxPull?: number;
+}
+export interface PullToRefreshResult {
+    /** Current pull distance in px */
+    pullDistance: number;
+    /** Whether the user is actively pulling */
+    isPulling: boolean;
+    /** Whether a refresh was triggered and is in progress */
+    isRefreshing: boolean;
+    /** Props to spread on the scrollable container */
+    containerProps: {
+        onTouchStart: (e: React.TouchEvent) => void;
+        onTouchMove: (e: React.TouchEvent) => void;
+        onTouchEnd: () => void;
+        style: React.CSSProperties;
+    };
+    /** Call this when the refresh operation completes */
+    endRefresh: () => void;
+}
+export declare function usePullToRefresh(onRefresh: () => void, options?: PullToRefreshOptions): PullToRefreshResult;

package/dist/hooks/useQuerySingleton.d.ts

@@ -0,0 +1,79 @@
+import type { FieldValue } from '@almadar/core';
+/**
+ * Query state for filters and search
+ */
+export interface QueryState {
+    search?: string;
+    filters?: Record<string, FieldValue>;
+    sortField?: string;
+    sortDirection?: 'asc' | 'desc';
+}
+/**
+ * Query singleton entity reference
+ */
+export interface QuerySingletonEntity {
+    name: string;
+    fields: Record<string, FieldValue>;
+}
+/**
+ * Query singleton result type
+ */
+export interface QuerySingletonResult {
+    state: QueryState;
+    setState: (state: Partial<QueryState>) => void;
+    reset: () => void;
+}
+export interface QuerySingletonState {
+    /** Current search term */
+    search: string;
+    /** Set search term */
+    setSearch: (value: string) => void;
+    /** Current filters */
+    filters: Record<string, FieldValue>;
+    /** Set a filter value */
+    setFilter: (key: string, value: FieldValue) => void;
+    /** Clear all filters */
+    clearFilters: () => void;
+    /** Current sort field */
+    sortField?: string;
+    /** Current sort direction */
+    sortDirection?: 'asc' | 'desc';
+    /** Set sort */
+    setSort: (field: string, direction: 'asc' | 'desc') => void;
+}
+/**
+ * Hook for accessing a query singleton by name
+ *
+ * @param query - Query singleton name (e.g., "@TaskQuery")
+ * @returns Query singleton state or null if no query provided
+ *
+ * @example
+ * ```tsx
+ * const queryState = useQuerySingleton('@TaskQuery');
+ *
+ * // Use search state
+ * queryState?.search
+ * queryState?.setSearch('new search term')
+ * ```
+ */
+export declare function useQuerySingleton(query?: string): QuerySingletonState | null;
+/**
+ * Parse a query binding string to extract the query singleton name
+ *
+ * @param binding - Binding string like "@TaskQuery.search" or "@TaskQuery"
+ * @returns Object with query name and optional field path
+ *
+ * @example
+ * ```tsx
+ * parseQueryBinding('@TaskQuery.search')
+ * // { query: 'TaskQuery', field: 'search' }
+ *
+ * parseQueryBinding('@TaskQuery')
+ * // { query: 'TaskQuery', field: undefined }
+ * ```
+ */
+export declare function parseQueryBinding(binding: string): {
+    query: string;
+    field?: string;
+};
+export default useQuerySingleton;

package/dist/hooks/useRenderInterpolation.d.ts

@@ -0,0 +1,33 @@
+export interface Positioned {
+    id: string;
+    x: number;
+    y: number;
+}
+export interface RenderInterpolationOptions {
+    /** Expected tick interval in ms (default: 1000/30 ≈ 33.3ms) */
+    tickIntervalMs?: number;
+}
+export interface RenderInterpolationHandle<T extends Positioned> {
+    /** Call when a new authoritative snapshot arrives from the model */
+    onSnapshot: (entities: readonly T[]) => void;
+    /** Returns interpolated positions for the current rAF timestamp; falls back to authoritative values */
+    getInterpolated: (now: number) => Map<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Start the rAF loop; call the supplied draw fn on every frame */
+    startLoop: (draw: (positions: Map<string, {
+        x: number;
+        y: number;
+    }>) => void) => () => void;
+}
+/**
+ * Fixed-timestep render interpolation between the last two authoritative model snapshots.
+ *
+ * Buffers two snapshots. On each rAF frame computes
+ *   alpha = clamp((now - lastArrival) / tickIntervalMs, 0, 1)
+ * and lerps x/y between prev and curr, matched by entity id.
+ * New or removed entities fall back to their authoritative value directly.
+ * Never throws; never causes a React re-render per frame.
+ */
+export declare function useRenderInterpolation<T extends Positioned>(options?: RenderInterpolationOptions): RenderInterpolationHandle<T>;

package/dist/hooks/useResolvedSchema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * useResolvedSchema Hook
+ *
+ * Resolves OrbitalSchema to IR for the OrbitalRuntime.
+ * Uses the shared resolver to ensure consistency with the compiler.
+ *
+ * TRAIT-DRIVEN ARCHITECTURE:
+ * - Pages have traits, NOT sections
+ * - UI is produced by trait effects (render_ui)
+ * - No backwards compatibility with legacy formats
+ *
+ * @packageDocumentation
+ */
+import type { OrbitalSchema } from '@almadar/core';
+import type { ResolvedIR, ResolvedPage, ResolvedTrait, ResolvedEntity, ResolvedTraitBinding } from '../types/runtime-types';
+export interface ResolvedSchemaResult {
+    /** The resolved page (or undefined if not found) */
+    page: ResolvedPage | undefined;
+    /** Trait bindings for this page */
+    traits: ResolvedTraitBinding[];
+    /** Entities used by this page */
+    entities: Map<string, ResolvedEntity>;
+    /** All entities from schema */
+    allEntities: Map<string, ResolvedEntity>;
+    /** All resolved traits */
+    allTraits: Map<string, ResolvedTrait>;
+    /** Loading state */
+    loading: boolean;
+    /** Error message if resolution failed */
+    error: string | null;
+    /** Full IR (for debugging) */
+    ir: ResolvedIR | null;
+}
+/**
+ * Hook to resolve an OrbitalSchema to IR.
+ *
+ * @param schema - The OrbitalSchema to resolve
+ * @param pageName - Optional page name (defaults to first page or initial page)
+ * @returns Resolved schema data including page, traits, and entities
+ */
+export declare function useResolvedSchema(schema: OrbitalSchema | null | undefined, pageName?: string): ResolvedSchemaResult;
+/**
+ * Clear the schema resolution cache
+ */
+export declare function clearSchemaCache(): void;

package/dist/hooks/useSwipeGesture.d.ts

@@ -0,0 +1,26 @@
+export interface SwipeGestureOptions {
+    /** Minimum distance in px to trigger a swipe (default: 50) */
+    threshold?: number;
+    /** Minimum velocity in px/ms to qualify (default: 0.3) */
+    velocityThreshold?: number;
+    /** Prevent default touch behavior during swipe (default: false) */
+    preventDefault?: boolean;
+}
+export interface SwipeGestureResult {
+    onSwipeLeft?: () => void;
+    onSwipeRight?: () => void;
+    onSwipeUp?: () => void;
+    onSwipeDown?: () => void;
+}
+export interface SwipeHandlers {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+    onPointerCancel: (e: React.PointerEvent) => void;
+    /** Current horizontal offset during swipe (for animation) */
+    offsetX: number;
+    /** Whether a swipe gesture is in progress */
+    isSwiping: boolean;
+}
+import type React from 'react';
+export declare function useSwipeGesture(callbacks: SwipeGestureResult, options?: SwipeGestureOptions): SwipeHandlers;

package/dist/hooks/useTapReveal.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Hover-only reveals (tooltips, hover-popovers, submenus, `Box.hoverEvent`) have no hover on
+ * touch, so they're invisible/unreachable. This adds the tap-to-reveal fallback: on a touch/pen
+ * tap the surface reveals and fires the SAME event the hover path fires; a tap outside dismisses.
+ * Mouse is left to the component's existing hover handlers (`pointerType === 'mouse'` is ignored),
+ * so this is purely additive — no behavior change on desktop.
+ */
+export interface TapRevealOptions {
+    /** Fired when a tap reveals — reuse to emit the component's existing hover event. */
+    onReveal?: () => void;
+    /** Fired when an outside tap (or a second trigger tap) dismisses. */
+    onDismiss?: () => void;
+    /**
+     * Elements considered "inside" for outside-tap detection. Pass the trigger and the surface
+     * (the surface may be portaled, so it isn't a DOM descendant of the trigger). A tap whose
+     * target is inside none of these dismisses.
+     */
+    refs?: ReadonlyArray<React.RefObject<HTMLElement | null>>;
+    /** When false, taps are ignored (hover-only). Default true. */
+    enabled?: boolean;
+}
+export interface TapRevealResult {
+    /** Whether the surface is currently revealed via a tap. OR this with the hover state. */
+    revealed: boolean;
+    /** Spread on the trigger; toggles reveal on a touch/pen tap (ignores mouse). */
+    triggerProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+    };
+    reveal: () => void;
+    dismiss: () => void;
+}
+export declare function useTapReveal(options?: TapRevealOptions): TapRevealResult;

package/dist/hooks/useTraitStateMachine.d.ts

@@ -0,0 +1,105 @@
+/**
+ * useTraitStateMachine Hook
+ *
+ * Manages trait state machines with event-driven transitions.
+ * Subscribes to eventBus events and executes effects when transitions occur.
+ *
+ * CONSOLIDATED RUNTIME:
+ * - Uses StateMachineManager from @almadar/runtime for state management
+ * - Uses the same state machine logic as the server runtime (OrbitalServerRuntime)
+ * - Ensures consistent behavior between client preview and server execution
+ *
+ * SLOT MANAGEMENT:
+ * - Collects all render-ui effects from a transition, groups by slot
+ * - Sets each slot's patterns array atomically via SlotsActions
+ * - No stacking logic, no priority system — transition produces complete slot content
+ *
+ * @packageDocumentation
+ */
+import type { EventPayload, ServiceParams } from '@almadar/core';
+import { type TraitState } from '@almadar/runtime';
+import type { ResolvedTraitBinding } from '../types/runtime-types';
+import type { useUISlots } from '../providers/UISlotContext';
+export type { TraitState };
+export interface TraitStateMachineResult {
+    /** Current state for each trait */
+    traitStates: Map<string, TraitState>;
+    /** Send an event to trigger a transition */
+    sendEvent: (eventKey: string, payload?: EventPayload) => void;
+    /** Get current state for a specific trait */
+    getTraitState: (traitName: string) => TraitState | undefined;
+    /** Check if a trait can handle an event from its current state */
+    canHandleEvent: (traitName: string, eventKey: string) => boolean;
+}
+export interface UseTraitStateMachineOptions {
+    /**
+     * Callback invoked after each event is processed (for server forwarding).
+     *
+     * `dispatchedOrbitals` is the set of orbital names whose traits actually
+     * executed a transition for this event. The server-bridge fan-out should
+     * be scoped to this set; sending the event to other orbitals fires
+     * same-named transitions in unrelated orbitals and stacks their UI into
+     * the wrong slot (gap #11 in `docs/Almadar_Std_Verification.md`). Empty
+     * set means no local transition matched — leave the legacy fallback to
+     * the consumer.
+     */
+    onEventProcessed?: (eventKey: string, payload?: EventPayload, dispatchedOrbitals?: Set<string>) => void | Promise<void>;
+    /** Router navigate function for navigate effects */
+    navigate?: (path: string, params?: Record<string, string>) => void;
+    /** Notification function for notify effects */
+    notify?: (message: string, type?: 'success' | 'error' | 'warning' | 'info') => void;
+    /**
+     * Offline-preview persistence layer. When set, the client runtime merges
+     * `@almadar/runtime` `createServerEffectHandlers` on top of the default
+     * client handlers so `fetch` / `persist` / `set` / `ref` / `deref` /
+     * `swap!` / `atomic` / `callService` run against this adapter — matching
+     * what `OrbitalServerRuntime` would do on the server. Left unset in the
+     * server-bridge path; effects there flow to the real server.
+     */
+    persistence?: import('@almadar/runtime').PersistenceAdapter;
+    /** Optional consumer `call-service` hook forwarded to the mock server handlers. */
+    callService?: (service: string, action: string, params?: ServiceParams) => Promise<EventPayload>;
+    /**
+     * Trait configs keyed by trait name. Threaded into setTraitConfig so
+     * `@config.X` resolves inside guard expressions on the client. Page-level
+     * `ResolvedTraitBinding`s often arrive without a config (the orbital-level
+     * config doesn't propagate through `@almadar/core`'s page resolver), so the
+     * caller assembles this map from the orbital schema directly.
+     */
+    traitConfigsByName?: Record<string, import('@almadar/core').TraitConfig>;
+    /**
+     * Trait → orbital map built from `schema.orbitals[].traits[]` by the
+     * caller. Threaded down so bus emits (`UI:Orbital.Trait.Event`) and
+     * subscriptions can carry the qualified `Orbital.Trait` scope —
+     * gap #13 unification. Same mechanism as `traitConfigsByName`: the
+     * orbital boundary doesn't propagate through `@almadar/core`'s
+     * `ResolvedTraitBinding`, so the caller assembles the map directly.
+     */
+    orbitalsByTrait?: Record<string, string>;
+    /**
+     * Set of trait names referenced via `@trait.X` by some sibling
+     * layout in the resolved schema. Slot writes from these traits go
+     * to the per-trait sidecar via `uiSlots.updateTraitContent`; the
+     * layout owns the slot and embeds via `<TraitFrame>`. Mirrors
+     * compiled-path codegen semantics.
+     */
+    embeddedTraits?: ReadonlySet<string>;
+}
+/**
+ * useTraitStateMachine - Manages state machines for multiple traits
+ *
+ * Uses the shared StateMachineManager for consistent behavior with server runtime.
+ * Collects render-ui effects per transition and sets slot content atomically.
+ *
+ * Slot writes go directly to `useUISlots` (the canonical store the DOM
+ * reads from) instead of routing through the now-removed `SlotsContext`
+ * + `SlotBridge` mirror. Trait names listed in `embeddedTraits` are
+ * referenced via `@trait.X` by some sibling layout's render-ui — for
+ * those, slot writes update the per-trait sidecar (via
+ * `updateTraitContent`) so `<TraitFrame>` can pick them up without the
+ * atom landing as a separate slot source. Mirrors compiled-path
+ * codegen, where atom views are inlined as JSX inside the layout's
+ * pattern rather than each writing a shared slot.
+ */
+export declare function useTraitStateMachine(traitBindings: ResolvedTraitBinding[], uiSlots: ReturnType<typeof useUISlots>, options?: UseTraitStateMachineOptions): TraitStateMachineResult;
+export default useTraitStateMachine;

package/dist/hooks/useTranslate.d.ts

@@ -0,0 +1,35 @@
+export type TranslateFunction = (key: string, params?: Record<string, string | number>) => string;
+export interface I18nContextValue {
+    /** Current locale code (e.g. 'en', 'ar', 'sl') */
+    locale: string;
+    /** Text direction for the current locale */
+    direction: 'ltr' | 'rtl';
+    /** Translate a key, with optional interpolation params */
+    t: TranslateFunction;
+}
+/**
+ * Provider component — wrap your app or Storybook decorator with this.
+ *
+ * ```tsx
+ * <I18nProvider value={{ locale: 'ar', direction: 'rtl', t: createTranslate(arMessages) }}>
+ *   <App />
+ * </I18nProvider>
+ * ```
+ */
+export declare const I18nProvider: import("react").Provider<I18nContextValue>;
+/**
+ * Hook to access the current locale and translate function.
+ * Safe to call without a provider — returns passthrough t().
+ */
+export declare function useTranslate(): I18nContextValue;
+/**
+ * Create a translate function from a flat messages object.
+ *
+ * ```ts
+ * const t = createTranslate({ 'common.save': 'Save', 'table.showing': 'Showing {{count}} of {{total}}' });
+ * t('common.save') // → 'Save'
+ * t('table.showing', { count: 5, total: 20 }) // → 'Showing 5 of 20'
+ * t('missing.key') // → 'missing.key' (fallback)
+ * ```
+ */
+export declare function createTranslate(messages: Record<string, string>): TranslateFunction;

package/dist/hooks/useUIEvents.d.ts

@@ -0,0 +1,41 @@
+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;