feat(workspace): copy tonight's first check for the band chat

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 lets the player copy that instrument check for the band chat.
 - 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 a copy of that check for the band chat
   - 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
 
+- Copy tonight's first instrument check from the ready rehearsal map so a player can paste it in the band chat before the first section.
 - 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, the next instrument check, and a copy of that check for the band chat. `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.copy-request-order.test.tsx

@@ -0,0 +1,116 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Workspace } from "./Workspace";
+
+const originalLanguage = navigator.language;
+const originalClipboard = navigator.clipboard;
+
+type Deferred<T> = {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+};
+
+function createDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve;
+    reject = promiseReject;
+  });
+  return { promise, reject, resolve };
+}
+
+function setNavigatorLanguage(language: string): void {
+  Object.defineProperty(navigator, "language", {
+    configurable: true,
+    value: language
+  });
+}
+
+describe("Workspace copy request ordering", () => {
+  afterEach(() => {
+    setNavigatorLanguage(originalLanguage);
+    vi.restoreAllMocks();
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: originalClipboard
+    });
+    Reflect.deleteProperty(document, "execCommand");
+  });
+
+  it("keeps the newest overlapping copy result when an older request finishes later", async () => {
+    setNavigatorLanguage("en-US");
+    const firstWrite = createDeferred<void>();
+    const secondWrite = createDeferred<void>();
+    const writeText = vi
+      .fn()
+      .mockImplementationOnce(() => firstWrite.promise)
+      .mockImplementationOnce(() => secondWrite.promise);
+    const execCommand = vi.fn().mockReturnValue(false);
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: { writeText }
+    });
+    Object.defineProperty(document, "execCommand", {
+      configurable: true,
+      value: execCommand,
+      writable: true
+    });
+
+    render(<Workspace song={createDemoRehearsalSong()} />);
+    const copyButton = screen.getByRole("button", { name: "Copy tonight's first check" });
+    fireEvent.click(copyButton);
+    fireEvent.click(copyButton);
+
+    expect(writeText).toHaveBeenCalledTimes(2);
+
+    secondWrite.resolve();
+    await waitFor(() => {
+      expect(screen.getByTestId("first-range-copy-status")).toHaveTextContent(
+        "Copied. Paste it in the band chat before the first section."
+      );
+    });
+
+    firstWrite.reject(new Error("older clipboard request blocked"));
+    await waitFor(() => {
+      expect(execCommand).toHaveBeenCalledTimes(1);
+    });
+    expect(screen.getByTestId("first-range-copy-status")).toHaveTextContent(
+      "Copied. Paste it in the band chat before the first section."
+    );
+  });
+
+  it("does not apply a pending copy result after the displayed sentence changes", async () => {
+    setNavigatorLanguage("en-US");
+    const pendingWrite = createDeferred<void>();
+    const writeText = vi.fn().mockImplementationOnce(() => pendingWrite.promise);
+    const execCommand = vi.fn().mockReturnValue(false);
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: { writeText }
+    });
+    Object.defineProperty(document, "execCommand", {
+      configurable: true,
+      value: execCommand,
+      writable: true
+    });
+
+    render(<Workspace song={createDemoRehearsalSong()} />);
+    fireEvent.click(screen.getByRole("button", { name: "Copy tonight's first check" }));
+    expect(writeText).toHaveBeenCalledTimes(1);
+
+    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."
+    );
+    expect(screen.getByTestId("first-range-copy-status")).toHaveTextContent("");
+
+    pendingWrite.reject(new Error("stale clipboard request blocked"));
+    await waitFor(() => {
+      expect(execCommand).toHaveBeenCalledTimes(1);
+    });
+    expect(screen.getByTestId("first-range-copy-status")).toHaveTextContent("");
+  });
+});

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

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { createDemoRehearsalSong, type ProjectBootstrapSummary, type RehearsalSong } from "@bandscope/shared-types";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { Workspace } from "./Workspace";
@@ -8,6 +8,7 @@ import { generateMetadataHandoffJson } from "../../lib/export";
 const originalLanguage = navigator.language;
 const originalCreateObjectUrl = URL.createObjectURL;
 const originalRevokeObjectUrl = URL.revokeObjectURL;
+const originalClipboard = navigator.clipboard;
 
 function setNavigatorLanguage(language: string) {
   Object.defineProperty(navigator, "language", {
@@ -20,6 +21,10 @@ describe("Workspace", () => {
   afterEach(() => {
     setNavigatorLanguage(originalLanguage);
     vi.restoreAllMocks();
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: originalClipboard
+    });
     Object.defineProperty(URL, "createObjectURL", {
       configurable: true,
       value: originalCreateObjectUrl
@@ -28,6 +33,7 @@ describe("Workspace", () => {
       configurable: true,
       value: originalRevokeObjectUrl
     });
+    Reflect.deleteProperty(document, "execCommand");
   });
 
   it("updates practice progress immutably through onSongUpdate", () => {
@@ -196,6 +202,76 @@ describe("Workspace", () => {
     );
   });
 
+  it("copies tonight's first check for the band chat", async () => {
+    setNavigatorLanguage("en-US");
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: { writeText }
+    });
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("button", { name: "Copy tonight's first check" }));
+
+    await waitFor(() => {
+      expect(writeText).toHaveBeenCalledWith(
+        "Bass Guitar sits C#2–E3 in verse. Hear that clash on your instrument before the verse."
+      );
+    });
+    expect(screen.getByTestId("first-range-copy-status")).toHaveTextContent(
+      "Copied. Paste it in the band chat before the first section."
+    );
+  });
+
+  it("names a next action when clipboard write is blocked without exposing the failure", async () => {
+    setNavigatorLanguage("en-US");
+    const writeText = vi.fn().mockRejectedValue(new Error("/Users/md/secret-job.json"));
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: { writeText }
+    });
+    Object.defineProperty(document, "execCommand", {
+      configurable: true,
+      writable: true,
+      value: vi.fn().mockReturnValue(false)
+    });
+
+    render(<Workspace song={createDemoRehearsalSong()} />);
+    fireEvent.click(screen.getByRole("button", { name: "Copy tonight's first check" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("first-range-copy-status")).toHaveTextContent(
+        "Clipboard is blocked in this window. Select tonight's first check and copy it before the first section."
+      );
+    });
+    expect(screen.queryByText(/secret-job/i)).toBeNull();
+  });
+
+  it("copies the missing-range next action when no named span exists", async () => {
+    setNavigatorLanguage("en-US");
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: { writeText }
+    });
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role) => ({
+      ...role,
+      range: { lowestNote: "", highestNote: "none" },
+      overlapWarnings: []
+    }));
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("button", { name: "Copy tonight's first check" }));
+
+    await waitFor(() => {
+      expect(writeText).toHaveBeenCalledWith(
+        "Tonight's first range still needs an ear check. Confirm the high and low notes on the selected part before the first section."
+      );
+    });
+  });
+
   it("falls back from blank planning copy and tolerates partial collaboration payloads", () => {
     setNavigatorLanguage("en-US");
     const song = createDemoRehearsalSong();
@@ -325,5 +401,27 @@ describe("Workspace", () => {
     expect(screen.getByText("스템")).toBeTruthy();
     expect(screen.getByText("합주 우선순위")).toBeTruthy();
     expect(screen.getByText("역할과 화성")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "오늘 첫 확인 복사" })).toBeTruthy();
+  });
+
+  it("copies the Korean first-check sentence for the band chat", async () => {
+    setNavigatorLanguage("ko-KR");
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: { writeText }
+    });
+
+    render(<Workspace song={createDemoRehearsalSong()} />);
+    fireEvent.click(screen.getByRole("button", { name: "오늘 첫 확인 복사" }));
+
+    await waitFor(() => {
+      expect(writeText).toHaveBeenCalledWith(
+        "verse의 Bass Guitar은 C#2–E3이고 다른 파트와 겹칩니다. verse 들어가기 전에 그 충돌을 악기로 들어 보세요."
+      );
+    });
+    expect(screen.getByTestId("first-range-copy-status")).toHaveTextContent(
+      "복사했습니다. 첫 구간 전에 밴드 채팅에 붙여 넣으세요."
+    );
   });
 });

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

@@ -1,15 +1,16 @@
-import { useState, useMemo, memo, type MouseEvent } from "react";
+import { useState, useMemo, memo, useLayoutEffect, useRef, type MouseEvent } from "react";
 import { parseProjectBootstrapSummary, type ProjectBootstrapSummary, type RehearsalSong, type RehearsalRole } from "@bandscope/shared-types";
 import { RoleSwitcher } from "./RoleSwitcher";
 import { SectionRoadmap } from "./SectionRoadmap";
 import { GrooveMap } from "./GrooveMap";
 import { PracticeProgress } from "./PracticeProgress";
 import { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze";
+import { copyFirstRangeAction, type FirstRangeCopyResult } from "./copyFirstRangeAction";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader, CardDescription } from "@/components/ui/card";
-import { Download, CheckCheck, ClipboardList, MessageSquareMore, CloudOff, Music4 } from "lucide-react";
+import { Download, CheckCheck, ClipboardList, MessageSquareMore, CloudOff, Music4, Copy } from "lucide-react";
 
 interface WorkspaceProps {
   song: RehearsalSong;
@@ -121,6 +122,7 @@ const SongStructure = memo(function SongStructure({ sections, t }: { sections: R
 /** Documented. */
 export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: WorkspaceProps) {
   const [activeRole, setActiveRole] = useState<string | null>(null);
+  const [copyStatus, setCopyStatus] = useState<FirstRangeCopyResult | "idle">("idle");
   const t = useMemo(() => createTranslator(detectPreferredLocale()), []);
 
   // Extract all unique roles from the song's sections
@@ -163,6 +165,31 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
         }
       )
     : t("workspaceFirstRangeMissing");
+  const copyRequestRef = useRef({ sequence: 0, sentence: firstRangeCopy });
+
+  useLayoutEffect(() => {
+    copyRequestRef.current = {
+      sequence: copyRequestRef.current.sequence + 1,
+      sentence: firstRangeCopy
+    };
+    setCopyStatus("idle");
+  }, [firstRangeCopy]);
+
+  /** Copy tonight's first instrument check for a band chat paste. */
+  const handleCopyFirstRange = async () => {
+    const request = {
+      sequence: copyRequestRef.current.sequence + 1,
+      sentence: firstRangeCopy
+    };
+    copyRequestRef.current = request;
+    const result = await copyFirstRangeAction(request.sentence);
+    if (
+      copyRequestRef.current.sequence === request.sequence &&
+      copyRequestRef.current.sentence === request.sentence
+    ) {
+      setCopyStatus(result);
+    }
+  };
 
   /** Handle the practice progress change internally by immutably updating the song state. */
   const handlePracticeProgressChange = (newProgress: number) => {
@@ -308,6 +335,31 @@ 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>
+            <div className="mt-3 flex flex-wrap items-center gap-3">
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => {
+                  void handleCopyFirstRange();
+                }}
+                className="min-h-10 border-fuchsia-300/30 bg-fuchsia-300/10 font-semibold text-fuchsia-50 shadow-sm hover:bg-fuchsia-300/20 hover:text-white"
+              >
+                <Copy className="mr-2 size-4 text-fuchsia-200" aria-hidden="true" />
+                {t("workspaceFirstRangeCopyAction")}
+              </Button>
+              <p
+                className="text-sm leading-6 text-fuchsia-100"
+                aria-live="polite"
+                data-testid="first-range-copy-status"
+              >
+                {copyStatus === "copied"
+                  ? t("workspaceFirstRangeCopied")
+                  : copyStatus === "unavailable"
+                    ? t("workspaceFirstRangeCopyUnavailable")
+                    : ""}
+              </p>
+            </div>
           </section>
 
           <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">