@almadar/ui 3.0.1 → 3.1.3

package/dist/avl/index.cjs

@@ -2953,11 +2953,15 @@ function EventBusProvider({ children, debug: debug2 = false }) {
       deprecationWarningShown.current = true;
     }
   }, []);
-  const emit = React126.useCallback((type, payload) => {
+  const emit = React126.useCallback((type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit takes Record for ergonomics
+      // (generic UI components pass consumer-defined rows) while the envelope
+      // stores the payload as EventPayload for listeners.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const listeners6 = listenersRef.current.get(type);
     const listenerCount = (listeners6?.size ?? 0) + anyListenersRef.current.size;
@@ -3107,8 +3111,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return React126.useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );
@@ -3124,11 +3128,15 @@ var init_useEventBus = __esm({
     fallbackListeners = /* @__PURE__ */ new Map();
     fallbackAnyListeners = /* @__PURE__ */ new Set();
     fallbackEventBus = {
-      emit: (type, payload) => {
+      emit: (type, payload, source) => {
         const event = {
           type,
+          // Narrow at the bus boundary: public emit accepts an opaque object so
+          // generic UI emit sites don't require casts; the envelope stores the
+          // payload as EventPayload which listeners consume directly.
           payload,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          source
         };
         const handlers = fallbackListeners.get(type);
         log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -51143,6 +51151,9 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
     const currentState = traitStatesRef.current.get(binding.trait.name)?.currentState ?? "";
     if (tick.appliesTo.length > 0 && !tick.appliesTo.includes(currentState)) return;
     const bindingCtx = { entity: {}, payload: {}, state: currentState };
+    if (binding.config) {
+      bindingCtx.config = binding.config;
+    }
     const evalCtx = runtime.createContextFromBindings(bindingCtx);
     if (tick.guard !== void 0) {
       const passed = runtime.interpolateValue(tick.guard, evalCtx);
@@ -51275,6 +51286,9 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           payload: payload || {},
           state: result.previousState
         };
+        if (binding.config) {
+          bindingCtx.config = binding.config;
+        }
         const effectContext = {
           traitName: binding.trait.name,
           state: result.previousState,

package/dist/avl/index.js

@@ -2907,11 +2907,15 @@ function EventBusProvider({ children, debug: debug2 = false }) {
       deprecationWarningShown.current = true;
     }
   }, []);
-  const emit = useCallback((type, payload) => {
+  const emit = useCallback((type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit takes Record for ergonomics
+      // (generic UI components pass consumer-defined rows) while the envelope
+      // stores the payload as EventPayload for listeners.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const listeners6 = listenersRef.current.get(type);
     const listenerCount = (listeners6?.size ?? 0) + anyListenersRef.current.size;
@@ -3061,8 +3065,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );
@@ -3078,11 +3082,15 @@ var init_useEventBus = __esm({
     fallbackListeners = /* @__PURE__ */ new Map();
     fallbackAnyListeners = /* @__PURE__ */ new Set();
     fallbackEventBus = {
-      emit: (type, payload) => {
+      emit: (type, payload, source) => {
         const event = {
           type,
+          // Narrow at the bus boundary: public emit accepts an opaque object so
+          // generic UI emit sites don't require casts; the envelope stores the
+          // payload as EventPayload which listeners consume directly.
           payload,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          source
         };
         const handlers = fallbackListeners.get(type);
         log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -51097,6 +51105,9 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
     const currentState = traitStatesRef.current.get(binding.trait.name)?.currentState ?? "";
     if (tick.appliesTo.length > 0 && !tick.appliesTo.includes(currentState)) return;
     const bindingCtx = { entity: {}, payload: {}, state: currentState };
+    if (binding.config) {
+      bindingCtx.config = binding.config;
+    }
     const evalCtx = createContextFromBindings(bindingCtx);
     if (tick.guard !== void 0) {
       const passed = interpolateValue(tick.guard, evalCtx);
@@ -51229,6 +51240,9 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           payload: payload || {},
           state: result.previousState
         };
+        if (binding.config) {
+          bindingCtx.config = binding.config;
+        }
         const effectContext = {
           traitName: binding.trait.name,
           state: result.previousState,

package/dist/components/index.cjs

@@ -208,8 +208,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return React110.useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );
@@ -224,11 +224,15 @@ var init_useEventBus = __esm({
     fallbackListeners = /* @__PURE__ */ new Map();
     fallbackAnyListeners = /* @__PURE__ */ new Set();
     fallbackEventBus = {
-      emit: (type, payload) => {
+      emit: (type, payload, source) => {
         const event = {
           type,
+          // Narrow at the bus boundary: public emit accepts an opaque object so
+          // generic UI emit sites don't require casts; the envelope stores the
+          // payload as EventPayload which listeners consume directly.
           payload,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          source
         };
         const handlers = fallbackListeners.get(type);
         log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });

package/dist/components/index.js

@@ -163,8 +163,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );
@@ -179,11 +179,15 @@ var init_useEventBus = __esm({
     fallbackListeners = /* @__PURE__ */ new Map();
     fallbackAnyListeners = /* @__PURE__ */ new Set();
     fallbackEventBus = {
-      emit: (type, payload) => {
+      emit: (type, payload, source) => {
         const event = {
           type,
+          // Narrow at the bus boundary: public emit accepts an opaque object so
+          // generic UI emit sites don't require casts; the envelope stores the
+          // payload as EventPayload which listeners consume directly.
           payload,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          source
         };
         const handlers = fallbackListeners.get(type);
         log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });

package/dist/components/organisms/game/three/index.cjs

@@ -1436,11 +1436,15 @@ function getGlobalEventBus() {
 var fallbackListeners = /* @__PURE__ */ new Map();
 var fallbackAnyListeners = /* @__PURE__ */ new Set();
 var fallbackEventBus = {
-  emit: (type, payload) => {
+  emit: (type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit accepts an opaque object so
+      // generic UI emit sites don't require casts; the envelope stores the
+      // payload as EventPayload which listeners consume directly.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const handlers = fallbackListeners.get(type);
     log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -1503,8 +1507,8 @@ function useEventBus() {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return React21.useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );

package/dist/components/organisms/game/three/index.js

@@ -1412,11 +1412,15 @@ function getGlobalEventBus() {
 var fallbackListeners = /* @__PURE__ */ new Map();
 var fallbackAnyListeners = /* @__PURE__ */ new Set();
 var fallbackEventBus = {
-  emit: (type, payload) => {
+  emit: (type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit accepts an opaque object so
+      // generic UI emit sites don't require casts; the envelope stores the
+      // payload as EventPayload which listeners consume directly.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const handlers = fallbackListeners.get(type);
     log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -1479,8 +1483,8 @@ function useEventBus() {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );

package/dist/docs/index.cjs

@@ -2570,11 +2570,15 @@ function getGlobalEventBus() {
 var fallbackListeners = /* @__PURE__ */ new Map();
 var fallbackAnyListeners = /* @__PURE__ */ new Set();
 var fallbackEventBus = {
-  emit: (type, payload) => {
+  emit: (type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit accepts an opaque object so
+      // generic UI emit sites don't require casts; the envelope stores the
+      // payload as EventPayload which listeners consume directly.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const handlers = fallbackListeners.get(type);
     log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });

package/dist/docs/index.d.cts

@@ -295,7 +295,7 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
     /** onChange handler - accepts events from input, select, or textarea */
     onChange?: React.ChangeEventHandler<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>;
 }
-declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>>;
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>>;
 
 /**
  * DocSidebar Molecule Component

package/dist/docs/index.js

@@ -2546,11 +2546,15 @@ function getGlobalEventBus() {
 var fallbackListeners = /* @__PURE__ */ new Map();
 var fallbackAnyListeners = /* @__PURE__ */ new Set();
 var fallbackEventBus = {
-  emit: (type, payload) => {
+  emit: (type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit accepts an opaque object so
+      // generic UI emit sites don't require casts; the envelope stores the
+      // payload as EventPayload which listeners consume directly.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const handlers = fallbackListeners.get(type);
     log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });

package/dist/hooks/event-bus-types.d.ts

@@ -1,42 +1,34 @@
 /**
  * Event Bus Types
  *
- * Type definitions for the page event bus system.
+ * Re-exports from @almadar/core so every package agrees on the same
+ * bus event envelope. @almadar/ui no longer owns its own KFlowEvent —
+ * that type was folded into core's BusEvent.
  *
  * @packageDocumentation
  */
-/**
- * A KFlow event that can be emitted on the event bus.
- */
-export interface KFlowEvent {
-    /** Event type identifier (e.g., 'TASK_COMPLETED', 'VALIDATION_SUCCESS') */
-    type: string;
-    /** Optional payload data */
-    payload?: Record<string, unknown>;
-    /** Timestamp when the event was emitted */
-    timestamp: number;
-    /** Source trait or component that emitted the event */
-    source?: string;
-}
-/**
- * Event listener callback function.
- */
-export type EventListener = (event: KFlowEvent) => void;
-/**
- * Function to unsubscribe from events.
- */
-export type Unsubscribe = () => void;
+import type { BusEvent, BusEventSource, BusEventListener, Unsubscribe } from "@almadar/core";
+export type { BusEvent, BusEventSource, Unsubscribe };
+export type EventListener = BusEventListener;
 /**
  * Event bus context type.
+ *
+ * `emit` accepts `Record<string, unknown>` on its public surface so
+ * generic UI components (DataGrid, SortableList, ...) can pass
+ * consumer-defined row data without a cast at every emit site. The
+ * envelope stored in `BusEvent.payload` is narrowed to `EventPayload`
+ * inside the bus implementation — listeners always receive the typed
+ * shape.
  */
 export interface EventBusContextType {
     /**
      * Emit an event to all listeners.
      *
      * @param type - Event type identifier
-     * @param payload - Optional payload data
+     * @param payload - Optional payload data (object-shaped)
+     * @param source - Optional origin info (orbital/trait/...)
      */
-    emit: (type: string, payload?: Record<string, unknown>) => void;
+    emit: (type: string, payload?: Record<string, unknown>, source?: BusEventSource) => void;
     /**
      * Subscribe to an event type.
      *
@@ -44,7 +36,7 @@ export interface EventBusContextType {
      * @param listener - Callback function
      * @returns Unsubscribe function
      */
-    on: (type: string, listener: EventListener) => Unsubscribe;
+    on: (type: string, listener: BusEventListener) => Unsubscribe;
     /**
      * Subscribe to an event type, but only fire once.
      *
@@ -52,7 +44,7 @@ export interface EventBusContextType {
      * @param listener - Callback function
      * @returns Unsubscribe function
      */
-    once: (type: string, listener: EventListener) => Unsubscribe;
+    once: (type: string, listener: BusEventListener) => Unsubscribe;
     /**
      * Check if there are any listeners for an event type.
      *
@@ -67,5 +59,5 @@ export interface EventBusContextType {
      * @param listener - Callback function invoked for every emitted event
      * @returns Unsubscribe function
      */
-    onAny?: (listener: EventListener) => Unsubscribe;
+    onAny?: (listener: BusEventListener) => Unsubscribe;
 }

package/dist/hooks/index.cjs

@@ -935,11 +935,15 @@ function getGlobalEventBus() {
 var fallbackListeners = /* @__PURE__ */ new Map();
 var fallbackAnyListeners = /* @__PURE__ */ new Set();
 var fallbackEventBus = {
-  emit: (type, payload) => {
+  emit: (type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit accepts an opaque object so
+      // generic UI emit sites don't require casts; the envelope stores the
+      // payload as EventPayload which listeners consume directly.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const handlers = fallbackListeners.get(type);
     log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -1016,8 +1020,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return React.useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );

package/dist/hooks/index.d.ts

@@ -11,7 +11,7 @@ export { useAgentChat } from './useAgentChat';
 export { useValidation } from './useValidation';
 export { useDeepAgentGeneration } from './useDeepAgentGeneration';
 export { useEventBus, useEventListener, useEmitEvent } from './useEventBus';
-export type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType } from './event-bus-types';
+export type { BusEvent, BusEventSource, EventListener, Unsubscribe, EventBusContextType, } from './event-bus-types';
 export { useUISlotManager, DEFAULT_SLOTS, type UISlot, type SlotAnimation, type SlotContent, type RenderUIConfig, type SlotChangeCallback, type UISlotManager, } from './useUISlots';
 export { useUIEvents, useSelectedEntity } from './useUIEvents';
 export { useEntityList, useEntityDetail, useEntity, useEntityListSuspense, useEntitySuspense, entityDataKeys, EntityDataProvider, useEntityDataAdapter, type EntityDataAdapter, type EntityDataRecord, type UseEntityListOptions, type UseEntityListResult, type UseEntityDetailResult, } from './useEntityData';

package/dist/hooks/index.js

@@ -929,11 +929,15 @@ function getGlobalEventBus() {
 var fallbackListeners = /* @__PURE__ */ new Map();
 var fallbackAnyListeners = /* @__PURE__ */ new Set();
 var fallbackEventBus = {
-  emit: (type, payload) => {
+  emit: (type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit accepts an opaque object so
+      // generic UI emit sites don't require casts; the envelope stores the
+      // payload as EventPayload which listeners consume directly.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const handlers = fallbackListeners.get(type);
     log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -1010,8 +1014,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );

package/dist/hooks/useEventBus.d.ts

@@ -1,5 +1,5 @@
-import type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType } from './event-bus-types';
-export type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType };
+import type { BusEvent, BusEventSource, EventListener, Unsubscribe, EventBusContextType } from './event-bus-types';
+export type { BusEvent, BusEventSource, EventListener, Unsubscribe, EventBusContextType };
 declare global {
     interface Window {
         __kflowEventBus?: EventBusContextType | null;
@@ -92,5 +92,5 @@ export declare const useEventSubscription: typeof useEventListener;
  * };
  * ```
  */
-export declare function useEmitEvent(): (type: string, payload?: Record<string, unknown>) => void;
+export declare function useEmitEvent(): (type: string, payload?: Record<string, unknown>, source?: BusEventSource) => void;
 export default useEventBus;

package/dist/lib/verificationRegistry.d.ts

@@ -9,6 +9,7 @@
  *
  * @packageDocumentation
  */
+import type { BusEvent, EventPayload } from '@almadar/core';
 export type CheckStatus = "pass" | "fail" | "pending" | "warn";
 export interface VerificationCheck {
     id: string;
@@ -91,7 +92,7 @@ export type AssetLoadStatus = "loaded" | "failed" | "pending";
 /** Event bus log entry for verification */
 export interface EventLogEntry {
     type: string;
-    payload?: Record<string, unknown>;
+    payload?: EventPayload;
     timestamp: number;
 }
 /** Exposed on window for Playwright to query */
@@ -132,10 +133,7 @@ export declare function waitForTransition(event: string, timeoutMs?: number): Pr
  */
 export declare function bindEventBus(eventBus: {
     emit: (type: string, payload?: Record<string, unknown>) => void;
-    onAny?: (listener: (event: {
-        type: string;
-        payload?: Record<string, unknown>;
-    }) => void) => () => void;
+    onAny?: (listener: (event: BusEvent) => void) => () => void;
 }): void;
 /**
  * Bind a trait state getter so automation can query current states.

package/dist/marketing/index.cjs

@@ -2570,11 +2570,15 @@ function getGlobalEventBus() {
 var fallbackListeners = /* @__PURE__ */ new Map();
 var fallbackAnyListeners = /* @__PURE__ */ new Set();
 var fallbackEventBus = {
-  emit: (type, payload) => {
+  emit: (type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit accepts an opaque object so
+      // generic UI emit sites don't require casts; the envelope stores the
+      // payload as EventPayload which listeners consume directly.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const handlers = fallbackListeners.get(type);
     log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });

package/dist/marketing/index.js

@@ -2546,11 +2546,15 @@ function getGlobalEventBus() {
 var fallbackListeners = /* @__PURE__ */ new Map();
 var fallbackAnyListeners = /* @__PURE__ */ new Set();
 var fallbackEventBus = {
-  emit: (type, payload) => {
+  emit: (type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit accepts an opaque object so
+      // generic UI emit sites don't require casts; the envelope stores the
+      // payload as EventPayload which listeners consume directly.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const handlers = fallbackListeners.get(type);
     log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });

package/dist/providers/index.cjs

@@ -455,8 +455,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return React115.useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );
@@ -471,11 +471,15 @@ var init_useEventBus = __esm({
     fallbackListeners = /* @__PURE__ */ new Map();
     fallbackAnyListeners = /* @__PURE__ */ new Set();
     fallbackEventBus = {
-      emit: (type, payload) => {
+      emit: (type, payload, source) => {
         const event = {
           type,
+          // Narrow at the bus boundary: public emit accepts an opaque object so
+          // generic UI emit sites don't require casts; the envelope stores the
+          // payload as EventPayload which listeners consume directly.
           payload,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          source
         };
         const handlers = fallbackListeners.get(type);
         log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -38229,11 +38233,15 @@ function EventBusProvider({ children, debug: debug2 = false }) {
       deprecationWarningShown.current = true;
     }
   }, []);
-  const emit = React115.useCallback((type, payload) => {
+  const emit = React115.useCallback((type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit takes Record for ergonomics
+      // (generic UI components pass consumer-defined rows) while the envelope
+      // stores the payload as EventPayload for listeners.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const listeners6 = listenersRef.current.get(type);
     const listenerCount = (listeners6?.size ?? 0) + anyListenersRef.current.size;

package/dist/providers/index.js

@@ -410,8 +410,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );
@@ -426,11 +426,15 @@ var init_useEventBus = __esm({
     fallbackListeners = /* @__PURE__ */ new Map();
     fallbackAnyListeners = /* @__PURE__ */ new Set();
     fallbackEventBus = {
-      emit: (type, payload) => {
+      emit: (type, payload, source) => {
         const event = {
           type,
+          // Narrow at the bus boundary: public emit accepts an opaque object so
+          // generic UI emit sites don't require casts; the envelope stores the
+          // payload as EventPayload which listeners consume directly.
           payload,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          source
         };
         const handlers = fallbackListeners.get(type);
         log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -38184,11 +38188,15 @@ function EventBusProvider({ children, debug: debug2 = false }) {
       deprecationWarningShown.current = true;
     }
   }, []);
-  const emit = useCallback((type, payload) => {
+  const emit = useCallback((type, payload, source) => {
     const event = {
       type,
+      // Narrow at the bus boundary: public emit takes Record for ergonomics
+      // (generic UI components pass consumer-defined rows) while the envelope
+      // stores the payload as EventPayload for listeners.
       payload,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      source
     };
     const listeners6 = listenersRef.current.get(type);
     const listenerCount = (listeners6?.size ?? 0) + anyListenersRef.current.size;

package/dist/runtime/index.cjs

@@ -202,8 +202,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return React116.useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );
@@ -218,11 +218,15 @@ var init_useEventBus = __esm({
     fallbackListeners = /* @__PURE__ */ new Map();
     fallbackAnyListeners = /* @__PURE__ */ new Set();
     fallbackEventBus = {
-      emit: (type, payload) => {
+      emit: (type, payload, source) => {
         const event = {
           type,
+          // Narrow at the bus boundary: public emit accepts an opaque object so
+          // generic UI emit sites don't require casts; the envelope stores the
+          // payload as EventPayload which listeners consume directly.
           payload,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          source
         };
         const handlers = fallbackListeners.get(type);
         log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -37940,6 +37944,9 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
     const currentState = traitStatesRef.current.get(binding.trait.name)?.currentState ?? "";
     if (tick.appliesTo.length > 0 && !tick.appliesTo.includes(currentState)) return;
     const bindingCtx = { entity: {}, payload: {}, state: currentState };
+    if (binding.config) {
+      bindingCtx.config = binding.config;
+    }
     const evalCtx = runtime.createContextFromBindings(bindingCtx);
     if (tick.guard !== void 0) {
       const passed = runtime.interpolateValue(tick.guard, evalCtx);
@@ -38072,6 +38079,9 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           payload: payload || {},
           state: result.previousState
         };
+        if (binding.config) {
+          bindingCtx.config = binding.config;
+        }
         const effectContext = {
           traitName: binding.trait.name,
           state: result.previousState,

package/dist/runtime/index.js

@@ -157,8 +157,8 @@ function useEventListener(event, handler) {
 function useEmitEvent() {
   const eventBus = useEventBus();
   return useCallback(
-    (type, payload) => {
-      eventBus.emit(type, payload);
+    (type, payload, source) => {
+      eventBus.emit(type, payload, source);
     },
     [eventBus]
   );
@@ -173,11 +173,15 @@ var init_useEventBus = __esm({
     fallbackListeners = /* @__PURE__ */ new Map();
     fallbackAnyListeners = /* @__PURE__ */ new Set();
     fallbackEventBus = {
-      emit: (type, payload) => {
+      emit: (type, payload, source) => {
         const event = {
           type,
+          // Narrow at the bus boundary: public emit accepts an opaque object so
+          // generic UI emit sites don't require casts; the envelope stores the
+          // payload as EventPayload which listeners consume directly.
           payload,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          source
         };
         const handlers = fallbackListeners.get(type);
         log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
@@ -37895,6 +37899,9 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
     const currentState = traitStatesRef.current.get(binding.trait.name)?.currentState ?? "";
     if (tick.appliesTo.length > 0 && !tick.appliesTo.includes(currentState)) return;
     const bindingCtx = { entity: {}, payload: {}, state: currentState };
+    if (binding.config) {
+      bindingCtx.config = binding.config;
+    }
     const evalCtx = createContextFromBindings(bindingCtx);
     if (tick.guard !== void 0) {
       const passed = interpolateValue(tick.guard, evalCtx);
@@ -38027,6 +38034,9 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           payload: payload || {},
           state: result.previousState
         };
+        if (binding.config) {
+          bindingCtx.config = binding.config;
+        }
         const effectContext = {
           traitName: binding.trait.name,
           state: result.previousState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "3.0.1",
+  "version": "3.1.3",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",
@@ -118,10 +118,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": ">=5.1.0",
-    "@almadar/evaluator": ">=2.8.1",
+    "@almadar/core": ">=5.3.1",
+    "@almadar/evaluator": ">=2.9.2",
     "@almadar/patterns": ">=2.14.1",
-    "@almadar/runtime": ">=4.0.0",
+    "@almadar/runtime": ">=4.3.0",
     "@almadar/std": ">=6.4.1",
     "@almadar/syntax": ">=1.3.1",
     "@xyflow/react": "12.10.1",