com.wallstop-studios.dxmessaging 2.1.5 → 2.1.6

package/docs/javascripts/mermaid-config.js

@@ -6,9 +6,12 @@
  * 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
+ * 5. Strips per-diagram %%{init:...}%% directives to prevent theme override conflicts
  *
- * For GitHub/VSCode markdown preview fallback, diagrams include:
- * %%{init: {'theme': 'neutral'}}%%
+ * IMPORTANT: Do not use %%{init: {'theme': '...'}}%% directives in docs/ markdown files.
+ * This script manages theming globally and per-diagram directives bypass the theme switching,
+ * causing diagrams to render incorrectly in light mode. The stripping function below removes
+ * such directives before rendering to ensure consistent behavior.
  */
 
 (function () {
@@ -116,6 +119,38 @@
     sequenceNumberColor: "#1e1e1e",
   };
 
+  /**
+   * Regex pattern to match Mermaid init directives
+   * Matches %%{init: {...}}%% at the start of any line in diagram source
+   *
+   * SYNC: Keep pattern in sync with scripts/__tests__/mermaid-config.test.js INIT_DIRECTIVE_PATTERN
+   *
+   * Flags (gims):
+   * - 'g' (global): Finds and replaces all occurrences, not just the first one
+   * - 'i' (case-insensitive): Matches regardless of case (e.g., `%%{Init:...}%%` or `%%{INIT:...}%%`)
+   * - 'm' (multiline): Makes '^' match at the start of every line, not just the start of the string -
+   *   this ensures init directives are stripped wherever they appear in the diagram source
+   * - 's' (dotAll): Makes '.' match any character including newlines, allowing '.*?' to span
+   *   multi-line directives
+   *
+   * These directives can override our theme settings, so we strip them.
+   * We use [ \t]* instead of \s* around the directive to avoid consuming newlines,
+   * which would concatenate adjacent diagram lines and break Mermaid syntax.
+   */
+  const INIT_DIRECTIVE_PATTERN = /^[ \t]*%%\{init:.*?\}%%[ \t]*\r?\n?/gims;
+
+  /**
+   * Strip per-diagram init directives that would override our theme configuration
+   *
+   * SYNC: Keep logic in sync with scripts/__tests__/mermaid-config.test.js stripInitDirectives
+   *
+   * @param {string} source - The original Mermaid diagram source
+   * @returns {string} The source with init directives removed
+   */
+  function stripInitDirectives(source) {
+    return source.replace(INIT_DIRECTIVE_PATTERN, "");
+  }
+
   /**
    * Detect if dark theme is currently active
    * MkDocs Material uses data-md-color-scheme attribute on body
@@ -205,8 +240,11 @@
         // Generate unique ID for this diagram
         const id = `mermaid-diagram-${Date.now()}-${i}`;
 
+        // Strip any per-diagram init directives that would override our theme
+        const cleanedDefinition = stripInitDirectives(graphDefinition);
+
         // Render the diagram
-        const { svg } = await mermaid.render(id, graphDefinition);
+        const { svg } = await mermaid.render(id, cleanedDefinition);
         element.innerHTML = svg;
         element.setAttribute("data-processed", "true");
       } catch (error) {
@@ -245,7 +283,9 @@
 
       try {
         const id = `mermaid-rerender-${Date.now()}-${i}`;
-        const { svg } = await mermaid.render(id, originalSource);
+        // Strip any per-diagram init directives that would override our theme
+        const cleanedSource = stripInitDirectives(originalSource);
+        const { svg } = await mermaid.render(id, cleanedSource);
         element.innerHTML = svg;
       } catch (error) {
         console.error("Mermaid re-rendering error:", error);

package/docs/reference/helpers.md

@@ -162,29 +162,25 @@ var settings4 = new SettingsChanged(0.8f, 2, brightness: 50);    // fullscreen=f
 
 The attribute provides constructor overloads for all common primitive types:
 
-<!-- markdownlint-disable MD046 -->
-
-!!! info "Built-in Type Support"
-
-    === "Numeric"
-
-        | Category              | Types                             |
-        | --------------------- | --------------------------------- |
-        | **Signed Integers**   | `sbyte`, `short`, `int`, `long`   |
-        | **Unsigned Integers** | `byte`, `ushort`, `uint`, `ulong` |
-        | **Floating Point**    | `float`, `double`                 |
-
-    === "Other"
-
-        | Category      | Types    |
-        | ------------- | -------- |
-        | **Boolean**   | `bool`   |
-        | **Character** | `char`   |
-        | **String**    | `string` |
-
-    For enums, Unity types, and other complex types, use the `Expression` property.
-
-<!-- markdownlint-enable MD046 -->
+> ℹ️ **Info: Built-in Type Support**
+>
+> **Numeric:**
+>
+> | Category              | Types                             |
+> | --------------------- | --------------------------------- |
+> | **Signed Integers**   | `sbyte`, `short`, `int`, `long`   |
+> | **Unsigned Integers** | `byte`, `ushort`, `uint`, `ulong` |
+> | **Floating Point**    | `float`, `double`                 |
+>
+> **Other:**
+>
+> | Category      | Types    |
+> | ------------- | -------- |
+> | **Boolean**   | `bool`   |
+> | **Character** | `char`   |
+> | **String**    | `string` |
+>
+> For enums, Unity types, and other complex types, use the `Expression` property.
 
 ##### Examples by type
 
@@ -294,16 +290,12 @@ public readonly partial struct AdvancedDefaults
 }
 ```
 
-<!-- markdownlint-disable MD046 -->
-
-!!! tip "Expression rules"
-
-    - The expression is inserted **verbatim** into the generated code
-    - Must be a valid C# constant expression
-    - Type safety is enforced by the C# compiler at build time
-    - Perfect for enums, nullable types, static constants, or complex defaults
-
-<!-- markdownlint-enable MD046 -->
+> 💡 **Tip: Expression rules**
+>
+> - The expression is inserted **verbatim** into the generated code
+> - Must be a valid C# constant expression
+> - Type safety is enforced by the C# compiler at build time
+> - Perfect for enums, nullable types, static constants, or complex defaults
 
 #### Code Examples
 
@@ -411,17 +403,13 @@ new AudioSettingsChanged(0.7f, 0.6f, 0.9f, false).Emit();
 
 #### Best Practices
 
-<!-- markdownlint-disable MD046 -->
-
-!!! success "Recommendations"
-
-    1. **Order matters** — Place required fields before optional fields in your struct
-    1. **Use meaningful defaults** — Choose defaults that represent the most common use case
-    1. **Prefer explicit values** — Use `[DxOptionalParameter(0)]` instead of `[DxOptionalParameter]` when clarity helps
-    1. **Use Expression for complex types** — Don't fight the type system; use `Expression` for enums and Unity types
-    1. **Document unusual defaults** — If a default isn't obvious, add a comment explaining why
-
-<!-- markdownlint-enable MD046 -->
+> ✅ **Success: Recommendations**
+>
+> 1. **Order matters** — Place required fields before optional fields in your struct
+> 1. **Use meaningful defaults** — Choose defaults that represent the most common use case
+> 1. **Prefer explicit values** — Use `[DxOptionalParameter(0)]` instead of `[DxOptionalParameter]` when clarity helps
+> 1. **Use Expression for complex types** — Don't fight the type system; use `Expression` for enums and Unity types
+> 1. **Document unusual defaults** — If a default isn't obvious, add a comment explaining why
 
 ## Why Use Attributes Instead of Manual Implementation
 
@@ -638,42 +626,38 @@ msg.Emit(testBus);
 
 ### Message Type Attributes
 
-<!-- markdownlint-disable MD046 -->
+#### Untargeted
 
-=== "Untargeted"
+Mark as a global message (no target):
 
-    Mark as a global message (no target):
-
-    ```csharp
-    [DxUntargetedMessage]
-    public readonly partial struct GamePaused { }
-    ```
-
-=== "Targeted"
+```csharp
+[DxUntargetedMessage]
+public readonly partial struct GamePaused { }
+```
 
-    Mark as a message sent to a specific target:
+#### Targeted
 
-    ```csharp
-    [DxTargetedMessage]
-    public readonly partial struct Heal
-    {
-        public readonly int amount;
-    }
-    ```
+Mark as a message sent to a specific target:
 
-=== "Broadcast"
+```csharp
+[DxTargetedMessage]
+public readonly partial struct Heal
+{
+    public readonly int amount;
+}
+```
 
-    Mark as a message broadcast from a source:
+#### Broadcast
 
-    ```csharp
-    [DxBroadcastMessage]
-    public readonly partial struct TookDamage
-    {
-        public readonly int amount;
-    }
-    ```
+Mark as a message broadcast from a source:
 
-<!-- markdownlint-enable MD046 -->
+```csharp
+[DxBroadcastMessage]
+public readonly partial struct TookDamage
+{
+    public readonly int amount;
+}
+```
 
 ### Constructor Generation Attributes
 
@@ -695,39 +679,35 @@ public readonly partial struct Damage
 
 Makes a constructor parameter optional. Three usage patterns:
 
-<!-- markdownlint-disable MD046 -->
-
-??? example "Default Value (type default)"
-
-    Uses the type's default value (`0`, `false`, `null`, etc.):
-
-    ```csharp
-    [DxOptionalParameter]
-    public readonly bool flag;
-    // Generates: bool flag = default
-    ```
-
-??? example "Custom Value (primitive)"
-
-    Provides a specific default value:
-
-    ```csharp
-    [DxOptionalParameter(42)]
-    public readonly int count;
-    // Generates: int count = 42
-    ```
-
-??? example "Expression (complex types)"
-
-    Uses a verbatim expression for enums, Unity types, etc.:
-
-    ```csharp
-    [DxOptionalParameter(Expression = "DamageType.Physical")]
-    public readonly DamageType damageType;
-    // Generates: DamageType damageType = DamageType.Physical
-    ```
-
-<!-- markdownlint-enable MD046 -->
+> 📋 **Example: Default Value (type default)**
+>
+> Uses the type's default value (`0`, `false`, `null`, etc.):
+>
+> ```csharp
+> [DxOptionalParameter]
+> public readonly bool flag;
+> // Generates: bool flag = default
+> ```
+>
+> 📋 **Example: Custom Value (primitive)**
+>
+> Provides a specific default value:
+>
+> ```csharp
+> [DxOptionalParameter(42)]
+> public readonly int count;
+> // Generates: int count = 42
+> ```
+>
+> 📋 **Example: Expression (complex types)**
+>
+> Uses a verbatim expression for enums, Unity types, etc.:
+>
+> ```csharp
+> [DxOptionalParameter(Expression = "DamageType.Physical")]
+> public readonly DamageType damageType;
+> // Generates: DamageType damageType = DamageType.Physical
+> ```
 
 ### Supported Types
 
@@ -936,55 +916,51 @@ public readonly partial struct MessageA
 
 ## Troubleshooting Source Generators
 
-<!-- markdownlint-disable MD046 -->
-
-??? warning "Attributes not working / code not generated"
-
-    ### Checklist
-
-    1. ✅ Is type marked `partial`?
-    1. ✅ Did you rebuild the project?
-    1. ✅ Is Unity 2021.3+ (Roslyn source generator support)?
-    1. ✅ Check `obj/` folder for `.g.cs` files
-
-    #### Fix
-
-    ```csharp
-    // ❌ Missing partial, will not compile
-    [DxAutoConstructor]
-    public readonly struct MyMsg { }
-
-    // ✅ Correct
-    [DxAutoConstructor]
-    public readonly partial struct MyMsg { }
-    ```
-
-??? warning "Constructor not generated"
-
-    **Cause:** No public fields to generate from
-
-    ```csharp
-    // ❌ No public fields
-    [DxAutoConstructor]
-    public readonly partial struct Empty { }
-
-    // ✅ Has public field
-    [DxAutoConstructor]
-    public readonly partial struct WithData {
-        public readonly int value;
-    }
-    ```
-
-??? warning "Unity can't find generated code"
-
-    ##### Solution
-
-    1. Close Unity
-    1. Delete `Library/` folder
-    1. Reopen Unity
-    1. Let it reimport everything
-
-<!-- markdownlint-enable MD046 -->
+> ⚠️ **Warning: Attributes not working / code not generated**
+>
+> ### Checklist
+>
+> 1. ✅ Is type marked `partial`?
+> 1. ✅ Did you rebuild the project?
+> 1. ✅ Is Unity 2021.3+ (Roslyn source generator support)?
+> 1. ✅ Check `obj/` folder for `.g.cs` files
+>
+> #### Fix
+>
+> ```csharp
+> // ❌ Missing partial, will not compile
+> [DxAutoConstructor]
+> public readonly struct MyMsg { }
+>
+> // ✅ Correct
+> [DxAutoConstructor]
+> public readonly partial struct MyMsg { }
+> ```
+>
+> ⚠️ **Warning: Constructor not generated**
+>
+> **Cause:** No public fields to generate from
+>
+> ```csharp
+> // ❌ No public fields
+> [DxAutoConstructor]
+> public readonly partial struct Empty { }
+>
+> // ✅ Has public field
+> [DxAutoConstructor]
+> public readonly partial struct WithData {
+>     public readonly int value;
+> }
+> ```
+>
+> ⚠️ **Warning: Unity can't find generated code**
+>
+> ##### Solution
+>
+> 1. Close Unity
+> 1. Delete `Library/` folder
+> 1. Reopen Unity
+> 1. Let it reimport everything
 
 ## Related Documentation
 

package/docs/reference/quick-reference.md

@@ -177,7 +177,11 @@ Interceptors → Global Accept-All → Handlers<T> @ source
     → Post-Processors<T> (All Sources)
 ```
 
-!!! note "Priority Rules" - Lower priority values run earlier - Same priority preserves registration order - Within a priority, fast (by-ref) handlers run before action handlers
+> 📝 **Note: Priority Rules**
+>
+> - Lower priority values run earlier
+> - Same priority preserves registration order
+> - Within a priority, fast (by-ref) handlers run before action handlers
 
 ## API Quick Reference