com.wallstop-studios.dxmessaging 2.1.3 → 2.1.5

package/docs/index.md

@@ -0,0 +1,61 @@
+---
+title: Home
+description: High-performance type-safe messaging library for Unity
+---
+
+# DxMessaging Documentation
+
+**DxMessaging** is a high-performance, type-safe messaging library for Unity that provides a clean, decoupled communication pattern between game components.
+
+[Get Started](getting-started/index.md){ .md-button .md-button--primary }
+[View on GitHub](https://github.com/wallstop/DxMessaging){ .md-button }
+
+## Why DxMessaging?
+
+- :zap: **High Performance** — Zero-allocation message dispatch with pooled handlers
+- :shield: **Type-Safe** — Compile-time message type checking prevents runtime errors
+- :package: **Decoupled Architecture** — Components communicate without direct references
+- :dart: **Flexible Targeting** — Untargeted, Targeted, and Broadcast message patterns
+- :wrench: **Unity-Native** — Built specifically for Unity with MonoBehaviour integration
+
+## Quick Links
+
+- **[Visual Guide](getting-started/visual-guide.md)** — Beginner-friendly introduction with diagrams
+- **[Quick Start](getting-started/quick-start.md)** — Your first message in 5 minutes
+- **[Message Types](concepts/message-types.md)** — Untargeted, Targeted, Broadcast patterns
+- **[API Reference](reference/reference.md)** — Complete API documentation
+
+## Installation
+
+### Via OpenUPM (Recommended)
+
+```bash
+openupm add com.wallstop-studios.dxmessaging
+```
+
+#### Or via Git URL
+
+```text
+https://github.com/wallstop/DxMessaging.git
+```
+
+See the [Install Guide](getting-started/install.md) for all options including NPM scoped registries and local tarballs.
+
+## Quick Example
+
+```csharp
+// Define a message
+public readonly struct DamageMessage : IUntargetedMessage
+{
+    public readonly int amount;
+    public DamageMessage(int amount) => this.amount = amount;
+}
+
+// Subscribe and handle (using a MessageRegistrationToken)
+_ = Token.RegisterUntargeted<DamageMessage>(msg =>
+    Debug.Log($"Received {msg.amount} damage!"));
+
+// Emit the message
+DamageMessage damage = new DamageMessage(25);
+damage.EmitUntargeted();
+```

package/docs/integrations/index.md

@@ -0,0 +1,66 @@
+# DI Framework Integrations
+
+DxMessaging integrates seamlessly with popular Unity dependency injection (DI) frameworks. This section covers how to combine DxMessaging's reactive event system with constructor-based dependency injection for a powerful, scalable architecture.
+
+## Why Combine DI + Messaging?
+
+Use the best of both worlds:
+
+- **Constructor Injection** — for service dependencies (repositories, managers, configuration)
+- **Messaging** — for reactive events (damage taken, item collected, game state changes)
+
+This combination provides:
+
+- Explicit dependencies with testable constructors
+- Loose coupling between systems via events
+- Scoped message buses for scene isolation
+- Clean separation of concerns
+
+## Supported Frameworks
+
+### [VContainer](vcontainer.md)
+
+Fast, lightweight DI with minimal overhead. Features scoped lifetimes for per-scene message buses.
+
+```csharp
+builder.Register<IMessageBus>(Lifetime.Scoped)
+    .AsImplementedInterfaces()
+    .AsSelf();
+```
+
+### [Zenject](zenject.md)
+
+Feature-rich DI with extensive Unity integration. Supports complex binding scenarios and sub-containers.
+
+```csharp
+Container.Bind<IMessageBus>()
+    .FromInstance(MessageHandler.MessageBus)
+    .AsSingle();
+```
+
+### [Reflex](reflex.md)
+
+Modern, reflection-free DI designed for performance. Zero-allocation resolution with AOT support.
+
+```csharp
+Container.Singleton<IMessageBus>(MessageHandler.MessageBus);
+```
+
+## Choosing a Framework
+
+| Framework      | Best For                                     | Performance    |
+| -------------- | -------------------------------------------- | -------------- |
+| **VContainer** | Most projects, additive scenes               | ⭐⭐⭐ Fast    |
+| **Zenject**    | Complex projects, existing Zenject codebases | ⭐⭐ Good      |
+| **Reflex**     | Performance-critical, AOT platforms          | ⭐⭐⭐ Fastest |
+
+## Common Patterns
+
+All frameworks support the same core patterns:
+
+1. **Global Bus** — Share `MessageHandler.MessageBus` across all systems
+1. **Scoped Bus** — Create per-scene buses for isolation
+1. **Builder Injection** — Inject `IMessageRegistrationBuilder` for flexible handler registration
+1. **Testable Design** — Mock `IMessageBus` in unit tests
+
+See each framework's guide for detailed examples and best practices.

package/docs/integrations/index.md.meta

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

package/{Docs/Integrations/Reflex.md → docs/integrations/reflex.md}

@@ -1,19 +1,19 @@
 # DxMessaging + Reflex
 
-[← Back to Integrations Overview](../README.md#-integrations)
+[← Back to Integrations Overview](index.md)
 
 ---
 
 ## Overview
 
-**Reflex** is a minimal, lightweight dependency injection framework for Unity with blazing-fast performance. DxMessaging integrates seamlessly with Reflex, allowing you to:
+**Reflex** is a minimal, lightweight dependency injection framework for Unity. DxMessaging integrates with Reflex, allowing you to:
 
 - **Inject `IMessageBus`** in any class with minimal overhead
 - **Use DI for construction** + DxMessaging for events (best of both worlds)
-- **Minimal API surface** — easy to learn, easy to use
-- **High performance** — Reflex + DxMessaging = minimal allocations
+- **Minimal API surface** — small number of concepts to understand
+- **Compatible** — Reflex and DxMessaging can be used together
 
-**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected). Reflex's minimal API makes integration simple and straightforward.
+**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected), combining both approaches.
 
 ---
 
