refactor: decompose Renderer2D and optimize RenderBuffer2D sort (#7)

* refactor: decompose Renderer2D and optimize RenderBuffer2D sort

* fix: stable sort and clearArray in RenderBuffer2D

- Pack (layer << 32) | index into int64 keys for stable sort
- Add clearArray=true when returning items to ArrayPool
- Update stability test with 20-item input (would fail with unstable sort)

Author: AngelMunoz

CHANGELOG.md

@@ -25,6 +25,8 @@
 - **Breaking:** `LitSprite` command signature changed — now carries `LightContext2D * SpriteState` instead of 8 individual fields. Consumers must update pattern matches and `LightDraw.litSprite` call sites to use the new `SpriteState` type.
 - **Breaking:** `IRenderPipeline3D.Execute` signature changed from curried (`gameCtx -> buffer -> rtPool -> unit`) to tupled (`gameCtx * buffer * rtPool -> unit`). All implementations and call sites must update.
 - `SpriteState` moved from `Command2D` module to top-level `Mibo.Elmish.Graphics2D` namespace.
+- `Renderer2D` refactored: extracted command dispatch into `module private CommandHandlers` with `RendererState` struct threaded `byref`. Post-processing extracted into `PostProcess2D` module. Class reduced from ~530 LOC to ~60 LOC of orchestration.
+- `RenderBuffer2D.Sort` optimized: layer keys are now precomputed during `Add` (O(n) pattern matches) and sort uses `Array.Sort(keys, items, ...)` with primitive int comparisons, eliminating O(n log n) repeated pattern matching over the 37-case `Command2D` union. Sort is now stable — same-layer commands preserve insertion order via packed `int64` keys (layer in high 32 bits, insertion index in low 32 bits).
 - Shadow rendering: `collectMeshDraws` now partitions draws (non-skinned first, skinned second) to minimize shader switches in the shadow pass.
 - Shadow rendering: `renderShadowRegion` skips `computeNormalMatrix` and `SetShaderValueMatrix` when consecutive meshes share the same transform.
 - Removed `lightsDirty` class field from `ForwardPbrPipeline`; handlers now check only `ShaderVariant.LightsDirty`. `handleLightCommand` sets all three variants' dirty flags directly.

src/Mibo.Raylib.Tests/Graphics2DTests.fs

@@ -840,34 +840,26 @@ let renderBuffer2DTests =
     test "Sort preserves insertion order for same layer" {
       let buf = RenderBuffer2D()
 
-      let cmdA =
-        Command2D.fillCircle
-          (5<RenderLayer>, Color.Red)
-          (Vector2(1.0f, 0.0f), 10.0f)
-
-      let cmdB =
-        Command2D.fillCircle
-          (5<RenderLayer>, Color.Blue)
-          (Vector2(2.0f, 0.0f), 10.0f)
-
-      let cmdC =
-        Command2D.fillCircle
-          (5<RenderLayer>, Color.Green)
-          (Vector2(3.0f, 0.0f), 10.0f)
-
-      buf.Add(cmdA)
-      buf.Add(cmdB)
-      buf.Add(cmdC)
+      // Use enough items on the same layer that an unstable sort would
+      // reorder them — 3 items is too few to trigger swaps in most algorithms.
+      let colors = [|
+        for i in 0..19 -> Color(byte i, byte(i * 10), 0uy, 255uy)
+      |]
+
+      for c in colors do
+        buf.Add(
+          Command2D.fillCircle
+            (5<RenderLayer>, c)
+            (Vector2(float32 c.R, 0.0f), 10.0f)
+        )
+
       buf.Sort()
 
-      match buf.Item 0, buf.Item 1, buf.Item 2 with
-      | Command2D.FillCircle(_, _, c1, _),
-        Command2D.FillCircle(_, _, c2, _),
-        Command2D.FillCircle(_, _, c3, _) ->
-        Expect.equal c1 Color.Red "First should be Red"
-        Expect.equal c2 Color.Blue "Second should be Blue"
-        Expect.equal c3 Color.Green "Third should be Green"
-      | _ -> Tests.failtest "Expected FillCircle commands"
+      for i = 0 to colors.Length - 1 do
+        match buf.Item i with
+        | Command2D.FillCircle(_, _, c, _) ->
+          Expect.equal c colors[i] $"Item {i} should match insertion order"
+        | _ -> Tests.failtest "Expected FillCircle"
     }
 
     test "Buffer expands capacity when full" {

src/Mibo.Raylib/Graphics2D/RenderBuffer.fs

@@ -2,7 +2,6 @@ namespace Mibo.Elmish.Graphics2D
 
 open System
 open System.Buffers
-open System.Collections.Generic
 
 /// <summary>
 /// An allocation-free buffer for 2D render commands, sorted by layer.
@@ -22,8 +21,9 @@ type RenderBuffer2D
   /// <summary>Initial capacity. Defaults to 1024 if not specified.</summary>
   ?capacity: int) =
 
-  let mutable items = ArrayPool<Command2D>.Shared.Rent(defaultArg capacity 1024)
-
+  let initialCapacity = defaultArg capacity 1024
+  let mutable items = ArrayPool<Command2D>.Shared.Rent(initialCapacity)
+  let mutable keys = ArrayPool<int64>.Shared.Rent(initialCapacity)
   let mutable count = 0
 
   let getLayer(cmd: Command2D) =
@@ -76,20 +76,19 @@ type RenderBuffer2D
     | Command2D.DisableShadows(_, layer) -> layer
     | Command2D.Particle(_, _, _, layer) -> layer
 
-  let layerComparer =
-    { new IComparer<Command2D> with
-        member _.Compare(a, b) = int(getLayer a) - int(getLayer b)
-    }
-
   let ensureCapacity(needed: int) =
     if count + needed > items.Length then
       let newSize = max (items.Length * 2) (count + needed)
 
-      let newArr = ArrayPool<Command2D>.Shared.Rent(newSize)
+      let newItems = ArrayPool<Command2D>.Shared.Rent(newSize)
+      let newKeys = ArrayPool<int64>.Shared.Rent(newSize)
 
-      Array.Copy(items, newArr, count)
-      ArrayPool<Command2D>.Shared.Return(items)
-      items <- newArr
+      Array.Copy(items, newItems, count)
+      Array.Copy(keys, newKeys, count)
+      ArrayPool<Command2D>.Shared.Return(items, true)
+      ArrayPool<int64>.Shared.Return(keys)
+      items <- newItems
+      keys <- newKeys
 
   /// <summary>The number of commands currently in the buffer.</summary>
   member _.Count = count
@@ -101,6 +100,7 @@ type RenderBuffer2D
   member _.Add(cmd: Command2D) =
     ensureCapacity 1
     items[count] <- cmd
+    keys[count] <- (int64(int(getLayer cmd)) <<< 32) ||| int64 count
     count <- count + 1
 
   /// <summary>
@@ -110,9 +110,10 @@ type RenderBuffer2D
   member _.Clear() = count <- 0
 
   /// <summary>
-  /// Sorts commands by layer in ascending order.
+  /// Sorts commands by layer in ascending order, preserving insertion order for same-layer commands.
+  /// Uses precomputed int64 keys (layer in high 32 bits, insertion index in low 32 bits) to avoid
+  /// repeated pattern matching during comparisons and guarantee stable sort.
   /// Must be called after <see cref="M:Mibo.Elmish.Graphics2D.RenderBuffer2D.Clear"/>
   /// and population, before iteration.
   /// </summary>
-  member _.Sort() =
-    Array.Sort(items, 0, count, layerComparer)
+  member _.Sort() = Array.Sort(keys, items, 0, count)