fix(tutorial): preserve click targets across UI transitions

Runtime/Core/ShrinkTutorialManager.cs

@@ -15,6 +15,12 @@ namespace ShrinkTutorial
 
         [SerializeField] private ShrinkTutorialSettings settingsOverride;
 
+        [Header("Explicit scene UI")]
+        [SerializeField] private Canvas canvasOverride;
+        [SerializeField] private ShrinkTutorialMask maskOverride;
+        [SerializeField] private ShrinkTutorialDialog dialogOverride;
+        [SerializeField] private bool allowRuntimeUiFallback = true;
+
         private readonly List<string> _pendingTutorialIds = new();
         private readonly HashSet<string> _completedTutorials = new();
         private readonly HashSet<string> _skippedTutorials = new();
@@ -32,6 +38,11 @@ namespace ShrinkTutorial
         private bool _skipRequested;
         private bool _stepCompleted;
         private bool _stepCompletionQueued;
+        private bool _clickTargetArmed;
+        private Rect _clickTargetArmedRect;
+        private ShrinkTutorialMaskShape _clickTargetArmedShape;
+        private int _clickTargetArmedFrame;
+        private bool _clickTargetArmedWithTouch;
         private float _stepAutoTimer;
         private string _receivedCustomEvent = string.Empty;
 
@@ -202,6 +213,7 @@ namespace ShrinkTutorial
                 _skipRequested = false;
                 _stepCompleted = false;
                 _stepCompletionQueued = false;
+                _clickTargetArmed = false;
                 _stepAutoTimer = tutorial.steps[stepIndex].autoDelay;
                 _receivedCustomEvent = string.Empty;
 
@@ -298,16 +310,7 @@ namespace ShrinkTutorial
                     }
                     break;
                 case ShrinkTutorialCompleteCondition.ClickTarget:
-                    if (targetTransform &&
-                        ShrinkTutorialTargetUtility.TryBuildScreenRect(targetTransform, out var targetRect) &&
-                        WasPrimaryPointerReleased(targetRect, step.maskShape, out var screenPosition) &&
-                        WasPointerReleaseRoutedToTarget(targetTransform, screenPosition))
-                    {
-                        LogDebug(
-                            $"ClickTarget candidate accepted, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
-                            $"pointer={screenPosition}, target={GetTransformPath(targetTransform)}");
-                        QueueStepCompletion();
-                    }
+                    TickClickTargetCompletion(step, targetTransform);
                     break;
                 case ShrinkTutorialCompleteCondition.CustomEvent:
                 case ShrinkTutorialCompleteCondition.DragToTarget:
@@ -359,24 +362,76 @@ namespace ShrinkTutorial
             return pressed && !_dialog.ContainsScreenPoint(screenPosition);
         }
 
-        private bool WasPrimaryPointerReleased(Rect targetRect, ShrinkTutorialMaskShape maskShape, out Vector2 screenPosition)
+        private void TickClickTargetCompletion(ShrinkTutorialStep step, Transform targetTransform)
         {
-            if (!TryGetPointerUpPosition(out screenPosition))
-                return false;
-
-            if (_dialog.ContainsScreenPoint(screenPosition))
+            if (!_clickTargetArmed &&
+                targetTransform &&
+                ShrinkTutorialTargetUtility.TryBuildScreenRect(targetTransform, out var targetRect) &&
+                TryGetPointerDownPosition(out var pointerDownPosition))
             {
-                LogDebug($"Pointer release ignored because it hit dialog, pointer={screenPosition}");
-                return false;
+                if (_dialog.ContainsScreenPoint(pointerDownPosition))
+                {
+                    LogDebug($"Pointer down ignored because it hit dialog, pointer={pointerDownPosition}");
+                }
+                else if (!IsPointInsideTarget(targetRect, step.maskShape, pointerDownPosition))
+                {
+                    LogDebug($"Pointer down outside target, pointer={pointerDownPosition}, rect={targetRect}");
+                }
+                else if (WasPointerRoutedToTarget(targetTransform, pointerDownPosition))
+                {
+                    _clickTargetArmed = true;
+                    _clickTargetArmedRect = targetRect;
+                    _clickTargetArmedShape = step.maskShape;
+                    _clickTargetArmedFrame = Time.frameCount;
+                    _clickTargetArmedWithTouch = Input.touchCount > 0;
+                    LogDebug(
+                        $"ClickTarget armed, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
+                        $"pointer={pointerDownPosition}, target={GetTransformPath(targetTransform)}");
+                }
             }
 
-            var insideTarget = maskShape == ShrinkTutorialMaskShape.Circle
+            if (!_clickTargetArmed)
+                return;
+
+            if (!TryGetPointerUpPosition(out var pointerUpPosition))
+            {
+                if (_clickTargetArmedWithTouch ||
+                    Time.frameCount <= _clickTargetArmedFrame ||
+                    Input.GetMouseButton(0))
+                {
+                    return;
+                }
+
+                pointerUpPosition = Input.mousePosition;
+            }
+
+            var armedRect = _clickTargetArmedRect;
+            var armedShape = _clickTargetArmedShape;
+            _clickTargetArmed = false;
+
+            if (_dialog.ContainsScreenPoint(pointerUpPosition))
+            {
+                LogDebug($"Pointer release ignored because it hit dialog, pointer={pointerUpPosition}");
+                return;
+            }
+
+            if (!IsPointInsideTarget(armedRect, armedShape, pointerUpPosition))
+            {
+                LogDebug($"Pointer release outside armed target, pointer={pointerUpPosition}, rect={armedRect}");
+                return;
+            }
+
+            LogDebug(
+                $"ClickTarget candidate accepted, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
+                $"pointer={pointerUpPosition}, target={GetTransformPath(targetTransform)}");
+            QueueStepCompletion();
+        }
+
+        private static bool IsPointInsideTarget(Rect targetRect, ShrinkTutorialMaskShape maskShape, Vector2 screenPosition)
+        {
+            return maskShape == ShrinkTutorialMaskShape.Circle
                 ? IsPointInsideCircle(targetRect, screenPosition)
                 : targetRect.Contains(screenPosition);
-            if (!insideTarget)
-                LogDebug($"Pointer release outside target, pointer={screenPosition}, rect={targetRect}");
-
-            return insideTarget;
         }
 
         private static bool IsPointInsideCircle(Rect targetRect, Vector2 screenPosition)
