feat(workspace): tap a session tempo when the song has none

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, a session tap tempo when the song has no trusted BPM, 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.

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # ARCHITECTURE.md
 
-Last updated: 2026-03-11
+Last updated: 2026-08-30
 
 ## Brand source
 
@@ -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, a session tap tempo when the song has no trusted BPM, 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

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Measure tonight's count-in tempo from at least four player taps when the song has no trusted BPM, then count in at that tempo and check the first range.
 - Name tonight's first playable range on the ready rehearsal map and tell the player to check that span on their instrument before the section.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.

CLAUDE.md

@@ -51,7 +51,7 @@ BandScope is a local-first desktop app for rehearsal prep: it turns a song into
 
 Three layers, decoupled through shared contracts:
 
-- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). The ready workspace names tonight's first playable range and the next instrument check. `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands, with a browser fallback that serves demo data when not running inside Tauri.
+- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). The ready workspace names tonight's first playable range, offers a session tap tempo when the song has no trusted BPM, and names 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.
 

apps/desktop/src/features/workspace/TapTempo.test.tsx

@@ -0,0 +1,47 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { createTranslator } from "../../i18n";
+import { TapTempo } from "./TapTempoPanel";
+
+const t = createTranslator("en");
+
+describe("TapTempo", () => {
+  it("names the tap next action and unlocks a 120 BPM count-in after four steady taps", () => {
+    let now = 10_000;
+    render(<TapTempo t={t} nowMs={() => now} />);
+
+    const region = screen.getByTestId("tap-tempo");
+    expect(region).toHaveTextContent("Tonight's tap tempo");
+    expect(region).toHaveTextContent(
+      "Tonight's first count-in still needs a tempo. Tap a steady groove at least four times, then count in at that tempo and check the first range."
+    );
+
+    const tap = screen.getByRole("button", { name: /tap the groove to set tonight's tempo/i });
+    fireEvent.click(tap);
+    now += 500;
+    fireEvent.click(tap);
+    expect(region).toHaveTextContent("Keep tapping a steady groove");
+    now += 500;
+    fireEvent.click(tap);
+    now += 500;
+    fireEvent.click(tap);
+
+    expect(region).toHaveTextContent("120 BPM from 4 taps. Count in 4 at 120 BPM, then check tonight's first range.");
+    expect(screen.getByTestId("tap-lamp-0").className).toContain("bg-amber-300");
+    expect(screen.getByTestId("tap-lamp-3").className).toContain("bg-amber-300");
+  });
+
+  it("resets the session taps without writing a song tempo", () => {
+    let now = 1_000;
+    render(<TapTempo t={t} nowMs={() => now} />);
+    const tap = screen.getByRole("button", { name: /tap the groove to set tonight's tempo/i });
+    fireEvent.click(tap);
+    now += 500;
+    fireEvent.click(tap);
+    fireEvent.click(screen.getByRole("button", { name: /reset tonight's tap tempo/i }));
+    expect(screen.getByTestId("tap-tempo")).toHaveTextContent(
+      "Tonight's first count-in still needs a tempo. Tap a steady groove at least four times, then count in at that tempo and check the first range."
+    );
+    expect(screen.getByRole("button", { name: /reset tonight's tap tempo/i })).toBeDisabled();
+  });
+});

apps/desktop/src/features/workspace/TapTempoPanel.tsx

@@ -0,0 +1,88 @@
+import { useMemo, useState } from "react";
+import { CircleDot } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { createTranslator } from "../../i18n";
+import {
+  emptyTapTempo,
+  fillTapCopy,
+  MIN_TAP_COUNT,
+  recordTap,
+  tapTempoReading,
+  type TapTempoState
+} from "./tapTempo";
+
+type Translator = ReturnType<typeof createTranslator>;
+
+interface TapTempoProps {
+  t: Translator;
+  nowMs?: () => number;
+}
+
+/**
+ * Measure tonight's count-in tempo from the player's taps when the song
+ * has no trusted BPM. Session-only; this does not write `song.tempo`.
+ */
+export function TapTempo({ t, nowMs }: TapTempoProps) {
+  const [state, setState] = useState<TapTempoState>(emptyTapTempo);
+  const reading = useMemo(() => tapTempoReading(state), [state]);
+  const clock = nowMs ?? Date.now;
+
+  const guidance = reading
+    ? fillTapCopy(t("workspaceTapTempoReady"), {
+        tempo: String(reading.tempoBpm),
+        taps: String(reading.tapCount)
+      })
+    : state.tapsMs.length > 0
+      ? t("workspaceTapTempoKeep")
+      : t("workspaceTapTempoNeed");
+
+  const filledLamps = Math.min(state.tapsMs.length, MIN_TAP_COUNT);
+
+  return (
+    <section
+      className="rounded-2xl border border-amber-300/20 bg-amber-300/[0.07] p-4"
+      data-testid="tap-tempo"
+      aria-label={t("workspaceTapTempoTitle")}
+    >
+      <p className="text-xs font-black uppercase tracking-[0.24em] text-amber-200">{t("workspaceTapTempoTitle")}</p>
+      <p className="mt-2 text-sm leading-6 text-slate-100">{guidance}</p>
+      <div className="mt-3 flex gap-2" aria-hidden="true">
+        {Array.from({ length: MIN_TAP_COUNT }, (_, index) => (
+          <span
+            key={index}
+            data-testid={`tap-lamp-${index}`}
+            className={
+              "size-3 rounded-full " +
+              (index < filledLamps ? "bg-amber-300" : "bg-white/15")
+            }
+          />
+        ))}
+      </div>
+      <div className="mt-3 flex flex-wrap gap-2">
+        <Button
+          type="button"
+          onClick={() => {
+            setState((current) => recordTap(current, clock()));
+          }}
+          aria-label={t("workspaceTapTempoActionLabel")}
+          className="min-h-11 border-amber-300/30 bg-amber-300/15 font-semibold text-amber-50 hover:bg-amber-300/25 hover:text-white"
+        >
+          <CircleDot className="mr-2 size-4 text-amber-200" aria-hidden="true" />
+          {t("workspaceTapTempoAction")}
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          onClick={() => {
+            setState(emptyTapTempo());
+          }}
+          disabled={state.tapsMs.length === 0}
+          aria-label={t("workspaceTapTempoResetLabel")}
+          className="min-h-11 border-white/10 bg-white/5 font-semibold text-slate-100"
+        >
+          {t("workspaceTapTempoReset")}
+        </Button>
+      </div>
+    </section>
+  );
+}

apps/desktop/src/features/workspace/Workspace.tap-tempo-session.test.tsx

@@ -0,0 +1,70 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { Workspace } from "./Workspace";
+
+function EditableWorkspace({ initialSong }: { initialSong: RehearsalSong }) {
+  const [song, setSong] = useState(initialSong);
+  return <Workspace song={song} onSongUpdate={setSong} />;
+}
+
+describe("Workspace tap-tempo session ownership", () => {
+  it("resets session taps when a different tempo-less song replaces a same-id analysis result", () => {
+    const firstSong = createDemoRehearsalSong();
+    firstSong.tempo = undefined;
+    firstSong.title = "First room song";
+
+    const nextSong = createDemoRehearsalSong();
+    nextSong.tempo = undefined;
+    nextSong.title = "Second room song";
+    expect(nextSong.id).toBe(firstSong.id);
+
+    const { rerender } = render(<Workspace song={firstSong} />);
+    fireEvent.click(screen.getByRole("button", { name: /tap the groove to set tonight's tempo/i }));
+    expect(screen.getByTestId("tap-lamp-0").className).toContain("bg-amber-300");
+
+    rerender(<Workspace song={nextSong} />);
+
+    expect(screen.getByTestId("tap-lamp-0").className).toContain("bg-white/15");
+    expect(screen.getByRole("button", { name: /reset tonight's tap tempo/i })).toBeDisabled();
+  });
+
+  it("resets session taps when a distinct loaded song collides on projected identity", () => {
+    const firstSong = createDemoRehearsalSong();
+    firstSong.tempo = undefined;
+    const nextSong = structuredClone(firstSong);
+    nextSong.sections[0]!.roles[0]!.harmony.chord = `${nextSong.sections[0]!.roles[0]!.harmony.chord}sus4`;
+
+    expect(nextSong.id).toBe(firstSong.id);
+    expect(nextSong.title).toBe(firstSong.title);
+    expect(nextSong.sections.map(({ id, timeRange }) => ({ id, timeRange }))).toEqual(
+      firstSong.sections.map(({ id, timeRange }) => ({ id, timeRange }))
+    );
+
+    const { rerender } = render(<Workspace song={firstSong} />);
+    fireEvent.click(screen.getByRole("button", { name: /tap the groove to set tonight's tempo/i }));
+    expect(screen.getByTestId("tap-lamp-0").className).toContain("bg-amber-300");
+
+    rerender(<Workspace song={nextSong} />);
+
+    expect(screen.getByTestId("tap-lamp-0").className).toContain("bg-white/15");
+    expect(screen.getByRole("button", { name: /reset tonight's tap tempo/i })).toBeDisabled();
+  });
+
+  it("preserves session taps when the supported chord editor updates the current song", () => {
+    const song = createDemoRehearsalSong();
+    song.tempo = undefined;
+    const prompt = vi.spyOn(window, "prompt").mockReturnValue("Dm7");
+
+    render(<EditableWorkspace initialSong={song} />);
+    fireEvent.click(screen.getByRole("button", { name: /tap the groove to set tonight's tempo/i }));
+    expect(screen.getByTestId("tap-lamp-0").className).toContain("bg-amber-300");
+
+    fireEvent.click(screen.getAllByRole("button", { name: /edit chord for/i })[0]!);
+
+    expect(prompt).toHaveBeenCalled();
+    expect(screen.getByTestId("tap-lamp-0").className).toContain("bg-amber-300");
+    prompt.mockRestore();
+  });
+});

apps/desktop/src/features/workspace/Workspace.test.tsx

@@ -153,6 +153,26 @@ describe("Workspace", () => {
     );
   });
 
+  it("offers a tap tempo when the song has no trusted BPM", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.tempo = undefined;
+
+    render(<Workspace song={song} />);
+
+    const callout = screen.getByTestId("tap-tempo");
+    expect(callout).toHaveTextContent("Tonight's tap tempo");
+    expect(callout).toHaveTextContent(
+      "Tonight's first count-in still needs a tempo. Tap a steady groove at least four times, then count in at that tempo and check the first range."
+    );
+  });
+
+  it("hides tap tempo when the song already has a trusted BPM", () => {
+    setNavigatorLanguage("en-US");
+    render(<Workspace song={createDemoRehearsalSong()} />);
+    expect(screen.queryByTestId("tap-tempo")).toBeNull();
+  });
+
   it("asks for an ear check when the selected part has no named span", () => {
     setNavigatorLanguage("en-US");
     const song = createDemoRehearsalSong();

apps/desktop/src/features/workspace/Workspace.tsx

@@ -5,6 +5,8 @@ import { SectionRoadmap } from "./SectionRoadmap";
 import { GrooveMap } from "./GrooveMap";
 import { PracticeProgress } from "./PracticeProgress";
 import { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze";
+import { TapTempo } from "./TapTempoPanel";
+import { inheritTapTempoSession, songNeedsTapTempo, tapTempoSessionKey } from "./tapTempo";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
@@ -123,6 +125,13 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
   const [activeRole, setActiveRole] = useState<string | null>(null);
   const t = useMemo(() => createTranslator(detectPreferredLocale()), []);
 
+  /** Preserve tap-session ownership only for updates emitted by this mounted workspace. */
+  const forwardSongUpdate = (updatedSong: RehearsalSong) => {
+    if (!onSongUpdate) return;
+    inheritTapTempoSession(song, updatedSong);
+    onSongUpdate(updatedSong);
+  };
+
   // Extract all unique roles from the song's sections
   const roleMap = useMemo(() => {
     const map = new Map<string, RehearsalRole>();
@@ -188,7 +197,7 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
       })
     };
 
-    onSongUpdate(nextSong);
+    forwardSongUpdate(nextSong);
   };
   const collaborationAssignments = useMemo(
     () => (Array.isArray(song.collaboration?.assignments) ? song.collaboration.assignments : []),
@@ -309,6 +318,7 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
             <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>
+          {songNeedsTapTempo(song) ? <TapTempo key={tapTempoSessionKey(song)} t={t} /> : null}
 
           <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">
@@ -505,7 +515,7 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
           <SectionRoadmap
             song={song}
             activeRole={activeRole}
-            onSongUpdate={onSongUpdate}
+            onSongUpdate={onSongUpdate ? forwardSongUpdate : undefined}
           />
           </section>
         </CardContent>