fix(ui): 修复歌单分屏闪烁与双轨 Cue 波形卡顿并发布预发布版

Author: coderDJing

package.json

@@ -1,6 +1,6 @@
 {
   "name": "frkb",
-  "version": "1.2.6-rc.202610281430",
+  "version": "1.2.6-rc.202610281518",
   "packageManager": "pnpm@9.15.9",
   "description": "Track Studio — Rapid Audio Organization Tool",
   "license": "PolyForm-Noncommercial-1.0.0",

src/renderer/src/composables/horizontalBrowse/createHorizontalBrowseStableRenderRevision.spec.ts

@@ -0,0 +1,81 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createHorizontalBrowseStableRenderRevision } from './createHorizontalBrowseStableRenderRevision'
+import { useHorizontalBrowseWaveformPresentationCoordinator } from './horizontalBrowseWaveformPresentationCoordinator'
+import { createHorizontalBrowseStableCanvasPresentationController } from './horizontalBrowseStableCanvasPresentation'
+
+afterEach(() => vi.unstubAllGlobals())
+
+describe('Cue 跳转复用稳定波形', () => {
+  it.each(['top', 'bottom'] as const)(
+    '%s 反复返回 Cue 只移动已有画布，不让整片波形失效',
+    (deck) => {
+      vi.stubGlobal('requestAnimationFrame', () => 1)
+      vi.stubGlobal('cancelAnimationFrame', () => {})
+      const coordinator = useHorizontalBrowseWaveformPresentationCoordinator()
+      const revision = createHorizontalBrowseStableRenderRevision({
+        song: null,
+        direction: deck === 'top' ? 'up' : 'down',
+        get presentationState() {
+          return coordinator.state[deck]
+        }
+      })
+      const scheduleDraw = vi.fn()
+      let playing = false
+      const controller = createHorizontalBrowseStableCanvasPresentationController({
+        isActive: () => true,
+        isPlaying: () => playing,
+        isDragging: () => false,
+        currentSeconds: () => 8.615104,
+        playbackRate: () => 1,
+        renderRevision: () => revision.value,
+        resolveViewportRangeStartSec: (seconds, visible = 12) => seconds - visible / 2,
+        waveformCanvas: () => null,
+        overlayCanvas: () => null,
+        scheduleDraw
+      })
+      // 覆盖初始画布，以及曾拖动/调整后持有非零展示版本的画布。
+      for (const afterDrag of [false, true]) {
+        if (afterDrag) coordinator.markDragPreview(deck, 8.615104, false)
+        const frameRevision = revision.value
+        controller.queueFrame({
+          renderToken: 1,
+          renderRevision: frameRevision,
+          playbackActive: false,
+          rangeStartSec: -33.384896,
+          rangeDurationSec: 84,
+          viewportRangeStartSec: 2.615104,
+          anchorSec: 8.615104,
+          anchorStartedAtMs: performance.now(),
+          playbackRate: 1,
+          renderWidth: 8400,
+          overscanCssPx: 3600,
+          pixelRatio: 1.75
+        })
+        controller.handleRendered({
+          renderToken: 1,
+          rangeStartSec: -33.384896,
+          rangeDurationSec: 84,
+          ready: true
+        })
+        for (let i = 0; i < 8; i += 1) {
+          playing = true
+          controller.startPlayback(8.615104, 1)
+          expect(controller.apply(8.815104, { requirePresentable: true }).applied).toBe(true)
+          coordinator.markSeek(deck, 8.615104)
+          playing = false
+          controller.stopPlayback()
+          expect(coordinator.state[deck].owner).toBe('seek')
+          expect(revision.value).toBe(frameRevision)
+          expect(controller.apply(8.615104, { requirePresentable: true }).applied).toBe(true)
+        }
+        expect(scheduleDraw).not.toHaveBeenCalled()
+        // 超出缓存覆盖范围仍须请求新画面，不能显示旧位置。
+        coordinator.markSeek(deck, 120)
+        expect(controller.apply(120, { requirePresentable: true }).applied).toBe(false)
+      }
+      // 改变展示内容的拖动版本仍会失效旧帧。
+      coordinator.markDragPreview(deck, 60, false)
+      expect(controller.measure(8.615104).presentable).toBe(false)
+    }
+  )
+})

src/renderer/src/composables/horizontalBrowse/createHorizontalBrowseStableRenderRevision.ts

