OmegaChannel

Definition: Central event bus. All communication between agents, flows and the UI goes through the channel. The emitter does not know who is listening; this decouples logic from the UI. There should only be one channel instance per app (created in OmegaRuntime.bootstrap and injected via OmegaScope).

Example:

channel.emit(OmegaEvent.fromName(AppEvent.authLoginRequest, payload: creds));
channel.events.listen((e) {
  if (e.name == AppEvent.authLoginSuccess.name) {
    final user = e.payloadAs<User>();
    if (user != null) goToHome(user);
  }
});

OmegaEvent

Definition: Represents "something that happened" in the system. It has an id (unique), name (semantic, e.g. "auth.login.success") and payload (optional data). To avoid magic strings, define an enum that implements OmegaEventName and use OmegaEvent.fromName(AppEvent.xxx, payload: data). To read the payload with type safety: event.payloadAs<User>() (returns null if the type does not match).

// Create
channel.emit(OmegaEvent.fromName(AppEvent.authLoginSuccess, payload: LoginSuccessPayload(...)));
// Read in listener
final data = event.payloadAs<LoginSuccessPayload>();

OmegaIntent

Definition: Represents an action request with business meaning: "I want to log in", "I want to go to home". The UI does not call flow or agent methods; it emits an intent with flowManager.handleIntent(OmegaIntent.fromName(AppIntent.authLogin, payload: creds)). The FlowManager only sends it to flows that are in the running state. They are also used for navigation: when the channel emits an event named "navigation.intent" and payload = OmegaIntent, the navigator executes push/pushReplacement and passes the intent payload as RouteSettings.arguments. Typed names: OmegaIntent.fromName(OmegaIntentName, payload). Typed reading: intent.payloadAs<LoginCredentials>().

OmegaEventName

Contract for typed event names. Implement with an enum (e.g. enum AppEvent implements OmegaEventName { authLoginSuccess('auth.login.success'); @override final String name; }) and use OmegaEvent.fromName(AppEvent.authLoginSuccess, payload: x).

OmegaIntentName

Contract for typed intent names. Implement with an enum and use OmegaIntent.fromName(AppIntent.authLogin, payload: creds).

OmegaObject

Base class: provides id and meta (metadata map). OmegaEvent, OmegaIntent and OmegaFailure extend it.

OmegaFailure

Error representation. message (human‑readable) and optional details. Useful to emit semantic errors through the channel.

OmegaAgent

Autonomous logic unit. It has an id, channel and behavior. It subscribes to the channel; the behavior evaluates context and returns reactions; the agent executes them in onAction. Call dispose() when closing.

OmegaAgentBehaviorEngine

Rule engine: given a context (event or intent), it returns the first reaction whose rule matches. addRule(OmegaAgentBehaviorRule) registers rules; evaluate(OmegaAgentBehaviorContext) returns an OmegaAgentReaction or null.

OmegaAgentBehaviorRule

Rule: condition(context) indicates whether it applies; reaction(context) returns the OmegaAgentReaction to execute.

OmegaAgentBehaviorContext

Context passed to evaluate: event, intent and a copy of the agent state.

OmegaAgentReaction

Result of a rule: action (name) and payload. The agent receives it in onAction.

OmegaAgentProtocol

Agent registry. register(OmegaAgent); send(OmegaAgentMessage) to a single agent; broadcast(action, {payload}) to all.

OmegaAgentInbox

FIFO message queue. receive(message) adds; next() returns the next or null; hasMessages indicates whether there are pending messages.

OmegaAgentMessage

Direct message: from, to, action, payload. Sent with OmegaAgentProtocol.send.

OmegaFlow

Definition: A flow is a business flow (login, checkout, onboarding). It has states (OmegaFlowState: idle, running, sleeping, paused, ended) and only when it is in running does it process channel events and intents (in onEvent and onIntent). The flow orchestrates: it receives intents from the UI, emits events to the channel so that agents act, listens to events (e.g. "auth.login.success"), emits expressions to the UI ("loading", "success", "error") and can emit a navigation intent. The UI does not ask "are you loading?"; the flow announces the state with emitExpression. The screen subscribes to flow.expressions. The flow also has memory (key/value map) that persists while it is active and is included in the snapshot for persistence.

OmegaFlowManager

Manages all flows: registers, activates/pauses, distributes intents to those that are in running. wireNavigator(nav) connects the channel to the navigator.

OmegaFlowState

