com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

package/.llm/skills/solid/collection-extensions-shuffle.md

@@ -0,0 +1,144 @@
+---
+title: "Collection Extensions: Shuffle"
+id: "collection-extensions-shuffle"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Extension/CollectionExtensions.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "collections"
+  - "shuffle"
+  - "fisher-yates"
+  - "performance"
+
+complexity:
+  level: "basic"
+  reasoning: "Uses a standard in-place shuffle algorithm"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "O(n) in-place shuffle with no allocations"
+  maintainability:
+    rating: "medium"
+    details: "Small helper with clear API"
+  testability:
+    rating: "high"
+    details: "Deterministic with injected Random"
+
+prerequisites:
+  - "Understanding of list indexing"
+
+dependencies:
+  packages: []
+  skills:
+    - "collection-extensions"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Fisher-Yates shuffle"
+
+related:
+  - "collection-extensions"
+  - "collection-extensions-accessors"
+
+status: "stable"
+---
+
+# Collection Extensions: Shuffle
+
+> **One-line summary**: Shuffle lists in-place using Fisher-Yates with optional deterministic Random.
+
+## Overview
+
+Shuffling is a common utility. The Fisher-Yates algorithm provides an unbiased, in-place shuffle in O(n) time.
+
+## Problem Statement
+
+Naive shuffle implementations introduce bias or allocate intermediate lists.
+
+## Solution
+
+### Implementation
+
+```csharp
+public static class ListExtensions
+{
+    public static void Shuffle<T>(this IList<T> list)
+    {
+        if (list == null)
+        {
+            throw new ArgumentNullException(nameof(list));
+        }
+
+        int n = list.Count;
+        while (n > 1)
+        {
+            n--;
+            int k = UnityEngine.Random.Range(0, n + 1);
+            T temp = list[k];
+            list[k] = list[n];
+            list[n] = temp;
+        }
+    }
+
+    public static void Shuffle<T>(this IList<T> list, System.Random random)
+    {
+        if (list == null)
+        {
+            throw new ArgumentNullException(nameof(list));
+        }
+
+        if (random == null)
+        {
+            throw new ArgumentNullException(nameof(random));
+        }
+
+        int n = list.Count;
+        while (n > 1)
+        {
+            n--;
+            int k = random.Next(n + 1);
+            T temp = list[k];
+            list[k] = list[n];
+            list[n] = temp;
+        }
+    }
+}
+```
+
+## Usage Example
+
+```csharp
+List<int> cards = BuildDeck();
+cards.Shuffle();
+```
+
+## Testing Considerations
+
+- Inject `System.Random` to make shuffle deterministic in tests
+- Assert on permutations by comparing sorted sequences
+
+## See Also
+
+- [Collection Extension Methods](collection-extensions.md)
+- [Collection Extensions: Accessors](collection-extensions-accessors.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |

package/.llm/skills/solid/collection-extensions-type-specialization.md

@@ -0,0 +1,168 @@
+---
+title: "Collection Extensions: Type Specialization"
+id: "collection-extensions-type-specialization"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Extension/CollectionExtensions.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "collections"
+  - "extensions"
+  - "performance"
+  - "type-specialization"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of interface dispatch and concrete-type fast paths"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Avoids interface dispatch overhead in hot paths"
+  maintainability:
+    rating: "medium"
+    details: "Adds branching but keeps a single API surface"
+  testability:
+    rating: "high"
+    details: "Behavior is deterministic across implementations"
+
+prerequisites:
+  - "Knowledge of collection interfaces"
+
+dependencies:
+  packages: []
+  skills:
+    - "collection-extensions"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Fast path overloads"
+
+related:
+  - "collection-extensions"
+  - "collection-extensions-accessors"
+
+status: "stable"
+---
+
+# Collection Extensions: Type Specialization
+
+> **One-line summary**: Use concrete-type fast paths to avoid interface dispatch overhead for hot collection operations.
+
+## Overview
+
+Interface calls are slower than direct calls. When collections are commonly `T[]` or `List<T>`, add specialized branches to avoid interface dispatch.
+
+## Problem Statement
+
+Generic `IReadOnlyList<T>` access is flexible but introduces virtual dispatch overhead on every access.
+
+## Solution
+
+### Core Concept
+
+Provide fast paths for common concrete types, with a generic fallback.
+
+### Implementation
+
+```csharp
+public static class CollectionExtensions
+{
+    public static int BinarySearch<T>(this IReadOnlyList<T> list, T value)
+        where T : IComparable<T>
+    {
+        if (list is T[] array)
+        {
+            return Array.BinarySearch(array, value);
+        }
+
+        if (list is List<T> concreteList)
+        {
+            return concreteList.BinarySearch(value);
+        }
+
+        return BinarySearchGeneric(list, value);
+    }
+
+    private static int BinarySearchGeneric<T>(IReadOnlyList<T> list, T value)
+        where T : IComparable<T>
+    {
+        int low = 0;
+        int high = list.Count - 1;
+
+        while (low <= high)
+        {
+            int mid = low + ((high - low) >> 1);
+            int comparison = list[mid].CompareTo(value);
+
+            if (comparison == 0)
+            {
+                return mid;
+            }
+            if (comparison < 0)
+            {
+                low = mid + 1;
+            }
+            else
+            {
+                high = mid - 1;
+            }
+        }
+
+        return ~low;
+    }
+}
+```
+
+## Performance Notes
+
+```csharp
+// Interface call: ~5ns overhead per call
+IReadOnlyList<int> list = myList;
+int first = list[0];
+
+// Direct call: ~0.5ns
+List<int> concreteList = myList;
+int firstConcrete = concreteList[0];
+```
+
+## Usage Example
+
+```csharp
+List<int> sortedList = GetSortedScores();
+int index = sortedList.BinarySearch(targetScore);
+
+if (index >= 0)
+{
+    Debug.Log($"Found at index {index}");
+}
+else
+{
+    int insertionPoint = ~index;
+    Debug.Log($"Would insert at index {insertionPoint}");
+}
+```
+
+## See Also
+
+- [Collection Extension Methods](collection-extensions.md)
+- [Collection Extensions: Accessors](collection-extensions-accessors.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |

package/.llm/skills/solid/collection-extensions.md

@@ -0,0 +1,144 @@
+---
+title: "Collection Extension Methods with Performance Documentation"
+id: "collection-extensions"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Extension/IReadonlyListExtensions.cs"
+      lines: "1-689"
+    - path: "Runtime/Core/Extension/CollectionExtensions.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "extensions"
+  - "collections"
+  - "dry"
+  - "documentation"
+  - "performance"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of extension methods and interface design"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Type-specialized implementations avoid interface dispatch overhead"
+  maintainability:
+    rating: "high"
+    details: "Consistent API across collection types"
+  testability:
+    rating: "high"
+    details: "Pure functions are easy to test"
+
+prerequisites:
+  - "Understanding of extension methods"
+  - "Knowledge of collection interfaces"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "IEnumerable extensions"
+  - "List extensions"
+  - "LINQ alternatives"
+
+related:
+  - "try-pattern-apis"
+  - "fluent-builder-pattern"
+  - "collection-extensions-accessors"
+  - "collection-extensions-type-specialization"
+  - "collection-extensions-shuffle"
+
+status: "stable"
+---
+
+# Collection Extension Methods with Performance Documentation
+
+> **One-line summary**: Create collection extension methods with explicit performance documentation and type-specialized overloads.
+
+## Overview
+
+Extension methods provide a fluent, discoverable API for collection operations. This pattern focuses on:
+
+1. **Performance documentation** in XML comments
+1. **Type-specialized implementations** for common collection types
+1. **Try-pattern APIs** for safe access
+1. **Zero-allocation** implementations where possible
+
+## Problem Statement
+
+```csharp
+// BAD: LINQ allocates iterators
+var first = list.FirstOrDefault(); // Allocates IEnumerator
+
+// BAD: No documentation about performance
+public static T GetRandom<T>(this IList<T> list)
+{
+    return list[Random.Range(0, list.Count)];
+}
+```
+
+## Solution
+
+### Core Pattern: Documented Extension Methods
+
+Use XML remarks to capture complexity, allocations, and thread safety:
+
+```csharp
+/// <summary>
+/// Brief description.
+/// </summary>
+/// <remarks>
+/// <para>Performance: O(?) where ? is...</para>
+/// <para>Allocations: No allocations / Allocates X bytes.</para>
+/// <para>Thread Safety: Thread-safe / Not thread-safe.</para>
+/// </remarks>
+```
+
+## Best Practices
+
+### Do
+
+- Document performance in XML comments
+- Provide type-specialized overloads for hot paths
+- Use Try-pattern for operations that can fail
+- Throw on null with clear parameter names
+- Use `[MethodImpl(MethodImplOptions.AggressiveInlining)]` for tiny methods
+
+### Don't
+
+- Don't hide allocations (document them)
+- Don't use LINQ in hot paths (allocates iterators)
+- Don't forget null checks
+- Don't assume interface performance equals concrete type performance
+
+## See Also
+
+- [Collection Extensions: Accessors](collection-extensions-accessors.md)
+- [Collection Extensions: Type Specialization](collection-extensions-type-specialization.md)
+- [Collection Extensions: Shuffle](collection-extensions-shuffle.md)
+- [Try-Pattern APIs](./try-pattern-apis.md)
+- [Fluent Builder Pattern](./fluent-builder-pattern.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |

package/.llm/skills/solid/fluent-builder-pattern-templates.md

@@ -0,0 +1,117 @@
+---
+title: "Fluent Builder Templates and Factories"
+id: "fluent-builder-pattern-templates"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Builders/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "patterns"
+  - "builder"
+  - "fluent-api"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Builds on fluent builder structure with reusable templates"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Struct builders minimize allocations"
+  maintainability:
+    rating: "high"
+    details: "Templates standardize builder APIs"
+  testability:
+    rating: "high"
+    details: "Builder validation can be unit-tested"
+
+prerequisites:
+  - "Understanding of fluent builders"
+
+dependencies:
+  packages: []
+  skills:
+    - "fluent-builder-pattern"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Builder templates"
+
+related:
+  - "fluent-builder-pattern"
+
+status: "stable"
+---
+
+# Fluent Builder Templates and Factories
+
+> **One-line summary**: Static factory entry points and reusable builder templates.
+
+## Overview
+
+This skill provides reusable templates and entry points for builders.
+
+## Solution
+
+Use these templates to standardize fluent builder APIs.
+
+### Static Factory Entry Point
+
+```csharp
+/// <summary>
+/// Entry point for cache creation.
+/// </summary>
+public static class Cache
+{
+    /// <summary>
+    /// Creates a new cache builder.
+    /// </summary>
+    public static CacheBuilder<TKey, TValue> Builder<TKey, TValue>()
+    {
+        return new CacheBuilder<TKey, TValue>();
+    }
+}
+```
+
+### Generic Builder Template
+
+```csharp
+/// <summary>
+/// Template for struct-based builders.
+/// </summary>
+public struct ObjectBuilder<T> where T : class, new()
+{
+    private T prototype;
+
+    private T GetOrCreatePrototype()
+    {
+        return prototype ?? (prototype = new T());
+    }
+
+    public ObjectBuilder<T> With(Action<T> configure)
+    {
+        var copy = this;
+        configure(copy.GetOrCreatePrototype());
+        return copy;
+    }
+
+    public T Build()
+    {
+        return prototype ?? new T();
+    }
+}
+```

package/.llm/skills/solid/fluent-builder-pattern-usage-examples.md

@@ -0,0 +1,128 @@
+---
+title: "Fluent Builder Usage Examples"
+id: "fluent-builder-pattern-usage-examples"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Builders/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "patterns"
+  - "builder"
+  - "fluent-api"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Builds on fluent builder structure with reusable templates"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Struct builders minimize allocations"
+  maintainability:
+    rating: "high"
+    details: "Templates standardize builder APIs"
+  testability:
+    rating: "high"
+    details: "Builder validation can be unit-tested"
+
+prerequisites:
+  - "Understanding of fluent builders"
+
+dependencies:
+  packages: []
+  skills:
+    - "fluent-builder-pattern"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Builder templates"
+
+related:
+  - "fluent-builder-pattern"
+
+status: "stable"
+---
+
+# Fluent Builder Usage Examples
+
+> **One-line summary**: Usage patterns for builder configuration and validation.
+
+## Overview
+
+This skill covers usage patterns for fluent builders and validation.
+
+## Solution
+
+Use the examples below to configure and validate builders.
+
+## Usage
+
+### Basic Builder Usage
+
+```csharp
+// Clear, self-documenting configuration
+using Cache<string, GameData> cache = new CacheBuilder<string, GameData>()
+    .WithMaximumSize(1000)
+    .WithPolicy(EvictionPolicy.Lru)
+    .WithExpireAfterWrite(TimeSpan.FromMinutes(5))
+    .WithExpireAfterAccess(TimeSpan.FromMinutes(1))
+    .WithRecordStats()
+    .Build();
+```
+
+### Using Static Factory
+
+```csharp
+using var cache = Cache.Builder<string, int>()
+    .WithMaximumSize(500)
+    .Build();
+```
+
+### Partial Configuration
+
+```csharp
+// Store partial configuration for reuse
+CacheBuilder<string, PlayerData> baseBuilder = new CacheBuilder<string, PlayerData>()
+    .WithMaximumSize(1000)
+    .WithPolicy(EvictionPolicy.Lru);
+
+// Extend for different use cases
+using var shortLivedCache = baseBuilder
+    .WithExpireAfterWrite(TimeSpan.FromMinutes(1))
+    .Build();
+
+using var longLivedCache = baseBuilder
+    .WithExpireAfterWrite(TimeSpan.FromHours(1))
+    .WithRecordStats()
+    .Build();
+```
+
+### With Validation
+
+```csharp
+// Invalid configuration fails at Build() time
+try
+{
+    var cache = new CacheBuilder<string, int>()
+        .WithExpirationJitter(0.1f) // Jitter without expiration!
+        .Build();
+}
+catch (InvalidOperationException ex)
+{
+    Debug.Log(ex.Message); // "Jitter requires expiration to be set..."
+}
+```