com.wallstop-studios.dxmessaging 2.0.0-rc27.3.1 → 2.1.0

package/Editor/CustomEditors/MessagingComponentEditor.cs

@@ -5,6 +5,7 @@ namespace DxMessaging.Editor.CustomEditors
     using System.Linq;
     using Core;
     using Core.Diagnostics;
+    using Core.MessageBus;
     using Core.Messages;
     using Unity;
     using UnityEditor;
@@ -107,18 +108,26 @@ namespace DxMessaging.Editor.CustomEditors
                 }
             }
 
-            if (!MessageHandler.MessageBus.DiagnosticsMode)
+            IMessageBus globalBus = MessageHandler.MessageBus;
+            if (globalBus is not MessageBus concreteBus)
+            {
+                EditorGUILayout.HelpBox(
+                    "Global diagnostics controls are unavailable because the active global bus is not the default DxMessaging MessageBus implementation.",
+                    MessageType.Info
+                );
+            }
+            else if (!concreteBus.DiagnosticsMode)
             {
                 if (GUILayout.Button("Enable Global Diagnostics"))
                 {
-                    MessageHandler.MessageBus.DiagnosticsMode = true;
+                    concreteBus.DiagnosticsMode = true;
                 }
             }
             else
             {
                 if (GUILayout.Button("Disable Global Diagnostics"))
                 {
-                    MessageHandler.MessageBus.DiagnosticsMode = false;
+                    concreteBus.DiagnosticsMode = false;
                 }
                 else
                 {
@@ -130,7 +139,7 @@ namespace DxMessaging.Editor.CustomEditors
                         "Global Messages",
                         true
                     );
-                    int totalGlobalMessages = MessageHandler.MessageBus._emissionBuffer.Count;
+                    int totalGlobalMessages = concreteBus._emissionBuffer.Count;
                     if (_globalBufferExpanded && totalGlobalMessages > 0)
                     {
                         int page = _globalBufferPaging;
@@ -163,8 +172,8 @@ namespace DxMessaging.Editor.CustomEditors
                             }
                         }
 
-                        MessageEmissionData[] pagedGlobalMessages = MessageHandler
-                            .MessageBus._emissionBuffer.Reverse()
+                        MessageEmissionData[] pagedGlobalMessages = concreteBus
+                            ._emissionBuffer.Reverse()
                             .Skip(page * PageSize)
                             .Take(PageSize)
                             .ToArray();

package/README.md

@@ -1,6 +1,6 @@
 # DxMessaging for Unity — The Modern Event System
 