@@ -28,25 +28,42 @@
 
 ```csharp
 using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity.Integrations.Reflex;
 using Reflex.Core;
 
-public sealed class DxMessagingInstaller : Installer
+// Option A: Use IInstaller interface (recommended for explicit registration)
+public sealed class DxMessagingInstaller : IInstaller
 {
-    public override void InstallBindings(ContainerDescriptor descriptor)
+    public void InstallBindings(ContainerBuilder containerBuilder)
     {
-        // Bind MessageBus as both concrete and interface
-        descriptor.AddSingleton(typeof(MessageBus), typeof(MessageBus));
-        descriptor.AddSingleton(typeof(IMessageBus), c => c.Resolve<MessageBus>());
+        // Bind MessageBus as singleton implementing IMessageBus
+        containerBuilder.AddSingleton(
+            typeof(MessageBus),
+            typeof(MessageBus),
+            typeof(IMessageBus)
+        );
 
         // Optional: Enable automatic IMessageRegistrationBuilder binding
-        // Requires REFLEX_PRESENT define (auto-added by DxMessaging when Reflex detected)
+        // Install the DxMessagingRegistrationInstaller to get IMessageRegistrationBuilder
         #if REFLEX_PRESENT
-        descriptor.AddMessageRegistrationBuilder();
+        new DxMessagingRegistrationInstaller().InstallBindings(containerBuilder);
         #endif
     }
 }
+
+// Option B: Extend Installer base class (common pattern)
+public sealed class DxMessagingInstallerAlt : Installer
+{
+    protected override void InstallBindings()
+    {
+        Container.Bind<MessageBus>().AsSingleton();
+        Container.Bind<IMessageBus>().FromContainer<MessageBus>();
+    }
+}
 ```
 