States: idle, running, sleeping, paused, ended. Only in running are events and intents processed.

OmegaFlowExpression

Message from the flow to the UI: type ("loading", "success", "error") and payload. Read payload with type: expr.payloadAs<User>().

OmegaFlowContext

Context in onEvent/onIntent: event, intent and flow memory.

OmegaFlowSnapshot

Snapshot of a flow: flowId, state, memory, lastExpression. toJson() / fromJson(Map) for persistence.

OmegaAppSnapshot

Snapshot of the app: activeFlowId and list of OmegaFlowSnapshot. toJson() / fromJson(Map). Restore with FlowManager.restoreFromSnapshot.

OmegaSnapshotStorage

Optional interface: save(OmegaAppSnapshot) and load() → Future<OmegaAppSnapshot?>. Implement with disk, SharedPreferences or a backend.

OmegaScope

InheritedWidget that exposes channel and flowManager (and optionally initialFlowId). Any child uses OmegaScope.of(context).

OmegaBuilder

Widget that rebuilds when an event arrives at the channel. Optionally filter by eventName. Requires OmegaScope in the tree.

OmegaNavigator

Converts intents "navigate.id" / "navigate.push.id" into push/pushReplacement. navigatorKey is assigned to MaterialApp.navigatorKey. registerRoute(OmegaRoute); handleIntent(OmegaIntent) performs navigation. The intent payload → RouteSettings.arguments.

OmegaRoute / OmegaRoute.typed / routeArguments

OmegaRoute(id, builder) defines a screen. OmegaRoute.typed<T>(id, builder: (context, T? arguments)) lets the view receive the payload with type. If you do not use typed: routeArguments<T>(context) to read typed arguments.

OmegaInspector / Launcher / Receiver / Server

OmegaInspector: overlay panel with latest channel events and flow snapshots. Debug only (kDebugMode).

OmegaInspectorLauncher: button that on web opens the inspector in a new window (BroadcastChannel); on desktop/mobile opens the overlay in a dialog. In release the button is hidden.

OmegaInspectorReceiver: in the window with ?omega_inspector=1 it shows the inspector (data via BroadcastChannel). In release it shows a "debug only" message.

OmegaInspectorServer: on desktop/mobile and debug only, starts an HTTP server; open the URL printed in the console (e.g. http://localhost:9292) to view the inspector in the browser. On web it is a no-op.

OmegaConfig

Bootstrap configuration: agents, flows, routes, initialFlowId (optional). Passed to OmegaRuntime.bootstrap.

OmegaRuntime

OmegaRuntime.bootstrap(createOmegaConfig) creates the channel, builds the config, registers agents in the protocol, flows in the manager, routes in the navigator, connects the navigator to the channel and returns the runtime. The app uses channel, flowManager, navigator and initialFlowId to mount OmegaScope and MaterialApp.

Persistence and restore

Concept: A snapshot is a picture of the app state (active flow + state and memory of each flow). You can serialize it to JSON, save it when closing the app (or at save points) and restore it on open. This way the user does not lose context (e.g. current screen and in‑memory data of the flows).

Flow: On close (or at a key point): flowManager.getAppSnapshot() → snapshot.toJson() → save (SharedPreferences, file with path_provider, backend). On open: load string/map → OmegaAppSnapshot.fromJson(map) → flowManager.restoreFromSnapshot(snapshot). The manager restores the memory of each flow and activates the flow that was active. For persistence to be correct, the values in memory and in the payloads you save must be JSON‑serializable (primitives, List, Map).

Optional interface: OmegaSnapshotStorage defines save(OmegaAppSnapshot) and load() → Future<OmegaAppSnapshot?>. You can implement it with any storage you want (file, SharedPreferences, API) and call save/load from your app at the lifecycle points you prefer.

// Guardar
final snapshot = flowManager.getAppSnapshot();
await prefs.setString("omega", jsonEncode(snapshot.toJson()));
// Restaurar al iniciar
final s = prefs.getString("omega");
if (s != null) flowManager.restoreFromSnapshot(OmegaAppSnapshot.fromJson(jsonDecode(s)));

Testing

Agents: Create a channel and test agent that stores what it receives in onAction. Emit an event or call agent.receiveIntent(intent). After a short delay, check the variables.

Flows: Create a test flow, call flow.start(), listen to flow.expressions, call flow.receiveIntent(intent) or emit events. After a delay, check the received expression. No WidgetTester or Flutter is required.

See doc/TESTING.md in the repo for complete examples.