diff --git a/AGENTS.md b/AGENTS.md index b9a67ce17..0457e5302 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, remaining-leftover cues at a leftover return, simplification guidance, transposition or setup cues, part-overlap cues, visible confidence, and rehearsal priorities. - 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..4947b182b 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, 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 naming tonight's first span and tonight's first remaining leftover at a leftover return - 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..0cf1d2ab8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ### Added +- Name tonight's first remaining leftover on the ready rehearsal map and tell the leftover part to stay out, or the band to count that leftover part out, at the leftover return. - 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..5e4a71b64 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 tonight's first remaining leftover at a leftover return. `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/Workspace.test.tsx b/apps/desktop/src/features/workspace/Workspace.test.tsx index 7837bf80e..1d9add39e 100644 --- a/apps/desktop/src/features/workspace/Workspace.test.tsx +++ b/apps/desktop/src/features/workspace/Workspace.test.tsx @@ -196,6 +196,114 @@ describe("Workspace", () => { ); }); + it("names tonight's first remaining leftover at a leftover return", () => { + setNavigatorLanguage("en-US"); + const song = createDemoRehearsalSong(); + const verse = song.sections[0]!; + song.sections = [ + { + ...verse, + partGraph: verse.partGraph.map((node) => + node.role_id === "bass-guitar" || + node.role_id === "keys-right" || + node.role_id === "lead-vocal" + ? { ...node, is_active: false } + : node + ) + }, + { + ...verse, + id: "chorus-1", + label: "chorus", + timeRange: { start: verse.timeRange.end, end: verse.timeRange.end + 20 }, + partGraph: verse.partGraph.map((node) => + node.role_id === "keys-right" || node.role_id === "lead-vocal" + ? { ...node, is_active: false } + : node + ) + }, + { + ...verse, + id: "bridge-1", + label: "bridge", + timeRange: { + start: verse.timeRange.end + 20, + end: verse.timeRange.end + 40 + }, + partGraph: verse.partGraph.map((node) => + node.role_id === "lead-vocal" ? { ...node, is_active: false } : node + ) + } + ]; + + render(); + + const callout = screen.getByTestId("first-remaining-leftover"); + expect(callout).toHaveTextContent("Tonight's first remaining leftover"); + expect(callout).toHaveTextContent( + "Lead Vocal stays out at bridge while Keyboard 1 Right Hand comes back from chorus. Count Lead Vocal out from the top of bridge." + ); + }); + + it("tells the remaining leftover to stay out at the leftover return", () => { + setNavigatorLanguage("en-US"); + const song = createDemoRehearsalSong(); + const verse = song.sections[0]!; + song.sections = [ + { + ...verse, + partGraph: verse.partGraph.map((node) => + node.role_id === "bass-guitar" || + node.role_id === "keys-right" || + node.role_id === "lead-vocal" + ? { ...node, is_active: false } + : node + ) + }, + { + ...verse, + id: "chorus-1", + label: "chorus", + timeRange: { start: verse.timeRange.end, end: verse.timeRange.end + 20 }, + partGraph: verse.partGraph.map((node) => + node.role_id === "keys-right" || node.role_id === "lead-vocal" + ? { ...node, is_active: false } + : node + ) + }, + { + ...verse, + id: "bridge-1", + label: "bridge", + timeRange: { + start: verse.timeRange.end + 20, + end: verse.timeRange.end + 40 + }, + partGraph: verse.partGraph.map((node) => + node.role_id === "lead-vocal" ? { ...node, is_active: false } : node + ) + } + ]; + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" })); + + expect(screen.getByTestId("first-remaining-leftover")).toHaveTextContent( + "Lead Vocal stays out at bridge while Keyboard 1 Right Hand comes back from chorus. Stay out from the top of bridge." + ); + }); + + it("asks the player to confirm the remaining leftover when every part stays active", () => { + setNavigatorLanguage("en-US"); + const song = createDemoRehearsalSong(); + + render(); + + expect(screen.getByTestId("first-remaining-leftover")).toHaveTextContent( + "Tonight's first remaining leftover still needs a named leftover part that stays out at the leftover return. Confirm who stays out at that return before the first section." + ); + }); + 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 d44e20777..a1f042e3f 100644 --- a/apps/desktop/src/features/workspace/Workspace.tsx +++ b/apps/desktop/src/features/workspace/Workspace.tsx @@ -5,6 +5,7 @@ import { SectionRoadmap } from "./SectionRoadmap"; import { GrooveMap } from "./GrooveMap"; import { PracticeProgress } from "./PracticeProgress"; import { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze"; +import { firstRemainingLeftover } from "./firstRemainingLeftover"; import { createTranslator, detectPreferredLocale } from "../../i18n"; import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export"; import { Button } from "@/components/ui/button"; @@ -163,6 +164,25 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp } ) : t("workspaceFirstRangeMissing"); + const namedRemainingLeftover = useMemo( + () => firstRemainingLeftover(song, activeRole), + [activeRole, song] + ); + const firstRemainingLeftoverCopy = namedRemainingLeftover + ? fillRangeCopy( + t( + activeRole && activeRole === namedRemainingLeftover.remainingRoleId + ? "workspaceFirstRemainingLeftoverStayOut" + : "workspaceFirstRemainingLeftoverNamed" + ), + { + remainingRoleName: namedRemainingLeftover.remainingRoleName, + returningRoleName: namedRemainingLeftover.returningRoleName, + sectionLabel: namedRemainingLeftover.sectionLabel, + leftoverSectionLabel: namedRemainingLeftover.leftoverSectionLabel + } + ) + : t("workspaceFirstRemainingLeftoverMissing"); /** Handle the practice progress change internally by immutably updating the song state. */ const handlePracticeProgressChange = (newProgress: number) => { @@ -309,6 +329,14 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp

