修复第五天教程中角色设置二级菜单重排后的位置同步问题：设置面板会避开任务栏，二级菜单会随面板重新定位，猫爪指针也会同步移动到新的二级菜单位… (#2092)

* 修复第五天教程中角色设置二级菜单重排后的位置同步问题：设置面板会避开任务栏，二级菜单会随面板重新定位，猫爪指针也会同步移动到新的二级菜单位置，并补充对应回归测试。

* Handle day5 settings panel review feedback

Author: MingTianSang

static/avatar-popup-common.js

@@ -273,13 +273,13 @@
         const currentTop = toNumber(popup.style.top, 0);
         let nextTop = currentTop;
         if (popupRect.bottom > screenHeight - bottomMargin) {
-            nextTop -= (popupRect.bottom - (screenHeight - bottomMargin));
+            nextTop -= toLocalCssPx(popupRect.bottom - (screenHeight - bottomMargin), sidePanelScale);
         }
         popup.style.top = `${nextTop}px`;
 
         popupRect = popup.getBoundingClientRect();
         if (popupRect.top < topMargin) {
-            popup.style.top = `${toNumber(popup.style.top, 0) + (topMargin - popupRect.top)}px`;
+            popup.style.top = `${toNumber(popup.style.top, 0) + toLocalCssPx(topMargin - popupRect.top, sidePanelScale)}px`;
         }
 
         return { opensLeft };

static/tutorial-settings-tour-flow.test.cjs

@@ -316,6 +316,165 @@ test('SettingsTourFlow owns linear day four gaze follow scene body', async () =>
     ]);
 });
 
