com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/coverage/lcov-report/transform-docs-to-wiki.js.html.meta

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

package/coverage/lcov-report/vendor.meta

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

package/coverage/lcov-report.meta

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

package/coverage/lcov.info.meta

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

package/{Docs/EmitShorthands.md → docs/advanced/emit-shorthands.md}

@@ -2,11 +2,11 @@
 
 **Quick, readable ways to send messages** without reaching for `MessageHandler.MessageBus` directly.
 
-These shorthands make your code cleaner and more expressive, but they come with important Unity-specific gotchas around GameObject vs Component targeting. Read the [Pitfalls](#unity-targeting-pitfalls) section to avoid silent bugs!
+These shorthands provide concise syntax for sending messages, but they come with important Unity-specific gotchas around GameObject vs Component targeting. Read the [Pitfalls](#unity-targeting-pitfalls) section to avoid silent bugs.
 
 ## What You Get
 
-Three simple methods that work on any message:
+Three methods that work on any message:
 
 | Method                 | Purpose                   | Message Type         | Example                                |
 | ---------------------- | ------------------------- | -------------------- | -------------------------------------- |
@@ -172,9 +172,9 @@ heal.EmitAt(this);
 
 **Remember:** In Unity, `this` inside a `MonoBehaviour` is always a Component, not a GameObject!
 
-### 🚀 Global Observers: Listen to ALL Events
+### Global Observers: Listen to All Events
 
-**Killer feature:** Unlike traditional event buses, you can listen to ALL targeted or broadcast messages without knowing specific targets/sources!
+**Feature:** DxMessaging allows listening to all targeted or broadcast messages without knowing specific targets/sources.
 
 ```csharp
 // Listen to ALL heals, regardless of target
@@ -194,16 +194,16 @@ void OnAnyDamage(ref InstanceId source, ref TookDamage msg)
 }
 ```
 
-#### Why this is revolutionary
+#### How this differs from some event bus patterns
 
-- **Classic event bus:** Subscribe to PlayerDamaged, EnemyDamaged, NPCDamaged... (tight coupling)
-- **DxMessaging:** Subscribe to ALL damage once (zero coupling, infinite scalability)
+- **Per-entity subscription:** Subscribe to PlayerDamaged, EnemyDamaged, NPCDamaged separately
+- **DxMessaging approach:** Subscribe to all damage events with one registration
 
 **Use cases:** Analytics, debugging, achievements, global UI, combat logs
 
 ---
 
-##### 📖 For the full deep dive on GameObject vs Component targeting and global observers, see [Targeting & Context](TargetingAndContext.md)
+##### 📖 For the full deep dive on GameObject vs Component targeting and global observers, see [Targeting & Context](../concepts/targeting-and-context.md)
 
 ---
 
@@ -267,13 +267,13 @@ DxMessaging includes three built-in string message types for rapid prototyping:
 "Hello".EmitAt(gameObject);
 
 // Or use explicit helpers
-"Hello".EmitGameObjectTargeted(gameObject); // Clearer!
+"Hello".EmitGameObjectTargeted(gameObject); // More explicit
 
 // Broadcast from GameObject
 "Died".EmitFrom(gameObject);
 
 // Or use explicit helpers
-"Died".EmitGameObjectBroadcast(gameObject); // Clearer!
+"Died".EmitGameObjectBroadcast(gameObject); // More explicit
 ```
 
 ### When to Use String Messages
@@ -291,7 +291,7 @@ DxMessaging includes three built-in string message types for rapid prototyping:
 - Performance-critical paths
 - Public APIs
 
-See [String Messages](StringMessages.md) for more details.
+See [String Messages](string-messages.md) for more details.
 
 ## Advanced: Optional Bus Parameter
 
@@ -362,7 +362,7 @@ public class DebugListener : MessagingComponent
 }
 ```
 
-See [Diagnostics](Diagnostics.md) for more debugging tools.
+See [Diagnostics](../guides/diagnostics.md) for more debugging tools.
 
 ## Comparison: Shorthands vs Explicit Helpers
 
@@ -461,8 +461,8 @@ public class AchievementTracker : MessageAwareComponent
 
 ## See Also
 
-- **[Quick Reference](QuickReference.md)** — API cheat sheet for all emit methods
-- **[Message Types](MessageTypes.md)** — Understand Untargeted, Targeted, and Broadcast messages
-- **[Targeting & Context](TargetingAndContext.md)** — Deep dive into GameObject vs Component
-- **[String Messages](StringMessages.md)** — More about string message helpers
-- **[Diagnostics](Diagnostics.md)** — Debugging tools and Inspector integration
+- **[Quick Reference](../reference/quick-reference.md)** — API cheat sheet for all emit methods
+- **[Message Types](../concepts/message-types.md)** — Understand Untargeted, Targeted, and Broadcast messages
+- **[Targeting & Context](../concepts/targeting-and-context.md)** — Deep dive into GameObject vs Component
+- **[String Messages](string-messages.md)** — More about string message helpers
+- **[Diagnostics](../guides/diagnostics.md)** — Debugging tools and Inspector integration

package/docs/advanced/emit-shorthands.md.meta

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

package/{Docs/MessageBusProviders.md → docs/advanced/message-bus-providers.md}

@@ -490,7 +490,8 @@ public class RuntimeReconfiguration : MonoBehaviour
 
 ## See Also
 
-- **[Runtime Configuration](RuntimeConfiguration.md)** — Setting and overriding global buses, re-binding registrations
-- **[DI Integration Guides](Integrations/)** — Zenject, VContainer, and Reflex integration patterns
-- **[Unity Integration](UnityIntegration.md)** — MessagingComponent and MessageAwareComponent deep dive
-- **[Back to Documentation Hub](Index.md)** — Browse all docs
+- **[Runtime Configuration](runtime-configuration.md)** — Setting and overriding global buses, re-binding registrations
+- **[Registration Builders](registration-builders.md)** — Fluent API for building message registrations with priority and lifecycle control
+- **[DI Integration Guides](../integrations/index.md)** — Zenject, VContainer, and Reflex integration patterns
+- **[Unity Integration](../guides/unity-integration.md)** — MessagingComponent and MessageAwareComponent deep dive
+- **[Back to Documentation Hub](../getting-started/index.md)** — Browse all docs

package/docs/advanced/message-bus-providers.md.meta

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

package/docs/advanced/registration-builders.md

@@ -0,0 +1,444 @@
+# Registration Builders
+
+The `MessageRegistrationBuilder` provides a structured way to create message registrations with fine-grained control over lifecycle, configuration, and resource cleanup.
+
+This guide covers:
+
+- When to use the builder pattern
+- Configuring registrations with options
+- Managing lifecycle with leases
+- Practical usage examples
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [MessageRegistrationBuilder](#messageregistrationbuilder)
+- [MessageRegistrationBuildOptions](#messageregistrationbuildoptions)
+- [MessageRegistrationLease](#messageregistrationlease)
+- [MessageRegistrationLifecycle](#messageregistrationlifecycle)
+- [Code Examples](#code-examples)
+- [See Also](#see-also)
+
+---
+
+## Overview
+
+DxMessaging offers two approaches to message registration:
+
+| Approach              | Use Case                                                                                 |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| Direct token creation | Simple scenarios with manual lifecycle management                                        |
+| Builder pattern       | Complex scenarios requiring DI integration, lifecycle hooks, or structured configuration |
+
+### When to use the builder pattern
+
+- You need lifecycle callbacks (build, activate, deactivate, dispose)
+- You want to integrate with dependency injection containers
+- You prefer a more declarative configuration style
+- You need to manage multiple registrations as a single unit
+
+#### When direct token creation is sufficient
+
+- Simple MonoBehaviour-based messaging
+- No need for lifecycle hooks
+- Using `MessagingComponent` or similar built-in components
+
+---
+
+## MessageRegistrationBuilder
+
+The `MessageRegistrationBuilder` class creates `MessageRegistrationLease` instances based on configuration options.
+
+### Creating a Builder
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+// Builder that uses global bus resolution
+MessageRegistrationBuilder builder = new MessageRegistrationBuilder();
+
+// Builder with a custom provider
+IMessageBusProvider provider = new FixedMessageBusProvider(myMessageBus);
+MessageRegistrationBuilder builderWithProvider = new MessageRegistrationBuilder(provider);
+```
+
+### Building Leases
+
+Call `Build()` with options to create a lease:
+
+```csharp
+MessageRegistrationBuildOptions options = new MessageRegistrationBuildOptions
+{
+    ActivateOnBuild = true,
+    Configure = token =>
+    {
+        _ = token.RegisterUntargeted<PlayerDamaged>(OnPlayerDamaged);
+    }
+};
+
+using MessageRegistrationLease lease = builder.Build(options);
+```
+
+---
+
+## MessageRegistrationBuildOptions
+
+Configure how the builder creates registrations using `MessageRegistrationBuildOptions`.
+
+### Owner Configuration
+
+Specify who owns the registration:
+
+```csharp
+// Explicit InstanceId owner
+options.Owner = new InstanceId(42);
+
+// Unity Object owner (Unity 2021.3+)
+options.UnityOwner = gameObject;  // or any Component
+```
+
+When omitted, a synthetic owner ID is generated automatically. `UnityOwner` takes precedence over `Owner` when both are set.
+
+### Message Bus Selection
+
+Control which bus handles registrations:
+
+```csharp
+// Use a specific bus directly
+options.PreferredMessageBus = myMessageBus;
+
+// Use a provider (falls back if PreferredMessageBus is null)
+options.MessageBusProvider = new FixedMessageBusProvider(otherBus);
+```
+
+Resolution order:
+
+1. `PreferredMessageBus` if set
+1. `MessageBusProvider.Resolve()` if provider is set
+1. Builder's provider (from constructor) if set
+1. `null` (uses global bus)
+
+---
+
+### Handler State
+
+Control the initial state of handlers:
+
+```csharp
+// Whether the underlying MessageHandler starts active (default: true)
+options.HandlerStartsActive = true;
+
+// Whether to call Enable() immediately after building (default: false)
+options.ActivateOnBuild = true;
+```
+
+### Diagnostics
+
+Enable diagnostic mode for debugging:
+
+```csharp
+options.EnableDiagnostics = true;
+```
+
+This sets `MessageRegistrationToken.DiagnosticMode` to `true`, enabling detailed logging.
+
+### Configure Callback
+
+Register handlers immediately after token creation:
+
+```csharp
+options.Configure = token =>
+{
+    _ = token.RegisterUntargeted<GameStarted>(OnGameStarted);
+    // For targeted messages, provide the target InstanceId
+    _ = token.RegisterTargeted<DamageMessage>(targetInstanceId, OnDamage);
+};
+```
+
+This callback runs after the token is created but before lifecycle hooks and activation.
+
+**Note:** `RegisterTargeted<T>` requires an `InstanceId` target parameter specifying which entity should receive the message. For Unity objects, use `RegisterGameObjectTargeted<T>` or `RegisterComponentTargeted<T>` instead.
+
+### Lifecycle Hooks
+
+Add callbacks for lifecycle events:
+
+```csharp
+options.Lifecycle = new MessageRegistrationLifecycle(
+    onBuild: token => Debug.Log("Token created"),
+    onActivate: token => Debug.Log("Token enabled"),
+    onDeactivate: token => Debug.Log("Token disabled"),
+    onDispose: token => Debug.Log("Token disposed")
+);
+```
+
+---
+
+## MessageRegistrationLease
+
+A `MessageRegistrationLease` wraps the created token and provides lifecycle management.
+
+### Properties
+
+| Property     | Type                       | Description                           |
+| ------------ | -------------------------- | ------------------------------------- |
+| `Token`      | `MessageRegistrationToken` | The underlying registration token     |
+| `Handler`    | `MessageHandler`           | The handler hosting registrations     |
+| `MessageBus` | `IMessageBus`              | The bus used for registrations        |
+| `Owner`      | `InstanceId`               | The owner identifier                  |
+| `IsActive`   | `bool`                     | Whether the lease is currently active |
+
+### Activation Methods
+
+```csharp
+// Enable the token and invoke OnActivate callback
+lease.Activate();
+
+// Disable the token and invoke OnDeactivate callback
+lease.Deactivate();
+```
+
+- `Activate()` throws `ObjectDisposedException` if called after disposal
+- `Deactivate()` is safe to call multiple times or after disposal
+
+### Dispose Pattern
+
+Leases implement `IDisposable`:
+
+```csharp
+using MessageRegistrationLease lease = builder.Build(options);
+// ... use the lease
+// Automatically deactivated and disposed at end of scope
+```
+
+Disposal sequence:
+
+1. Calls `Deactivate()` if active (triggers `OnDeactivate`)
+1. Invokes `OnDispose` callback
+1. Marks lease as disposed
+
+---
+
+## MessageRegistrationLifecycle
+
+The `MessageRegistrationLifecycle` struct holds callbacks for each lifecycle stage:
+
+```csharp
+public readonly struct MessageRegistrationLifecycle
+{
+    public MessageRegistrationLifecycle(
+        Action<MessageRegistrationToken> onBuild,
+        Action<MessageRegistrationToken> onActivate,
+        Action<MessageRegistrationToken> onDeactivate,
+        Action<MessageRegistrationToken> onDispose);
+
+    public Action<MessageRegistrationToken> OnBuild { get; }
+    public Action<MessageRegistrationToken> OnActivate { get; }
+    public Action<MessageRegistrationToken> OnDeactivate { get; }
+    public Action<MessageRegistrationToken> OnDispose { get; }
+}
+```
+
+### Callback Order
+
+1. `OnBuild` — Immediately after lease creation, before activation
+1. `OnActivate` — When `Activate()` is called (or automatically if `ActivateOnBuild = true`)
+1. `OnDeactivate` — When `Deactivate()` is called or during disposal while active
+1. `OnDispose` — During `Dispose()`, after deactivation
+
+All callbacks receive the `MessageRegistrationToken` as a parameter.
+
+---
+
+## Code Examples
+
+### Basic Builder Usage
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using UnityEngine;
+
+public sealed class BasicBuilderExample : MonoBehaviour
+{
+    private MessageRegistrationBuilder builder;
+    private MessageRegistrationLease lease;
+
+    private void Awake()
+    {
+        builder = new MessageRegistrationBuilder();
+
+        MessageRegistrationBuildOptions options = new MessageRegistrationBuildOptions
+        {
+            UnityOwner = this,
+            ActivateOnBuild = true,
+            Configure = token =>
+            {
+                _ = token.RegisterUntargeted<GameEvent>(OnGameEvent);
+            }
+        };
+
+        lease = builder.Build(options);
+    }
+
+    private void OnDestroy()
+    {
+        lease?.Dispose();
+    }
+
+    // Action<T> handler signature (used with RegisterUntargeted<T>(..., Action<T>))
+    private void OnGameEvent(GameEvent message)
+    {
+        Debug.Log($"Received: {message}");
+    }
+
+    // Alternative: FastHandler<T> signature for better performance (avoids boxing)
+    // private void OnGameEvent(ref GameEvent message)
+    // {
+    //     Debug.Log($"Received: {message}");
+    // }
+}
+```
+
+### DI Integration Pattern
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using UnityEngine;
+
+public sealed class DIIntegrationExample : MonoBehaviour
+{
+    // Injected by your DI container
+    private IMessageBusProvider messageBusProvider;
+    private MessageRegistrationLease lease;
+
+    public void Initialize(IMessageBusProvider provider)
+    {
+        messageBusProvider = provider;
+
+        MessageRegistrationBuilder builder = new MessageRegistrationBuilder(provider);
+
+        MessageRegistrationBuildOptions options = new MessageRegistrationBuildOptions
+        {
+            UnityOwner = this,
+            ActivateOnBuild = true,
+            Configure = ConfigureRegistrations
+        };
+
+        lease = builder.Build(options);
+    }
+
+    private void ConfigureRegistrations(MessageRegistrationToken token)
+    {
+        _ = token.RegisterUntargeted<PlayerSpawned>(OnPlayerSpawned);
+        _ = token.RegisterUntargeted<PlayerDied>(OnPlayerDied);
+    }
+
+    private void OnDestroy()
+    {
+        lease?.Dispose();
+    }
+
+    // Action<T> handler signatures
+    private void OnPlayerSpawned(PlayerSpawned message)
+    {
+        Debug.Log($"Player spawned: {message.PlayerId}");
+    }
+
+    private void OnPlayerDied(PlayerDied message)
+    {
+        Debug.Log($"Player died: {message.PlayerId}");
+    }
+}
+```
+
+### Custom Lifecycle Hooks
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using UnityEngine;
+
+public sealed class LifecycleHooksExample : MonoBehaviour
+{
+    private MessageRegistrationBuilder builder;
+    private MessageRegistrationLease lease;
+
+    private void Awake()
+    {
+        builder = new MessageRegistrationBuilder();
+
+        MessageRegistrationBuildOptions options = new MessageRegistrationBuildOptions
+        {
+            UnityOwner = this,
+            HandlerStartsActive = true,
+            ActivateOnBuild = false,  // We'll activate manually
+            EnableDiagnostics = true,
+            Configure = token =>
+            {
+                _ = token.RegisterUntargeted<LevelLoaded>(OnLevelLoaded);
+            },
+            Lifecycle = new MessageRegistrationLifecycle(
+                onBuild: token => Debug.Log("[Lifecycle] Token built"),
+                onActivate: token => Debug.Log("[Lifecycle] Activated - now receiving messages"),
+                onDeactivate: token => Debug.Log("[Lifecycle] Deactivated - paused"),
+                onDispose: token => Debug.Log("[Lifecycle] Disposed - cleanup complete")
+            )
+        };
+
+        lease = builder.Build(options);
+    }
+
+    private void OnEnable()
+    {
+        // Activate when the component is enabled
+        lease?.Activate();
+    }
+
+    private void OnDisable()
+    {
+        // Deactivate but don't dispose - we might re-enable
+        lease?.Deactivate();
+    }
+
+    private void OnDestroy()
+    {
+        lease?.Dispose();
+    }
+
+    // Action<T> handler signature
+    private void OnLevelLoaded(LevelLoaded message)
+    {
+        Debug.Log($"Level loaded: {message.LevelName}");
+    }
+}
+```
+
+### FixedMessageBusProvider
+
+For scenarios where you always want to use a specific bus instance:
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+// Create a provider that always returns a specific bus
+IMessageBus myBus = new MessageBus();
+IMessageBusProvider provider = new FixedMessageBusProvider(myBus);
+
+// Use with builder
+MessageRegistrationBuilder builder = new MessageRegistrationBuilder(provider);
+
+// Or override per-build
+MessageRegistrationBuildOptions options = new MessageRegistrationBuildOptions
+{
+    MessageBusProvider = provider,
+    Configure = token => { /* ... */ }
+};
+```
+
+---
+
+## See Also
+
+- [Message Bus Providers](message-bus-providers.md) — More on the provider system
+- [Runtime Configuration](runtime-configuration.md) — Dynamic reconfiguration options

package/docs/advanced/registration-builders.md.meta

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

package/{Docs/RuntimeConfiguration.md → docs/advanced/runtime-configuration.md}

@@ -401,7 +401,8 @@ public class DynamicComponentManager
 
 ## See Also
 
-- **[Message Bus Providers](MessageBusProviders.md)** — ScriptableObject-based provider system for design-time configuration
-- **[DI Integration Guides](Integrations/)** — Zenject, VContainer, and Reflex integration patterns
-- **[Testing Guide](Testing.md)** — Comprehensive testing patterns with DxMessaging
-- **[Back to Documentation Hub](Index.md)** — Browse all docs
+- **[Message Bus Providers](message-bus-providers.md)** — ScriptableObject-based provider system for design-time configuration
+- **[Registration Builders](registration-builders.md)** — Fluent API for building message registrations with priority and lifecycle control
+- **[DI Integration Guides](../integrations/index.md)** — Zenject, VContainer, and Reflex integration patterns
+- **[Testing Guide](../guides/testing.md)** — Comprehensive testing patterns with DxMessaging
+- **[Back to Documentation Hub](../getting-started/index.md)** — Browse all docs

package/docs/advanced/runtime-configuration.md.meta

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

package/{Docs/StringMessages.md → docs/advanced/string-messages.md}

@@ -67,5 +67,5 @@ Tips
 
 Related
 
-- [Message Types](MessageTypes.md)
-- [Diagnostics](Diagnostics.md)
+- [Message Types](../concepts/message-types.md)
+- [Diagnostics](../guides/diagnostics.md)

package/docs/advanced/string-messages.md.meta

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

package/docs/advanced.meta

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