feat: import rehearsal handoffs for focused reanalysis

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Import a bounded, validated BandScope metadata-handoff JSON file, require an explicit fresh local-audio pairing, and reuse the handoff's focused rehearsal roles for reanalysis (#739). Competing source actions and project replacement remain locked while handoff validation is pending; project loading reciprocally locks source/handoff changes and saving the prior project until the load settles; source/project/analysis handlers and the handoff import/open/change/clear handlers independently reject stale overlapping transitions even if UI disablement is bypassed; once a handoff validates, YouTube import stays unavailable until the handoff is cleared or consumed so only an explicit recipient-selected local file can satisfy the pairing boundary.
 - 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 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.

apps/desktop/src/App.handoff-project-load.test.tsx

@@ -0,0 +1,86 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { RehearsalSong } from "@bandscope/shared-types";
+import { App } from "./App";
+import { loadProject } from "./lib/analysis";
+
+vi.mock("./features/score/ScoreView", () => ({
+  ScoreView: () => <div>Score view</div>
+}));
+
+vi.mock("./features/workspace/Workspace", () => ({
+  Workspace: () => <div>Workspace result</div>
+}));
+
+vi.mock("./lib/analysis", () => ({
+  MAX_YOUTUBE_URL_LENGTH: 2048,
+  createDefaultAnalysisRequest: vi.fn(() => ({
+    sourceKind: "demo",
+    sourceLabel: "Late Night Set",
+    roleFocus: ["keys-right"]
+  })),
+  getAnalysisJobStatus: vi.fn(),
+  importYoutubeUrl: vi.fn(),
+  isSupportedYoutubeUrl: vi.fn(() => true),
+  loadProject: vi.fn(),
+  saveProject: vi.fn(),
+  selectLocalAudioSource: vi.fn(),
+  startAnalysisJob: vi.fn(),
+  subscribeToAnalysisJobUpdates: vi.fn(async () => () => undefined)
+}));
+
+vi.mock("./lib/handoff", async (importActual) => {
+  const actual = await importActual<typeof import("./lib/handoff")>();
+  return {
+    ...actual,
+    readMetadataHandoffFile: vi.fn()
+  };
+});
+
+const mockedLoadProject = vi.mocked(loadProject);
+
+function loadedSong(): RehearsalSong {
+  return {
+    id: "loaded-song",
+    title: "Loaded song",
+    sections: [],
+    exportSummary: {
+      format: "cue-sheet",
+      headline: "Loaded rehearsal project",
+      focusSections: []
+    }
+  } as RehearsalSong;
+}
+
+describe("App project-load source exclusion", () => {
+  beforeEach(() => {
+    mockedLoadProject.mockReset();
+  });
+
+  it("locks source and handoff controls until project loading settles", async () => {
+    let resolveProject: ((song: RehearsalSong) => void) | null = null;
+    mockedLoadProject.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveProject = resolve;
+        })
+    );
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /open project/i }));
+
+    expect(screen.getByRole("button", { name: /open project/i })).toBeDisabled();
+    expect(screen.getByRole("button", { name: /choose local audio/i })).toBeDisabled();
+    expect(screen.getByRole("button", { name: /import handoff/i })).toBeDisabled();
+    expect(screen.getByLabelText(/youtube url/i)).toBeDisabled();
+
+    resolveProject?.(loadedSong());
+    await screen.findByText("Workspace result");
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /open project/i })).not.toBeDisabled();
+      expect(screen.getByRole("button", { name: /choose local audio/i })).not.toBeDisabled();
+      expect(screen.getByRole("button", { name: /import handoff/i })).not.toBeDisabled();
+      expect(screen.getByLabelText(/youtube url/i)).not.toBeDisabled();
+    });
+  });
+});

apps/desktop/src/App.handoff-youtube-guard.test.tsx

