From a19c28a36b6eec6f77506cb69d29081de7ec3b33 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 20 Aug 2026 09:13:40 +0000
Subject: [PATCH 01/10] feat(workspace): name tonight's first playable range on
 the map

The ready rehearsal board showed chords, cues, and clashes but never
named the first playable span, so players still guessed whether a part
would fit before the next section.

Security Notes: no new filesystem, URL, subprocess, IPC, or model
authority. Copy is derived from already-validated rehearsal analysis
fields already rendered in the workspace.
---
 AGENTS.md                                     |  2 +-
 ARCHITECTURE.md                               |  2 +-
 CHANGELOG.md                                  |  1 +
 CLAUDE.md                                     |  2 +-
 .../workspace/SectionRoadmap.test.tsx         | 17 ++++
 .../src/features/workspace/SectionRoadmap.tsx | 13 +++
 .../src/features/workspace/Workspace.test.tsx | 56 +++++++++++
 .../src/features/workspace/Workspace.tsx      | 22 +++++
 .../workspace/firstRangeSqueeze.test.ts       | 97 +++++++++++++++++++
 .../features/workspace/firstRangeSqueeze.ts   | 83 ++++++++++++++++
 apps/desktop/src/locales/en/common.json       |  8 +-
 apps/desktop/src/locales/ko/common.json       |  8 +-
 12 files changed, 306 insertions(+), 5 deletions(-)
 create mode 100644 apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
 create mode 100644 apps/desktop/src/features/workspace/firstRangeSqueeze.ts

diff --git a/AGENTS.md b/AGENTS.md
index fca448ce9..b9a67ce17 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -83,7 +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.
-- 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 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.
 
 ## Safety
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 3302a6fc3..ca0df5ac4 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -82,7 +82,7 @@ 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
+  - playable ranges and density or overlap warnings, with the ready workspace naming tonight's first span and the next instrument check
   - 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 eea696893..21de664e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Added
 
