fix(timeline): enforce track lock invariants

src/features/timeline/hooks/use-timeline-tracks.test.tsx

@@ -0,0 +1,40 @@
+import { act, renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it } from 'vite-plus/test'
+import { useItemsStore } from '../stores/items-store'
+import { useTimelineCommandStore } from '../stores/timeline-command-store'
+import { useTimelineSettingsStore } from '../stores/timeline-settings-store'
+import { makeTimelineTrack } from '../test-helpers'
+import { useTimelineTracks } from './use-timeline-tracks'
+
+describe('useTimelineTracks solo contract', () => {
+  beforeEach(() => {
+    useItemsStore.getState().setItems([])
+    useItemsStore
+      .getState()
+      .setTracks([
+        makeTimelineTrack({ id: 'v1', name: 'V1', kind: 'video', order: 0 }),
+        makeTimelineTrack({ id: 'a1', name: 'A1', kind: 'audio', order: 1 }),
+      ])
+    useTimelineCommandStore.getState().clearHistory()
+    useTimelineSettingsStore.setState({ isDirty: false })
+  })
+
+  it('keeps multiple stems soloed and toggles each track independently', () => {
+    const { result } = renderHook(() => useTimelineTracks())
+
+    act(() => result.current.toggleTrackSolo('v1'))
+    act(() => result.current.toggleTrackSolo('a1'))
+
+    expect(useItemsStore.getState().tracks.map(({ id, solo }) => ({ id, solo }))).toEqual([
+      { id: 'v1', solo: true },
+      { id: 'a1', solo: true },
+    ])
+
+    act(() => result.current.toggleTrackSolo('v1'))
+
+    expect(useItemsStore.getState().tracks.map(({ id, solo }) => ({ id, solo }))).toEqual([
+      { id: 'v1', solo: false },
+      { id: 'a1', solo: true },
+    ])
+  })
+})

src/features/timeline/hooks/use-timeline-tracks.ts