@@ -0,0 +1,124 @@
+import type { ButtonHTMLAttributes } from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { MetadataHandoffArtifact } from "@bandscope/shared-types";
+import { App } from "./App";
+import { importYoutubeUrl } from "./lib/analysis";
+import { readMetadataHandoffFile } from "./lib/handoff";
+
+vi.mock("./features/score/ScoreView", () => ({
+  ScoreView: () => <div>Score view</div>
+}));
+
+vi.mock("./features/workspace/Workspace", () => ({
+  Workspace: () => <div>Workspace result</div>
+}));
+
+vi.mock("@/components/ui/button", () => ({
+  Button: ({ disabled, ...props }: ButtonHTMLAttributes<HTMLButtonElement>) => (
+    <button {...props} data-disabled={disabled ? "true" : "false"} />
+  )
+}));
+
+vi.mock("./lib/analysis", () => ({
+  MAX_YOUTUBE_URL_LENGTH: 2048,
+  createDefaultAnalysisRequest: vi.fn(() => ({
+    sourceKind: "demo",
+    sourceLabel: "Late Night Set",
+    roleFocus: ["keys-right"]
+  })),
+  getAnalysisJobStatus: vi.fn(),
+  importYoutubeUrl: vi.fn(),
+  isSupportedYoutubeUrl: vi.fn(() => true),
+  loadProject: vi.fn(),
+  saveProject: vi.fn(),
+  selectLocalAudioSource: vi.fn(),
+  startAnalysisJob: vi.fn(),
+  subscribeToAnalysisJobUpdates: vi.fn(async () => () => undefined)
+}));
+
+vi.mock("./lib/handoff", async (importActual) => {
+  const actual = await importActual<typeof import("./lib/handoff")>();
+  return {
+    ...actual,
+    readMetadataHandoffFile: vi.fn()
+  };
+});
+
+const mockedImportYoutubeUrl = vi.mocked(importYoutubeUrl);
+const mockedReadMetadataHandoffFile = vi.mocked(readMetadataHandoffFile);
+
+function handoff(): MetadataHandoffArtifact {
+  return {
+    artifactKind: "bandscope.metadata-handoff",
+    artifactVersion: 1,
+    createdAt: "2026-08-16T00:00:00.000Z",
+    workspace: { id: "workspace-1", title: "Friday rehearsal", workspaceVersion: 1 },
+    song: {
+      id: "song-1",
+      title: "Late Night Set",
+      exportSummary: {
+        format: "cue-sheet",
+        headline: "Start with the chorus entrance.",
+        focusSections: ["chorus"]
+      }
+    },
+    sections: [
+      {
+        id: "chorus-1",
+        label: "chorus",
+        timeRange: { start: 0, end: 30 },
+        confidence: { level: "high", source: "model", notes: "" },
+        roleBuckets: [
+          {
+            id: "keys-right",
+            name: "Keys Right",
+            roleType: "instrument",
+            confidence: { level: "high", source: "model", notes: "" },
+            rehearsalPriority: "high"
+          }
+        ]
+      }
+    ],
+    sourceAssets: []
+  };
+}
+
+describe("App handoff YouTube defense in depth", () => {
+  beforeEach(() => {
+    mockedImportYoutubeUrl.mockReset();
+    mockedReadMetadataHandoffFile.mockReset();
+  });
+
+  it("keeps the handler fail-closed if the UI disablement boundary is bypassed", async () => {
+    mockedReadMetadataHandoffFile.mockResolvedValueOnce({
+      ok: true,
+      fileName: "handoff.json",
+      artifact: handoff(),
+      roleFocus: ["keys-right"]
+    });
+
+    render(<App />);
+
+    fireEvent.change(screen.getByLabelText(/youtube url/i), {
+      target: { value: "https://youtu.be/abc123DEF45" }
+    });
+    const importButton = screen.getByRole("button", { name: /import youtube/i });
+
+    fireEvent.change(screen.getByLabelText(/handoff JSON file/i), {
+      target: {
+        files: [new File(["{}"], "handoff.json", { type: "application/json" })]
+      }
+    });
+
+    await screen.findByText("Friday rehearsal");
+    expect(importButton).toHaveAttribute("data-disabled", "true");
+
+    // The test Button deliberately records but does not enforce `disabled`,
+    // modeling a compromised UI primitive. The handler must still reject the
+    // stale YouTube action while validated handoff authority is pending.
+    fireEvent.click(importButton);
+
+    expect(mockedImportYoutubeUrl).not.toHaveBeenCalled();
+  });
+});