feat: implement V2 Advanced Rehearsal Collaboration Features

apps/desktop/package.json

@@ -17,6 +17,7 @@
     "@tauri-apps/api": "^2.8.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "jszip": "^3.10.1",
     "lucide-react": "^1.11.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.5",

apps/desktop/src/App.test.tsx

@@ -1,6 +1,7 @@
 import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { App } from "./App";
+import { type RehearsalSong } from "@bandscope/shared-types";
 
 const tauriInvoke = vi.fn();
 const mockLoadProject = vi.fn();
@@ -28,6 +29,21 @@ vi.mock("./lib/analysis", async (importActual) => {
   };
 });
 
+
+function wrapInWorkspace(song: RehearsalSong) {
+  return {
+    id: "ws-test",
+    title: song.title || "Untitled",
+    workspaceVersion: 1,
+    songs: [{
+      id: "pack-test",
+      packState: "ready",
+      song: song,
+      sourceLabel: "Test Source"
+    }]
+  };
+}
+
 function succeededResult() {
   return {
     jobId: "job-1",
@@ -186,7 +202,7 @@ describe("App", () => {
   });
 
   it("renders the loaded song as a dark rehearsal command board", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /open project/i }));
@@ -201,7 +217,7 @@ describe("App", () => {
   });
 
   it("renders a rehearsal song structure timeline from real section ranges", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /open project/i }));
@@ -219,7 +235,7 @@ describe("App", () => {
   });
 
   it("does not show unavailable analysis metrics as detected facts", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /open project/i }));
@@ -244,7 +260,7 @@ describe("App", () => {
       label: "chorus",
       confidence: { level: "high", source: "model", notes: "The chorus form is clear." }
     });
-    mockLoadProject.mockResolvedValueOnce(loadedProject);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(loadedProject));
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /open project/i }));
@@ -660,7 +676,7 @@ describe("App", () => {
 
 
   it("loads a project and updates the UI", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /open project/i }));
