feat(workspace): name tonight's first come-in 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, simplification guidance, transposition or setup cues, part-overlap cues, visible confidence, and rehearsal priorities. The ready workspace names tonight's first playable range and the first come-in so a sitting-out part knows where to return.
 - 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, the next instrument check, and the first come-in so a sitting-out part knows where to 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

@@ -5,6 +5,7 @@
 ### Added
 
 - 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.
+- Name tonight's first come-in on the ready rehearsal map and tell the player to play from the top of that section after sitting out.
 - 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, the next instrument check, and the first come-in so a sitting-out part knows where to 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,72 @@ describe("Workspace", () => {
     );
   });
 
+  it("names tonight's first come-in and the next return", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    const verse = song.sections[0]!;
+    song.sections = [
+      {
+        ...verse,
+        partGraph: verse.partGraph.map((node) =>
+          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 }
+      }
+    ];
+
+    render(<Workspace song={song} />);
+
+    const callout = screen.getByTestId("first-come-in");
+    expect(callout).toHaveTextContent("Tonight's first come-in");
+    expect(callout).toHaveTextContent(
+      "Keyboard 1 Right Hand comes in on chorus. Play from the top after sitting out of verse."
+    );
+  });
+
+  it("keeps the selected active part on tonight's first come-in", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    const verse = song.sections[0]!;
+    song.sections = [
+      {
+        ...verse,
+        partGraph: verse.partGraph.map((node) =>
+          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 }
+      }
+    ];
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" }));
+
+    expect(screen.getByTestId("first-come-in")).toHaveTextContent(
+      "Lead Vocal comes in on chorus. Play from the top after sitting out of verse."
+    );
+  });
+
+  it("asks the player to confirm the return when every part stays active", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-come-in")).toHaveTextContent(
+      "Tonight's first come-in still needs a return. Confirm where the sitting-out part comes back 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 { firstComeIn } from "./firstComeIn";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
@@ -163,6 +164,14 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
         }
       )
     : t("workspaceFirstRangeMissing");