+- 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 82c2c704a..b5a34c1fa 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). `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. `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/SectionRoadmap.test.tsx b/apps/desktop/src/features/workspace/SectionRoadmap.test.tsx
index 75a199246..2182a41d1 100644
--- a/apps/desktop/src/features/workspace/SectionRoadmap.test.tsx
+++ b/apps/desktop/src/features/workspace/SectionRoadmap.test.tsx
@@ -31,6 +31,23 @@ describe("SectionRoadmap", () => {
     expect(screen.getAllByText("큐").length).toBeGreaterThan(0);
     expect(screen.getAllByTitle("우선순위: high").length).toBeGreaterThan(0);
     expect(screen.getByText("사용자")).toBeTruthy();
+    expect(screen.getAllByText("음역").length).toBeGreaterThan(0);
+    expect(screen.getByText("C#2 — E3")).toBeTruthy();
+    expect(screen.getAllByText("verse 들어가기 전에 이 음역을 악기로 확인해 보세요.").length).toBeGreaterThan(0);
+  });
+
+  it("omits the range row when both notes are unnamed", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      range: { lowestNote: " ", highestNote: "none" }
+    };
+
+    render(<SectionRoadmap song={song} activeRole="bass-guitar" />);
+
+    expect(screen.queryByText("Range")).toBeNull();
+    expect(screen.queryByText(/Check this span on your instrument/i)).toBeNull();
   });
 
   it("uses localized copy for chord edit prompts and control labels", () => {
diff --git a/apps/desktop/src/features/workspace/SectionRoadmap.tsx b/apps/desktop/src/features/workspace/SectionRoadmap.tsx
index 6f27c2509..29974d024 100644
--- a/apps/desktop/src/features/workspace/SectionRoadmap.tsx
+++ b/apps/desktop/src/features/workspace/SectionRoadmap.tsx
@@ -2,6 +2,7 @@ import type { RehearsalSong, RehearsalRole } from "@bandscope/shared-types";
 import { useId, useMemo } from "react";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { ConfidenceBadge } from "./ConfidenceBadge";
+import { fillRangeCopy, meaningfulRangeText } from "./firstRangeSqueeze";
 import { Card, CardContent, CardHeader } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
 import { Separator } from "@/components/ui/separator";
@@ -182,6 +183,18 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
                           {role.cue.value}
                         </div>
 
+                        {meaningfulRangeText(role.range.lowestNote) && meaningfulRangeText(role.range.highestNote) ? (
+                          <div className="text-sm font-medium leading-snug text-slate-200">
+                            <span className="mb-0.5 block text-[0.65rem] font-bold uppercase tracking-wider text-slate-400">{t("sectionRangeLabel")}</span>
+                            <span>
+                              {meaningfulRangeText(role.range.lowestNote)} — {meaningfulRangeText(role.range.highestNote)}
+                            </span>
+                            <p className="mt-1 text-xs font-medium text-slate-400">
+                              {fillRangeCopy(t("sectionRangeNextAction"), { sectionLabel: section.label })}
+                            </p>
+                          </div>
+                        ) : null}
+
                         {role.setupNote && (
                           <div className="flex items-start gap-2 rounded-md border border-amber-300/20 bg-amber-300/[0.08] p-2 text-xs font-medium text-amber-100">
                             <Lightbulb className="mt-0.5 size-3.5 shrink-0" aria-hidden="true" />
diff --git a/apps/desktop/src/features/workspace/Workspace.test.tsx b/apps/desktop/src/features/workspace/Workspace.test.tsx
index a3da5ffe6..7837bf80e 100644
--- a/apps/desktop/src/features/workspace/Workspace.test.tsx
+++ b/apps/desktop/src/features/workspace/Workspace.test.tsx
@@ -140,6 +140,62 @@ describe("Workspace", () => {
     expect(screen.getByText(/Verse harmony pass/i)).toBeTruthy();
   });
 
+  it("names tonight's first playable range and the next instrument check", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+
+    const callout = screen.getByTestId("first-range-squeeze");
+    expect(callout).toHaveTextContent("Tonight's first range");
+    expect(callout).toHaveTextContent(
+      "Bass Guitar sits C#2–E3 in verse. Hear that clash on your instrument before the verse."
+    );
+  });
+
+  it("asks for an ear check when the selected part has no named span", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role) => ({
+      ...role,
+      range: { lowestNote: "", highestNote: "none" },
+      overlapWarnings: []
+    }));
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-range-squeeze")).toHaveTextContent(
+      "Tonight's first range still needs an ear check. Confirm the high and low notes on the selected part before the first section."
+    );
+  });
+
+  it("limits the range callout to the selected role", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" }));
+
+    expect(screen.getByTestId("first-range-squeeze")).toHaveTextContent(
+      "Lead Vocal sits G#3–C#5 in verse. Hear that clash on your instrument before the verse."
+    );
+  });
+
+  it("asks the player to check a named span when no clash is present", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role) => ({
+      ...role,
+      overlapWarnings: []
+    }));
+
+    render(<Workspace song={song} />);
+
+    expect(screen.getByTestId("first-range-squeeze")).toHaveTextContent(
+      "Bass Guitar sits C#2–E3 in verse. Check that span on your instrument before the verse."
+    );
+  });
+
   it("falls back from blank planning copy and tolerates partial collaboration payloads", () => {
     setNavigatorLanguage("en-US");
     const song = createDemoRehearsalSong();
diff --git a/apps/desktop/src/features/workspace/Workspace.tsx b/apps/desktop/src/features/workspace/Workspace.tsx
index 71546b524..d44e20777 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 { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
@@ -150,6 +151,18 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
     return roleMap.get(activeRole);
   }, [activeRole, roleMap]);
   const canTranscribeBass = activeRoleDetails?.name.toLowerCase().includes("bass") ?? false;
+  const firstRange = useMemo(() => firstRangeSqueeze(song, activeRole), [activeRole, song]);
+  const firstRangeCopy = firstRange
+    ? fillRangeCopy(
+        t(firstRange.overlapWarning ? "workspaceFirstRangeClash" : "workspaceFirstRangeCheck"),
+        {
+          roleName: firstRange.roleName,
+          lowestNote: firstRange.lowestNote,
+          highestNote: firstRange.highestNote,
+          sectionLabel: firstRange.sectionLabel
+        }
+      )
+    : t("workspaceFirstRangeMissing");
 
   /** Handle the practice progress change internally by immutably updating the song state. */
   const handlePracticeProgressChange = (newProgress: number) => {
@@ -288,6 +301,15 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
         </CardHeader>
 
         <CardContent className="space-y-6 bg-[linear-gradient(180deg,rgba(15,23,42,0.72),rgba(2,6,23,0.86))] p-5 md:p-7">
+          <section
+            className="rounded-2xl border border-fuchsia-300/20 bg-fuchsia-300/[0.07] p-4"
+            data-testid="first-range-squeeze"
+            aria-label={t("workspaceFirstRangeTitle")}
+          >
+            <p className="text-xs font-black uppercase tracking-[0.24em] text-fuchsia-200">{t("workspaceFirstRangeTitle")}</p>
+            <p className="mt-2 text-sm leading-6 text-slate-100">{firstRangeCopy}</p>
+          </section>
+
           <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
             <section className="rounded-2xl border border-cyan-300/20 bg-cyan-300/[0.06] p-4 md:col-span-2">
               <p className="text-xs font-black uppercase tracking-[0.24em] text-cyan-300">{t("workspaceSongTimelineLabel")}</p>
diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
new file mode 100644
index 000000000..7c4f4aeb5
--- /dev/null
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
@@ -0,0 +1,97 @@
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import { fillRangeCopy, firstRangeSqueeze, meaningfulRangeText } from "./firstRangeSqueeze";
+
+function blankRoleRange(song: RehearsalSong): RehearsalSong {
+  return {
+    ...song,
+    sections: song.sections.map((section) => ({
+      ...section,
+      roles: section.roles.map((role) => ({
+        ...role,
+        range: { lowestNote: "", highestNote: "" },
+        overlapWarnings: []
+      }))
+    }))
+  };
+}
+
+describe("meaningfulRangeText", () => {
+  it("rejects blank, whitespace, and none sentinels", () => {
+    expect(meaningfulRangeText(undefined)).toBeUndefined();
+    expect(meaningfulRangeText("")).toBeUndefined();
+    expect(meaningfulRangeText("   ")).toBeUndefined();
+    expect(meaningfulRangeText("none")).toBeUndefined();
+    expect(meaningfulRangeText("NONE")).toBeUndefined();
+    expect(meaningfulRangeText(" C#2 ")).toBe("C#2");
+  });
+});
+
+describe("firstRangeSqueeze", () => {
+  it("prefers the first named span that also carries a clash warning", () => {
+    const squeeze = firstRangeSqueeze(createDemoRehearsalSong());
+
+    expect(squeeze).toEqual({
+      sectionLabel: "verse",
+      roleName: "Bass Guitar",
+      lowestNote: "C#2",
+      highestNote: "E3",
+      overlapWarning: "Density warning: competing with Keyboard Left Hand in low register."
+    });
+  });
+
+  it("falls back to the first named span when clashes are only none sentinels", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role, index) => ({
+      ...role,
+      overlapWarnings: index === 0 ? [" none ", ""] : []
+    }));
+
+    expect(firstRangeSqueeze(song)).toEqual({
+      sectionLabel: "verse",
+      roleName: "Bass Guitar",
+      lowestNote: "C#2",
+      highestNote: "E3",
+      overlapWarning: undefined
+    });
+  });
+
+  it("skips roles whose span is blank or none until a named span exists", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      range: { lowestNote: "none", highestNote: "E3" },
+      overlapWarnings: ["Density warning: competing with Keyboard Left Hand in low register."]
+    };
+
+    expect(firstRangeSqueeze(song)?.roleName).toBe("Keyboard 1 Right Hand");
+  });
+
+  it("limits the squeeze to the selected role", () => {
+    const squeeze = firstRangeSqueeze(createDemoRehearsalSong(), "lead-vocal");
+
+    expect(squeeze).toEqual({
+      sectionLabel: "verse",
+      roleName: "Lead Vocal",
+      lowestNote: "G#3",
+      highestNote: "C#5",
+      overlapWarning: "Melodic overlap: competing with Keyboard 1 Right Hand."
+    });
+  });
+
+  it("returns null when no selected role has both notes", () => {
+    expect(firstRangeSqueeze(blankRoleRange(createDemoRehearsalSong()))).toBeNull();
+    expect(firstRangeSqueeze(createDemoRehearsalSong(), "missing-role")).toBeNull();
+  });
+});
+
+describe("fillRangeCopy", () => {
+  it("replaces every token occurrence", () => {
+    expect(
+      fillRangeCopy("{roleName} in {sectionLabel} before the {sectionLabel}.", {
+        roleName: "Bass Guitar",
+        sectionLabel: "verse"
+      })
+    ).toBe("Bass Guitar in verse before the verse.");
+  });
+});
diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
new file mode 100644
index 000000000..981c89641
--- /dev/null
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
@@ -0,0 +1,83 @@
+import type { RehearsalSong } from "@bandscope/shared-types";
+
+/** Tonight's first named playable span on the rehearsal map. */
+export type FirstRangeSqueeze = {
+  sectionLabel: string;
+  roleName: string;
+  lowestNote: string;
+  highestNote: string;
+  overlapWarning?: string;
+};
+
+/** Return trimmed copy that is not a blank or `none` sentinel. */
+export function meaningfulRangeText(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed || /^none$/i.test(trimmed)) {
+    return undefined;
+  }
+  return trimmed;
+}
+
+/**
+ * Pick the first playable range a player should check before the next section.
+ *
+ * Prefers a named span that also carries a clash warning so the board names
+ * the squeeze that will waste rehearsal time. Falls back to the first named
+ * span when no clash is present. Roles without both notes stay unnamed.
+ */
+export function firstRangeSqueeze(
+  song: RehearsalSong,
+  activeRole: string | null = null
+): FirstRangeSqueeze | null {
+  let fallback: FirstRangeSqueeze | null = null;
+
+  for (const section of song.sections) {
+    for (const role of section.roles) {
+      if (activeRole && role.id !== activeRole) {
+        continue;
+      }
+
+      const lowestNote = meaningfulRangeText(role.range.lowestNote);
+      const highestNote = meaningfulRangeText(role.range.highestNote);
+      if (!lowestNote || !highestNote) {
+        continue;
+      }
+
+      let overlapWarning: string | undefined;
+      for (const warning of role.overlapWarnings) {
+        const meaningfulWarning = meaningfulRangeText(warning);
+        if (meaningfulWarning) {
+          overlapWarning = meaningfulWarning;
+          break;
+        }
+      }
+
+      const candidate: FirstRangeSqueeze = {
+        sectionLabel: section.label,
+        roleName: role.name,
+        lowestNote,
+        highestNote,
+        overlapWarning
+      };
+
+      if (overlapWarning) {
+        return candidate;
+      }
+
+      if (!fallback) {
+        fallback = candidate;
+      }
+    }
+  }
+
+  return fallback;
+}
+
+/** Fill `{token}` placeholders in rehearsal copy without leaving unmatched holes. */
+export function fillRangeCopy(template: string, values: Record<string, string>): string {
+  let filled = template;
+  for (const [token, value] of Object.entries(values)) {
+    filled = filled.replaceAll(`{${token}}`, value);
+  }
+  return filled;
+}
diff --git a/apps/desktop/src/locales/en/common.json b/apps/desktop/src/locales/en/common.json
index 39f716d50..d803a765e 100644
--- a/apps/desktop/src/locales/en/common.json
+++ b/apps/desktop/src/locales/en/common.json
@@ -148,5 +148,11 @@
   "practiceProgressRegionLabel": "Practice Progress",
   "practiceProgressLabel": "Practice Progress",
   "decreasePracticeProgressLabel": "Decrease progress",