+**Note:** You must import the `DxMessaging.Unity.Integrations.Reflex` namespace to access `DxMessagingRegistrationInstaller`.
+
 #### Add to your scene
 
 1. Create a `SceneContext` or `ProjectContext` in your scene
@@ -112,9 +129,17 @@ public sealed class DamageService
 #### Register the service in your installer
 
 ```csharp
-public override void InstallBindings(ContainerDescriptor descriptor)
+// Using IInstaller interface
+public void InstallBindings(ContainerBuilder containerBuilder)
+{
+    containerBuilder.AddSingleton(typeof(DamageService), typeof(DamageService));
+    // Call Initialize() from a bootstrap MonoBehaviour
+}
+
+// Or using Installer base class
+protected override void InstallBindings()
 {
-    descriptor.AddSingleton<DamageService>();
+    Container.Bind<DamageService>().AsSingleton();
     // Call Initialize() from a bootstrap MonoBehaviour
 }
 ```
@@ -264,7 +289,7 @@ public class DamageServiceTests
 - [ ] Install DxMessaging and Reflex
 - [ ] Create `DxMessagingInstaller` with bus bindings
 - [ ] Add installer to your `SceneContext` or `ProjectContext`
-- [ ] Add `#if REFLEX_PRESENT` check and call `descriptor.AddMessageRegistrationBuilder()`
+- [ ] Import `DxMessaging.Unity.Integrations.Reflex` and install `DxMessagingRegistrationInstaller` for `IMessageRegistrationBuilder` support
 
 ### Integration
 
@@ -287,6 +312,6 @@ public class DamageServiceTests
 
 ## Next Steps
 
-- **[Zenject Integration](Zenject.md)** — Full-featured DI with extensive Unity support
-- **[VContainer Integration](VContainer.md)** — Lightweight alternative with scoped lifetimes
-- **[Back to Documentation Hub](../Index.md)** — Browse all docs
+- **[Zenject Integration](zenject.md)** — Full-featured DI with extensive Unity support
+- **[VContainer Integration](vcontainer.md)** — Lightweight alternative with scoped lifetimes
+- **[Back to Documentation Hub](../getting-started/index.md)** — Browse all docs

package/{Docs/Integrations/VContainer.md → docs/integrations/vcontainer.md}

@@ -1,19 +1,19 @@
 # DxMessaging + VContainer
 
-[← Back to Integrations Overview](../README.md#-integrations)
+[← Back to Integrations Overview](index.md)
 
 ---
 
 ## Overview
 
-**VContainer** is a fast, lightweight dependency injection framework for Unity with minimal overhead. DxMessaging integrates seamlessly with VContainer, allowing you to:
+**VContainer** is a fast, lightweight dependency injection framework for Unity with minimal overhead. DxMessaging integrates with VContainer, allowing you to:
 
 - **Inject `IMessageBus`** in any class with deterministic lifetimes
 - **Create per-scope buses** for scene isolation (perfect for additive scenes)
 - **Use DI for construction** + DxMessaging for events (best of both worlds)
-- **Minimal performance overhead** — VContainer + DxMessaging = blazing fast
+- **Compatible** — VContainer and DxMessaging can be used together
 
-**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected). VContainer's scoped lifetimes make it perfect for per-scene message buses.
+**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected), combining both approaches. VContainer's scoped lifetimes support per-scene message buses.
 
 ---
 
@@ -28,6 +28,7 @@
 
 ```csharp
 using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity.Integrations.VContainer; // Required for RegisterMessageRegistrationBuilder()
 using UnityEngine;
 using VContainer;
 using VContainer.Unity;
@@ -48,6 +49,8 @@ public sealed class MessagingLifetimeScope : LifetimeScope
 }
 ```
 
+**Note:** You must import the `DxMessaging.Unity.Integrations.VContainer` namespace to access the `RegisterMessageRegistrationBuilder()` extension method.
+
 #### Add to your scene
 
 1. Create an empty GameObject in your scene
