feat(workspace): name tonight's first remaining leftover 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, remaining-leftover cues at a leftover return, 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 remaining leftover at a leftover return
   - 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 remaining leftover on the ready rehearsal map and tell the leftover part to stay out, or the band to count that leftover part out, at the leftover return.
 - 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 remaining leftover at a leftover return. `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.test.tsx

@@ -196,6 +196,114 @@ describe("Workspace", () => {
     );
   });
 
+  it("names tonight's first remaining leftover at a leftover 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.role_id === "lead-vocal"
+            ? { ...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.role_id === "lead-vocal"
+            ? { ...node, is_active: false }
+            : node
+        )
+      },
+      {
+        ...verse,
+        id: "bridge-1",
+        label: "bridge",
+        timeRange: {
+          start: verse.timeRange.end + 20,
+          end: verse.timeRange.end + 40
+        },
+        partGraph: verse.partGraph.map((node) =>
+          node.role_id === "lead-vocal" ? { ...node, is_active: false } : node
+        )
+      }
+    ];
+
+    render(<Workspace song={song} />);
+
+    const callout = screen.getByTestId("first-remaining-leftover");
+    expect(callout).toHaveTextContent("Tonight's first remaining leftover");
+    expect(callout).toHaveTextContent(
+      "Lead Vocal stays out at bridge while Keyboard 1 Right Hand comes back from chorus. Count Lead Vocal out from the top of bridge."
+    );
+  });
+
+  it("tells the remaining leftover to stay out at the leftover 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.role_id === "lead-vocal"
+            ? { ...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.role_id === "lead-vocal"
+            ? { ...node, is_active: false }
+            : node
+        )
+      },
+      {
+        ...verse,
+        id: "bridge-1",
+        label: "bridge",
+        timeRange: {
+          start: verse.timeRange.end + 20,
+          end: verse.timeRange.end + 40
+        },
+        partGraph: verse.partGraph.map((node) =>
+          node.role_id === "lead-vocal" ? { ...node, is_active: false } : node
+        )
+      }
+    ];
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" }));
+
+    expect(screen.getByTestId("first-remaining-leftover")).toHaveTextContent(
+      "Lead Vocal stays out at bridge while Keyboard 1 Right Hand comes back from chorus. Stay out from the top of bridge."
+    );
+  });
+
+  it("asks the player to confirm the remaining leftover when every part stays active", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-remaining-leftover")).toHaveTextContent(
+      "Tonight's first remaining leftover still needs a named leftover part that stays out at the leftover return. Confirm who stays out at that return before the first section."
+    );
+  });
+
   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 { firstRemainingLeftover } from "./firstRemainingLeftover";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
@@ -163,6 +164,25 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
         }
       )
     : t("workspaceFirstRangeMissing");
+  const namedRemainingLeftover = useMemo(
+    () => firstRemainingLeftover(song, activeRole),
+    [activeRole, song]
+  );
+  const firstRemainingLeftoverCopy = namedRemainingLeftover
+    ? fillRangeCopy(
+        t(
+          activeRole && activeRole === namedRemainingLeftover.remainingRoleId
+            ? "workspaceFirstRemainingLeftoverStayOut"
+            : "workspaceFirstRemainingLeftoverNamed"
+        ),
+        {
+          remainingRoleName: namedRemainingLeftover.remainingRoleName,
+          returningRoleName: namedRemainingLeftover.returningRoleName,
+          sectionLabel: namedRemainingLeftover.sectionLabel,
+          leftoverSectionLabel: namedRemainingLeftover.leftoverSectionLabel
+        }
+      )
+    : t("workspaceFirstRemainingLeftoverMissing");
 
   /** Handle the practice progress change internally by immutably updating the song state. */
   const handlePracticeProgressChange = (newProgress: number) => {
@@ -309,6 +329,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-rose-300/20 bg-rose-300/[0.07] p-4"
+            data-testid="first-remaining-leftover"
+            aria-label={t("workspaceFirstRemainingLeftoverTitle")}
+          >
+            <p className="text-xs font-black uppercase tracking-[0.24em] text-rose-200">{t("workspaceFirstRemainingLeftoverTitle")}</p>
+            <p className="mt-2 text-sm leading-6 text-slate-100">{firstRemainingLeftoverCopy}</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/firstRemainingLeftover.selected-role.test.ts

@@ -0,0 +1,122 @@
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import { firstRemainingLeftover } from "./firstRemainingLeftover";
+
+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("firstRemainingLeftover 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",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [
+          "keys-right",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, [
+          "bass-guitar",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(template, "outro-1", "outro", 60, ["lead-vocal"])
+      ]
+    };
+
+    expect(firstRemainingLeftover(song, "bass-guitar")).toEqual({
+      sectionLabel: "outro",
+      leftoverSectionLabel: "chorus",
+      fromSectionLabel: "verse",
+      remainingRoleId: "lead-vocal",
+      remainingRoleName: "Lead Vocal",
+      returningRoleId: "keys-right",
+      returningRoleName: "Keyboard 1 Right Hand"
+    });
+  });
+
+  it("does not tell a new dropout to stay out 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",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [
+          "keys-right",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, ["bass-guitar", "lead-vocal"])
+      ]
+    };
+
+    expect(firstRemainingLeftover(song, "bass-guitar")).toBeNull();
+  });
+
+  it("does not show another part's leftover cue to a selected part that stayed active", () => {
+    const seed = createDemoRehearsalSong();
+    const template = seed.sections[0]!;
+    const selectedRole = {
+      ...template.roles[0]!,
+      id: "always-active",
+      name: "Always Active"
+    };
+    const selectedTemplate: RehearsalSong["sections"][number] = {
+      ...template,
+      roles: [...template.roles, selectedRole],
+      partGraph: [
+        ...template.partGraph,
+        {
+          ...template.partGraph[0]!,
+          role_id: "always-active",
+          is_active: true,
+          handoff_to: [],
+          handoff_from: []
+        }
+      ]
+    };
+    const song: RehearsalSong = {
+      ...seed,
+      sections: [
+        sectionWithInactiveRoles(selectedTemplate, "verse-1", "verse", 0, [
+          "bass-guitar",
+          "keys-right",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(selectedTemplate, "chorus-1", "chorus", 20, [
+          "keys-right",
+          "lead-vocal"
+        ]),
+        sectionWithInactiveRoles(selectedTemplate, "bridge-1", "bridge", 40, ["lead-vocal"])
+      ]
+    };
+
+    expect(firstRemainingLeftover(song, "always-active")).toBeNull();
+  });
+});