feat(workspace): name tonight's first simpler take 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 simpler take with the owning part, the labeled section, and the time so the next action is obvious.
 - 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

@@ -6,6 +6,7 @@ Last updated: 2026-03-11
 
 - Product identity, UX tone, copy rules, and prioritization tie-breakers live in `docs/brand-story.md`.
 - Future PRDs, TRDs, onboarding copy, empty states, error messages, and marketing copy should use that document as the single brand source of truth.
+- The mounted workspace copy for tonight's first simpler take must name the owning part, the labeled section, and the time so the next action is obvious. Open moves to the matching rendered map section. Do not invent a simpler take from setup notes, cues, overlap warnings, or unlabeled fields.
 
 ## Security source
 

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - 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.
+- Name tonight's first simpler take in the mounted rehearsal workspace so the room can get through the section together; the Open action moves to the matching rendered map section, while inherited or accessor-backed runtime metadata remains guidance-only instead of becoming navigation authority.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 
 ### Changed

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 tonight's first simpler take, then opens the matching rendered map section. Do not invent an easier pass from setup notes, cues, or overlap warnings. `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/FirstSimplificationCallout.particle.test.tsx

@@ -0,0 +1,41 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstSimplificationCallout } from "./FirstSimplificationCallout";
+
+describe("FirstSimplificationCallout Korean role copy", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps vowel-ending dynamic role names particle-safe before and after the simpler-take action", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0]!.name = "피아노";
+
+    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 = "0";
+    Object.defineProperty(target, "scrollIntoView", {
+      configurable: true,
+      value: vi.fn()
+    });
+    grid.appendChild(target);
+    document.body.appendChild(grid);
+
+    render(<FirstSimplificationCallout song={song} />);
+
+    expect(screen.getByText("0:10 벌스에서 피아노 파트가 더 쉽게 칠 수 있습니다.")).toBeTruthy();
+    expect(screen.queryByText(/피아노이/)).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: "0:10 피아노 쉬운 패스 위치 열기" }));
+
+    expect(screen.getByText("0:10에서 피아노 파트와 함께 쉬운 패스로 넘기세요. 같이 통과하세요.")).toBeTruthy();
+    expect(screen.queryByText(/피아노과/)).toBeNull();
+
+    grid.remove();
+  });
+});

apps/desktop/src/features/workspace/FirstSimplificationCallout.reduced-motion.test.tsx

@@ -0,0 +1,41 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstSimplificationCallout } from "./FirstSimplificationCallout";
+
+describe("FirstSimplificationCallout reduced motion", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("scrolls immediately when the operating system requests reduced motion", () => {
+    vi.stubGlobal("matchMedia", (query: string) => ({
+      matches: query === "(prefers-reduced-motion: reduce)",
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn()
+    }));
+
+    const grid = document.createElement("div");
+    grid.dataset.testid = "song-structure-grid";
+    const target = document.createElement("div");
+    target.dataset.sectionIndex = "0";
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(target, "scrollIntoView", {
+      configurable: true,
+      value: scrollIntoView
+    });
+    grid.appendChild(target);
+    document.body.appendChild(grid);
+
+    render(<FirstSimplificationCallout song={createDemoRehearsalSong()} />);
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" }));
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "auto" });
+
+    grid.remove();
+  });
+});

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

@@ -0,0 +1,229 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstSimplificationCallout } from "./FirstSimplificationCallout";
+
+function songWithoutSimplification() {
+  const song = createDemoRehearsalSong();
+  for (const section of song.sections) {
+    for (const role of section.roles) {
+      role.simplification = "   ";
+    }
+  }
+  return song;
+}
+
+function appendSongStructureTarget(ariaLabel = "Scrollable song structure timeline") {
+  const timeline = document.createElement("div");
+  timeline.setAttribute("role", "region");
+  timeline.setAttribute("aria-label", ariaLabel);
+  const grid = document.createElement("div");
+  grid.dataset.testid = "song-structure-grid";
+  const target = document.createElement("div");
+  target.dataset.sectionIndex = "0";
+  const scrollIntoView = vi.fn();
+  Object.defineProperty(target, "scrollIntoView", {
+    configurable: true,
+    value: scrollIntoView
+  });
+  grid.appendChild(target);
+  timeline.appendChild(grid);
+  document.body.appendChild(timeline);
+  return { grid: timeline, scrollIntoView };
+}
+
+describe("FirstSimplificationCallout", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("contains a malformed runtime song root instead of crashing the callout", () => {
+    render(<FirstSimplificationCallout song={null as unknown as RehearsalSong} />);
+
+    expect(
+      screen.getByText("No simpler take yet. Stay on tonight's map until a part names an easier pass.")
+    ).toBeTruthy();
+  });
+
+  it("contains a hostile song identity accessor instead of crashing the callout", () => {
+    const song = createDemoRehearsalSong();
+    Object.defineProperty(song, "id", {
+      configurable: true,
+      enumerable: true,
+      get() {
+        throw new Error("hostile song id getter");
+      }
+    });
+
+    expect(() => render(<FirstSimplificationCallout song={song} />)).not.toThrow();
+    expect(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" })).toBeTruthy();
+  });
+
+  it("resets armed guidance when accessor-id songs change with the same simplification signature", () => {
+    const firstSong = createDemoRehearsalSong();
+    const nextSong = createDemoRehearsalSong();
+    for (const song of [firstSong, nextSong]) {
+      Object.defineProperty(song, "id", {
+        configurable: true,
+        enumerable: true,
+        get() {
+          throw new Error("hostile song id getter");
+        }
+      });
+    }
+    const { grid } = appendSongStructureTarget();
+    const { rerender } = render(<FirstSimplificationCallout song={firstSong} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" }));
+    expect(
+      screen.getByText(/Use the simpler take with Bass Guitar at 0:10. Get through it together./)
+    ).toBeTruthy();
+
+    rerender(<FirstSimplificationCallout song={nextSong} />);
+
+    expect(screen.getByText("Bass Guitar can play simpler in the verse at 0:10.")).toBeTruthy();
+    expect(
+      screen.queryByText(/Use the simpler take with Bass Guitar at 0:10. Get through it together./)
+    ).toBeNull();
+
+    grid.remove();
+  });
+
+  it("keeps armed guidance across unrelated immutable edits to the same song", () => {
+    const initialSong = createDemoRehearsalSong();
+    const { grid } = appendSongStructureTarget();
+    const { rerender } = render(<FirstSimplificationCallout song={initialSong} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" }));
+    expect(
+      screen.getByText(/Use the simpler take with Bass Guitar at 0:10. Get through it together./)
+    ).toBeTruthy();
+
+    const updatedSong = structuredClone(initialSong);
+    updatedSong.sections[0]!.roles[0]!.practiceProgress = 60;
+    rerender(<FirstSimplificationCallout song={updatedSong} />);
+
+    expect(
+      screen.getByText(/Use the simpler take with Bass Guitar at 0:10. Get through it together./)
+    ).toBeTruthy();
+
+    grid.remove();
+  });
+
+  it("names the first simpler take as map navigation, scrolls to its rendered section, and arms that action", () => {
+    const { grid, scrollIntoView } = appendSongStructureTarget();
+
+    render(<FirstSimplificationCallout song={createDemoRehearsalSong()} />);
+
+    expect(screen.getByText("Stay on roots if the chorus entrance gets muddy.")).toBeTruthy();
+    const action = screen.getByRole("button", {
+      name: "Open Bass Guitar simpler take at 0:10"
+    });
+    expect(action).toBeTruthy();
+    fireEvent.click(action);
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+    expect(
+      screen.getByText(/Use the simpler take with Bass Guitar at 0:10. Get through it together./)
+    ).toBeTruthy();
+
+    grid.remove();
+  });
+
+  it("keeps map navigation stable when the renderer accessible name is localized", () => {
+    const { grid, scrollIntoView } = appendSongStructureTarget("스크롤 가능한 곡 구조 타임라인");
+
+    render(<FirstSimplificationCallout song={createDemoRehearsalSong()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" }));
+
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+    expect(
+      screen.getByText(/Use the simpler take with Bass Guitar at 0:10. Get through it together./)
+    ).toBeTruthy();
+
+    grid.remove();
+  });
+
+  it("does not claim map navigation completed when the rendered section target is missing", () => {
+    render(<FirstSimplificationCallout song={createDemoRehearsalSong()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" }));
+
+    expect(screen.getByText("Bass Guitar can play simpler in the verse at 0:10.")).toBeTruthy();
+    expect(
+      screen.queryByText(/Use the simpler take with Bass Guitar at 0:10. Get through it together./)
+    ).toBeNull();
+  });
+
+  it("navigates by renderer-owned section position instead of untrusted analysis ids", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.id = "analysis section / duplicate";
+    const { grid, scrollIntoView } = appendSongStructureTarget();
+
+    render(<FirstSimplificationCallout song={song} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" }));
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+
+    grid.remove();
+  });
+
+  it("scopes map navigation to the song-structure renderer when another surface reuses an index", () => {
+    const decoy = document.createElement("div");
+    decoy.dataset.sectionIndex = "0";
+    const decoyScrollIntoView = vi.fn();
+    Object.defineProperty(decoy, "scrollIntoView", {
+      configurable: true,
+      value: decoyScrollIntoView
+    });
+    document.body.appendChild(decoy);
+    const { grid, scrollIntoView } = appendSongStructureTarget();
+
+    render(<FirstSimplificationCallout song={createDemoRehearsalSong()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" }));
+
+    expect(decoyScrollIntoView).not.toHaveBeenCalled();
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+
+    decoy.remove();
+    grid.remove();
+  });
+
+  it("shows fresh guidance when the first simpler take changes or returns later", () => {
+    const initialSong = createDemoRehearsalSong();
+    const { grid } = appendSongStructureTarget();
+    const { rerender } = render(<FirstSimplificationCallout song={initialSong} />);
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar simpler take at 0:10" }));
+    expect(
+      screen.getByText(/Use the simpler take with Bass Guitar at 0:10. Get through it together./)
+    ).toBeTruthy();
+
+    const nextSong = createDemoRehearsalSong();
+    nextSong.id = "next-song";
+    nextSong.sections[0]!.timeRange = { start: 24, end: 44 };
+    rerender(<FirstSimplificationCallout song={nextSong} />);
+    expect(screen.getByText("Bass Guitar can play simpler in the verse at 0:24.")).toBeTruthy();
+
+    grid.remove();
+  });
+
+  it("keeps an unavailable simpler take guidance-only", () => {
+    render(<FirstSimplificationCallout song={songWithoutSimplification()} />);
+    expect(screen.queryByRole("button")).toBeNull();
+    expect(
+      screen.getByText("No simpler take yet. Stay on tonight's map until a part names an easier pass.")
+    ).toBeTruthy();
+  });
+
+  it("localizes the section form label instead of exposing its raw enum in Korean copy", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0]!.name = "베이스";
+
+    render(<FirstSimplificationCallout song={song} />);
+
+    expect(screen.getByText("0:10 벌스에서 베이스 파트가 더 쉽게 칠 수 있습니다.")).toBeTruthy();
+    expect(screen.queryByText(/verse에서/)).toBeNull();
+  });
+});