feat(workspace): name tonight's first transition cue 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 owned transition cue with the holding part when an active role is corroborated, the change, 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 owned transition cue must name the holding part when corroborated, the change, and the time so the next action is obvious. Open moves to the matching rendered map section. Do not invent a transition from lyric, count, groove, setup, simplification, overlap, or form labels.
 
 ## 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 owned transition cue in the mounted rehearsal workspace so the room can catch the change together; the Open action moves to the matching rendered map section, while lyric, count, 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 mounted workspace names tonight's first owned transition cue and opens the matching rendered map section. The ready workspace names tonight's first playable range and the next instrument check. Do not invent a change from lyric, count, groove, or unlabeled form. `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/FirstTransitionCallout.identity.test.tsx

@@ -0,0 +1,38 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it, vi } from "vitest";
+import { FirstTransitionCallout } from "./FirstTransitionCallout";
+
+function appendTransitionTarget() {
+  const renderer = document.createElement("div");
+  renderer.dataset.testid = "song-structure-grid";
+  const target = document.createElement("div");
+  target.dataset.sectionIndex = "0";
+  Object.defineProperty(target, "scrollIntoView", {
+    configurable: true,
+    value: vi.fn()
+  });
+  renderer.appendChild(target);
+  document.body.appendChild(renderer);
+  return renderer;
+}
+
+describe("FirstTransitionCallout song identity", () => {
+  it("keeps opened guidance when an immutable update replaces the song object without changing the transition", () => {
+    const renderer = appendTransitionTarget();
+    const song = createDemoRehearsalSong();
+    const { rerender } = render(<FirstTransitionCallout song={song} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar transition at 0:10" }));
+    expect(
+      screen.getByText("Catch the change with Bass Guitar at 0:10. Stay together through it.")
+    ).toBeTruthy();
+
+    rerender(<FirstTransitionCallout song={{ ...song }} />);
+
+    expect(
+      screen.getByText("Catch the change with Bass Guitar at 0:10. Stay together through it.")
+    ).toBeTruthy();
+    renderer.remove();
+  });
+});

apps/desktop/src/features/workspace/FirstTransitionCallout.landmark-id.test.tsx

@@ -0,0 +1,22 @@
+import { render } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { expect, it } from "vitest";
+import { FirstTransitionCallout } from "./FirstTransitionCallout";
+
+it("gives co-mounted transition callouts distinct DOM identities", () => {
+  const song = createDemoRehearsalSong();
+  const { container } = render(
+    <>
+      <FirstTransitionCallout song={song} />
+      <FirstTransitionCallout song={song} />
+    </>
+  );
+
+  const calloutIds = Array.from(
+    container.querySelectorAll<HTMLElement>('[id^="workspace-surface-transition-"]'),
+    (element) => element.id
+  );
+
+  expect(calloutIds).toHaveLength(2);
+  expect(new Set(calloutIds).size).toBe(calloutIds.length);
+});

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

@@ -0,0 +1,52 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstTransitionCallout } from "./FirstTransitionCallout";
+
+describe("FirstTransitionCallout Korean role copy", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps vowel-ending dynamic role names particle-safe before and after the transition action", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = [
+      {
+        ...song.sections[0]!.roles[0]!,
+        id: "piano",
+        name: "피아노",
+        rehearsalPriority: "high",
+        cue: { kind: "transition", value: "픽업 뒤에서 다운비트를 잡으세요." }
+      }
+    ];
+    song.sections[0]!.partGraph = [
+      { role_id: "piano", is_active: true, handoff_to: [], handoff_from: [] }
+    ];
+
+    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(<FirstTransitionCallout 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/FirstTransitionCallout.reduced-motion.test.tsx

@@ -0,0 +1,43 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstTransitionCallout } from "./FirstTransitionCallout";
+
+describe("FirstTransitionCallout 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";
+    grid.setAttribute("role", "region");
+    grid.setAttribute("aria-label", "Scrollable song structure timeline");
+    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(<FirstTransitionCallout song={createDemoRehearsalSong()} />);
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar transition at 0:10" }));
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "auto" });
+
+    grid.remove();
+  });
+});

apps/desktop/src/features/workspace/FirstTransitionCallout.resolver-cache.test.tsx

@@ -0,0 +1,25 @@
+import { render } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstTransitionCallout } from "./FirstTransitionCallout";
+
+describe("FirstTransitionCallout resolver reuse", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("does not rescan transition metadata when a parent rerenders the same song object", () => {
+    const song = createDemoRehearsalSong();
+    const role = song.sections[0]!.roles[0]!;
+    const descriptorSpy = vi.spyOn(Object, "getOwnPropertyDescriptor");
+
+    const { rerender } = render(<FirstTransitionCallout song={song} />);
+    const firstScanCount = descriptorSpy.mock.calls.filter(([target]) => target === role).length;
+    expect(firstScanCount).toBeGreaterThan(0);
+
+    rerender(<FirstTransitionCallout song={song} />);
+    const secondScanCount = descriptorSpy.mock.calls.filter(([target]) => target === role).length;
+
+    expect(secondScanCount).toBe(firstScanCount);
+  });
+});