com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

package/{Docs/VisualGuide.md → docs/getting-started/visual-guide.md}

@@ -1,13 +1,13 @@
-# DxMessaging Visual Guide for Absolute Beginners
+# DxMessaging Visual Guide for Beginners
 
 If you're brand new to messaging systems, this visual guide will help you understand DxMessaging in minutes.
 
-## 🎯 What Problem Does It Solve
+## What Problem Does It Solve
 
 ### The Old Way (Spaghetti Code)
 
 ```mermaid
-graph LR
+flowchart LR
     Player[Player]
     Enemy[Enemy]
     Inventory[Inventory]
@@ -20,23 +20,22 @@ graph LR
     Enemy -->|direct ref| Audio
     Inventory -->|direct ref| Audio
 
-    style Player fill:#ffa39e,stroke:#cf1322,stroke-width:2px,color:#000
-    style Enemy fill:#ffa39e,stroke:#cf1322,stroke-width:2px,color:#000
-    style Inventory fill:#ffa39e,stroke:#cf1322,stroke-width:2px,color:#000
-    style UI fill:#b7eb8f,stroke:#389e0d,stroke-width:2px,color:#000
-    style Audio fill:#b7eb8f,stroke:#389e0d,stroke-width:2px,color:#000
+    classDef danger stroke-width:2px
+    class Player,Enemy,Inventory danger
+    classDef success stroke-width:2px
+    class UI,Audio success
 ```
 
 #### Problems
 
-- ❌ Everyone needs to know everyone else
-- ❌ Hard to add/remove systems
-- ❌ Memory leaks from forgotten unsubscribes
+- Everyone needs to know everyone else
+- Hard to add/remove systems
+- Memory leaks from forgotten unsubscribes
 
 ### The DxMessaging Way (Clean Separation)
 
 ```mermaid
-graph TB
+flowchart TB
     Player[Player]
     Enemy[Enemy]
     Inventory[Inventory]
@@ -53,26 +52,25 @@ graph TB
     Bus -->|notify| Audio
     Bus -->|notify| Analytics
 
-    style Player fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-    style Enemy fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-    style Inventory fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-    style Bus fill:#ffd591,stroke:#d46b08,stroke-width:3px,color:#000
-    style UI fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
-    style Audio fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
-    style Analytics fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+    classDef primary stroke-width:2px
+    class Player,Enemy,Inventory primary
+    classDef warning stroke-width:3px
+    class Bus warning
+    classDef success stroke-width:2px
+    class UI,Audio,Analytics success
 ```
 
 #### Benefits
 
-- ✅ Nobody knows about anyone else
-- ✅ Easy to add/remove systems
-- ✅ Zero memory leaks (automatic cleanup)
+- Nobody knows about anyone else
+- Easy to add/remove systems
+- Automatic cleanup (prevents common leaks)
 
-## 📨 The Three Message Types (Simple!)
+## The Three Message Types (Simple!)
 
 Think of messages like different kinds of mail:
 
-### 1. 📢 Untargeted (Announcement to Everyone)
+### 1. Untargeted (Announcement to Everyone)
 
 Like a megaphone announcement in a stadium - everyone hears it.
 
@@ -96,7 +94,7 @@ _ = token.RegisterUntargeted<GamePaused>(OnPause);
 - "Settings changed!"
 - "Level loaded!"
 
-### 2. 📮 Targeted (Letter to One Person)
+### 2. Targeted (Letter to One Person)
 
 Like mailing a letter to a specific address - only that recipient gets it.
 
@@ -120,7 +118,7 @@ _ = token.RegisterComponentTargeted<Heal>(this, OnHeal);
 - "Enemy #3, take damage!"
 - "Button, update your text!"
 
-### 3. 📡 Broadcast (News from One Source)
+### 3. Broadcast (News from One Source)
 
 Like a news broadcast - comes from one source, anyone can tune in.
 
@@ -147,7 +145,7 @@ _ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyEnemy);
 - "I (enemy) died!"
 - "I (chest) was opened!"
 
-## 🔄 The Message Journey (Step by Step)
+## The Message Journey (Step by Step)
 
 When you send a message, here's what happens:
 
