feat(ui): centralize retained window lifecycle

src/AcDream.App/UI/IRetainedPanelController.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace AcDream.App.UI;
+
+/// <summary>
+/// Lifecycle contract for a controller attached to a retained retail window.
+/// Implementations own panel-specific subscriptions and reactions; the window
+/// manager owns visibility, focus, capture, geometry, and teardown ordering.
+/// </summary>
+public interface IRetainedPanelController : IDisposable
+{
+    /// <summary>Called once for each hidden-to-shown transition.</summary>
+    void OnShown();
+
+    /// <summary>Called once for each shown-to-hidden transition.</summary>
+    void OnHidden();
+
+    /// <summary>
+    /// Called when keyboard focus enters, leaves, or moves within this window.
+    /// <paramref name="focusedDescendant"/> is null when focus left the window.
+    /// Controllers that do not react to focus may use this default no-op.
+    /// </summary>
+    void OnDescendantFocusChanged(UiElement? focusedDescendant) { }
+}