From ebb7410061bdcabe9ce2dc6b49a7d6c6b53c0ac4 Mon Sep 17 00:00:00 2001
From: ChuxiJ <junmin@acestudio.ai>
Date: Fri, 27 Mar 2026 14:22:19 +0800
Subject: [PATCH] feat: add follow actions for session clips and scenes

Implement follow actions system that allows clips to automatically
trigger other clips when they finish playing, similar to Ableton Live.

- Add FollowActionType, FollowActionConfig types to project.ts
- Add followAction field to SessionClipSlot, followActionsEnabled to SessionState
- Add 'follow-action' to SessionPendingLaunch type union
- Create src/utils/followActions.ts with clip group detection, action resolution,
  and probability rolling utilities
- Add store actions: setSessionSlotFollowAction, setSessionFollowActionsEnabled,
  scheduleFollowAction
- Handle follow-action in commitPendingSessionLaunches
- Add UI: global toggle button, follow action badge on clips, context menu
  with action A/B selectors, chance slider, and time input
- 29 comprehensive unit tests covering utilities and store actions

Closes #920

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/components/session/SessionView.tsx | 127 ++++++++++++-
 src/store/projectStore.ts              | 104 +++++++++++
 src/types/project.ts                   |  25 ++-
 src/utils/followActions.ts             | 107 +++++++++++
 tests/unit/followActions.test.ts       | 236 +++++++++++++++++++++++++
 tests/unit/followActionsStore.test.ts  | 194 ++++++++++++++++++++
 6 files changed, 791 insertions(+), 2 deletions(-)
 create mode 100644 src/utils/followActions.ts
 create mode 100644 tests/unit/followActions.test.ts
 create mode 100644 tests/unit/followActionsStore.test.ts

diff --git a/src/components/session/SessionView.tsx b/src/components/session/SessionView.tsx
index 87cb684c..4007da1b 100644
--- a/src/components/session/SessionView.tsx
+++ b/src/components/session/SessionView.tsx
@@ -9,7 +9,7 @@ import { useSessionDragDrop, type SessionDragState, type SessionDropTarget } fro
 import { ContextMenuWrapper, ContextMenuSeparator, ContextMenuItem } from '../ui/ContextMenu';
 import { ColorSwatchPalette } from '../ui/ColorSwatchPalette';
 import { SessionMixer } from './SessionMixer';
-import type { Clip, Track, SessionLaunchQuantization, SessionLaunchMode, SessionClipSlot, SessionPendingLaunch, SessionScene, SceneFollowActionType } from '../../types/project';
+import type { Clip, Track, SessionLaunchQuantization, SessionLaunchMode, SessionClipSlot, SessionPendingLaunch, SessionScene, SceneFollowActionType, FollowActionType, FollowActionConfig } from '../../types/project';
 
 const LAUNCH_MODE_OPTIONS: SessionLaunchMode[] = ['trigger', 'gate', 'toggle', 'repeat'];
 
@@ -80,8 +80,20 @@ interface SlotContextMenuState {
   currentColor: string | null;
   legato: boolean;
   currentLaunchMode: SessionLaunchMode;
+  followAction?: FollowActionConfig;
 }
 
+const CLIP_FOLLOW_ACTION_OPTIONS: { value: FollowActionType; label: string }[] = [
+  { value: 'stop', label: 'Stop' },
+  { value: 'again', label: 'Again' },
+  { value: 'previous', label: 'Previous' },
+  { value: 'next', label: 'Next' },
+  { value: 'first', label: 'First' },
+  { value: 'last', label: 'Last' },
+  { value: 'any', label: 'Any' },
+  { value: 'other', label: 'Other' },
+];
+
 
 export function SessionView() {
   const project = useProjectStore((s) => s.project);
@@ -94,6 +106,8 @@ export function SessionView() {
   const setSessionSlotColor = useProjectStore((s) => s.setSessionSlotColor);
   const setSessionSlotLegato = useProjectStore((s) => s.setSessionSlotLegato);
   const setSessionSlotLaunchMode = useProjectStore((s) => s.setSessionSlotLaunchMode);
+  const setSessionSlotFollowAction = useProjectStore((s) => s.setSessionSlotFollowAction);
+  const setSessionFollowActionsEnabled = useProjectStore((s) => s.setSessionFollowActionsEnabled);
   const selectedSessionSlot = useUIStore((s) => s.selectedSessionSlot);
   const setSelectedSessionSlot = useUIStore((s) => s.setSelectedSessionSlot);
   const setKeyboardContext = useUIStore((s) => s.setKeyboardContext);
@@ -135,6 +149,20 @@ export function SessionView() {
     }
   }, [colorMenu, setSessionSlotLaunchMode]);
 
