com.wallstop-studios.dxmessaging 2.1.3 → 2.1.5

package/docs/javascripts/mermaid-config.js

@@ -0,0 +1,347 @@
+/**
+ * Mermaid theme-aware configuration for MkDocs Material
+ *
+ * This script:
+ * 1. Detects the current MkDocs Material theme (light vs slate/dark)
+ * 2. Initializes Mermaid with appropriate theme variables
+ * 3. Listens for theme changes and re-renders diagrams
+ * 4. Uses semantic class-based styling that works with both themes
+ *
+ * For GitHub/VSCode markdown preview fallback, diagrams include:
+ * %%{init: {'theme': 'neutral'}}%%
+ */
+
+(function () {
+  "use strict";
+
+  // Color palettes for light and dark themes
+  // These provide semantic colors for diagram elements
+  const lightTheme = {
+    // Base colors
+    primaryColor: "#e3f2fd", // Light blue background
+    primaryTextColor: "#1565c0", // Dark blue text
+    primaryBorderColor: "#1976d2", // Blue border
+    // Secondary (success)
+    secondaryColor: "#e8f5e9", // Light green background
+    secondaryTextColor: "#2e7d32", // Dark green text
+    secondaryBorderColor: "#388e3c", // Green border
+    // Tertiary (warning/accent)
+    tertiaryColor: "#fff3e0", // Light orange background
+    tertiaryTextColor: "#c43e00", // Dark orange text (contrast ratio ~5.5:1)
+    tertiaryBorderColor: "#f57c00", // Orange border
+    // Quaternary (danger/red)
+    quaternaryColor: "#ffebee", // Light red background
+    quaternaryTextColor: "#b71c1c", // Dark red text
+    quaternaryBorderColor: "#d32f2f", // Red border
+    // Quinary (accent/purple) - fifth semantic color
+    quinaryColor: "#f3e5f5", // Light purple background
+    quinaryTextColor: "#4a148c", // Dark purple text
+    quinaryBorderColor: "#8e24aa", // Purple border
+    // Neutral colors
+    background: "#ffffff",
+    mainBkg: "#f5f5f5",
+    lineColor: "#37474f",
+    textColor: "#263238",
+    // Flowchart specific
+    nodeBorder: "#1976d2",
+    clusterBkg: "#eceff1",
+    clusterBorder: "#90a4ae",
+    defaultLinkColor: "#37474f",
+    // Sequence diagram specific
+    actorBkg: "#e3f2fd",
+    actorBorder: "#1976d2",
+    actorTextColor: "#1565c0",
+    actorLineColor: "#37474f",
+    signalColor: "#37474f",
+    signalTextColor: "#263238",
+    labelBoxBkgColor: "#eceff1",
+    labelBoxBorderColor: "#90a4ae",
+    labelTextColor: "#263238",
+    loopTextColor: "#263238",
+    noteBorderColor: "#f57c00",
+    noteBkgColor: "#fff3e0",
+    noteTextColor: "#c43e00",
+    activationBorderColor: "#1976d2",
+    activationBkgColor: "#e3f2fd",
+    sequenceNumberColor: "#ffffff",
+  };
+
+  const darkTheme = {
+    // Base colors
+    primaryColor: "#1e3a5f", // Dark blue background
+    primaryTextColor: "#90caf9", // Light blue text
+    primaryBorderColor: "#42a5f5", // Blue border
+    // Secondary (success)
+    secondaryColor: "#1b3d2e", // Dark green background
+    secondaryTextColor: "#81c784", // Light green text
+    secondaryBorderColor: "#66bb6a", // Green border
+    // Tertiary (warning/accent)
+    tertiaryColor: "#3d2e1a", // Dark orange background
+    tertiaryTextColor: "#ffb74d", // Light orange text
+    tertiaryBorderColor: "#ffa726", // Orange border
+    // Quaternary (danger/red)
+    quaternaryColor: "#3d1a1a", // Dark red background
+    quaternaryTextColor: "#ef9a9a", // Light red text
+    quaternaryBorderColor: "#ef5350", // Red border
+    // Quinary (accent/purple) - fifth semantic color
+    quinaryColor: "#2d1f3d", // Dark purple background
+    quinaryTextColor: "#ce93d8", // Light purple text
+    quinaryBorderColor: "#ab47bc", // Purple border
+    // Neutral colors
+    background: "#1e1e1e",
+    mainBkg: "#2d2d2d",
+    lineColor: "#90a4ae",
+    textColor: "#e0e0e0",
+    // Flowchart specific
+    nodeBorder: "#42a5f5",
+    clusterBkg: "#2d2d2d",
+    clusterBorder: "#546e7a",
+    defaultLinkColor: "#90a4ae",
+    // Sequence diagram specific
+    actorBkg: "#1e3a5f",
+    actorBorder: "#42a5f5",
+    actorTextColor: "#90caf9",
+    actorLineColor: "#90a4ae",
+    signalColor: "#90a4ae",
+    signalTextColor: "#e0e0e0",
+    labelBoxBkgColor: "#2d2d2d",
+    labelBoxBorderColor: "#546e7a",
+    labelTextColor: "#e0e0e0",
+    loopTextColor: "#e0e0e0",
+    noteBorderColor: "#ffa726",
+    noteBkgColor: "#3d2e1a",
+    noteTextColor: "#ffb74d",
+    activationBorderColor: "#42a5f5",
+    activationBkgColor: "#1e3a5f",
+    sequenceNumberColor: "#1e1e1e",
+  };
+
+  /**
+   * Detect if dark theme is currently active
+   * MkDocs Material uses data-md-color-scheme attribute on body
+   */
+  function isDarkTheme() {
+    const scheme = document.body.getAttribute("data-md-color-scheme");
+    return scheme === "slate";
+  }
+
+  /**
+   * Get the current theme configuration
+   */
+  function getThemeConfig() {
+    return isDarkTheme() ? darkTheme : lightTheme;
+  }
+
+  /**
+   * Build Mermaid configuration object with current theme
+   * @param {Object} options - Optional overrides for sequence diagram settings
+   * @returns {Object} Mermaid configuration object
+   */
+  function buildMermaidConfig(options = {}) {
+    const themeVars = getThemeConfig();
+    const sequenceDefaults = {
+      useMaxWidth: true,
+      wrap: true,
+    };
+
+    return {
+      startOnLoad: false,
+      theme: "base",
+      themeVariables: themeVars,
+      flowchart: {
+        htmlLabels: true,
+        curve: "basis",
+        useMaxWidth: true,
+      },
+      sequence: {
+        ...sequenceDefaults,
+        diagramMarginX: 50,
+        diagramMarginY: 10,
+        actorMargin: 50,
+        boxMargin: 10,
+        boxTextMargin: 5,
+        noteMargin: 10,
+        messageMargin: 35,
+        ...options.sequence,
+      },
+      securityLevel: "loose",
+    };
+  }
+
+  /**
+   * Initialize or reinitialize Mermaid with the current theme
+   */
+  function initMermaid() {
+    if (typeof mermaid === "undefined") {
+      // Mermaid not loaded yet, wait and retry
+      setTimeout(initMermaid, 100);
+      return;
+    }
+
+    mermaid.initialize(buildMermaidConfig());
+    renderDiagrams();
+  }
+
+  /**
+   * Render all Mermaid diagrams on the page
+   */
+  async function renderDiagrams() {
+    if (typeof mermaid === "undefined") {
+      return;
+    }
+
+    const diagrams = document.querySelectorAll(".mermaid:not([data-processed])");
+
+    for (let i = 0; i < diagrams.length; i++) {
+      const element = diagrams[i];
+      const graphDefinition = element.textContent || element.innerText;
+
+      // Skip if already processed or empty
+      if (!graphDefinition.trim()) {
+        continue;
+      }
+
+      try {
+        // Generate unique ID for this diagram
+        const id = `mermaid-diagram-${Date.now()}-${i}`;
+
+        // Render the diagram
+        const { svg } = await mermaid.render(id, graphDefinition);
+        element.innerHTML = svg;
+        element.setAttribute("data-processed", "true");
+      } catch (error) {
+        console.error("Mermaid rendering error:", error);
+        // Show user-friendly error message styled for current theme
+        const errorColor = isDarkTheme() ? "#ff6b6b" : "#c62828";
+        const bgColor = isDarkTheme() ? "#3d1a1a" : "#ffebee";
+        const borderColor = isDarkTheme() ? "#ef5350" : "#d32f2f";
+        element.innerHTML = `<div style="padding: 1rem; border: 1px solid ${borderColor}; border-radius: 4px; background: ${bgColor}; color: ${errorColor}; font-family: system-ui, sans-serif;">⚠️ Diagram failed to render. Check console for details.</div>`;
+      }
+    }
+  }
+
+  /**
+   * Re-render all diagrams (used after theme change)
+   */
+  async function reRenderDiagrams() {
+    if (typeof mermaid === "undefined") {
+      return;
+    }
+
+    // Reinitialize mermaid with new theme using shared config
+    mermaid.initialize(buildMermaidConfig());
+
+    // Find all processed diagrams and re-render them
+    const diagrams = document.querySelectorAll(".mermaid[data-processed]");
+
+    for (let i = 0; i < diagrams.length; i++) {
+      const element = diagrams[i];
+
+      // Get original source from data attribute or SVG title
+      const originalSource = element.getAttribute("data-original-source");
+      if (!originalSource) {
+        continue;
+      }
+
+      try {
+        const id = `mermaid-rerender-${Date.now()}-${i}`;
+        const { svg } = await mermaid.render(id, originalSource);
+        element.innerHTML = svg;
+      } catch (error) {
+        console.error("Mermaid re-rendering error:", error);
+      }
+    }
+  }
+
+  /**
+   * Store original diagram sources before first render
+   */
+  function storeOriginalSources() {
+    const diagrams = document.querySelectorAll(".mermaid:not([data-original-source])");
+    diagrams.forEach((element) => {
+      const source = element.textContent || element.innerText;
+      if (source.trim()) {
+        element.setAttribute("data-original-source", source.trim());
+      }
+    });
+  }
+
+  /**
+   * Create a debounced version of a function
+   * @param {Function} func - Function to debounce
+   * @param {number} wait - Milliseconds to wait before invoking
+   * @returns {Function} Debounced function
+   */
+  function debounce(func, wait) {
+    let timeoutId = null;
+    return function (...args) {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+      }
+      timeoutId = setTimeout(() => {
+        func.apply(this, args);
+        timeoutId = null;
+      }, wait);
+    };
+  }
+
+  /**
+   * Set up theme change observer with debouncing
+   */
+  function observeThemeChanges() {
+    // Debounce re-renders to prevent rapid theme toggle issues.
+    // 150ms chosen as a balance: fast enough to feel responsive to users,
+    // but slow enough to coalesce rapid theme toggles and avoid redundant renders.
+    // Lower values (50-100ms) may cause double-renders; higher values (200ms+) feel sluggish.
+    const debouncedReRender = debounce(reRenderDiagrams, 150);
+
+    // MkDocs Material changes the data-md-color-scheme attribute on the body
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (
+          mutation.type === "attributes" &&
+          mutation.attributeName === "data-md-color-scheme"
+        ) {
+          // Theme changed, re-render diagrams (debounced)
+          debouncedReRender();
+          break;
+        }
+      }
+    });
+
+    observer.observe(document.body, {
+      attributes: true,
+      attributeFilter: ["data-md-color-scheme"],
+    });
+  }
+
+  /**
+   * Initialize everything when DOM is ready
+   */
+  function init() {
+    // Store original sources before any rendering
+    storeOriginalSources();
+
+    // Initialize Mermaid
+    initMermaid();
+
+    // Set up theme change observer
+    observeThemeChanges();
+
+    // Also handle MkDocs instant navigation (if enabled)
+    // MkDocs fires a 'DOMContentLoaded'-like event when new content loads
+    if (typeof document$ !== "undefined") {
+      document$.subscribe(function () {
+        storeOriginalSources();
+        initMermaid();
+      });
+    }
+  }
+
+  // Wait for DOM to be ready
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", init);
+  } else {
+    init();
+  }
+})();