@@ -116,6 +119,10 @@ public sealed class PlayerService : IStartable, IDisposable
 #### Register the service in your scope
 
 ```csharp
+using DxMessaging.Unity.Integrations.VContainer; // Required for extension method
+
+// ...
+
 protected override void Configure(IContainerBuilder builder)
 {
     builder.Register<MessageBus>(Lifetime.Singleton).As<IMessageBus>();
@@ -193,10 +200,11 @@ public sealed class GameInitializer : IStartable
 
 ## Advanced: Scene Scopes and Isolation
 
-VContainer's scoped lifetimes make it perfect for per-scene message buses. This is useful for additive scenes or isolated gameplay features:
+VContainer's scoped lifetimes support per-scene message buses. This is useful for additive scenes or isolated gameplay features:
 
 ```csharp
 using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity.Integrations.VContainer; // Required for extension method
 using VContainer;
 using VContainer.Unity;
 
@@ -227,7 +235,7 @@ public sealed class LevelLoader
 
 - Each scene gets its own isolated message bus
 - Messages don't leak between scenes
-- Perfect for multiplayer lobbies, mini-games, or feature-scoped events
+- Suitable for multiplayer lobbies, mini-games, or feature-scoped events
 
 ---
 
@@ -300,6 +308,7 @@ public IEnumerator PlayMode_MessageBusIsolation()
 - [ ] Install DxMessaging and VContainer
 - [ ] Create `MessagingLifetimeScope` with `builder.Register<MessageBus>().As<IMessageBus>()`
 - [ ] Add scope to your scene as a GameObject component
+- [ ] Import `DxMessaging.Unity.Integrations.VContainer` namespace for extension methods
 - [ ] Add `#if VCONTAINER_PRESENT` check and call `builder.RegisterMessageRegistrationBuilder()`
 
 ### Integration
@@ -319,6 +328,6 @@ public IEnumerator PlayMode_MessageBusIsolation()
 
 ## Next Steps
 
-- **[Zenject Integration](Zenject.md)** — Full-featured DI with extensive Unity support
-- **[Reflex Integration](Reflex.md)** — Minimal DI framework
-- **[Back to Documentation Hub](../Index.md)** — Browse all docs
+- **[Zenject Integration](zenject.md)** — Full-featured DI with extensive Unity support
+- **[Reflex Integration](reflex.md)** — Minimal DI framework
+- **[Back to Documentation Hub](../getting-started/index.md)** — Browse all docs

package/{Docs/Integrations/Zenject.md → docs/integrations/zenject.md}

@@ -1,19 +1,19 @@
 # DxMessaging + Zenject
 
-[← Back to Integrations Overview](../README.md#-integrations)
+[← Back to Integrations Overview](index.md)
 
 ---
 
 ## Overview
 
-**Zenject** (also known as Extenject) is a powerful dependency injection framework for Unity. DxMessaging integrates seamlessly with Zenject, allowing you to:
+**Zenject** (also known as Extenject) is a powerful dependency injection framework for Unity. DxMessaging integrates with Zenject, allowing you to:
 
 - **Inject `IMessageBus`** as a singleton dependency in any class
 - **Use DI for construction** + DxMessaging for events (best of both worlds)
 - **Create per-scope message buses** for scene or gameplay isolation
 - **Bridge to SignalBus** for gradual migration from Zenject Signals
 
-**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected). This keeps your architecture clean and testable.
+**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected), combining both approaches.
 
 ---
 
@@ -328,6 +328,6 @@ public class GameInitializerTests : ZenjectUnitTestFixture
 
 ## Next Steps
 
-- **[VContainer Integration](VContainer.md)** — Lightweight alternative to Zenject
-- **[Reflex Integration](Reflex.md)** — Minimal DI framework
-- **[Back to Documentation Hub](../Index.md)** — Browse all docs
+- **[VContainer Integration](vcontainer.md)** — Lightweight alternative to Zenject
+- **[Reflex Integration](reflex.md)** — Minimal DI framework
+- **[Back to Documentation Hub](../getting-started/index.md)** — Browse all docs