-  "increasePracticeProgressLabel": "Increase progress"
+  "increasePracticeProgressLabel": "Increase progress",
+  "workspaceFirstRangeTitle": "Tonight's first range",
+  "workspaceFirstRangeCheck": "{roleName} sits {lowestNote}–{highestNote} in {sectionLabel}. Check that span on your instrument before the {sectionLabel}.",
+  "workspaceFirstRangeClash": "{roleName} sits {lowestNote}–{highestNote} in {sectionLabel}. Hear that clash on your instrument before the {sectionLabel}.",
+  "workspaceFirstRangeMissing": "Tonight's first range still needs an ear check. Confirm the high and low notes on the selected part before the first section.",
+  "sectionRangeLabel": "Range",
+  "sectionRangeNextAction": "Check this span on your instrument before {sectionLabel}."
 }
diff --git a/apps/desktop/src/locales/ko/common.json b/apps/desktop/src/locales/ko/common.json
index 371884abb..0f6c6c66d 100644
--- a/apps/desktop/src/locales/ko/common.json
+++ b/apps/desktop/src/locales/ko/common.json
@@ -148,5 +148,11 @@
   "practiceProgressRegionLabel": "연습 진척도",
   "practiceProgressLabel": "연습 진척도",
   "decreasePracticeProgressLabel": "진척도 감소",
