Document multiphase animation test activation

docs/window-animations-testing.md

@@ -35,6 +35,49 @@ Current curve IDs in code:
 - `3` or any other unrecognized value: CSS `ease-out`
 - `4`: CSS `ease-in-out`
 
+## Enabling Multiphase Tests
+
+There is currently no separate user-facing multiphase toggle. To exercise the
+multiphase planner:
+
+1. Enable animations with `SetAnimationsEnabled`.
+2. Set a slow duration with `SetAnimationDurationMs`, around `400-700ms`.
+3. Use tiled layout commands that are wired through `State::with_layout_animations`.
+4. Use layouts where at least two tiled windows change geometry in the same
+   container layout batch.
+
+The compositor then attempts multiphase planning automatically when the batched
+layout pass completes. If the planner proves a legal no-overlap sequence, that
+group uses phased animation. If it cannot prove one, only that motion group falls
+back to ordinary linear animation.
+
+Good command families for multiphase testing:
+
+- seat/window move in a tiled direction
+- split changes
+- tab/group operations
+- group-opposite changes
+- equalize
+- move-tab
+- mono enter/exit
+- command-driven window resize
+
+These paths should not be used as evidence of multiphase behavior:
+
+- tile-to-float and float-to-tile, which deliberately use linear animation
+- command-driven floating move/resize, which may animate but can overlap
+- pointer or tablet drag/resize, which should not animate
+- spawn-in and spawn-out, which are always linear
+- cross-output or cross-scale movement, which should snap
+- layer-shell, overlay, override-redirect, and fullscreen map/unmap paths
+
+Useful debug signal:
+
+- `falling back to linear layout animation for group ...` means the group entered
+  the multiphase gate but the planner rejected it. That is acceptable for
+  unsupported patterns, but unexpected for the supported swap/extraction cases
+  below.
+
 ## Pass Criteria
 
 A test passes when: