com.wallstop-studios.dxmessaging 2.1.7 → 2.1.9

package/docs/guides/patterns.md.meta

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

package/docs/guides/testing.md

@@ -1,243 +0,0 @@
-# Testing with DxMessaging
-
-[<- Back to Index](../getting-started/index.md) | [Patterns](patterns.md) | [Runtime Configuration](../advanced/runtime-configuration.md)
-
----
-
-**You're here because:** You want to write reliable, isolated tests for systems that use DxMessaging.
-
-## Key Testing Principles
-
-1. **Use isolated MessageBus instances** - Avoid global state pollution between tests
-1. **Manage token lifecycles explicitly** - Enable/disable tokens to control when handlers are active
-1. **Clean up spawned objects** - Destroy test GameObjects to prevent registration leaks
-
----
-
-## 1) Isolated MessageBus for Unit Tests
-
-The global `MessageHandler.MessageBus` is shared across your application. For unit tests, create a dedicated `MessageBus` instance to ensure complete isolation.
-
-```csharp
-using DxMessaging.Core;
-using DxMessaging.Core.MessageBus;
-using NUnit.Framework;
-using UnityEngine;
-
-[Test]
-public void IsolatedBusDoesNotAffectGlobalBus()
-{
-    // Create isolated bus and handler
-    MessageBus testBus = new();
-    GameObject testObject = new("TestObject");
-    MessageHandler handler = new(testObject) { active = true };
-    MessageRegistrationToken token = MessageRegistrationToken.Create(handler, testBus);
-    token.Enable();
-
-    int localCount = 0;
-    _ = token.RegisterUntargeted<MyMessage>(_ => localCount++);
-
-    // Emit to isolated bus only
-    MyMessage msg = new();
-    msg.EmitUntargeted(testBus);
-
-    Assert.AreEqual(1, localCount, "Local handler should receive message.");
-
-    // Cleanup
-    token.UnregisterAll();
-    Object.DestroyImmediate(testObject);
-}
-```
-
----
-
-## 2) Test Base Class Pattern
-
-Create a reusable base class for common setup/teardown.
-
-```csharp
-public abstract class MessagingTestBase
-{
-    protected readonly List<GameObject> _spawned = new();
-
-    [TearDown]
-    public virtual void Cleanup()
-    {
-        foreach (GameObject spawned in _spawned)
-            if (spawned != null) Object.Destroy(spawned);
-        _spawned.Clear();
-    }
-
-    [UnitySetUp]
-    public virtual IEnumerator UnitySetup()
-    {
-        IMessageBus bus = MessageHandler.MessageBus;
-        while (bus.RegisteredUntargeted != 0 || bus.RegisteredTargeted != 0)
-            yield return null;
-    }
-
-    protected MessageRegistrationToken GetToken(MessageAwareComponent c) => c.Token;
-}
-```
-
----
-
-## 3) Verifying Message Emission and Handling
-
-Use counters or captured values to verify messages are emitted and handled correctly.
-
-```csharp
-[UnityTest]
-public IEnumerator TargetedMessageReachesCorrectTarget()
-{
-    GameObject target = new("Target", typeof(EmptyMessageAwareComponent));
-    GameObject nonTarget = new("NonTarget", typeof(EmptyMessageAwareComponent));
-    _spawned.Add(target);
-    _spawned.Add(nonTarget);
-
-    MessageRegistrationToken targetToken = GetToken(target.GetComponent<EmptyMessageAwareComponent>());
-    MessageRegistrationToken nonTargetToken = GetToken(nonTarget.GetComponent<EmptyMessageAwareComponent>());
-
-    int targetReceived = 0;
-    int nonTargetReceived = 0;
-
-    _ = targetToken.RegisterGameObjectTargeted<DamageMessage>(target, _ => targetReceived++);
-    _ = nonTargetToken.RegisterGameObjectTargeted<DamageMessage>(nonTarget, _ => nonTargetReceived++);
-
-    DamageMessage msg = new() { amount = 10 };
-    msg.EmitGameObjectTargeted(target);
-
-    Assert.AreEqual(1, targetReceived, "Target should receive message.");
-    Assert.AreEqual(0, nonTargetReceived, "Non-target should NOT receive message.");
-    yield break;
-}
-```
-
----
-
-## 4) Testing Interceptors
-
-Interceptors can cancel or modify messages. Test both scenarios.
-
-```csharp
-[UnityTest]
-public IEnumerator InterceptorCanCancelMessage()
-{
-    GameObject host = new("Host", typeof(EmptyMessageAwareComponent));
-    _spawned.Add(host);
-    MessageRegistrationToken token = GetToken(host.GetComponent<EmptyMessageAwareComponent>());
-
-    int handlerCalled = 0;
-    _ = token.RegisterUntargeted<TestMessage>(_ => handlerCalled++);
-    _ = token.RegisterUntargetedInterceptor((ref TestMessage _) => false); // Cancel
-
-    TestMessage msg = new();
-    msg.EmitUntargeted();
-
-    Assert.AreEqual(0, handlerCalled, "Handler must not run when interceptor cancels.");
-    yield break;
-}
-
-[UnityTest]
-public IEnumerator InterceptorCanModifyMessage()
-{
-    GameObject host = new("Host", typeof(EmptyMessageAwareComponent));
-    _spawned.Add(host);
-    MessageRegistrationToken token = GetToken(host.GetComponent<EmptyMessageAwareComponent>());
-
-    int receivedAmount = 0;
-    _ = token.RegisterUntargeted<DamageMessage>(msg => receivedAmount = msg.amount);
-    _ = token.RegisterUntargetedInterceptor((ref DamageMessage msg) =>
-    {
-        if (msg.amount > 100) msg = new DamageMessage { amount = 100 };
-        return true;
-    });
-
-    DamageMessage msg = new() { amount = 999 };
-    msg.EmitUntargeted();
-
-    Assert.AreEqual(100, receivedAmount, "Interceptor should clamp damage to 100.");
-    yield break;
-}
-```
-
----
-
-## 5) Testing Component Lifecycle
-
-Verify handlers respect Unity's enable/disable lifecycle.
-
-```csharp
-[UnityTest]
-public IEnumerator DisabledComponentDoesNotReceiveMessages()
-{
-    GameObject host = new("Host", typeof(EmptyMessageAwareComponent));
-    _spawned.Add(host);
-    EmptyMessageAwareComponent component = host.GetComponent<EmptyMessageAwareComponent>();
-    MessageRegistrationToken token = GetToken(component);
-
-    int count = 0;
-    _ = token.RegisterUntargeted<TestMessage>(_ => count++);
-
-    TestMessage msg1 = new();
-    msg1.EmitUntargeted();
-    Assert.AreEqual(1, count, "Enabled component should receive message.");
-
-    component.enabled = false;
-    yield return null;
-
-    TestMessage msg2 = new();
-    msg2.EmitUntargeted();
-    Assert.AreEqual(1, count, "Disabled component should NOT receive message.");
-
-    component.enabled = true;
-    yield return null;
-
-    TestMessage msg3 = new();
-    msg3.EmitUntargeted();
-    Assert.AreEqual(2, count, "Re-enabled component should receive message.");
-}
-```
-
----
-
-## 6) Integration Testing
-
-For integration tests, use the global bus with proper cleanup. Create GameObjects with components, emit messages, and verify system-wide behavior across multiple components.
-
----
-
-## Best Practices
-
-| Practice                                    | Why                                                           |
-| ------------------------------------------- | ------------------------------------------------------------- |
-| Use isolated `MessageBus` for unit tests    | Prevents test pollution and flakiness                         |
-| Track spawned objects in a list             | Ensures cleanup even if test fails                            |
-| Use `yield return null` after state changes | Allows Unity lifecycle methods to execute                     |
-| Test both positive and negative cases       | Verify messages reach correct targets AND miss incorrect ones |
-| Use expressive assertion messages           | Makes test failures easier to diagnose                        |
-
----
-
-## Quick Reference: Test Message Setup
-
-```csharp
-// Test messages
-[DxUntargetedMessage]
-public partial struct TestMessage { }
-
-[DxTargetedMessage]
-[DxAutoConstructor]
-public readonly partial struct DamageMessage { public readonly int amount; }
-
-// Minimal test component - registers no handlers by default
-public sealed class EmptyMessageAwareComponent : MessageAwareComponent { }
-```
-
----
-
-## See Also
-
-- **[Patterns](patterns.md)** - Pattern #6 (Local Bus Islands) and #12 (Testing)
-- **[Runtime Configuration](../advanced/runtime-configuration.md)** - MessageBus configuration options
-- **[Back to Documentation Hub](../getting-started/index.md)** - Browse all docs

