feat(workspace): name tonight's first pickup plan on the map

AGENTS.md

@@ -83,6 +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.
+- Name tonight's first pickup plan with the owning part when an active role is corroborated, the owned `pickupPlan` copy, the labeled section, and the time so the next action is obvious. Do not invent that copy from groove, cue, simplification, overlap, range, chord labels, function labels, setup notes, transposition plans, vamp plans, fill plans, tuning plans, dynamics plans, articulation plans, hook plans, solo plans, pad plans, hit plans, cutoff plans, turnaround plans, confirmed overrides, harmonic explanations, or confidence notes.
 - 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.
 

ARCHITECTURE.md

@@ -1,10 +1,11 @@
 # ARCHITECTURE.md
 
-Last updated: 2026-03-11
+Last updated: 2026-08-27
 
 ## Brand source
 
 - Product identity, UX tone, copy rules, and prioritization tie-breakers live in `docs/brand-story.md`.
+- The mounted workspace copy for tonight's first pickup plan must name the owning part when corroborated, the owned `pickupPlan` text, the labeled section, and the time so the next action is obvious. Open moves to the matching rendered map section. Do not invent that copy from groove, cue, simplification, overlap, range, chord labels, function labels, setup notes, transposition plans, vamp plans, fill plans, tuning plans, dynamics plans, articulation plans, hook plans, solo plans, pad plans, hit plans, cutoff plans, turnaround plans, confirmed overrides, harmonic explanations, or confidence notes. Distinct from first-turnaround-plan, first-cutoff-plan, first-hit-plan, first-vamp-plan, first-pad-plan, first-solo-plan, first-hook-plan, first-fill-plan, first-setup-note, first-transposition-plan, first-tuning-plan, first-articulation-plan, and the labeled-pickup section guide.
 - Future PRDs, TRDs, onboarding copy, empty states, error messages, and marketing copy should use that document as the single brand source of truth.
 
 ## Security source

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Name tonight's first pickup plan in the mounted rehearsal workspace so a part that was resting can lead into the next downbeat on the map; real analyzed songs now receive this guidance only when section-level stem activity shows that part becoming active after an abutting rest, with at least one other distinct source already on the landing downbeat, while heuristic-only topology remains unavailable. Open moves to the matching rendered map section, and inherited, accessor-backed, or Proxy-substituted runtime metadata remains guidance-only instead of becoming copy, identity, timing, or navigation authority.
 - 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 mounted workspace names tonight's first pickup plan and opens the matching rendered map section. The ready workspace names tonight's first playable range and the next instrument check. Do not invent that copy from groove, cue, simplification, overlap, range, chord labels, function labels, setup notes, transposition plans, vamp plans, fill plans, tuning plans, dynamics plans, articulation plans, hook plans, solo plans, pad plans, hit plans, cutoff plans, turnaround plans, confirmed overrides, harmonic explanations, or confidence notes. Distinct from first-turnaround-plan, first-cutoff-plan, first-hit-plan, first-vamp-plan, first-pad-plan, first-solo-plan, first-hook-plan, first-fill-plan, first-setup-note, first-transposition-plan, first-tuning-plan, first-articulation-plan, and the labeled-pickup section guide. `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/FirstPickupPlanCallout.identity.test.tsx

@@ -0,0 +1,21 @@
+import { render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { expect, it } from "vitest";
+import { FirstPickupPlanCallout } from "./FirstPickupPlanCallout";
+
+it("gives co-mounted pickup-plan callouts distinct DOM identities", () => {
+  render(
+    <>
+      <FirstPickupPlanCallout song={createDemoRehearsalSong()} />
+      <FirstPickupPlanCallout song={createDemoRehearsalSong()} />
+    </>
+  );
+
+  const callouts = screen.getAllByRole("complementary", {
+    name: "Tonight's first pickup plan"
+  });
+  const ids = callouts.map((callout) => callout.id);
+
+  expect(ids.every((id) => id.length > 0)).toBe(true);
+  expect(new Set(ids).size).toBe(callouts.length);
+});

apps/desktop/src/features/workspace/FirstPickupPlanCallout.memoization.test.tsx

@@ -0,0 +1,46 @@
+import { render } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstPickupPlanCallout } from "./FirstPickupPlanCallout";
+
+function songWithPickupPlan() {
+  const song = createDemoRehearsalSong();
+  const verse = song.sections[0]!;
+  const intro = structuredClone(verse);
+  intro.id = "intro-1";
+  intro.label = "intro";
+  intro.timeRange = { start: 0, end: verse.timeRange.start };
+  intro.roles = intro.roles.map((role) => {
+    const clone = { ...role };
+    delete clone.pickupPlan;
+    delete clone.pickupPlanSource;
+    return clone;
+  });
+  intro.partGraph = intro.partGraph.map((node) => ({
+    ...node,
+    is_active: node.role_id !== "bass-guitar"
+  }));
+  song.sections = [intro, verse];
+  return song;
+}
+
+describe("FirstPickupPlanCallout resolver reuse", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("does not rescan role metadata when a parent rerenders the same song object", () => {
+    const song = songWithPickupPlan();
+    const role = song.sections[1]!.roles.find((candidate) => candidate.id === "bass-guitar")!;
+    const descriptorSpy = vi.spyOn(Object, "getOwnPropertyDescriptor");
+
+    const { rerender } = render(<FirstPickupPlanCallout song={song} />);
+    const firstScanCount = descriptorSpy.mock.calls.filter(([target]) => target === role).length;
+    expect(firstScanCount).toBeGreaterThan(0);
+
+    rerender(<FirstPickupPlanCallout song={song} />);
+    const secondScanCount = descriptorSpy.mock.calls.filter(([target]) => target === role).length;
+
+    expect(secondScanCount).toBe(firstScanCount);
+  });
+});

apps/desktop/src/features/workspace/FirstPickupPlanCallout.navigation-failure.test.tsx

@@ -0,0 +1,42 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import { FirstPickupPlanCallout } from "./FirstPickupPlanCallout";
+
+function songWithPickupPlan() {
+  const song = createDemoRehearsalSong();
+  const verse = song.sections[0]!;
+  const intro = structuredClone(verse);
+  intro.id = "intro-1";
+  intro.label = "intro";
+  intro.timeRange = { start: 0, end: verse.timeRange.start };
+  intro.roles = intro.roles.map((role) => {
+    const clone = { ...role };
+    delete clone.pickupPlan;
+    delete clone.pickupPlanSource;
+    return clone;
+  });
+  intro.partGraph = intro.partGraph.map((node) => ({
+    ...node,
+    is_active: node.role_id !== "bass-guitar"
+  }));
+  song.sections = [intro, verse];
+  return song;
+}
+
+describe("FirstPickupPlanCallout navigation failure", () => {
+  it("tells the user when the named pickup cannot be opened on the rendered map", () => {
+    render(<FirstPickupPlanCallout song={songWithPickupPlan()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar pickup at 0:10" }));
+
+    expect(
+      screen.getByText(
+        "Could not open this pickup on the song map. Use the map below to find the section."
+      )
+    ).toBeTruthy();
+    expect(
+      screen.queryByText(/Play that pickup on Bass Guitar at 0:10 before the downbeat lands./)
+    ).toBeNull();
+  });
+});

apps/desktop/src/features/workspace/FirstPickupPlanCallout.particle.test.tsx

@@ -0,0 +1,139 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstPickupPlanCallout } from "./FirstPickupPlanCallout";
+
+function songWithKoreanPickup(
+  pickupPlan: string,
+  pickupPlanSource?: "model" | "user"
+) {
+  const song = createDemoRehearsalSong();
+  const verse = song.sections[0]!;
+  const companion = verse.roles.find((role) => role.id === "bass-guitar")!;
+  verse.roles = [
+    {
+      ...verse.roles[2]!,
+      id: "piano",
+      name: "피아노",
+      rehearsalPriority: "high",
+      pickupPlan,
+      ...(pickupPlanSource ? { pickupPlanSource } : {})
+    },
+    companion
+  ];
+  verse.partGraph = [
+    { role_id: "piano", is_active: true, handoff_to: [], handoff_from: [] },
+    { role_id: "bass-guitar", is_active: true, handoff_to: [], handoff_from: [] }
+  ];
+  const intro = structuredClone(verse);
+  intro.id = "intro-1";
+  intro.label = "intro";
+  intro.timeRange = { start: 0, end: verse.timeRange.start };
+  intro.roles = intro.roles.map((role) => {
+    const clone = { ...role };
+    delete clone.pickupPlan;
+    delete clone.pickupPlanSource;
+    return clone;
+  });
+  intro.partGraph = intro.partGraph.map((node) => ({
+    ...node,
+    is_active: node.role_id !== "piano"
+  }));
+  song.sections = [intro, verse];
+  return song;
+}
+
+describe("FirstPickupPlanCallout Korean role copy", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps vowel-ending role names particle-safe before and after the pickup action", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const song = songWithKoreanPickup(
+      "Play this pickup with Lead Vocal on the verse last beat; land the chorus downbeat together."
+    );
+
+    const grid = document.createElement("div");
+    grid.dataset.testid = "song-structure-grid";
+    grid.setAttribute("role", "region");
+    grid.setAttribute("aria-label", "Scrollable song structure timeline");
+    const target = document.createElement("div");
+    target.dataset.sectionIndex = "1";
+    Object.defineProperty(target, "scrollIntoView", {
+      configurable: true,
+      value: vi.fn()
+    });
+    grid.appendChild(target);
+    document.body.appendChild(grid);
+
+    render(<FirstPickupPlanCallout song={song} />);
+
+    expect(screen.getByText("0:10 벌스에서 피아노 파트의 픽업 계획이 있습니다.")).toBeTruthy();
+    expect(screen.queryByText(/피아노이/)).toBeNull();
+    expect(screen.queryByText(/피아노가/)).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: "0:10 피아노 픽업 열기" }));
+
+    expect(screen.getByText("0:10에서 피아노 파트의 픽업을 넣은 다음 합주를 시작하세요.")).toBeTruthy();
+    expect(screen.queryByText(/피아노과/)).toBeNull();
+
+    grid.remove();
+  });
+
+  it("localizes the analysis-engine pickup template instead of exposing English guidance", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const song = songWithKoreanPickup(
+      "Play this pickup with Lead Vocal; land the downbeat together.",
+      "model"
+    );
+
+    render(<FirstPickupPlanCallout song={song} />);
+
+    expect(
+      screen.getByText("Lead Vocal 파트와 이 픽업을 맞추세요. 첫 박에 함께 들어가세요.")
+    ).toBeTruthy();
+    expect(
+      screen.queryByText("Play this pickup with Lead Vocal; land the downbeat together.")
+    ).toBeNull();
+  });
+
+  it("localizes the rest-of-band pickup template instead of exposing English guidance", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const song = songWithKoreanPickup(
+      "Play this pickup with the rest of the band; land the downbeat together.",
+      "model"
+    );
+
+    render(<FirstPickupPlanCallout song={song} />);
+
+    expect(
+      screen.getByText("나머지 밴드와 이 픽업을 맞추세요. 첫 박에 함께 들어가세요.")
+    ).toBeTruthy();
+    expect(
+      screen.queryByText("Play this pickup with the rest of the band; land the downbeat together.")
+    ).toBeNull();
+  });
+
+  it("preserves the generated template shape when long target names are bounded", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const targetRole = `Lead-${"A".repeat(180)}`;
+    const song = songWithKoreanPickup(
+      `Play this pickup with ${targetRole}; land the downbeat together.`,
+      "model"
+    );
+    const landing = song.sections[1]!;
+    landing.roles[1] = { ...landing.roles[1]!, name: targetRole };
+
+    render(<FirstPickupPlanCallout song={song} />);
+
+    expect(screen.queryByText(/^Play this pickup with /)).toBeNull();
+    expect(
+      screen.getByText(
+        (content) =>
+          content.startsWith("Lead-") &&
+          content.endsWith("파트와 이 픽업을 맞추세요. 첫 박에 함께 들어가세요.")
+      )
+    ).toBeTruthy();
+  });
+});

apps/desktop/src/features/workspace/FirstPickupPlanCallout.provenance.test.tsx

@@ -0,0 +1,89 @@
+import { render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstPickupPlanCallout } from "./FirstPickupPlanCallout";
+
+function songWithKoreanPickup(
+  pickupPlan: string,
+  pickupPlanSource?: "model" | "user"
+) {
+  const song = createDemoRehearsalSong();
+  const verse = song.sections[0]!;
+  const companion = verse.roles.find((role) => role.id === "bass-guitar")!;
+  verse.roles = [
+    {
+      ...verse.roles[2]!,
+      id: "piano",
+      name: "피아노",
+      rehearsalPriority: "high",
+      pickupPlan,
+      ...(pickupPlanSource ? { pickupPlanSource } : {})
+    },
+    companion
+  ];
+  verse.partGraph = [
+    { role_id: "piano", is_active: true, handoff_to: [], handoff_from: [] },
+    { role_id: "bass-guitar", is_active: true, handoff_to: [], handoff_from: [] }
+  ];
+  const intro = structuredClone(verse);
+  intro.id = "intro-1";
+  intro.label = "intro";
+  intro.timeRange = { start: 0, end: verse.timeRange.start };
+  intro.roles = intro.roles.map((role) => {
+    const clone = { ...role };
+    delete clone.pickupPlan;
+    delete clone.pickupPlanSource;
+    return clone;
+  });
+  intro.partGraph = intro.partGraph.map((node) => ({
+    ...node,
+    is_active: node.role_id !== "piano"
+  }));
+  song.sections = [intro, verse];
+  return song;
+}
+
+describe("FirstPickupPlanCallout pickup-plan provenance", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("preserves user pickup guidance that happens to match the engine sentence shape", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const customPlan = "Play this pickup with Lead Vocal; land the downbeat together.";
+    const song = songWithKoreanPickup(customPlan, "user");
+
+    render(<FirstPickupPlanCallout song={song} />);
+
+    expect(screen.getByText(customPlan)).toBeTruthy();
+    expect(
+      screen.queryByText("Bass Guitar 파트와 이 픽업을 맞추세요. 첫 박에 함께 들어가세요.")
+    ).toBeNull();
+  });
+
+  it("does not infer model authority when persisted pickup guidance has no source", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const legacyPlan = "Play this pickup with Lead Vocal; land the downbeat together.";
+    const song = songWithKoreanPickup(legacyPlan);
+
+    render(<FirstPickupPlanCallout song={song} />);
+
+    expect(screen.getByText(legacyPlan)).toBeTruthy();
+    expect(
+      screen.queryByText("Bass Guitar 파트와 이 픽업을 맞추세요. 첫 박에 함께 들어가세요.")
+    ).toBeNull();
+  });
+
+  it("localizes model guidance from structured landing topology instead of display sentence wording", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const changedDisplayCopy = "Pickup display wording changed upstream.";
+    const song = songWithKoreanPickup(changedDisplayCopy, "model");
+
+    render(<FirstPickupPlanCallout song={song} />);
+
+    expect(
+      screen.getByText("Bass Guitar 파트와 이 픽업을 맞추세요. 첫 박에 함께 들어가세요.")
+    ).toBeTruthy();
+    expect(screen.queryByText(changedDisplayCopy)).toBeNull();
+  });
+});