@@ -171,9 +169,9 @@ sequenceDiagram
     Msg->>Int: Check message
     Int->>Int: Is valid? (>0)<br/>Clamp if needed (<999)
     alt Invalid message
-        Int--xMsg: ❌ Cancel
+        Int--xMsg: Cancel
     else Valid message
-        Int->>H0: ✅ Continue
+        Int->>H0: Continue
     end
 
     Note over H0,H10: 4. Execute handlers (by priority)
@@ -193,17 +191,17 @@ sequenceDiagram
 - **Step 1-2:** You create and emit the message
 - **Step 3 (Optional):** Interceptors can validate, modify, or cancel
 - **Step 4:** Handlers run in priority order (lower number = earlier)
-- **Step 5 (Optional):** Post-processors run after everything (perfect for analytics)
+- **Step 5 (Optional):** Post-processors run after everything (suitable for analytics)
 
-## 🎮 Your First Message (3 Easy Steps)
+## Your First Message (3 Easy Steps)
 
-### Step 1️⃣: Define It
+### Step 1: Define It
 
 ```csharp
 using DxMessaging.Core.Attributes;
 
-[DxTargetedMessage]     // ← What kind of message?
-[DxAutoConstructor]     // ← Auto-make a constructor
+[DxTargetedMessage]     // <- What kind of message?
+[DxAutoConstructor]     // <- Auto-make a constructor
 public readonly partial struct Heal {
     public readonly int amount;
 }
@@ -211,22 +209,22 @@ public readonly partial struct Heal {
 
 #### What are those `[DxSomething]` tags?
 
-They're called **attributes** — magic markers that tell the computer to write code for you! It's like having a robot assistant:
+These are **attributes** that work with C# source generators to produce boilerplate code at compile time:
 
-- **`[DxTargetedMessage]`** → "Hey robot, make this a targeted message"
-- **`[DxAutoConstructor]`** → "Hey robot, create a constructor for me"
+- **`[DxTargetedMessage]`** - Marks this struct as a targeted message and generates the required emit methods
+- **`[DxAutoConstructor]`** - Generates a constructor that initializes all fields
 
-The `[DxAutoConstructor]` automatically creates this:
+For example, `[DxAutoConstructor]` generates this constructor automatically:
 
 ```csharp
 public Heal(int amount) { this.amount = amount; }
 ```
 
-**Why `partial`?** So the robot can add code to your type in a separate file. Think of it as giving permission to extend your struct.
+**Why `partial`?** The `partial` keyword allows the source generator to add the generated code to your type in a separate file during compilation.
 
-**Want to learn more?** See [Helpers & Source Generation](Helpers.md) for the full explanation!
+**Want to learn more?** See [Helpers & Source Generation](../reference/helpers.md) for the full explanation!
 
-### Step 2️⃣: Listen for It
+### Step 2: Listen for It
 
 ```csharp
 using DxMessaging.Unity;
@@ -245,24 +243,24 @@ public class Player : MessageAwareComponent {
 }
 ```
 
-**Magic:** `MessageAwareComponent` handles all the lifecycle automatically!
+**Automatic:** `MessageAwareComponent` handles all the lifecycle automatically.
 
 - Creates registration in `Awake()`
 - Activates in `OnEnable()`
 - Deactivates in `OnDisable()`
 - Cleans up in `OnDestroy()`
 
-### Step 3️⃣: Send It
+### Step 3: Send It
 
 ```csharp
 // From anywhere in your code:
 var healMsg = new Heal(50);
 healMsg.EmitComponentTargeted(playerComponent);
 
-// That's it! Player will receive it automatically.
+// Player will receive this message.
 ```
 
-## 🧩 Common Patterns Visualized
+## Common Patterns Visualized
 
 ### Pattern: Scene Transition
 
@@ -284,7 +282,7 @@ sequenceDiagram
     Bus->>Save: SceneChanged received
     Save->>Save: SaveGame()
 
-    Note over Audio,Save: ✅ All independent!<br/>No coupling!
+    Note over Audio,Save: All independent,<br/>no coupling
 ```
 
 **Why this works:** AudioSystem and SaveSystem don't know about SceneManager or each other. They just listen for `SceneChanged` messages and react independently.