@@ -232,8 +232,8 @@ export function useTimelineTracks() {
   )
 
   /**
-   * Toggle track solo state
-   * Only one track can be soloed at a time - soloing a track will unsolo all others
+   * Toggle one track's solo state without changing any other soloed tracks.
+   * Multi-track solo is additive so editors can audition several stems together.
    * Reads latest state to avoid stale closure bugs
    */
   const toggleTrackSolo = useCallback(

src/features/timeline/hooks/use-timeline-trim.test.tsx

@@ -333,13 +333,7 @@ describe('useTimelineTrim', () => {
         .setItems([text, alignedVideo, alignedAudio, earlierVideo, earlierAudio])
       useSelectionStore
         .getState()
-        .selectItems([
-          'text-1',
-          'video-aligned',
-          'audio-aligned',
-          'video-earlier',
-          'audio-earlier',
-        ])
+        .selectItems(['text-1', 'video-aligned', 'audio-aligned', 'video-earlier', 'audio-earlier'])
       const { result } = renderTrimHook(text)
 
       startTrim(result, 'end')
@@ -400,13 +394,7 @@ describe('useTimelineTrim', () => {
         .setItems([text, alignedVideo, alignedAudio, earlierVideo, earlierAudio])
       useSelectionStore
         .getState()
-        .selectItems([
-          'text-1',
-          'video-aligned',
-          'audio-aligned',
-          'video-earlier',
-          'audio-earlier',
-        ])
+        .selectItems(['text-1', 'video-aligned', 'audio-aligned', 'video-earlier', 'audio-earlier'])
       const { result } = renderTrimHook(text)
 
       startTrim(result, 'start')
@@ -464,7 +452,7 @@ describe('useTimelineTrim', () => {
       expect(getItem('video-near').durationInFrames).toBe(60)
     })
 
-    it('leaves a vertically aligned selected companion unchanged on a locked track', () => {
+    it('rejects a vertically aligned trim cohort containing a locked linked companion', () => {
       const text: TextItem = {
         id: 'text-1',
         type: 'text',
@@ -477,21 +465,20 @@ describe('useTimelineTrim', () => {
       }
       const video = makeTimelineVideoItem({ id: 'video-1', linkedGroupId: 'lg-1' })
       const audio = makeTimelineAudioItem({ id: 'audio-1', linkedGroupId: 'lg-1' })
-      useItemsStore
-        .getState()
-        .setTracks([
-          makeTimelineTrack({ id: 'track-v1', name: 'V1', kind: 'video', order: 0 }),
-          makeTimelineTrack({ id: 'track-v2', name: 'V2', kind: 'video', order: 1 }),
-          makeTimelineTrack({
-            id: 'track-a1',
-            name: 'A1',
-            kind: 'audio',
-            order: 2,
-            locked: true,
-          }),
-        ])
+      useItemsStore.getState().setTracks([
+        makeTimelineTrack({ id: 'track-v1', name: 'V1', kind: 'video', order: 0 }),
+        makeTimelineTrack({ id: 'track-v2', name: 'V2', kind: 'video', order: 1 }),
+        makeTimelineTrack({
+          id: 'track-a1',
+          name: 'A1',
+          kind: 'audio',
+          order: 2,
+          locked: true,
+        }),
+      ])
       useItemsStore.getState().setItems([text, video, audio])
       useSelectionStore.getState().selectItems(['text-1', 'video-1', 'audio-1'])
+      const undoDepthBefore = useTimelineCommandStore.getState().undoStack.length
       const { result } = renderTrimHook(text)
 
       startTrim(result, 'end')
@@ -503,9 +490,11 @@ describe('useTimelineTrim', () => {
 
       releaseMouse()
 
-      expect(getItem('text-1').durationInFrames).toBe(50)
-      expect(getItem('video-1').durationInFrames).toBe(50)
+      expect(getItem('text-1').durationInFrames).toBe(60)
+      expect(getItem('video-1').durationInFrames).toBe(60)
       expect(getItem('audio-1').durationInFrames).toBe(60)
+      expect(useTimelineCommandStore.getState().undoStack).toHaveLength(undoDepthBefore)
+      expect(useTimelineSettingsStore.getState().isDirty).toBe(false)
     })
 
     it('uses the tightest neighbor clamp across the vertical trim group', () => {

src/features/timeline/hooks/use-timeline-trim.ts

@@ -280,12 +280,7 @@ export function useTimelineTrim(
       let constraintLabel: string | null = null
       const trimConstraintItems = isRollingEdit || isRippleEdit ? [currentItem] : normalTrimItems
       for (const trimConstraintItem of trimConstraintItems) {
-        const { clampedAmount } = clampTrimAmount(
-          trimConstraintItem,
-          handle!,
-          deltaFrames,
-          fps,
-        )
+        const { clampedAmount } = clampTrimAmount(trimConstraintItem, handle!, deltaFrames, fps)
         if (clampedAmount !== deltaFrames) {
           isConstrained = true
           constraintLabel = 'no handle'
@@ -596,6 +591,10 @@ export function useTimelineTrim(
                   items: allItems,
                   tracks: useItemsStore.getState().tracks,
                   editedTrackIds,
+                  additionalAffectedIds: new Set([
+                    ...synchronizedItems.map((linkedItem) => linkedItem.id),
+                    ...linkedPreviewUpdates.map((update) => update.id),
+                  ]),
                   intervals: [
                     {
                       start: currentItem.from + currentItem.durationInFrames + rippleShift,
@@ -607,6 +606,10 @@ export function useTimelineTrim(
                   items: allItems,
                   tracks: useItemsStore.getState().tracks,
                   editedTrackIds,
+                  additionalAffectedIds: new Set([
+                    ...synchronizedItems.map((linkedItem) => linkedItem.id),
+                    ...linkedPreviewUpdates.map((update) => update.id),
+                  ]),
                   cutFrame: currentItem.from + currentItem.durationInFrames,
                   amount: rippleShift,
                 })
@@ -874,10 +877,9 @@ export function useTimelineTrim(
           handle === 'start' ? trimmedItem.from : trimmedItem.from + trimmedItem.durationInFrames
         return areTrimEdgesAligned(anchorTrimEdge, trimmedItemEdge)
       })
-      const trimmedItemIds =
-        verticallyAlignedTrimItemIds.includes(currentItem.id)
-          ? verticallyAlignedTrimItemIds
-          : [currentItem.id]
+      const trimmedItemIds = verticallyAlignedTrimItemIds.includes(currentItem.id)
+        ? verticallyAlignedTrimItemIds
+        : [currentItem.id]
 
       magneticSnapTargetsRef.current = getMagneticSnapTargets()
       setDragState({

src/features/timeline/hooks/use-track-drag.ts

@@ -375,6 +375,7 @@ export function useTrackDrag(track: TimelineTrack): UseTrackDragReturn {
         }
       } else {
         const updates = buildTrackContentMoveUpdates({
+          tracks: allTracks,
           sectionTrackIds: dragState.sectionTrackIds,
           draggedTrackIds: draggedIds,
           items: itemsRef.current,

src/features/timeline/hooks/use-track-push.test.tsx

@@ -0,0 +1,82 @@
+import type { MouseEvent as ReactMouseEvent } from 'react'
+import { act, renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { useSelectionStore } from '@/shared/state/selection'
+import { useItemsStore } from '../stores/items-store'
+import { useTimelineSettingsStore } from '../stores/timeline-settings-store'
+import { useTrackPushPreviewStore } from '../stores/track-push-preview-store'
+import { makeTimelineAudioItem, makeTimelineTrack, makeTimelineVideoItem } from '../test-helpers'
+import { useTrackPush } from './use-track-push'
+
+function makeMouseEvent(): ReactMouseEvent {
+  return {
+    button: 0,
+    clientX: 100,
+    preventDefault: vi.fn(),
+    stopPropagation: vi.fn(),
+  } as unknown as ReactMouseEvent
+}
+
+describe('useTrackPush lock preview', () => {
+  beforeEach(() => {
+    useItemsStore.getState().setItems([])
+    useItemsStore.getState().setTracks([])
+    useTimelineSettingsStore.setState({ fps: 30, snapEnabled: false })
+    useTrackPushPreviewStore.getState().clearPreview()
+    useSelectionStore.getState().setDragState(null)
+    useSelectionStore.getState().setActiveSnapTarget(null)
+  })
+
+  it('previews eligible unlocked items without moving standalone locked-track items', () => {
+    const video = makeTimelineVideoItem({ id: 'video', from: 30 })
+    const lockedAudio = makeTimelineAudioItem({ id: 'audio', from: 30 })
+    useItemsStore.getState().setTracks([
+      makeTimelineTrack({ id: 'track-v1', name: 'V1', kind: 'video', order: 0 }),
+      makeTimelineTrack({
+        id: 'track-a1',
+        name: 'A1',
+        kind: 'audio',
+        order: 1,
+        locked: true,
+      }),
+    ])
+    useItemsStore.getState().setItems([video, lockedAudio])
+    const { result } = renderHook(() => useTrackPush(video, 10))
+
+    act(() => result.current.handleTrackPushStart(makeMouseEvent()))
+
+    expect(result.current.isTrackPushActive).toBe(true)
+    expect([...useTrackPushPreviewStore.getState().shiftedItemIds]).toEqual([video.id])
+  })
+
+  it('does not start or create a preview when the anchor has a locked linked companion', () => {
+    const video = makeTimelineVideoItem({
+      id: 'video',
+      from: 30,
+      linkedGroupId: 'linked-av',
+    })
+    const audio = makeTimelineAudioItem({
+      id: 'audio',
+      from: 30,
+      linkedGroupId: 'linked-av',
+    })
+    useItemsStore.getState().setTracks([
+      makeTimelineTrack({ id: 'track-v1', name: 'V1', kind: 'video', order: 0 }),
+      makeTimelineTrack({
+        id: 'track-a1',
+        name: 'A1',
+        kind: 'audio',
+        order: 1,
+        locked: true,
+      }),
+    ])
+    useItemsStore.getState().setItems([video, audio])
+    const { result } = renderHook(() => useTrackPush(video, 10))
+
+    act(() => result.current.handleTrackPushStart(makeMouseEvent()))
+
+    expect(result.current.isTrackPushActive).toBe(false)
+    expect(useTrackPushPreviewStore.getState().anchorItemId).toBeNull()
+    expect(useSelectionStore.getState().dragState).toBeNull()
+  })
+})

src/features/timeline/hooks/use-track-push.ts

@@ -10,6 +10,7 @@ import { useSnapCalculator } from './use-snap-calculator'
 import { trackPushItems } from '../stores/actions/item-actions'
 import type { SnapTarget } from '../types/drag'
 import { setActiveSnapTargetIfChanged } from '../utils/snap-target-state'
+import { partitionItemMutationIdsByLock } from '../utils/track-lock-invariants'
 
 interface TrackPushState {
   isActive: boolean
@@ -145,16 +146,19 @@ export function useTrackPush(
       e.preventDefault()
       commitPreviewFrameToCurrentFrame()
 
-      const { items: allItems, itemsByTrackId } = useItemsStore.getState()
+      const { items: allItems, itemsByTrackId, tracks } = useItemsStore.getState()
       const cutFrame = item.from
 
-      // Collect ALL items at or after the anchor's position, across every track
-      const shiftedIds = new Set<string>()
-      for (const ti of allItems) {
-        if (ti.from >= cutFrame) {
-          shiftedIds.add(ti.id)
-        }
-      }
+      // Locked tracks stay fixed. If one proposed item belongs to a linked
+      // cohort with a locked companion, reject the gesture instead of
+      // previewing an A/V desync that the commit cannot accept.
+      const mutationPartition = partitionItemMutationIdsByLock({
+        items: allItems,
+        tracks,
+        itemIds: allItems.filter((candidate) => candidate.from >= cutFrame).map(({ id }) => id),
+      })
+      const shiftedIds = new Set(mutationPartition.allowedIds)
+      if (mutationPartition.blockedByLockedLinkedCohort || !shiftedIds.has(item.id)) return
 
       // Compute the tightest gap across all tracks.
       // Per track, find the first shifted item and the last non-shifted item