reveal() 失败/返回 false 没有 fallback：有效，已加 return-ball-reveal-failed 桌面状态和 neko:return-ball-reveal-failed 事件

await reveal 后缺少 drag token 复查：当前分支确实有这个风险；我没有加 token 复查，而是更小地移除了阻塞式 await，所以这个 async gap 不再存在

Author: MingTianSang

static/app-ui.js

@@ -1472,6 +1472,7 @@
     const MULTI_WINDOW_RETURN_BALL_DRAG_SHRINK_SIZE = 160;
     const MULTI_WINDOW_RETURN_BALL_DRAG_SHRINK_FALLBACK_MS = 220;
     const MULTI_WINDOW_RETURN_BALL_DRAG_RESTORE_FALLBACK_MS = 600;
+    const MULTI_WINDOW_RETURN_BALL_REVEAL_FALLBACK_MS = 600;
     let multiWindowReturnBallDragState = null;
     let idleReturnBallDesktopDragStateFrame = 0;
     let idleReturnBallDesktopDragStatePending = null;
@@ -2347,14 +2348,47 @@
             restoreSavedReturnBallStyle(container, state);
         }
 
-        async function revealReturnBallDragWindow() {
+        function dispatchReturnBallRevealFailed(reason, error) {
+            scheduleIdleReturnBallDesktopBridge('return-ball-reveal-failed', container);
+            window.dispatchEvent(new CustomEvent('neko:return-ball-reveal-failed', {
+                detail: {
+                    reason: reason || 'unknown',
+                    container: container,
+                    errorMessage: error && (error.message || String(error))
+                }
+            }));
+        }
+
+        function revealReturnBallDragWindow() {
             if (!window.nekoPetDrag || typeof window.nekoPetDrag.reveal !== 'function') {
+                dispatchReturnBallRevealFailed('bridge-unavailable');
                 return false;
             }
+            let settled = false;
+            const fallbackTimer = setTimeout(() => {
+                if (settled) return;
+                dispatchReturnBallRevealFailed('reveal-timeout');
+            }, MULTI_WINDOW_RETURN_BALL_REVEAL_FALLBACK_MS);
             try {
-                return await window.nekoPetDrag.reveal();
+                const revealResult = window.nekoPetDrag.reveal();
+                Promise.resolve(revealResult).then((ok) => {
+                    settled = true;
+                    clearTimeout(fallbackTimer);
+                    if (ok === false) {
+                        dispatchReturnBallRevealFailed('reveal-failed');
+                    }
+                }).catch((error) => {
+                    settled = true;
+                    clearTimeout(fallbackTimer);
+                    console.warn('[App] 返回球拖拽渲染完成后恢复窗口显示失败:', error);
+                    dispatchReturnBallRevealFailed('reveal-rejected', error);
+                });
+                return true;
             } catch (error) {
+                settled = true;
+                clearTimeout(fallbackTimer);
                 console.warn('[App] 返回球拖拽渲染完成后恢复窗口显示失败:', error);
+                dispatchReturnBallRevealFailed('reveal-threw', error);
                 return false;
             }
         }
@@ -2694,12 +2728,12 @@
                 if (!isActiveDragToken(dragToken)) return;
                 const expectedWidth = restoreBounds ? restoreBounds.width : state.savedWindowW;
                 const expectedHeight = restoreBounds ? restoreBounds.height : state.savedWindowH;
-                waitForViewportSize(dragToken, expectedWidth, expectedHeight, async () => {
+                waitForViewportSize(dragToken, expectedWidth, expectedHeight, () => {
                     restoreSavedBallStyle();
                     delete document.body.dataset.nekoBallDrag;
                     container.setAttribute('data-dragging', 'false');
                     scheduleIdleReturnBallDesktopBridge('return-ball-drag-click', container);
-                    await revealReturnBallDragWindow();
+                    revealReturnBallDragWindow();
                     dispatchReturnBallClick();
                 }, {
                     fallbackMs: MULTI_WINDOW_RETURN_BALL_DRAG_RESTORE_FALLBACK_MS,
@@ -2734,7 +2768,7 @@
 
             const expectedWidth = finalBounds ? finalBounds.width : state.savedWindowW;
             const expectedHeight = finalBounds ? finalBounds.height : state.savedWindowH;
-            waitForViewportSize(dragToken, expectedWidth, expectedHeight, async () => {
+            waitForViewportSize(dragToken, expectedWidth, expectedHeight, () => {
                 if (shouldRestoreSavedBallStyle) {
                     restoreSavedBallStyle();
                     container.setAttribute('data-dragging', 'false');
@@ -2747,7 +2781,7 @@
                             movedDistancePx: movedDistancePx
                         }
                     }));
-                    await revealReturnBallDragWindow();
+                    revealReturnBallDragWindow();
                     return;
                 }
                 // 先同步恢复球 opacity，再删除 nekoBallDrag 显示页面内容，
@@ -2765,7 +2799,7 @@
                         movedDistancePx: movedDistancePx
                     }
                 }));
-                await revealReturnBallDragWindow();
+                revealReturnBallDragWindow();
                 // 延迟恢复 transition，避免恢复瞬间触发动画
                 state.transitionCleanupTimer = setTimeout(() => {
                     state.transitionCleanupTimer = null;

tests/unit/test_avatar_return_button_idle_tiers_static.py

@@ -232,15 +232,22 @@ def test_desktop_return_ball_drag_lifecycle_waits_for_restored_viewport_before_r
 
     assert "MULTI_WINDOW_RETURN_BALL_DRAG_SHRINK_FALLBACK_MS = 220" in source
     assert "MULTI_WINDOW_RETURN_BALL_DRAG_RESTORE_FALLBACK_MS = 600" in source
+    assert "MULTI_WINDOW_RETURN_BALL_REVEAL_FALLBACK_MS = 600" in source
     assert "continueOnFallback" in source
     assert "waitForViewportSize timed out; continuing best-effort cleanup" in source
     assert "keeping return-ball hidden until viewport is restored" in source
     assert "waitForViewportSize hard timeout; continuing best-effort cleanup" in source
     assert "clearMultiWindowReturnBallDeferredWork(state)" in source
     assert "state.viewportWaitFallbackTimer = setTimeout(pollViewportRestore, 50)" in source
     assert "runWhenStable({ timedOut: true })" in source
-    assert "async function revealReturnBallDragWindow()" in source
+    assert "function revealReturnBallDragWindow()" in source
     assert "window.nekoPetDrag.reveal" in source
+    assert "function dispatchReturnBallRevealFailed(reason, error)" in source
+    assert "'return-ball-reveal-failed'" in source
+    assert "'neko:return-ball-reveal-failed'" in source
+    assert "Promise.resolve(revealResult)" in source
+    assert "dispatchReturnBallRevealFailed('reveal-timeout')" in source
+    assert "await revealReturnBallDragWindow()" not in source
     assert "function isNativeReturnBallDragDisabled()" in source
     assert "isNativeReturnBallDragDisabled() || !window.nekoPetDrag" in source
     assert "const dragStarted = window.nekoPetDrag.start(screenX, screenY)" in source
@@ -258,7 +265,7 @@ def test_desktop_return_ball_drag_lifecycle_waits_for_restored_viewport_before_r
     no_move_end = source.index("const finalBounds = await resolveFinalWindowBounds", no_move_start)
     no_move_block = source[no_move_start:no_move_end]
 
-    assert no_move_block.index("await revealReturnBallDragWindow();") < no_move_block.index("dispatchReturnBallClick();")
+    assert no_move_block.index("revealReturnBallDragWindow();") < no_move_block.index("dispatchReturnBallClick();")
 
 
 def test_return_button_drag_has_single_owner_per_runtime_path():