feat(workspace): name tonight's first score check 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 attached score to open in Score.
 - 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 attached score to open in Score
   - 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 attached score on the ready rehearsal map and tell the player to open it in Score, or add a score and check the first range by ear.
 - 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 score to open in Score. `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,67 @@ describe("Workspace", () => {
     );
   });
 
+  it("names tonight's first score check and the next Score action", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.scoreAttachments = [
+      { id: "3f2c8f0e-1a2b-4c3d-8e9f-001122334455", fileName: "opener.pdf" }
+    ];
+
+    render(<Workspace song={song} />);
+
+    const callout = screen.getByTestId("first-score-check");
+    expect(callout).toHaveTextContent("Tonight's first score check");
+    expect(callout).toHaveTextContent(
+      "Open opener.pdf in Score and check Bass Guitar's C#2–E3 in verse against the page before the verse."
+    );
+  });
+
+  it("asks the player to add a score when no trusted attachment exists", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-score-check")).toHaveTextContent(
+      "Add a score in Score, or check tonight's first range by ear before the first section."
+    );
+  });
+
+  it("asks the player to mark the range on the page when the score is attached without a span", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.scoreAttachments = [
+      { id: "3f2c8f0e-1a2b-4c3d-8e9f-001122334455", fileName: "opener.pdf" }
+    ];
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role) => ({
+      ...role,
+      range: { lowestNote: "", highestNote: "none" },
+      overlapWarnings: []
+    }));
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-score-check")).toHaveTextContent(
+      "Open opener.pdf in Score and mark tonight's first range on the page."
+    );
+  });
+
+  it("limits the score-check range to the selected role", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.scoreAttachments = [
+      { id: "3f2c8f0e-1a2b-4c3d-8e9f-001122334455", fileName: "opener.pdf" }
+    ];
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" }));
+
+    expect(screen.getByTestId("first-score-check")).toHaveTextContent(
+      "Open opener.pdf in Score and check Lead Vocal's G#3–C#5 in verse against the page 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

@@ -5,6 +5,7 @@ import { SectionRoadmap } from "./SectionRoadmap";
 import { GrooveMap } from "./GrooveMap";
 import { PracticeProgress } from "./PracticeProgress";
 import { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze";
+import { firstScoreCheck } from "./firstScoreCheck";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
@@ -163,6 +164,23 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
         }
       )
     : t("workspaceFirstRangeMissing");
+  const firstScore = useMemo(() => firstScoreCheck(song, activeRole), [activeRole, song]);
+  const firstScoreCopy = firstScore
+    ? fillRangeCopy(
+        t(
+          firstScore.sectionLabel
+            ? "workspaceFirstScoreCheck"
+            : "workspaceFirstScoreCheckNoRange"
+        ),
+        {
+          fileName: firstScore.fileName,
+          roleName: firstScore.roleName ?? "",
+          lowestNote: firstScore.lowestNote ?? "",
+          highestNote: firstScore.highestNote ?? "",
+          sectionLabel: firstScore.sectionLabel ?? ""
+        }
+      )
+    : t("workspaceFirstScoreMissing");
 
   /** Handle the practice progress change internally by immutably updating the song state. */
   const handlePracticeProgressChange = (newProgress: number) => {
@@ -309,6 +327,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-sky-300/20 bg-sky-300/[0.07] p-4"
+            data-testid="first-score-check"
+            aria-label={t("workspaceFirstScoreTitle")}
+          >
+            <p className="text-xs font-black uppercase tracking-[0.24em] text-sky-200">{t("workspaceFirstScoreTitle")}</p>
+            <p className="mt-2 text-sm leading-6 text-slate-100">{firstScoreCopy}</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/firstScoreCheck.test.ts

@@ -0,0 +1,168 @@
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import {
+  MAX_SCORE_DISPLAY_NAME_LENGTH,
+  firstScoreCheck,
+  trustedScoreAttachment,
+  trustedScoreFileName
+} from "./firstScoreCheck";
+import { fillRangeCopy } from "./firstRangeSqueeze";
+
+const TRUSTED_SCORE_ID = "3f2c8f0e-1a2b-4c3d-8e9f-001122334455";
+
+function songWithAttachments(
+  attachments: unknown,
+  song: RehearsalSong = createDemoRehearsalSong()
+): RehearsalSong {
+  return {
+    ...song,
+    scoreAttachments: attachments as RehearsalSong["scoreAttachments"]
+  };
+}
+
+function blankRoleRange(song: RehearsalSong): RehearsalSong {
+  return {
+    ...song,
+    sections: song.sections.map((section) => ({
+      ...section,
+      roles: section.roles.map((role) => ({
+        ...role,
+        range: { lowestNote: "", highestNote: "" },
+        overlapWarnings: []
+      }))
+    }))
+  };
+}
+
+describe("trustedScoreFileName", () => {
+  it("admits a bounded PDF basename", () => {
+    expect(trustedScoreFileName("opener.pdf")).toBe("opener.pdf");
+    expect(trustedScoreFileName("Late Night Set.PDF")).toBe("Late Night Set.PDF");
+  });
+
+  it("fails closed on blank, overlong, path, control, and reserved names", () => {
+    for (const value of [
+      "",
+      "pdf",
+      ".pdf",
+      " opener.pdf",
+      "opener.pdf ",
+      "opener.pdf/",
+      "../opener.pdf",
+      "folder/opener.pdf",
+      "folder\\opener.pdf",
+      "open\ner.pdf",
+      "open\u0000er.pdf",
+      "CON.pdf",
+      "aux.PDF",
+      "opener.docx",
+      `${"a".repeat(MAX_SCORE_DISPLAY_NAME_LENGTH)}.pdf`
+    ]) {
+      expect(trustedScoreFileName(value)).toBeNull();
+    }
+  });
+});
+
+describe("trustedScoreAttachment", () => {
+  it("admits a lowercase UUID plus trusted PDF basename", () => {
+    expect(
+      trustedScoreAttachment({ id: TRUSTED_SCORE_ID, fileName: "opener.pdf" })
+    ).toEqual({ id: TRUSTED_SCORE_ID, fileName: "opener.pdf" });
+  });
+
+  it("fails closed on extra keys, inherited members, and malformed ids", () => {
+    expect(trustedScoreAttachment(null)).toBeNull();
+    expect(trustedScoreAttachment({ fileName: "opener.pdf" })).toBeNull();
+    expect(
+      trustedScoreAttachment({
+        id: TRUSTED_SCORE_ID,
+        fileName: "opener.pdf",
+        extra: true
+      })
+    ).toBeNull();
+    expect(
+      trustedScoreAttachment({
+        id: "3F2C8F0E-1A2B-4C3D-8E9F-001122334455",
+        fileName: "opener.pdf"
+      })
+    ).toBeNull();
+    expect(
+      trustedScoreAttachment({
+        id: "../../etc/passwd-aaaa-bbbb-cccc-dddddddddddd",
+        fileName: "opener.pdf"
+      })
+    ).toBeNull();
+    expect(
+      trustedScoreAttachment(Object.create({ id: TRUSTED_SCORE_ID, fileName: "opener.pdf" }))
+    ).toBeNull();
+  });
+});
+
+describe("firstScoreCheck", () => {
+  it("returns null when no trusted score is attached", () => {
+    expect(firstScoreCheck(createDemoRehearsalSong())).toBeNull();
+    expect(firstScoreCheck(songWithAttachments(null))).toBeNull();
+    expect(firstScoreCheck(songWithAttachments([]))).toBeNull();
+    expect(firstScoreCheck(songWithAttachments([{ id: "bad", fileName: "opener.pdf" }]))).toBeNull();
+  });
+
+  it("skips malformed attachments and names the first trusted score with tonight's range", () => {
+    const check = firstScoreCheck(
+      songWithAttachments([
+        { id: "bad", fileName: "skip.pdf" },
+        { id: TRUSTED_SCORE_ID, fileName: "opener.pdf" }
+      ])
+    );
+
+    expect(check).toEqual({
+      fileName: "opener.pdf",
+      sectionLabel: "verse",
+      roleName: "Bass Guitar",
+      lowestNote: "C#2",
+      highestNote: "E3"
+    });
+  });
+
+  it("still names the score when the selected part has no playable span", () => {
+    expect(
+      firstScoreCheck(
+        songWithAttachments(
+          [{ id: TRUSTED_SCORE_ID, fileName: "opener.pdf" }],
+          blankRoleRange(createDemoRehearsalSong())
+        )
+      )
+    ).toEqual({ fileName: "opener.pdf" });
+  });
+
+  it("limits the paired range to the selected role", () => {
+    expect(
+      firstScoreCheck(
+        songWithAttachments([{ id: TRUSTED_SCORE_ID, fileName: "opener.pdf" }]),
+        "lead-vocal"
+      )
+    ).toEqual({
+      fileName: "opener.pdf",
+      sectionLabel: "verse",
+      roleName: "Lead Vocal",
+      lowestNote: "G#3",
+      highestNote: "C#5"
+    });
+  });
+
+  it("fails closed on malformed runtime roots", () => {
+    for (const malformed of [null, {}, { scoreAttachments: {} }]) {
+      expect(firstScoreCheck(malformed as unknown as RehearsalSong)).toBeNull();
+    }
+  });
+});
+
+describe("score check copy filling", () => {
+  it("keeps the attached file name literal", () => {
+    expect(
+      fillRangeCopy("Open {fileName} in Score before the {sectionLabel}.", {
+        fileName: "Bass $& {sectionLabel}.pdf",
+        sectionLabel: "verse"
+      })
+    ).toBe("Open Bass $& {sectionLabel}.pdf in Score before the verse.");
+  });
+});