feat(G.3a): TeleportArrivalController hold-until-hydration state machine (#133)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/AcDream.App.Tests/World/TeleportArrivalControllerTests.cs

@@ -0,0 +1,123 @@
+using System.Collections.Generic;
+using System.Numerics;
+using AcDream.App.World;
+using Xunit;
+
+namespace AcDream.App.Tests.World;
+
+public class TeleportArrivalControllerTests
+{
+    // Records each Place(destPos, destCell, forced) call.
+    private sealed record PlaceCall(Vector3 Pos, uint Cell, bool Forced);
+
+    private static TeleportArrivalController Make(
+        ArrivalReadiness verdict,
+        List<PlaceCall> placed,
+        int maxHoldFrames = TeleportArrivalController.DefaultMaxHoldFrames)
+        => new(
+            readiness: (_, _) => verdict,
+            place: (pos, cell, forced) => placed.Add(new PlaceCall(pos, cell, forced)),
+            maxHoldFrames: maxHoldFrames);
+
+    [Fact]
+    public void BeginArrival_EntersHolding()
+    {
+        var placed = new List<PlaceCall>();
+        var c = Make(ArrivalReadiness.NotReady, placed);
+
+        c.BeginArrival(new Vector3(1, 2, 3), 0x01250126u);
+
+        Assert.Equal(TeleportArrivalPhase.Holding, c.Phase);
+        Assert.Empty(placed);
+    }
+
+    [Fact]
+    public void Tick_WhenIdle_IsNoOp()
+    {
+        var placed = new List<PlaceCall>();
+        var c = Make(ArrivalReadiness.Ready, placed);
+
+        c.Tick(); // never began
+
+        Assert.Equal(TeleportArrivalPhase.Idle, c.Phase);
+        Assert.Empty(placed);
+    }
+
+    [Fact]
+    public void Tick_NotReady_KeepsHolding_DoesNotPlace()
+    {
+        var placed = new List<PlaceCall>();
+        var c = Make(ArrivalReadiness.NotReady, placed);
+        c.BeginArrival(new Vector3(1, 2, 3), 0x01250126u);
+
+        c.Tick();
+        c.Tick();
+
+        Assert.Equal(TeleportArrivalPhase.Holding, c.Phase);
+        Assert.Empty(placed);
+    }
+
+    [Fact]
+    public void Tick_Ready_PlacesUnforced_AndIdles()
+    {
+        var placed = new List<PlaceCall>();
+        var c = Make(ArrivalReadiness.Ready, placed);
+        c.BeginArrival(new Vector3(30, -60, 6.005f), 0x01250126u);
+
+        c.Tick();
+
+        Assert.Equal(TeleportArrivalPhase.Idle, c.Phase);
+        var call = Assert.Single(placed);
+        Assert.False(call.Forced);
+        Assert.Equal(0x01250126u, call.Cell);
+        Assert.Equal(new Vector3(30, -60, 6.005f), call.Pos);
+    }
+
+    [Fact]
+    public void Tick_Impossible_PlacesForced_AndIdles()
+    {
+        var placed = new List<PlaceCall>();
+        var c = Make(ArrivalReadiness.Impossible, placed);
+        c.BeginArrival(new Vector3(1, 2, 3), 0x0125FF00u);
+
+        c.Tick();
+
+        Assert.Equal(TeleportArrivalPhase.Idle, c.Phase);
+        var call = Assert.Single(placed);
+        Assert.True(call.Forced);
+    }
+
+    [Fact]
+    public void Tick_Timeout_PlacesForced_AfterMaxHoldFrames()
+    {
+        var placed = new List<PlaceCall>();
+        var c = Make(ArrivalReadiness.NotReady, placed, maxHoldFrames: 3);
+        c.BeginArrival(new Vector3(1, 2, 3), 0x01250126u);
+
+        c.Tick(); // 1
+        c.Tick(); // 2
+        Assert.Empty(placed);
+        Assert.Equal(TeleportArrivalPhase.Holding, c.Phase);
+
+        c.Tick(); // 3 -> timeout
+
+        var call = Assert.Single(placed);
+        Assert.True(call.Forced);
+        Assert.Equal(TeleportArrivalPhase.Idle, c.Phase);
+    }
+
+    [Fact]
+    public void BeginArrival_AfterPlace_ReArms()
+    {
+        var placed = new List<PlaceCall>();
+        var c = Make(ArrivalReadiness.Ready, placed);
+
+        c.BeginArrival(new Vector3(1, 0, 0), 0x01250126u);
+        c.Tick(); // places #1, idle
+        c.BeginArrival(new Vector3(2, 0, 0), 0x01250127u);
+        c.Tick(); // places #2, idle
+
+        Assert.Equal(2, placed.Count);
+        Assert.Equal(0x01250127u, placed[1].Cell);
+    }
+}