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

@@ -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 count must name the entering part when corroborated, the owned count cue, the labeled section, and the time so the next action is obvious. Open moves to the matching rendered map section. Do not invent an entrance from lyric, transition, 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

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Name tonight's first count in the mounted rehearsal workspace so the room can catch the entrance 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.
 - 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 count and opens the matching rendered map section. The ready workspace names tonight's first playable range and the next instrument check. Do not invent an entrance from lyric, transition, 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/FirstCountCueCallout.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 { FirstCountCueCallout } from "./FirstCountCueCallout";
+
+describe("FirstCountCueCallout Korean role copy", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps vowel-ending dynamic role names particle-safe before and after the count action", () => {
+    vi.stubGlobal("navigator", { language: "ko-KR" });
+    const song = createDemoRehearsalSong();
+    const seed = song.sections[0]!;
+    seed.roles = [
+      {
+        ...seed.roles[1]!,
+        id: "piano",
+        name: "피아노",
+        rehearsalPriority: "high",
+        cue: { kind: "count", value: "픽업 다음 2박에 들어가세요." }
+      }
+    ];
+    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(<FirstCountCueCallout 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/FirstCountCueCallout.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 { FirstCountCueCallout } from "./FirstCountCueCallout";
+
+describe("FirstCountCueCallout 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(<FirstCountCueCallout song={createDemoRehearsalSong()} />);
+    fireEvent.click(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand count at 0:10" }));
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "auto" });
+
+    grid.remove();
+  });
+});

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