@@ -430,7 +485,7 @@ namespace ShrinkTutorial
             return false;
         }
 
-        private bool WasPointerReleaseRoutedToTarget(Transform targetTransform, Vector2 screenPosition)
+        private bool WasPointerRoutedToTarget(Transform targetTransform, Vector2 screenPosition)
         {
             var eventSystem = EventSystem.current;
             if (!eventSystem)
@@ -521,6 +576,7 @@ namespace ShrinkTutorial
             _currentStepIndex = -1;
             _runner = null;
             _stepCompletionQueued = false;
+            _clickTargetArmed = false;
 
             TryStartQueuedTutorial();
         }
@@ -530,6 +586,24 @@ namespace ShrinkTutorial
             if (_canvas && _mask && _dialog)
                 return;
 
+            if (canvasOverride && maskOverride && dialogOverride)
+            {
+                _canvas = canvasOverride;
+                _mask = maskOverride;
+                _dialog = dialogOverride;
+                if (!_dialog.BindExisting())
+                    throw new InvalidOperationException("ShrinkTutorial explicit dialog bindings are incomplete.");
+
+                _dialog.Hide();
+                return;
+            }
+
+            if (!allowRuntimeUiFallback)
+            {
+                throw new InvalidOperationException(
+                    "ShrinkTutorialManager requires explicit Canvas, Mask and Dialog bindings when runtime UI fallback is disabled.");
+            }
+
             var settings = ResolveSettings();
             var canvasObject = new GameObject("ShrinkTutorialCanvas", typeof(RectTransform), typeof(Canvas), typeof(CanvasScaler),
                 typeof(GraphicRaycaster));

Runtime/UI/ShrinkTutorialDialog.cs

@@ -7,12 +7,30 @@ namespace ShrinkTutorial
 {
     public class ShrinkTutorialDialog : MonoBehaviour
     {
-        private RectTransform _rectTransform;
-        private RectTransform _arrowRectTransform;
-        private TextMeshProUGUI _contentText;
-        private GameObject _skipButtonObject;
+        [Header("Explicit scene bindings")]
+        [SerializeField] private RectTransform _rectTransform;
+        [SerializeField] private RectTransform _arrowRectTransform;
+        [SerializeField] private TextMeshProUGUI _contentText;
+        [SerializeField] private GameObject _skipButtonObject;
         private Action _skipAction;
 
+        /// <summary>
+        /// Uses UI objects that already exist in the scene. This path intentionally does not
+        /// create children or add listeners at runtime; scene-authored persistent callbacks
+        /// remain the source of truth.
+        /// </summary>
+        public bool BindExisting()
+        {
+            if (!_rectTransform)
+                _rectTransform = GetComponent<RectTransform>();
+
+            if (_rectTransform && _arrowRectTransform && _contentText)
+                return true;
+
+            Debug.LogError("[ShrinkTutorial] Explicit dialog bindings are incomplete.", this);
+            return false;
+        }
+
         public void Initialize(Transform parent, Action skipAction)
         {
             _skipAction = skipAction;