diff --git a/AGENTS.md b/AGENTS.md
index b9a67ce17..f5267aee6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
# AGENTS.md
## Project overview
-- BandScope is a local-first desktop app for rehearsal prep: a practical song view with likely harmony by section and by instrument or vocal role, form and groove cues, stems, playable ranges, simplification guidance, transposition or setup cues, part-overlap cues, visible confidence, and rehearsal priorities.
+- BandScope is a local-first desktop app for rehearsal prep: a practical song view with likely harmony by section and by instrument or vocal role, form and groove cues, stems, playable ranges, simplification guidance, transposition or setup cues, part-overlap cues, visible confidence, and rehearsal priorities. Ranges names only playable spans and the next instrument check. The Player window names tonight's first map section to loop and does not claim audio playback.
- Authoritative delivery rules live in `ARCHITECTURE.md`, `docs/plans/`, and the root verification scripts.
- Brand, tone, UX copy, and prioritization rules live in `docs/brand-story.md` and must be applied to PRDs, TRDs, UI copy, onboarding, empty states, and error messages.
- App security rules live in `docs/security/app-security.md` and must be applied to file handling, URL intake, subprocesses, IPC, WebView usage, model loading, updates, logging, cache handling, and export behavior.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index ca0df5ac4..df97e7005 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -82,7 +82,8 @@ Last updated: 2026-03-11
- likely harmony by section and by role
- section roadmap with entries, dropouts, pickups, stops, tags, and handoffs
- groove and timing cues relevant to locking the band together
- - playable ranges and density or overlap warnings, with the ready workspace naming tonight's first span and the next instrument check
+ - playable ranges and density or overlap warnings, with the ready workspace and Ranges board naming tonight's first span and the next instrument check
+ - a Player window that names tonight's first map section to loop and does not claim local-audio playback before the rehearsal-player core exists
- simplification, transposition, capo, tuning, or setup cues where applicable
- role-specific rehearsal priorities and confidence flags
- cue-sheet or chart-style exports that summarize the analysis in rehearsal-friendly form
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b6f7e784..31e29432d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
### Added
+- Name playable spans on the Ranges board and send the player to check those notes on their instrument. The Player window names tonight's first map section to loop and does not claim audio playback.
- 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..a15843cb2 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 ready workspace names tonight's first playable range and the next instrument check. Ranges uses that same playable-span authority. The Player window names tonight's first map section to loop and does not claim audio playback. `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/player/index.test.tsx b/apps/desktop/src/features/player/index.test.tsx
new file mode 100644
index 000000000..eaa52e4d9
--- /dev/null
+++ b/apps/desktop/src/features/player/index.test.tsx
@@ -0,0 +1,120 @@
+import { render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { afterEach, describe, expect, it } from "vitest";
+import { PlayerFeature, firstNamedSection } from "./index";
+
+const originalLanguage = navigator.language;
+
+/** Set the browser language used by locale detection for one test case. */
+function setNavigatorLanguage(language: string) {
+ Object.defineProperty(navigator, "language", {
+ configurable: true,
+ value: language
+ });
+}
+
+describe("firstNamedSection", () => {
+ it("returns the first labeled window with a forward time range", () => {
+ expect(firstNamedSection(createDemoRehearsalSong())).toEqual({ id: "verse-1", label: "verse" });
+ });
+
+ it("skips blank labels and inverted windows", () => {
+ const song = createDemoRehearsalSong();
+ const verse = song.sections[0]!;
+ song.sections = [
+ {
+ ...verse,
+ id: " ",
+ label: "none",
+ timeRange: { start: 30, end: 10 }
+ },
+ {
+ ...verse,
+ id: "chorus-1",
+ label: "chorus",
+ timeRange: { start: 30, end: 50 }
+ }
+ ];
+ expect(firstNamedSection(song)).toEqual({ id: "chorus-1", label: "chorus" });
+ });
+
+ it("rejects Proxy section data instead of trusting descriptor reads", () => {
+ const song = createDemoRehearsalSong();
+ const verse = song.sections[0]!;
+ song.sections = [
+ new Proxy(verse, {
+ get(target, property, receiver) {
+ if (property === "id") return "spoofed-section";
+ if (property === "label") return "chorus";
+ if (property === "timeRange") return { start: 90, end: 100 };
+ return Reflect.get(target, property, receiver);
+ }
+ })
+ ];
+
+ expect(firstNamedSection(song)).toBeNull();
+ });
+
+ it("rejects Proxy descriptor traps before they can forge a loop", () => {
+ const song = createDemoRehearsalSong();
+ const forged = new Proxy(song, {
+ getOwnPropertyDescriptor(target, property) {
+ if (property === "sections") {
+ return {
+ configurable: true,
+ enumerable: true,
+ value: [{ id: "spoofed", label: "spoofed", timeRange: { start: 1, end: 2 } }],
+ writable: true
+ };
+ }
+ return Reflect.getOwnPropertyDescriptor(target, property);
+ }
+ });
+
+ expect(firstNamedSection(forged as RehearsalSong)).toBeNull();
+ });
+
+ it("rejects malformed roots instead of inventing a loop", () => {
+ expect(firstNamedSection(null)).toBeNull();
+ expect(firstNamedSection({ sections: "bad" } as never)).toBeNull();
+ });
+});
+
+describe("PlayerFeature", () => {
+ afterEach(() => {
+ setNavigatorLanguage(originalLanguage);
+ });
+
+ it("names the rehearsal map when no song is loaded", () => {
+ setNavigatorLanguage("en-US");
+ render();
+ expect(
+ screen.getByText(
+ "Open the rehearsal map and choose a song first. This window does not play audio yet."
+ )
+ ).toBeTruthy();
+ });
+
+ it("names tonight's first map section without claiming playback", () => {
+ setNavigatorLanguage("en-US");
+ render();
+
+ const callout = screen.getByTestId("player-next-map-loop");
+ expect(callout).toHaveTextContent("Tonight's first loop");
+ expect(callout).toHaveTextContent(
+ "Tonight's first section is verse. Open that section on the rehearsal map to set tonight's loop."
+ );
+ expect(callout).toHaveTextContent("This window does not play audio yet.");
+ expect(screen.getByTestId("player-song-title")).toHaveTextContent("Late Night Set");
+ });
+
+ it("asks for a named window when no section can be looped", () => {
+ setNavigatorLanguage("en-US");
+ const song = createDemoRehearsalSong();
+ song.sections = [];
+ render();
+ expect(
+ screen.getByText("Tonight's first section still needs a named window on the rehearsal map.")
+ ).toBeTruthy();
+ });
+});
diff --git a/apps/desktop/src/features/player/index.tsx b/apps/desktop/src/features/player/index.tsx
index 37bc12f71..a017ce01b 100644
--- a/apps/desktop/src/features/player/index.tsx
+++ b/apps/desktop/src/features/player/index.tsx
@@ -1,56 +1,100 @@
+import { useMemo } from "react";
import type { RehearsalSong } from "@bandscope/shared-types";
+import { createTranslator, detectPreferredLocale } from "../../i18n";
+import {
+ fillRangeCopy,
+ isSafeRuntimeValue,
+ meaningfulRangeText,
+ ownDataProperty
+} from "../workspace/firstRangeSqueeze";
-/** Documented. */
+/** Tonight's first named section a player should loop from the rehearsal map. */
+export type FirstNamedSection = {
+ id: string;
+ label: string;
+};
+
+/** Return whether an untrusted runtime value is a non-array object record. */
+function isRuntimeObject(value: unknown): value is Record {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Pick the first named section window without treating malformed evidence as a loop. */
+export function firstNamedSection(song: RehearsalSong | null | undefined): FirstNamedSection | null {
+ const runtimeSong: unknown = song;
+ if (!isRuntimeObject(runtimeSong) || !isSafeRuntimeValue(runtimeSong)) {
+ return null;
+ }
+ const sections = ownDataProperty(runtimeSong, "sections");
+ if (!Array.isArray(sections)) {
+ return null;
+ }
+ for (const sectionValue of sections) {
+ if (!isRuntimeObject(sectionValue)) {
+ continue;
+ }
+ const id = meaningfulRangeText(ownDataProperty(sectionValue, "id"));
+ const label = meaningfulRangeText(ownDataProperty(sectionValue, "label"));
+ if (!id || !label) {
+ continue;
+ }
+ const timeRange = ownDataProperty(sectionValue, "timeRange");
+ if (!isRuntimeObject(timeRange)) {
+ continue;
+ }
+ const start = ownDataProperty(timeRange, "start");
+ const end = ownDataProperty(timeRange, "end");
+ if (typeof start !== "number" || typeof end !== "number" || !Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
+ continue;
+ }
+ return { id, label };
+ }
+ return null;
+}
+
+/** Name the next map loop when this window cannot play local audio yet. */
export function PlayerFeature(props: { title: string; song?: RehearsalSong | null }) {
const { title, song } = props;
+ const t = useMemo(() => createTranslator(detectPreferredLocale()), []);
+ const safeSong = useMemo(
+ () => (song && isSafeRuntimeValue(song) ? song : null),
+ [song],
+ );
+ const namedSection = useMemo(() => firstNamedSection(safeSong), [safeSong]);
+ const songTitle = meaningfulRangeText(
+ isRuntimeObject(safeSong) ? ownDataProperty(safeSong, "title") : undefined
+ );
if (!song) {
return (
-
-
{title}
-
No song loaded. Start an analysis to use the player.