@@ -306,7 +304,7 @@ _ = audioToken.RegisterUntargeted<SceneChanged>(OnScene);
 _ = saveToken.RegisterUntargeted<SceneChanged>(OnScene);
 ```
 
-### Pattern: Player Input → Action
+### Pattern: Player Input -> Action
 
 ```mermaid
 sequenceDiagram
@@ -320,7 +318,7 @@ sequenceDiagram
     Bus->>Player: Jump message received
     Player->>Player: ApplyForce()<br/>rb.AddForce(...)
 
-    Note over Input,Player: ✅ Decoupled!<br/>Input doesn't reference Player
+    Note over Input,Player: Decoupled!<br/>Input doesn't reference Player
 ```
 
 **Why this works:** InputSystem doesn't need a reference to Player. It just sends a `Jump` message targeted at the player, and the player responds.
@@ -364,7 +362,7 @@ sequenceDiagram
     C->>Bus: ChestOpened
     Bus->>Ach: CheckProgress()<br/>UnlockIfReady()
 
-    Note over Ach: ✅ Sees EVERYTHING<br/>without coupling!
+    Note over Ach: Sees EVERYTHING<br/>without coupling!
 ```
 
 **Why this works:** Achievement System uses `RegisterGlobalAcceptAll()` to observe every message type, tracking progress across the entire game without any system knowing about it.
@@ -385,28 +383,28 @@ public class AchievementSystem : MessageAwareComponent {
 }
 ```
 
-## 🚦 When to Use Which Message Type
+## When to Use Which Message Type
 
 ### Use Untargeted When
 
-- ✅ Global game state changes (pause, settings, scene load)
-- ✅ System-wide announcements
-- ✅ Configuration updates
+- Global game state changes (pause, settings, scene load)
+- System-wide announcements
+- Configuration updates
 
 ### Use Targeted When
 
-- ✅ Commanding a specific object ("You, do this!")
-- ✅ UI updates for specific elements
-- ✅ Direct communication (A → B)
+- Commanding a specific object ("You, do this!")
+- UI updates for specific elements
+- Direct communication (A -> B)
 
 ### Use Broadcast When
 
-- ✅ Events others should know about ("I did this!")
-- ✅ Analytics tracking
-- ✅ Achievement triggers
-- ✅ Notifications from specific sources
+- Events others should know about ("I did this!")
+- Analytics tracking
+- Achievement triggers
+- Notifications from specific sources
 
-## 🎨 Mental Model: Restaurant Analogy
+## Mental Model: Restaurant Analogy
 
 Think of DxMessaging like a restaurant:
 
@@ -414,25 +412,25 @@ Think of DxMessaging like a restaurant:
 
 > "Attention all customers: We're closing in 10 minutes!"
 >
-> → Everyone hears it
+> -> Everyone hears it
 
 ### Targeted = Waiter Delivering Food
 
 > "Order for table 5: Here's your burger"
 >
-> → Only table 5 gets it
+> -> Only table 5 gets it
 
 ### Broadcast = Customer Calling Waiter
 
 > "Excuse me, I need a refill!" (from table 3)
 >
-> → Comes from table 3
+> -> Comes from table 3
 >
-> → Any available waiter can respond
+> -> Any available waiter can respond
 >
-> → Manager might track it for statistics
+> -> Manager might track it for statistics
 
-## 🔍 Debugging Visualized
+## Debugging Visualized
 
 DxMessaging has built-in Inspector support!
 
@@ -440,46 +438,50 @@ DxMessaging has built-in Inspector support!
 
 #### Message History (last 10)
 
-- `12:34:05 - Heal → Player (50)`
-- `12:34:03 - Jump → Player`
+- `12:34:05 - Heal -> Player (50)`
+- `12:34:03 - Jump -> Player`
 - `12:34:01 - GamePaused (global)`
 
 ##### Registrations
 
-- ✓ Heal (priority: 0, 5 calls)
-- ✓ Jump (priority: 0, 2 calls)
-- ✓ TookDamage (priority: 10)
+- Heal (priority: 0, 5 calls)
+- Jump (priority: 0, 2 calls)
+- TookDamage (priority: 10)
 
-## ⚡ Performance at a Glance
+## Performance at a Glance
 
 | Metric       | Traditional C# Events | DxMessaging                         |
 | ------------ | --------------------- | ----------------------------------- |
-| **Speed**    | ⚡⚡⚡⚡ (baseline)   | ⚡⚡⚡⚡ (~10ns slower, negligible) |
-| **Memory**   | ⚠️ Can leak!          | ✅ Zero leaks (struct messages)     |
-| **Coupling** | ❌ Tight coupling     | ✅ Zero coupling                    |
+| **Speed**    | (baseline)            | (~10ns slower, negligible)          |
+| **Memory**   | Can leak!             | Automatic cleanup (struct messages) |
+| **Coupling** | Tight coupling        | Zero coupling                       |
 
 **Bottom line:** Slightly slower than raw events, but:
 
-- ✅ Zero memory leaks
-- ✅ Zero coupling
-- ✅ Full observability
-- ✅ Predictable ordering
+- Prevents common memory leaks
+- Zero coupling
+- Full observability
+- Predictable ordering
 
-## 🎓 Learning Path
+## Learning Path
 
 ```mermaid
