feat(workspace): name the next instrument check on Ranges and Player

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.

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

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 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.

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.
 

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(<PlayerFeature title="Player" />);
+    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(<PlayerFeature title="Player" song={createDemoRehearsalSong()} />);
+
+    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(<PlayerFeature title="Player" song={song} />);
+    expect(
+      screen.getByText("Tonight's first section still needs a named window on the rehearsal map.")
+    ).toBeTruthy();
+  });
+});

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<string, unknown> {
+  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 (
-      <section style={{ padding: "24px" }}>
-        <h2>{title}</h2>
-        <p style={{ color: "#999" }}>No song loaded. Start an analysis to use the player.</p>
+      <section className="space-y-4 rounded-3xl border border-cyan-300/20 bg-slate-950/72 p-5 text-slate-100 shadow-[0_20px_80px_rgba(0,0,0,0.24)]">
+        <h2 className="text-2xl font-black tracking-tight text-white">{title}</h2>
+        <p className="text-sm leading-6 text-slate-300">{t("playerEmptyState")}</p>
       </section>
     );
   }
 
+  const nextAction = namedSection
+    ? fillRangeCopy(t("playerMapLoopNextAction"), { sectionLabel: namedSection.label })
+    : t("playerMissingSection");
+
   return (
-    <section style={{ padding: "24px" }}>
-      <h2>{title}</h2>
-      <div
-        style={{
-          padding: "16px",
-          backgroundColor: "#fafafa",
-          borderRadius: "8px",
-          border: "1px solid #e8e8e8",
-        }}
+    <section className="space-y-4 text-slate-100">
+      <h2 className="text-2xl font-black tracking-tight text-white">{title}</h2>
+      <section
+        className="rounded-2xl border border-amber-300/20 bg-amber-300/[0.07] p-4"
+        data-testid="player-next-map-loop"
+        aria-label={t("playerNextMapLoopTitle")}
       >
-        <div style={{ marginBottom: "12px" }}>
-          <strong>{song.title}</strong>
-          <span style={{ color: "#666", marginLeft: "8px" }}>
-            {song.sections.length} {song.sections.length === 1 ? "section" : "sections"}
-          </span>
-        </div>
-        <div style={{ display: "flex", gap: "8px", flexWrap: "wrap" }}>
-          {song.sections.map((section) => (
-            <span
-              key={section.id}
-              style={{
-                padding: "4px 12px",
-                borderRadius: "16px",
-                backgroundColor: "#fff",
-                border: "1px solid #d9d9d9",
-                fontSize: "0.85em",
-                textTransform: "capitalize",
-              }}
-            >
-              {section.label}
-            </span>
-          ))}
-        </div>
-        <div style={{ marginTop: "16px", color: "#999", fontSize: "0.85em" }}>
-          Audio playback requires the desktop app with a local audio source.
-        </div>
-      </div>
+        <p className="text-xs font-black uppercase tracking-[0.24em] text-amber-200">{t("playerNextMapLoopTitle")}</p>
+        <p className="mt-2 text-sm leading-6 text-slate-100">{nextAction}</p>
+        <p className="mt-2 text-sm leading-6 text-slate-300">{t("playerNoAudioYet")}</p>
+      </section>
+      {namedSection && songTitle ? (
+        <p className="text-sm font-semibold text-slate-200" data-testid="player-song-title">
+          {songTitle}
+        </p>
+      ) : null}
     </section>
   );
 }