diff --git a/AGENTS.md b/AGENTS.md index b9a67ce17..887811c57 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, leftover sit-out cues after a partial 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..5f1ef4555 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 leftover sit-out after a partial 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..fc3fdfb3f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ### Added +- Name tonight's first leftover sit-out on the ready rehearsal map and tell returning parts to play without waiting, or the leftover part to stay out. - 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..964b0a6f8 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 leftover sit-out after a partial 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..4ed4e013a 100644 --- a/apps/desktop/src/features/workspace/Workspace.test.tsx +++ b/apps/desktop/src/features/workspace/Workspace.test.tsx @@ -196,6 +196,82 @@ describe("Workspace", () => { ); }); + it("names tonight's first leftover sit-out after a partial 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, 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, is_active: false } : node + ) + } + ]; + + render(); + + const callout = screen.getByTestId("first-leftover"); + expect(callout).toHaveTextContent("Tonight's first leftover sit-out"); + expect(callout).toHaveTextContent( + "Keyboard 1 Right Hand stays tacet in chorus after verse. Play chorus without waiting for Keyboard 1 Right Hand." + ); + }); + + it("tells the leftover part to stay out of the partial 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, 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, is_active: false } : node + ) + } + ]; + + render(); + fireEvent.click(screen.getByRole("tab", { name: "Keyboard 1 Right Hand" })); + + expect(screen.getByTestId("first-leftover")).toHaveTextContent( + "Keyboard 1 Right Hand stays tacet in chorus after verse. Stay out of chorus." + ); + }); + + it("asks the player to confirm the leftover sit-out when every part stays active", () => { + setNavigatorLanguage("en-US"); + const song = createDemoRehearsalSong(); + + render(); + + expect(screen.getByTestId("first-leftover")).toHaveTextContent( + "Tonight's first leftover sit-out still needs a named part that stays out after others return. Confirm who stays tacet 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..aafe5a93e 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 { firstLeftover } from "./firstLeftover"; import { createTranslator, detectPreferredLocale } from "../../i18n"; import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export"; import { Button } from "@/components/ui/button"; @@ -163,6 +164,21 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp } ) : t("workspaceFirstRangeMissing"); + const namedLeftover = useMemo(() => firstLeftover(song, activeRole), [activeRole, song]); + const firstLeftoverCopy = namedLeftover + ? fillRangeCopy( + t( + activeRole && activeRole === namedLeftover.leftoverRoleId + ? "workspaceFirstLeftoverStayOut" + : "workspaceFirstLeftoverNamed" + ), + { + leftoverRoleName: namedLeftover.leftoverRoleName, + sectionLabel: namedLeftover.sectionLabel, + fromSectionLabel: namedLeftover.fromSectionLabel + } + ) + : t("workspaceFirstLeftoverMissing"); /** Handle the practice progress change internally by immutably updating the song state. */ const handlePracticeProgressChange = (newProgress: number) => { @@ -309,6 +325,14 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp

{t("workspaceFirstRangeTitle")}

{firstRangeCopy}

+
+

{t("workspaceFirstLeftoverTitle")}

+

{firstLeftoverCopy}

