feat(workspace): name tonight's first playable range on the map

AGENTS.md

@@ -83,7 +83,7 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 - Keep UI and analysis engine decoupled through shared contracts.
 - Prefer minimal, test-first changes for production code.
 - Prefer practical, friendly, rehearsal-first wording over academic or authority-heavy language.
-- Do not reduce the product to a chord analyzer when form, timing, player coordination, simplification, and setup cues are the real rehearsal blockers.
+- Do not reduce the product to a chord analyzer when form, timing, player coordination, playable ranges, simplification, and setup cues are the real rehearsal blockers.
 - Do not frame usability as a reason to accept weak analysis quality; BandScope should aim for both easy use and high accuracy.
 
 ## Safety

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
+  - playable ranges and density or overlap warnings, with the ready workspace naming tonight's first span and the next instrument check
   - 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 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). `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 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/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/SectionRoadmap.test.tsx

@@ -31,6 +31,52 @@ describe("SectionRoadmap", () => {
     expect(screen.getAllByText("큐").length).toBeGreaterThan(0);
     expect(screen.getAllByTitle("우선순위: high").length).toBeGreaterThan(0);
     expect(screen.getByText("사용자")).toBeTruthy();
+    expect(screen.getAllByText("음역").length).toBeGreaterThan(0);
+    expect(screen.getByText("C#2 — E3")).toBeTruthy();
+    expect(screen.getAllByText("verse 들어가기 전에 이 음역을 악기로 확인해 보세요.").length).toBeGreaterThan(0);
+  });
+
+  it("omits the range row when both notes are unnamed", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      range: { lowestNote: " ", highestNote: "none" }
+    };
+
+    render(<SectionRoadmap song={song} activeRole="bass-guitar" />);
+
+    expect(screen.queryByText("Range")).toBeNull();
+    expect(screen.queryByText(/Check this span on your instrument/i)).toBeNull();
+  });
+
+  it("omits the range row when the span is inverted instead of presenting it as valid", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      range: { lowestNote: "E3", highestNote: "C#2" }
+    };
+
+    render(<SectionRoadmap song={song} activeRole="bass-guitar" />);
+
+    expect(screen.queryByText("Range")).toBeNull();
+    expect(screen.queryByText(/Check this span on your instrument/i)).toBeNull();
+    expect(screen.queryByText(/E3 — C#2/)).toBeNull();
+  });
+
+  it("omits the range row when a note is not a scientific-pitch label", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      range: { lowestNote: "low-ish", highestNote: "E3" }
+    };
+
+    render(<SectionRoadmap song={song} activeRole="bass-guitar" />);
+
+    expect(screen.queryByText("Range")).toBeNull();
+    expect(screen.queryByText(/Check this span on your instrument/i)).toBeNull();
   });
 
   it("uses localized copy for chord edit prompts and control labels", () => {

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

@@ -2,6 +2,7 @@ import type { RehearsalSong, RehearsalRole } from "@bandscope/shared-types";
 import { useId, useMemo } from "react";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { ConfidenceBadge } from "./ConfidenceBadge";
+import { fillRangeCopy, playableRange } from "./firstRangeSqueeze";
 import { Card, CardContent, CardHeader } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
 import { Separator } from "@/components/ui/separator";
@@ -124,7 +125,9 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
             <CardContent className="p-4 space-y-4">
               {section.roles
                 .filter(role => !activeRole || role.id === activeRole)
-                .map(role => (
+                .map(role => {
+                  const validatedRange = playableRange(role.range.lowestNote, role.range.highestNote);
+                  return (
                   <div
                     key={role.id}
                     className={`rounded-xl border-l-4 p-4 transition-all hover:translate-x-1 ${getPriorityColor(role.rehearsalPriority)}`}
@@ -182,6 +185,18 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
                           {role.cue.value}
                         </div>
 
+                        {validatedRange ? (
+                          <div className="text-sm font-medium leading-snug text-slate-200">
+                            <span className="mb-0.5 block text-[0.65rem] font-bold uppercase tracking-wider text-slate-400">{t("sectionRangeLabel")}</span>
+                            <span>
+                              {validatedRange.lowestNote} — {validatedRange.highestNote}
+                            </span>
+                            <p className="mt-1 text-xs font-medium text-slate-400">
+                              {fillRangeCopy(t("sectionRangeNextAction"), { sectionLabel: section.label })}
+                            </p>
+                          </div>
+                        ) : null}
+
                         {role.setupNote && (
                           <div className="flex items-start gap-2 rounded-md border border-amber-300/20 bg-amber-300/[0.08] p-2 text-xs font-medium text-amber-100">
                             <Lightbulb className="mt-0.5 size-3.5 shrink-0" aria-hidden="true" />
@@ -209,7 +224,8 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
                       </div>
                     </div>
                   </div>
-              ))}
+                  );
+                })}
             </CardContent>
           </Card>
         ))}

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

@@ -140,6 +140,62 @@ describe("Workspace", () => {
     expect(screen.getByText(/Verse harmony pass/i)).toBeTruthy();
   });
 
+  it("names tonight's first playable range and the next instrument check", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+
+    const callout = screen.getByTestId("first-range-squeeze");
+    expect(callout).toHaveTextContent("Tonight's first range");
+    expect(callout).toHaveTextContent(
+      "Bass Guitar sits C#2–E3 in verse. Hear that clash on your instrument before the verse."
+    );
+  });
+
+  it("asks for an ear check when the selected part has no named span", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role) => ({
+      ...role,
+      range: { lowestNote: "", highestNote: "none" },
+      overlapWarnings: []
+    }));
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-range-squeeze")).toHaveTextContent(
+      "Tonight's first range still needs an ear check. Confirm the high and low notes on the selected part before the first section."
+    );
+  });
+
+  it("limits the range callout to the selected role", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" }));
+
+    expect(screen.getByTestId("first-range-squeeze")).toHaveTextContent(
+      "Lead Vocal sits G#3–C#5 in verse. Hear that clash on your instrument before the verse."
+    );
+  });
+
+  it("asks the player to check a named span when no clash is present", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role) => ({
+      ...role,
+      overlapWarnings: []
+    }));
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-range-squeeze")).toHaveTextContent(
+      "Bass Guitar sits C#2–E3 in verse. Check that span on your instrument before the verse."
+    );
+  });
+
   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

@@ -4,6 +4,7 @@ import { RoleSwitcher } from "./RoleSwitcher";
 import { SectionRoadmap } from "./SectionRoadmap";
 import { GrooveMap } from "./GrooveMap";
 import { PracticeProgress } from "./PracticeProgress";
+import { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
@@ -150,6 +151,18 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
     return roleMap.get(activeRole);
   }, [activeRole, roleMap]);
   const canTranscribeBass = activeRoleDetails?.name.toLowerCase().includes("bass") ?? false;
+  const firstRange = useMemo(() => firstRangeSqueeze(song, activeRole), [activeRole, song]);
+  const firstRangeCopy = firstRange
+    ? fillRangeCopy(
+        t(firstRange.overlapWarning ? "workspaceFirstRangeClash" : "workspaceFirstRangeCheck"),
+        {
+          roleName: firstRange.roleName,
+          lowestNote: firstRange.lowestNote,
+          highestNote: firstRange.highestNote,
+          sectionLabel: firstRange.sectionLabel
+        }
+      )
+    : t("workspaceFirstRangeMissing");
 
   /** Handle the practice progress change internally by immutably updating the song state. */
   const handlePracticeProgressChange = (newProgress: number) => {
@@ -288,6 +301,15 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
         </CardHeader>
 
         <CardContent className="space-y-6 bg-[linear-gradient(180deg,rgba(15,23,42,0.72),rgba(2,6,23,0.86))] p-5 md:p-7">
+          <section
+            className="rounded-2xl border border-fuchsia-300/20 bg-fuchsia-300/[0.07] p-4"
+            data-testid="first-range-squeeze"
+            aria-label={t("workspaceFirstRangeTitle")}
+          >
+            <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>
+
           <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">
               <p className="text-xs font-black uppercase tracking-[0.24em] text-cyan-300">{t("workspaceSongTimelineLabel")}</p>