feat(workspace): name tonight's first transition 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 transition with the changing part when an active role is corroborated, the owned transition cue, 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, 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

@@ -5,6 +5,7 @@ Last updated: 2026-03-11
 ## 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 transition must name the changing part when corroborated, the owned transition cue, the labeled section, and the time so the next action is obvious. Open moves to the matching rendered map section. Do not invent a change from lyric, count, groove, setup, simplification, overlap, or range copy.
 - 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

@@ -5,6 +5,7 @@
 ### Added
 
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
+- Name tonight's first transition in the mounted rehearsal workspace so the room can catch the change 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 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 
 ## [0.1.3] - 2026-04-29

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). `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 transition and opens the matching rendered map section. Do not invent a change from lyric, count, groove, setup, simplification, overlap, or range copy. `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.particle.test.tsx

@@ -0,0 +1,51 @@
+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();
+    const seed = song.sections[0]!;
+    seed.roles = [
+      {
+        ...seed.roles[0]!,
+        id: "piano",
+        name: "피아노",
+        rehearsalPriority: "high",
+        cue: { kind: "transition", value: "픽업 직전까지 붙잡으세요." }
+      }
+    ];
+    seed.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.test.tsx

@@ -0,0 +1,221 @@
+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 { FirstTransitionCallout } from "./FirstTransitionCallout";
+
+function songWithTransition() {
+  return createDemoRehearsalSong();
+}
+
+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("FirstTransitionCallout", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("contains a malformed runtime song root instead of crashing the callout", () => {
+    render(<FirstTransitionCallout song={null as unknown as RehearsalSong} />);
+
+    expect(
+      screen.getByText("No transition yet. Stay on tonight's map until a part names the change.")
+    ).toBeTruthy();
+  });
+
+  it("contains a hostile song identity accessor instead of crashing the callout", () => {
+    const song = songWithTransition();
+    Object.defineProperty(song, "id", {
+      configurable: true,
+      enumerable: true,
+      get() {
+        throw new Error("hostile song id getter");
+      }
+    });
+
+    expect(() => render(<FirstTransitionCallout song={song} />)).not.toThrow();
+    expect(screen.getByRole("button", { name: "Open Bass Guitar transition at 0:10" })).toBeTruthy();
+  });
+
+  it("resets armed guidance when accessor-id songs change with the same transition signature", () => {
+    const firstSong = songWithTransition();
+    const nextSong = songWithTransition();
+    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(<FirstTransitionCallout song={firstSong} />);
+
+    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. Hold through together./)).toBeTruthy();
+
+    rerender(<FirstTransitionCallout song={nextSong} />);
+
+    expect(screen.getByText("Bass Guitar changes in the verse at 0:10.")).toBeTruthy();
+    expect(screen.queryByText(/Catch the change with Bass Guitar at 0:10. Hold through together./)).toBeNull();
+
+    grid.remove();
+  });
+
+  it("names the first transition as map navigation, scrolls to its rendered section, and arms that action", () => {
+    const { grid, scrollIntoView } = appendSongStructureTarget();
+
+    render(<FirstTransitionCallout song={songWithTransition()} />);
+
+    expect(screen.getByText("Hold through the pickup before the downbeat.")).toBeTruthy();
+    const action = screen.getByRole("button", {
+      name: "Open Bass Guitar transition at 0:10"
+    });
+    expect(action).toBeTruthy();
+    fireEvent.click(action);
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+    expect(screen.getByText(/Catch the change with Bass Guitar at 0:10. Hold through together./)).toBeTruthy();
+
+    grid.remove();
+  });
+
+  it("keeps map navigation stable when the renderer accessible name is localized", () => {
+    const { grid, scrollIntoView } = appendSongStructureTarget("스크롤 가능한 곡 구조 타임라인");
+
+    render(<FirstTransitionCallout song={songWithTransition()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar transition at 0:10" }));
+
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+    expect(screen.getByText(/Catch the change with Bass Guitar at 0:10. Hold through together./)).toBeTruthy();
+
+    grid.remove();
+  });
+
+  it("does not claim map navigation completed when the rendered section target is missing", () => {
+    render(<FirstTransitionCallout song={songWithTransition()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar transition at 0:10" }));
+
+    expect(screen.getByText("Bass Guitar changes in the verse at 0:10.")).toBeTruthy();
+    expect(screen.queryByText(/Catch the change with Bass Guitar at 0:10. Hold through together./)).toBeNull();
+  });
+
+  it("navigates by renderer-owned section position instead of untrusted analysis ids", () => {
+    const song = songWithTransition();
+    song.sections[0]!.id = "analysis section / duplicate";
+    const { grid, scrollIntoView } = appendSongStructureTarget();
+
+    render(<FirstTransitionCallout song={song} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar transition 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(<FirstTransitionCallout song={songWithTransition()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Bass Guitar transition 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 transition changes or returns later", () => {
+    const initialSong = songWithTransition();
+    const { grid } = appendSongStructureTarget();
+    const { rerender } = render(<FirstTransitionCallout song={initialSong} />);
+    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. Hold through together./)).toBeTruthy();
+
+    const nextSong = songWithTransition();
+    nextSong.id = "next-song";
+    nextSong.sections[0]!.timeRange = { start: 20, end: 40 };
+    rerender(<FirstTransitionCallout song={nextSong} />);
+    expect(screen.getByText("Bass Guitar changes in the verse at 0:20.")).toBeTruthy();
+
+    grid.remove();
+  });
+
+  it("keeps an unavailable transition guidance-only", () => {
+    const song = songWithTransition();
+    for (const role of song.sections[0]!.roles) {
+      role.cue = { kind: "lyric", value: "city lights" };
+    }
+    render(<FirstTransitionCallout song={song} />);
+    expect(screen.queryByRole("button")).toBeNull();
+    expect(
+      screen.getByText("No transition yet. Stay on tonight's map until a part names the change.")
+    ).toBeTruthy();
+  });
+
+  it("names a band-wide transition when no part carries it", () => {
+    const song = songWithTransition();
+    for (const node of song.sections[0]!.partGraph) {
+      node.is_active = false;
+    }
+    const { grid, scrollIntoView } = appendSongStructureTarget();
+    render(<FirstTransitionCallout song={song} />);
+    const action = screen.getByRole("button", { name: "Open the first transition at 0:10" });
+    expect(screen.getByText("The band changes in the verse at 0:10.")).toBeTruthy();
+    fireEvent.click(action);
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+    expect(screen.getByText("Catch the change at 0:10. Hold through together.")).toBeTruthy();
+    grid.remove();
+  });
+
+  it("localizes the transition form label instead of exposing its raw enum in Korean copy", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const song = songWithTransition();
+    song.sections[0]!.roles[0]!.name = "베이스 기타";
+    song.sections[0]!.roles[1]!.rehearsalPriority = "low";
+    song.sections[0]!.roles[2]!.rehearsalPriority = "low";
+
+    render(<FirstTransitionCallout song={song} />);
+
+    expect(screen.getByText("0:10 벌스에서 베이스 기타 파트가 바뀝니다.")).toBeTruthy();
+    expect(screen.queryByText(/verse에서/)).toBeNull();
+  });
+
+  it("renders the owned transition cue as a text node instead of template syntax", () => {
+    const song = songWithTransition();
+    song.sections[0]!.roles[0]!.cue = { kind: "transition", value: "Hold {role} at {at}" };
+    song.sections[0]!.roles[1]!.cue = { kind: "count", value: "Enter on beat 2 after the pickup." };
+    song.sections[0]!.roles[2]!.cue = { kind: "lyric", value: "city lights" };
+    render(<FirstTransitionCallout song={song} />);
+    expect(screen.getByText("Hold {role} at {at}")).toBeTruthy();
+    expect(screen.queryByText("Hold Bass Guitar at 0:10")).toBeNull();
+  });
+});