{t("workspaceFirstRangeTitle")}

{firstRangeCopy}

+
+

{t("workspaceFirstRemainingLeftoverTitle")}

+

{firstRemainingLeftoverCopy}

+
diff --git a/apps/desktop/src/features/workspace/firstRemainingLeftover.selected-role.test.ts b/apps/desktop/src/features/workspace/firstRemainingLeftover.selected-role.test.ts new file mode 100644 index 000000000..5cf0fd675 --- /dev/null +++ b/apps/desktop/src/features/workspace/firstRemainingLeftover.selected-role.test.ts @@ -0,0 +1,122 @@ +import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types"; +import { describe, expect, it } from "vitest"; +import { firstRemainingLeftover } from "./firstRemainingLeftover"; + +function sectionWithInactiveRoles( + template: RehearsalSong["sections"][number], + id: string, + label: RehearsalSong["sections"][number]["label"], + start: number, + inactiveRoleIds: readonly string[] +): RehearsalSong["sections"][number] { + const inactive = new Set(inactiveRoleIds); + return { + ...template, + id, + label, + timeRange: { start, end: start + 20 }, + partGraph: template.partGraph.map((node) => ({ + ...node, + is_active: !inactive.has(node.role_id) + })) + }; +} + +describe("firstRemainingLeftover selected-role search", () => { + it("keeps searching after the selected part newly drops out during an earlier leftover sit-out", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, [ + "bass-guitar", + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [ + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, [ + "bass-guitar", + "lead-vocal" + ]), + sectionWithInactiveRoles(template, "outro-1", "outro", 60, ["lead-vocal"]) + ] + }; + + expect(firstRemainingLeftover(song, "bass-guitar")).toEqual({ + sectionLabel: "outro", + leftoverSectionLabel: "chorus", + fromSectionLabel: "verse", + remainingRoleId: "lead-vocal", + remainingRoleName: "Lead Vocal", + returningRoleId: "keys-right", + returningRoleName: "Keyboard 1 Right Hand" + }); + }); + + it("does not tell a new dropout to stay out from an earlier leftover sit-out", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, [ + "bass-guitar", + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [ + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, ["bass-guitar", "lead-vocal"]) + ] + }; + + expect(firstRemainingLeftover(song, "bass-guitar")).toBeNull(); + }); + + it("does not show another part's leftover cue to a selected part that stayed active", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const selectedRole = { + ...template.roles[0]!, + id: "always-active", + name: "Always Active" + }; + const selectedTemplate: RehearsalSong["sections"][number] = { + ...template, + roles: [...template.roles, selectedRole], + partGraph: [ + ...template.partGraph, + { + ...template.partGraph[0]!, + role_id: "always-active", + is_active: true, + handoff_to: [], + handoff_from: [] + } + ] + }; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(selectedTemplate, "verse-1", "verse", 0, [ + "bass-guitar", + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(selectedTemplate, "chorus-1", "chorus", 20, [ + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(selectedTemplate, "bridge-1", "bridge", 40, ["lead-vocal"]) + ] + }; + + expect(firstRemainingLeftover(song, "always-active")).toBeNull(); + }); +}); diff --git a/apps/desktop/src/features/workspace/firstRemainingLeftover.test.ts b/apps/desktop/src/features/workspace/firstRemainingLeftover.test.ts new file mode 100644 index 000000000..69cfc8301 --- /dev/null +++ b/apps/desktop/src/features/workspace/firstRemainingLeftover.test.ts @@ -0,0 +1,399 @@ +import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types"; +import { describe, expect, it } from "vitest"; +import { fillRangeCopy } from "./firstRangeSqueeze"; +import { firstRemainingLeftover } from "./firstRemainingLeftover"; + +function sectionWithInactiveRoles( + template: RehearsalSong["sections"][number], + id: string, + label: string, + start: number, + inactiveRoleIds: readonly string[], + activeOnlyRoles = false +): RehearsalSong["sections"][number] { + const inactive = new Set(inactiveRoleIds); + const partGraph = template.partGraph.map((node) => ({ + ...node, + is_active: !inactive.has(node.role_id) + })); + return { + ...template, + id, + label: label as RehearsalSong["sections"][number]["label"], + timeRange: { start, end: start + 20 }, + partGraph, + roles: activeOnlyRoles + ? template.roles.filter((role) => !inactive.has(role.id)) + : template.roles + }; +} + +function leftoverThenRemainingReturn( + returningRoleId = "keys-right", + remainingRoleId = "lead-vocal", + originalSitOutRoleId = "bass-guitar" +): RehearsalSong { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + return { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, [ + originalSitOutRoleId, + returningRoleId, + remainingRoleId + ]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [ + returningRoleId, + remainingRoleId + ]), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, [remainingRoleId]) + ] + }; +} + +describe("firstRemainingLeftover", () => { + it("returns null on the demo song where every graph node is active", () => { + expect(firstRemainingLeftover(createDemoRehearsalSong())).toBeNull(); + }); + + it("names the remaining leftover at a leftover return", () => { + expect(firstRemainingLeftover(leftoverThenRemainingReturn())).toEqual({ + sectionLabel: "bridge", + leftoverSectionLabel: "chorus", + fromSectionLabel: "verse", + remainingRoleId: "lead-vocal", + remainingRoleName: "Lead Vocal", + returningRoleId: "keys-right", + returningRoleName: "Keyboard 1 Right Hand" + }); + }); + + it("uses song-wide role names when inactive analysis roles are omitted from section roles", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "opening-1", "opening", 0, []), + sectionWithInactiveRoles( + template, + "bridge-1", + "bridge", + 20, + ["bass-guitar", "keys-right", "lead-vocal"], + true + ), + sectionWithInactiveRoles( + template, + "chorus-1", + "chorus", + 40, + ["keys-right", "lead-vocal"], + true + ), + sectionWithInactiveRoles(template, "outro-1", "outro", 60, ["lead-vocal"], true) + ] + }; + + expect(firstRemainingLeftover(song)).toEqual({ + sectionLabel: "outro", + leftoverSectionLabel: "chorus", + fromSectionLabel: "bridge", + remainingRoleId: "lead-vocal", + remainingRoleName: "Lead Vocal", + returningRoleId: "keys-right", + returningRoleName: "Keyboard 1 Right Hand" + }); + }); + + it("treats repeated form labels as distinct timeline sections", () => { + const song = leftoverThenRemainingReturn(); + song.sections[2] = { + ...song.sections[2]!, + label: song.sections[1]!.label + }; + + expect(firstRemainingLeftover(song)).toEqual({ + sectionLabel: "chorus", + leftoverSectionLabel: "chorus", + fromSectionLabel: "verse", + remainingRoleId: "lead-vocal", + remainingRoleName: "Lead Vocal", + returningRoleId: "keys-right", + returningRoleName: "Keyboard 1 Right Hand" + }); + }); + + it("skips a continued leftover sit-out until a leftover return leaves a remaining leftover", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, [ + "bass-guitar", + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [ + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(template, "tag-1", "tag", 40, ["keys-right", "lead-vocal"]), + sectionWithInactiveRoles(template, "outro-1", "outro", 60, ["lead-vocal"]) + ] + }; + + expect(firstRemainingLeftover(song)).toEqual({ + sectionLabel: "outro", + leftoverSectionLabel: "chorus", + fromSectionLabel: "verse", + remainingRoleId: "lead-vocal", + remainingRoleName: "Lead Vocal", + returningRoleId: "keys-right", + returningRoleName: "Keyboard 1 Right Hand" + }); + }); + + it("fails closed when the leftover return has no remaining leftover", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, ["bass-guitar", "keys-right"]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, ["keys-right"]), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, []) + ] + }; + + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("keeps the selected remaining leftover and returning leftover on tonight's first remaining leftover", () => { + const song = leftoverThenRemainingReturn(); + expect(firstRemainingLeftover(song, "lead-vocal")).toEqual({ + sectionLabel: "bridge", + leftoverSectionLabel: "chorus", + fromSectionLabel: "verse", + remainingRoleId: "lead-vocal", + remainingRoleName: "Lead Vocal", + returningRoleId: "keys-right", + returningRoleName: "Keyboard 1 Right Hand" + }); + expect(firstRemainingLeftover(song, "keys-right")).toEqual({ + sectionLabel: "bridge", + leftoverSectionLabel: "chorus", + fromSectionLabel: "verse", + remainingRoleId: "lead-vocal", + remainingRoleName: "Lead Vocal", + returningRoleId: "keys-right", + returningRoleName: "Keyboard 1 Right Hand" + }); + expect(firstRemainingLeftover(song, "bass-guitar")).toEqual({ + sectionLabel: "bridge", + leftoverSectionLabel: "chorus", + fromSectionLabel: "verse", + remainingRoleId: "lead-vocal", + remainingRoleName: "Lead Vocal", + returningRoleId: "keys-right", + returningRoleName: "Keyboard 1 Right Hand" + }); + expect(firstRemainingLeftover(song, "missing-role")).toBeNull(); + }); + + it("does not treat a leftover sit-out without a later leftover return as a remaining leftover", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + expect( + firstRemainingLeftover({ + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, [ + "bass-guitar", + "keys-right", + "lead-vocal" + ]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, [ + "keys-right", + "lead-vocal" + ]) + ] + }) + ).toBeNull(); + }); + + it("does not treat a come-in without a leftover sit-out as a remaining leftover", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, ["keys-right"]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, []) + ] + }; + + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("does not treat a tutti after a full original return as a remaining leftover", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, ["bass-guitar", "keys-right"]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, []), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, []) + ] + }; + + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("does not treat a new dropout after every original sit-out returns as a remaining leftover", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, ["bass-guitar", "keys-right"]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, []), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, ["lead-vocal"]) + ] + }; + + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("does not treat a continued sit-out with nobody returning as a remaining leftover", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, ["keys-right"]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, ["keys-right"]), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, []) + ] + }; + + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("ignores inherited is_active evidence", () => { + const song = leftoverThenRemainingReturn(); + const inherited = Object.create({ + is_active: false, + role_id: "keys-right" + }) as RehearsalSong["sections"][number]["partGraph"][number]; + song.sections[0] = { + ...song.sections[0]!, + partGraph: [inherited, ...song.sections[0]!.partGraph] + }; + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("does not treat a missing is_active flag as remaining-leftover evidence", () => { + const song = leftoverThenRemainingReturn(); + song.sections[1] = { + ...song.sections[1]!, + partGraph: song.sections[1]!.partGraph.map((node) => { + if (node.role_id !== "keys-right") { + return node; + } + const rest: Record = { + role_id: node.role_id, + handoff_to: node.handoff_to, + handoff_from: node.handoff_from + }; + return rest as RehearsalSong["sections"][number]["partGraph"][number]; + }) + }; + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("fails closed on contradictory duplicate graph identities", () => { + const song = leftoverThenRemainingReturn(); + const section = song.sections[2]!; + const keysNode = section.partGraph.find((node) => node.role_id === "keys-right")!; + const withoutKeys = section.partGraph.filter((node) => node.role_id !== "keys-right"); + song.sections[2] = { + ...section, + partGraph: [...withoutKeys, { ...keysNode, is_active: true }, { ...keysNode, is_active: false }] + }; + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("skips blank leftover-return labels until a named remaining leftover exists", () => { + const song = leftoverThenRemainingReturn(); + song.sections[2] = { + ...song.sections[2]!, + label: "none" as RehearsalSong["sections"][number]["label"] + }; + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("fails closed when the later section has no named leftover role", () => { + const song = leftoverThenRemainingReturn(); + song.sections[0] = { + ...song.sections[0]!, + roles: song.sections[0]!.roles.map((role) => ({ ...role, name: " " })) + }; + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("fails closed when a later section has no named graph", () => { + const song = leftoverThenRemainingReturn(); + song.sections[2] = { + ...song.sections[2]!, + partGraph: [] + }; + expect(firstRemainingLeftover(song)).toBeNull(); + }); + + it("fails closed on malformed runtime roots", () => { + for (const malformed of [null, {}, { sections: {} }, { sections: [null] }]) { + expect(firstRemainingLeftover(malformed as unknown as RehearsalSong)).toBeNull(); + } + }); + + it("isolates blank role ids, non-boolean flags, and unnamed graph members", () => { + const song = leftoverThenRemainingReturn(); + song.sections[0] = { + ...song.sections[0]!, + partGraph: [ + { role_id: " ", is_active: false, handoff_to: [], handoff_from: [] }, + { role_id: "ghost", is_active: false, handoff_to: [], handoff_from: [] }, + { + role_id: "keys-right", + is_active: "no" as unknown as boolean, + handoff_to: [], + handoff_from: [] + }, + ...song.sections[0]!.partGraph + ] + }; + expect(firstRemainingLeftover(song)).toBeNull(); + }); +}); + +describe("remaining-leftover copy filling", () => { + it("keeps rehearsal values literal", () => { + expect( + fillRangeCopy( + "{remainingRoleName} stays out at {sectionLabel} while {returningRoleName} comes back from {leftoverSectionLabel}.", + { + remainingRoleName: "Lead Vocal {sectionLabel}", + returningRoleName: "Keyboard 1 Right Hand", + sectionLabel: "bridge", + leftoverSectionLabel: "chorus" + } + ) + ).toBe( + "Lead Vocal {sectionLabel} stays out at bridge while Keyboard 1 Right Hand comes back from chorus." + ); + }); +}); diff --git a/apps/desktop/src/features/workspace/firstRemainingLeftover.ts b/apps/desktop/src/features/workspace/firstRemainingLeftover.ts new file mode 100644 index 000000000..2c52c2fd8 --- /dev/null +++ b/apps/desktop/src/features/workspace/firstRemainingLeftover.ts @@ -0,0 +1,279 @@ +import type { RehearsalSong } from "@bandscope/shared-types"; +import { meaningfulRangeText } from "./firstRangeSqueeze"; + +/** Tonight's first named remaining leftover at a leftover return. */ +export type FirstRemainingLeftover = { + sectionLabel: string; + leftoverSectionLabel: string; + fromSectionLabel: string; + remainingRoleId: string; + remainingRoleName: string; + returningRoleId: string; + returningRoleName: string; +}; + +/** Return whether an untrusted runtime value is a plain object record. */ +function isRuntimeObject(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +/** Admit an own-property boolean `is_active` flag. Inherited evidence is isolated. */ +function ownActiveFlag(value: Record): boolean | null { + if (!Object.prototype.hasOwnProperty.call(value, "is_active")) { + return null; + } + if (value.is_active === true) { + return true; + } + if (value.is_active === false) { + return false; + } + return null; +} + +type NamedRoleCatalog = Map; + +/** + * Build trustworthy role identity evidence across the whole song. + * + * Production analysis emits active-only section `roles` while keeping inactive + * identities in `partGraph`. The song-wide catalog therefore lets a leftover + * part keep its trustworthy display name across the sit-out, leftover return, + * and remaining leftover. + */ +function namedSongRoles(songValue: Record): NamedRoleCatalog | null { + if (!Array.isArray(songValue.sections)) { + return null; + } + + const namedRoles: NamedRoleCatalog = new Map(); + for (const sectionValue of songValue.sections) { + if (!isRuntimeObject(sectionValue) || !Array.isArray(sectionValue.roles)) { + return null; + } + + const sectionRoleIds = new Set(); + for (const roleValue of sectionValue.roles) { + if ( + !isRuntimeObject(roleValue) || + !Object.prototype.hasOwnProperty.call(roleValue, "id") || + !Object.prototype.hasOwnProperty.call(roleValue, "name") + ) { + return null; + } + + const roleId = meaningfulRangeText(roleValue.id); + const roleName = meaningfulRangeText(roleValue.name); + if (!roleId || !roleName || sectionRoleIds.has(roleId)) { + return null; + } + sectionRoleIds.add(roleId); + + const knownName = namedRoles.get(roleId); + if (knownName && knownName !== roleName) { + return null; + } + namedRoles.set(roleId, roleName); + } + } + + return namedRoles.size > 0 ? namedRoles : null; +} + +type NamedGraphNode = { + roleId: string; + active: boolean; +}; + +/** + * Collect one complete, unique activity record for every song-wide named role. + * + * Missing, unknown, duplicate, inherited, or non-boolean graph evidence fails + * closed so a leftover part cannot be both returning and remaining in the same + * section. + */ +function namedGraphNodes( + sectionValue: Record, + namedRoles: NamedRoleCatalog +): NamedGraphNode[] | null { + if (!Array.isArray(sectionValue.partGraph)) { + return null; + } + + const nodes: NamedGraphNode[] = []; + const seenRoleIds = new Set(); + for (const nodeValue of sectionValue.partGraph) { + if ( + !isRuntimeObject(nodeValue) || + !Object.prototype.hasOwnProperty.call(nodeValue, "role_id") + ) { + return null; + } + + const roleId = meaningfulRangeText(nodeValue.role_id); + if (!roleId || !namedRoles.has(roleId) || seenRoleIds.has(roleId)) { + return null; + } + + const active = ownActiveFlag(nodeValue); + if (active === null) { + return null; + } + + seenRoleIds.add(roleId); + nodes.push({ roleId, active }); + } + + return seenRoleIds.size === namedRoles.size ? nodes : null; +} + +type PendingLeftoverSitOut = { + leftoverSectionLabel: string; + fromSectionLabel: string; + reducedCohortIds: string[]; + leftoverIds: string[]; +}; + +/** + * Pick the first remaining leftover a player should honor at a leftover return. + * + * A leftover sit-out is the first later named section where at least one member + * of the current reduced cohort has returned and at least one remains out. A + * leftover return is the first named section after that leftover sit-out where + * at least one leftover part is own-property active. A remaining leftover is a + * leftover from that leftover sit-out that is still own-property tacet at the + * leftover return. A leftover return with nobody still out, a come-in, tacet, + * leftover sit-out, tutti, continued sit-out, or a new dropout after a full + * original return is not a remaining leftover. + * + * Inherited/missing activity, incomplete or contradictory graphs, unnamed + * roles, and malformed runtime data fail closed. When a role is selected, a + * remaining leftover is shown only when that named part belonged to the + * originating reduced cohort. A selected part that drops out again later must + * itself be one of the remaining leftovers before that cue can be shown. + */ +export function firstRemainingLeftover( + song: RehearsalSong | unknown, + activeRole: string | null = null +): FirstRemainingLeftover | null { + if (!isRuntimeObject(song) || !Array.isArray(song.sections)) { + return null; + } + + const namedRoles = namedSongRoles(song); + if (!namedRoles || (activeRole && !namedRoles.has(activeRole))) { + return null; + } + + let reducedFrom: string | null = null; + let sittingOutIds: Set | null = null; + let pending: PendingLeftoverSitOut | null = null; + + for (const sectionValue of song.sections) { + if (!isRuntimeObject(sectionValue)) { + return null; + } + const sectionLabel = meaningfulRangeText(sectionValue.label); + if (!sectionLabel) { + continue; + } + + const nodes = namedGraphNodes(sectionValue, namedRoles); + if (!nodes) { + return null; + } + + const sittingOut = nodes.filter((node) => node.active === false); + + if (pending) { + const leftoverNodes = pending.leftoverIds.map((leftoverId) => + nodes.find((node) => node.roleId === leftoverId) + ); + if (leftoverNodes.some((node) => !node)) { + return null; + } + + const returningLeftovers = leftoverNodes.filter((node) => node!.active); + const remainingLeftovers = leftoverNodes.filter((node) => node!.active === false); + + if (returningLeftovers.length > 0 && remainingLeftovers.length > 0) { + let remaining = remainingLeftovers[0]!; + const returning = returningLeftovers[0]!; + if (activeRole) { + if (!pending.reducedCohortIds.includes(activeRole)) { + continue; + } + const activeRoleNode = nodes.find((node) => node.roleId === activeRole); + if (!activeRoleNode) { + return null; + } + if (!activeRoleNode.active) { + const selectedRemaining = remainingLeftovers.find((node) => node!.roleId === activeRole); + if (!selectedRemaining) { + continue; + } + remaining = selectedRemaining; + } + } + return { + sectionLabel, + leftoverSectionLabel: pending.leftoverSectionLabel, + fromSectionLabel: pending.fromSectionLabel, + remainingRoleId: remaining.roleId, + remainingRoleName: namedRoles.get(remaining.roleId)!, + returningRoleId: returning.roleId, + returningRoleName: namedRoles.get(returning.roleId)! + }; + } + + if (returningLeftovers.length > 0 && remainingLeftovers.length === 0) { + pending = null; + if (sittingOut.length === 0) { + reducedFrom = null; + sittingOutIds = null; + } else { + reducedFrom = sectionLabel; + sittingOutIds = new Set(sittingOut.map((node) => node.roleId)); + } + } + continue; + } + + if (!sittingOutIds || !reducedFrom) { + if (sittingOut.length === 0) { + continue; + } + reducedFrom = sectionLabel; + sittingOutIds = new Set(sittingOut.map((node) => node.roleId)); + continue; + } + + const baselineIds = sittingOutIds; + const returning = nodes.filter( + (node) => node.active === true && baselineIds.has(node.roleId) + ); + const leftovers = sittingOut.filter((node) => baselineIds.has(node.roleId)); + + if (returning.length > 0 && leftovers.length > 0) { + pending = { + leftoverSectionLabel: sectionLabel, + fromSectionLabel: reducedFrom, + reducedCohortIds: [...baselineIds], + leftoverIds: leftovers.map((node) => node.roleId) + }; + continue; + } + + if (returning.length === baselineIds.size && leftovers.length === 0) { + if (sittingOut.length === 0) { + reducedFrom = null; + sittingOutIds = null; + } else { + reducedFrom = sectionLabel; + sittingOutIds = new Set(sittingOut.map((node) => node.roleId)); + } + } + } + + return null; +} diff --git a/apps/desktop/src/i18n/index.test.ts b/apps/desktop/src/i18n/index.test.ts index dc49a0a25..f107b222e 100644 --- a/apps/desktop/src/i18n/index.test.ts +++ b/apps/desktop/src/i18n/index.test.ts @@ -60,6 +60,7 @@ describe("i18n", () => { const t = createTranslator("ko"); expect(t("appTitle")).toBe("BandScope"); expect(t("appSubtitle")).toBe("합주 준비를 위한 로컬-퍼스트 분석 도구"); + expect(t("workspaceFirstRemainingLeftoverTitle")).toBe("오늘 먼저 남을 쉬는 자리"); }); it("falls back to English when a Korean translation is missing", () => { diff --git a/apps/desktop/src/locales/en/common.json b/apps/desktop/src/locales/en/common.json index d803a765e..e4a1c7585 100644 --- a/apps/desktop/src/locales/en/common.json +++ b/apps/desktop/src/locales/en/common.json @@ -153,6 +153,10 @@ "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.", + "workspaceFirstRemainingLeftoverTitle": "Tonight's first remaining leftover", + "workspaceFirstRemainingLeftoverNamed": "{remainingRoleName} stays out at {sectionLabel} while {returningRoleName} comes back from {leftoverSectionLabel}. Count {remainingRoleName} out from the top of {sectionLabel}.", + "workspaceFirstRemainingLeftoverStayOut": "{remainingRoleName} stays out at {sectionLabel} while {returningRoleName} comes back from {leftoverSectionLabel}. Stay out from the top of {sectionLabel}.", + "workspaceFirstRemainingLeftoverMissing": "Tonight's first remaining leftover still needs a named leftover part that stays out at the leftover return. Confirm who stays out at that return 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 0f6c6c66d..98757e39d 100644 --- a/apps/desktop/src/locales/ko/common.json +++ b/apps/desktop/src/locales/ko/common.json @@ -153,6 +153,10 @@ "workspaceFirstRangeCheck": "{sectionLabel}의 {roleName}은 {lowestNote}–{highestNote}입니다. {sectionLabel} 들어가기 전에 그 음역을 악기로 확인해 보세요.", "workspaceFirstRangeClash": "{sectionLabel}의 {roleName}은 {lowestNote}–{highestNote}이고 다른 파트와 겹칩니다. {sectionLabel} 들어가기 전에 그 충돌을 악기로 들어 보세요.", "workspaceFirstRangeMissing": "오늘 먼저 볼 음역은 아직 귀로 확인이 필요합니다. 선택한 파트의 최저·최고음을 첫 구간 전에 확인해 보세요.", + "workspaceFirstRemainingLeftoverTitle": "오늘 먼저 남을 쉬는 자리", + "workspaceFirstRemainingLeftoverNamed": "{remainingRoleName}은 {leftoverSectionLabel}에서 쉰 뒤 {sectionLabel}에서 {returningRoleName}이 들어올 때도 쉬세요. {sectionLabel} 처음부터 {remainingRoleName}을 빼 두세요.", + "workspaceFirstRemainingLeftoverStayOut": "{remainingRoleName}은 {leftoverSectionLabel}에서 쉰 뒤 {sectionLabel}에서 {returningRoleName}이 들어올 때도 쉬세요. {sectionLabel} 처음부터 쉬세요.", + "workspaceFirstRemainingLeftoverMissing": "오늘 먼저 남을 쉬는 자리는 아직 확인이 필요합니다. 복귀 구간에서 누가 계속 쉬는지 첫 구간 전에 확인하세요.", "sectionRangeLabel": "음역", "sectionRangeNextAction": "{sectionLabel} 들어가기 전에 이 음역을 악기로 확인해 보세요." } diff --git a/docs/design-system/component-contract.md b/docs/design-system/component-contract.md index 22602c313..af2a0d23b 100644 --- a/docs/design-system/component-contract.md +++ b/docs/design-system/component-contract.md @@ -80,6 +80,7 @@ The authoritative Figma view is `31 Component Contract Catalog`. This file mirro - `LoadingState` keeps `role="status"`, `aria-live="polite"`, `aria-atomic="true"`, and `aria-busy="true"`. - `ErrorState` keeps `role="alert"`, `aria-live="assertive"`, and visible safe error detail copy. - `EmptyState` must remain an actionable state card, not a blank placeholder panel. +- Ready `Workspace` names tonight's first playable range and tonight's first remaining leftover so the map enables the next rehearsal action without opening files or export paths. - If a new workspace state is added in code, update Figma page 34 and page 33 audit evidence before merging. ## Pattern Backlog diff --git a/docs/doctoring/first-remaining-leftover.md b/docs/doctoring/first-remaining-leftover.md new file mode 100644 index 000000000..d7ab48ff2 --- /dev/null +++ b/docs/doctoring/first-remaining-leftover.md @@ -0,0 +1,18 @@ +# Tonight's first remaining leftover + +The ready rehearsal map names the first remaining leftover from existing `partGraph` evidence: a named leftover sit-out, then a later named leftover return where at least one leftover named part is own-property active and at least one leftover remains own-property tacet. This is who still stays out while the leftover part comes back. It is not a come-in, tacet, leftover sit-out, leftover return, tutti, handoff, Fine, last-line breath, a leftover return with nobody still out, a continued sit-out with nobody returning, or a new dropout after every original sit-out returns. + +## Next action + +- Named remaining leftover: stay out from the top of the named leftover return while the leftover part comes back. +- Named returning or other included part: count the remaining leftover out from the top of the named leftover return. +- Missing: confirm who stays out at the leftover return before the first section. + +## Security Notes + +- Untrusted inputs: `RehearsalSong` JSON, section labels, `partGraph` nodes, `is_active`, role ids, and role names from analysis or a reopened project. +- Trust boundary: this helper never opens files, URLs, IPC, WebView, subprocesses, model artifacts, or export paths. It only admits an own-property leftover sit-out followed by a later named leftover return where a leftover part is own-property active and another leftover remains own-property tacet. +- Allowlist: section labels and role names must be meaningful text. A missing graph node is not a remaining leftover. Inherited `is_active` is isolated. Same-section false-then-true nodes are not a remaining leftover. A leftover return with nobody still out is a leftover return, not a remaining leftover. All-active later sections after a full original return are tuttis, not remaining leftovers. Continued sit-outs with nobody returning are not remaining leftovers. A new dropout after every original sit-out returns is a dropout, not a remaining leftover. When a role is selected, only a remaining leftover after a leftover sit-out that includes that named part is shown. +- Safe failure: inherited flags, blank labels, missing names, leftover sit-outs without a leftover return, leftover returns with nobody still out, come-ins without a leftover, full-band returns, continued sit-outs, new dropouts after a full original return, and malformed roots return `null` so the workspace shows the missing-copy next action instead of crashing or inventing a remaining leftover. +- Logging/privacy: rejected or accepted remaining leftovers are not logged. Copy interpolation keeps rehearsal values literal. +- Tests: `firstRemainingLeftover.test.ts` and the Workspace callout cover the demo all-active case, an explicit lead remaining leftover after a leftover return, selected-role scoping, inherited flags, missing `is_active`, continued sit-outs, tuttis, come-ins, leftover returns with nobody still out, new dropouts after a full original return, unnamed roles, empty graphs, and literal copy filling.