+
diff --git a/apps/desktop/src/features/workspace/firstLeftover.selected-role.test.ts b/apps/desktop/src/features/workspace/firstLeftover.selected-role.test.ts new file mode 100644 index 000000000..d200a77b2 --- /dev/null +++ b/apps/desktop/src/features/workspace/firstLeftover.selected-role.test.ts @@ -0,0 +1,51 @@ +import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types"; +import { describe, expect, it } from "vitest"; +import { firstLeftover } from "./firstLeftover"; + +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("firstLeftover selected-role search", () => { + it("keeps searching after the selected part newly drops out during an earlier partial return", () => { + 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, [ + "lead-vocal", + "keys-right" + ]), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, ["keys-right"]) + ] + }; + + expect(firstLeftover(song, "lead-vocal")).toEqual({ + sectionLabel: "bridge", + fromSectionLabel: "verse", + leftoverRoleId: "keys-right", + leftoverRoleName: "Keyboard 1 Right Hand" + }); + }); +}); diff --git a/apps/desktop/src/features/workspace/firstLeftover.test.ts b/apps/desktop/src/features/workspace/firstLeftover.test.ts new file mode 100644 index 000000000..4d3392f84 --- /dev/null +++ b/apps/desktop/src/features/workspace/firstLeftover.test.ts @@ -0,0 +1,355 @@ +import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types"; +import { describe, expect, it } from "vitest"; +import { fillRangeCopy } from "./firstRangeSqueeze"; +import { firstLeftover } from "./firstLeftover"; + +function withChorus(song: RehearsalSong): RehearsalSong { + const verse = song.sections[0]!; + const chorus = { + ...verse, + id: "chorus-1", + label: "chorus" as RehearsalSong["sections"][number]["label"], + timeRange: { + start: verse.timeRange.end, + end: verse.timeRange.end + 20 + } + }; + return { ...song, sections: [verse, chorus] }; +} + +function withPartialReturn( + song: RehearsalSong, + returningRoleId: string, + leftoverRoleId: string, + leftoverActive: boolean | "omit" = false +): RehearsalSong { + const twoSection = withChorus(song); + return { + ...twoSection, + sections: twoSection.sections.map((section, index) => ({ + ...section, + partGraph: section.partGraph.map((node) => { + if (index === 0) { + if (node.role_id === returningRoleId || node.role_id === leftoverRoleId) { + return { ...node, is_active: false }; + } + return node; + } + if (node.role_id === leftoverRoleId) { + if (leftoverActive === "omit") { + 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]; + } + return { ...node, is_active: leftoverActive }; + } + return node; + }) + })) + }; +} + +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 + }; +} + +describe("firstLeftover", () => { + it("returns null on the demo song where every graph node is active", () => { + expect(firstLeftover(createDemoRehearsalSong())).toBeNull(); + expect(firstLeftover(withChorus(createDemoRehearsalSong()))).toBeNull(); + }); + + it("names the leftover sit-out after a partial return", () => { + expect( + firstLeftover(withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right")) + ).toEqual({ + sectionLabel: "chorus", + fromSectionLabel: "verse", + leftoverRoleId: "keys-right", + leftoverRoleName: "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"], + true + ), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 40, ["keys-right"], true) + ] + }; + + expect(firstLeftover(song)).toEqual({ + sectionLabel: "chorus", + fromSectionLabel: "bridge", + leftoverRoleId: "keys-right", + leftoverRoleName: "Keyboard 1 Right Hand" + }); + }); + + it("treats repeated form labels as distinct timeline sections", () => { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right"); + song.sections[1] = { + ...song.sections[1]!, + label: song.sections[0]!.label + }; + + expect(firstLeftover(song)).toEqual({ + sectionLabel: "verse", + fromSectionLabel: "verse", + leftoverRoleId: "keys-right", + leftoverRoleName: "Keyboard 1 Right Hand" + }); + }); + + it("starts a new reduction baseline after the prior sit-outs fully return", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const song: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, ["lead-vocal"]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, []), + sectionWithInactiveRoles(template, "bridge-1", "bridge", 40, ["bass-guitar", "keys-right"]), + sectionWithInactiveRoles(template, "outro-1", "outro", 60, ["keys-right"]) + ] + }; + + expect(firstLeftover(song)).toEqual({ + sectionLabel: "outro", + fromSectionLabel: "bridge", + leftoverRoleId: "keys-right", + leftoverRoleName: "Keyboard 1 Right Hand" + }); + }); + + it("fails closed on contradictory duplicate graph identities", () => { + for (const reverse of [false, true]) { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right"); + const section = song.sections[1]!; + const keysNode = section.partGraph.find((node) => node.role_id === "keys-right")!; + const withoutKeys = section.partGraph.filter((node) => node.role_id !== "keys-right"); + const inactiveKeys = { ...keysNode, is_active: false }; + const activeKeys = { ...keysNode, is_active: true }; + song.sections[1] = { + ...section, + partGraph: [ + ...withoutKeys, + ...(reverse ? [activeKeys, inactiveKeys] : [inactiveKeys, activeKeys]) + ] + }; + + expect(firstLeftover(song)).toBeNull(); + } + }); + + it("skips blank leftover labels until a named partial return exists", () => { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right"); + song.sections[1] = { + ...song.sections[1]!, + label: "none" as RehearsalSong["sections"][number]["label"] + }; + expect(firstLeftover(song)).toBeNull(); + }); + + it("keeps the selected active part on tonight's first leftover", () => { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right"); + expect(firstLeftover(song, "keys-right")).toEqual({ + sectionLabel: "chorus", + fromSectionLabel: "verse", + leftoverRoleId: "keys-right", + leftoverRoleName: "Keyboard 1 Right Hand" + }); + expect(firstLeftover(song, "bass-guitar")).toEqual({ + sectionLabel: "chorus", + fromSectionLabel: "verse", + leftoverRoleId: "keys-right", + leftoverRoleName: "Keyboard 1 Right Hand" + }); + expect(firstLeftover(song, "missing-role")).toBeNull(); + }); + + it("keeps a selected inactive part from receiving a play instruction", () => { + const seed = createDemoRehearsalSong(); + const template = seed.sections[0]!; + const reduction = sectionWithInactiveRoles( + template, + "verse-1", + "verse", + 0, + ["bass-guitar", "lead-vocal", "keys-right"] + ); + const partial = sectionWithInactiveRoles( + template, + "chorus-1", + "chorus", + 20, + ["lead-vocal", "keys-right"] + ); + partial.partGraph = [ + ...partial.partGraph.filter((node) => node.role_id === "lead-vocal"), + ...partial.partGraph.filter( + (node) => node.role_id !== "lead-vocal" && node.role_id !== "keys-right" + ), + ...partial.partGraph.filter((node) => node.role_id === "keys-right") + ]; + const song: RehearsalSong = { ...seed, sections: [reduction, partial] }; + + expect(firstLeftover(song, "keys-right")).toEqual({ + sectionLabel: "chorus", + fromSectionLabel: "verse", + leftoverRoleId: "keys-right", + leftoverRoleName: "Keyboard 1 Right Hand" + }); + + const newDropout: RehearsalSong = { + ...seed, + sections: [ + sectionWithInactiveRoles(template, "verse-1", "verse", 0, ["bass-guitar", "keys-right"]), + sectionWithInactiveRoles(template, "chorus-1", "chorus", 20, ["lead-vocal", "keys-right"]) + ] + }; + expect(firstLeftover(newDropout, "lead-vocal")).toBeNull(); + }); + + it("ignores inherited is_active evidence", () => { + const song = withChorus(createDemoRehearsalSong()); + 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(firstLeftover(song)).toBeNull(); + }); + + it("does not treat a missing is_active flag as a leftover", () => { + expect( + firstLeftover(withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right", "omit")) + ).toBeNull(); + }); + + it("does not treat a continued sit-out with nobody returning as a leftover", () => { + const song = withChorus(createDemoRehearsalSong()); + song.sections = song.sections.map((section) => ({ + ...section, + partGraph: section.partGraph.map((node) => + node.role_id === "keys-right" ? { ...node, is_active: false } : node + ) + })); + expect(firstLeftover(song)).toBeNull(); + }); + + it("does not treat a full-band return as a leftover", () => { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right", true); + expect(firstLeftover(song)).toBeNull(); + }); + + it("does not treat a new dropout after every original sit-out returns as a leftover", () => { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right", true); + song.sections[1] = { + ...song.sections[1]!, + partGraph: song.sections[1]!.partGraph.map((node) => + node.role_id === "lead-vocal" ? { ...node, is_active: false } : node + ) + }; + expect(firstLeftover(song)).toBeNull(); + }); + + it("fails closed when the later section has no named leftover role", () => { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right"); + song.sections[1] = { + ...song.sections[1]!, + roles: song.sections[1]!.roles.map((role) => ({ ...role, name: " " })) + }; + expect(firstLeftover(song)).toBeNull(); + }); + + it("fails closed when the later section has no named graph", () => { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right"); + song.sections[1] = { + ...song.sections[1]!, + partGraph: [] + }; + expect(firstLeftover(song)).toBeNull(); + }); + + it("fails closed on malformed runtime roots", () => { + for (const malformed of [null, {}, { sections: {} }, { sections: [null] }]) { + expect(firstLeftover(malformed as unknown as RehearsalSong)).toBeNull(); + } + }); + + it("isolates blank role ids, non-boolean flags, and unnamed graph members", () => { + const song = withPartialReturn(createDemoRehearsalSong(), "bass-guitar", "keys-right"); + 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 + ] + }; + const inheritedId = Object.create({ id: "keys-right", name: "Inherited Keys" }); + song.sections[0] = { + ...song.sections[0]!, + roles: [inheritedId as RehearsalSong["sections"][number]["roles"][number], ...song.sections[0]!.roles] + }; + expect( + firstLeftover({ + ...song, + sections: [song.sections[0]!, { ...song.sections[1]!, roles: "broken" as unknown as RehearsalSong["sections"][number]["roles"] }] + }) + ).toBeNull(); + expect(firstLeftover({ ...song, sections: [song.sections[0]!, { ...song.sections[1]!, partGraph: null }] })).toBeNull(); + }); +}); + +describe("leftover copy filling", () => { + it("keeps rehearsal values literal", () => { + expect( + fillRangeCopy("{leftoverRoleName} stays tacet in {sectionLabel} after {fromSectionLabel}.", { + leftoverRoleName: "Keyboard 1 Right Hand {sectionLabel}", + sectionLabel: "chorus", + fromSectionLabel: "verse" + }) + ).toBe("Keyboard 1 Right Hand {sectionLabel} stays tacet in chorus after verse."); + }); +}); diff --git a/apps/desktop/src/features/workspace/firstLeftover.ts b/apps/desktop/src/features/workspace/firstLeftover.ts new file mode 100644 index 000000000..312c66c61 --- /dev/null +++ b/apps/desktop/src/features/workspace/firstLeftover.ts @@ -0,0 +1,220 @@ +import type { RehearsalSong } from "@bandscope/shared-types"; +import { meaningfulRangeText } from "./firstRangeSqueeze"; + +/** Tonight's first named leftover sit-out after a partial return. */ +export type FirstLeftover = { + sectionLabel: string; + fromSectionLabel: string; + leftoverRoleId: string; + leftoverRoleName: 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 role keep + * its trustworthy display name across sections without treating inherited, + * blank, duplicate, or contradictory metadata as authority. + */ +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 one part can never satisfy both the returning and leftover sides of + * the same transition. + */ +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; +} + +/** + * Pick the first leftover sit-out a player should honor after others return. + * + * Uses song-wide role identity plus complete `partGraph` activity evidence. A + * leftover 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 complete + * return closes that cohort; a new sit-out in the same or a later section can + * establish the next reduction baseline. Section labels remain display data, + * so repeated form labels never collapse distinct timeline positions. + * + * Inherited/missing activity, incomplete or contradictory graphs, unnamed + * roles, and malformed runtime data fail closed. When a role is selected, a + * selected inactive part is shown only when it is itself a leftover from the + * tracked reduced cohort, so the workspace never tells a silent part to play. + */ +export function firstLeftover( + song: RehearsalSong | unknown, + activeRole: string | null = null +): FirstLeftover | 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; + + 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 (!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) { + let leftover = leftovers[0]!; + if (activeRole) { + const activeRoleNode = nodes.find((node) => node.roleId === activeRole)!; + if (!activeRoleNode.active) { + const selectedLeftover = leftovers.find((node) => node.roleId === activeRole); + if (!selectedLeftover) { + continue; + } + leftover = selectedLeftover; + } + } + return { + sectionLabel, + fromSectionLabel: reducedFrom, + leftoverRoleId: leftover.roleId, + leftoverRoleName: namedRoles.get(leftover.roleId)! + }; + } + + 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..dbbd7d1f4 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("workspaceFirstLeftoverTitle")).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..6af5075b8 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.", + "workspaceFirstLeftoverTitle": "Tonight's first leftover sit-out", + "workspaceFirstLeftoverNamed": "{leftoverRoleName} stays tacet in {sectionLabel} after {fromSectionLabel}. Play {sectionLabel} without waiting for {leftoverRoleName}.", + "workspaceFirstLeftoverStayOut": "{leftoverRoleName} stays tacet in {sectionLabel} after {fromSectionLabel}. Stay out of {sectionLabel}.", + "workspaceFirstLeftoverMissing": "Tonight's first leftover sit-out still needs a named part that stays out after others return. Confirm who stays tacet 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..c6bf81c1b 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": "오늘 먼저 볼 음역은 아직 귀로 확인이 필요합니다. 선택한 파트의 최저·최고음을 첫 구간 전에 확인해 보세요.", + "workspaceFirstLeftoverTitle": "오늘 먼저 남을 쉬는 자리", + "workspaceFirstLeftoverNamed": "{leftoverRoleName}은 {fromSectionLabel} 다음 {sectionLabel}에서 그대로 쉽니다. 그 파트를 기다리지 말고 {sectionLabel}부터 연주하세요.", + "workspaceFirstLeftoverStayOut": "{leftoverRoleName}은 {fromSectionLabel} 다음 {sectionLabel}에서 그대로 쉽니다. {sectionLabel}에는 들어오지 마세요.", + "workspaceFirstLeftoverMissing": "오늘 먼저 남을 쉬는 자리는 아직 확인이 필요합니다. 다른 파트가 돌아온 뒤에도 쉬는 파트를 첫 구간 전에 확인하세요.", "sectionRangeLabel": "음역", "sectionRangeNextAction": "{sectionLabel} 들어가기 전에 이 음역을 악기로 확인해 보세요." } diff --git a/docs/design-system/component-contract.md b/docs/design-system/component-contract.md index 22602c313..c755d9004 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 leftover sit-out 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-leftover.md b/docs/doctoring/first-leftover.md new file mode 100644 index 000000000..eaecc2895 --- /dev/null +++ b/docs/doctoring/first-leftover.md @@ -0,0 +1,18 @@ +# Tonight's first leftover sit-out + +The ready rehearsal map names the first leftover sit-out from existing `partGraph` evidence: a named section where at least one previously sitting-out named part is own-property active and at least one previously sitting-out named part is still own-property tacet. This is where the returning parts should play without waiting, and the leftover part should stay out. It is not a come-in, tacet, dropout, tutti, handoff, Fine, last-line breath, a continued sit-out with nobody returning, or a new dropout after every original sit-out returns. + +## Next action + +- Named returning part: play the named section without waiting for the leftover part. +- Named leftover part: stay tacet through the named section after the reduced earlier section. +- Missing: confirm who stays tacet after others 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 sit-out on a named section followed by a later named section with a partial return and a leftover sit-out. +- Allowlist: section labels and role names must be meaningful text. A missing graph node is not a leftover. Inherited `is_active` is isolated. Same-section false-then-true nodes are not a return. All-active later sections are tuttis, not leftovers. Continued sit-outs with nobody returning are not leftovers. A new dropout after every original sit-out returns is a dropout, not a leftover. When a role is selected, only a leftover section that includes that named part is shown. +- Safe failure: inherited flags, blank labels, missing names, 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 leftover. +- Logging/privacy: rejected or accepted leftovers are not logged. Copy interpolation keeps rehearsal values literal. +- Tests: `firstLeftover.test.ts` and the Workspace callout cover the demo all-active case, an explicit bass return with keys leftover, selected-role scoping, inherited flags, missing `is_active`, continued sit-outs, full-band returns, new dropouts after a full original return, unnamed roles, empty graphs, and literal copy filling.