package/docs/javascripts/csharp-highlight.js

@@ -0,0 +1,246 @@
+/**
+ * C# Semantic Syntax Highlighting Enhancement
+ *
+ * Pygments' C# lexer classifies many tokens as generic "Name" (.n) tokens,
+ * making it impossible to differentiate types from methods from variables
+ * with CSS alone. This script post-processes code blocks to add semantic
+ * classes based on contextual patterns:
+ *
+ * - .n-type: Type names (PascalCase identifiers, often followed by < or at line start)
+ * - .n-method: Method names (identifiers followed by < and ( or just ()
+ * - .n-param: Parameter names (after type in parameter list, before = or , or ))
+ * - .n-var: Variable names (other identifiers)
+ */
+(function () {
+  "use strict";
+
+  /** Maximum iterations for look-ahead loops to prevent hangs */
+  var MAX_LOOKAHEAD = 50;
+
+  /**
+   * Check if a string is PascalCase (starts with uppercase)
+   */
+  function isPascalCase(text) {
+    return /^[A-Z][a-zA-Z0-9]*$/.test(text);
+  }
+
+  /**
+   * Check if a string is camelCase (starts with lowercase)
+   */
+  function isCamelCase(text) {
+    return /^[a-z][a-zA-Z0-9]*$/.test(text);
+  }
+
+  /**
+   * Safely get classList as array, handling elements without classList
+   */
+  function getClassList(element) {
+    if (element && element.classList) {
+      return Array.from(element.classList);
+    }
+    return [];
+  }
+
+  /**
+   * Get the next sibling element (skipping whitespace spans)
+   */
+  function getNextNonWhitespace(element) {
+    var next = element.nextElementSibling;
+    while (next && next.classList && next.classList.contains("w")) {
+      next = next.nextElementSibling;
+    }
+    return next;
+  }
+
+  /**
+   * Get the previous sibling element (skipping whitespace spans)
+   */
+  function getPrevNonWhitespace(element) {
+    var prev = element.previousElementSibling;
+    while (prev && prev.classList && prev.classList.contains("w")) {
+      prev = prev.previousElementSibling;
+    }
+    return prev;
+  }
+
+  /**
+   * Process a single .n token and determine its semantic type
+   */
+  function classifyNameToken(span) {
+    var text = span.textContent.trim();
+    if (!text) return null;
+
+    var next = getNextNonWhitespace(span);
+    var prev = getPrevNonWhitespace(span);
+    var nextText = next ? next.textContent.trim() : "";
+    var prevText = prev ? prev.textContent.trim() : "";
+    var nextClass = getClassList(next);
+    var prevClass = getClassList(prev);
+
+    // Method call: followed by (
+    // Pattern: name(
+    if (nextClass.includes("p") && nextText === "(") {
+      return "n-method";
+    }
+
+    // Generic method or type: followed by < (operator)
+    // Need to check if it's eventually followed by ( for method
+    if (nextClass.includes("o") && nextText.startsWith("<")) {
+      // Look ahead to see if there's a ( after the generic parameters
+      var lookahead = next;
+      var depth = 0;
+      var iterations = 0;
+
+      while (lookahead && iterations < MAX_LOOKAHEAD) {
+        iterations++;
+        var t = lookahead.textContent.trim();
+
+        // Count generic bracket depth
+        if (t === "<") depth++;
+        if (t === ">") depth--;
+
+        // Found ( after closing all generics - it's a method
+        if (depth === 0 && t === "(") {
+          return "n-method";
+        }
+
+        // Went negative or found definitive end
+        if (depth < 0) break;
+
+        lookahead = lookahead.nextElementSibling;
+
+        // Stop at comments or end of line
+        var lookaheadClass = getClassList(lookahead);
+        if (lookaheadClass.includes("c1") || lookaheadClass.includes("cm")) {
+          break;
+        }
+      }
+      // If no ( found, it's likely a type
+      return "n-type";
+    }
+
+    // Parameter: after another .n token (the type) and followed by , or ) or =
+    if (
+      (nextText === "," || nextText === ")" || nextText === "=") &&
+      prevClass.includes("n") &&
+      isCamelCase(text)
+    ) {
+      return "n-param";
+    }
+
+    // Parameter: after > (closing generic) and followed by , or ) or =
+    if (
+      (nextText === "," || nextText === ")" || nextText === "=") &&
+      prevText === ">" &&
+      isCamelCase(text)
+    ) {
+      return "n-param";
+    }
+
+    // Parameter: after ] (array type like int[]) and followed by , or ) or =
+    if (
+      (nextText === "," || nextText === ")" || nextText === "=") &&
+      prevText === "]" &&
+      isCamelCase(text)
+    ) {
+      return "n-param";
+    }
+
+    // Parameter: after ? (nullable type like int?) and followed by , or ) or =
+    if (
+      (nextText === "," || nextText === ")" || nextText === "=") &&
+      prevText === "?" &&
+      isCamelCase(text)
+    ) {
+      return "n-param";
+    }
+
+    // Parameter: after out/ref/in keywords
+    if (
+      prevClass.includes("k") &&
+      (prevText === "out" || prevText === "ref" || prevText === "in") &&
+      isCamelCase(text)
+    ) {
+      return "n-param";
+    }
+
+    // Type: PascalCase identifiers in various contexts
+    if (isPascalCase(text)) {
+      // After a keyword, it's likely a type (e.g., "class Foo", "new Bar")
+      if (prevClass.includes("k") || prevClass.includes("kt")) {
+        return "n-type";
+      }
+
+      // At the start of a code line (no previous sibling)
+      if (!prev) {
+        return "n-type";
+      }
+
+      // After punctuation like ( or < or , - likely a type in parameter list
+      if (prevText === "(" || prevText === "<" || prevText === ",") {
+        return "n-type";
+      }
+
+      // After . (dot) - member access, could be nested type or static member
+      if (prevText === ".") {
+        // If followed by < or ( it would have been caught above
+        // Otherwise assume it's a type or type-like member
+        return "n-type";
+      }
+
+      // Default: PascalCase is likely a type
+      return "n-type";
+    }
+
+    // Variable/field: camelCase identifiers not caught above
+    if (isCamelCase(text)) {
+      return "n-var";
+    }
+
+    // Default: leave as-is (don't add any class)
+    return null;
+  }
+
+  /**
+   * Process all C# code blocks on the page
+   */
+  function enhanceCSharpHighlighting() {
+    // Find all C# code blocks - handle both class orderings
+    // .language-csharp.highlight is the actual structure from Pygments
+    var codeBlocks = document.querySelectorAll(
+      ".language-csharp.highlight code, .highlight.language-csharp code"
+    );
+
+    codeBlocks.forEach(function (codeBlock) {
+      // Skip if already processed (idempotency)
+      if (codeBlock.hasAttribute("data-semantic-enhanced")) {
+        return;
+      }
+      codeBlock.setAttribute("data-semantic-enhanced", "true");
+
+      // Find all .n spans (generic Name tokens)
+      var nameSpans = codeBlock.querySelectorAll("span.n");
+
+      nameSpans.forEach(function (span) {
+        var semanticClass = classifyNameToken(span);
+        if (semanticClass) {
+          span.classList.add(semanticClass);
+        }
+      });
+    });
+  }
+
+  // Run when DOM is ready
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", enhanceCSharpHighlighting);
+  } else {
+    enhanceCSharpHighlighting();
+  }
+
+  // Also run on navigation (for single-page app behavior in Material)
+  if (typeof document$ !== "undefined") {
+    document$.subscribe(function () {
+      enhanceCSharpHighlighting();
+    });
+  }
+})();

package/docs/javascripts/csharp-highlight.js.meta

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