feat(workspace): name tonight's first leftover return on the map

AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md
 
 ## Project overview
-- BandScope is a local-first desktop app for rehearsal prep: a practical song view with likely harmony by section and by instrument or vocal role, form and groove cues, stems, playable ranges, simplification guidance, transposition or setup cues, part-overlap cues, visible confidence, and rehearsal priorities.
+- BandScope is a local-first desktop app for rehearsal prep: a practical song view with likely harmony by section and by instrument or vocal role, form and groove cues, stems, playable ranges, leftover-return cues after a leftover sit-out, simplification guidance, transposition or setup cues, part-overlap cues, visible confidence, and rehearsal priorities.
 - Authoritative delivery rules live in `ARCHITECTURE.md`, `docs/plans/`, and the root verification scripts.
 - Brand, tone, UX copy, and prioritization rules live in `docs/brand-story.md` and must be applied to PRDs, TRDs, UI copy, onboarding, empty states, and error messages.
 - App security rules live in `docs/security/app-security.md` and must be applied to file handling, URL intake, subprocesses, IPC, WebView usage, model loading, updates, logging, cache handling, and export behavior.

ARCHITECTURE.md

@@ -82,7 +82,7 @@ Last updated: 2026-03-11
   - likely harmony by section and by role
   - section roadmap with entries, dropouts, pickups, stops, tags, and handoffs
   - groove and timing cues relevant to locking the band together
-  - playable ranges and density or overlap warnings, with the ready workspace naming tonight's first span and the next instrument check
+  - playable ranges and density or overlap warnings, with the ready workspace naming tonight's first span and tonight's first leftover return after a leftover sit-out
   - simplification, transposition, capo, tuning, or setup cues where applicable
   - role-specific rehearsal priorities and confidence flags
   - cue-sheet or chart-style exports that summarize the analysis in rehearsal-friendly form

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Name tonight's first leftover return on the ready rehearsal map and tell the leftover part to come back, or the band to count that leftover part in.
 - Name tonight's first playable range on the ready rehearsal map and tell the player to check that span on their instrument before the section.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.

CLAUDE.md

@@ -51,7 +51,7 @@ BandScope is a local-first desktop app for rehearsal prep: it turns a song into
 
 Three layers, decoupled through shared contracts:
 
-- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). The ready workspace names tonight's first playable range and the next instrument check. `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands, with a browser fallback that serves demo data when not running inside Tauri.
+- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). The ready workspace names tonight's first playable range and tonight's first leftover return after a leftover sit-out. `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands, with a browser fallback that serves demo data when not running inside Tauri.
 - `apps/desktop/src-tauri/src/main.rs` — the Rust orchestration boundary. Tauri commands (`start_analysis_job`, `get_analysis_job_status`, `select_local_audio_source`, `import_youtube_url`) validate untrusted input (project IDs, file paths, URLs) and spawn the Python engine as a subprocess. There is no loopback HTTP listener and no network path for local analysis.
 - `services/analysis-engine` — Python package `bandscope_analysis` (librosa/numpy). Entry point `cli.py` reads a JSON job request on stdin and prints a structured job-status JSON envelope on stdout (`--progress-jsonl` streams progress lines). `api.py` orchestrates the pipeline across the `separation`, `sections`, `roles`, `chords`, `ranges`, `temporal`, `transcription`, and `youtube` modules.
 

apps/desktop/src/features/workspace/Workspace.leftover-return.test.tsx

@@ -0,0 +1,30 @@
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { Workspace } from "./Workspace";
+
+const originalLanguage = navigator.language;
+
+function setNavigatorLanguage(language: string) {
+  Object.defineProperty(navigator, "language", {
+    configurable: true,
+    value: language
+  });
+}
+
+describe("Workspace leftover-return empty state", () => {
+  afterEach(() => {
+    setNavigatorLanguage(originalLanguage);
+  });
+
+  it("explains when a trustworthy all-active song needs no leftover-return cue", () => {
+    setNavigatorLanguage("en-US");
+    render(<Workspace song={createDemoRehearsalSong()} />);
+
+    const callout = screen.getByTestId("first-leftover-return");
+    expect(callout).toHaveTextContent(
+      "No leftover return is needed: every named part stays active. Rehearse from the first section without a count-back cue."
+    );
+    expect(callout).not.toHaveTextContent("still needs a named leftover part");
+  });
+});

apps/desktop/src/features/workspace/Workspace.test.tsx

@@ -196,6 +196,100 @@ describe("Workspace", () => {
     );
   });
 
+  it("names tonight's first leftover return after a leftover sit-out", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    const verse = song.sections[0]!;
+    song.sections = [
+      {
+        ...verse,
+        partGraph: verse.partGraph.map((node) =>
+          node.role_id === "bass-guitar" || node.role_id === "keys-right"
+            ? { ...node, is_active: false }
+            : node
+        )
+      },
+      {
+        ...verse,
+        id: "chorus-1",
+        label: "chorus",
+        timeRange: { start: verse.timeRange.end, end: verse.timeRange.end + 20 },
+        partGraph: verse.partGraph.map((node) =>
+          node.role_id === "keys-right" ? { ...node, is_active: false } : node
+        )
+      },
+      {
+        ...verse,
+        id: "bridge-1",
+        label: "bridge",
+        timeRange: {
+          start: verse.timeRange.end + 20,
+          end: verse.timeRange.end + 40
+        }
+      }
+    ];
+
+    render(<Workspace song={song} />);
+
+    const callout = screen.getByTestId("first-leftover-return");
+    expect(callout).toHaveTextContent("Tonight's first leftover return");
+    expect(callout).toHaveTextContent(
+      "Keyboard 1 Right Hand comes back at bridge after staying out of chorus. Count Keyboard 1 Right Hand in from the top of bridge."
+    );
+  });
+
+  it("tells the leftover part to come back at the named return", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    const verse = song.sections[0]!;
+    song.sections = [
+      {
+        ...verse,
+        partGraph: verse.partGraph.map((node) =>
+          node.role_id === "bass-guitar" || node.role_id === "keys-right"
+            ? { ...node, is_active: false }
+            : node
+        )
+      },
+      {
+        ...verse,
+        id: "chorus-1",
+        label: "chorus",
+        timeRange: { start: verse.timeRange.end, end: verse.timeRange.end + 20 },
+        partGraph: verse.partGraph.map((node) =>
+          node.role_id === "keys-right" ? { ...node, is_active: false } : node
+        )
+      },
+      {
+        ...verse,
+        id: "bridge-1",
+        label: "bridge",
+        timeRange: {
+          start: verse.timeRange.end + 20,
+          end: verse.timeRange.end + 40
+        }
+      }
+    ];
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Keyboard 1 Right Hand" }));
+
+    expect(screen.getByTestId("first-leftover-return")).toHaveTextContent(
+      "Keyboard 1 Right Hand comes back at bridge after staying out of chorus. Play from the top of bridge."
+    );
+  });
+
+  it("explains when no leftover return is needed because every part stays active", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-leftover-return")).toHaveTextContent(
+      "No leftover return is needed: every named part stays active. Rehearse from the first section without a count-back cue."
+    );
+  });
+
   it("falls back from blank planning copy and tolerates partial collaboration payloads", () => {
     setNavigatorLanguage("en-US");
     const song = createDemoRehearsalSong();

apps/desktop/src/features/workspace/Workspace.tsx

@@ -5,6 +5,7 @@ import { SectionRoadmap } from "./SectionRoadmap";
 import { GrooveMap } from "./GrooveMap";
 import { PracticeProgress } from "./PracticeProgress";
 import { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze";
+import { firstLeftoverReturn, hasTrustworthyAllActiveTimeline } from "./firstLeftoverReturn";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
@@ -163,6 +164,32 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
         }
       )
     : t("workspaceFirstRangeMissing");
+  const namedLeftoverReturn = useMemo(
+    () => firstLeftoverReturn(song, activeRole),
+    [activeRole, song]
+  );
+  const noLeftoverReturnNeeded = useMemo(
+    () => hasTrustworthyAllActiveTimeline(song),
+    [song]
+  );
+  const firstLeftoverReturnCopy = namedLeftoverReturn
+    ? fillRangeCopy(
+        t(
+          activeRole && activeRole === namedLeftoverReturn.leftoverRoleId
+            ? "workspaceFirstLeftoverReturnComeBack"
+            : "workspaceFirstLeftoverReturnNamed"
+        ),
+        {
+          leftoverRoleName: namedLeftoverReturn.leftoverRoleName,
+          sectionLabel: namedLeftoverReturn.sectionLabel,
+          leftoverSectionLabel: namedLeftoverReturn.leftoverSectionLabel
+        }
+      )
+    : t(
+        noLeftoverReturnNeeded
+          ? "workspaceFirstLeftoverReturnNone"
+          : "workspaceFirstLeftoverReturnMissing"
+      );
 
   /** Handle the practice progress change internally by immutably updating the song state. */
   const handlePracticeProgressChange = (newProgress: number) => {
@@ -309,6 +336,14 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
             <p className="text-xs font-black uppercase tracking-[0.24em] text-fuchsia-200">{t("workspaceFirstRangeTitle")}</p>
             <p className="mt-2 text-sm leading-6 text-slate-100">{firstRangeCopy}</p>
           </section>
+          <section
+            className="rounded-2xl border border-teal-300/20 bg-teal-300/[0.07] p-4"
+            data-testid="first-leftover-return"
+            aria-label={t("workspaceFirstLeftoverReturnTitle")}
+          >
+            <p className="text-xs font-black uppercase tracking-[0.24em] text-teal-200">{t("workspaceFirstLeftoverReturnTitle")}</p>
+            <p className="mt-2 text-sm leading-6 text-slate-100">{firstLeftoverReturnCopy}</p>
+          </section>
 
           <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
             <section className="rounded-2xl border border-cyan-300/20 bg-cyan-300/[0.06] p-4 md:col-span-2">

apps/desktop/src/features/workspace/firstLeftoverReturn.all-active.test.ts

@@ -0,0 +1,50 @@
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import { hasTrustworthyAllActiveTimeline } from "./firstLeftoverReturn";
+
+describe("hasTrustworthyAllActiveTimeline", () => {
+  it("accepts a complete named timeline when every graph role stays active", () => {
+    expect(hasTrustworthyAllActiveTimeline(createDemoRehearsalSong())).toBe(true);
+  });
+
+  it("rejects non-song roots and empty timelines", () => {
+    expect(hasTrustworthyAllActiveTimeline(null)).toBe(false);
+
+    const empty = createDemoRehearsalSong();
+    empty.sections = [];
+    expect(hasTrustworthyAllActiveTimeline(empty)).toBe(false);
+  });
+
+  it("rejects timelines without a named section", () => {
+    const song = createDemoRehearsalSong();
+    song.sections = song.sections.map((section) => ({ ...section, label: "   " }));
+
+    expect(hasTrustworthyAllActiveTimeline(song)).toBe(false);
+  });
+
+  it("rejects an inactive named role", () => {
+    const song = createDemoRehearsalSong();
+    const firstSection = song.sections[0]!;
+    firstSection.partGraph = firstSection.partGraph.map((node, index) =>
+      index === 0 ? { ...node, is_active: false } : node
+    );
+
+    expect(hasTrustworthyAllActiveTimeline(song)).toBe(false);
+  });
+
+  it("fails closed on malformed section and graph evidence", () => {
+    expect(
+      hasTrustworthyAllActiveTimeline({ sections: [null] })
+    ).toBe(false);
+
+    const song = createDemoRehearsalSong();
+    const malformed = song as unknown as {
+      sections: Array<{
+        partGraph: Array<Record<string, unknown>>;
+      }>;
+    };
+    delete malformed.sections[0]!.partGraph[0]!.is_active;
+
+    expect(hasTrustworthyAllActiveTimeline(song)).toBe(false);
+  });
+});

apps/desktop/src/features/workspace/firstLeftoverReturn.selected-role.test.ts

@@ -0,0 +1,120 @@
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import { firstLeftoverReturn } from "./firstLeftoverReturn";
+
+function sectionWithInactiveRoles(
+  template: RehearsalSong["sections"][number],
+  id: string,
+  label: RehearsalSong["sections"][number]["label"],
+  start: number,
+  inactiveRoleIds: readonly string[]
+): RehearsalSong["sections"][number] {
+  const inactive = new Set(inactiveRoleIds);
+  return {
+    ...template,
+    id,
+    label,
+    timeRange: { start, end: start + 20 },
+    partGraph: template.partGraph.map((node) => ({
+      ...node,
+      is_active: !inactive.has(node.role_id)
+    }))
+  };
+}
+
+describe("firstLeftoverReturn selected-role search", () => {
+  it("keeps searching after the selected part newly drops out during an earlier leftover sit-out", () => {
+    const seed = createDemoRehearsalSong();
+    const template = seed.sections[0]!;
+    const song: RehearsalSong = {
+      ...seed,
+      sections: [
+        sectionWithInactiveRoles(template, "verse-1", "verse", 0, [
+          "bass-guitar",
+          "keys-right"
+        ]),
+        sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [
+          "lead-vocal",
+          "keys-right"
+        ]),
+        sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, ["keys-right"]),
+        sectionWithInactiveRoles(template, "outro-1", "outro", 60, [])
+      ]
+    };
+
+    expect(firstLeftoverReturn(song, "lead-vocal")).toEqual({
+      sectionLabel: "outro",
+      leftoverSectionLabel: "bridge",
+      fromSectionLabel: "verse",
+      leftoverRoleId: "keys-right",
+      leftoverRoleName: "Keyboard 1 Right Hand"
+    });
+  });
+
+  it("does not show another cohort's leftover return to a continuously active selected role", () => {
+    const seed = createDemoRehearsalSong();
+    const template = seed.sections[0]!;
+    const song: RehearsalSong = {
+      ...seed,
+      sections: [
+        sectionWithInactiveRoles(template, "verse-1", "verse", 0, [
+          "bass-guitar",
+          "keys-right"
+        ]),
+        sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, ["keys-right"]),
+        sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, [])
+      ]
+    };
+
+    expect(firstLeftoverReturn(song, "lead-vocal")).toBeNull();
+  });
+
+  it("returns the first eligible leftover even when a later graph entry returns first", () => {
+    const seed = createDemoRehearsalSong();
+    const template = seed.sections[0]!;
+    const song: RehearsalSong = {
+      ...seed,
+      sections: [
+        sectionWithInactiveRoles(template, "verse-1", "verse", 0, [
+          "bass-guitar",
+          "keys-right",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [
+          "keys-right",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, ["keys-right"])
+      ]
+    };
+
+    expect(firstLeftoverReturn(song)).toEqual({
+      sectionLabel: "bridge",
+      leftoverSectionLabel: "chorus",
+      fromSectionLabel: "verse",
+      leftoverRoleId: "lead-vocal",
+      leftoverRoleName: "Lead Vocal"
+    });
+  });
+
+  it("does not tell a new dropout to come back from an earlier leftover sit-out", () => {
+    const seed = createDemoRehearsalSong();
+    const template = seed.sections[0]!;
+    const song: RehearsalSong = {
+      ...seed,
+      sections: [
+        sectionWithInactiveRoles(template, "verse-1", "verse", 0, [
+          "bass-guitar",
+          "keys-right"
+        ]),
+        sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [
+          "lead-vocal",
+          "keys-right"
+        ]),
+        sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, [])
+      ]
+    };
+
+    expect(firstLeftoverReturn(song, "lead-vocal")).toBeNull();
+  });
+});