+test('SettingsTourFlow refreshes visible day five character panel before panic narration', async () => {
+    const calls = [];
+    const characterSettingsPanel = { id: 'character-settings-panel' };
+    const characterSettingsButton = { id: 'character-settings-button' };
+    const director = {
+        sceneRunId: 17,
+        destroyed: false,
+        angryExitTriggered: false,
+        currentStep: 'day5-panic',
+        overlay: {
+            clearActionSpotlight() {
+                calls.push(['clear-action']);
+            },
+            clearPersistentSpotlight() {
+                calls.push(['clear-persistent']);
+            }
+        },
+        prepareNarration(scene) {
+            calls.push(['prepare', scene.id]);
+            return { text: 'line', voiceKey: 'voice', canHandleSceneButtons: false, actionWaitPromise: null };
+        },
+        getCharacterSettingsSidePanel() {
+            calls.push(['get-panel']);
+            return characterSettingsPanel;
+        },
+        isElementVisible(panel) {
+            calls.push(['visible', panel.id]);
+            return true;
+        },
+        ensureAvatarFloatingSettingsSidePanel(panelId) {
+            calls.push(['ensure-panel', panelId]);
+            return Promise.resolve(characterSettingsPanel);
+        },
+        getDay5CharacterSettingsButtonTarget() {
+            calls.push(['get-button']);
+            return characterSettingsButton;
+        },
+        refreshAvatarFloatingSettingsPanelLayout(panel) {
+            calls.push(['refresh-layout', panel.id]);
+        },
+        applyGuideHighlights(config) {
+            calls.push(['highlight', config.key, config.primary.id, config.persistent.id]);
+        },
+        moveCursorToElement(element, durationMs, options) {
+            const normalizedOptions = options || {};
+            calls.push(['move', element.id, durationMs, normalizedOptions.exactDuration]);
+            return Promise.resolve(true);
+        },
+        enableInterrupts(step) {
+            calls.push(['interrupts', step]);
+        },
+        createNarrationPromise(scene, text, voiceKey) {
+            calls.push(['narration', scene.id, text, voiceKey]);
+            return Promise.resolve();
+        },
+        getAvatarFloatingNarrationDurationMs(voiceKey, text) {
+            calls.push(['duration', voiceKey, text]);
+            return 900;
+        },
+        getElementRect(target) {
+            calls.push(['rect', target.id]);
+            return { left: 10, top: 20, width: 100, height: 200 };
+        },
+        runSettingsPeekPanicPerformance(options) {
+            calls.push(['panic', options.targetRect.width, options.totalDurationMs, options.runId]);
+            return Promise.resolve();
+        },
+        isStopping() {
+            return false;
+        },
+        collapseCharacterSettingsSidePanel() {
+            calls.push(['collapse-character']);
+        },
+        finalizeScene(sceneRunId, options) {
+            calls.push(['finalize', sceneRunId, options.index, options.total]);
+            return Promise.resolve(true);
+        }
+    };
+    const flow = new SettingsTourFlow(director);
+
+    const result = await flow.play({ id: 'day5_character_panic' }, {
+        sceneRunId: 17,
+        index: 2,
+        total: 4
+    });
+
+    assert.equal(result, true);
+    assert.deepEqual(calls, [
+        ['prepare', 'day5_character_panic'],
+        ['get-panel'],
+        ['visible', 'character-settings-panel'],
+        ['get-button'],
+        ['refresh-layout', 'character-settings-panel'],
+        ['highlight', 'day5_character_panic-character-settings-panel', 'character-settings-panel', 'character-settings-button'],
+        ['move', 'character-settings-panel', 0, true],
+        ['interrupts', 'day5-panic'],
+        ['narration', 'day5_character_panic', 'line', 'voice'],
+        ['duration', 'voice', 'line'],
+        ['rect', 'character-settings-panel'],
+        ['panic', 100, 900, 17],
+        ['clear-action'],
+        ['clear-persistent'],
+        ['collapse-character'],
+        ['finalize', 17, 2, 4]
+    ]);
+    assert.equal(calls.some((call) => call[0] === 'ensure-panel'), false);
+});
+
+test('SettingsTourFlow stops day five panic scene after stale async panel ensure', async () => {
+    const calls = [];
+    const characterSettingsPanel = { id: 'character-settings-panel' };
+    const director = {
+        sceneRunId: 17,
+        destroyed: false,
+        angryExitTriggered: false,
+        currentStep: 'day5-panic',
+        prepareNarration(scene) {
+            calls.push(['prepare', scene.id]);
+            return { text: 'line', voiceKey: 'voice', canHandleSceneButtons: false, actionWaitPromise: null };
+        },
+        getCharacterSettingsSidePanel() {
+            calls.push(['get-panel']);
+            return null;
+        },
+        ensureAvatarFloatingSettingsSidePanel(panelId) {
+            calls.push(['ensure-panel', panelId]);
+            this.sceneRunId = 18;
+            return Promise.resolve(characterSettingsPanel);
+        },
+        getDay5CharacterSettingsButtonTarget() {
+            calls.push(['get-button']);
+            return { id: 'character-settings-button' };
+        },
+        refreshAvatarFloatingSettingsPanelLayout(panel) {
+            calls.push(['refresh-layout', panel && panel.id]);
+        },
+        applyGuideHighlights(config) {
+            calls.push(['highlight', config.key]);
+        },
+        isStopping() {
+            return false;
+        }
+    };
+    const flow = new SettingsTourFlow(director);
+
+    const result = await flow.play({ id: 'day5_character_panic' }, {
+        sceneRunId: 17,
+        index: 2,
+        total: 4
+    });
+
+    assert.equal(result, false);
+    assert.deepEqual(calls, [
+        ['prepare', 'day5_character_panic'],
+        ['get-panel'],
+        ['ensure-panel', 'character-settings']
+    ]);
+});
+
 test('SettingsTourFlow delegates narration and finalize to the director', async () => {
     const calls = [];
     const director = {

static/tutorial/core/settings-tour-flow.js

@@ -401,6 +401,9 @@
                 return false;
             }
             await director.openSettingsPanel();
+            if (typeof director.positionManagedPanelNow === 'function') {
+                director.positionManagedPanelNow('settings');
+            }
             if (this.isSceneStale(sceneRunId)) {
                 return false;
             }
@@ -424,6 +427,9 @@
 
             characterSettingsPanel = await director.ensureAvatarFloatingSettingsSidePanel('character-settings')
                 || characterSettingsPanel;
+            if (typeof director.refreshAvatarFloatingSettingsPanelLayout === 'function') {
+                director.refreshAvatarFloatingSettingsPanelLayout(characterSettingsPanel);
+            }
             await this.tourPanel(scene, sceneRunId, characterSettingsPanel, narrationPromise, {
                 key: scene.id + '-character-settings-panel',
                 persistent: settingsButton || null
@@ -439,15 +445,36 @@
             const narration = this.prepareNarration(scene);
             const { text, voiceKey } = narration;
 
-            const characterSettingsPanel = director.getCharacterSettingsSidePanel()
-                || await director.ensureAvatarFloatingSettingsSidePanel('character-settings');
+            let characterSettingsPanel = director.getCharacterSettingsSidePanel();
+            const hasVisibleCharacterPanel = characterSettingsPanel && (
+                typeof director.isElementVisible !== 'function'
+                || director.isElementVisible(characterSettingsPanel)
+            );
+            if (!hasVisibleCharacterPanel) {
+                characterSettingsPanel = await director.ensureAvatarFloatingSettingsSidePanel('character-settings')
+                    || characterSettingsPanel;
+                if (this.isSceneStale(sceneRunId)) {
+                    return false;
+                }
+            }
             const characterSettingsButton = director.getDay5CharacterSettingsButtonTarget();
+            if (characterSettingsPanel && typeof director.refreshAvatarFloatingSettingsPanelLayout === 'function') {
+                director.refreshAvatarFloatingSettingsPanelLayout(characterSettingsPanel);
+            }
             if (characterSettingsPanel) {
                 director.applyGuideHighlights({
                     key: scene.id + '-character-settings-panel',
                     persistent: characterSettingsButton || null,
                     primary: characterSettingsPanel
                 });
+                if (typeof director.moveCursorToElement === 'function') {
+                    await director.moveCursorToElement(characterSettingsPanel, 0, {
+                        exactDuration: true
+                    });
+                    if (this.isSceneStale(sceneRunId)) {
+                        return false;
+                    }
+                }
             }
             director.enableInterrupts(director.currentStep);
 

static/tutorial/yui-guide/director.js

@@ -6049,6 +6049,31 @@
             return hidden;
         }
 
+        positionAvatarFloatingSidePanelNow(panel) {
+            const targetPanel = panel || null;
+            const anchor = targetPanel && targetPanel._anchorElement ? targetPanel._anchorElement : null;
+            const popupUi = window.AvatarPopupUI || null;
+            if (!targetPanel || !anchor || !popupUi || typeof popupUi.positionSidePanel !== 'function') {
+                return false;
+            }
+
+            try {
+                popupUi.positionSidePanel(targetPanel, anchor);
+                return true;
+            } catch (error) {
+                console.warn('[YuiGuide] positionAvatarFloatingSidePanelNow 失败:', error);
+                return false;
+            }
+        }
+
+        refreshAvatarFloatingSettingsPanelLayout(panel) {
+            const popupPositioned = this.positionManagedPanelNow('settings');
+            const sidePanelPositioned = panel && this.isElementVisible(panel)
+                ? this.positionAvatarFloatingSidePanelNow(panel)
+                : false;
+            return popupPositioned || sidePanelPositioned;
+        }
+
         forceHideAvatarFloatingGuideManagedSurfaces() {
             this.forceHideManagedPanel('settings');
             this.forceHideManagedPanel('agent');
@@ -6077,6 +6102,9 @@
                 return false;
             }
             const targetAnchor = anchor || panel._anchorElement || null;
+            if (targetAnchor) {
+                this.refreshAvatarFloatingSettingsPanelLayout(panel);
+            }
             this.collapseAvatarFloatingSidePanelsExcept(panel);
             if (typeof panel._expand === 'function') {
                 if (panel._hoverCollapseTimer) {
@@ -6106,12 +6134,17 @@
             if (!opened || this.isStopping()) {
                 return null;
             }
+            this.positionManagedPanelNow('settings');
             const panel = await this.waitForElement(() => this.getAvatarFloatingSidePanel(type), 1200);
             if (!panel) {
                 return null;
             }
             this.sidebarPauseController.trackPanel(panel);
-            return (await this.expandAvatarFloatingSidePanel(panel, panel._anchorElement || null)) ? panel : null;
+            const expanded = await this.expandAvatarFloatingSidePanel(panel, panel._anchorElement || null);
+            if (expanded) {
+                this.refreshAvatarFloatingSettingsPanelLayout(panel);
+            }
+            return expanded ? panel : null;
         }
 
         async ensureAvatarFloatingAgentSidePanel(toggleId) {

static/tutorial/yui-guide/page-handoff.js

@@ -629,6 +629,43 @@
         return !!(sidePanel && sidePanel.style.display === 'flex' && sidePanel.style.opacity !== '0');
     }
 
+    function collapseSettingSidePanels() {
+        document.querySelectorAll([
+            '[data-neko-sidepanel-type="chat-settings"]',
+            '[data-neko-sidepanel-type="animation-settings"]',
+            '[data-neko-sidepanel-type="character-settings"]',
+            '[data-neko-sidepanel-type="interval-proactive-chat"]',
+            '[data-neko-sidepanel-type="interval-proactive-vision"]'
+        ].join(',')).forEach(function (panel) {
+            if (!panel) return;
+            if (panel._hoverCollapseTimer) {
+                clearTimeout(panel._hoverCollapseTimer);
+                panel._hoverCollapseTimer = null;
+            }
+            if (panel._collapseTimeout) {
+                clearTimeout(panel._collapseTimeout);
+                panel._collapseTimeout = null;
+            }
+            if (panel._expandFrameId) {
+                const cancelFrame = window.cancelAnimationFrame || function () {};
+                cancelFrame(panel._expandFrameId);
+                panel._expandFrameId = null;
+            }
+            if (typeof panel._stopHoverPointerTracking === 'function') {
+                panel._stopHoverPointerTracking();
+            }
+            if (typeof panel._collapse === 'function') {
+                panel._collapse();
+                return;
+            }
+            panel.style.transition = 'none';
+            panel.style.opacity = '0';
+            panel.style.display = 'none';
+            panel.style.pointerEvents = 'none';
+            panel.style.transition = '';
+        });
+    }
+
     function getAgentSidePanelAction(toggleId, actionId) {
         if (!toggleId || !actionId) return null;
         return document.getElementById('neko-sidepanel-action-' + toggleId + '-' + actionId);
@@ -1012,6 +1049,8 @@
 
         return openSettingsPanel().then(function (opened) {
             if (!opened) return false;
+            collapseSettingSidePanels();
+            positionFloatingPopupNow('settings', prefix);
 
             var el = document.getElementById(prefix + '-menu-' + menuId);
             if (!el) {
@@ -1022,6 +1061,7 @@
             if (typeof el.scrollIntoView === 'function') {
                 el.scrollIntoView({ block: 'nearest', behavior: 'instant' });
             }
+            positionFloatingPopupNow('settings', prefix);
 
             return true;
         });