@@ -723,7 +739,7 @@ describe("App", () => {
   });
 
   it("saves a project successfully", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     // Load first to get jobResult populated
@@ -738,12 +754,23 @@ describe("App", () => {
     fireEvent.click(screen.getByRole("button", { name: /save project/i }));
 
     await waitFor(() => {
-      expect(mockSaveProject).toHaveBeenCalledWith(succeededResult().result);
+      expect(mockSaveProject).toHaveBeenCalledWith(
+        expect.objectContaining({
+          id: expect.any(String),
+          title: expect.any(String),
+          workspaceVersion: 1,
+          songs: expect.arrayContaining([
+            expect.objectContaining({
+              song: succeededResult().result
+            })
+          ])
+        })
+      );
     });
   });
 
   it("handles saving a project failure gracefully", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     // Load first to get jobResult populated
@@ -763,7 +790,7 @@ describe("App", () => {
   });
 
   it("ignores cancellation when saving a project with Error object", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     // Load first to get jobResult populated
@@ -786,7 +813,7 @@ describe("App", () => {
   });
 
   it("handles saving a project failure with string error gracefully", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     // Load first to get jobResult populated
@@ -806,7 +833,7 @@ describe("App", () => {
   });
 
   it("ignores cancellation when saving a project with string error", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     // Load first to get jobResult populated
@@ -829,7 +856,7 @@ describe("App", () => {
   });
 
   it("handles song update from workspace", async () => {
-    mockLoadProject.mockResolvedValueOnce(succeededResult().result);
+    mockLoadProject.mockResolvedValueOnce(wrapInWorkspace(succeededResult().result));
     render(<App />);
 
     // Load first to get jobResult populated

apps/desktop/src/App.tsx

@@ -26,7 +26,8 @@ import {
   type AnalysisJobRequest,
   type AnalysisJobStatus,
   type ProjectBootstrapSummary,
-  type RehearsalSong
+  type RehearsalSong,
+  type RehearsalWorkspace
 } from "@bandscope/shared-types";
 import {
   createDefaultAnalysisRequest,
@@ -145,7 +146,7 @@ export function App() {
   const t = useMemo(() => createTranslator(detectPreferredLocale()), []);
   const defaultRequest = useMemo(() => createDefaultAnalysisRequest(), []);
   const [jobStatus, setJobStatus] = useState<AnalysisJobStatus | null>(null);
-  const [jobResult, setJobResult] = useState<RehearsalSong | null>(null);
+  const [jobResult, setJobResult] = useState<RehearsalWorkspace | null>(null);
   const [jobError, setJobError] = useState<string | null>(null);
   const [isStarting, setIsStarting] = useState(false);
   const [selectedBootstrap, setSelectedBootstrap] = useState<ProjectBootstrapSummary | null>(null);
@@ -173,7 +174,18 @@ export function App() {
         const nextStatus = await getAnalysisJobStatus(jobStatus.jobId);
         setJobStatus(nextStatus);
         if (nextStatus.state === "succeeded" && nextStatus.result) {
-          setJobResult(nextStatus.result);
+          const workspace: RehearsalWorkspace = {
+            id: "ws-" + Date.now(),
+            title: nextStatus.result.title || "Untitled",
+            workspaceVersion: 1,
+            songs: [{
+              id: "pack-" + Date.now(),
+              packState: "ready",
+              song: nextStatus.result,
+              sourceLabel: selectedRequest.sourceLabel
+            }]
+          };
+          setJobResult(workspace);
           setJobError(null);
         }
         if (nextStatus.state === "failed") {
@@ -220,7 +232,18 @@ export function App() {
       const nextStatus = await startAnalysisJob(selectedRequest);
       setJobStatus(nextStatus);
       if (nextStatus.state === "succeeded" && nextStatus.result) {
-        setJobResult(nextStatus.result);
+        const workspace: RehearsalWorkspace = {
+            id: "ws-" + Date.now(),
+            title: nextStatus.result.title || "Untitled",
+            workspaceVersion: 1,
+            songs: [{
+              id: "pack-" + Date.now(),
+              packState: "ready",
+              song: nextStatus.result,
+              sourceLabel: selectedRequest.sourceLabel
+            }]
+        };
+        setJobResult(workspace);
       }
       if (nextStatus.state === "failed") {
         setJobError(nextStatus.error?.message ?? t("analysisCouldNotStart"));
@@ -280,8 +303,8 @@ export function App() {
   /** Documented. */
   const handleLoadProject = async () => {
     try {
-      const song = await loadProject();
-      setJobResult(song);
+      const workspace = await loadProject();
+      setJobResult(workspace);
       setJobError(null);
       setSelectedBootstrap(null);
       setJobStatus(null);
@@ -309,7 +332,16 @@ export function App() {
 
   /** Documented. */
   const handleSongUpdate = (updatedSong: RehearsalSong) => {
-    setJobResult(updatedSong);
+    if (jobResult) {
+      setJobResult({
+        ...jobResult,
+        songs: jobResult.songs.map(p => 
+          p.packState === "ready" && p.song.id === updatedSong.id 
+            ? { ...p, song: updatedSong } 
+            : p
+        )
+      });
+    }
   };
 
   /** Documented. */
@@ -320,8 +352,16 @@ export function App() {
     if (analysisInFlight || isStarting) {
       return <LoadingState />;
     }
-    if (jobResult) {
-      return <Workspace song={jobResult} onSongUpdate={handleSongUpdate} />;
+    if (jobResult && jobResult.songs.length > 0) {
+      const firstReady = jobResult.songs.find(p => p.packState === "ready");
+      if (firstReady && firstReady.packState === "ready") {
+        return (
+          <Workspace
+            song={firstReady.song}
+            onSongUpdate={handleSongUpdate}
+          />
+        );
+      }
     }
     return <EmptyState />;
   };
@@ -423,27 +463,33 @@ export function App() {
             ))}
           </nav>
 
-          <header className="mb-4 grid gap-3 md:grid-cols-2 xl:grid-cols-5">
-            <MetricCard icon={<Clock3 className="size-5" aria-hidden="true" />} label="Tempo" value="Pending" detail="Awaiting reliable detection" accent="text-sky-300" />
-            <MetricCard icon={<KeyRound className="size-5" aria-hidden="true" />} label="Key" value="Pending" detail="No trusted key yet" accent="text-cyan-300" />
-            <MetricCard icon={<Wand2 className="size-5" aria-hidden="true" />} label="Transpose" value="Pending" detail="Review after key detection" accent="text-blue-300" />
-            <ConfidenceMetric song={jobResult} />
-            <MetricCard icon={<Star className="size-5 fill-amber-300 text-amber-300" aria-hidden="true" />} label="Priority" value={priorityLabel(jobResult)} detail={jobResult?.exportSummary?.headline ?? "Choose or open audio"} accent="text-amber-300" />
-          </header>
-
-          <section aria-label="Source controls" className="mb-4 rounded-3xl border border-white/10 bg-slate-950/72 p-4 shadow-[0_18px_60px_rgba(0,0,0,0.25)] backdrop-blur-xl">
-            <div className="grid gap-4 2xl:grid-cols-[1.4fr_minmax(0,1fr)_auto] 2xl:items-center">
-              <div>
-                <p className="text-xs font-semibold uppercase tracking-[0.26em] text-cyan-300">
-                  {jobResult ? "READY • REHEARSAL" : "SYNCED • LOCAL"}
-                </p>
-                <h1 className="mt-2 text-3xl font-black tracking-tight text-white sm:text-4xl">
-                  {jobResult ? "Rehearsal Console" : "Workspace Home"}
-                </h1>
-                <p className="mt-2 max-w-2xl text-sm leading-6 text-slate-400">
-                  {jobResult?.exportSummary?.headline ?? "Turn a song into a practical rehearsal view."}
-                </p>
-              </div>
+          {(() => {
+            const firstReadyPack = jobResult?.songs.find(p => p.packState === "ready");
+            const firstReadySong = firstReadyPack && firstReadyPack.packState === "ready" ? firstReadyPack.song : null;
+
+            return (
+              <>
+                <header className="mb-4 grid gap-3 md:grid-cols-2 xl:grid-cols-5">
+                  <MetricCard icon={<Clock3 className="size-5" aria-hidden="true" />} label="Tempo" value="Pending" detail="Awaiting reliable detection" accent="text-sky-300" />
+                  <MetricCard icon={<KeyRound className="size-5" aria-hidden="true" />} label="Key" value="Pending" detail="No trusted key yet" accent="text-cyan-300" />
+                  <MetricCard icon={<Wand2 className="size-5" aria-hidden="true" />} label="Transpose" value="Pending" detail="Review after key detection" accent="text-blue-300" />
+                  <ConfidenceMetric song={firstReadySong} />
+                  <MetricCard icon={<Star className="size-5 fill-amber-300 text-amber-300" aria-hidden="true" />} label="Priority" value={priorityLabel(firstReadySong)} detail={firstReadySong?.exportSummary?.headline ?? "Choose or open audio"} accent="text-amber-300" />
+                </header>
+
+                <section aria-label="Source controls" className="mb-4 rounded-3xl border border-white/10 bg-slate-950/72 p-4 shadow-[0_18px_60px_rgba(0,0,0,0.25)] backdrop-blur-xl">
+                  <div className="grid gap-4 2xl:grid-cols-[1.4fr_minmax(0,1fr)_auto] 2xl:items-center">
+                    <div>
+                      <p className="text-xs font-semibold uppercase tracking-[0.26em] text-cyan-300">
+                        {jobResult ? "READY • REHEARSAL" : "SYNCED • LOCAL"}
+                      </p>
+                      <h1 className="mt-2 text-3xl font-black tracking-tight text-white sm:text-4xl">
+                        {jobResult ? "Rehearsal Console" : "Workspace Home"}
+                      </h1>
+                      <p className="mt-2 max-w-2xl text-sm leading-6 text-slate-400">
+                        {firstReadySong?.exportSummary?.headline ?? "Turn a song into a practical rehearsal view."}
+                      </p>
+                    </div>
 
               <div className="grid min-w-0 gap-3 sm:grid-cols-[auto_1fr_auto] sm:items-center 2xl:grid-cols-[auto_1fr]">
                 <Button
@@ -547,6 +593,9 @@ export function App() {
               </div>
             </div>
           </section>
+              </>
+            );
+          })()}
 
           <section className="animate-in fade-in duration-500 ease-out fill-mode-both">
             {renderWorkspaceState()}

apps/desktop/src/lib/analysis.ts

@@ -7,12 +7,12 @@ import {
   parseAnalysisJobStatus,
   parseAnalysisJobRequest,
   parseProjectBootstrapSummary,
-  parseRehearsalSong,
+  parseRehearsalWorkspace,
   type AnalysisJobError,
   type AnalysisJobRequest,
   type AnalysisJobStatus,
   type ProjectBootstrapSummary,
-  type RehearsalSong
+  type RehearsalWorkspace
 } from "@bandscope/shared-types";
 
 type TauriInvoke = (command: string, args?: Record<string, unknown>) => Promise<unknown>;
@@ -275,13 +275,13 @@ export async function importYoutubeUrl(url: string): Promise<LocalAudioSelection
 }
 
 /** Documented. */
-export async function saveProject(song: RehearsalSong): Promise<void> {
-  const parsedSong = parseRehearsalSong(song);
-  await invokeAnalysis("save_project", { payload: parsedSong });
+export async function saveProject(workspace: RehearsalWorkspace): Promise<void> {
+  const parsedWorkspace = parseRehearsalWorkspace(workspace);
+  await invokeAnalysis("save_project", { payload: parsedWorkspace });
 }
 
 /** Documented. */
-export async function loadProject(): Promise<RehearsalSong> {
+export async function loadProject(): Promise<RehearsalWorkspace> {
   const response = await invokeAnalysis("load_project");
-  return parseRehearsalSong(response);
+  return parseRehearsalWorkspace(response);
 }

apps/desktop/src/lib/annotations.ts

@@ -0,0 +1,31 @@
+import { Annotation } from "@bandscope/shared-types";
+
+/**
+ * Merges two arrays of annotations, keeping unique ones and sorting by timestamp.
+ * 
+ * @param existing - The existing annotations.
+ * @param incoming - The incoming annotations.
+ * @returns The merged annotations array.
+ */
+export function mergeAnnotations(existing: Annotation[] = [], incoming: Annotation[] = []): Annotation[] {
+  const merged = [...existing];
+  const existingIds = new Set(existing.map((a) => a.id));
+
+  for (const ann of incoming) {
+    if (!existingIds.has(ann.id)) {
+      merged.push(ann);
+      existingIds.add(ann.id);
+    }
+  }
+
+  const mergedWithIndex = merged.map((item, index) => ({ item, index }));
+  mergedWithIndex.sort((a, b) => {
+    const ta = Date.parse(a.item.timestamp);
+    const tb = Date.parse(b.item.timestamp);
+    const tsa = Number.isFinite(ta) ? ta : 0;
+    const tsb = Number.isFinite(tb) ? tb : 0;
+    if (tsa !== tsb) return tsa - tsb;
+    return a.index - b.index;
+  });
+  return mergedWithIndex.map(x => x.item);
+}