com.wallstop-studios.dxmessaging 2.1.5 → 2.1.7

package/docs/concepts/mental-model.md

@@ -0,0 +1,390 @@
+# Mental Model: How to Think About DxMessaging
+
+[← Concepts Index](index.md) | [Message Types](message-types.md) | [Getting Started](../getting-started/getting-started.md)
+
+---
+
+This guide explains how to think about DxMessaging from first principles. Understanding the mental model makes everything else easier.
+
+## The Core Idea
+
+DxMessaging is built around one principle: **it gets out of your way**.
+
+You have data. You need to pass it around. That's the problem.
+
+DxMessaging provides fast, simple primitives as building blocks. You model changes as message types with optional context, using game primitives (GameObjects, components) as that context. The library handles the plumbing.
+
+You don't build your game INTO the messaging system. The messaging system is opt-in and optional - a tool you reach for when it helps.
+
+## What Problem Does This Solve?
+
+In a typical Unity project, you face a common challenge:
+
+```text
+Player takes damage
+    ├── Health bar needs updating
+    ├── Sound system plays damage audio
+    ├── Camera shakes
+    ├── Achievement system checks milestones
+    ├── Analytics logs the event
+    └── Tutorial system checks for tips
+```
+
+Traditional approaches require tight coupling: either the Player knows about all these systems, or they all hold references to the Player. Both paths lead to tangled dependencies.
+
+DxMessaging inverts this relationship. The Player broadcasts a fact - "I took 25 damage" - and interested systems subscribe to receive it. Systems come and go without the Player knowing or caring.
+
+## The Three Message Categories
+
+DxMessaging models three fundamental patterns of communication. Each maps to a real-world analogy.
+
+### Untargeted: The PA System
+
+```mermaid
+flowchart LR
+    S[Someone] -->|announces| PA[📢 PA System]
+    PA --> L1[Listener A]
+    PA --> L2[Listener B]
+    PA --> L3[Listener C]
+```
+
+Untargeted messages are announcements. No specific recipient. No specific sender that matters. Everyone who cares can hear it.
+
+> 📝 **Note: No sender identity**
+>
+> Unlike a real PA system, untargeted messages carry no concept of "who announced it." There is no sender identity attached - only the message content itself.
+
+#### Real examples
+
+- "The game is paused"
+- "Settings changed"
+- "Scene finished loading"
+- "Day/night cycle switched to night"
+
+```csharp
+// Define an untargeted message with attributes
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct GamePaused
+{
+    public readonly bool isPaused;
+}
+
+// Multiple fields are supported
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct SettingsChanged
+{
+    public readonly float volume;
+    public readonly int quality;
+}
+```
+
+**Use when:** You need to announce something to whoever might care. The sender doesn't know or care who's listening.
+
+### Targeted: The Addressed Letter
+
+```mermaid
+flowchart LR
+    S[Sender] -->|"To: Player"| Letter[📬 Message Bus]
+    Letter --> Player[Player receives]
+    Other1[Enemy A] -.->|ignores| Letter
+    Other2[Enemy B] -.->|ignores| Letter
+```
+
+Targeted messages are commands or directed events. They have a specific recipient. Only that recipient (and any interested observers) receives them.
+
+#### Real examples
+
+- "Player, heal for 10 HP"
+- "Door #7, open"
+- "This specific enemy, take 25 damage"
+- "Inventory slot 3, equip this weapon"
+
+```csharp
+// Define a targeted message with attributes
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct Heal
+{
+    public readonly int amount;
+}
+
+// Emit to a specific target
+Heal heal = new Heal(10);
+heal.EmitGameObjectTargeted(playerGameObject);
+```
+
+**Use when:** You're commanding a specific entity to do something, or notifying a specific entity about something that happened to it.
+
+### Broadcast: The Radio Station
+
+```mermaid
+flowchart LR
+    Source[Enemy] -->|"I took damage!"| Radio[📻 Message Bus]
+    Radio --> L1[Damage Numbers UI]
+    Radio --> L2[Achievement Tracker]
+    Radio --> L3[Analytics]
+    Radio --> L4[Combat Log]
+```
+
+Broadcast messages are facts emitted by a specific source. Unlike targeted messages, there's no intended recipient - just an origin. Anyone who wants to observe can tune in.
+
+#### Real examples
+
+- "This enemy took 25 damage" (from the enemy)
+- "The player picked up item X" (from the player)
+- "This chest opened" (from the chest)
+- "Projectile hit something" (from the projectile)
+
+```csharp
+// Define a broadcast message with attributes
+[DxBroadcastMessage]
+[DxAutoConstructor]
+public readonly partial struct TookDamage
+{
+    public readonly int amount;
+}
+
+// Emit from a specific source
+TookDamage damage = new TookDamage(25);
+damage.EmitGameObjectBroadcast(thisEnemy);
+```
+
+**Use when:** Something happened to an entity, and other systems might want to know about it. The entity doesn't care who's listening.
+
+## Deciding Which Type to Use
+
+```mermaid
+flowchart TD
+    Start([I need to send a message])
+    Start --> Q1{Does it matter<br/>WHO sent it?}
+
+    Q1 -->|No| Q2{Does it matter<br/>WHO receives it?}
+    Q2 -->|No| Untargeted[Use UNTARGETED<br/>Global announcement]
+    Q2 -->|Yes| Targeted[Use TARGETED<br/>Directed command]
+
+    Q1 -->|Yes| Q3{Am I commanding<br/>someone to act?}
+    Q3 -->|Yes| Targeted
+    Q3 -->|No| Broadcast[Use BROADCAST<br/>Observable fact]
+```
+
+| Question                            | Untargeted | Targeted | Broadcast |
+| ----------------------------------- | :--------: | :------: | :-------: |
+| Has a specific sender that matters? |     ❌     |    ❌    |    ✅     |
+| Has a specific recipient?           |     ❌     |    ✅    |    ❌     |
+| Is it a command?                    |     ❌     |    ✅    |    ❌     |
+| Is it an observable fact?           |   Maybe    |    ❌    |    ✅     |
+| Is it a global announcement?        |     ✅     |    ❌    |    ❌     |
+
+## Tokens and Lifecycle
+
+Registration in DxMessaging happens through tokens. A `MessageRegistrationToken` collects your registrations and ties them to a lifecycle.
+
+### The Pattern
+
+```csharp
+public class HealthDisplay : MessageAwareComponent
+{
+    protected override void RegisterMessageHandlers()
+    {
+        base.RegisterMessageHandlers();
+
+        // Register handlers through the Token
+        _ = Token.RegisterGameObjectBroadcast<TookDamage>(player, OnPlayerDamaged);
+        _ = Token.RegisterUntargeted<GamePaused>(OnGamePaused);
+    }
+
+    private void OnPlayerDamaged(ref TookDamage msg) { /* update display */ }
+    private void OnGamePaused(ref GamePaused msg) { /* pause animations */ }
+}
+```
+
+> ⚠️ **Warning: Always call `base.RegisterMessageHandlers()`**
+>
+> When overriding `RegisterMessageHandlers()`, always call `base.RegisterMessageHandlers()` first. This ensures that any registrations from parent classes are preserved. Forgetting this call can silently break inherited behavior.
+
+### What the Token Does
+
+```mermaid
+sequenceDiagram
+    participant C as Component
+    participant T as Token
+    participant B as MessageBus
+
+    Note over C,B: Awake
+    C->>T: Create Token
+    C->>T: Register handlers
+    T-->>T: Stage (not active yet)
+
+    Note over C,B: OnEnable
+    C->>T: Enable()
+    T->>B: Activate registrations
+
+    Note over C,B: Messages flow
+    B->>C: Handler called
+
+    Note over C,B: OnDisable
+    C->>T: Disable()
+    T->>B: Deactivate registrations
+
+    Note over C,B: OnDestroy
+    C->>T: Dispose/Release
+    T->>B: Remove registrations
+```
+
+The token:
+
+1. **Stages** registrations when you call `Register*` methods
+1. **Activates** them when you call `Enable()`
+1. **Deactivates** them when you call `Disable()`
+1. **Cleans up** when the token is disposed or the component is destroyed
+
+This maps directly to Unity's lifecycle: registrations activate in `OnEnable`, deactivate in `OnDisable`, and clean up in `OnDestroy`.
+
+### Why Tokens Matter
+
+Tokens prevent common event system bugs:
+
+- **No forgotten unsubscribes**: The token tracks everything
+- **No null reference handlers**: Disabled tokens don't receive messages
+- **No memory leaks**: Token cleanup is automatic with `MessageAwareComponent`
+- **Predictable timing**: Enable/disable follows Unity's enable state
+
+## Context Through Game Primitives
+
+DxMessaging uses Unity's primitives (GameObjects, Components) as natural context for messages.
+
+### InstanceId
+
+Every registration and emission uses an `InstanceId` - a lightweight identifier that wraps a Unity Object's instance ID. You rarely need to create these manually because extension methods handle the conversion:
+
+```csharp
+// These are equivalent:
+heal.EmitGameObjectTargeted(playerGameObject);
+heal.EmitTargeted((InstanceId)playerGameObject);
+
+// Registering for a specific component
+Token.RegisterComponentTargeted<Damage>(this, OnDamage);
+
+// Registering for a whole GameObject
+Token.RegisterGameObjectTargeted<Damage>(gameObject, OnDamage);
+```
+
+### GameObject vs Component Targeting
+
+You can target at two levels:
+
+**GameObject level**: All components on that GameObject can respond
+
+```csharp
+// Registration
+Token.RegisterGameObjectTargeted<Command>(gameObject, HandleCommand);
+
+// Emission (any component on playerGO can receive this)
+command.EmitGameObjectTargeted(playerGO);
+```
+
+**Component level**: Only that specific component responds
+
+```csharp
+// Registration
+Token.RegisterComponentTargeted<Command>(this, HandleCommand);
+
+// Emission (only this specific component instance receives this)
+command.EmitComponentTargeted(specificComponent);
+```
+
+## Observing Without Targeting
+
+Sometimes you want to see all messages of a type, regardless of their target or source.
+
+### Observing All Targeted Messages
+
+```csharp
+// See every Heal message, no matter who it's for
+Token.RegisterTargetedWithoutTargeting<Heal>(OnAnyHeal);
+
+void OnAnyHeal(ref InstanceId target, ref Heal msg)
+{
+    // 'target' tells you who was healed
+    Debug.Log($"Someone healed {target} for {msg.amount}");
+}
+```
+
+### Observing All Broadcast Messages
+
+```csharp
+// See every TookDamage message, no matter who broadcast it
+Token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyDamage);
+
+void OnAnyDamage(ref InstanceId source, ref TookDamage msg)
+{
+    // 'source' tells you who took damage
+    Debug.Log($"{source} took {msg.amount} damage");
+}
+```
+
+These patterns are useful for:
+
+- Analytics systems
+- Combat logs
+- Debug overlays
+- Achievement tracking
+- Network replication
+
+## The "Gets Out of the Way" Philosophy
+
+DxMessaging is designed to be invisible when you don't need it:
+
+1. **No global state pollution**: Messages are just data. Define them anywhere.
+1. **No inheritance requirements**: Implement an interface or add an attribute. That's it.
+1. **No framework lock-in**: Your message structs are plain C#. They work outside DxMessaging.
+1. **No ceremony**: Define a struct, emit it, handle it. Three steps.
+1. **Optional everywhere**: Don't want to use it for something? Don't. Mix and match.
+
+The library provides primitives. You compose them into patterns that fit your game.
+
+## Common Patterns at a Glance
+
+| Pattern               | Message Type | Registration                          | Emission                          |
+| --------------------- | ------------ | ------------------------------------- | --------------------------------- |
+| Global setting change | Untargeted   | `RegisterUntargeted<T>`               | `msg.EmitUntargeted()`            |
+| Command to entity     | Targeted     | `RegisterGameObjectTargeted<T>`       | `msg.EmitGameObjectTargeted(go)`  |
+| Something happened    | Broadcast    | `RegisterGameObjectBroadcast<T>`      | `msg.EmitGameObjectBroadcast(go)` |
+| Observe all of type   | Targeted     | `RegisterTargetedWithoutTargeting<T>` | (normal emission)                 |
+| Observe all sources   | Broadcast    | `RegisterBroadcastWithoutSource<T>`   | (normal emission)                 |
+
+## Common Mistakes
+
+When getting started with DxMessaging, watch out for these common pitfalls:
+
+### Forgetting to Enable the Token
+
+Registrations are **staged** when you call `Register*` methods, but they don't become active until the token is enabled. If you're using `MessageAwareComponent`, this is handled automatically. If managing tokens manually, remember to call `Token.Enable()` after registering.
+
+### Targeting Component When You Meant GameObject (or Vice Versa)
+
+Component-level targeting (`EmitComponentTargeted`) and GameObject-level targeting (`EmitGameObjectTargeted`) are distinct. A message emitted to a specific component won't be received by handlers registered at the GameObject level for the same object, and vice versa. Be deliberate about which level you're targeting.
+
+### Forgetting to Call `base.RegisterMessageHandlers()`
+
+See the warning in [The Pattern](#the-pattern) above. Always call the base method first when overriding `RegisterMessageHandlers()`.
+
+### Not Understanding Synchronous Handler Execution
+
+Message handlers are called **synchronously** and **immediately** when a message is emitted. This means:
+
+- The emitting code blocks until all handlers complete
+- Long-running handlers will cause frame hitches
+- Handlers execute in registration order (modified by priority)
+- Exceptions in handlers can affect other handlers if not caught
+
+Design your handlers to be fast and non-blocking.
+
+## Next Steps
+
+- [Message Types](message-types.md): Detailed reference for all three types
+- [Listening Patterns](listening-patterns.md): All the ways to receive messages
+- [Getting Started](../getting-started/getting-started.md): Hands-on walkthrough
+- [Patterns Guide](../guides/patterns.md): Real-world usage patterns

package/docs/concepts/mental-model.md.meta

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

package/docs/concepts/message-types.md

@@ -15,7 +15,6 @@ This guide introduces the three message categories in DxMessaging with concepts,
 ### Quick Decision Guide
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
 flowchart TD
     Start([Choose Message Type])
 

package/docs/getting-started/getting-started.md

@@ -182,6 +182,7 @@ Checklist:
 
 ## Next Steps
 
+- [Mental Model](../concepts/mental-model.md) - Understand the philosophy behind DxMessaging
 - [Visual Guide](visual-guide.md)
 - [Quick Reference](../reference/quick-reference.md)
 - [Diagnostics](../guides/diagnostics.md)

package/docs/getting-started/index.md

@@ -5,8 +5,7 @@ This is the documentation for DxMessaging, a type-safe messaging system for Unit
 ## Visual Documentation Map
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
-graph TD
+flowchart TD
     Start[START HERE<br/>Visual Guide<br/>5 minutes]
     Start --> Quick[Quick Start<br/>5 min]
     Start --> Getting[Getting Started<br/>10 min]
@@ -39,6 +38,7 @@ graph TD
 
 **Never used a messaging system before?** Start here:
 
+1. **[Mental Model](../concepts/mental-model.md)** - How to think about DxMessaging (10 min)
 1. **[Visual Guide](visual-guide.md)** - Beginner-friendly visual introduction (5 min)
 1. **[Getting Started Guide](getting-started.md)** - Comprehensive guide with examples (10 min)
 1. **[Quick Start](quick-start.md)** - Your first working message (5 min)
@@ -48,6 +48,7 @@ graph TD
 
 ### For Absolute Beginners (Never Used Messaging Before)
 
+1. Read [Mental Model](../concepts/mental-model.md) (10 min) - Philosophy first!
 1. Read [Visual Guide](visual-guide.md) (5 min) - Pictures and analogies!
 1. Read [Getting Started](getting-started.md) (10 min) - Complete introduction
 1. Try [Quick Start](quick-start.md) (5 min) - Hands-on tutorial
@@ -166,7 +167,6 @@ From [Common Patterns](../guides/patterns.md):
 Every message flows through 3 stages:
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
 flowchart LR
     P[Producer] --> I[Interceptors<br/>validate/mutate/cancel]
     I --> H[Handlers<br/>main logic by priority]
@@ -298,9 +298,10 @@ From [Comparisons](../architecture/comparisons.md):
 
 ## Quick Start Path
 
-**Absolute Beginner?** Follow this 30-minute path:
+**Absolute Beginner?** Follow this 40-minute path:
 
-1. 5 min: [Visual Guide](visual-guide.md) - Start here for pictures & analogies!
+1. 10 min: [Mental Model](../concepts/mental-model.md) - Understand the philosophy first!
+1. 5 min: [Visual Guide](visual-guide.md) - Pictures & analogies
 1. 10 min: [Getting Started](getting-started.md) - Deep dive
 1. 5 min: [Quick Start](quick-start.md) - Hands-on code
 1. 10 min: Try a [Sample](https://github.com/wallstop/DxMessaging/blob/master/Samples~/Mini%20Combat/README.md) - See it in action

package/docs/getting-started/overview.md

@@ -142,6 +142,7 @@ _ = Token.RegisterBroadcastWithoutSource<TookDamage>(
 
 ### Start Here
 
+- -> [Mental Model](../concepts/mental-model.md) (10 min) - Philosophy and first principles
 - -> [Visual Guide](visual-guide.md) (5 min) - Beginner-friendly introduction
 - -> [Getting Started](getting-started.md) (10 min) - Complete guide
 - -> [Quick Start](quick-start.md) (5 min) - Working example

package/docs/getting-started/quick-start.md

@@ -143,7 +143,8 @@ Registration cleanup is automatic. Messages are type-safe.
 ## Next Steps
 
 - **Understand What You Did**
-  - -> [Getting Started Guide](getting-started.md) (10 min) - Full explanation with mental models
+  - -> [Mental Model](../concepts/mental-model.md) (10 min) - Philosophy and first principles
+  - -> [Getting Started Guide](getting-started.md) (10 min) - Full explanation with examples
   - -> [Visual Guide](visual-guide.md) (5 min) - Pictures and analogies
 - **Try Real Examples**
   - -> [Mini Combat sample](https://github.com/wallstop/DxMessaging/blob/master/Samples~/Mini%20Combat/README.md) - Working combat example

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

@@ -7,8 +7,7 @@ If you're brand new to messaging systems, this visual guide will help you unders
 ### The Old Way (Spaghetti Code)
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
-graph LR
+flowchart LR
     Player[Player]
     Enemy[Enemy]
     Inventory[Inventory]
@@ -36,8 +35,7 @@ graph LR
 ### The DxMessaging Way (Clean Separation)
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
-graph TB
+flowchart TB
     Player[Player]
     Enemy[Enemy]
     Inventory[Inventory]
@@ -152,7 +150,6 @@ _ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyEnemy);
 When you send a message, here's what happens:
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
 sequenceDiagram
     participant You as Your Code
     participant Msg as Message
@@ -268,7 +265,6 @@ healMsg.EmitComponentTargeted(playerComponent);
 ### Pattern: Scene Transition
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
 sequenceDiagram
     participant SM as SceneManager
     participant Bus as Message Bus
@@ -311,7 +307,6 @@ _ = saveToken.RegisterUntargeted<SceneChanged>(OnScene);
 ### Pattern: Player Input -> Action
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
 sequenceDiagram
     participant Input as InputSystem
     participant Bus as Message Bus
@@ -349,7 +344,6 @@ void OnJump(ref Jump msg) {
 ### Pattern: Achievement Tracking
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
 sequenceDiagram
     participant E as Enemy
     participant P as Player
@@ -472,8 +466,7 @@ DxMessaging has built-in Inspector support!
 ## Learning Path
 
 ```mermaid
-%%{init: {'theme': 'neutral'}}%%
-graph TD
+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!]
@@ -601,6 +594,7 @@ If you checked all these, you are following best practices.
 
 Ready to dive deeper?
 
+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

package/docs/hooks.py

@@ -28,11 +28,20 @@ SOURCE_PREFIXES = ("Runtime/", "Tests/", "Editor/", "Samples~/")
 MARKDOWN_LINK_PATTERN = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
 
 # Regex to match fenced code blocks (``` or ~~~ with optional language specifier)
-# Uses DOTALL to match across newlines
+# 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)
 
 

package/docs/images/DxMessaging-banner.svg

@@ -107,7 +107,7 @@
   <!-- Version badge (top right) - text must contain vX.Y.Z for version sync -->
   <g transform="translate(720, 25)">
     <rect x="0" y="-12" width="60" height="22" rx="11" fill="#e94560" filter="url(#softShadow)"/>
-    <text x="30" y="4" text-anchor="middle" font-family="'SF Mono', 'Fira Code', monospace" font-size="12" font-weight="600" fill="#ffffff" letter-spacing="0.5">v2.1.5</text>
+    <text x="30" y="4" text-anchor="middle" font-family="'SF Mono', 'Fira Code', monospace" font-size="12" font-weight="600" fill="#ffffff" letter-spacing="0.5">v2.1.7</text>
   </g>
   
   <!-- Wallstop Studios branding (bottom right) -->

package/docs/index.md

@@ -7,19 +7,19 @@ description: High-performance type-safe messaging library for Unity
 
 **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 }
+**[Get Started](getting-started/index.md)** | [View on GitHub](https://github.com/wallstop/DxMessaging)
 
 ## 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
+- ⚡ **High Performance** — Zero-allocation message dispatch with pooled handlers
+- 🛡️ **Type-Safe** — Compile-time message type checking prevents runtime errors
+- 📦 **Decoupled Architecture** — Components communicate without direct references
+- 🎯 **Flexible Targeting** — Untargeted, Targeted, and Broadcast message patterns
+- 🔧 **Unity-Native** — Built specifically for Unity with MonoBehaviour integration
 
 ## Quick Links
 
+- **[Mental Model](concepts/mental-model.md)** — How to think about DxMessaging
 - **[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