+  const handleFollowActionChange = useCallback((field: string, value: string | number | boolean) => {
+    if (!colorMenu) return;
+    setSessionSlotFollowAction(colorMenu.slotId, { [field]: value });
+    // Update local state to reflect change immediately
+    setColorMenu((prev) => {
+      if (!prev) return null;
+      const defaultFA: FollowActionConfig = { actionA: 'next', actionB: 'stop', chanceA: 1, time: 4, enabled: true };
+      return {
+        ...prev,
+        followAction: { ...(prev.followAction ?? defaultFA), [field]: value },
+      };
+    });
+  }, [colorMenu, setSessionSlotFollowAction]);
+
   // Set keyboard context to 'session' on mount, restore previous on unmount
   useEffect(() => {
     const previousScope = useUIStore.getState().keyboardContext.scope;
@@ -166,6 +194,7 @@ export function SessionView() {
   const sessionSlots = project.session?.slots ?? [];
   const pendingLaunches = project.session?.pendingLaunches ?? [];
   const scenes = project.session?.scenes ?? [];
+  const followActionsEnabled = project.session?.followActionsEnabled !== false;
 
   return (
     <div className="flex-1 min-w-0 bg-[radial-gradient(circle_at_top,#313131_0%,#202020_55%,#171717_100%)] border-l border-[#111] overflow-auto">
@@ -190,6 +219,17 @@ export function SessionView() {
                 ))}
               </select>
             </label>
+            <button
+              onClick={() => setSessionFollowActionsEnabled(!followActionsEnabled)}
+              className={`px-3 py-1.5 rounded-md text-[11px] font-medium transition-colors ${
+                followActionsEnabled
+                  ? 'bg-purple-600/30 text-purple-300 border border-purple-500/50'
+                  : 'bg-[#2a2a2a] text-zinc-500 hover:bg-[#343434]'
+              }`}
+              aria-label={followActionsEnabled ? 'Disable follow actions' : 'Enable follow actions'}
+            >
+              Follow Actions {followActionsEnabled ? 'ON' : 'OFF'}
+            </button>
             <button
               onClick={() => void toggleSessionArrangementRecording()}
               className={`px-3 py-1.5 rounded-md text-[11px] font-medium transition-colors ${
@@ -372,6 +412,81 @@ export function SessionView() {
               setColorMenu(null);
             }}
           />
+          <ContextMenuSeparator />
+          <div className="px-3 py-1 text-[10px] uppercase tracking-[0.16em] text-zinc-400">
+            Follow Action
+          </div>
+          <div className="px-3 py-1 flex items-center gap-2">
+            <label className="flex items-center gap-1.5 text-[11px] text-zinc-300 cursor-pointer">
+              <input
+                type="checkbox"
+                checked={colorMenu.followAction?.enabled ?? false}
+                onChange={(e) => handleFollowActionChange('enabled', e.target.checked)}
+                className="accent-purple-500"
+                aria-label="Enable follow action for this slot"
+              />
+              Enabled
+            </label>
+          </div>
+          {(colorMenu.followAction?.enabled) && (
+            <>
+              <div className="px-3 py-1 flex items-center gap-2">
+                <label className="text-[11px] text-zinc-400 w-10">A:</label>
+                <select
+                  value={colorMenu.followAction?.actionA ?? 'next'}
+                  onChange={(e) => handleFollowActionChange('actionA', e.target.value)}
+                  className="flex-1 rounded bg-[#2a2a2a] border border-[#444] px-1.5 py-0.5 text-[11px] text-zinc-200 outline-none"
+                  aria-label="Follow action A"
+                >
+                  {CLIP_FOLLOW_ACTION_OPTIONS.map((opt) => (
+                    <option key={opt.value} value={opt.value}>{opt.label}</option>
+                  ))}
+                </select>
+              </div>
+              <div className="px-3 py-1 flex items-center gap-2">
+                <label className="text-[11px] text-zinc-400 w-10">B:</label>
+                <select
+                  value={colorMenu.followAction?.actionB ?? 'stop'}
+                  onChange={(e) => handleFollowActionChange('actionB', e.target.value)}
+                  className="flex-1 rounded bg-[#2a2a2a] border border-[#444] px-1.5 py-0.5 text-[11px] text-zinc-200 outline-none"
+                  aria-label="Follow action B"
+                >
+                  {CLIP_FOLLOW_ACTION_OPTIONS.map((opt) => (
+                    <option key={opt.value} value={opt.value}>{opt.label}</option>
+                  ))}
+                </select>
+              </div>
+              <div className="px-3 py-1 flex items-center gap-2">
+                <label className="text-[11px] text-zinc-400 w-10">A%:</label>
+                <input
+                  type="range"
+                  min={0}
+                  max={100}
+                  value={Math.round((colorMenu.followAction?.chanceA ?? 1) * 100)}
+                  onChange={(e) => handleFollowActionChange('chanceA', Number(e.target.value) / 100)}
+                  className="flex-1 accent-purple-500"
+                  aria-label="Follow action A probability"
+                />
+                <span className="text-[10px] text-zinc-400 w-8 text-right">
+                  {Math.round((colorMenu.followAction?.chanceA ?? 1) * 100)}%
+                </span>
+              </div>
+              <div className="px-3 py-1 flex items-center gap-2">
+                <label className="text-[11px] text-zinc-400 w-10">Time:</label>
+                <input
+                  type="number"
+                  min={0.25}
+                  max={64}
+                  step={0.25}
+                  value={colorMenu.followAction?.time ?? 4}
+                  onChange={(e) => handleFollowActionChange('time', Number(e.target.value))}
+                  className="w-16 rounded bg-[#2a2a2a] border border-[#444] px-1.5 py-0.5 text-[11px] text-zinc-200 outline-none"
+                  aria-label="Follow action time in beats"
+                />
+                <span className="text-[10px] text-zinc-400">beats</span>
+              </div>
+            </>
+          )}
         </ContextMenuWrapper>
       )}
 
@@ -651,6 +766,7 @@ function FragmentRow({
             currentColor: slotColor,
             legato: slot.legato ?? false,
             currentLaunchMode: slotLaunchMode,
+            followAction: slot.followAction,
           });
         };
 
@@ -760,6 +876,15 @@ function FragmentRow({
                     {launchModeBadge}
                   </span>
                 )}
+                {slot?.followAction?.enabled && (
+                  <span
+                    className="absolute top-1 left-6 rounded bg-purple-600/80 px-1 py-0.5 text-[9px] font-semibold text-white leading-none pointer-events-none"
+                    title={`Follow: ${slot.followAction.actionA} / ${slot.followAction.actionB}`}
+                    data-testid={`follow-badge-${slot.id}`}
+                  >
+                    &#x2192;
+                  </span>
+                )}
                 {hasOverride && (
                   <span
                     className="absolute top-1 right-1 rounded bg-daw-accent/80 px-1 py-0.5 text-[9px] font-semibold text-white leading-none pointer-events-none"
diff --git a/src/store/projectStore.ts b/src/store/projectStore.ts
index 72f62284..1a3e465c 100644
--- a/src/store/projectStore.ts
+++ b/src/store/projectStore.ts
@@ -56,6 +56,7 @@ import type {
   DrumMachineConfig,
   DrumKitName,
   SamplerConfig,
+  FollowActionConfig,
   SessionClipSlot,
   SessionLaunchEvent,
   SessionLaunchMode,
@@ -114,6 +115,7 @@ import { encodeMidiFile, parseMidiFile } from '../utils/midi';
 import { encodeMidiFile as encodeMultiTrackMidiFile, type MidiExportTrack } from '../utils/midiEncoder';
 import { clampClipFadeDurations } from '../utils/clipFade';
 import { getSynthPresetById } from '../data/synthPresets';
+import { detectClipGroups, resolveFollowAction, rollFollowAction } from '../utils/followActions';
 import { extractGroove, applyGroove, type ExtractGrooveOptions, type ApplyGrooveOptions } from '../utils/groovePool';
 import type { GrooveTemplate } from '../types/project';
 import { toastError, toastSuccess } from '../hooks/useToast';
@@ -723,6 +725,9 @@ export interface ProjectState extends MidiSliceActions {
   stopSessionTrack: (trackId: string) => void;
   stopAllSessionClips: () => void;
   commitPendingSessionLaunches: (currentTime: number) => void;
+  setSessionSlotFollowAction: (slotId: string, config: Partial<import('../types/project').FollowActionConfig>) => void;
+  setSessionFollowActionsEnabled: (enabled: boolean) => void;
+  scheduleFollowAction: (trackId: string, currentSlotId: string, launchTime: number) => void;
   startSessionArrangementRecording: (startTime?: number) => void;
   stopSessionArrangementRecording: (endTime?: number) => Clip[];
   moveSessionSlotClip: (sourceSlotId: string, targetSlotId: string) => void;
@@ -5200,6 +5205,15 @@ export const useProjectStore = create<ProjectState>()(
         nextProject = applySessionTrackLaunch(nextProject, launch.trackId, null, launch.executeAt, 'stop');
         continue;
       }
+      if (launch.type === 'follow-action' && launch.trackId) {
+        if (launch.clipId) {
+          nextProject = applySessionTrackLaunch(nextProject, launch.trackId, launch.clipId, launch.executeAt, 'clip', launch.sceneId ?? null);
+        } else {
+          // follow-action resolved to 'stop'
+          nextProject = applySessionTrackLaunch(nextProject, launch.trackId, null, launch.executeAt, 'stop');
+        }
+        continue;
+      }
       if (launch.type === 'stop-all') {
         for (const track of nextProject.tracks) {
           nextProject = applySessionTrackLaunch(nextProject, track.id, null, launch.executeAt, 'stop');
@@ -5210,6 +5224,96 @@ export const useProjectStore = create<ProjectState>()(
     set({ project: nextProject });
   },
 
+  setSessionSlotFollowAction: (slotId, config) => {
+    const state = get();
+    if (!state.project) return;
+    const session = ensureProjectSession(state.project).session!;
+    const slotIndex = session.slots.findIndex((s) => s.id === slotId);
+    if (slotIndex === -1) return;
+
+    _pushHistory(state.project);
+    const currentSlot = session.slots[slotIndex];
+    const defaultConfig: FollowActionConfig = {
+      actionA: 'next',
+      actionB: 'stop',
+      chanceA: 1,
+      time: 4,
+      enabled: true,
+    };
+    const merged: FollowActionConfig = {
+      ...(currentSlot.followAction ?? defaultConfig),
+      ...config,
+    };
+
+    const nextSlots = [...session.slots];
+    nextSlots[slotIndex] = { ...currentSlot, followAction: merged };
+    set({
+      project: {
+        ...state.project,
+        updatedAt: Date.now(),
+        session: { ...session, slots: nextSlots },
+      },
+    });
+  },
+
+  setSessionFollowActionsEnabled: (enabled) => {
+    const state = get();
+    if (!state.project) return;
+    const session = ensureProjectSession(state.project).session!;
+
+    _pushHistory(state.project);
+    set({
+      project: {
+        ...state.project,
+        updatedAt: Date.now(),
+        session: { ...session, followActionsEnabled: enabled },
+      },
+    });
+  },
+
+  scheduleFollowAction: (trackId, currentSlotId, launchTime) => {
+    const state = get();
+    if (!state.project) return;
+    const session = ensureProjectSession(state.project).session!;
+
+    // Check global toggle (default true)
+    if (session.followActionsEnabled === false) return;
+
+    const currentSlot = session.slots.find((s) => s.id === currentSlotId);
+    if (!currentSlot?.followAction?.enabled) return;
+
+    const followAction = currentSlot.followAction;
+
+    // Detect the clip group containing the current slot
+    const groups = detectClipGroups(session.slots, session.scenes, trackId);
+    const group = groups.find((g) => g.some((s) => s.id === currentSlotId));
+    if (!group) return;
+
+    // Roll A/B and resolve target
+    const action = rollFollowAction(followAction);
+    const targetSlot = resolveFollowAction(action, currentSlot, group);
+
+    // Calculate fire time: launchTime + followAction.time beats
+    const beatDuration = 60 / Math.max(1, state.project.bpm);
+    const executeAt = launchTime + followAction.time * beatDuration;
+
+    // Queue a follow-action pending launch
+    const nextSession = queuePendingSessionLaunch(session, {
+      type: 'follow-action',
+      trackId,
+      sceneId: targetSlot?.sceneId,
+      clipId: targetSlot?.clipId ?? null,
+      executeAt,
+    });
+
+    set({
+      project: {
+        ...state.project,
+        session: nextSession,
+      },
+    });
+  },
+
   startSessionArrangementRecording: (startTime) => {
     const state = get();
     if (!state.project) return;
diff --git a/src/types/project.ts b/src/types/project.ts
index d1fb717b..a9dcd70d 100644
--- a/src/types/project.ts
+++ b/src/types/project.ts
@@ -961,6 +961,25 @@ export type SessionLaunchMode = 'trigger' | 'gate' | 'toggle' | 'repeat';
 /** Action to perform automatically when a scene finishes playing. */
 export type SceneFollowActionType = 'none' | 'next' | 'previous' | 'random' | 'stop';
 
+// ─── Follow Action Types ─────────────────────────────────────────────────────
+
+/** The type of follow action to perform when a clip finishes playing. */
+export type FollowActionType = 'stop' | 'again' | 'previous' | 'next' | 'first' | 'last' | 'any' | 'other';
+
+/** Configuration for a follow action on a session clip slot. */
+export interface FollowActionConfig {
+  /** Primary follow action. */
+  actionA: FollowActionType;
+  /** Secondary follow action. */
+  actionB: FollowActionType;
+  /** Probability of action A (0-1). Action B probability = 1 - chanceA. */
+  chanceA: number;
+  /** Follow action trigger time in beats (e.g., 4 = 1 bar in 4/4). */
+  time: number;
+  /** Whether this follow action is enabled. */
+  enabled: boolean;
+}
+
 export interface SessionScene {
   id: string;
   name: string;
@@ -990,11 +1009,13 @@ export interface SessionClipSlot {
   legato?: boolean;
   /** Clip launch behavior: trigger (default), gate, toggle, or repeat. */
   launchMode?: SessionLaunchMode;
+  /** Follow action configuration for this clip slot. */
+  followAction?: FollowActionConfig;
 }
 
 export interface SessionPendingLaunch {
   id: string;
-  type: 'clip' | 'scene' | 'stop-track' | 'stop-all';
+  type: 'clip' | 'scene' | 'stop-track' | 'stop-all' | 'follow-action';
   executeAt: number;
   requestedAt: number;
   trackId?: string;
@@ -1024,6 +1045,8 @@ export interface SessionState {
   recordedLaunches: SessionLaunchEvent[];
   lastLaunchedSceneId: string | null;
   lastLaunchAt: number | null;
+  /** Global toggle for follow actions. When false, no follow actions fire. Default true. */
+  followActionsEnabled?: boolean;
 }
 
 /** A saved project template — a snapshot of project settings and track layout (without audio). */
diff --git a/src/utils/followActions.ts b/src/utils/followActions.ts
new file mode 100644
index 00000000..16e0e38e
--- /dev/null
+++ b/src/utils/followActions.ts
@@ -0,0 +1,107 @@
+import type {
+  SessionClipSlot,
+  SessionScene,
+  FollowActionConfig,
+  FollowActionType,
+} from '../types/project';
+
+/**
+ * Detect clip groups — consecutive occupied slots on the same track,
+ * ordered by scene index. Empty slots act as group boundaries.
+ */
+export function detectClipGroups(
+  slots: SessionClipSlot[],
+  scenes: SessionScene[],
+  trackId: string,
+): SessionClipSlot[][] {
+  // Build a map from sceneId -> scene index for ordering
+  const sceneIndexMap = new Map(scenes.map((s) => [s.id, s.index]));
+
+  // Filter to the target track and sort by scene index
+  const trackSlots = slots
+    .filter((s) => s.trackId === trackId)
+    .sort((a, b) => (sceneIndexMap.get(a.sceneId) ?? 0) - (sceneIndexMap.get(b.sceneId) ?? 0));
+
+  const groups: SessionClipSlot[][] = [];
+  let currentGroup: SessionClipSlot[] = [];
+
+  for (const slot of trackSlots) {
+    if (slot.clipId !== null) {
+      currentGroup.push(slot);
+    } else {
+      if (currentGroup.length > 0) {
+        groups.push(currentGroup);
+        currentGroup = [];
+      }
+    }
+  }
+
+  if (currentGroup.length > 0) {
+    groups.push(currentGroup);
+  }
+
+  return groups;
+}
+
+/**
+ * Resolve a follow action type to the target clip slot.
+ * Returns null for 'stop' action (meaning stop playback).
+ */
+export function resolveFollowAction(
+  action: FollowActionType,
+  currentSlot: SessionClipSlot,
+  group: SessionClipSlot[],
+): SessionClipSlot | null {
+  const currentIndex = group.findIndex((s) => s.id === currentSlot.id);
+  if (currentIndex === -1) return null;
+
+  switch (action) {
+    case 'stop':
+      return null;
+
+    case 'again':
+      return currentSlot;
+
+    case 'next': {
+      const nextIndex = (currentIndex + 1) % group.length;
+      return group[nextIndex];
+    }
+
+    case 'previous': {
+      const prevIndex = (currentIndex - 1 + group.length) % group.length;
+      return group[prevIndex];
+    }
+
+    case 'first':
+      return group[0];
+
+    case 'last':
+      return group[group.length - 1];
+
+    case 'any': {
+      const randomIndex = Math.floor(Math.random() * group.length);
+      return group[randomIndex];
+    }
+
+    case 'other': {
+      if (group.length <= 1) {
+        // Fallback: only one clip, play again
+        return currentSlot;
+      }
+      const others = group.filter((s) => s.id !== currentSlot.id);
+      const randomIndex = Math.floor(Math.random() * others.length);
+      return others[randomIndex];
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Roll between action A and action B based on the configured probability.
+ * Returns action A with probability chanceA, action B otherwise.
+ */
+export function rollFollowAction(config: FollowActionConfig): FollowActionType {
+  return Math.random() < config.chanceA ? config.actionA : config.actionB;
+}
diff --git a/tests/unit/followActions.test.ts b/tests/unit/followActions.test.ts
new file mode 100644
index 00000000..24a41032
--- /dev/null
+++ b/tests/unit/followActions.test.ts
@@ -0,0 +1,236 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  detectClipGroups,
+  resolveFollowAction,
+  rollFollowAction,
+} from '../../src/utils/followActions';
+import type {
+  SessionClipSlot,
+  SessionScene,
+  FollowActionConfig,
+  FollowActionType,
+} from '../../src/types/project';
+
+function makeScene(index: number): SessionScene {
+  return { id: `scene-${index}`, name: `Scene ${index + 1}`, index };
+}
+
+function makeSlot(
+  trackId: string,
+  sceneId: string,
+  clipId: string | null,
+  overrides: Partial<SessionClipSlot> = {},
+): SessionClipSlot {
+  return {
+    id: `slot-${trackId}-${sceneId}`,
+    trackId,
+    sceneId,
+    clipId,
+    ...overrides,
+  };
+}
+
+function makeConfig(overrides: Partial<FollowActionConfig> = {}): FollowActionConfig {
+  return {
+    actionA: 'next',
+    actionB: 'stop',
+    chanceA: 1,
+    time: 4,
+    enabled: true,
+    ...overrides,
+  };
+}
+
+describe('detectClipGroups', () => {
+  it('detects a single group of consecutive occupied slots', () => {
+    const scenes = [makeScene(0), makeScene(1), makeScene(2)];
+    const slots = [
+      makeSlot('t1', 'scene-0', 'clip-a'),
+      makeSlot('t1', 'scene-1', 'clip-b'),
+      makeSlot('t1', 'scene-2', 'clip-c'),
+    ];
+
+    const groups = detectClipGroups(slots, scenes, 't1');
+    expect(groups).toHaveLength(1);
+    expect(groups[0].map((s) => s.clipId)).toEqual(['clip-a', 'clip-b', 'clip-c']);
+  });
+
+  it('splits groups at empty slots', () => {
+    const scenes = [makeScene(0), makeScene(1), makeScene(2), makeScene(3)];
+    const slots = [
+      makeSlot('t1', 'scene-0', 'clip-a'),
+      makeSlot('t1', 'scene-1', null),
+      makeSlot('t1', 'scene-2', 'clip-b'),
+      makeSlot('t1', 'scene-3', 'clip-c'),
+    ];
+
+    const groups = detectClipGroups(slots, scenes, 't1');
+    expect(groups).toHaveLength(2);
+    expect(groups[0].map((s) => s.clipId)).toEqual(['clip-a']);
+    expect(groups[1].map((s) => s.clipId)).toEqual(['clip-b', 'clip-c']);
+  });
+
+  it('returns empty array for track with no occupied slots', () => {
+    const scenes = [makeScene(0), makeScene(1)];
+    const slots = [
+      makeSlot('t1', 'scene-0', null),
+      makeSlot('t1', 'scene-1', null),
+    ];
+
+    const groups = detectClipGroups(slots, scenes, 't1');
+    expect(groups).toHaveLength(0);
+  });
+
+  it('filters slots by trackId', () => {
+    const scenes = [makeScene(0), makeScene(1)];
+    const slots = [
+      makeSlot('t1', 'scene-0', 'clip-a'),
+      makeSlot('t2', 'scene-0', 'clip-x'),
+      makeSlot('t1', 'scene-1', 'clip-b'),
+      makeSlot('t2', 'scene-1', null),
+    ];
+
+    const groups = detectClipGroups(slots, scenes, 't1');
+    expect(groups).toHaveLength(1);
+    expect(groups[0].map((s) => s.clipId)).toEqual(['clip-a', 'clip-b']);
+  });
+
+  it('handles single occupied slot as a group', () => {
+    const scenes = [makeScene(0), makeScene(1), makeScene(2)];
+    const slots = [
+      makeSlot('t1', 'scene-0', null),
+      makeSlot('t1', 'scene-1', 'clip-a'),
+      makeSlot('t1', 'scene-2', null),
+    ];
+
+    const groups = detectClipGroups(slots, scenes, 't1');
+    expect(groups).toHaveLength(1);
+    expect(groups[0].map((s) => s.clipId)).toEqual(['clip-a']);
+  });
+
+  it('orders slots by scene index', () => {
+    const scenes = [makeScene(0), makeScene(1), makeScene(2)];
+    // Slots given in reverse order
+    const slots = [
+      makeSlot('t1', 'scene-2', 'clip-c'),
+      makeSlot('t1', 'scene-0', 'clip-a'),
+      makeSlot('t1', 'scene-1', 'clip-b'),
+    ];
+
+    const groups = detectClipGroups(slots, scenes, 't1');
+    expect(groups).toHaveLength(1);
+    expect(groups[0].map((s) => s.clipId)).toEqual(['clip-a', 'clip-b', 'clip-c']);
+  });
+});
+
+describe('resolveFollowAction', () => {
+  const scenes = [makeScene(0), makeScene(1), makeScene(2), makeScene(3)];
+  const slots = [
+    makeSlot('t1', 'scene-0', 'clip-a'),
+    makeSlot('t1', 'scene-1', 'clip-b'),
+    makeSlot('t1', 'scene-2', 'clip-c'),
+  ];
+
+  // A helper to get a group for tests
+  function getGroup(): SessionClipSlot[] {
+    return detectClipGroups(slots, scenes, 't1')[0];
+  }
+
+  it('"next" resolves to the next clip in group', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('next', group[0], group);
+    expect(result?.clipId).toBe('clip-b');
+  });
+
+  it('"next" wraps to first from the last clip in group', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('next', group[2], group);
+    expect(result?.clipId).toBe('clip-a');
+  });
+
+  it('"previous" resolves to the previous clip in group', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('previous', group[1], group);
+    expect(result?.clipId).toBe('clip-a');
+  });
+
+  it('"previous" wraps to last from the first clip in group', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('previous', group[0], group);
+    expect(result?.clipId).toBe('clip-c');
+  });
+
+  it('"first" resolves to the first clip in group', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('first', group[2], group);
+    expect(result?.clipId).toBe('clip-a');
+  });
+
+  it('"last" resolves to the last clip in group', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('last', group[0], group);
+    expect(result?.clipId).toBe('clip-c');
+  });
+
+  it('"again" resolves to the same clip', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('again', group[1], group);
+    expect(result?.clipId).toBe('clip-b');
+  });
+
+  it('"stop" resolves to null (stop playback)', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('stop', group[0], group);
+    expect(result).toBeNull();
+  });
+
+  it('"any" resolves to some clip in the group', () => {
+    const group = getGroup();
+    const result = resolveFollowAction('any', group[0], group);
+    // Result is either null (stop) or a slot in the group
+    expect(result === null || group.some((s) => s.id === result?.id)).toBe(true);
+  });
+
+  it('"other" resolves to a different clip in the group', () => {
+    const group = getGroup();
+    // Run multiple times to exercise randomness; should never return the current slot
+    for (let i = 0; i < 20; i++) {
+      const result = resolveFollowAction('other', group[0], group);
+      expect(result).not.toBeNull();
+      expect(result!.clipId).not.toBe('clip-a');
+    }
+  });
+
+  it('"other" with single-clip group returns the same clip (fallback)', () => {
+    const singleSlot = makeSlot('t1', 'scene-0', 'clip-a');
+    const result = resolveFollowAction('other', singleSlot, [singleSlot]);
+    // When there's only one clip, "other" falls back to "again"
+    expect(result?.clipId).toBe('clip-a');
+  });
+});
+
+describe('rollFollowAction', () => {
+  it('always picks action A when chanceA is 1', () => {
+    const config = makeConfig({ actionA: 'next', actionB: 'stop', chanceA: 1 });
+    for (let i = 0; i < 50; i++) {
+      expect(rollFollowAction(config)).toBe('next');
+    }
+  });
+
+  it('always picks action B when chanceA is 0', () => {
+    const config = makeConfig({ actionA: 'next', actionB: 'stop', chanceA: 0 });
+    for (let i = 0; i < 50; i++) {
+      expect(rollFollowAction(config)).toBe('stop');
+    }
+  });
+
+  it('picks both actions over many rolls when chanceA is 0.5', () => {
+    const config = makeConfig({ actionA: 'next', actionB: 'stop', chanceA: 0.5 });
+    const results = new Set<FollowActionType>();
+    for (let i = 0; i < 200; i++) {
+      results.add(rollFollowAction(config));
+    }
+    expect(results.has('next')).toBe(true);
+    expect(results.has('stop')).toBe(true);
+  });
+});
diff --git a/tests/unit/followActionsStore.test.ts b/tests/unit/followActionsStore.test.ts
new file mode 100644
index 00000000..90c361f6
--- /dev/null
+++ b/tests/unit/followActionsStore.test.ts
@@ -0,0 +1,194 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { useProjectStore } from '../../src/store/projectStore';
+import { useTransportStore } from '../../src/store/transportStore';
+
+vi.mock('../../src/services/projectStorage', () => ({
+  saveProject: vi.fn(),
+}));
+
+describe('follow actions store', () => {
+  beforeEach(() => {
+    useProjectStore.setState(useProjectStore.getInitialState(), true);
+    useTransportStore.setState(useTransportStore.getInitialState(), true);
+    useProjectStore.getState().createProject({ bpm: 120, timeSignature: 4 });
+  });
+
+  function addTrackWithClips(count: number) {
+    const store = useProjectStore.getState();
+    const track = store.addTrack('drums');
+    const clips = [];
+    for (let i = 0; i < count; i++) {
+      const clip = store.addClip(track.id, {
+        startTime: i * 4,
+        duration: 4,
+        prompt: `Clip ${i + 1}`,
+        globalCaption: '',
+        lyrics: '',
+        source: 'uploaded',
+      });
+      clips.push(clip);
+    }
+    return { track, clips };
+  }
+
+  describe('setSessionSlotFollowAction', () => {
+    it('sets follow action on a slot with defaults', () => {
+      const { track } = addTrackWithClips(2);
+      const session = useProjectStore.getState().project!.session!;
+      const slot = session.slots.find((s) => s.trackId === track.id && s.clipId !== null);
+      expect(slot).toBeDefined();
+
+      useProjectStore.getState().setSessionSlotFollowAction(slot!.id, { actionA: 'next' });
+      const updatedSession = useProjectStore.getState().project!.session!;
+      const updatedSlot = updatedSession.slots.find((s) => s.id === slot!.id);
+      expect(updatedSlot?.followAction).toMatchObject({
+        actionA: 'next',
+        actionB: 'stop',
+        chanceA: 1,
+        time: 4,
+        enabled: true,
+      });
+    });
+
+    it('merges partial config with existing follow action', () => {
+      const { track } = addTrackWithClips(1);
+      const session = useProjectStore.getState().project!.session!;
+      const slot = session.slots.find((s) => s.trackId === track.id && s.clipId !== null)!;
+
+      useProjectStore.getState().setSessionSlotFollowAction(slot.id, { actionA: 'next', chanceA: 0.7 });
+      useProjectStore.getState().setSessionSlotFollowAction(slot.id, { actionB: 'again' });
+
+      const updatedSlot = useProjectStore.getState().project!.session!.slots.find((s) => s.id === slot.id);
+      expect(updatedSlot?.followAction).toMatchObject({
+        actionA: 'next',
+        actionB: 'again',
+        chanceA: 0.7,
+      });
+    });
+
+    it('is a no-op for invalid slot id', () => {
+      addTrackWithClips(1);
+      const before = useProjectStore.getState().project!.session!;
+      useProjectStore.getState().setSessionSlotFollowAction('nonexistent', { actionA: 'stop' });
+      const after = useProjectStore.getState().project!.session!;
+      expect(after.slots).toEqual(before.slots);
+    });
+  });
+
+  describe('setSessionFollowActionsEnabled', () => {
+    it('toggles global follow actions enabled', () => {
+      addTrackWithClips(1);
+      // Default is true (undefined means true)
+      expect(useProjectStore.getState().project!.session!.followActionsEnabled).toBeUndefined();
+
+      useProjectStore.getState().setSessionFollowActionsEnabled(false);
+      expect(useProjectStore.getState().project!.session!.followActionsEnabled).toBe(false);
+
+      useProjectStore.getState().setSessionFollowActionsEnabled(true);
+      expect(useProjectStore.getState().project!.session!.followActionsEnabled).toBe(true);
+    });
+  });
+
+  describe('scheduleFollowAction', () => {
+    it('queues a pending follow-action launch', () => {
+      const { track, clips } = addTrackWithClips(3);
+      const session = useProjectStore.getState().project!.session!;
+      const slot = session.slots.find((s) => s.trackId === track.id && s.clipId === clips[0].id)!;
+
+      // Configure follow action on first slot: always go to next
+      useProjectStore.getState().setSessionSlotFollowAction(slot.id, {
+        actionA: 'next',
+        actionB: 'next',
+        chanceA: 1,
+        time: 4,
+        enabled: true,
+      });
+
+      useProjectStore.getState().scheduleFollowAction(track.id, slot.id, 0);
+
+      const pending = useProjectStore.getState().project!.session!.pendingLaunches;
+      expect(pending).toHaveLength(1);
+      expect(pending[0].type).toBe('follow-action');
+      expect(pending[0].trackId).toBe(track.id);
+      expect(pending[0].clipId).toBe(clips[1].id); // next clip
+      // At 120 BPM, 4 beats = 2 seconds
+      expect(pending[0].executeAt).toBeCloseTo(2, 5);
+    });
+
+    it('does not schedule when follow action is disabled on slot', () => {
+      const { track, clips } = addTrackWithClips(2);
+      const session = useProjectStore.getState().project!.session!;
+      const slot = session.slots.find((s) => s.trackId === track.id && s.clipId === clips[0].id)!;
+
+      useProjectStore.getState().setSessionSlotFollowAction(slot.id, {
+        actionA: 'next',
+        enabled: false,
+      });
+
+      useProjectStore.getState().scheduleFollowAction(track.id, slot.id, 0);
+      const pending = useProjectStore.getState().project!.session!.pendingLaunches;
+      expect(pending).toHaveLength(0);
+    });
+
+    it('does not schedule when global follow actions are disabled', () => {
+      const { track, clips } = addTrackWithClips(2);
+      const session = useProjectStore.getState().project!.session!;
+      const slot = session.slots.find((s) => s.trackId === track.id && s.clipId === clips[0].id)!;
+
+      useProjectStore.getState().setSessionSlotFollowAction(slot.id, {
+        actionA: 'next',
+        enabled: true,
+      });
+      useProjectStore.getState().setSessionFollowActionsEnabled(false);
+
+      useProjectStore.getState().scheduleFollowAction(track.id, slot.id, 0);
+      const pending = useProjectStore.getState().project!.session!.pendingLaunches;
+      expect(pending).toHaveLength(0);
+    });
+
+    it('schedules a stop when follow action resolves to stop', () => {
+      const { track, clips } = addTrackWithClips(2);
+      const session = useProjectStore.getState().project!.session!;
+      const slot = session.slots.find((s) => s.trackId === track.id && s.clipId === clips[0].id)!;
+
+      useProjectStore.getState().setSessionSlotFollowAction(slot.id, {
+        actionA: 'stop',
+        actionB: 'stop',
+        chanceA: 1,
+        time: 4,
+        enabled: true,
+      });
+
+      useProjectStore.getState().scheduleFollowAction(track.id, slot.id, 0);
+      const pending = useProjectStore.getState().project!.session!.pendingLaunches;
+      expect(pending).toHaveLength(1);
+      expect(pending[0].type).toBe('follow-action');
+      expect(pending[0].clipId).toBeNull();
+    });
+
+    it('commitPendingSessionLaunches processes follow-action launches', () => {
+      const { track, clips } = addTrackWithClips(3);
+      const session = useProjectStore.getState().project!.session!;
+      const slot = session.slots.find((s) => s.trackId === track.id && s.clipId === clips[0].id)!;
+
+      // Set up follow action: next
+      useProjectStore.getState().setSessionSlotFollowAction(slot.id, {
+        actionA: 'next',
+        actionB: 'next',
+        chanceA: 1,
+        time: 4,
+        enabled: true,
+      });
+
+      // Schedule follow action
+      useProjectStore.getState().scheduleFollowAction(track.id, slot.id, 0);
+
+      // Commit at the right time (2 seconds at 120bpm)
+      useProjectStore.getState().commitPendingSessionLaunches(2);
+
+      const nextSession = useProjectStore.getState().project!.session!;
+      expect(nextSession.pendingLaunches).toHaveLength(0);
+      expect(nextSession.activeClipIdsByTrackId[track.id]).toBe(clips[1].id);
+    });
+  });
+});