-[![Unity](https://img.shields.io/badge/Unity-2021.3+-black.svg)](https://unity.com/download)<br/>
+[![Unity](https://img.shields.io/badge/Unity-2021.3+-black.svg)](https://unity.com/releases/editor)<br/>
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)<br/>
 [![Version](https://img.shields.io/badge/version-2.0.0--rc27-green.svg)](package.json)<br/>
 [![Performance: OS-Specific Benchmarks](https://img.shields.io/badge/Performance-OS--specific-blueviolet.svg)](Docs/Performance.md)<br/>
@@ -32,17 +32,27 @@ Think of it as **the event system Unity should have built-in** — one that actu
 
 ## 30-Second Elevator Pitch
 
-**Problem:** In Unity, you're stuck with manual event management (memory leaks!), tight coupling (everything knows everything!), or messy global event buses (no context, no control!).
+### If you've ever
 
-**Solution:** DxMessaging gives you three simple message types:
+- Forgotten to unsubscribe from an event and spent hours debugging memory leaks
+- Had UI code tangled with 15 different game systems
+- Wondered "which event fired when?" with no way to see message flow
+- Copy-pasted event boilerplate dozens of times
 
-1. **Untargeted** - "Hey everyone!" (global events)
-1. **Targeted** - "Hey YOU!" (commands to specific objects)
-1. **Broadcast** - "I did something!" (events from sources)
+#### Then DxMessaging solves your problems
 
-**Result:** Zero memory leaks (automatic lifecycle), zero coupling (no references needed), full observability (see everything in Inspector), and predictable execution (priority-based ordering).
+- **Zero memory leaks** - automatic lifecycle management, no manual unsubscribe
+- **Zero coupling** - systems communicate without knowing each other exist
+- **Full visibility** - see every message in the Inspector with timestamps and payloads
+- **Complete control** - priority-based ordering, validation, and interception
 
-**One line:** It's like C# events, but with superpowers and no footguns. 🚀
+##### Three simple message types
+
+1. **Untargeted** - "Everyone listen!" (pause game, settings changed)
+1. **Targeted** - "Tell Player to heal" (commands to specific entities)
+1. **Broadcast** - "Enemy took damage" (events others can observe)
+
+**One line:** It's the event system Unity should have shipped with - type-safe, leak-proof, and actually debuggable. 🚀
 
 ---
 
@@ -103,6 +113,57 @@ msg.EmitComponentTargeted(chestComponent);
 
 ---
 
+## 🔧 Dependency Injection (DI) Compatible
+
+**Using Zenject, VContainer, or Reflex?** DxMessaging is fully DI-compatible out of the box!
+
+```csharp
+// Inject IMessageBus in any class
+public class PlayerService : IInitializable, IDisposable
+{
+    private readonly MessageRegistrationLease _lease;
+
+    public PlayerService(IMessageRegistrationBuilder builder)
+    {
+        // Builder automatically resolves your container-managed bus
+        _lease = builder.Build(new MessageRegistrationBuildOptions
+        {
+            Configure = token => token.RegisterUntargeted<PlayerSpawned>(OnSpawn)
+        });
+    }
+
+    public void Initialize() => _lease.Activate();
+    public void Dispose() => _lease.Dispose();
+}
+```
+
+### Why use DI + Messaging?
+
+- **DI for construction** — Inject services, repositories, managers via constructors
+- **Messaging for events** — Reactive, decoupled communication for gameplay events
+- **Best of both worlds** — Clean architecture with testable, isolated buses
+
+#### Automatic integration for
+
+- ✅ **Zenject/Extenject** — Full-featured DI with extensive Unity support
+- ✅ **VContainer** — Lightweight, high-performance DI with scoped lifetimes
+- ✅ **Reflex** — Minimal API, blazing-fast dependency injection
+
+##### Get started
+
+- [Zenject Integration Guide](Docs/Integrations/Zenject.md) — Complete setup with examples
+- [VContainer Integration Guide](Docs/Integrations/VContainer.md) — Scoped buses for scene isolation
+- [Reflex Integration Guide](Docs/Integrations/Reflex.md) — Minimal, lightweight patterns
+
+##### Core DI concepts
+
+- [Runtime Configuration](Docs/RuntimeConfiguration.md) — Setting message buses at runtime, re-binding registrations
+- [Message Bus Providers](Docs/MessageBusProviders.md) — Provider system for design-time and runtime bus configuration
+
+**Not using DI?** No problem! DxMessaging works perfectly standalone with zero dependencies.
+
+---
+
 ## Is DxMessaging Right for You
 
 ### ✅ Use DxMessaging When
@@ -113,6 +174,7 @@ msg.EmitComponentTargeted(chestComponent);
 - **You value observability** - Need to debug "what fired when?" or track message flow
 - **Teams/long-term maintenance** - Multiple developers, or you'll maintain this code for years
 - **You want decoupling** - Hate when UI classes need references to 15 different game systems
+- **You're using DI frameworks** - Seamless integration with Zenject/VContainer/Reflex (see [DI Compatible](#-dependency-injection-di-compatible))
 
 ### ❌ Don't Use DxMessaging When
 
@@ -152,95 +214,194 @@ Looking for hard numbers? See OS-specific [Performance Benchmarks](Docs/Performa
 
 ## Why DxMessaging
 
-### The Problem You Know
+### The Problems You've Probably Hit
+
+#### Scenario 1: The Memory Leak Nightmare
+
+You write this innocent-looking code:
+
+```csharp
+public class GameUI : MonoBehaviour {
+    void OnEnable() {
+        GameManager.Instance.OnScoreChanged += UpdateScore;
+    }
+    // Oops, forgot OnDisable... leak! 💀
+}
+```
+
+Months later: "Why is our game using 2GB of RAM after an hour?"
+
+##### Scenario 2: The Spaghetti Mess
 
 ```csharp
-// C# Events: Manual lifecycle hell
 public class GameUI : MonoBehaviour {
     [SerializeField] private Player player;
     [SerializeField] private EnemySpawner spawner;
+    [SerializeField] private InventorySystem inventory;
+    [SerializeField] private QuestSystem quests;
+    [SerializeField] private AudioManager audio;
+    // ... 15 more SerializeFields ...
 
     void Awake() {
         player.OnHealthChanged += UpdateHealth;
         spawner.OnWaveStart += ShowWave;
-    }
-
-    void OnDestroy() {
-        // Easy to forget = memory leaks
-        player.OnHealthChanged -= UpdateHealth;
-        spawner.OnWaveStart -= ShowWave;
+        inventory.OnItemAdded += RefreshInventory;
+        quests.OnQuestCompleted += ShowQuestNotification;
+        // ... 20 more subscriptions ...
     }
 }
 ```
 
-Problems:
+**Your UI now depends on EVERYTHING.** Good luck refactoring that.
+
+###### Scenario 3: The Debugging Black Hole
+
+Player reports: "My health bar didn't update!"
+
+You think: "Okay, which of the 47 events touching health failed? And in what order?"
 
-- ❌ Manual subscribe/unsubscribe (memory leaks waiting to happen)
-- ❌ Tight coupling (UI needs references to every system)
-- ❌ No execution order control
-- ❌ Impossible to debug ("which event fired when?")
+**30 minutes later:** Still setting breakpoints everywhere...
+
+### Common Problems
+
+- ❌ **Memory leaks** from forgotten unsubscribes (every Unity dev's nightmare)
+- ❌ **Tight coupling** making refactoring terrifying ("change one thing, break five others")
+- ❌ **No execution order control** ("why does the UI update before the player takes damage?")
+- ❌ **Impossible to debug** ("what fired when?" has no answer)
+- ❌ **Boilerplate overload** (write 50 lines for 3 events)
 
 ### The DxMessaging Solution
 
+#### Same scenarios, zero pain
+
+##### Scenario 1: No More Memory Leaks
+
 ```csharp
-using DxMessaging.Core.Attributes;
-using DxMessaging.Core.Extensions;
-using DxMessaging.Unity;
+public class GameUI : MessageAwareComponent {
+    protected override void RegisterMessageHandlers() {
+        base.RegisterMessageHandlers();
+        _ = Token.RegisterUntargeted<ScoreChanged>(UpdateScore);
+    }
+    // That's it! No manual cleanup needed.
+    // Token automatically handles OnEnable/OnDisable/OnDestroy
+}
+```
+
+**Automatic lifecycle = impossible to leak.** 🎉
+
+###### Scenario 2: No More Coupling
+
+```csharp
+public class GameUI : MessageAwareComponent {
+    // Zero SerializeFields! Zero references!
+
+    protected override void RegisterMessageHandlers() {
+        base.RegisterMessageHandlers();
+        _ = Token.RegisterUntargeted<HealthChanged>(OnHealth);
+        _ = Token.RegisterUntargeted<WaveStarted>(OnWave);
+        _ = Token.RegisterUntargeted<ItemAdded>(OnItem);
+        // Listen to anything, from anywhere, no coupling
+    }
+}
+```
+
+**Your UI is now independent.** Swap systems freely without breaking anything.
+
+###### Scenario 3: Debugging is Built In
+
+Open any `MessageAwareComponent` in the Inspector:
+
+```text
+Message History (last 50):
+[12:34:56] HealthChanged (amount: 25) → Priority: 0
+[12:34:55] ItemAdded (id: 42, count: 1) → Priority: 5
+[12:34:54] WaveStarted (wave: 3) → Priority: 0
+
+Active Registrations:
+✓ HealthChanged (5 handlers)
+✓ ItemAdded (2 handlers)
+```
 
-// 1. Define messages (clean, typed, immutable)
+**See exactly what fired, when, and who handled it.** No guesswork.
+
+### How It Transforms Your Code
+
+```csharp
+// 1. Define messages (clean, typed, discoverable)
 [DxTargetedMessage]
 [DxAutoConstructor]
 public readonly partial struct Heal { public readonly int amount; }
 
 // 2. Listen (automatic lifecycle - zero leaks)
-public class GameUI : MessageAwareComponent {
+public class Player : MessageAwareComponent {
     protected override void RegisterMessageHandlers() {
         base.RegisterMessageHandlers();
         _ = Token.RegisterComponentTargeted<Heal>(this, OnHeal);
     }
 
-    void OnHeal(ref Heal m) => UpdateHealthBar(m.amount);
+    void OnHeal(ref Heal m) {
+        health += m.amount;
+        Debug.Log($"Healed {m.amount}!");
+    }
 }
 
-// 3. Send (discoverable, type-safe)
-var heal = new Heal(10);
-heal.EmitGameObjectTargeted(gameObject);
+// 3. Send (from anywhere - zero coupling)
+var heal = new Heal(50);
+heal.EmitComponentTargeted(playerComponent);
 ```
 
-Benefits:
+#### What you get
 
-- ✅ **Zero memory leaks** - automatic lifecycle via tokens
-- ✅ **Full decoupling** - no direct references needed
-- ✅ **Predictable order** - priority-based execution
-- ✅ **Type-safe** - compile-time guarantees
-- ✅ **Observable** - built-in Inspector diagnostics
-- ✅ **Intercept & validate** - enforce rules before handlers run
+- ✅ **Zero memory leaks** - tokens clean up automatically when components are destroyed
+- ✅ **Zero coupling** - no SerializeFields, no GetComponent, no direct references
+- ✅ **Full visibility** - see message flow in Inspector with timestamps and payloads
+- ✅ **Predictable order** - priority-based execution (no more mystery race conditions)
+- ✅ **Type-safe** - compile-time guarantees, refactor with confidence
+- ✅ **Intercept & validate** - enforce rules before handlers run (clamp damage, block invalid input)
+- ✅ **Extension points everywhere** - interceptors, handlers, post-processors with priorities
 
 ## Killer Features
 
-### 🚀 Performance: Zero-Allocation Design
+Why DxMessaging is different:
+
+### 🚀 Performance: Zero-Allocation, Zero-Leak Design
+
+**The problem with normal events:** Boxing allocations, GC spikes, memory leaks from forgotten unsubscribes.
 
-Messages are `readonly struct` types passed by `ref` — no boxing, no GC pressure.
+#### DxMessaging solution
 
 ```csharp
-void OnDamage(ref TookDamage msg) {  // No allocations!
-    health -= msg.amount;
+void OnDamage(ref TookDamage msg) {  // Pass by ref = zero allocations
+    health -= msg.amount;            // No boxing, no GC pressure
 }
+// Automatic cleanup = zero leaks, guaranteed
 ```
 
-### 🎯 Three Message Types That Make Sense
+**Real-world impact:** A game emitting 1000 messages/second uses **zero GC** with DxMessaging vs. 40KB/sec with boxed events.
+
+### 🎯 Three Message Types That Actually Make Sense
+
+Most event systems force you into one pattern. DxMessaging gives you the right tool for each job:
 
 ```csharp
-// Untargeted: Global events anyone can hear
-[DxUntargetedMessage] public struct GamePaused { }
+// Untargeted: "Everyone, listen up!" (global announcements)
+[DxUntargetedMessage]
+public struct GamePaused { }
+// ↳ Perfect for: settings, scene transitions, global state
 
-// Targeted: Commands to specific entities
-[DxTargetedMessage] public struct Heal { public int amount; }
+// Targeted: "Hey Player, do this!" (commands to specific entities)
+[DxTargetedMessage]
+public struct Heal { public int amount; }
+// ↳ Perfect for: UI actions, direct commands, player input
 
-// Broadcast: Events from a source that others observe
-[DxBroadcastMessage] public struct TookDamage { public int amount; }
+// Broadcast: "I took damage!" (events others can observe)
+[DxBroadcastMessage]
+public struct TookDamage { public int amount; }
+// ↳ Perfect for: achievements, analytics, UI updates from entities
 ```
 
+**Why this matters:** You're not forcing everything through one generic "Event<T>" pattern. Each message type has clear semantics.
+
 ### 🔄 The Message Pipeline
 
 Every message flows through 3 stages with priority control:
@@ -250,51 +411,136 @@ flowchart LR
     P[Producer] --> I[Interceptors<br/>validate/mutate]
     I --> H[Handlers<br/>main logic]
     H --> PP[Post-Processors<br/>analytics/logging]
-    style I fill:#fff4e5,stroke:#f0b429
-    style H fill:#e6f7ff,stroke:#1890ff
-    style PP fill:#eef7ee,stroke:#52c41a
+    style I fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
+    style H fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+    style PP fill:#b7eb8f,stroke:#389e0d,stroke-width:2px,color:#000
 ```
 
-### 🎭 Listen to "All Targets" or "All Sources"
+### 🎭 Global Observers: Listen to EVERYTHING (Unique Feature!)
+
+**The problem with normal events:** To track all player damage, enemy damage, and NPC damage, you need 3 separate event subscriptions.
 
-Perfect for analytics, achievements, and debugging:
+**DxMessaging's superpower:** Subscribe ONCE to a message type, receive ALL instances with source information:
 
 ```csharp
-// Track ALL damage, regardless of source
+// Track ALL damage from ANY source (players, enemies, NPCs, environment)
 _ = token.RegisterBroadcastWithoutSource<TookDamage>(
     (InstanceId source, TookDamage msg) => {
+        Debug.Log($"{source} took {msg.amount} damage!");
         Analytics.LogDamage(source, msg.amount);
+        CheckAchievements(source, msg.amount);
     }
 );
 ```
 
-### 🛡️ Interceptors: Validate Before Execution
+#### Real-world use cases
+
+- **Achievement system:** Track all kills, deaths, damage across the entire game
+- **Combat log:** "Player took 25 damage, Enemy3 took 50 damage, Boss took 100 damage"
+- **Analytics:** Aggregate stats from all entities without knowing about them upfront
+- **Debug tools:** Watch ALL messages in the Inspector without instrumenting code
+
+**Why this is revolutionary:** Traditional event buses require you to know entity types upfront. DxMessaging lets you observe dynamically.
+
+### 🛡️ Interceptors: Validate Before Execution (Safety Built In)
+
+**The problem with normal events:** Validation logic duplicated in every handler, or bugs when you forget.
+
+**DxMessaging solution:** Validate ONCE before ANY handler runs:
 
 ```csharp
-// Clamp damage before any handler sees it
+// ONE interceptor protects ALL handlers
 _ = token.RegisterBroadcastInterceptor<TookDamage>(
     (ref InstanceId src, ref TookDamage msg) => {
-        if (msg.amount <= 0) return false; // Cancel
-        msg = new TookDamage(Math.Min(msg.amount, 999)); // Clamp
+        if (msg.amount <= 0) return false;               // Cancel invalid
+        if (msg.amount > 999) {
+            msg = new TookDamage(999);                   // Clamp excessive
+        }
+        if (IsGodModeActive(src)) return false;          // Block damage
         return true;
-    }
+    },
+    priority: -100  // Run FIRST
 );
+
+// Now ALL handlers receive clean, validated data
+_ = token.RegisterComponentTargeted<TookDamage>(player, OnDamage);
+void OnDamage(ref TookDamage msg) {
+    // No validation needed - interceptor guarantees validity!
+    health -= msg.amount;
+}
 ```
 
-### 🔍 Built-in Inspector Diagnostics
+#### Real-world use cases
+
+- Clamp/normalize values (damage, healing, speeds)
+- Enforce game rules ("can't heal above max health")
+- Block messages during cutscenes
+- Log/audit sensitive actions
+
+### 🔍 Built-in Inspector Diagnostics (Actually Debuggable!)
+
+**The problem with normal events:** "Which event fired? When? Who handled it? In what order?" = 🤷
+
+**DxMessaging solution:** Click any `MessageAwareComponent` in the Inspector:
+
+#### Message History (last 50)
 
-See message history, handler counts, and registrations live in the Unity Inspector. For screenshots and details, see Unity Integration → Diagnostics.
+- `[12:34:56.123] HealthChanged`
+  - amount: 25
+  - priority: 0
+  - handlers: 3
+- `[12:34:55.987] ItemAdded`
+  - itemId: 42, count: 1
+  - priority: 5
+  - handlers: 2
 
-### 🏝️ Local Bus Islands for Testing
+##### Active Registrations
 
-Isolate subsystems with their own message buses:
+- ✓ HealthChanged (priority: 0, called: 847 times)
+- ✓ ItemAdded (priority: 5, called: 23 times)
+- ✓ TookDamage (priority: 10, called: 1,203 times)
+
+#### Real-world debugging scenarios
+
+- "Did my message fire?" → Check history, see timestamp
+- "Why didn't my handler run?" → Check registrations, see if it's active
+- "What's firing too often?" → Sort by call count
+- "What's the execution order?" → Sort by priority
+
+**No more:** Setting 50 breakpoints and stepping through code for 30 minutes.
+
+### 🏝️ Local Bus Islands for Testing (Actually Testable!)
+
+**The problem with normal events:** Global static events contaminate tests. Mock hell. Flaky tests.
+
+**DxMessaging solution:** Each test gets its own isolated message bus:
 
 ```csharp
-var testBus = new MessageBus();
-var token = MessageRegistrationToken.Create(handler, testBus);
-// Messages here don't affect the global bus!
+[Test]
+public void TestAchievementSystem() {
+    // Create isolated bus - zero global state
+    var testBus = new MessageBus();
+    var handler = new MessageHandler(new InstanceId(1), testBus) { active = true };
+    var token = MessageRegistrationToken.Create(handler, testBus);
+
+    // Test in isolation
+    _ = token.RegisterBroadcastWithoutSource<EnemyKilled>(achievements.OnKill);
+
+    var msg = new EnemyKilled("Boss");
+    msg.EmitGameObjectBroadcast(enemy, testBus);  // Only this test sees it
+
+    Assert.IsTrue(achievements.Unlocked("BossSlayer"));
+}
+// Bus destroyed, zero cleanup needed
 ```
 
+#### Why this matters
+
+- Tests don't interfere with each other
+- No "arrange/act/cleanup" boilerplate
+- No mocking frameworks needed
+- Parallel test execution works perfectly
+
 ## Documentation
 
 ### 🎓 Learn
@@ -325,9 +571,64 @@ Important: Inheritance with MessageAwareComponent
 - If you need to opt out of string demos, override `RegisterForStringMessages => false` instead of skipping the base call.
 - Don’t hide Unity methods with `new` (e.g., `new void OnEnable()`); always `override` and call `base.*`.
 
+### 🧩 DI Framework Integrations
+
+DxMessaging works standalone (zero dependencies) or with any major DI framework. For detailed setup guides and code examples:
+
+- **[Zenject Integration Guide](Docs/Integrations/Zenject.md)** — Full-featured DI with extensive Unity support
+- **[VContainer Integration Guide](Docs/Integrations/VContainer.md)** — Lightweight DI with scoped lifetimes for scene isolation
+- **[Reflex Integration Guide](Docs/Integrations/Reflex.md)** — Minimal API, blazing-fast performance
+
+#### Core DI concepts
+
+- **[Runtime Configuration](Docs/RuntimeConfiguration.md)** — Setting and overriding message buses at runtime, re-binding registrations
+- **[Message Bus Providers](Docs/MessageBusProviders.md)** — Provider system and MessageBusProviderHandle for flexible bus configuration
+
+Each guide includes:
+
+- ✅ Complete setup instructions with installers
+- ✅ Multiple usage patterns (plain classes, MonoBehaviours, direct injection)
+- ✅ Testing examples with isolated buses
+- ✅ Advanced patterns (pooling, scene scopes, signal bridges)
+
+See the [🔧 DI Compatible section](#-dependency-injection-di-compatible) above for a quick overview.
+
 ### 🆚 Comparisons
 
-- [Compare with C# events, UnityEvents, and SendMessage](Docs/Comparisons.md)
+- [Compare with Other Unity Messaging Frameworks](Docs/Comparisons.md) — In-depth comparison with UniRx, MessagePipe, Zenject Signals, C# events, UnityEvents, and more
+- [Scriptable Object Architecture (SOA) Compatibility](Docs/Patterns.md#14-compatibility-with-scriptable-object-architecture-soa) — Migration patterns and interoperability with SOA
+
+#### Quick Framework Comparison
+
+| Framework           | Best For                          | Key Strength                     | Unity Support      | Learning Curve |
+| ------------------- | --------------------------------- | -------------------------------- | ------------------ | -------------- |
+| **DxMessaging**     | Unity pub/sub with lifecycle mgmt | Inspector debugging + control    | ✅ Built for Unity | ⭐⭐⭐         |
+| **UniRx**           | Complex event stream transforms   | Reactive operators (LINQ)        | ✅ Built for Unity | ⭐⭐           |
+| **MessagePipe**     | High-performance DI messaging     | Highest throughput (97M ops/sec) | ✅ Built for Unity | ⭐⭐⭐⭐       |
+| **Zenject Signals** | DI-integrated messaging           | Zenject ecosystem                | ✅ Built for Unity | ⭐⭐           |
+| **C# Events**       | Simple, local communication       | Minimal overhead                 | ✅ Native C#       | ⭐⭐⭐⭐⭐     |
+
+##### Choose DxMessaging when you want
+
+- Unity-first design with GameObject/Component targeting
+- Automatic lifecycle management (zero memory leaks)
+- Inspector debugging to see message flow and history
+- Execution order control (priority-based handlers)
+- Message validation/interception pipeline
+- Global observers (listen to all message instances)
+- Post-processing stage (analytics, logging after handlers)
+- No dependencies, plug-and-play setup
+
+See [full comparison](Docs/Comparisons.md) for detailed analysis with code examples, performance benchmarks, and decision guides.
+
+> **📦 Using Scriptable Object Architecture (SOA)?**
+>
+> DxMessaging can work alongside or replace SOA patterns. See [SOA Compatibility Guide](Docs/Patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for:
+>
+> - Fair comparison of SOA vs. DxMessaging
+> - Migration patterns from GameEvent/FloatVariable to DxMessaging
+> - How to use both systems together (SOs for configs, DxMessaging for events)
+> - When to keep using ScriptableObjects (immutable design data)
 
 ### 📖 Reference
 
@@ -400,6 +701,26 @@ For OS-specific benchmark tables generated by PlayMode tests, see [Performance B
 
 ## Comparison Table
 
+### Comparison with Unity Messaging Frameworks
+
+| Feature                  | DxMessaging        | UniRx              | MessagePipe        | Zenject Signals    |
+| ------------------------ | ------------------ | ------------------ | ------------------ | ------------------ |
+| **Unity Compatibility**  | ✅ Built for Unity | ✅ Built for Unity | ✅ Built for Unity | ✅ Built for Unity |
+| **Decoupling**           | ✅ Full            | ✅ Full            | ✅ Full            | ✅ Full            |
+| **Lifecycle Safety**     | ✅ Auto            | ⚠️ Manual          | ⚠️ Manual          | ⚠️ DI-managed      |
+| **Execution Order**      | ✅ Priority        | ❌ None            | ❌ None            | ❌ None            |
+| **Type Safety**          | ✅ Strong          | ✅ Strong          | ✅ Strong          | ✅ Strong          |
+| **Inspector Debug**      | ✅ Built-in        | ❌ No              | ❌ No              | ❌ No              |
+| **GameObject Targeting** | ✅ Yes             | ❌ No              | ❌ No              | ❌ No              |
+| **Global Observers**     | ✅ Yes             | ❌ No              | ❌ No              | ❌ No              |
+| **Interceptors**         | ✅ Pipeline        | ❌ No              | ⚠️ Filters         | ❌ No              |
+| **Post-Processing**      | ✅ Dedicated       | ❌ No              | ⚠️ Filters         | ❌ No              |
+| **Stream Operators**     | ❌ No              | ✅ Extensive       | ❌ No              | ⚠️ With UniRx      |
+| **Performance**          | ✅ Good (14M)      | ✅ Good (18M)      | ✅ Best (97M)      | ⚠️ Moderate (2.5M) |
+| **Dependencies**         | ✅ None            | ⚠️ UniTask         | ✅ None            | ⚠️ Zenject         |
+
+### Comparison with Traditional Approaches
+
 | Feature                | DxMessaging   | C# Events    | UnityEvents   | Static Event Bus |
 | ---------------------- | ------------- | ------------ | ------------- | ---------------- |
 | **Decoupling**         | ✅ Full       | ❌ Tight     | ⚠️ Hidden     | ✅ Yes           |

package/Runtime/AssemblyInfo.cs

@@ -5,3 +5,7 @@ using System.Runtime.CompilerServices;
     AllInternalsVisible = true
 )]
 [assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Editor")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime.Reflex")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime.VContainer")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime.Zenject")]