feat(workspace): name tonight's first vamp plan on the map

.jules/palette.md

@@ -1,3 +1,43 @@
-## 2024-05-19 - Replace HTML disabled with aria-disabled="true" for Accessible Tooltips
-**Learning:** Native HTML `disabled` attributes completely hide elements from screen readers and block all pointer/hover events, preventing tooltips from functioning for disabled elements.
-**Action:** Replace `disabled` with `aria-disabled="true"`, enforce block click handlers via `e.preventDefault()`, and add a title tooltip directly to the element to maintain full tooltip accessibility and keyboard focus support for visually impaired and mouse users.
+## 2024-05-19 - Native disabled and aria-disabled serve different accessibility needs
+**Learning:** Native HTML `disabled` controls are not focusable and leave the tab order, and user activation such as clicks is suppressed. They are not correctly described as completely hidden from assistive technology, and pointer/hover behavior should not be generalized across browsers and event types. `aria-disabled="true"` keeps disabled semantics without changing focusability or suppressing behavior automatically.
+**Action:** Prefer native `disabled` for native form controls when the action should be unavailable. Use `aria-disabled="true"` only when a disabled action intentionally needs to remain discoverable in keyboard navigation, and then suppress activation in application code and provide a real accessible explanation; do not rely on `title` alone for screen-reader guidance.
+
+## 2024-05-18 - Added focus visible styles for keyboard navigation
+**Learning:** Interactive inline buttons (like the chord editor) and scrollable regions with `tabIndex={0}` do not automatically get focus visible styles, meaning keyboard users tabbing through won't know they are focused on them. Unlike central `<Button />` components which bake focus states in, these custom inline interactive elements need explicit focus styling.
+**Action:** Always add explicit focus visible styles (e.g., `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300`) to custom interactive elements and scrollable regions with `tabIndex={0}` for proper keyboard accessibility.
+
+## 2024-05-24 - Visual tooltips for disabled icon-only buttons
+**Learning:** Icon-only buttons with `aria-label` are accessible to screen readers, but sighted users relying on mouse hover don't get context if the `title` attribute is missing, especially when the button is disabled and its purpose is unclear (e.g. "coming soon").
+**Action:** Always add a `title` attribute mirroring the `aria-label` (or providing a specific disabled reason) to icon-only buttons so sighted users also receive explanatory tooltips on hover.
+
+## 2026-06-13 - Added screen reader text for tooltip divs
+**Learning:** When using `title` attributes on non-interactive elements like icon-only `div`s for tooltips, screen readers might not announce them properly because they aren't focusable. The visual tooltip is not enough for accessibility.
+**Action:** Always add a visually hidden `<span className="sr-only">[Tooltip Text]</span>` inside non-interactive elements that rely on a `title` attribute so that screen readers have text content to announce.
+
+## 2026-06-18 - Added keyboard accessibility to scrollable regions
+**Learning:** Horizontally scrollable regions (like the `SectionRoadmap` component) are not accessible to keyboard-only users unless they can receive focus. Keyboard users must be able to focus the container to scroll its content using arrow keys.
+**Action:** For proper keyboard accessibility in custom scrollable regions, always include `tabIndex={0}`, an appropriate `aria-label`, `role="region"`, and explicit focus visible styling (e.g., `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300`).
+
+## 2026-06-19 - Internationalization
+**Learning:** The desktop app uses i18n via json files located in `apps/desktop/src/locales/`
+**Action:** When adding new text strings, make sure to add it to all locale files.
+
+## 2026-06-25 - Native tooltips on disabled elements
+**Learning:** Standard HTML `title` attributes used as tooltips do not render on elements that use Tailwind's `pointer-events-none` class, which is often applied to `disabled:` variants in Base UI and styled components.
+**Action:** Do not rely on native `title` attributes for explaining disabled states on buttons with `pointer-events-none`. Instead, either use a custom tooltip component or ensure focus/interactive styles are preserved if an explanation is strictly required.
+
+## 2024-06-29 - 비활성화된 네이티브 버튼의 설명 제공
+**Learning:** 네이티브 `<button disabled>`는 포커스를 받을 수 없어 키보드 탭 순서에서 제외되고 사용자 활성화가 차단됩니다. 보조기술에는 disabled 상태로 전달될 수 있으며, `title` 툴팁이나 포인터/호버 동작은 브라우저와 이벤트 종류에 따라 달라질 수 있으므로 모든 포인터 이벤트가 차단된다고 일반화하지 않습니다.
+**Action:** 비활성 액션의 이유가 모든 사용자에게 필요하면 `title`만 의존하지 말고 화면에 보이는 설명 또는 `sr-only` 등 실제 접근 가능한 텍스트를 제공하세요. 툴팁을 위해 네이티브 버튼을 wrapper로 감싸야 하더라도 wrapper에 `role="button"`을 부여해 중첩 버튼 의미를 만들지 마세요. disabled 액션을 의도적으로 탭 순서에 남겨야 하는 경우에만 `aria-disabled="true"` 패턴을 사용하고, 애플리케이션 코드에서 활성화를 직접 차단하세요.
+
+## 2024-07-01 - Testing components with focusable disabled button wrappers
+**Learning:** When native disabled buttons are wrapped in a focusable `span` to provide accessible tooltips, tests that previously found and clicked the `button` (by temporarily removing the `disabled` attribute) may fail or become overly complex. It is cleaner and more accurate to query the wrapper element (e.g. via its `title`) and fire events on it, reflecting the actual accessible DOM structure.
+**Action:** When testing UI components that wrap disabled buttons in a focusable span for accessibility (e.g., using a tooltip/title), use `screen.getByTitle(...)` to query the wrapper element for interactions like `fireEvent.click` rather than `screen.getByRole('button')`.
+
+## 2024-05-24 - Avoid nesting native buttons with ARIA role button on wrappers
+**Learning:** Adding `role="button"` to a `span` or `div` wrapper that contains a native `<button>` element inside violates ARIA specifications. Interactive roles (like `button`) must not contain other interactive elements (even if the inner element is disabled or has `aria-hidden`), as this causes invalid/redundant accessibility trees and screen reader confusion.
+**Action:** Always verify wrappers used to implement tooltips for disabled buttons are standard elements (e.g., `<span tabIndex={0} title="...">`) but *do not* assign `role="button"` to the wrapper itself.
+
+## 2026-07-02 - Inline clear buttons preserve focus
+**Learning:** Inline clear buttons often unmount immediately after clearing state, which can drop keyboard focus to the document body.
+**Action:** Move focus back to the owning input before clearing state, and cover the behavior with a DOM focus test.

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 vamp plan with the owning part when an active role is corroborated, the owned `vampPlan` copy, the labeled section, and the time so the next action is obvious. Do not invent that copy from groove, cue, simplification, overlap, range, chord labels, function labels, setup notes, transposition plans, fill plans, tuning plans, dynamics plans, articulation plans, hook plans, solo plans, pad plans, confirmed overrides, harmonic explanations, or confidence notes.
 - 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

