RealmUI Runtime

State Flow

1. Host sends CmdUiDocumentCreate, CmdUiThemeDefine, CmdUiApplyOps.
2. Core updates UiState (documents, themes, images, focus, and caches).
3. UI pass executes layout/paint and generates draw data.
4. egui platform output becomes:
   • internal window/cursor/IME commands;
   • host events (UiOpenUrl, clipboard, screenshot request, viewport sync).

Input

• Pointer/keyboard come from the input subsystem.
• Routing passes through target layer and resolves realm/document focus.
• For RealmPlane/WidgetRealmViewport, position is transformed to local coordinates.

Output

• Widget events: EngineEvent::Ui(UiEvent).
• UI system events: EngineEvent::System(SystemEvent::Ui*).
• Diagnostic failures: SystemEvent::Error is also emitted.

Async Resources

• CmdUiImageCreateFromBuffer starts async decode.
• Progress events:
  • UiImageProcessingStarted
  • UiImageProcessingProgress
  • UiImageProcessingFinished
  • UiImageReady
• CmdUiImageDispose cancels pending decode and discards results.

Focus

• Focus is mapped by windowId + realmId + documentId + nodeId.
• Commands:
  • CmdUiFocusSet
  • CmdUiFocusGet

Input Trace

• CmdUiEventTraceSet controls:
  • level (off/errors/basic/full);
  • sampling (0..100).
• Trace includes realm/target/layer hops for routing diagnostics.