diff --git a/AGENTS.md b/AGENTS.md
index b9a67ce17..c287a433f 100644
--- a/AGENTS.md
+++ b/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 open rehearsal comment with the author, the corroborated holding 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.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index ca0df5ac4..ff19d2a74 100644
--- a/ARCHITECTURE.md
+++ b/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 open rehearsal comment must name the author, the corroborated holding 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 note from resolved comments, assignments, approvals, cues, 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
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b6f7e784..bf282b41b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
### Added
+- Name tonight's first open rehearsal comment in the mounted rehearsal workspace so the room can read the MD note and open 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 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
diff --git a/CLAUDE.md b/CLAUDE.md
index b5a34c1fa..530d8d771 100644
--- a/CLAUDE.md
+++ b/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 open rehearsal comment 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 note from resolved comments, assignments, approvals, cues, 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.
diff --git a/apps/desktop/src/features/workspace/FirstOpenCommentCallout.particle.test.tsx b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.particle.test.tsx
new file mode 100644
index 000000000..b6024272a
--- /dev/null
+++ b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.particle.test.tsx
@@ -0,0 +1,60 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FirstOpenCommentCallout } from "./FirstOpenCommentCallout";
+
+describe("FirstOpenCommentCallout Korean role copy", () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ it("keeps vowel-ending dynamic role names particle-safe before and after the note 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"
+ }
+ ];
+ seed.partGraph = [{ role_id: "piano", is_active: true, handoff_to: [], handoff_from: [] }];
+ song.collaboration!.comments = [
+ {
+ id: "comment-piano-color",
+ author: "MD",
+ body: "첫 패스에서는 톤을 부드럽게 유지하세요.",
+ sectionId: seed.id,
+ roleId: "piano",
+ status: "open"
+ }
+ ];
+
+ 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();
+
+ expect(screen.getByText("MD님이 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();
+ });
+});
diff --git a/apps/desktop/src/features/workspace/FirstOpenCommentCallout.proxy.test.tsx b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.proxy.test.tsx
new file mode 100644
index 000000000..e2d2dbdac
--- /dev/null
+++ b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.proxy.test.tsx
@@ -0,0 +1,28 @@
+import { render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import { FirstOpenCommentCallout } from "./FirstOpenCommentCallout";
+
+describe("FirstOpenCommentCallout hostile runtime identity", () => {
+ it("contains a song identity descriptor trap without discarding the valid owned comment", () => {
+ const song = createDemoRehearsalSong();
+ const hostileSong = new Proxy(song, {
+ getOwnPropertyDescriptor(target, property) {
+ if (property === "id") {
+ throw new Error("hostile song id descriptor trap");
+ }
+ return Reflect.getOwnPropertyDescriptor(target, property);
+ }
+ });
+
+ expect(() => render()).not.toThrow();
+ expect(
+ screen.getByText("MD left a note for Keyboard 1 Right Hand in the verse at 0:10.")
+ ).toBeTruthy();
+ expect(
+ screen.getByText(
+ "Keep the keyboard color tone gentle on the first pass so the vocal cue stays forward."
+ )
+ ).toBeTruthy();
+ });
+});
diff --git a/apps/desktop/src/features/workspace/FirstOpenCommentCallout.reduced-motion.test.tsx b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.reduced-motion.test.tsx
new file mode 100644
index 000000000..ff502cfff
--- /dev/null
+++ b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.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 { FirstOpenCommentCallout } from "./FirstOpenCommentCallout";
+
+describe("FirstOpenCommentCallout 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();
+ fireEvent.click(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand at 0:10" }));
+ expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "auto" });
+
+ grid.remove();
+ });
+});
diff --git a/apps/desktop/src/features/workspace/FirstOpenCommentCallout.stories.tsx b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.stories.tsx
new file mode 100644
index 000000000..352388d8e
--- /dev/null
+++ b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.stories.tsx
@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+
+import { FirstOpenCommentCallout } from "./FirstOpenCommentCallout";
+
+const availableSong = createDemoRehearsalSong();
+const unavailableSong = createDemoRehearsalSong();
+for (const comment of unavailableSong.collaboration?.comments ?? []) {
+ comment.status = "resolved";
+}
+
+const meta = {
+ title: "Workspace/First Open Comment Callout",
+ component: FirstOpenCommentCallout,
+ parameters: { layout: "padded" },
+ decorators: [
+ (Story) => (
+
+
+
+ Song structure target · section 1
+
+
+
+
+ )
+ ]
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Figma workspace next-action pattern with the earliest owned open rehearsal note. */
+export const Available: Story = {
+ args: { song: availableSong }
+};
+
+/** Guidance-only state when tonight's map has no owned open rehearsal note. */
+export const Unavailable: Story = {
+ args: { song: unavailableSong }
+};
diff --git a/apps/desktop/src/features/workspace/FirstOpenCommentCallout.test.tsx b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.test.tsx
new file mode 100644
index 000000000..3e9369ad1
--- /dev/null
+++ b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.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 { FirstOpenCommentCallout } from "./FirstOpenCommentCallout";
+
+function songWithOpenComment() {
+ 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("FirstOpenCommentCallout", () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ it("contains a malformed runtime song root instead of crashing the callout", () => {
+ render();
+
+ expect(
+ screen.getByText("No open note yet. Stay on tonight's map until someone leaves a rehearsal comment.")
+ ).toBeTruthy();
+ });
+
+ it("contains a hostile song identity accessor instead of crashing the callout", () => {
+ const song = songWithOpenComment();
+ Object.defineProperty(song, "id", {
+ configurable: true,
+ enumerable: true,
+ get() {
+ throw new Error("hostile song id getter");
+ }
+ });
+
+ expect(() => render()).not.toThrow();
+ expect(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand at 0:10" })).toBeTruthy();
+ });
+
+ it("keeps armed guidance when an unrelated song edit preserves the first-open-note identity", () => {
+ const firstSong = songWithOpenComment();
+ const nextSong = { ...firstSong };
+ const { grid } = appendSongStructureTarget();
+ const { rerender } = render();
+
+ fireEvent.click(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand at 0:10" }));
+ expect(
+ screen.getByText(/Read MD's note with Keyboard 1 Right Hand at 0:10. Keep that part in view./)
+ ).toBeTruthy();
+
+ rerender();
+
+ expect(
+ screen.getByText(/Read MD's note with Keyboard 1 Right Hand at 0:10. Keep that part in view./)
+ ).toBeTruthy();
+ expect(screen.queryByText("MD left a note for Keyboard 1 Right Hand in the verse at 0:10.")).toBeNull();
+
+ grid.remove();
+ });
+
+ it("names the first open note as map navigation, scrolls to its rendered section, and arms that action", () => {
+ const { grid, scrollIntoView } = appendSongStructureTarget();
+
+ render();
+
+ expect(
+ screen.getByText("Keep the keyboard color tone gentle on the first pass so the vocal cue stays forward.")
+ ).toBeTruthy();
+ const action = screen.getByRole("button", {
+ name: "Open Keyboard 1 Right Hand at 0:10"
+ });
+ expect(action).toBeTruthy();
+ fireEvent.click(action);
+ expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+ expect(
+ screen.getByText(/Read MD's note with Keyboard 1 Right Hand at 0:10. Keep that part in view./)
+ ).toBeTruthy();
+
+ grid.remove();
+ });
+
+ it("keeps map navigation stable when the renderer accessible name is localized", () => {
+ const { grid, scrollIntoView } = appendSongStructureTarget("스크롤 가능한 곡 구조 타임라인");
+
+ render();
+
+ fireEvent.click(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand at 0:10" }));
+
+ expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+ expect(
+ screen.getByText(/Read MD's note with Keyboard 1 Right Hand at 0:10. Keep that part in view./)
+ ).toBeTruthy();
+
+ grid.remove();
+ });
+
+ it("does not claim map navigation completed when the rendered section target is missing", () => {
+ render();
+
+ fireEvent.click(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand at 0:10" }));
+
+ expect(screen.getByText("MD left a note for Keyboard 1 Right Hand in the verse at 0:10.")).toBeTruthy();
+ expect(
+ screen.queryByText(/Read MD's note with Keyboard 1 Right Hand at 0:10. Keep that part in view./)
+ ).toBeNull();
+ });
+
+ it("navigates by renderer-owned section position instead of untrusted analysis ids", () => {
+ const song = songWithOpenComment();
+ song.sections[0]!.id = "analysis section / duplicate";
+ song.collaboration!.comments[0]!.sectionId = "analysis section / duplicate";
+ const { grid, scrollIntoView } = appendSongStructureTarget();
+
+ render();
+
+ fireEvent.click(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand 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();
+
+ fireEvent.click(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand 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 open note changes or returns later", () => {
+ const initialSong = songWithOpenComment();
+ const { grid } = appendSongStructureTarget();
+ const { rerender } = render();
+ fireEvent.click(screen.getByRole("button", { name: "Open Keyboard 1 Right Hand at 0:10" }));
+ expect(
+ screen.getByText(/Read MD's note with Keyboard 1 Right Hand at 0:10. Keep that part in view./)
+ ).toBeTruthy();
+
+ const nextSong = songWithOpenComment();
+ nextSong.id = "next-song";
+ nextSong.sections[0]!.timeRange = { start: 20, end: 40 };
+ rerender();
+ expect(screen.getByText("MD left a note for Keyboard 1 Right Hand in the verse at 0:20.")).toBeTruthy();
+
+ grid.remove();
+ });
+
+ it("keeps an unavailable note guidance-only", () => {
+ const song = songWithOpenComment();
+ for (const comment of song.collaboration!.comments) {
+ comment.status = "resolved";
+ }
+ render();
+ expect(screen.queryByRole("button")).toBeNull();
+ expect(
+ screen.getByText("No open note yet. Stay on tonight's map until someone leaves a rehearsal comment.")
+ ).toBeTruthy();
+ });
+
+ it("names a section-wide note when no part carries it", () => {
+ const song = songWithOpenComment();
+ delete song.collaboration!.comments[0]!.roleId;
+ const { grid, scrollIntoView } = appendSongStructureTarget();
+ render();
+ const action = screen.getByRole("button", { name: "Open the first note at 0:10" });
+ expect(screen.getByText("MD left a note in the verse at 0:10.")).toBeTruthy();
+ fireEvent.click(action);
+ expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+ expect(screen.getByText("Read MD's note at 0:10. Keep that section in view.")).toBeTruthy();
+ grid.remove();
+ });
+
+ it("localizes the comment form label instead of exposing its raw enum in Korean copy", () => {
+ vi.stubGlobal("navigator", { language: "ko-KR" });
+ const song = songWithOpenComment();
+ song.sections[0]!.roles[1]!.name = "키보드 오른손";
+
+ render();
+
+ expect(screen.getByText("MD님이 0:10 벌스에서 키보드 오른손 파트에 메모를 남겼습니다.")).toBeTruthy();
+ expect(screen.queryByText(/verse에서/)).toBeNull();
+ });
+
+ it("renders the owned comment body as a text node instead of template syntax", () => {
+ const song = songWithOpenComment();
+ song.collaboration!.comments[0]!.body = "Keep {role} gentle at {at}";
+ render();
+ expect(screen.getByText("Keep {role} gentle at {at}")).toBeTruthy();
+ expect(screen.queryByText("Keep Keyboard 1 Right Hand gentle at 0:10")).toBeNull();
+ });
+});
diff --git a/apps/desktop/src/features/workspace/FirstOpenCommentCallout.tsx b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.tsx
new file mode 100644
index 000000000..6b56f8df1
--- /dev/null
+++ b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.tsx
@@ -0,0 +1,183 @@
+import { useEffect, useState } from "react";
+import type { RehearsalSong } from "@bandscope/shared-types";
+import { Button } from "@/components/ui/button";
+import {
+ createTranslator,
+ detectPreferredLocale,
+ translateSectionFormLabel
+} from "../../i18n";
+import { formatOpenCommentTime, resolveFirstOpenComment } from "./firstOpenComment";
+
+/** Props for the first-open-comment rehearsal callout. */
+export interface FirstOpenCommentCalloutProps {
+ song: RehearsalSong;
+}
+
+type OpenCommentCopyValues = Readonly>;
+
+type OpenedOpenComment = Readonly<{
+ songIdentifier: string | null;
+ commentId: string;
+ sectionId: string;
+ sectionIndex: number;
+ holdingRoleId: string | null;
+ atSeconds: number;
+}>;
+
+/** Read a stable song id only when runtime data owns it as a plain string value. */
+function ownedSongIdentifier(song: RehearsalSong): string | null {
+ if (song === null || typeof song !== "object" || Array.isArray(song)) {
+ return null;
+ }
+ let descriptor: PropertyDescriptor | undefined;
+ try {
+ descriptor = Object.getOwnPropertyDescriptor(song, "id");
+ } catch {
+ return null;
+ }
+ return descriptor !== undefined &&
+ Object.prototype.hasOwnProperty.call(descriptor, "value") &&
+ typeof descriptor.value === "string"
+ ? descriptor.value
+ : null;
+}
+
+/** Interpolate comment placeholders once so rehearsal data is never rescanned as template syntax. */
+function formatOpenCommentCopy(template: string, values: OpenCommentCopyValues): string {
+ return template.replace(/\{(author|role|section|at)\}/g, (placeholder) => {
+ const key = placeholder.slice(1, -1) as keyof OpenCommentCopyValues;
+ return values[key] ?? placeholder;
+ });
+}
+
+/** Use immediate scrolling when the operating system requests reduced motion. */
+function preferredOpenCommentScrollBehavior(): ScrollBehavior {
+ return typeof window.matchMedia === "function" &&
+ window.matchMedia("(prefers-reduced-motion: reduce)").matches
+ ? "auto"
+ : "smooth";
+}
+
+/** Resolve the song-structure renderer owned by this workspace, failing closed on ambiguous mounts. */
+function resolveOpenCommentRenderer(origin: HTMLElement): HTMLElement | null {
+ const selector = '[data-testid="song-structure-grid"]';
+ const localScope = origin.closest("aside")?.parentElement ?? null;
+ const localRenderers = localScope?.querySelectorAll(selector) ?? [];
+ if (localRenderers.length === 1) {
+ return localRenderers[0] ?? null;
+ }
+ if (localRenderers.length > 1) {
+ return null;
+ }
+
+ const globalRenderers = document.querySelectorAll(selector);
+ return globalRenderers.length === 1 ? (globalRenderers[0] ?? null) : null;
+}
+
+/** Name tonight's first open rehearsal comment and open the matching rendered map section. */
+export function FirstOpenCommentCallout({ song }: FirstOpenCommentCalloutProps) {
+ const locale = detectPreferredLocale();
+ const t = createTranslator(locale);
+ const songIdentifier = ownedSongIdentifier(song);
+ const runtimeSong = song as unknown as Partial | null;
+ const openComment = resolveFirstOpenComment(song);
+ const openCommentSectionIndex =
+ openComment && Array.isArray(runtimeSong?.sections)
+ ? runtimeSong.sections.indexOf(openComment.section)
+ : -1;
+ const [openedOpenComment, setOpenedOpenComment] = useState(null);
+
+ useEffect(() => {
+ setOpenedOpenComment(null);
+ }, [
+ songIdentifier,
+ openCommentSectionIndex,
+ openComment?.comment.id,
+ openComment?.section.id,
+ openComment?.holdingRole?.id,
+ openComment?.atSeconds
+ ]);
+
+ if (!openComment) {
+ return (
+
+ );
+ }
+
+ const opened =
+ openedOpenComment !== null &&
+ openedOpenComment.songIdentifier === songIdentifier &&
+ openedOpenComment.commentId === openComment.comment.id &&
+ openedOpenComment.sectionId === openComment.section.id &&
+ openedOpenComment.sectionIndex === openCommentSectionIndex &&
+ openedOpenComment.holdingRoleId === (openComment.holdingRole?.id ?? null) &&
+ openedOpenComment.atSeconds === openComment.atSeconds;
+ const at = formatOpenCommentTime(openComment.atSeconds);
+ const copyValues: OpenCommentCopyValues = {
+ author: openComment.author,
+ role: openComment.holdingRole?.name ?? "",
+ section: translateSectionFormLabel(locale, openComment.section.label),
+ at
+ };
+ const hasRole = openComment.holdingRole !== null;
+ const actionLabel = formatOpenCommentCopy(
+ t(hasRole ? "firstOpenCommentOpenAction" : "firstOpenCommentOpenActionBand"),
+ copyValues
+ );
+ const body = formatOpenCommentCopy(
+ t(hasRole ? "firstOpenCommentBody" : "firstOpenCommentBodyBand"),
+ copyValues
+ );
+ const armed = formatOpenCommentCopy(
+ t(hasRole ? "firstOpenCommentArmed" : "firstOpenCommentArmedBand"),
+ copyValues
+ );
+
+ return (
+
+ );
+}
diff --git a/apps/desktop/src/features/workspace/FirstOpenCommentCallout.workspace-scope.test.tsx b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.workspace-scope.test.tsx
new file mode 100644
index 000000000..308828c27
--- /dev/null
+++ b/apps/desktop/src/features/workspace/FirstOpenCommentCallout.workspace-scope.test.tsx
@@ -0,0 +1,54 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it, vi } from "vitest";
+import { FirstOpenCommentCallout } from "./FirstOpenCommentCallout";
+
+describe("FirstOpenCommentCallout workspace scope", () => {
+ it("opens the song-structure renderer owned by the current workspace", () => {
+ const firstSong = createDemoRehearsalSong();
+ const secondSong = createDemoRehearsalSong();
+ secondSong.id = "second-workspace-song";
+
+ const { container } = render(
+ <>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+
+ const targets = container.querySelectorAll('[data-section-index="0"]');
+ expect(targets).toHaveLength(2);
+ const firstScrollIntoView = vi.fn();
+ const secondScrollIntoView = vi.fn();
+ Object.defineProperty(targets[0]!, "scrollIntoView", {
+ configurable: true,
+ value: firstScrollIntoView
+ });
+ Object.defineProperty(targets[1]!, "scrollIntoView", {
+ configurable: true,
+ value: secondScrollIntoView
+ });
+
+ const actions = screen.getAllByRole("button", {
+ name: "Open Keyboard 1 Right Hand at 0:10"
+ });
+ expect(actions).toHaveLength(2);
+ fireEvent.click(actions[1]!);
+
+ expect(firstScrollIntoView).not.toHaveBeenCalled();
+ expect(secondScrollIntoView).toHaveBeenCalledWith({
+ block: "nearest",
+ behavior: "smooth"
+ });
+ });
+});
diff --git a/apps/desktop/src/features/workspace/Workspace.test.tsx b/apps/desktop/src/features/workspace/Workspace.test.tsx
index 7837bf80e..ab46b410e 100644
--- a/apps/desktop/src/features/workspace/Workspace.test.tsx
+++ b/apps/desktop/src/features/workspace/Workspace.test.tsx
@@ -326,4 +326,32 @@ describe("Workspace", () => {
expect(screen.getByText("합주 우선순위")).toBeTruthy();
expect(screen.getByText("역할과 화성")).toBeTruthy();
});
+
+ it("names tonight's first open rehearsal comment as workspace navigation", () => {
+ const song = createDemoRehearsalSong();
+
+ render();
+
+ const target = screen.getByTestId("song-structure-grid").children.item(0);
+ expect(target).toBeTruthy();
+ const scrollIntoView = vi.fn();
+ Object.defineProperty(target!, "scrollIntoView", {
+ configurable: true,
+ value: scrollIntoView
+ });
+
+ expect(
+ screen.getAllByText("Keep the keyboard color tone gentle on the first pass so the vocal cue stays forward.")
+ .length
+ ).toBeGreaterThan(0);
+ const action = screen.getByRole("button", {
+ name: "Open Keyboard 1 Right Hand at 0:10"
+ });
+ expect(action).toBeTruthy();
+ fireEvent.click(action);
+ expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest", behavior: "smooth" });
+ expect(
+ screen.getByText(/Read MD's note with Keyboard 1 Right Hand at 0:10. Keep that part in view./)
+ ).toBeTruthy();
+ });
});
diff --git a/apps/desktop/src/features/workspace/Workspace.tsx b/apps/desktop/src/features/workspace/Workspace.tsx
index d44e20777..fcd43d3b2 100644
--- a/apps/desktop/src/features/workspace/Workspace.tsx
+++ b/apps/desktop/src/features/workspace/Workspace.tsx
@@ -4,6 +4,7 @@ import { RoleSwitcher } from "./RoleSwitcher";
import { SectionRoadmap } from "./SectionRoadmap";
import { GrooveMap } from "./GrooveMap";
import { PracticeProgress } from "./PracticeProgress";
+import { FirstOpenCommentCallout } from "./FirstOpenCommentCallout";
import { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze";
import { createTranslator, detectPreferredLocale } from "../../i18n";
import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
@@ -91,8 +92,12 @@ const SongStructure = memo(function SongStructure({ sections, t }: { sections: R
data-testid="song-structure-grid"
style={{ gridTemplateColumns: `repeat(${Math.max(1, sections.length)}, minmax(8rem, 1fr))` }}
>
- {sections.map((section) => (
-