com.wallstop-studios.dxmessaging 3.2.0 → 3.2.1

package/Editor/Windows/DxMessagingMessageMonitorWindow.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 2ca6a4e3bf77409a9be9f081ef85983d
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/Windows.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 51d5e91f8bea443da9aa3ce912e88410
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/README.md

@@ -1,31 +1,37 @@
-# DxMessaging for Unity
+# DxMessaging
 
 <p align="center">
-  <img src="docs/images/DxMessaging-banner.svg" alt="DxMessaging - Type-safe messaging system for Unity" width="800"/>
+  <img src="docs/images/DxMessaging-banner.svg" alt="DxMessaging - Decoupled, simple systems for Unity" width="800"/>
 </p>
 
 <p align="center">
   <a href="https://ambiguous-interactive.github.io/DxMessaging/">
-    <img src="https://img.shields.io/badge/Full_Documentation-Visit_the_Docs_Site-2ea44f?style=for-the-badge" alt="Full Documentation" />
+    <img src="https://img.shields.io/badge/Docs-ambiguous--interactive.github.io-f4a836?style=for-the-badge" alt="Documentation" />
   </a>
 </p>
 
 [![Unity](https://img.shields.io/badge/Unity-2021.3+-black.svg)](https://unity.com/releases/editor/archive)<br/>
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)<br/>
+[![License: MIT](https://img.shields.io/badge/License-MIT-f4a836.svg)](LICENSE.md)<br/>
 [![openupm](https://img.shields.io/npm/v/com.wallstop-studios.dxmessaging?label=openupm&registry_uri=https://package.openupm.com)](https://openupm.com/packages/com.wallstop-studios.dxmessaging/)<br/>
 [![Version](https://img.shields.io/npm/v/com.wallstop-studios.dxmessaging.svg)](https://www.npmjs.com/package/com.wallstop-studios.dxmessaging)<br/>
-[![Performance: Standalone (IL2CPP)](<https://img.shields.io/badge/Performance-Standalone%20(IL2CPP)-blueviolet.svg>)](docs/architecture/performance.md)<br/>
+[![Performance: Standalone (IL2CPP)](<https://img.shields.io/badge/Performance-Standalone%20(IL2CPP)-f4a836.svg>)](docs/architecture/performance.md)<br/>
 [![Markdown Link Validity](https://github.com/Ambiguous-Interactive/DxMessaging/actions/workflows/markdown-link-validity.yml/badge.svg)](https://github.com/Ambiguous-Interactive/DxMessaging/actions/workflows/markdown-link-validity.yml)
 
-> **🤖 AI Assistance Disclosure:**
+> **AI Assistance Disclosure:**
 >
 > This project has been actively developed and maintained by human authors for over a decade. Recent versions have utilized AI assistance for documentation, test coverage, and performance optimizations.
 
-**DxMessaging is a type-safe messaging system** that replaces sprawling C# events, brittle UnityEvents, and global static event buses with an observable and lifecycle-managed communication pattern.
+**DxMessaging is a synchronous, type-safe Unity message bus for decoupled, simple systems.** It replaces sprawling C# events, brittle UnityEvents, and global static event buses with explicit message contracts, lifecycle-managed registrations, and editor-visible routing.
 
-Think of it as: A messaging system designed for decoupled game systems.
+Use it when one system needs to announce a fact, command a target, or broadcast from a source without keeping a direct scene reference to the receiver.
 
-Need install instructions? Try [OpenUPM](https://openupm.com/packages/com.wallstop-studios.dxmessaging/) (recommended) or see the [Install Guide](docs/getting-started/install.md) for Git URLs, scoped registries, and more.
+```bash
+openupm add com.wallstop-studios.dxmessaging
+```
+
+The core taxonomy is small: **Untargeted** announcements, **Targeted** commands, and **Broadcast** facts from a source. Diagnostics are built around that model: Message Monitor shows recent emissions and filters, Flow Graph shows registration topology and trace evidence, and the Inspector overlay catches `MessageAwareComponent` lifecycle mistakes.
+
+See the [Install Guide](docs/getting-started/install.md) for Git URL, scoped registry, and release tarball options.
 
 ## Table of Contents
 
@@ -605,38 +611,79 @@ void OnDamage(ref TookDamage msg) {
 - Block messages during cutscenes
 - Log/audit sensitive actions
 
-### Built-in Inspector Diagnostics
+### Built-in Editor Diagnostics
 
 **The problem with normal events:** "Which event fired? When? Who handled it? In what order?" = unknown
 
-**DxMessaging solution:** Click any `MessageAwareComponent` in the Inspector:
-
-#### Message History (last 50)
-
-- `[12:34:56.123] HealthChanged`
-  - amount: 25
-  - priority: 0
-  - handlers: 3
-- `[12:34:55.987] ItemAdded`
-  - itemId: 42, count: 1
-  - priority: 5
-  - handlers: 2
-
-##### Active Registrations
-
-- [x] HealthChanged (priority: 0, called: 847 times)
-- [x] ItemAdded (priority: 5, called: 23 times)
-- [x] TookDamage (priority: 10, called: 1,203 times)
+**DxMessaging solution:** turn on diagnostics in the Inspector or Project Settings, then use the
+dedicated Unity editor tools under **Tools > Wallstop Studios > DxMessaging**.
+
+#### Message Monitor
+
+- Recent global-bus emissions, most-recent first
+- Message type, context, and stack trace details
+- Plain text filtering, `type:` / `message:` / `context:` / `stack:` field
+  filters, an active-filter summary with Clear, and Copy JSON export
+- Visible message-type lanes showing per-filter entry counts, context breadth,
+  and message-volume share, plus context lanes showing context volume and
+  message breadth, with row-level Filter shortcuts and exact quoted context
+  shortcuts
+- Loaded-scene `MessagingComponent` diagnostics, including listener counts,
+  registrations, calls, local messages, and provider warnings
+
+#### Flow Graph
+
+- Component nodes, message-type nodes, and registration edges
+- Route-map route-kind mix, call shares, widest-message target-component
+  fan-out, most-routed target, inactive routed-target, hottest-route, and
+  no-call route summaries, recent traced-route coverage, busiest traced-route,
+  traced-message, and traced-target share, visible message lanes grouped by
+  message type, visible target lanes grouped by target component, visible trace
+  route-kind lanes grouped by traced registration kind, visible trace message
+  lanes grouped by traced message type, visible trace target lanes grouped by
+  traced target component, visible trace-id lanes grouped by positive trace id,
+  visible trace context lanes grouped by normalized context, visible trace
+  context volume and share, visible trace-id
+  breadth, visible trace-target/path concentration, selected
+  component/message route-health and busiest traced-route details, selected
+  component busiest traced-message details, selected message busiest
+  traced-target details, selected
+  component/message/route visible traced-share details, and selected
+  component/message/route trace context volume, trace context delivery,
+  busiest-context-share, trace-id breadth, selected component trace-message,
+  selected message trace-target, busiest-path, and busiest-path-share details
+- Recent global/listener emission evidence
+- Exact recent traced delivery counts per registration edge
+- Recent trace-path/context aggregates, including busiest trace context share,
+  busiest trace message/target/path shares, visible flow corridors by
+  message/target pair, visible trace route-kind lanes by traced registration
+  kind, visible trace message lanes by traced message type, visible trace target
+  lanes by traced target component, visible trace context lanes by normalized
+  context, visible trace-id lanes by positive trace id, widest visible trace id
+  by path count, and exact trace-id export arrays when diagnostics capture token
+  delivery records with positive trace ids
+
+#### Inspector integration
+
+Click any `MessagingComponent` in the Inspector for component-local diagnostics
+and any `MessageAwareComponent` subclass for base-call warning surfaces.
 
 #### 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
+- "Did my message fire?" -> Check Message Monitor history.
+- "Why didn't my handler run?" -> Check registrations and Flow Graph edges.
+- "What's firing too often?" -> Compare call counts in component and route summaries.
+- "Which source/target context was involved?" -> Check Message Monitor context
+  and Flow Graph trace paths.
 
 **No more:** Setting 50 breakpoints and stepping through code for 30 minutes.
 
+See [Diagnostics](docs/guides/diagnostics.md) for the current editor tooling and
+trace-path semantics. The
+[Diagnostics Tooling Exerciser](Samples~/Diagnostics%20Tooling%20Exerciser/README.md)
+sample imports a deterministic scene that drives Message Monitor, Flow Graph,
+Inspector diagnostics, and Project Settings together.
+
 ### Local Bus Islands for Testing
 
 **The problem with normal events:** Global static events contaminate tests. Mock complexity. Flaky tests.
@@ -654,8 +701,9 @@ public void TestAchievementSystem() {
     // Test in isolation
     _ = token.RegisterBroadcastWithoutSource<EnemyKilled>(achievements.OnKill);
 
+    var gameObject = new GameObject();
     var msg = new EnemyKilled("Boss");
-    msg.EmitGameObjectBroadcast(enemy, testBus);  // Only this test sees it
+    msg.EmitGameObjectBroadcast(gameObject, testBus);  // Only this test sees it
 
     Assert.IsTrue(achievements.Unlocked("BossSlayer"));
 }
@@ -693,7 +741,7 @@ public void TestAchievementSystem() {
 
 - [Unity Integration](docs/guides/unity-integration.md) -- MessagingComponent deep dive
 - [Targeting & Context](docs/concepts/targeting-and-context.md) -- GameObject vs Component
-- [Diagnostics](docs/guides/diagnostics.md) -- Inspector tools and debugging
+- [Diagnostics](docs/guides/diagnostics.md) -- editor tools, traces, and debugging
 - [Memory Reclamation](docs/guides/memory-reclamation.md) -- idle eviction, explicit Trim, and tuning the runtime settings asset
 
 Important: Inheritance with MessageAwareComponent
@@ -872,6 +920,7 @@ Import samples from Package Manager:
 
 - **[Mini Combat](Samples~/Mini%20Combat/README.md)** -- Simple combat with Heal/Damage messages
 - **[UI Buttons + Inspector](Samples~/UI%20Buttons%20%2B%20Inspector/README.md)** -- Interactive diagnostics demo
+- **[Diagnostics Tooling Exerciser](Samples~/Diagnostics%20Tooling%20Exerciser/README.md)** -- Deterministic scene for Message Monitor, Flow Graph, Inspector diagnostics, and Project Settings
 
 ## Requirements
 
@@ -908,7 +957,7 @@ DxMessaging publishes machine-readable context for AI agents through [llms.txt](
 
 - **[llms.txt](llms.txt)** -- Complete project overview, API reference, and context in a single file
 - **[Repository Guidelines](.llm/context.md)** -- Coding standards and development workflows
-- **[AI Agent Skills](.llm/skills/)** -- 157+ specialized skill documents covering documentation, testing, GitHub Actions, and more
+- **[AI Agent Skills](.llm/skills/)** -- 159+ specialized skill documents covering documentation, testing, GitHub Actions, and more
 
 The `llms.txt` file is automatically updated via CI/CD to stay current with project changes. It includes:
 

package/Runtime/AssemblyInfo.cs

@@ -14,3 +14,4 @@ using System.Runtime.CompilerServices;
 [assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime.Zenject")]
 [assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Editor")]
 [assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Editor.Allocations")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.00.Runtime.Benchmarks")]

package/Runtime/Core/Diagnostics/MessageEmissionData.cs

@@ -17,7 +17,9 @@ namespace DxMessaging.Core.Diagnostics
     /// that excludes DxMessaging internals for easier debugging.
     ///
     /// The <see cref="context"/> contains the relevant <see cref="InstanceId"/> for targeted/broadcast messages
-    /// (target or source respectively) and is null for untargeted messages.
+    /// (target or source respectively) and is null for untargeted messages. Runtime records emitted by a
+    /// <see cref="MessageBus.MessageBus"/> also carry a <see cref="traceId"/> that token-local delivery records can
+    /// use to join a bus emission to the registrations that observed it.
     /// </remarks>
     public readonly struct MessageEmissionData
     {
@@ -33,15 +35,41 @@ namespace DxMessaging.Core.Diagnostics
         /// <summary>Trimmed stack trace captured at the emission site.</summary>
         public readonly string stackTrace;
 
+        /// <summary>
+        /// Dispatch trace identifier shared by bus-side emission records and token-side delivery records.
+        /// </summary>
+        public readonly long traceId;
+
+        /// <summary>
+        /// Registration handle that observed this message; default for bus-side emission records.
+        /// </summary>
+        public readonly MessageRegistrationHandle registrationHandle;
+
         /// <summary>
         /// Creates a new diagnostic record for an emitted message.
         /// </summary>
         /// <param name="message">The message that was emitted.</param>
         /// <param name="context">Target or source depending on message category; null for untargeted.</param>
         public MessageEmissionData(IMessage message, InstanceId? context = null)
+            : this(message, context, traceId: 0, registrationHandle: default) { }
+
+        internal MessageEmissionData(IMessage message, long traceId)
+            : this(message, context: null, traceId, registrationHandle: default) { }
+
+        internal MessageEmissionData(IMessage message, InstanceId? context, long traceId)
+            : this(message, context, traceId, registrationHandle: default) { }
+
+        internal MessageEmissionData(
+            IMessage message,
+            InstanceId? context,
+            long traceId,
+            MessageRegistrationHandle registrationHandle
+        )
         {
             this.message = message;
             this.context = context;
+            this.traceId = traceId;
+            this.registrationHandle = registrationHandle;
             stackTrace = GetAccurateStackTrace();
         }
 

package/Runtime/Core/Extensions/MessageExtensions.cs

@@ -23,10 +23,9 @@ namespace DxMessaging.Core.Extensions
     /// var heal = new Heal(10);
     /// heal.EmitTargeted(target);
     ///
-    /// // Broadcast (from source)
-    /// var source = (DxMessaging.Core.InstanceId)gameObject;
+    /// // Broadcast (from this GameObject)
     /// var dmg = new TookDamage(5);
-    /// dmg.EmitBroadcast(source);
+    /// dmg.EmitGameObjectBroadcast(gameObject);
     ///
     /// // Unity conveniences
     /// var hello = new StringMessage("Hello");
@@ -334,11 +333,11 @@ namespace DxMessaging.Core.Extensions
         /// public readonly partial struct TookDamage { public readonly int amount; }
         ///
         /// var dmg = new TookDamage(5);
-        /// dmg.EmitFrom((InstanceId)gameObject);        // OK: from GameObject
         /// dmg.EmitGameObjectBroadcast(gameObject);     // explicit, preferred in Unity code
+        /// dmg.EmitFrom(gameObject);                    // shorthand from the same GameObject
         ///
         /// // Pitfall: identifies the Component as source (won't match GO-source registrations)
-        /// dmg.EmitFrom((InstanceId)this);
+        /// dmg.EmitComponentBroadcast(this);
         /// </code>
         /// </example>
         public static void EmitFrom<TMessage>(

package/Runtime/Core/Helper/MessageCache.cs

@@ -1,5 +1,6 @@
 namespace DxMessaging.Core.Helper
 {
+    using System;
     using System.Collections;
     using System.Collections.Generic;
     using System.Runtime.CompilerServices;
@@ -8,7 +9,7 @@ namespace DxMessaging.Core.Helper
     /// Sparse, type-indexed cache keyed by message type for fast lookups without dictionaries.
     /// </summary>
     /// <remarks>
-    /// Internally maintains a list indexed by a compact, per-message-type integer (assigned via
+    /// Internally maintains a sparse array indexed by a compact, per-message-type integer (assigned via
     /// <see cref="MessageHelperIndexer{TMessage}"/>). Used heavily by the bus to store handlers and interceptors
     /// with minimal overhead.
     /// </remarks>
@@ -39,8 +40,8 @@ namespace DxMessaging.Core.Helper
             /// <returns><c>true</c> if another non-null value exists; otherwise <c>false</c>.</returns>
             public bool MoveNext()
             {
-                List<TValue> values = _cache._values;
-                int count = values.Count;
+                TValue[] values = _cache._values;
+                int count = _cache._count;
                 while (++_index < count)
                 {
                     _current = values[_index];
@@ -74,7 +75,8 @@ namespace DxMessaging.Core.Helper
             public void Dispose() { }
         }
 
-        private readonly List<TValue> _values = new();
+        private TValue[] _values = Array.Empty<TValue>();
+        private int _count;
 
         /// <summary>
         /// Retrieves the value associated with <typeparamref name="TMessage"/>, creating one if needed.
@@ -89,7 +91,7 @@ namespace DxMessaging.Core.Helper
             int index = MessageHelperIndexer<TMessage>.SequentialId;
             if (0 <= index)
             {
-                FillToIndex(index);
+                EnsureIndex(index);
                 value = _values[index];
                 if (value != null)
                 {
@@ -101,11 +103,9 @@ namespace DxMessaging.Core.Helper
             }
             else
             {
-                index = MessageHelperIndexer.TotalMessages++;
-                MessageHelperIndexer<TMessage>.SequentialId = index;
-                FillToIndex(index - 1);
+                index = AssignIndex<TMessage>();
                 value = new TValue();
-                _values.Add(value);
+                _values[index] = value;
             }
 
             return value;
@@ -123,15 +123,13 @@ namespace DxMessaging.Core.Helper
             int index = MessageHelperIndexer<TMessage>.SequentialId;
             if (0 <= index)
             {
-                FillToIndex(index);
+                EnsureIndex(index);
                 _values[index] = value;
                 return;
             }
 
-            index = MessageHelperIndexer.TotalMessages++;
-            MessageHelperIndexer<TMessage>.SequentialId = index;
-            FillToIndex(index - 1);
-            _values.Add(value);
+            index = AssignIndex<TMessage>();
+            _values[index] = value;
         }
 
         /// <summary>
@@ -145,7 +143,7 @@ namespace DxMessaging.Core.Helper
             where TMessage : IMessage
         {
             int index = MessageHelperIndexer<TMessage>.SequentialId;
-            if (0 <= index && index < _values.Count)
+            if (0 <= index && index < _values.Length)
             {
                 value = _values[index];
                 return value != null;
@@ -164,7 +162,7 @@ namespace DxMessaging.Core.Helper
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         internal bool TryGetValueAtIndex(int index, out TValue value)
         {
-            if (0 <= index && index < _values.Count)
+            if (0 <= index && index < _values.Length)
             {
                 value = _values[index];
                 return value != null;
@@ -183,7 +181,7 @@ namespace DxMessaging.Core.Helper
             where TMessage : IMessage
         {
             int index = MessageHelperIndexer<TMessage>.SequentialId;
-            if (0 <= index && index < _values.Count)
+            if (0 <= index && index < _values.Length)
             {
                 _values[index] = null;
             }
@@ -196,7 +194,7 @@ namespace DxMessaging.Core.Helper
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         internal void RemoveAtIndex(int index)
         {
-            if (0 <= index && index < _values.Count)
+            if (0 <= index && index < _values.Length)
             {
                 _values[index] = null;
             }
@@ -224,17 +222,52 @@ namespace DxMessaging.Core.Helper
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         internal void Clear()
         {
-            _values.Clear();
+            _values = Array.Empty<TValue>();
+            _count = 0;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private int AssignIndex<TMessage>()
+            where TMessage : IMessage
+        {
+            int index = MessageHelperIndexer.TotalMessages;
+            EnsureIndex(index);
+            MessageHelperIndexer<TMessage>.SequentialId = index;
+            MessageHelperIndexer.TotalMessages = index + 1;
+            return index;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private void FillToIndex(int index)
+        private void EnsureIndex(int index)
         {
-            int count = _values.Count;
-            for (int i = count; i <= index; ++i)
+            if (index < 0)
+            {
+                throw new InvalidOperationException("Message type indices cannot be negative.");
+            }
+
+            if (index < _values.Length)
+            {
+                if (_count <= index)
+                {
+                    _count = index + 1;
+                }
+                return;
+            }
+
+            int capacity = _values.Length == 0 ? 4 : _values.Length;
+            while (capacity <= index)
             {
-                _values.Add(null);
+                if (capacity > int.MaxValue >> 1)
+                {
+                    throw new InvalidOperationException(
+                        "The message type index exceeds the cache's supported capacity."
+                    );
+                }
+                capacity <<= 1;
             }
+
+            Array.Resize(ref _values, capacity);
+            _count = index + 1;
         }
     }
 }

package/Runtime/Core/Internal/FlatDispatch.cs

@@ -68,6 +68,23 @@ namespace DxMessaging.Core.Internal
     /// </summary>
     internal abstract class FlatDispatchArray
     {
+        internal abstract int Count { get; }
+
+        /// <summary>
+        /// Physical length of the currently rented entry array. Exposed only for internal
+        /// storage benchmarks; dispatch continues to use <see cref="Count"/> as its bound.
+        /// </summary>
+        internal abstract int Capacity { get; }
+
+        /// <summary>
+        /// Number of released holders currently retained by this holder shape's pool. Released
+        /// holders have already returned their rented arrays and hold <c>Array.Empty</c>,
+        /// so this is empty-holder pool topology, not retained array-memory evidence. Array-pool
+        /// retained bytes require external memory measurement. This benchmark telemetry does not
+        /// participate in rent/release decisions.
+        /// </summary>
+        internal abstract int EmptyHolderPoolCount { get; }
+
         internal abstract void Release();
     }
 
@@ -108,6 +125,21 @@ namespace DxMessaging.Core.Internal
         internal TEntry[] entries = Array.Empty<TEntry>();
         internal int count;
 
+        internal override int Count => count;
+
+        internal override int Capacity => entries.Length;
+
+        internal override int EmptyHolderPoolCount
+        {
+            get
+            {
+                lock (HolderPoolLock)
+                {
+                    return HolderPool.Count;
+                }
+            }
+        }
+
         // True while the holder is parked in (or eligible for) the pool;
         // false while it is owned by a live DispatchSnapshot. Guards the
         // rent/release lifecycle against double-release and rent-of-live.

package/Runtime/Core/Internal/TypedSlots.cs

@@ -28,13 +28,9 @@ namespace DxMessaging.Core.Internal
     /// surface picks up no new members from the interface retrofit.
     /// </para>
     /// <para>
-    /// Deliberately a thin, marker-style surface: only the five members that
-    /// staged dispatch (<see cref="Version"/>, <see cref="LastSeenVersion"/>,
-    /// <see cref="LastSeenEmissionId"/>) and eviction
-    /// (<see cref="IsEmpty"/>, <see cref="Reset"/>) require. The
-    /// <c>entries</c> dictionary and <c>cache</c> list are NOT exposed
-    /// because their generic shape is the very thing this interface erases;
-    /// dispatchers that need the typed cache down-cast at the call site.
+    /// Deliberately a thin erased lifecycle surface for staged dispatch and eviction.
+    /// Generic keys, values, snapshot lists, and representation diagnostics are not
+    /// exposed; dispatchers that need typed entries down-cast at the call site.
     /// </para>
     /// </remarks>
     internal interface IHandlerActionCache