package/docs/guides/testing.md.meta

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

package/docs/guides/unity-integration.md

@@ -1,139 +0,0 @@
-# Unity Integration
-
-Unity‑centric helpers make registration lifecycles explicit and safe.
-
-## MessagingComponent
-
-- Attach to any GameObject that will send or receive messages.
-- Creates a per-owner `MessageHandler` and offers `Create(this)` to get a `MessageRegistrationToken`.
-- Call `Configure(IMessageBus, MessageBusRebindMode)` before `Create` if you want the component to use a custom bus (e.g., one resolved from a DI container). Passing `MessageBusRebindMode.RebindActive` migrates current registrations; `PreserveRegistrations` defers the swap until the next enable.
-- Optional: set `emitMessagesWhenDisabled` if you need to emit while disabled.
-
-## MessageAwareComponent
-
-- Derive for a batteries‑included pattern; it manages a token for you.
-- Override `RegisterMessageHandlers()` to stage registrations.
-- The token is enabled/disabled with the component’s enable state.
-- Call `ConfigureMessageBus(IMessageBus, MessageBusRebindMode)` before `base.Awake()` (or shortly after via a DI bootstrapper) to ensure the token is created against your container-provided bus.
-
-```csharp
-using DxMessaging.Unity;
-using DxMessaging.Core.Messages;
-
-public sealed class HealthComponent : MessageAwareComponent
-{
-    protected override void RegisterMessageHandlers()
-    {
-        base.RegisterMessageHandlers();
-        _ = Token.RegisterComponentTargeted<TookDamage>(this, OnTookDamage);
-        _ = Token.RegisterUntargeted<WorldRegenerated>(OnWorldRegenerated);
-    }
-
-    private void OnTookDamage(ref TookDamage m) => Apply(m.amount);
-    private void OnWorldRegenerated(ref WorldRegenerated m) => Reset();
-}
-```
-
-## Do's
-
-- Use `MessageAwareComponent` when possible to avoid boilerplate.
-- Override `RegisterMessageHandlers()` and bind to named methods.
-- Keep handlers small and fast; offload heavy work.
-
-## Don'ts
-
-- Don’t register in Update; register once and enable/disable with component state.
-- Don’t forget to call `base.RegisterMessageHandlers()` if your subclass relies on base registrations.
-
-## Important: Inheritance and base calls
-
-- `MessageAwareComponent` uses many virtual methods (e.g., `Awake`, `OnEnable`, `OnDisable`, `RegisterMessageHandlers`).
-- **CRITICAL**: If you override any of these, you MUST call the base method: `base.Awake()`, `base.OnEnable()`, `base.OnDisable()`, `base.RegisterMessageHandlers()`.
-- **Always call `base.RegisterMessageHandlers()` first** in your override—this ensures parent class registrations happen before yours.
-- Skipping base calls can break core setup (token creation/enable) and default string‑message registrations.
-- If you need to opt out of string demos, prefer overriding `RegisterForStringMessages => false` rather than removing the base call.
-- **Don't hide Unity methods** with `new` (e.g., `new void OnEnable()`); always `override` and call `base.*`.
-
-## Registration timing
-
-- **Prefer `Awake()` for registration** rather than `Start()`.
-- `MessageAwareComponent` automatically calls `RegisterMessageHandlers()` in `Awake()`.
-- Early registration in `Awake()` ensures handlers are ready before other components' `Start()` methods run.
-- If you need custom setup before registration, override `Awake()`, do your setup, then call `base.Awake()`.
-
-## Manual token management
-
-```csharp
-using DxMessaging.Unity;
-using DxMessaging.Core;
-using DxMessaging.Core.Messages;
-
-[RequireComponent(typeof(MessagingComponent))]
-public sealed class InventoryUI : UnityEngine.MonoBehaviour
-{
-    private MessagingComponent _messaging;
-    private MessageRegistrationToken _token;
-
-    private void Awake()
-    {
-        _messaging = GetComponent<MessagingComponent>();
-        _token = _messaging.Create(this);
-        _ = _token.RegisterUntargeted<WorldRegenerated>(OnWorld);
-        _ = _token.RegisterComponentTargeted<TookDamage>(this, OnDamage);
-    }
-
-    private void OnEnable() => _token.Enable();
-    private void OnDisable() => _token.Disable();
-
-    private void OnWorld(ref WorldRegenerated m) { /* update UI */ }
-    private void OnDamage(ref TookDamage m) { /* flash damage */ }
-}
-```
-
-## Manual enable/disable (advanced)
-
-```csharp
-public sealed class AlwaysListening : MessageAwareComponent
-{
-    protected override bool MessageRegistrationTiedToEnableStatus => false; // keep token enabled
-
-    protected override void RegisterMessageHandlers()
-    {
-        base.RegisterMessageHandlers();
-        _ = Token.RegisterUntargeted<MyEvent>(OnEvent);
-        Token.Enable(); // explicitly enable once
-    }
-
-    private void OnEvent(ref MyEvent m) { /* ... */ }
-}
-```
-
-## String message demos (opt‑out)
-
-```csharp
-public sealed class NoStringDemos : MessageAwareComponent
-{
-    protected override bool RegisterForStringMessages => false;
-
-    protected override void RegisterMessageHandlers()
-    {
-        // only your registrations
-    }
-}
-```
-
-## ReflexiveMessage (bridging legacy SendMessage)
-
-```csharp
-using DxMessaging.Core;
-using DxMessaging.Core.Messages;
-
-var msg = new ReflexiveMessage("OnHit", ReflexiveSendMode.Upwards, 10);
-msg.EmitGameObjectTargeted(gameObject);
-```
-
-Related
-
-- [Quick Start](../getting-started/quick-start.md)
-- [Patterns](patterns.md)
-- [Diagnostics (Inspector)](diagnostics.md)