-  "increasePracticeProgressLabel": "진척도 증가"
+  "increasePracticeProgressLabel": "진척도 증가",
+  "workspaceFirstRangeTitle": "오늘 먼저 볼 음역",
+  "workspaceFirstRangeCheck": "{sectionLabel}의 {roleName}은 {lowestNote}–{highestNote}입니다. {sectionLabel} 들어가기 전에 그 음역을 악기로 확인해 보세요.",
+  "workspaceFirstRangeClash": "{sectionLabel}의 {roleName}은 {lowestNote}–{highestNote}이고 다른 파트와 겹칩니다. {sectionLabel} 들어가기 전에 그 충돌을 악기로 들어 보세요.",
+  "workspaceFirstRangeMissing": "오늘 먼저 볼 음역은 아직 귀로 확인이 필요합니다. 선택한 파트의 최저·최고음을 첫 구간 전에 확인해 보세요.",
+  "sectionRangeLabel": "음역",
+  "sectionRangeNextAction": "{sectionLabel} 들어가기 전에 이 음역을 악기로 확인해 보세요."
 }

From ee9e99065c666d445849661ac94bf49d505fd8bc Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 20 Aug 2026 02:24:05 -0700
Subject: [PATCH 02/10] test(workspace): reproduce literal range copy
 interpolation

---
 .../src/features/workspace/firstRangeSqueeze.test.ts     | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
index 7c4f4aeb5..98c2c0df8 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
@@ -94,4 +94,13 @@ describe("fillRangeCopy", () => {
       })
     ).toBe("Bass Guitar in verse before the verse.");
   });
+
+  it("keeps replacement tokens and placeholder-shaped rehearsal values literal", () => {
+    expect(
+      fillRangeCopy("{roleName} in {sectionLabel}.", {
+        roleName: "Bass $& {sectionLabel}",
+        sectionLabel: "verse"
+      })
+    ).toBe("Bass $& {sectionLabel} in verse.");
+  });
 });

From 3de95837e816c516ff12d85a5cee1c43fbe505af Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 20 Aug 2026 02:24:36 -0700
Subject: [PATCH 03/10] fix(workspace): keep range copy values literal

---
 .../src/features/workspace/firstRangeSqueeze.ts        | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
index 981c89641..a9eff00b4 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
@@ -73,11 +73,9 @@ export function firstRangeSqueeze(
   return fallback;
 }
 
-/** Fill `{token}` placeholders in rehearsal copy without leaving unmatched holes. */
+/** Fill trusted `{token}` placeholders once while keeping rehearsal values literal. */
 export function fillRangeCopy(template: string, values: Record<string, string>): string {
-  let filled = template;
-  for (const [token, value] of Object.entries(values)) {
-    filled = filled.replaceAll(`{${token}}`, value);
-  }
-  return filled;
+  return template.replace(/\{([A-Za-z][A-Za-z0-9]*)\}/g, (placeholder, token: string) => {
+    return values[token] ?? placeholder;
+  });
 }

From b42cc90f3ed2f4a95b6b0224efe07b0079d56ae9 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 20 Aug 2026 02:39:03 -0700
Subject: [PATCH 04/10] test(workspace): reject invalid playable ranges

---
 .../features/workspace/firstRangeSqueeze.test.ts    | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