@@ -1,10 +1,11 @@
 # ARCHITECTURE.md
 
-Last updated: 2026-03-11
+Last updated: 2026-08-25
 
 ## 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 vamp plan must name the owning part when corroborated, the owned `vampPlan` text, the labeled section, and the time so the next action is obvious. Open moves to the matching rendered map section. Do not invent that copy from groove, cue, simplification, overlap, range, chord labels, function labels, setup notes, transposition plans, fill plans, tuning plans, dynamics plans, articulation plans, hook plans, solo plans, pad plans, confirmed overrides, harmonic explanations, or confidence notes. Distinct from first-pad-plan, first-solo-plan, first-hook-plan, first-fill-plan, first-setup-note, first-transposition-plan, first-tuning-plan, first-dynamics-plan, and first-articulation-plan.
 - 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 vamp plan in the mounted rehearsal workspace so a part can hold the groove until the next entrance; real analyzed songs now receive this guidance only when section-level stem activity shows the same part staying active across the boundary and exactly one other role entering next, while ambiguous or heuristic-only topology remains unavailable. Open moves to the matching rendered map section, and inherited, accessor-backed, or Proxy-substituted runtime metadata remains guidance-only instead of becoming copy, identity, timing, or 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 vamp plan and opens the matching rendered map section. The ready workspace names tonight's first playable range and the next instrument check. Do not invent that copy from groove, cue, simplification, overlap, range, chord labels, function labels, setup notes, transposition plans, fill plans, tuning plans, dynamics plans, articulation plans, hook plans, solo plans, pad plans, confirmed overrides, harmonic explanations, or confidence notes. Distinct from first-pad-plan, first-solo-plan, first-hook-plan, first-fill-plan, first-setup-note, first-transposition-plan, first-tuning-plan, first-dynamics-plan, and first-articulation-plan. `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/FirstVampPlanCallout.identity.test.tsx

@@ -0,0 +1,21 @@
+import { render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { expect, it } from "vitest";
+import { FirstVampPlanCallout } from "./FirstVampPlanCallout";
+
+it("gives co-mounted vamp-plan callouts distinct DOM identities", () => {
+  render(
+    <>
+      <FirstVampPlanCallout song={createDemoRehearsalSong()} />
+      <FirstVampPlanCallout song={createDemoRehearsalSong()} />
+    </>
+  );
+
+  const callouts = screen.getAllByRole("complementary", {
+    name: "Tonight's first vamp plan"
+  });
+  const ids = callouts.map((callout) => callout.id);
+
+  expect(ids.every((id) => id.length > 0)).toBe(true);
+  expect(new Set(ids).size).toBe(callouts.length);
+});

apps/desktop/src/features/workspace/FirstVampPlanCallout.memoization.test.tsx

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