@@ -10,14 +10,17 @@ export const createHorizontalBrowseStableRenderRevision = (
     const presentationRevision = Math.max(0, Math.floor(Number(state?.revision) || 0))
     if (
       state?.owner === 'linked-playback' ||
-      state?.owner === 'seek' ||
       state?.owner === 'drag' ||
       state?.owner === 'linked-drag'
     ) {
       lastPresentationStableRenderRevision = presentationRevision
       return presentationRevision
     }
+    // Seek/Cue 只改变视口位置，不改变已经绘制的波形内容。保留画布版本，
+    // 让覆盖目标位置的稳定帧直接平移复用；越出覆盖范围仍由 seek watcher 请求新帧。
+    // 若把 seek 的展示事务版本作为内容版本，每次松开 Cue 都会清空块池并重画整片波形。
     if (
+      state?.owner === 'seek' ||
       state?.owner === 'sync-transaction' ||
       (state?.owner === 'playback' &&
         state.sourceDeck === null &&

src/renderer/src/composables/horizontalBrowse/useHorizontalBrowseRenderSync.spec.ts

@@ -6,8 +6,7 @@ import {
 import { useHorizontalBrowseRenderSync } from './useHorizontalBrowseRenderSync'
 
 const createPlayingSnapshot = () => {
-  const snapshot = createEmptyHorizontalBrowseTransportSnapshot()
-  snapshot.stateRevision = 1
+  const snapshot = { ...createEmptyHorizontalBrowseTransportSnapshot(), stateRevision: 1 }
   snapshot.top = {
     ...snapshot.top,
     label: 'top',
@@ -60,6 +59,61 @@ const createRenderSync = (linkedGridVisualPending: () => boolean) => {
 }
 
 describe('useHorizontalBrowseRenderSync', () => {
+  it.each(['top', 'bottom'] as const)('另一轨反复 Cue 不应重置 %s Master 波形', (deck) => {
+    const { snapshot, renderSync } = createRenderSync(() => false)
+    const cueDeck = deck === 'top' ? 'bottom' : 'top'
+    snapshot[cueDeck].playing = false
+    snapshot[cueDeck].leader = false
+    Object.assign(snapshot[deck], { leader: true, playbackRate: 1, renderCurrentSec: 10 })
+    const playbackRevision =
+      deck === 'top'
+        ? renderSync.topDeckPlaybackSyncRevision
+        : renderSync.bottomDeckPlaybackSyncRevision
+    const renderSeconds =
+      deck === 'top'
+        ? renderSync.topDeckRenderCurrentSeconds
+        : renderSync.bottomDeckRenderCurrentSeconds
+    renderSync.syncDeckRenderState({ nowMs: 1000, snapshotAtMs: 1000 })
+    const revision = playbackRevision.value
+    for (let step = 1; step <= 6; step += 1) {
+      snapshot.stateRevision += 1
+      snapshot[cueDeck].playing = step % 2 === 1
+      // Native output buffers and IPC timestamps can differ by a few milliseconds.
+      snapshot[deck].renderCurrentSec = 10 + step * 0.2 - 0.008
+      renderSync.syncDeckRenderState({ nowMs: 1000 + step * 200, snapshotAtMs: 1000 + step * 200 })
+      expect(playbackRevision.value).toBe(revision)
+      expect(renderSeconds.value).toBeCloseTo(10 + step * 0.2, 6)
+    }
+  })
+
+  it('跟随轨的真实相位校正仍会更新波形', () => {
+    const { snapshot, renderSync } = createRenderSync(() => false)
+    Object.assign(snapshot.bottom, { playbackRate: 1, renderCurrentSec: 10 })
+    renderSync.syncDeckRenderState({ nowMs: 1000, snapshotAtMs: 1000 })
+    const revision = renderSync.bottomDeckPlaybackSyncRevision.value
+    snapshot.stateRevision += 1
+    snapshot.bottom.renderCurrentSec = 10.208
+    renderSync.syncDeckRenderState({ nowMs: 1200, snapshotAtMs: 1200 })
+    expect(renderSync.bottomDeckPlaybackSyncRevision.value).toBe(revision + 1)
+    expect(renderSync.bottomDeckRenderCurrentSeconds.value).toBeCloseTo(10.208, 6)
+  })
+
+  it('Master 本轨的主动小幅跳转和明显偏差仍会更新波形', () => {
+    const { snapshot, renderSync } = createRenderSync(() => false)
+    snapshot.top.renderCurrentSec = 10
+    renderSync.syncDeckRenderState({ nowMs: 1000, snapshotAtMs: 1000 })
+    const revision = renderSync.topDeckPlaybackSyncRevision.value
+    snapshot.stateRevision += 1
+    snapshot.top.renderCurrentSec = 10.208
+    renderSync.syncDeckRenderState({ nowMs: 1200, snapshotAtMs: 1200, force: 'top' })
+    expect(renderSync.topDeckPlaybackSyncRevision.value).toBe(revision + 1)
+    expect(renderSync.topDeckRenderCurrentSeconds.value).toBeCloseTo(10.208, 6)
+    snapshot.top.renderCurrentSec = 20
+    renderSync.syncDeckRenderState({ nowMs: 1400, snapshotAtMs: 1400 })
+    expect(renderSync.topDeckPlaybackSyncRevision.value).toBe(revision + 2)
+    expect(renderSync.topDeckRenderCurrentSeconds.value).toBe(20)
+  })
+
   it.each([0.5, 0.125, 0.0625, 0.03125, 0.0078125])(
     '两轨短 Loop（%s 秒）每帧回环，无需等待 native 快照',
     (loopDurationSec) => {

src/renderer/src/composables/horizontalBrowse/useHorizontalBrowseRenderSync.ts

@@ -374,8 +374,10 @@ export const useHorizontalBrowseRenderSync = (params: UseHorizontalBrowseRenderS
       !!recentIntent &&
       recentIntentAgeMs <= RENDER_SYNC_RECENT_INTENT_CONFIRM_MS &&
       Math.abs(snapshotSec - recentIntent.seconds) <= RENDER_SYNC_PENDING_INTENT_EPSILON_SEC
+    // Native 只校正跟随轨的相位；另一轨的 Cue 也会更新全局版本，不能因此重置 Master 时钟。
     const fullSyncPhaseChanged =
       stateRevisionChanged &&
+      !snapshot.leader &&
       snapshot.syncEnabled &&
       snapshot.syncLock === 'full' &&
       playbackSnapshotAuthoritative &&

src/renderer/src/pages/homePage.vue

@@ -3,11 +3,14 @@ import librarySelectArea from './modules/librarySelectArea.vue'
 import libraryArea from './modules/libraryArea.vue'
 import pioneerDeviceLibraryArea from './modules/pioneerDeviceLibraryArea.vue'
 import songsArea from './modules/songsArea/songsArea.vue'
+import SongsAreaPreviewHost from './homePage/SongsAreaPreviewHost'
+import { useSongsAreaPaneViews } from './homePage/useSongsAreaPaneViews'
 import pioneerSongsArea from './modules/pioneerSongsArea.vue'
 import {
   type ISongsAreaPaneRuntimeState,
   type LibrarySelection,
   type SplitSongsAreaPaneKey,
+  type SongsAreaPaneKey,
   useRuntimeStore
 } from '@renderer/stores/runtime'
 import { onMounted, onUnmounted, ref, computed, watch } from 'vue'
@@ -164,7 +167,6 @@ onUnmounted(() => {
 
 let librarySelected = ref('FilterLibrary')
 type CoreLibraryName = 'FilterLibrary' | 'CuratedLibrary' | 'SetLibrary' | 'MixtapeLibrary'
-const splitPaneKeys: SplitSongsAreaPaneKey[] = ['left', 'right']
 const normalizeLibraryPath = (value: string) => (value || '').replace(/\\/g, '/')
 const isCoreLibraryName = (value: string): value is CoreLibraryName =>
   ['FilterLibrary', 'CuratedLibrary', 'SetLibrary', 'MixtapeLibrary'].includes(value)
@@ -385,6 +387,7 @@ const showMainSongPlayer = computed(
 const isSongsAreaSplit = computed(
   () => runtime.songsAreaPanels.splitEnabled && !isPioneerDeviceLibraryView.value
 )
+const visiblePaneViews = useSongsAreaPaneViews(runtime.songsAreaPanels.panes, isSongsAreaSplit)
 const showEmptyRecycleBinButton = computed(
   () =>
     isRecycleBinView.value &&
@@ -438,9 +441,8 @@ watch(
     singlePaneHeaderRevealPending.value = false
   }
 )
-const isSplitPaneActive = (pane: SplitSongsAreaPaneKey) =>
-  runtime.songsAreaPanels.activePane === pane
-const handleSplitPaneMouseDown = (pane: SplitSongsAreaPaneKey) => {
+const isSplitPaneActive = (pane: SongsAreaPaneKey) => runtime.songsAreaPanels.activePane === pane
+const handleSplitPaneMouseDown = (pane: SongsAreaPaneKey) => {
   // 激活歌曲操作的目标面板，不联动左侧正在浏览的库。
   activateSongsAreaPane(runtime, pane)
 }
@@ -760,34 +762,41 @@ const drop = async (e: DragEvent) => {
             style="width: 100%; height: 100%; min-width: 0"
           />
           <div
-            v-else-if="isSongsAreaSplit"
+            v-else
             ref="splitSongsAreaRef"
-            class="splitSongsArea"
-            :style="splitSongsAreaStyle"
+            :class="isSongsAreaSplit ? 'splitSongsArea' : 'singleSongsAreaShell'"
+            :style="isSongsAreaSplit ? splitSongsAreaStyle : undefined"
           >
+            <SongsAreaPreviewHost />
             <div
-              v-for="pane in splitPaneKeys"
-              :key="pane"
-              class="splitSongsAreaPane"
-              :class="[`splitSongsAreaPane--${pane}`, { 'is-active': isSplitPaneActive(pane) }]"
+              v-for="{ pane, viewId } in visiblePaneViews"
+              :key="viewId"
+              :class="
+                isSongsAreaSplit
+                  ? [
+                      'splitSongsAreaPane',
+                      `splitSongsAreaPane--${pane}`,
+                      { 'is-active': isSplitPaneActive(pane) }
+                    ]
+                  : 'singleSongsAreaShell'
+              "
+              :style="!isSongsAreaSplit ? { flex: 1, minHeight: 0 } : undefined"
               @mousedown.capture="handleSplitPaneMouseDown(pane)"
             >
               <SongsAreaPaneHeader
+                v-if="isSongsAreaSplit || showSingleSongsAreaHeader"
                 :pane="pane"
                 v-model:search-query="runtime.songsAreaPanels.panes[pane].searchQuery"
                 v-model:compatible-key-only="runtime.songsAreaPanels.panes[pane].compatibleKeyOnly"
                 :title="resolveSongsPaneTitle(pane)"
                 :show-empty-recycle-bin-button="showEmptyRecycleBinButton"
                 @empty-recycle-bin="emptyRecycleBinWithOptimisticUpdate(runtime)"
-                @close="handleSplitPaneClose(pane)"
-              />
-              <songsArea
-                :pane="pane"
-                :enable-preview-player="pane === 'left'"
-                style="flex: 1; min-width: 0; min-height: 0"
+                @close="pane === 'single' ? handleSinglePaneClose() : handleSplitPaneClose(pane)"
               />
+              <songsArea :pane="pane" style="flex: 1; min-width: 0; min-height: 0" />
             </div>
             <div
+              v-if="isSongsAreaSplit"
               class="splitSongsAreaDivider"
               :class="{
                 'is-hovered': splitDividerHovered,
@@ -800,23 +809,6 @@ const drop = async (e: DragEvent) => {
               @mouseleave="splitDividerHovered = isSongsAreaSplitDividerResizing"
             ></div>
           </div>
-          <div v-else class="singleSongsAreaShell">
-            <SongsAreaPaneHeader
-              v-if="showSingleSongsAreaHeader"
-              pane="single"
-              v-model:search-query="runtime.songsAreaPanels.panes.single.searchQuery"
-              v-model:compatible-key-only="runtime.songsAreaPanels.panes.single.compatibleKeyOnly"
-              :title="resolveSongsPaneTitle('single')"
-              :show-empty-recycle-bin-button="showEmptyRecycleBinButton"
-              @empty-recycle-bin="emptyRecycleBinWithOptimisticUpdate(runtime)"
-              @close="handleSinglePaneClose"
-            />
-            <songsArea
-              pane="single"
-              :enable-preview-player="true"
-              style="flex: 1; min-width: 0; min-height: 0"
-            />
-          </div>
         </div>
       </div>
       <div class="mainPlayerShell" :class="{ 'mainPlayerShell--visible': showMainSongPlayer }">

src/renderer/src/pages/homePage/SongsAreaPreviewHost.ts

@@ -0,0 +1,10 @@
+import { defineComponent } from 'vue'
+import { useWaveformPreviewPlayer } from '../modules/songsArea/composables/useWaveformPreviewPlayer'
+
+// One preview player for the local list layout, independent of the number or order of panes.
+export default defineComponent({
+  setup() {
+    useWaveformPreviewPlayer()
+    return () => null
+  }
+})