index 98c2c0df8..3aa420df2 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
@@ -67,6 +67,19 @@ describe("firstRangeSqueeze", () => {
     expect(firstRangeSqueeze(song)?.roleName).toBe("Keyboard 1 Right Hand");
   });
 
+  it("rejects malformed and inverted spans instead of calling them playable", () => {
+    for (const range of [
+      { lowestNote: "not-a-note", highestNote: "E3" },
+      { lowestNote: "E3", highestNote: "C#2" }
+    ]) {
+      const song = createDemoRehearsalSong();
+      const selectedRole = song.sections[0]!.roles[0]!;
+      selectedRole.range = range;
+
+      expect(firstRangeSqueeze(song, selectedRole.id)).toBeNull();
+    }
+  });
+
   it("limits the squeeze to the selected role", () => {
     const squeeze = firstRangeSqueeze(createDemoRehearsalSong(), "lead-vocal");
 

From 28f4f7bcb246df130f36672bd76d623d37b51ba6 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 20 Aug 2026 02:39:41 -0700
Subject: [PATCH 05/10] fix(workspace): validate playable range evidence

---
 .../features/workspace/firstRangeSqueeze.ts   | 62 +++++++++++++++++--
 1 file changed, 56 insertions(+), 6 deletions(-)

diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
index a9eff00b4..f2ef8d500 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
@@ -9,6 +9,26 @@ export type FirstRangeSqueeze = {
   overlapWarning?: string;
 };
 
+const NATURAL_PITCH_CLASS = {
+  C: 0,
+  D: 2,
+  E: 4,
+  F: 5,
+  G: 7,
+  A: 9,
+  B: 11
+} as const;
+
+const ACCIDENTAL_OFFSET: Record<string, number> = {
+  "": 0,
+  "#": 1,
+  "♯": 1,
+  b: -1,
+  "♭": -1
+};
+
+const NOTE_PATTERN = /^([A-Ga-g])([#b♯♭]?)(-?\d{1,2})$/u;
+
 /** Return trimmed copy that is not a blank or `none` sentinel. */
 export function meaningfulRangeText(value: string | undefined): string | undefined {
   const trimmed = value?.trim();
@@ -18,12 +38,44 @@ export function meaningfulRangeText(value: string | undefined): string | undefin
   return trimmed;
 }
 
+/** Convert a bounded scientific-pitch label into chromatic ordering. */
+function notePitchValue(note: string): number | null {
+  const match = NOTE_PATTERN.exec(note);
+  if (!match) {
+    return null;
+  }
+  const letter = match[1].toUpperCase() as keyof typeof NATURAL_PITCH_CLASS;
+  const octave = Number(match[3]);
+  return (octave + 1) * 12 + NATURAL_PITCH_CLASS[letter] + ACCIDENTAL_OFFSET[match[2]];
+}
+
+/** Return a complete, ordered scientific-pitch range or fail closed. */
+function playableRange(
+  lowestNoteValue: string | undefined,
+  highestNoteValue: string | undefined
+): Pick<FirstRangeSqueeze, "lowestNote" | "highestNote"> | null {
+  const lowestNote = meaningfulRangeText(lowestNoteValue);
+  const highestNote = meaningfulRangeText(highestNoteValue);
+  if (!lowestNote || !highestNote) {
+    return null;
+  }
+
+  const lowestPitch = notePitchValue(lowestNote);
+  const highestPitch = notePitchValue(highestNote);
+  if (lowestPitch === null || highestPitch === null || lowestPitch > highestPitch) {
+    return null;
+  }
+
+  return { lowestNote, highestNote };
+}
+
 /**
  * Pick the first playable range a player should check before the next section.
  *
  * Prefers a named span that also carries a clash warning so the board names
  * the squeeze that will waste rehearsal time. Falls back to the first named
- * span when no clash is present. Roles without both notes stay unnamed.
+ * span when no clash is present. Malformed, incomplete, or inverted ranges
+ * fail closed instead of becoming buyer-visible playable-range evidence.
  */
 export function firstRangeSqueeze(
   song: RehearsalSong,
@@ -37,9 +89,8 @@ export function firstRangeSqueeze(
         continue;
       }
 
-      const lowestNote = meaningfulRangeText(role.range.lowestNote);
-      const highestNote = meaningfulRangeText(role.range.highestNote);
-      if (!lowestNote || !highestNote) {
+      const range = playableRange(role.range.lowestNote, role.range.highestNote);
+      if (!range) {
         continue;
       }
 
@@ -55,8 +106,7 @@ export function firstRangeSqueeze(
       const candidate: FirstRangeSqueeze = {
         sectionLabel: section.label,
         roleName: role.name,
-        lowestNote,
-        highestNote,
+        ...range,
         overlapWarning
       };
 

From 2143fbf71ffc22d88ebc5545be4980b2f39331af Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 20 Aug 2026 02:52:57 -0700
Subject: [PATCH 06/10] test(workspace): contain malformed range evidence

---
 .../workspace/firstRangeSqueeze.test.ts       | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
index 3aa420df2..33c30bc45 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
@@ -80,6 +80,29 @@ describe("firstRangeSqueeze", () => {
     }
   });
 
+  it("fails closed on malformed runtime roots and collections", () => {
+    for (const malformed of [null, {}, { sections: null }, { sections: [null] }]) {
+      expect(firstRangeSqueeze(malformed as unknown as RehearsalSong)).toBeNull();
+    }
+
+    const song = createDemoRehearsalSong();
+    const validRole = song.sections[0]!.roles[0]!;
+    const malformedSection = {
+      ...song.sections[0],
+      roles: [null, { ...validRole, range: null }, validRole]
+    };
+
+    expect(
+      firstRangeSqueeze({ ...song, sections: [malformedSection] } as unknown as RehearsalSong)
+    ).toEqual({
+      sectionLabel: "verse",
+      roleName: "Bass Guitar",
+      lowestNote: "C#2",
+      highestNote: "E3",
+      overlapWarning: "Density warning: competing with Keyboard Left Hand in low register."
+    });
+  });
+
   it("limits the squeeze to the selected role", () => {
     const squeeze = firstRangeSqueeze(createDemoRehearsalSong(), "lead-vocal");
 

From bd0915dae91c5ab0d54758d0b7475445bee94009 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 20 Aug 2026 02:53:33 -0700
Subject: [PATCH 07/10] fix(workspace): contain malformed range evidence

---
 .../features/workspace/firstRangeSqueeze.ts   | 65 ++++++++++++++-----
 1 file changed, 48 insertions(+), 17 deletions(-)

diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
index f2ef8d500..80a8f3df2 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
@@ -29,9 +29,16 @@ const ACCIDENTAL_OFFSET: Record<string, number> = {
 
 const NOTE_PATTERN = /^([A-Ga-g])([#b♯♭]?)(-?\d{1,2})$/u;
 
+function isRuntimeObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /** Return trimmed copy that is not a blank or `none` sentinel. */
-export function meaningfulRangeText(value: string | undefined): string | undefined {
-  const trimmed = value?.trim();
+export function meaningfulRangeText(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
   if (!trimmed || /^none$/i.test(trimmed)) {
     return undefined;
   }
@@ -51,8 +58,8 @@ function notePitchValue(note: string): number | null {
 
 /** Return a complete, ordered scientific-pitch range or fail closed. */
 function playableRange(
-  lowestNoteValue: string | undefined,
-  highestNoteValue: string | undefined
+  lowestNoteValue: unknown,
+  highestNoteValue: unknown
 ): Pick<FirstRangeSqueeze, "lowestNote" | "highestNote"> | null {
   const lowestNote = meaningfulRangeText(lowestNoteValue);
   const highestNote = meaningfulRangeText(highestNoteValue);
@@ -74,38 +81,62 @@ function playableRange(
  *
  * Prefers a named span that also carries a clash warning so the board names
  * the squeeze that will waste rehearsal time. Falls back to the first named
- * span when no clash is present. Malformed, incomplete, or inverted ranges
- * fail closed instead of becoming buyer-visible playable-range evidence.
+ * span when no clash is present. Runtime roots and collection members are
+ * treated as untrusted; malformed evidence is isolated instead of crashing
+ * the buyer-visible workspace or becoming playable-range authority.
  */
 export function firstRangeSqueeze(
   song: RehearsalSong,
   activeRole: string | null = null
 ): FirstRangeSqueeze | null {
+  const runtimeSong: unknown = song;
+  if (!isRuntimeObject(runtimeSong) || !Array.isArray(runtimeSong.sections)) {
+    return null;
+  }
+
   let fallback: FirstRangeSqueeze | null = null;
 
-  for (const section of song.sections) {
-    for (const role of section.roles) {
-      if (activeRole && role.id !== activeRole) {
+  for (const sectionValue of runtimeSong.sections) {
+    if (!isRuntimeObject(sectionValue) || !Array.isArray(sectionValue.roles)) {
+      continue;
+    }
+    const sectionLabel = meaningfulRangeText(sectionValue.label);
+    if (!sectionLabel) {
+      continue;
+    }
+
+    for (const roleValue of sectionValue.roles) {
+      if (!isRuntimeObject(roleValue)) {
+        continue;
+      }
+      const roleId = meaningfulRangeText(roleValue.id);
+      const roleName = meaningfulRangeText(roleValue.name);
+      if (!roleId || !roleName || (activeRole && roleId !== activeRole)) {
+        continue;
+      }
+      if (!isRuntimeObject(roleValue.range)) {
         continue;
       }
 
-      const range = playableRange(role.range.lowestNote, role.range.highestNote);
+      const range = playableRange(roleValue.range.lowestNote, roleValue.range.highestNote);
       if (!range) {
         continue;
       }
 
       let overlapWarning: string | undefined;
-      for (const warning of role.overlapWarnings) {
-        const meaningfulWarning = meaningfulRangeText(warning);
-        if (meaningfulWarning) {
-          overlapWarning = meaningfulWarning;
-          break;
+      if (Array.isArray(roleValue.overlapWarnings)) {
+        for (const warning of roleValue.overlapWarnings) {
+          const meaningfulWarning = meaningfulRangeText(warning);
+          if (meaningfulWarning) {
+            overlapWarning = meaningfulWarning;
+            break;
+          }
         }
       }
 
       const candidate: FirstRangeSqueeze = {
-        sectionLabel: section.label,
-        roleName: role.name,
+        sectionLabel,
+        roleName,
         ...range,
         overlapWarning
       };

From 4c4c045cfe1eabf585aadb01bf799ed68d654e4f Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 20 Aug 2026 05:39:28 -0700
Subject: [PATCH 08/10] docs(workspace): document runtime range guard

---
 apps/desktop/src/features/workspace/firstRangeSqueeze.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
index 80a8f3df2..634fb97c9 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
@@ -29,6 +29,7 @@ const ACCIDENTAL_OFFSET: Record<string, number> = {
 
 const NOTE_PATTERN = /^([A-Ga-g])([#b♯♭]?)(-?\d{1,2})$/u;
 
+/** Return whether an untrusted runtime value is a plain object record. */
 function isRuntimeObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

From 7b620e270ae77a90473ad0f5dc703c1ca3e1ef64 Mon Sep 17 00:00:00 2001
From: seonghobae <me@seonghobae.me>
Date: Wed, 26 Aug 2026 12:54:39 +0900
Subject: [PATCH 09/10] fix(review): gate section roadmap range row on
 validated pitch span

The section card range row gated only on meaningfulRangeText, so an
inverted or malformed span (e.g. E3-C#2) rendered as valid playable-range
guidance while firstRangeSqueeze failed closed on the same data. Export
the shared playableRange helper and gate the roadmap row on it so both
surfaces reject non-pitch or low>high evidence identically.
---
 .../workspace/SectionRoadmap.test.tsx         | 29 +++++++++++++++++++
 .../src/features/workspace/SectionRoadmap.tsx | 13 +++++----
 .../workspace/firstRangeSqueeze.test.ts       | 21 +++++++++++++-
 .../features/workspace/firstRangeSqueeze.ts   | 11 +++++--
 4 files changed, 66 insertions(+), 8 deletions(-)

diff --git a/apps/desktop/src/features/workspace/SectionRoadmap.test.tsx b/apps/desktop/src/features/workspace/SectionRoadmap.test.tsx
index 2182a41d1..5b32019d2 100644
--- a/apps/desktop/src/features/workspace/SectionRoadmap.test.tsx
+++ b/apps/desktop/src/features/workspace/SectionRoadmap.test.tsx
@@ -50,6 +50,35 @@ describe("SectionRoadmap", () => {
     expect(screen.queryByText(/Check this span on your instrument/i)).toBeNull();
   });
 
+  it("omits the range row when the span is inverted instead of presenting it as valid", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      range: { lowestNote: "E3", highestNote: "C#2" }
+    };
+
+    render(<SectionRoadmap song={song} activeRole="bass-guitar" />);
+
+    expect(screen.queryByText("Range")).toBeNull();
+    expect(screen.queryByText(/Check this span on your instrument/i)).toBeNull();
+    expect(screen.queryByText(/E3 — C#2/)).toBeNull();
+  });
+
+  it("omits the range row when a note is not a scientific-pitch label", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      range: { lowestNote: "low-ish", highestNote: "E3" }
+    };
+
+    render(<SectionRoadmap song={song} activeRole="bass-guitar" />);
+
+    expect(screen.queryByText("Range")).toBeNull();
+    expect(screen.queryByText(/Check this span on your instrument/i)).toBeNull();
+  });
+
   it("uses localized copy for chord edit prompts and control labels", () => {
     setNavigatorLanguage("ko-KR");
     const song = createDemoRehearsalSong();
diff --git a/apps/desktop/src/features/workspace/SectionRoadmap.tsx b/apps/desktop/src/features/workspace/SectionRoadmap.tsx
index 29974d024..834d1e8f0 100644
--- a/apps/desktop/src/features/workspace/SectionRoadmap.tsx
+++ b/apps/desktop/src/features/workspace/SectionRoadmap.tsx
@@ -2,7 +2,7 @@ import type { RehearsalSong, RehearsalRole } from "@bandscope/shared-types";
 import { useId, useMemo } from "react";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { ConfidenceBadge } from "./ConfidenceBadge";
-import { fillRangeCopy, meaningfulRangeText } from "./firstRangeSqueeze";
+import { fillRangeCopy, playableRange } from "./firstRangeSqueeze";
 import { Card, CardContent, CardHeader } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
 import { Separator } from "@/components/ui/separator";
@@ -125,7 +125,9 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
             <CardContent className="p-4 space-y-4">
               {section.roles
                 .filter(role => !activeRole || role.id === activeRole)
-                .map(role => (
+                .map(role => {
+                  const validatedRange = playableRange(role.range.lowestNote, role.range.highestNote);
+                  return (
                   <div
                     key={role.id}
                     className={`rounded-xl border-l-4 p-4 transition-all hover:translate-x-1 ${getPriorityColor(role.rehearsalPriority)}`}
@@ -183,11 +185,11 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
                           {role.cue.value}
                         </div>
 
-                        {meaningfulRangeText(role.range.lowestNote) && meaningfulRangeText(role.range.highestNote) ? (
+                        {validatedRange ? (
                           <div className="text-sm font-medium leading-snug text-slate-200">
                             <span className="mb-0.5 block text-[0.65rem] font-bold uppercase tracking-wider text-slate-400">{t("sectionRangeLabel")}</span>
                             <span>
-                              {meaningfulRangeText(role.range.lowestNote)} — {meaningfulRangeText(role.range.highestNote)}
+                              {validatedRange.lowestNote} — {validatedRange.highestNote}
                             </span>
                             <p className="mt-1 text-xs font-medium text-slate-400">
                               {fillRangeCopy(t("sectionRangeNextAction"), { sectionLabel: section.label })}
@@ -222,7 +224,8 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
                       </div>
                     </div>
                   </div>
-              ))}
+                  );
+                })}
             </CardContent>
           </Card>
         ))}
diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
index 33c30bc45..7997d80db 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
@@ -1,6 +1,6 @@
 import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
 import { describe, expect, it } from "vitest";
-import { fillRangeCopy, firstRangeSqueeze, meaningfulRangeText } from "./firstRangeSqueeze";
+import { fillRangeCopy, firstRangeSqueeze, meaningfulRangeText, playableRange } from "./firstRangeSqueeze";
 
 function blankRoleRange(song: RehearsalSong): RehearsalSong {
   return {
@@ -27,6 +27,25 @@ describe("meaningfulRangeText", () => {
   });
 });
 
+describe("playableRange", () => {
+  it("returns the trimmed ordered span for a valid scientific-pitch range", () => {
+    expect(playableRange(" C#2 ", "E3")).toEqual({ lowestNote: "C#2", highestNote: "E3" });
+    expect(playableRange("E3", "E3")).toEqual({ lowestNote: "E3", highestNote: "E3" });
+  });
+
+  it("fails closed on blank, none, non-pitch, or inverted spans", () => {
+    for (const [lowestNote, highestNote] of [
+      ["", ""],
+      ["none", "E3"],
+      ["not-a-note", "E3"],
+      ["E3", "not-a-note"],
+      ["E3", "C#2"]
+    ]) {
+      expect(playableRange(lowestNote, highestNote)).toBeNull();
+    }
+  });
+});
+
 describe("firstRangeSqueeze", () => {
   it("prefers the first named span that also carries a clash warning", () => {
     const squeeze = firstRangeSqueeze(createDemoRehearsalSong());
diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
index 634fb97c9..5cd1d42ba 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
@@ -57,8 +57,15 @@ function notePitchValue(note: string): number | null {
   return (octave + 1) * 12 + NATURAL_PITCH_CLASS[letter] + ACCIDENTAL_OFFSET[match[2]];
 }
 
-/** Return a complete, ordered scientific-pitch range or fail closed. */
-function playableRange(
+/**
+ * Return a complete, ordered scientific-pitch range or fail closed.
+ *
+ * Shared by the first-range callout and the section roadmap so both surfaces
+ * only present spans that parse as scientific pitch labels in low-to-high
+ * order; malformed or inverted evidence is rejected instead of being shown
+ * as playable-range guidance.
+ */
+export function playableRange(
   lowestNoteValue: unknown,
   highestNoteValue: unknown
 ): Pick<FirstRangeSqueeze, "lowestNote" | "highestNote"> | null {

From 3a42d475de6e15b7928e50e34bdbbe6e50f14f41 Mon Sep 17 00:00:00 2001
From: seonghobae <me@seonghobae.me>
Date: Wed, 26 Aug 2026 13:52:34 +0900
Subject: [PATCH 10/10] fix(review): satisfy fillRangeCopy tokens from own
 properties only

values[token] also resolves inherited members, so a {toString} token with no
matching value would render the inherited function source instead of keeping
the placeholder. Look up via hasOwnProperty and pin the regression with a
{toString}/{missingToken} test.
---
 .../src/features/workspace/firstRangeSqueeze.test.ts        | 6 ++++++
 apps/desktop/src/features/workspace/firstRangeSqueeze.ts    | 4 +++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
index 7997d80db..643935954 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.test.ts
@@ -158,4 +158,10 @@ describe("fillRangeCopy", () => {
       })
     ).toBe("Bass $& {sectionLabel} in verse.");
   });
+
+  it("does not satisfy tokens with inherited object members", () => {
+    expect(
+      fillRangeCopy("Check {toString} before {missingToken}.", { sectionLabel: "verse" })
+    ).toBe("Check {toString} before {missingToken}.");
+  });
 });
diff --git a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
index 5cd1d42ba..47270d2a9 100644
--- a/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
+++ b/apps/desktop/src/features/workspace/firstRangeSqueeze.ts
@@ -165,6 +165,8 @@ export function firstRangeSqueeze(
 /** Fill trusted `{token}` placeholders once while keeping rehearsal values literal. */
 export function fillRangeCopy(template: string, values: Record<string, string>): string {
   return template.replace(/\{([A-Za-z][A-Za-z0-9]*)\}/g, (placeholder, token: string) => {
-    return values[token] ?? placeholder;
+    // Own-property lookup only: inherited members such as `toString` must
+    // never satisfy a token, or the raw function source would be rendered.
+    return Object.prototype.hasOwnProperty.call(values, token) ? values[token] : placeholder;
   });
 }