package/docs/javascripts/mermaid-config.js.meta

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

package/docs/javascripts.meta

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

package/{Docs/Compatibility.md → docs/reference/compatibility.md}

@@ -20,25 +20,25 @@ Notes
 
 ### Scriptable Object Architecture (SOA)
 
-DxMessaging can work alongside Scriptable Object Architecture patterns, though SOA has documented limitations. See [Pattern 14: SOA Compatibility](Patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for detailed integration strategies, code examples, and migration paths.
+DxMessaging can work alongside Scriptable Object Architecture patterns, though SOA has documented limitations. See [Pattern 14: SOA Compatibility](../guides/patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for detailed integration strategies, code examples, and migration paths.
 
 #### Quick summary
 
 - ✅ **Compatible** - DxMessaging can bridge with SOA systems
 - ⚠️ **Not recommended** - SOA has scalability and maintainability concerns ([detailed critique](https://github.com/cathei/AntiScriptableObjectArchitecture))
 - ✅ **Best practice** - Use ScriptableObjects for immutable design data, DxMessaging for runtime events
-- → See [SOA Integration Patterns](Patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for three coexistence strategies with code examples
+- → See [SOA Integration Patterns](../guides/patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for three coexistence strategies with code examples
 
 ### Dependency Injection (DI) Frameworks
 
-DxMessaging integrates seamlessly with popular DI frameworks:
+DxMessaging integrates with popular DI frameworks:
 
-- **Zenject** - See [Zenject Integration Guide](Integrations/Zenject.md)
-- **VContainer** - See [VContainer Integration Guide](Integrations/VContainer.md)
-- **Reflex** - See [Reflex Integration Guide](Integrations/Reflex.md)
+- **Zenject** - See [Zenject Integration Guide](../integrations/zenject.md)
+- **VContainer** - See [VContainer Integration Guide](../integrations/vcontainer.md)
+- **Reflex** - See [Reflex Integration Guide](../integrations/reflex.md)
 
 DI and DxMessaging complement each other: DI manages dependencies/services, DxMessaging handles event communication.
 
 ### Other Unity Frameworks
 
-For comparisons with other messaging/event frameworks (UniRx, MessagePipe, Zenject Signals, etc.), see [Framework Comparisons](Comparisons.md).
+For comparisons with other messaging/event frameworks (UniRx, MessagePipe, Zenject Signals, etc.), see [Framework Comparisons](../architecture/comparisons.md).

package/docs/reference/compatibility.md.meta

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

package/{Docs/FAQ.md → docs/reference/faq.md}

@@ -1,6 +1,6 @@
 # FAQ — Frequently Asked Questions
 
-[← Back to Index](Index.md) | [Troubleshooting](Troubleshooting.md) | [Getting Started](GettingStarted.md) | [Glossary](Glossary.md)
+[← Back to Index](../getting-started/index.md) | [Troubleshooting](troubleshooting.md) | [Getting Started](../getting-started/getting-started.md) | [Glossary](glossary.md)
 
 ---
 
@@ -8,32 +8,32 @@
 
 - No. You can implement `IUntargetedMessage<T>`, `ITargetedMessage<T>`, or `IBroadcastMessage<T>` directly (recommended for structs). Attributes are optional and help tooling/source‑gen.
 
-Which message type should I use?
+## Which message type should I use?
 
-- Untargeted: global notifications (any listener).
-- Targeted: commands/events for a specific recipient.
-- Broadcast: facts emitted from a source that others may observe.
+- **Untargeted** - global notifications (any listener).
+- **Targeted** - commands/events for a specific recipient.
+- **Broadcast** - facts emitted from a source that others may observe.
 
-How do I enforce ordering?
+## How do I enforce ordering?
 
 - Use the `priority` parameter at registration; lower runs earlier. Interceptors run before handlers; post‑processors run after.
 
-Can I observe all targets/sources for a type?
+## Can I observe all targets/sources for a type?
 
 - Yes. Use `RegisterTargetedWithoutTargeting<T>` or `RegisterBroadcastWithoutSource<T>` (and their post‑processor counterparts).
 
-How do I diagnose what's happening?
+## How do I diagnose what's happening?
 
-- Enable logs and diagnostics: [Diagnostics](Diagnostics.md).
+- Enable logs and diagnostics: [Diagnostics](../guides/diagnostics.md).
 
 ## What happens if I register a listener inside a message handler?
 
 - The newly registered listener will **not** run for the current message emission. It will only become active starting with the **next** message emission.
 - This is called "snapshot semantics" — when a message is emitted, DxMessaging takes a snapshot of all current listeners and uses that frozen list for the entire emission.
 - This applies to all listener types (handlers, interceptors, post-processors) and all message categories (Untargeted, Targeted, Broadcast).
-- This behavior prevents infinite loops and ensures predictable execution order. See [Interceptors & Ordering](InterceptorsAndOrdering.md#snapshot-semantics-frozen-listener-lists) for details and examples.
+- This behavior prevents infinite loops and ensures predictable execution order. See [Interceptors & Ordering](../concepts/interceptors-and-ordering.md#snapshot-semantics-frozen-listener-lists) for details and examples.
 
-Do I need a global bus?
+## Do I need a global bus?
 
 - A global bus is provided (`MessageHandler.MessageBus`). You can also create and pass your own `MessageBus` instance to isolate subsystems and tests.
 
@@ -45,18 +45,13 @@ Do I need a global bus?
 
 ## Related Documentation
 
-### New to DxMessaging?
-
-- → [Visual Guide](VisualGuide.md) — Beginner-friendly introduction
-- → [Getting Started](GettingStarted.md) — Complete guide
-- → [Glossary](Glossary.md) — All terms explained
-
-#### Common Issues
-
-- → [Troubleshooting](Troubleshooting.md) — Solutions to common problems
-- → [Common Patterns](Patterns.md) — See how to use it correctly
-
-##### Reference
-
-- → [Quick Reference](QuickReference.md) — API cheat sheet
-- → [Message Types](MessageTypes.md) — Which type to use when
+- **New to DxMessaging?**
+  - → [Visual Guide](../getting-started/visual-guide.md) — Beginner-friendly introduction
+  - → [Getting Started](../getting-started/getting-started.md) — Complete guide
+  - → [Glossary](glossary.md) — All terms explained
+- **Common Issues**
+  - → [Troubleshooting](troubleshooting.md) — Solutions to common problems
+  - → [Common Patterns](../guides/patterns.md) — See how to use it correctly
+- **Reference**
+  - → [Quick Reference](quick-reference.md) — API cheat sheet
+  - → [Message Types](../concepts/message-types.md) — Which type to use when

package/docs/reference/faq.md.meta

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

package/{Docs/Glossary.md → docs/reference/glossary.md}

@@ -1,6 +1,6 @@
 # Glossary — DxMessaging Terms Explained
 
-[← Back to Index](Index.md) | [Getting Started](GettingStarted.md) | [Visual Guide](VisualGuide.md)
+[← Back to Index](../getting-started/index.md) | [Getting Started](../getting-started/getting-started.md) | [Visual Guide](../getting-started/visual-guide.md)
 
 ---
 
@@ -59,7 +59,11 @@ Code that runs **before** handlers. Can **validate, modify, or cancel** messages
 Example: "Only allow damage between 1 and 999"
 
 ```csharp
-_ = token.RegisterInterceptor<Damage>((ref Damage msg) => {
+// Use the type-specific interceptor variant based on your message type:
+// - RegisterUntargetedInterceptor<T> for IUntargetedMessage
+// - RegisterTargetedInterceptor<T> for ITargetedMessage
+// - RegisterBroadcastInterceptor<T> for IBroadcastMessage
+_ = token.RegisterBroadcastInterceptor<Damage>((ref InstanceId source, ref Damage msg) => {
     if (msg.amount <= 0) return false; // Cancel
     if (msg.amount > 999) msg = new Damage(999); // Clamp
     return true; // Allow
@@ -73,8 +77,11 @@ Code that runs **after** all handlers. Perfect for **logging, analytics, or metr
 Example: "Track every damage event for statistics"
 
 ```csharp
-_ = token.RegisterPostProcessor<Damage>((ref Damage msg) => {
-    Analytics.LogDamage(msg.amount);
+// Use the type-specific post-processor variant based on your message type:
+// - RegisterUntargetedPostProcessor<T> for IUntargetedMessage
+// - RegisterBroadcastWithoutSourcePostProcessor<T> for IBroadcastMessage from any source
+_ = token.RegisterBroadcastWithoutSourcePostProcessor<Damage>((InstanceId source, Damage msg) => {
+    Analytics.LogDamage(source, msg.amount);
 });
 ```
 
@@ -247,16 +254,14 @@ public class UI : MessageAwareComponent {
 
 ### Learn More
 
-- → [Visual Guide](VisualGuide.md) — See these concepts visualized
-- → [Getting Started](GettingStarted.md) — Full introduction with examples
-- → [Message Types](MessageTypes.md) — When to use each type
+- → [Visual Guide](../getting-started/visual-guide.md) — See these concepts visualized
+- → [Getting Started](../getting-started/getting-started.md) — Full introduction with examples
+- → [Message Types](../concepts/message-types.md) — When to use each type
 
 #### Reference
 
-- → [Quick Reference](QuickReference.md) — API cheat sheet
-- → [API Reference](Reference.md) — Complete API documentation
+- → [Quick Reference](quick-reference.md) — API cheat sheet
+- → [API Reference](reference.md) — Complete API documentation
 
-##### Examples
-
-- → [Mini Combat sample](../Samples~/Mini%20Combat/README.md) — See concepts in action
-- → [Patterns](Patterns.md) — Real-world usage patterns
+- → [Mini Combat sample](https://github.com/wallstop/DxMessaging/blob/master/Samples~/Mini%20Combat/README.md) — See concepts in action
+- → [Patterns](../guides/patterns.md) — Real-world usage patterns

package/docs/reference/glossary.md.meta

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