com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/{Docs/Advanced.md → docs/guides/advanced.md}

@@ -201,7 +201,7 @@ Do's
 - Listeners registered **during** an emission will **not** run for that emission — they only become active for the **next** emission.
 - This prevents infinite loops (e.g., a handler that registers itself won't recurse).
 - This applies to all message types (Untargeted, Targeted, Broadcast) and all listener types.
-- See [Interceptors & Ordering](InterceptorsAndOrdering.md#snapshot-semantics-frozen-listener-lists) for detailed examples.
+- See [Interceptors & Ordering](../concepts/interceptors-and-ordering.md#snapshot-semantics-frozen-listener-lists) for detailed examples.
 
 Don’ts
 
@@ -256,6 +256,6 @@ More advanced use cases
 
 Related
 
-- [Unity Integration](UnityIntegration.md)
-- [Diagnostics (Inspector)](Diagnostics.md)
-- [String Messages](StringMessages.md)
+- [Unity Integration](unity-integration.md)
+- [Diagnostics (Inspector)](diagnostics.md)
+- [String Messages](../advanced/string-messages.md)

package/docs/guides/advanced.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 6f33244a60113bc4d9d6167c5bfc60e4
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/docs/guides/diagnostics.md

@@ -0,0 +1,300 @@
+# Diagnostics
+
+DxMessaging emphasizes visibility. You can enable diagnostics globally or per token, inspect recent emissions, page through registrations, and even view contexts (targets/sources) — all from the MessagingComponent inspector.
+
+## DiagnosticsTarget Enum
+
+The `DiagnosticsTarget` enum is a flags enum that controls when diagnostics are enabled. It allows fine-grained control over which execution environments collect diagnostic data.
+
+| Value     | Description                                                     |
+| --------- | --------------------------------------------------------------- |
+| `Off`     | Diagnostics are disabled in all environments.                   |
+| `Editor`  | Diagnostics run only while in the Unity Editor.                 |
+| `Runtime` | Diagnostics run only in player/runtime builds (not the Editor). |
+| `All`     | Diagnostics run in both Editor and runtime environments.        |
+
+Because `DiagnosticsTarget` is a flags enum, you can combine values:
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+// Enable diagnostics only in the Unity Editor
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Editor;
+
+// Enable diagnostics only in runtime builds
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Runtime;
+
+// Enable diagnostics everywhere
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.All;
+
+// Disable diagnostics completely
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Off;
+```
+
+## Configuration Toggles
+
+DxMessaging provides multiple levels of diagnostics control:
+
+### Global Defaults
+
+- `IMessageBus.GlobalDiagnosticsTargets` — Sets the default diagnostics mode for newly created buses and tokens. Uses the `DiagnosticsTarget` flags enum.
+- `IMessageBus.GlobalMessageBufferSize` — Sets the default ring buffer size for emission history (default: 100).
+
+### Per-Bus and Per-Token
+
+- `IMessageBus.DiagnosticsMode` — Read-only property indicating whether diagnostics are active for a specific bus instance.
+- `MessageRegistrationToken.DiagnosticMode` — Controls diagnostics for an individual registration token.
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+
+// Configure global defaults before creating buses/tokens
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Editor;
+IMessageBus.GlobalMessageBufferSize = 200;
+
+// Check if diagnostics are enabled for a specific bus
+IMessageBus bus = MessageHandler.MessageBus;
+if (bus.DiagnosticsMode)
+{
+    Debug.Log("Diagnostics are active on this bus.");
+}
+```
+
+## RegistrationLog API
+
+The `RegistrationLog` class tracks all messaging registrations and deregistrations for a message bus. This is invaluable for debugging subscription issues and understanding message flow.
+
+### Properties
+
+| Property        | Type                                   | Description                                                             |
+| --------------- | -------------------------------------- | ----------------------------------------------------------------------- |
+| `Enabled`       | `bool`                                 | Get/set whether logging is active. Disabled by default for performance. |
+| `Registrations` | `IReadOnlyList<MessagingRegistration>` | Read-only access to all logged registrations.                           |
+
+### Methods
+
+#### `Log(MessagingRegistration registration)`
+
+Records a registration event. Called automatically by the message bus when `Enabled` is true.
+
+#### `GetRegistrations(InstanceId instanceId)`
+
+Returns all registrations for a specific instance. Useful for inspecting what a particular component has registered for.
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+
+IMessageBus bus = MessageHandler.MessageBus;
+bus.Log.Enabled = true;
+
+// After some registrations occur...
+InstanceId myComponent = GetComponent<MonoBehaviour>();
+foreach (MessagingRegistration reg in bus.Log.GetRegistrations(myComponent))
+{
+    Debug.Log($"Registered for {reg.type.Name} via {reg.registrationMethod}");
+}
+```
+
+#### `ToString()` and `ToString(Func<MessagingRegistration, string> serializer)`
+
+Returns a string representation of all logged registrations. You can provide a custom serializer for formatted output.
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+
+IMessageBus bus = MessageHandler.MessageBus;
+bus.Log.Enabled = true;
+
+// ... after some registrations/deregistrations
+Debug.Log(bus.Log.ToString());
+
+// Custom formatting
+string formatted = bus.Log.ToString(reg =>
+    $"[{reg.registrationType}] {reg.type.Name} @ {reg.time:F2}s"
+);
+Debug.Log(formatted);
+```
+
+#### `Clear(Predicate<MessagingRegistration> shouldRemove = null)`
+
+Removes registrations from the log. Pass `null` to clear all, or provide a predicate to selectively remove entries.
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+
+IMessageBus bus = MessageHandler.MessageBus;
+
+// Clear all registrations
+int cleared = bus.Log.Clear();
+
+// Clear only deregistrations
+int deregistrationsCleared = bus.Log.Clear(
+    reg => reg.registrationType == RegistrationType.Deregister
+);
+```
+
+## MessagingRegistration Struct
+
+Each logged registration is stored as a `MessagingRegistration` struct containing:
+
+| Field                | Type                 | Description                                                  |
+| -------------------- | -------------------- | ------------------------------------------------------------ |
+| `id`                 | `InstanceId`         | The handler's unique identifier.                             |
+| `type`               | `Type`               | The message type being registered for.                       |
+| `registrationType`   | `RegistrationType`   | Whether this was a `Register` or `Deregister` event.         |
+| `registrationMethod` | `RegistrationMethod` | The exact registration category (Targeted, Broadcast, etc.). |
+| `time`               | `float`              | Unity time when the registration occurred (Unity only).      |
+
+### RegistrationMethod Values
+
+The `RegistrationMethod` enum captures how the handler was wired up:
+
+- `Targeted` — Bound to a specific recipient
+- `Untargeted` — Global untargeted handler
+- `Broadcast` — Bound to a specific source
+- `BroadcastWithoutSource` — Broadcast handler without explicit source
+- `TargetedWithoutTargeting` — Targeted handler ignoring runtime target
+- `GlobalAcceptAll` — Catch-all handler
+- `Interceptor` — Message interceptor
+- `UntargetedPostProcessor`, `TargetedPostProcessor`, `BroadcastPostProcessor` — Post-processors
+- `TargetedWithoutTargetingPostProcessor` — Post-processor for targeted messages ignoring runtime target
+- `BroadcastWithoutSourcePostProcessor` — Post-processor for broadcasts without explicit source
+
+## Emission History
+
+When diagnostics are enabled, buses and tokens record message emissions in a ring buffer:
+
+- Buffer size is controlled by `IMessageBus.GlobalMessageBufferSize` (default: 100).
+- Setting buffer size to 0 disables history retention (emissions are silently discarded).
+- Inspect recent emissions per token via built-in diagnostics or build custom tools using post-processors.
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+// Increase buffer size for more history
+IMessageBus.GlobalMessageBufferSize = 500;
+```
+
+## Logging Integration
+
+Integrate DxMessaging with your logging framework:
+
+```csharp
+using DxMessaging.Core;
+
+MessagingDebug.enabled = true;
+MessagingDebug.LogFunction = (level, msg) =>
+    UnityEngine.Debug.Log($"[DxMessaging:{level}] {msg}");
+```
+
+## Per-Environment Configuration
+
+A common pattern is enabling diagnostics only in the Editor for development visibility while keeping runtime builds lean.
+
+### Editor-Only Diagnostics
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+// Enable diagnostics only when running in the Unity Editor
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Editor;
+```
+
+This is the recommended default for most projects. You get full visibility during development without any performance cost in production builds.
+
+### Runtime Diagnostics for QA Builds
+
+For QA or debug builds where you need diagnostics in the player:
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+#if DEVELOPMENT_BUILD || UNITY_EDITOR
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.All;
+#else
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Off;
+#endif
+```
+
+### Conditional Logging Based on Build Type
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+
+public static class DiagnosticsBootstrap
+{
+    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
+    private static void Initialize()
+    {
+#if UNITY_EDITOR
+        IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Editor;
+        IMessageBus.GlobalMessageBufferSize = 200;
+        MessageHandler.MessageBus.Log.Enabled = true;
+#elif DEVELOPMENT_BUILD
+        IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Runtime;
+        IMessageBus.GlobalMessageBufferSize = 50;
+#else
+        IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Off;
+#endif
+    }
+}
+```
+
+## Performance Considerations
+
+Diagnostics add overhead. Consider these factors when enabling them:
+
+### Memory Impact
+
+- Each `MessagingRegistration` struct consumes memory for the registration log.
+- The emission ring buffer stores `MessageEmissionData` records (controlled by `GlobalMessageBufferSize`).
+- Larger buffer sizes consume more memory but provide more history.
+
+### CPU Impact
+
+- Registration logging adds overhead to every `Register` and `Deregister` call.
+- Emission recording adds overhead to every message broadcast.
+- Post-processor chains for diagnostics run after each message dispatch.
+
+### Recommendations
+
+| Environment        | Recommended Setting                     | Buffer Size |
+| ------------------ | --------------------------------------- | ----------- |
+| Development/Editor | `DiagnosticsTarget.Editor`              | 100-200     |
+| QA/Debug Builds    | `DiagnosticsTarget.All`                 | 50-100      |
+| Release Builds     | `DiagnosticsTarget.Off`                 | N/A         |
+| Automated Tests    | `DiagnosticsTarget.All` + `Log.Enabled` | 100         |
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+// Production-safe defaults
+IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Off;
+IMessageBus.GlobalMessageBufferSize = 0; // No history retention
+```
+
+## Editor Integration (Inspector)
+
+Attach `MessagingComponent` to a GameObject. In the Unity Inspector:
+
+- **Enable/Disable Global Diagnostics**: Toggles bus-wide recording.
+- **Global Buffer**: Paged view of recent emissions (type and context). Matching listeners are highlighted.
+- **Local Buffer**: Per-listener ring buffer; enable per-token diagnostics to populate.
+- **Registrations**: Paged list of what each listener registered for (type, priority, context).
+
+## Tips
+
+- Turn on diagnostics while developing; turn off for release builds if you don't need runtime recording.
+- Use `RegisterTargetedWithoutTargeting` or `RegisterBroadcastWithoutSource` for custom monitoring dashboards.
+- Set `Log.Enabled = true` in tests to verify registration behavior.
+- Use `Log.Clear()` between test cases to isolate registration tracking.
+
+## Related
+
+- [Listening Patterns](../concepts/listening-patterns.md)
+- [Troubleshooting](../reference/troubleshooting.md)

package/docs/guides/diagnostics.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: ccd582351affbfc418defaa919a964ff
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/{Docs/MigrationGuide.md → docs/guides/migration-guide.md}

@@ -22,7 +22,7 @@ This guide helps you introduce DxMessaging into an existing Unity project **grad
 ### Goal: Get comfortable without touching production code
 
 1. **Install DxMessaging** via Package Manager
-1. **Read the [Visual Guide](VisualGuide.md)** (5 minutes)
+1. **Read the [Visual Guide](../getting-started/visual-guide.md)** (5 minutes)
 1. **Import the Mini Combat sample** from Package Manager
 1. **Create a throwaway test scene** and try:
 
@@ -347,7 +347,7 @@ door.Close();
 #### Solution
 
 - Schedule a 30-minute walkthrough
-- Share the [Visual Guide](VisualGuide.md)
+- Share the [Visual Guide](../getting-started/visual-guide.md)
 - Pair program on first migrations
 - Document team conventions in your wiki
 
@@ -510,4 +510,4 @@ Profile early, measure impact.
 
 ---
 
-**Questions?** See [FAQ](FAQ.md) | **Need patterns?** See [Common Patterns](Patterns.md)
+**Questions?** See [FAQ](../reference/faq.md) | **Need patterns?** See [Common Patterns](patterns.md)

package/docs/guides/migration-guide.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 80c561972458cc24cad7256da3cbe0fa
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/{Docs/Patterns.md → docs/guides/patterns.md}

@@ -1,6 +1,6 @@
 # DxMessaging Patterns: Real-World Solutions
 
-[← Back to Index](Index.md) | [Getting Started](GettingStarted.md) | [Message Types](MessageTypes.md) | [Samples](../Samples~/)
+[← Back to Index](../getting-started/index.md) | [Getting Started](../getting-started/getting-started.md) | [Message Types](../concepts/message-types.md) | [Samples](https://github.com/wallstop/DxMessaging/tree/master/Samples~)
 
 ---
 
@@ -10,7 +10,7 @@
 
 - **Basic Patterns** - Fundamental building blocks (scene transitions, commands, observability)
 - **Advanced Patterns** - Power user techniques (diagnostics, testing, legacy integration)
-- **Scale Patterns** - Production-ready examples (100+ entities, cross-scene systems, large UI)
+- **Scale Patterns** - Examples for larger systems (100+ entities, cross-scene systems, large UI)
 
 ### Reading guide
 
@@ -19,7 +19,7 @@
 - **Building at scale?** Go straight to Real-World Scale Patterns
 - **Specific problem?** Use Ctrl+F / Cmd+F to search
 
-**Philosophy:** These aren't toy examples. They're patterns from real games with real problems.
+**Philosophy:** These patterns address common challenges teams face when building messaging systems.
 
 ---
 
@@ -173,7 +173,7 @@ Use interceptors to enforce rules before handlers run.
 using DxMessaging.Core; // MessageHandler
 
 var bus = MessageHandler.MessageBus;
-_ = token.RegisterTargetedInterceptor<TookDamage>((ref InstanceId target, ref TookDamage m) =>
+_ = token.RegisterBroadcastInterceptor<TookDamage>((ref InstanceId source, ref TookDamage m) =>
 {
     if (m.amount <= 0) return false; // cancel
     m = new TookDamage(Math.Min(m.amount, 999)); // clamp
@@ -186,7 +186,7 @@ _ = token.RegisterTargetedInterceptor<TookDamage>((ref InstanceId target, ref To
 Post-processors run after handlers—ideal for metrics.
 
 ```csharp
-_ = token.RegisterUntargetedPostProcessor<SceneLoaded>((ref SceneLoaded m) => Metrics.TrackScene(m.index));
+_ = token.RegisterUntargetedPostProcessor<SceneLoaded>((ref SceneLoaded m) => Metrics.TrackScene(m.buildIndex));
 ```
 
 ## 6) Local Bus Islands
@@ -566,7 +566,7 @@ public class DamageValidator : MessageAwareComponent {
 // Handlers can trust data is valid (no duplicate checks needed)
 public class CombatEntity : MessageAwareComponent {
     protected override void RegisterMessageHandlers() {
-        _ = Token.RegisterComponentTargeted<EntityDamaged>(this, OnDamaged);
+        _ = Token.RegisterComponentBroadcast<EntityDamaged>(this, OnDamaged);
     }
 
     void OnDamaged(ref EntityDamaged msg) {
@@ -772,7 +772,7 @@ public class MatchStats : MessageAwareComponent {
 
 ## 14) Compatibility with Scriptable Object Architecture (SOA)
 
-**Disclaimer:** Scriptable Object Architecture (SOA) is a debated pattern in the Unity community. While it has proponents, there are documented criticisms regarding its scalability and maintainability. See [Anti-ScriptableObject Architecture](https://github.com/cathei/AntiScriptableObjectArchitecture) for a detailed critique. **SOA is not a recommended pattern** for most projects, unless you need designers wiring events. Consider alternatives like dependency injection (Zenject, VContainer), reactive systems (UniRx), or messaging systems (DxMessaging, MessagePipe), as they often provide better long-term maintainability.
+**Note:** Scriptable Object Architecture (SOA) is a debated pattern in the Unity community. It has both proponents who value its designer-friendly workflow and critics who raise concerns about scalability and maintainability. See [Anti-ScriptableObject Architecture](https://github.com/cathei/AntiScriptableObjectArchitecture) for one perspective on the criticisms. Teams should evaluate SOA based on their specific needs. Alternatives include dependency injection (Zenject, VContainer), reactive systems (UniRx), or messaging systems (DxMessaging, MessagePipe).
 
 That said, if your project uses or requires SOA, DxMessaging can work alongside it.
 
@@ -806,7 +806,7 @@ From [Anti-ScriptableObject Architecture](https://github.com/cathei/AntiScriptab
 
 #### Recommended alternatives
 
-- **Dependency Injection** - Zenject, VContainer, Reflex (see [DxMessaging DI Integrations](Integrations/))
+- **Dependency Injection** - Zenject, VContainer, Reflex (see [DxMessaging DI Integrations](../integrations/index.md))
 - **Reactive Systems** - UniRx, UniTask
 - **Messaging** - DxMessaging (this framework), MessagePipe
 - **Configuration Data** - Spreadsheet-based solutions (e.g., BakingSheet)
@@ -828,7 +828,7 @@ Use ScriptableObjects for their intended purpose: **immutable design-time data**
 | **Use Case**         | Shared state, designer-driven configs                                               | Event-driven communication, runtime logic |
 | **Testability**      | ⚠️ Requires SO asset cleanup                                                        | ✅ Isolated buses per test                |
 
-**Bottom line:** If you're starting fresh, prefer DxMessaging or DI. If you have legacy SOA code, the patterns below show coexistence strategies.
+**Summary:** For new projects, evaluate DxMessaging, DI frameworks, or other messaging approaches based on your needs. If you have existing SOA code, the patterns below show coexistence strategies.
 
 ### Pattern Overview
 
@@ -999,7 +999,7 @@ public class CombatAnalytics : MessageAwareComponent
 - ✅ Uses each system correctly: SOs for their intended purpose (immutable design data), messaging for runtime communication
 - ✅ This is NOT SOA - it's proper Unity architecture
 
-###### This is the recommended pattern for all projects
+###### This pattern separates concerns clearly
 
 ### When to Use Each Pattern
 
@@ -1048,7 +1048,7 @@ For SOA variables:
 - [Anti-ScriptableObject Architecture](https://github.com/cathei/AntiScriptableObjectArchitecture) - Detailed critique
 - [Ryan Hipple Unite 2017 Talk](https://www.youtube.com/watch?v=raQ3iHhE_Kk) - Original SOA presentation
 - [Unity Official Guide](https://unity.com/how-to/architect-game-code-scriptable-objects) - Unity's perspective
-- [DxMessaging DI Integrations](Integrations/) - Better alternatives for dependency management
+- [DxMessaging DI Integrations](../integrations/index.md) - Better alternatives for dependency management
 - [Zenject](https://github.com/modesttree/Zenject) - Recommended DI framework
 - [VContainer](https://github.com/hadashiA/VContainer) - Lightweight DI alternative
 
@@ -1058,23 +1058,23 @@ For SOA variables:
 
 ### Learn the Basics First?
 
-- → [Getting Started](GettingStarted.md) (10 min) — Complete introduction
-- → [Message Types](MessageTypes.md) (10 min) — When to use what
-- → [Visual Guide](VisualGuide.md) (5 min) — Beginner-friendly pictures
+- → [Getting Started](../getting-started/getting-started.md) (10 min) — Complete introduction
+- → [Message Types](../concepts/message-types.md) (10 min) — When to use what
+- → [Visual Guide](../getting-started/visual-guide.md) (5 min) — Beginner-friendly pictures
 
 ### Try Real Examples
 
-- → [Mini Combat sample](../Samples~/Mini%20Combat/README.md) — Working combat example
-- → [UI Buttons + Inspector sample](../Samples~/UI%20Buttons%20%2B%20Inspector/README.md) — Interactive diagnostics
-- → [End-to-End Example](EndToEnd.md) — Complete feature walkthrough
+- → [Mini Combat sample](https://github.com/wallstop/DxMessaging/blob/master/Samples~/Mini%20Combat/README.md) — Working combat example
+- → [UI Buttons + Inspector sample](https://github.com/wallstop/DxMessaging/blob/master/Samples~/UI%20Buttons%20%2B%20Inspector/README.md) — Interactive diagnostics
+- → [End-to-End Example](../examples/end-to-end.md) — Complete feature walkthrough
 
 ### Deep Dives
 
-- → [Interceptors & Ordering](InterceptorsAndOrdering.md) — Control execution flow
-- → [Design & Architecture](DesignAndArchitecture.md) — Internals and optimizations
-- → [Performance](Performance.md) — Benchmarks and tuning
+- → [Interceptors & Ordering](../concepts/interceptors-and-ordering.md) — Control execution flow
+- → [Design & Architecture](../architecture/design-and-architecture.md) — Internals and optimizations
+- → [Performance](../architecture/performance.md) — Benchmarks and tuning
 
 ### Reference
 
-- → [Quick Reference](QuickReference.md) — Cheat sheet
-- → [API Reference](Reference.md) — Complete API
+- → [Quick Reference](../reference/quick-reference.md) — Cheat sheet
+- → [API Reference](../reference/reference.md) — Complete API

package/docs/guides/patterns.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 47fb90fdd5d4c0b4a9e07d13daaf24ed
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: