diff --git a/AGENTS.md b/AGENTS.md index fca448ce9..bb4b51aed 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. +- After a part is selected, the transcribe control must open tonight's first notes or range on the groove map. Do not leave `Transcribe` as a no-op or "coming soon", and do not invent a new MIR extractor. - 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. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 3302a6fc3..d45ecdd65 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -68,6 +68,7 @@ Last updated: 2026-03-11 - BandScope is not only a shell around chord labels, stems, and ranges. - The technical scope includes rehearsal-facing outputs for harmony, section roadmap, groove cues, role entry and dropout cues, simplification guidance, transposition or setup guidance, confidence flags, and rehearsal priority. - These outputs must stay aligned with `docs/brand-story.md` rather than drifting back to a song-summary-only analyzer. +- Ready-workspace transcribe control focuses existing role notes or range on the Groove Map. It does not invent isolation playback or a new MIR product. ## Analysis target model diff --git a/CHANGELOG.md b/CHANGELOG.md index eea696893..40d7bc975 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ### Added +- The ready workspace can open tonight's first notes or range on the groove map from the selected part, honors the user's reduced-motion preference for that navigation, and no longer leaves `Transcribe` as a dead end. - 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 82c2c704a..e37ed5f49 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co `AGENTS.md` is the canonical agent operating guide — read and follow it before making changes. It defines the security workflow (`Security Notes`), supply-chain workflow, cross-platform build rules, GitHub bootstrap rules, code style, and safety guardrails. This file complements it with commands and architecture; when in doubt, `AGENTS.md` and the docs it references win. +After a part is selected, the transcribe control must open tonight's first notes or range on the groove map. Do not leave that button as a no-op. + Agent execution and delegation rules live in `docs/agents/README.md`. PR canonicalization rules live in `docs/workflow/pr-continuity.md`. ## Common commands diff --git a/apps/desktop/src/features/workspace/GrooveMap.tsx b/apps/desktop/src/features/workspace/GrooveMap.tsx index 2745d4d79..bc2f2c193 100644 --- a/apps/desktop/src/features/workspace/GrooveMap.tsx +++ b/apps/desktop/src/features/workspace/GrooveMap.tsx @@ -9,11 +9,16 @@ const EMPTY_NOTES: TranscriptionNote[] = []; interface GrooveMapProps { notes?: TranscriptionNote[]; isLoading?: boolean; + regionLabel?: string; + emptyMessage?: string; } /** Documented. */ -function GrooveMapComponent({ notes, isLoading }: GrooveMapProps) { +function GrooveMapComponent({ notes, isLoading, regionLabel, emptyMessage }: GrooveMapProps) { const renderedNotes = notes ?? EMPTY_NOTES; + const mapLabel = regionLabel ?? "Bass transcription groove map"; + const emptyCopy = + emptyMessage ?? "No bass line transcription yet. Use it when you want to check the groove before rehearsal."; // Find max offset to determine timeline width const maxTime = useMemo(() => { @@ -56,19 +61,24 @@ function GrooveMapComponent({ notes, isLoading }: GrooveMapProps) { if (renderedNotes.length === 0) { return (
- No bass line transcription yet. Use it when you want to check the groove before rehearsal. + {emptyCopy}
); } return (
Transcription complete. {renderedNotes.length} notes analyzed. diff --git a/apps/desktop/src/features/workspace/Workspace.cue-action.test.tsx b/apps/desktop/src/features/workspace/Workspace.cue-action.test.tsx new file mode 100644 index 000000000..dc175b483 --- /dev/null +++ b/apps/desktop/src/features/workspace/Workspace.cue-action.test.tsx @@ -0,0 +1,156 @@ +import { fireEvent, render, screen } from "@testing-library/react"; +import { createDemoRehearsalSong } from "@bandscope/shared-types"; +import { afterEach, it, expect, vi } from "vitest"; +import { Workspace } from "./Workspace"; + +const originalLanguage = navigator.language; +const originalScrollIntoView = HTMLElement.prototype.scrollIntoView; + +function setNavigatorLanguage(language: string): void { + Object.defineProperty(navigator, "language", { + configurable: true, + value: language + }); +} + +afterEach(() => { + setNavigatorLanguage(originalLanguage); + HTMLElement.prototype.scrollIntoView = originalScrollIntoView; + vi.restoreAllMocks(); +}); + +it("keeps cue-only roles off the first-notes action until notes or a range exist", () => { + setNavigatorLanguage("en-US"); + const song = createDemoRehearsalSong(); + song.sections[0]!.roles[0] = { + ...song.sections[0]!.roles[0]!, + transcription: undefined, + range: { + lowestNote: "", + highestNote: "" + }, + cue: { + kind: "transition", + value: "Hold through the pickup before the downbeat." + } + }; + const scrollIntoView = vi.fn(); + HTMLElement.prototype.scrollIntoView = scrollIntoView; + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Bass Guitar" })); + + const unavailableButton = screen.getByRole("button", { + name: "No notes are ready yet. Stay on tonight's map." + }); + expect(unavailableButton.getAttribute("aria-disabled")).toBe("true"); + + fireEvent.click(unavailableButton); + + expect(screen.queryByText(/Tonight's Bass Guitar cue is/)).toBeNull(); + expect(document.activeElement?.id).not.toBe("workspace-groove-map"); + expect(scrollIntoView).not.toHaveBeenCalled(); +}); + +it("opens the earliest transcription for a selected role even when its first section has only range metadata", () => { + setNavigatorLanguage("en-US"); + const song = createDemoRehearsalSong(); + const firstSection = song.sections[0]!; + const bassRole = firstSection.roles[0]!; + firstSection.roles[0] = { + ...bassRole, + transcription: undefined + }; + song.sections.push({ + ...firstSection, + id: "later-bass-entry", + label: "chorus", + timeRange: { + start: 40, + end: 60 + }, + roles: [ + { + ...bassRole, + transcription: [ + { + pitch: "A2", + onset: 42, + offset: 42.5, + velocity: 0.8 + } + ] + } + ] + }); + const scrollIntoView = vi.fn(); + HTMLElement.prototype.scrollIntoView = scrollIntoView; + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Bass Guitar" })); + + const notesButton = screen.getByRole("button", { + name: "Open Bass Guitar notes starting at A2 from 0:42 on tonight's groove map" + }); + expect(notesButton.textContent).toBe("See Bass Guitar notes · A2 from 0:42"); + + fireEvent.click(notesButton); + + expect(screen.getByText("A2")).toBeTruthy(); + expect(screen.getByText("1 notes mapped for rehearsal")).toBeTruthy(); + expect(screen.getByText("Tonight's first Bass Guitar notes are A2 from 0:42. Count in on the groove map.")).toBeTruthy(); + expect(document.activeElement?.id).toBe("workspace-groove-map"); + expect(scrollIntoView).toHaveBeenCalledTimes(1); +}); + +it("ignores malformed transcription metadata before choosing tonight's first real note", () => { + setNavigatorLanguage("en-US"); + const song = createDemoRehearsalSong(); + const firstSection = song.sections[0]!; + const bassRole = firstSection.roles[0]!; + firstSection.roles[0] = { + ...bassRole, + range: { + lowestNote: "", + highestNote: "" + }, + transcription: [ + { + pitch: "", + onset: -5, + offset: -4, + velocity: 2 + } + ] + }; + song.sections.push({ + ...firstSection, + id: "later-valid-bass-entry", + label: "chorus", + timeRange: { + start: 40, + end: 60 + }, + roles: [ + { + ...bassRole, + transcription: [ + { + pitch: "A2", + onset: 42, + offset: 42.5, + velocity: 0.8 + } + ] + } + ] + }); + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Bass Guitar" })); + + const notesButton = screen.getByRole("button", { + name: "Open Bass Guitar notes starting at A2 from 0:42 on tonight's groove map" + }); + expect(notesButton.textContent).toBe("See Bass Guitar notes · A2 from 0:42"); +}); diff --git a/apps/desktop/src/features/workspace/Workspace.first-notes-reduced-motion.test.tsx b/apps/desktop/src/features/workspace/Workspace.first-notes-reduced-motion.test.tsx new file mode 100644 index 000000000..e3e547af4 --- /dev/null +++ b/apps/desktop/src/features/workspace/Workspace.first-notes-reduced-motion.test.tsx @@ -0,0 +1,49 @@ +import { fireEvent, render, screen } from "@testing-library/react"; +import { createDemoRehearsalSong } from "@bandscope/shared-types"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { Workspace } from "./Workspace"; + +const originalScrollIntoView = HTMLElement.prototype.scrollIntoView; + +afterEach(() => { + vi.unstubAllGlobals(); + HTMLElement.prototype.scrollIntoView = originalScrollIntoView; +}); + +describe("Workspace first-notes reduced-motion navigation", () => { + it("avoids smooth scrolling when the user requests reduced motion", () => { + const song = createDemoRehearsalSong(); + song.sections[0]!.roles[0] = { + ...song.sections[0]!.roles[0]!, + transcription: [{ pitch: "E2", onset: 0, offset: 0.75, velocity: 0.74 }] + }; + const scrollIntoView = vi.fn(); + HTMLElement.prototype.scrollIntoView = scrollIntoView; + vi.stubGlobal( + "matchMedia", + vi.fn((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() + })) + ); + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Bass Guitar" })); + fireEvent.click( + screen.getByRole("button", { + name: "Open Bass Guitar notes starting at E2 from 0:00 on tonight's groove map" + }) + ); + + expect(scrollIntoView).toHaveBeenCalledWith({ + block: "nearest", + behavior: "auto" + }); + }); +}); diff --git a/apps/desktop/src/features/workspace/Workspace.test.tsx b/apps/desktop/src/features/workspace/Workspace.test.tsx index a3da5ffe6..6f5aefd03 100644 --- a/apps/desktop/src/features/workspace/Workspace.test.tsx +++ b/apps/desktop/src/features/workspace/Workspace.test.tsx @@ -8,6 +8,7 @@ import { generateMetadataHandoffJson } from "../../lib/export"; const originalLanguage = navigator.language; const originalCreateObjectUrl = URL.createObjectURL; const originalRevokeObjectUrl = URL.revokeObjectURL; +const originalScrollIntoView = HTMLElement.prototype.scrollIntoView; function setNavigatorLanguage(language: string) { Object.defineProperty(navigator, "language", { @@ -28,6 +29,7 @@ describe("Workspace", () => { configurable: true, value: originalRevokeObjectUrl }); + HTMLElement.prototype.scrollIntoView = originalScrollIntoView; }); it("updates practice progress immutably through onSongUpdate", () => { @@ -96,9 +98,11 @@ describe("Workspace", () => { render(); fireEvent.click(screen.getByRole("tab", { name: "Bass Guitar" })); - const transcribeButton = screen.getByRole("button", { name: "Transcribe Bass" }) as HTMLButtonElement; - expect(transcribeButton.disabled).toBe(false); - expect(transcribeButton.title).toBe("Transcribe part"); + const notesButton = screen.getByRole("button", { + name: "Open Bass Guitar range C#2 to E3 on tonight's groove map" + }) as HTMLButtonElement; + expect(notesButton.disabled).toBe(false); + expect(notesButton.textContent).toBe("See Bass Guitar range · C#2–E3"); }); it("renders bass transcription in the dark rehearsal cockpit system", () => { @@ -115,7 +119,7 @@ describe("Workspace", () => { render(); fireEvent.click(screen.getByRole("tab", { name: "Bass Guitar" })); - const grooveMap = screen.getByRole("region", { name: /bass transcription groove map/i }); + const grooveMap = screen.getByRole("region", { name: /bass guitar notes on tonight's groove map/i }); expect(grooveMap.className).toContain("bg-slate-950"); expect(screen.getByText("E2")).toBeTruthy(); expect(screen.getByText("G2")).toBeTruthy(); @@ -270,4 +274,59 @@ describe("Workspace", () => { expect(screen.getByText("합주 우선순위")).toBeTruthy(); expect(screen.getByText("역할과 화성")).toBeTruthy(); }); + + it("opens tonight's first notes on the groove map from the selected part", () => { + const song = createDemoRehearsalSong(); + song.sections[0]!.roles[0] = { + ...song.sections[0]!.roles[0]!, + transcription: [ + { pitch: "G2", onset: 0.9, offset: 1.25, velocity: 0.68 }, + { pitch: "E2", onset: 0, offset: 0.75, velocity: 0.74 } + ] + }; + const scrollIntoView = vi.fn(); + HTMLElement.prototype.scrollIntoView = scrollIntoView; + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Bass Guitar" })); + fireEvent.click( + screen.getByRole("button", { + name: "Open Bass Guitar notes starting at E2 from 0:00 on tonight's groove map" + }) + ); + + expect( + screen.getByText("Tonight's first Bass Guitar notes are E2 from 0:00. Count in on the groove map.") + ).toBeTruthy(); + expect(document.activeElement?.id).toBe("workspace-groove-map"); + expect(scrollIntoView).toHaveBeenCalled(); + }); + + it("names the selected part's range when no note map exists yet", () => { + const song = createDemoRehearsalSong(); + const scrollIntoView = vi.fn(); + HTMLElement.prototype.scrollIntoView = scrollIntoView; + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" })); + fireEvent.click( + screen.getByRole("button", { + name: "Open Lead Vocal range G#3 to C#5 on tonight's groove map" + }) + ); + + expect(screen.getByText("Tonight's Lead Vocal range is G#3–C#5. Count in on the groove map.")).toBeTruthy(); + expect(screen.getByText(/No note map yet for Lead Vocal/)).toBeTruthy(); + expect(document.activeElement?.id).toBe("workspace-groove-map"); + }); + + it("localizes the first-notes action", () => { + setNavigatorLanguage("ko-KR"); + const song = createDemoRehearsalSong(); + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Bass Guitar" })); + + expect(screen.getByRole("button", { name: "오늘 그루브 맵에서 Bass Guitar 음역 C#2–E3 열기" })).toBeTruthy(); + }); }); diff --git a/apps/desktop/src/features/workspace/Workspace.tsx b/apps/desktop/src/features/workspace/Workspace.tsx index 71546b524..602313361 100644 --- a/apps/desktop/src/features/workspace/Workspace.tsx +++ b/apps/desktop/src/features/workspace/Workspace.tsx @@ -40,6 +40,7 @@ function downloadTextFile(contents: string, type: string, filename: string): voi } type Translator = ReturnType; +type TranscriptionNote = NonNullable[number]; /** Documented. */ function preventUnavailableAction(event: MouseEvent): void { @@ -57,6 +58,70 @@ function nonBlankText(value: string | undefined): string | undefined { return trimmed ? trimmed : undefined; } +/** Fill rehearsal copy with named placeholders. */ +function fillCopy(template: string, values: Record): string { + return Object.entries(values).reduce( + (text, [key, value]) => text.replaceAll(`{${key}}`, value), + template + ); +} + +/** Accept only finite, forward-moving analyzed notes that are safe to rank and render. */ +function isUsableTranscriptionNote(note: unknown): note is TranscriptionNote { + if (!note || typeof note !== "object") { + return false; + } + + const candidate = note as Partial; + return ( + typeof candidate.pitch === "string" && + nonBlankText(candidate.pitch) !== undefined && + typeof candidate.onset === "number" && + Number.isFinite(candidate.onset) && + candidate.onset >= 0 && + typeof candidate.offset === "number" && + Number.isFinite(candidate.offset) && + candidate.offset > candidate.onset && + typeof candidate.velocity === "number" && + Number.isFinite(candidate.velocity) && + candidate.velocity >= 0 && + candidate.velocity <= 1 + ); +} + +/** Return the earliest analyzed note so tonight starts on the first attack. */ +function firstTranscriptionNote(notes: RehearsalRole["transcription"]): TranscriptionNote | undefined { + if (!notes || notes.length === 0) { + return undefined; + } + + let earliest = notes[0]!; + for (const note of notes) { + if (note.onset < earliest.onset) { + earliest = note; + } + } + return earliest; +} + +/** Use immediate scrolling when the operating system requests reduced motion. */ +function preferredGrooveScrollBehavior(): ScrollBehavior { + return typeof window.matchMedia === "function" && + window.matchMedia("(prefers-reduced-motion: reduce)").matches + ? "auto" + : "smooth"; +} + +/** Scroll and focus the groove map that already holds tonight's notes. */ +function focusGrooveMap(): void { + const node = document.getElementById("workspace-groove-map"); + if (!(node instanceof HTMLElement)) { + return; + } + node.scrollIntoView({ behavior: preferredGrooveScrollBehavior(), block: "nearest" }); + node.focus(); +} + /** Documented. */ function safeProjectBootstrapSummary(value: ProjectBootstrapSummary | null): ProjectBootstrapSummary | null { if (!value) { @@ -120,6 +185,7 @@ const SongStructure = memo(function SongStructure({ sections, t }: { sections: R /** Documented. */ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: WorkspaceProps) { const [activeRole, setActiveRole] = useState(null); + const [openedNotesRoleId, setOpenedNotesRoleId] = useState(null); const t = useMemo(() => createTranslator(detectPreferredLocale()), []); // Extract all unique roles from the song's sections @@ -149,7 +215,28 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp if (!activeRole) return undefined; return roleMap.get(activeRole); }, [activeRole, roleMap]); - const canTranscribeBass = activeRoleDetails?.name.toLowerCase().includes("bass") ?? false; + const activeRoleTranscription = useMemo(() => { + if (!activeRole) return undefined; + const notes: TranscriptionNote[] = []; + for (const section of song.sections) { + for (const role of section.roles) { + if (role.id !== activeRole || !Array.isArray(role.transcription)) continue; + for (const note of role.transcription) { + if (isUsableTranscriptionNote(note)) { + notes.push(note); + } + } + } + } + if (notes.length === 0) return undefined; + notes.sort((left, right) => left.onset - right.onset); + return notes; + }, [activeRole, song.sections]); + const firstNote = firstTranscriptionNote(activeRoleTranscription); + const roleRangeLow = nonBlankText(activeRoleDetails?.range.lowestNote); + const roleRangeHigh = nonBlankText(activeRoleDetails?.range.highestNote); + const roleCue = nonBlankText(activeRoleDetails?.cue.value); + const canOpenTonightNotes = Boolean(firstNote || (roleRangeLow && roleRangeHigh)); /** Handle the practice progress change internally by immutably updating the song state. */ const handlePracticeProgressChange = (newProgress: number) => { @@ -212,6 +299,72 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp const roleTranspositionPlan = nonBlankText(activeRoleDetails?.transpositionPlan) ?? nonBlankText(activeRoleDetails?.simplification); + const roleName = nonBlankText(activeRoleDetails?.name) ?? t("workspaceThisRole"); + const notesActionLabel = firstNote + ? fillCopy(t("workspaceOpenNotesAction"), { + role: roleName, + pitch: firstNote.pitch, + start: formatTimelineTime(firstNote.onset) + }) + : roleRangeLow && roleRangeHigh + ? fillCopy(t("workspaceOpenRangeAction"), { + role: roleName, + low: roleRangeLow, + high: roleRangeHigh + }) + : t("workspaceOpenNotesUnavailable"); + const notesAriaLabel = firstNote + ? fillCopy(t("workspaceOpenNotesAria"), { + role: roleName, + pitch: firstNote.pitch, + start: formatTimelineTime(firstNote.onset) + }) + : roleRangeLow && roleRangeHigh + ? fillCopy(t("workspaceOpenRangeAria"), { + role: roleName, + low: roleRangeLow, + high: roleRangeHigh + }) + : t("workspaceOpenNotesUnavailable"); + const notesStatus = firstNote + ? fillCopy(t("workspaceOpenNotesArmed"), { + role: roleName, + pitch: firstNote.pitch, + start: formatTimelineTime(firstNote.onset) + }) + : roleRangeLow && roleRangeHigh + ? fillCopy(t("workspaceOpenRangeArmed"), { + role: roleName, + low: roleRangeLow, + high: roleRangeHigh + }) + : t("workspaceOpenNotesUnavailable"); + const grooveEmptyMessage = firstNote + ? fillCopy(t("workspaceGrooveMapReady"), { count: String(activeRoleTranscription?.length ?? 0) }) + : roleRangeLow && roleRangeHigh + ? fillCopy(t("workspaceGrooveMapRangeEmpty"), { + role: roleName, + low: roleRangeLow, + high: roleRangeHigh, + cue: roleCue ?? t("workspaceGrooveMapCueFallback") + }) + : fillCopy(t("workspaceGrooveMapEmpty"), { role: roleName }); + const grooveRegionLabel = fillCopy(t("workspaceGrooveMapRegion"), { role: roleName }); + + /** Open tonight's first notes or range on the groove map without inventing transcription. */ + const openTonightNotes = (): void => { + if (!activeRole || !canOpenTonightNotes) { + return; + } + setOpenedNotesRoleId(activeRole); + focusGrooveMap(); + }; + + /** Keep the role board and opened-notes status on the same selected part. */ + const handleRoleChange = (roleId: string | null): void => { + setActiveRole(roleId); + setOpenedNotesRoleId(null); + }; /** Documented. */ const handleExportCueSheet = () => { @@ -332,7 +485,6 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
-
@@ -342,7 +494,7 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
@@ -384,25 +536,28 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp > Solo / mute others - {canTranscribeBass ? ( + {canOpenTonightNotes ? ( ) : ( )}
@@ -476,7 +631,17 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
)} - + {openedNotesRoleId === activeRole ? ( +

+ {notesStatus} +

+ ) : null} + )} @@ -490,4 +655,4 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp ); -} +} \ No newline at end of file diff --git a/apps/desktop/src/locales/en/common.json b/apps/desktop/src/locales/en/common.json index 39f716d50..c19285646 100644 --- a/apps/desktop/src/locales/en/common.json +++ b/apps/desktop/src/locales/en/common.json @@ -50,6 +50,20 @@ "workspaceStemsLabel": "Stems", "workspaceRehearsalPrioritiesLabel": "Rehearsal Priorities", "workspaceRolesHarmonyLabel": "Roles & Harmony", + "workspaceThisRole": "This part", + "workspaceOpenNotesAction": "See {role} notes · {pitch} from {start}", + "workspaceOpenNotesAria": "Open {role} notes starting at {pitch} from {start} on tonight's groove map", + "workspaceOpenNotesArmed": "Tonight's first {role} notes are {pitch} from {start}. Count in on the groove map.", + "workspaceOpenRangeAction": "See {role} range · {low}–{high}", + "workspaceOpenRangeAria": "Open {role} range {low} to {high} on tonight's groove map", + "workspaceOpenRangeArmed": "Tonight's {role} range is {low}–{high}. Count in on the groove map.", + "workspaceOpenCueArmed": "Tonight's {role} cue is {cue}. Count in on the groove map.", + "workspaceOpenNotesUnavailable": "No notes are ready yet. Stay on tonight's map.", + "workspaceGrooveMapRegion": "{role} notes on tonight's groove map", + "workspaceGrooveMapReady": "{count} notes mapped for rehearsal", + "workspaceGrooveMapRangeEmpty": "No note map yet for {role}. Tonight's range is {low}–{high}. {cue}", + "workspaceGrooveMapEmpty": "No notes yet for {role}. Stay on tonight's map.", + "workspaceGrooveMapCueFallback": "Use the range to lock the first entrance.", "sectionRoadmapTitle": "Section Roadmap", "sectionRoadmapScrollHint": "Scroll for more sections →", "sectionGrooveLabel": "Groove", diff --git a/apps/desktop/src/locales/ko/common.json b/apps/desktop/src/locales/ko/common.json index 371884abb..3e55cba31 100644 --- a/apps/desktop/src/locales/ko/common.json +++ b/apps/desktop/src/locales/ko/common.json @@ -50,6 +50,20 @@ "workspaceStemsLabel": "스템", "workspaceRehearsalPrioritiesLabel": "합주 우선순위", "workspaceRolesHarmonyLabel": "역할과 화성", + "workspaceThisRole": "이 파트", + "workspaceOpenNotesAction": "{role} 음 보기 · {start}부터 {pitch}", + "workspaceOpenNotesAria": "오늘 그루브 맵에서 {role} 음을 {start}의 {pitch}부터 열기", + "workspaceOpenNotesArmed": "오늘 첫 {role} 음은 {start}의 {pitch}. 그루브 맵에서 카운트인하세요.", + "workspaceOpenRangeAction": "{role} 음역 보기 · {low}–{high}", + "workspaceOpenRangeAria": "오늘 그루브 맵에서 {role} 음역 {low}–{high} 열기", + "workspaceOpenRangeArmed": "오늘 {role} 음역은 {low}–{high}. 그루브 맵에서 카운트인하세요.", + "workspaceOpenCueArmed": "오늘 {role} 큐는 {cue}. 그루브 맵에서 카운트인하세요.", + "workspaceOpenNotesUnavailable": "아직 준비된 음이 없습니다. 오늘 지도에 머무르세요.", + "workspaceGrooveMapRegion": "오늘 그루브 맵의 {role} 음", + "workspaceGrooveMapReady": "합주용으로 정리된 음 {count}개", + "workspaceGrooveMapRangeEmpty": "{role} 음 지도는 아직 없습니다. 오늘 음역은 {low}–{high}. {cue}", + "workspaceGrooveMapEmpty": "{role} 음이 아직 없습니다. 오늘 지도에 머무르세요.", + "workspaceGrooveMapCueFallback": "첫 입장 음을 음역으로 먼저 잡으세요.", "sectionRoadmapTitle": "구간 흐름", "sectionRoadmapScrollHint": "더 많은 구간은 옆으로 스크롤하세요 →", "sectionGrooveLabel": "그루브", diff --git a/docs/design-system/component-contract.md b/docs/design-system/component-contract.md index 22602c313..0f84f1f23 100644 --- a/docs/design-system/component-contract.md +++ b/docs/design-system/component-contract.md @@ -31,7 +31,7 @@ The authoritative Figma view is `31 Component Contract Catalog`. This file mirro | Role Switcher | https://www.figma.com/design/zthWmqfNKUgJBECvv002Qk/Bandscope-Design-System-v1?node-id=19-337 | `apps/desktop/src/features/workspace/RoleSwitcher.tsx` | Use `roles`, `activeRole`, and `onRoleChange`; `null` means all roles. | | Section Roadmap Card | https://www.figma.com/design/zthWmqfNKUgJBECvv002Qk/Bandscope-Design-System-v1?node-id=19-402 | `apps/desktop/src/features/workspace/SectionRoadmap.tsx` | Use `song`, `activeRole`, and optional `onSongUpdate`; avoid rebuilding its internal card layout. | | Song Structure Timeline | https://www.figma.com/design/zthWmqfNKUgJBECvv002Qk/Bandscope-Design-System-v1?node-id=19-457 | `apps/desktop/src/features/workspace/Workspace.tsx` | Feature-local `SongStructure({ sections, t })` memo component; not exported. | -| Groove Map | https://www.figma.com/design/zthWmqfNKUgJBECvv002Qk/Bandscope-Design-System-v1?node-id=19-526 | `apps/desktop/src/features/workspace/GrooveMap.tsx` | Use `notes?: TranscriptionNote[]` and `isLoading?: boolean`; preserve scrollable region semantics and note labels. | +| Groove Map | https://www.figma.com/design/zthWmqfNKUgJBECvv002Qk/Bandscope-Design-System-v1?node-id=19-526 | `apps/desktop/src/features/workspace/GrooveMap.tsx` | Use `notes?: TranscriptionNote[]`, `isLoading?: boolean`, `regionLabel`, and `emptyMessage`; `id="workspace-groove-map"` is the focus target for tonight's first notes. | | Source Control Stack | https://www.figma.com/design/zthWmqfNKUgJBECvv002Qk/Bandscope-Design-System-v1?node-id=19-655 | `apps/desktop/src/App.tsx` | Feature-local source controls for local audio, YouTube URL import, project actions, and Start Analysis; keep before metrics at 375px. | | Export Action Group | https://www.figma.com/design/zthWmqfNKUgJBECvv002Qk/Bandscope-Design-System-v1?node-id=19-731 | `apps/desktop/src/features/workspace/Workspace.tsx` | Feature-local export buttons call `handleExportCueSheet`, `handleExportChart`, and `handleExportHandoff`. | | Workspace State Matrix | https://www.figma.com/design/zthWmqfNKUgJBECvv002Qk/Bandscope-Design-System-v1?node-id=99-560 | `apps/desktop/src/features/workspace/WorkspaceStates.tsx`, `apps/desktop/src/App.tsx` | Whole-workspace empty, loading, error, and ready state routing; use before changing `renderWorkspaceState()`. | diff --git a/docs/doctoring/reduced-motion-first-notes-navigation.md b/docs/doctoring/reduced-motion-first-notes-navigation.md new file mode 100644 index 000000000..a91ff515e --- /dev/null +++ b/docs/doctoring/reduced-motion-first-notes-navigation.md @@ -0,0 +1,30 @@ +# Reduced-motion first-notes navigation + +## Scope + +The workspace first-notes action scrolls and focuses the existing groove map after a player selects a part. Smooth scrolling is not essential to exposing the selected role's analyzed notes or range, so BandScope honors the operating-system/user-agent reduced-motion preference for this interaction-triggered navigation. + +## Contract + +- The default first-notes path preserves the existing smooth scroll and focus behavior. +- When `window.matchMedia("(prefers-reduced-motion: reduce)").matches` is true, the same action uses immediate (`auto`) scrolling and still focuses the same renderer-owned `workspace-groove-map` target. +- If `matchMedia` is unavailable, BandScope preserves the existing smooth behavior rather than inventing a preference. +- The preference changes animation behavior only; it does not change role selection, note/range evidence, action availability, or filesystem/network/model authority. + +## Verification + +`apps/desktop/src/features/workspace/Workspace.first-notes-reduced-motion.test.tsx` selects the demo Bass Guitar role, opens its real first-note action, and requires `scrollIntoView({ block: "nearest", behavior: "auto" })` when reduced motion is requested. Existing workspace tests continue to cover the default navigation, focus, note/range status, and fail-closed unavailable action. + +## Standards rationale + +WCAG 2.2 Success Criterion 2.3.3, Animation from Interactions (Level AAA), requires non-essential interaction-triggered motion animation to be disableable. W3C Technique SCR40 documents evaluating `prefers-reduced-motion` in JavaScript to prevent such motion. The groove-map scroll animation is not necessary to identify the selected part's notes or range, so respecting that preference is the narrow behavior-preserving implementation. + +This record is implementation rationale and test evidence, not a claim of WCAG certification or overall conformance. + +## References + +World Wide Web Consortium. (2024). *Web Content Accessibility Guidelines (WCAG) 2.2* (W3C Recommendation, December 12, 2024). https://www.w3.org/TR/WCAG22/ + +World Wide Web Consortium, Web Accessibility Initiative. (n.d.). *Understanding Success Criterion 2.3.3: Animation from interactions*. Retrieved August 18, 2026, from https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions/ + +World Wide Web Consortium, Web Accessibility Initiative. (n.d.). *SCR40: Using the CSS prefers-reduced-motion query in JavaScript to prevent motion*. Retrieved August 18, 2026, from https://www.w3.org/WAI/WCAG22/Techniques/client-side-script/SCR40