package/docs/guides/unity-integration.md.meta

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

package/docs/guides.meta

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

package/docs/hooks.py

@@ -1,177 +0,0 @@
-"""
-MkDocs hooks for transforming source code links.
-
-This module provides a hook that transforms markdown links pointing to source files
-into full GitHub URLs during the MkDocs build process. This approach keeps markdown
-files readable in VSCode preview while generating correct links for GitHub Pages.
-
-Transformations:
-- Links starting with Runtime/, Tests/, Editor/, or Samples~/ are transformed
-- File links use /blob/master/
-- Directory links use /tree/master/
-- Spaces in paths are URL-encoded
-- Links inside code blocks (fenced or inline) are NOT transformed
-"""
-
-import re
-from urllib.parse import quote
-
-# GitHub repository configuration
-REPO_URL = "https://github.com/wallstop/DxMessaging"
-BRANCH = "master"
-
-# Patterns that indicate source file references (not doc-relative links)
-SOURCE_PREFIXES = ("Runtime/", "Tests/", "Editor/", "Samples~/")
-
-# Regex to match markdown links: [text](url)
-# Captures: group 1 = display text, group 2 = URL
-MARKDOWN_LINK_PATTERN = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
-
-# Regex to match fenced code blocks (``` or ~~~ with optional language specifier)
-# Regex flags used:
-#   - DOTALL (s): Makes . match newline characters, allowing pattern to span multiple lines
-# The re.sub() method with this pattern finds all occurrences (equivalent to 'g' global flag)
-# Pattern is case-sensitive (no IGNORECASE flag needed - backticks are symbols)
-# No MULTILINE flag needed - we don't use ^ or $ anchors
-FENCED_CODE_BLOCK_PATTERN = re.compile(r"(```|~~~)[^\n]*\n.*?\1", re.DOTALL)
-
-# Regex to match inline code (handles multiple backticks like `` or ```)
-# Matches backtick(s), then content that doesn't contain that same sequence, then same backticks
-# Regex flags used:
-#   - DOTALL (s): Makes . match newline characters, allowing inline code to span lines
-# The re.sub() method with this pattern finds all occurrences (equivalent to 'g' global flag)
-# Pattern is case-sensitive (no IGNORECASE flag needed - backticks are symbols)
-# No MULTILINE flag needed - we don't use ^ or $ anchors
-INLINE_CODE_PATTERN = re.compile(r"(`+)(?!`)(.*?)(?<!`)\1(?!`)", re.DOTALL)
-
-
-def is_source_link(url):
-    """
-    Check if a URL is a source file reference that should be transformed.
-
-    Args:
-        url: The URL from a markdown link.
-
-    Returns:
-        True if the URL should be transformed to a GitHub URL.
-    """
-    return url.startswith(SOURCE_PREFIXES)
-
-
-def is_directory_link(path):
-    """
-    Determine if a path points to a directory rather than a file.
-
-    Args:
-        path: The path to check.
-
-    Returns:
-        True if the path appears to be a directory.
-    """
-    # Paths ending with / are directories
-    if path.endswith("/"):
-        return True
-
-    # Paths without a file extension in the last component are likely directories
-    # (but be careful with extensionless files)
-    last_component = path.rstrip("/").split("/")[-1]
-
-    # If no dot in the last component, it's likely a directory
-    # Exception: files like Makefile, Dockerfile, etc. but those are rare in this codebase
-    return "." not in last_component
-
-
-def transform_to_github_url(path):
-    """
-    Transform a source path to a full GitHub URL.
-
-    Args:
-        path: The source path (e.g., 'Runtime/Core/MessageBus.cs').
-
-    Returns:
-        The full GitHub URL for the path.
-    """
-    # Determine if it's a file or directory
-    link_type = "tree" if is_directory_link(path) else "blob"
-
-    # URL-encode spaces and other special characters in the path
-    # We need to encode each path component separately to preserve slashes
-    path_components = path.split("/")
-    encoded_components = [quote(component, safe="") for component in path_components]
-    encoded_path = "/".join(encoded_components)
-
-    return f"{REPO_URL}/{link_type}/{BRANCH}/{encoded_path}"
-
-
-def transform_link(match):
-    """
-    Transform a single markdown link match.
-
-    Args:
-        match: A regex match object with groups for display text and URL.
-
-    Returns:
-        The transformed markdown link, or the original if no transformation needed.
-    """
-    display_text = match.group(1)
-    url = match.group(2)
-
-    # Only transform source file links
-    if not is_source_link(url):
-        return match.group(0)
-
-    # Transform to GitHub URL
-    github_url = transform_to_github_url(url)
-    return f"[{display_text}]({github_url})"
-
-
-def on_page_markdown(markdown, page, config, files):
-    """
-    MkDocs hook that runs on each page during build.
-
-    Transforms markdown links pointing to source files into full GitHub URLs.
-    Code blocks (fenced and inline) are protected from transformation.
-
-    Args:
-        markdown: The markdown content of the page.
-        page: The MkDocs page object.
-        config: The MkDocs configuration.
-        files: The MkDocs files collection.
-
-    Returns:
-        The transformed markdown content.
-    """
-    # Store code blocks to protect them from transformation
-    fenced_blocks = []
-    inline_codes = []
-
-    def mask_fenced_block(match):
-        """Replace fenced code block with placeholder."""
-        placeholder = f"__FENCED_CODE_BLOCK_{len(fenced_blocks)}__"
-        fenced_blocks.append(match.group(0))
-        return placeholder
-
-    def mask_inline_code(match):
-        """Replace inline code with placeholder."""
-        placeholder = f"__INLINE_CODE_{len(inline_codes)}__"
-        inline_codes.append(match.group(0))
-        return placeholder
-
-    # Step 1: Mask fenced code blocks first (they may contain inline code syntax)
-    content = FENCED_CODE_BLOCK_PATTERN.sub(mask_fenced_block, markdown)
-
-    # Step 2: Mask inline code
-    content = INLINE_CODE_PATTERN.sub(mask_inline_code, content)
-
-    # Step 3: Transform all markdown links in the remaining content
-    content = MARKDOWN_LINK_PATTERN.sub(transform_link, content)
-
-    # Step 4: Restore inline code (in reverse order of masking)
-    for i, inline_code in enumerate(inline_codes):
-        content = content.replace(f"__INLINE_CODE_{i}__", inline_code)
-
-    # Step 5: Restore fenced code blocks
-    for i, fenced_block in enumerate(fenced_blocks):
-        content = content.replace(f"__FENCED_CODE_BLOCK_{i}__", fenced_block)
-
-    return content

package/docs/hooks.py.meta

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