-graph TD
-    Start[START HERE<br/>Read this Visual Guide<br/>5 min ✓]
-    Start --> Step2[Try Quick Start example<br/>5 min<br/>Define → Listen → Send]
+flowchart TD
+    Start[START HERE<br/>Read this Visual Guide<br/>5 min]
+    Start --> Step2[Try Quick Start example<br/>5 min<br/>Define -> Listen -> Send]
     Step2 --> Step3[Import Mini Combat sample<br/>10 min<br/>See it in action!]
     Step3 --> Step4[Read Common Patterns<br/>15 min<br/>Real-world solutions]
     Step4 --> Step5[Build your first feature!<br/>30 min<br/>You're ready!]
 
-    style Start fill:#91d5ff,stroke:#096dd9,stroke-width:3px,color:#000
-    style Step5 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+    classDef primary stroke-width:3px
+    class Start primary
+    classDef success stroke-width:2px
+    class Step5 success
+    classDef secondary stroke-width:2px
+    class Step2,Step3,Step4 secondary
 ```
 
-## 🆘 Common Beginner Questions
+## Common Beginner Questions
 
 ### "Do I always need MessageAwareComponent?"
 
@@ -487,7 +489,7 @@ graph TD
 
 **For pure C#:** No, you can use `MessageRegistrationToken` directly if you're not in Unity.
 
-**Bottom line:** If you're in Unity, just use `MessageAwareComponent`. It'll save you hours of debugging.
+**Bottom line:** If you're in Unity, use `MessageAwareComponent`. It handles subscription lifecycle automatically, which can reduce debugging related to memory leaks.
 
 ### "Can I send a message to multiple targets?"
 
@@ -501,19 +503,19 @@ graph TD
 ##### Example
 
 ```csharp
-// ❌ DON'T: Try to target multiple entities
+// DON'T: Try to target multiple entities
 msg.EmitComponentTargeted(player1);
 msg.EmitComponentTargeted(player2);  // Feels wrong, right?
 
-// ✅ DO: Use broadcast so everyone can listen
+// DO: Use broadcast so everyone can listen
 msg.EmitGameObjectBroadcast(enemy);  // Now anyone can observe this enemy
 ```
 
 ### "What if I forget to unsubscribe?"
 
-**You literally can't forget!** 🎉
+#### The system handles cleanup automatically
 
-When your component is destroyed, DxMessaging automatically cleans up. No `OnDestroy()` needed. No memory leaks possible.
+When your component is destroyed, DxMessaging cleans up registrations for you. No `OnDestroy()` needed. This reduces the likelihood of common memory leak patterns.
 
 #### Old way (easy to forget)
 
@@ -522,26 +524,26 @@ void OnEnable() { GameManager.OnScoreChanged += Update; }
 void OnDisable() { GameManager.OnScoreChanged -= Update; }  // Forgot this? LEAK!
 ```
 
-##### DxMessaging way (impossible to forget)
+##### DxMessaging way (automatic management)
 
 ```csharp
 protected override void RegisterMessageHandlers() {
     _ = Token.RegisterUntargeted<ScoreChanged>(Update);
 }
-// That's it! Automatic cleanup when component dies.
+// Automatic cleanup when component is destroyed.
 ```
 
 ### "Is it slower than regular events?"
 
 **Barely** (~10ns per handler = 0.00001 milliseconds).
 
-#### Put it this way
+#### Benchmark comparison
 
 - Regular C# event: ~50ns
 - DxMessaging: ~60ns
-- The difference: Drinking a coffee takes 3 billion nanoseconds
+- Difference: ~10ns per invocation
 
-You get automatic lifecycle, zero leaks, full observability, and predictable ordering for a 20% overhead that's **completely negligible** in any real game.
+You get automatic lifecycle, automatic cleanup, full observability, and predictable ordering for approximately 20% overhead compared to direct method calls.
 
 ### "Can I cancel a message?"
 
@@ -577,26 +579,27 @@ You'll see:
 
 **No more guessing.** You can literally see your event flow in real-time.
 
-## ✅ Quick Checklist: Am I Doing It Right
+## Quick Checklist: Am I Doing It Right
 
-- [ ] Using `MessageAwareComponent` for Unity components? ✅
-- [ ] Defining messages as `readonly struct`? ✅
-- [ ] Using `[DxAutoConstructor]` to avoid boilerplate? ✅
-- [ ] Storing struct in variable before emitting? ✅
-- [ ] Choosing the right message type (Untargeted/Targeted/Broadcast)? ✅
-- [ ] Using GameObject/Component emit helpers? ✅
+- [ ] Using `MessageAwareComponent` for Unity components?
+- [ ] Defining messages as `readonly struct`?
+- [ ] Using `[DxAutoConstructor]` to avoid boilerplate?
+- [ ] Storing struct in variable before emitting?
+- [ ] Choosing the right message type (Untargeted/Targeted/Broadcast)?
+- [ ] Using GameObject/Component emit helpers?
 
-If you checked all these, **you're doing it right!** 🎉
+If you checked all these, you are following best practices.
 
-## 🚀 Next Steps
+## Next Steps
 
 Ready to dive deeper?
 
-1. **[Getting Started Guide](GettingStarted.md)** - Full guide with more details
-1. **[Common Patterns](Patterns.md)** - Real-world examples
-1. **[Message Types](MessageTypes.md)** - Deep dive into when to use what
-1. **[Diagnostics](Diagnostics.md)** - Master the Inspector tools
+1. **[Mental Model](../concepts/mental-model.md)** - Understand the philosophy
+1. **[Getting Started Guide](getting-started.md)** - Full guide with more details
+1. **[Common Patterns](../guides/patterns.md)** - Real-world examples
+1. **[Message Types](../concepts/message-types.md)** - Deep dive into when to use what
+1. **[Diagnostics](../guides/diagnostics.md)** - Master the Inspector tools
 
 ---
 
-**Remember:** DxMessaging makes complex communication simple. You define what to say, who should hear it, and the system handles the rest! 🎊
+**Summary:** DxMessaging provides a structured approach to inter-component communication. You define the message, specify recipients, and the system handles delivery.

package/docs/getting-started/visual-guide.md.meta

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

package/docs/getting-started.meta

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

package/{Docs/Advanced.md → docs/guides/advanced.md}

@@ -201,7 +201,7 @@ Do's
 - Listeners registered **during** an emission will **not** run for that emission — they only become active for the **next** emission.
 - This prevents infinite loops (e.g., a handler that registers itself won't recurse).
 - This applies to all message types (Untargeted, Targeted, Broadcast) and all listener types.
-- See [Interceptors & Ordering](InterceptorsAndOrdering.md#snapshot-semantics-frozen-listener-lists) for detailed examples.
+- See [Interceptors & Ordering](../concepts/interceptors-and-ordering.md#snapshot-semantics-frozen-listener-lists) for detailed examples.
 
 Don’ts
 
@@ -256,6 +256,6 @@ More advanced use cases
 
 Related
 
-- [Unity Integration](UnityIntegration.md)
-- [Diagnostics (Inspector)](Diagnostics.md)
-- [String Messages](StringMessages.md)
+- [Unity Integration](unity-integration.md)
+- [Diagnostics (Inspector)](diagnostics.md)
+- [String Messages](../advanced/string-messages.md)

package/docs/guides/advanced.md.meta

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