+  const namedComeIn = useMemo(() => firstComeIn(song, activeRole), [activeRole, song]);
+  const firstComeInCopy = namedComeIn
+    ? fillRangeCopy(t("workspaceFirstComeInNamed"), {
+        roleName: namedComeIn.roleName,
+        sectionLabel: namedComeIn.sectionLabel,
+        fromSectionLabel: namedComeIn.fromSectionLabel
+      })
+    : t("workspaceFirstComeInMissing");
 
   /** Handle the practice progress change internally by immutably updating the song state. */
   const handlePracticeProgressChange = (newProgress: number) => {
@@ -309,6 +318,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-lime-300/20 bg-lime-300/[0.07] p-4"
+            data-testid="first-come-in"
+            aria-label={t("workspaceFirstComeInTitle")}
+          >
+            <p className="text-xs font-black uppercase tracking-[0.24em] text-lime-200">{t("workspaceFirstComeInTitle")}</p>
+            <p className="mt-2 text-sm leading-6 text-slate-100">{firstComeInCopy}</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/firstComeIn.conflict.test.ts

@@ -0,0 +1,37 @@
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import { firstComeIn } from "./firstComeIn";
+
+function songWithSameSectionConflict(reverse: boolean): RehearsalSong {
+  const seed = createDemoRehearsalSong();
+  const template = seed.sections[0]!;
+  const bass = template.partGraph.find((node) => node.role_id === "bass-guitar")!;
+  const others = template.partGraph.filter((node) => node.role_id !== "bass-guitar");
+  const inactiveBass = { ...bass, is_active: false };
+  const activeBass = { ...bass, is_active: true };
+  const conflict = {
+    ...template,
+    id: "verse-conflict",
+    label: "verse" as RehearsalSong["sections"][number]["label"],
+    timeRange: { start: 0, end: 20 },
+    partGraph: [
+      ...others,
+      ...(reverse ? [activeBass, inactiveBass] : [inactiveBass, activeBass])
+    ]
+  };
+  const later = {
+    ...template,
+    id: "verse-later",
+    label: "verse" as RehearsalSong["sections"][number]["label"],
+    timeRange: { start: 20, end: 40 }
+  };
+  return { ...seed, sections: [conflict, later] };
+}
+
+describe("firstComeIn conflicting section evidence", () => {
+  it("fails closed for false/true and true/false duplicates before a later active section", () => {
+    for (const reverse of [false, true]) {
+      expect(firstComeIn(songWithSameSectionConflict(reverse), "bass-guitar")).toBeNull();
+    }
+  });
+});

apps/desktop/src/features/workspace/firstComeIn.test.ts

@@ -0,0 +1,194 @@
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import { fillRangeCopy } from "./firstRangeSqueeze";
+import { firstComeIn } from "./firstComeIn";
+
+function withChorus(song: RehearsalSong): RehearsalSong {
+  const verse = song.sections[0]!;
+  const chorus = {
+    ...verse,
+    id: "chorus-1",
+    label: "chorus" as RehearsalSong["sections"][number]["label"],
+    timeRange: {
+      start: verse.timeRange.end,
+      end: verse.timeRange.end + 20
+    }
+  };
+  return { ...song, sections: [verse, chorus] };
+}
+
+function withSitOutThenComeIn(
+  song: RehearsalSong,
+  roleId: string,
+  sitOutActive: boolean | "omit" = false
+): RehearsalSong {
+  const twoSection = withChorus(song);
+  return {
+    ...twoSection,
+    sections: twoSection.sections.map((section, index) =>
+      index === 0
+        ? {
+            ...section,
+            partGraph: section.partGraph.map((node) => {
+              if (node.role_id !== roleId) {
+                return node;
+              }
+              if (sitOutActive === "omit") {
+                const rest: Record<string, unknown> = {
+                  role_id: node.role_id,
+                  handoff_to: node.handoff_to,
+                  handoff_from: node.handoff_from
+                };
+                return rest as RehearsalSong["sections"][number]["partGraph"][number];
+              }
+              return { ...node, is_active: sitOutActive };
+            })
+          }
+        : section
+    )
+  };
+}
+
+describe("firstComeIn", () => {
+  it("returns null on the demo song where every graph node is active", () => {
+    expect(firstComeIn(createDemoRehearsalSong())).toBeNull();
+    expect(firstComeIn(withChorus(createDemoRehearsalSong()))).toBeNull();
+  });
+
+  it("names the first explicit return from existing part-graph evidence", () => {
+    expect(firstComeIn(withSitOutThenComeIn(createDemoRehearsalSong(), "keys-right"))).toEqual({
+      sectionLabel: "chorus",
+      roleName: "Keyboard 1 Right Hand",
+      fromSectionLabel: "verse"
+    });
+  });
+
+  it("keeps the first return when a later section repeats the sit-out label", () => {
+    const song = withSitOutThenComeIn(createDemoRehearsalSong(), "keys-right");
+    const repeatedVerse = {
+      ...song.sections[1]!,
+      id: "verse-2",
+      label: "verse" as RehearsalSong["sections"][number]["label"]
+    };
+    const laterChorus = {
+      ...song.sections[1]!,
+      id: "chorus-2",
+      timeRange: {
+        start: song.sections[1]!.timeRange.end,
+        end: song.sections[1]!.timeRange.end + 20
+      }
+    };
+    song.sections = [song.sections[0]!, repeatedVerse, laterChorus];
+
+    expect(firstComeIn(song)).toEqual({
+      sectionLabel: "verse",
+      roleName: "Keyboard 1 Right Hand",
+      fromSectionLabel: "verse"
+    });
+  });
+
+  it("skips blank come-in labels until a named return exists", () => {
+    const song = withSitOutThenComeIn(createDemoRehearsalSong(), "keys-right");
+    song.sections[1] = {
+      ...song.sections[1]!,
+      label: "none" as RehearsalSong["sections"][number]["label"]
+    };
+    expect(firstComeIn(song)).toBeNull();
+  });
+
+  it("keeps the selected active part on tonight's first come-in", () => {
+    const song = withSitOutThenComeIn(createDemoRehearsalSong(), "lead-vocal");
+    expect(firstComeIn(song, "lead-vocal")).toEqual({
+      sectionLabel: "chorus",
+      roleName: "Lead Vocal",
+      fromSectionLabel: "verse"
+    });
+    expect(firstComeIn(song, "bass-guitar")).toBeNull();
+  });
+
+  it("ignores inherited is_active evidence", () => {
+    const song = withChorus(createDemoRehearsalSong());
+    const inherited = Object.create({
+      is_active: false,
+      role_id: "keys-right"
+    }) as RehearsalSong["sections"][number]["partGraph"][number];
+    song.sections[0] = {
+      ...song.sections[0]!,
+      partGraph: [inherited, ...song.sections[0]!.partGraph]
+    };
+    expect(firstComeIn(song)).toBeNull();
+  });
+
+  it("does not treat a missing is_active flag as a sit-out", () => {
+    expect(firstComeIn(withSitOutThenComeIn(createDemoRehearsalSong(), "keys-right", "omit"))).toBeNull();
+  });
+
+  it("does not treat the song's opening entrance as a come-in", () => {
+    expect(firstComeIn(withSitOutThenComeIn(createDemoRehearsalSong(), "keys-right", true))).toBeNull();
+  });
+
+  it("fails closed when the return section has no named role", () => {
+    const song = withSitOutThenComeIn(createDemoRehearsalSong(), "keys-right");
+    song.sections[1] = {
+      ...song.sections[1]!,
+      roles: song.sections[1]!.roles.map((role) =>
+        role.id === "keys-right" ? { ...role, name: "   " } : role
+      )
+    };
+    expect(firstComeIn(song)).toBeNull();
+  });
+
+  it("rejects inherited return-section roles as naming authority", () => {
+    const song = withSitOutThenComeIn(createDemoRehearsalSong(), "keys-right");
+    const returnSection = song.sections[1]!;
+    const returnWithoutOwnRoles = { ...returnSection } as Record<string, unknown>;
+    delete returnWithoutOwnRoles.roles;
+    song.sections[1] = Object.assign(
+      Object.create({ roles: returnSection.roles }),
+      returnWithoutOwnRoles
+    ) as RehearsalSong["sections"][number];
+
+    expect(firstComeIn(song)).toBeNull();
+  });
+
+  it("fails closed when the first active return has no trustworthy role name", () => {
+    const song = withSitOutThenComeIn(createDemoRehearsalSong(), "keys-right");
+    const chorus = song.sections[1]!;
+    const unnamedChorus = {
+      ...chorus,
+      roles: chorus.roles.map((role) =>
+        role.id === "keys-right" ? { ...role, name: "   " } : role
+      )
+    };
+    const bridge = {
+      ...chorus,
+      id: "bridge-1",
+      label: "bridge" as RehearsalSong["sections"][number]["label"],
+      timeRange: {
+        start: chorus.timeRange.end,
+        end: chorus.timeRange.end + 20
+      }
+    };
+    song.sections = [song.sections[0]!, unnamedChorus, bridge];
+
+    expect(firstComeIn(song)).toBeNull();
+  });
+
+  it("fails closed on malformed runtime roots", () => {
+    for (const malformed of [null, {}, { sections: {} }, { sections: [null] }]) {
+      expect(firstComeIn(malformed as unknown as RehearsalSong)).toBeNull();
+    }
+  });
+});
+
+describe("come-in copy filling", () => {
+  it("keeps rehearsal values literal", () => {
+    expect(
+      fillRangeCopy("{roleName} comes in on {sectionLabel} after {fromSectionLabel}.", {
+        roleName: "Bass {sectionLabel}",
+        sectionLabel: "chorus",
+        fromSectionLabel: "verse"
+      })
+    ).toBe("Bass {sectionLabel} comes in on chorus after verse.");
+  });
+});