feat(activation): license a demo song and name first-run next actions

AGENTS.md

@@ -98,3 +98,4 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 - Do not justify risky debug defaults as temporary shortcuts.
 - Do not defer dependency review, SBOM generation, or supply-chain checks to a later phase.
 - Do not defer Windows or macOS build enforcement to a later phase.
+- The licensed demo is original CC0 audio that must pass the same local-audio intake as a user-selected file. Never present mocked browser success as production analysis.

ARCHITECTURE.md

@@ -113,6 +113,7 @@ Last updated: 2026-03-11
 - The current shared-types baseline includes a rehearsal-domain fixture that exercises section, role, cue, confidence, provenance, and export-summary fields in the desktop shell before the full analysis pipeline lands.
 - Local analysis orchestration uses typed Tauri IPC commands and a Python subprocess over stdin/stdout rather than a loopback HTTP listener.
 - Local audio intake bootstraps a project by validating a user-selected file in Rust, creating app-owned temp/cache/project roots, and referencing the original source file rather than copying it in this phase.
+- First-run empty workspace names **Try the demo** and **Use my own song**. The licensed demo is the CC0 `Late Night Set` package under `apps/desktop/src-tauri/resources/demo/` and enters through `select_demo_audio_source`, which reuses the same bootstrap as a user-selected local file.
 - Those bootstrap roots should resolve from app-owned Tauri data/cache paths instead of the shared system temp namespace.
 - Product and UX decisions should prefer rehearsal-first simplicity while still maintaining high analytical accuracy.
 - Security decisions should prefer allowlisted narrow capabilities over generic convenience APIs.

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- First-run empty workspace offers **Try the demo** and **Use my own song**, with a CC0 licensed `Late Night Set` package that uses the same local-audio intake as a user-selected file (#964).
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 

CLAUDE.md

@@ -51,8 +51,8 @@ BandScope is a local-first desktop app for rehearsal prep: it turns a song into
 
 Three layers, decoupled through shared contracts:
 
-- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands, with a browser fallback that serves demo data when not running inside Tauri.
-- `apps/desktop/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.
+- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands. Without the desktop IPC bridge, analysis fails closed instead of synthesizing a production success; bundled licensed-demo intake is desktop-only and also fails closed in the browser.
+- `apps/desktop/src-tauri/src/main.rs` — the Rust orchestration boundary. Tauri commands (`start_analysis_job`, `get_analysis_job_status`, `select_local_audio_source`, `select_demo_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.
 
 Data flow: React UI → Tauri IPC command → Rust validation + Python subprocess over stdin/stdout → job status and progress events emitted back to the UI.

apps/desktop/core/src/lib.rs

@@ -40,6 +40,17 @@ pub const ANALYSIS_WAIT_POLL: Duration = Duration::from_millis(50);
 
 pub const AUDIO_EXTENSIONS: [&str; 4] = ["wav", "mp3", "flac", "m4a"];
 
+pub const DEMO_AUDIO_FILE_NAME: &str = "late-night-set.wav";
+
+pub const DEMO_AUDIO_BYTES: u64 = 88244;
+
+pub const DEMO_UNAVAILABLE_MESSAGE: &str =
+    "The licensed demo song could not be loaded. Use your own song to start tonight.";
+
+const WAV_RIFF_MAGIC: &[u8] = b"RIFF";
+
+const WAV_WAVE_MAGIC: &[u8] = b"WAVE";
+
 pub const MISSING_ANALYSIS_PYTHON: &str = "__bandscope_missing_analysis_python__";
 
 pub const YOUTUBE_IMPORT_TIMEOUT: Duration = Duration::from_secs(120);
@@ -655,6 +666,124 @@ pub fn validate_score_pdf_source(path: &Path) -> Result<(PathBuf, String, u64),
     Ok((canonical, file_name, file_size_bytes))
 }
 
+/// Validate the bundled licensed demo WAV before it reuses local-audio bootstrap.
+pub fn validate_demo_audio_source(path: &Path) -> Result<LocalAudioSourcePayload, String> {
+    let link_metadata = std::fs::symlink_metadata(path)
+        .map_err(|_| DEMO_UNAVAILABLE_MESSAGE.to_string())?;
+    #[cfg(not(all(coverage, windows)))]
+    if link_metadata.file_type().is_symlink() {
+        return Err(DEMO_UNAVAILABLE_MESSAGE.to_string());
+    }
+
+    #[cfg(coverage)]
+    let canonical = path
+        .canonicalize()
+        .expect("demo audio path should canonicalize after metadata lookup");
+    #[cfg(not(coverage))]
+    let canonical = path
+        .canonicalize()
+        .map_err(|_| DEMO_UNAVAILABLE_MESSAGE.to_string())?;
+
+    let file_name = canonical
+        .file_name()
+        .and_then(|value| value.to_str())
+        .ok_or_else(|| DEMO_UNAVAILABLE_MESSAGE.to_string())?;
+    if file_name != DEMO_AUDIO_FILE_NAME {
+        return Err(DEMO_UNAVAILABLE_MESSAGE.to_string());
+    }
+    let extension = canonical
+        .extension()
+        .and_then(|value| value.to_str())
+        .map(|value| value.to_ascii_lowercase())
+        .ok_or_else(|| DEMO_UNAVAILABLE_MESSAGE.to_string())?;
+    if extension != "wav" {
+        return Err(DEMO_UNAVAILABLE_MESSAGE.to_string());
+    }
+    if !link_metadata.is_file() || link_metadata.len() != DEMO_AUDIO_BYTES {
+        return Err(DEMO_UNAVAILABLE_MESSAGE.to_string());
+    }
+
+    let data = std::fs::read(&canonical).map_err(|_| DEMO_UNAVAILABLE_MESSAGE.to_string())?;
+    if !is_valid_demo_wav(&data) {
+        return Err(DEMO_UNAVAILABLE_MESSAGE.to_string());
+    }
+
+    Ok(LocalAudioSourcePayload {
+        source_path: canonical.to_string_lossy().into_owned(),
+        file_name: file_name.to_string(),
+        extension,
+        file_size_bytes: link_metadata.len(),
+    })
+}
+
+fn is_valid_demo_wav(data: &[u8]) -> bool {
+    if data.len() < 44
+        || &data[0..4] != WAV_RIFF_MAGIC
+        || &data[8..12] != WAV_WAVE_MAGIC
+        || u32::from_le_bytes([data[4], data[5], data[6], data[7]]) as usize != data.len() - 8
+    {
+        return false;
+    }
+
+    let mut offset = 12usize;
+    let mut has_format = false;
+    let mut has_data = false;
+    while offset < data.len() {
+        let header_end = match offset.checked_add(8) {
+            Some(value) if value <= data.len() => value,
+            _ => return false,
+        };
+        let chunk_size = u32::from_le_bytes([
+            data[offset + 4],
+            data[offset + 5],
+            data[offset + 6],
+            data[offset + 7],
+        ]) as usize;
+        let chunk_end = match header_end.checked_add(chunk_size) {
+            Some(value) if value <= data.len() => value,
+            _ => return false,
+        };
+        let next_offset = match chunk_end.checked_add(chunk_size % 2) {
+            Some(value) if value <= data.len() => value,
+            _ => return false,
+        };
+
+        match &data[offset..offset + 4] {
+            b"fmt " if chunk_size >= 16 => {
+                let format = u16::from_le_bytes([data[header_end], data[header_end + 1]]);
+                let channels = u16::from_le_bytes([data[header_end + 2], data[header_end + 3]]);
+                let sample_rate = u32::from_le_bytes([
+                    data[header_end + 4],
+                    data[header_end + 5],
+                    data[header_end + 6],
+                    data[header_end + 7],
+                ]);
+                let byte_rate = u32::from_le_bytes([
+                    data[header_end + 8],
+                    data[header_end + 9],
+                    data[header_end + 10],
+                    data[header_end + 11],
+                ]);
+                let block_align = u16::from_le_bytes([data[header_end + 12], data[header_end + 13]]);
+                let bits_per_sample =
+                    u16::from_le_bytes([data[header_end + 14], data[header_end + 15]]);
+                has_format = format == 1
+                    && channels > 0
+                    && sample_rate > 0
+                    && byte_rate > 0
+                    && block_align > 0
+                    && bits_per_sample > 0;
+            }
+            b"data" if chunk_size > 0 => has_data = true,
+            _ => {}
+        }
+
+        offset = next_offset;
+    }
+
+    offset == data.len() && has_format && has_data
+}
+
 /// Security Notes: reads and deletes never accept an arbitrary path from the
 /// WebView. The path is rebuilt server-side from validated ids, symlinks are
 /// refused, and the canonicalized result must still live under the
@@ -1280,4 +1409,81 @@ mod tests {
         let _ = std::fs::remove_dir_all(scores_root);
         let _ = std::fs::remove_dir_all(outside_root);
     }
+
+    fn write_sized_demo_wav(path: &Path, bytes: u64, riff: bool, wave: bool) {
+        let mut data = vec![0u8; bytes as usize];
+        if riff && wave && data.len() >= 44 {
+            let data_len = data.len() as u32;
+            data[0..4].copy_from_slice(b"RIFF");
+            data[4..8].copy_from_slice(&(data_len - 8).to_le_bytes());
+            data[8..12].copy_from_slice(b"WAVE");
+            data[12..16].copy_from_slice(b"fmt ");
+            data[16..20].copy_from_slice(&16u32.to_le_bytes());
+            data[20..22].copy_from_slice(&1u16.to_le_bytes());
+            data[22..24].copy_from_slice(&1u16.to_le_bytes());
+            data[24..28].copy_from_slice(&44_100u32.to_le_bytes());
+            data[28..32].copy_from_slice(&88_200u32.to_le_bytes());
+            data[32..34].copy_from_slice(&2u16.to_le_bytes());
+            data[34..36].copy_from_slice(&16u16.to_le_bytes());
+            data[36..40].copy_from_slice(b"data");
+            data[40..44].copy_from_slice(&(data_len - 44).to_le_bytes());
+        }
+        std::fs::write(path, data).expect("demo fixture should be written");
+    }
+
+    #[test]
+    fn demo_audio_validation_accepts_the_licensed_wav_contract() {
+        let root = unique_test_dir("demo-valid");
+        std::fs::create_dir_all(&root).expect("demo root should be created");
+        let path = root.join(DEMO_AUDIO_FILE_NAME);
+        write_sized_demo_wav(&path, DEMO_AUDIO_BYTES, true, true);
+        let source = validate_demo_audio_source(&path).expect("licensed demo wav should validate");
+        assert_eq!(source.file_name, DEMO_AUDIO_FILE_NAME);
+        assert_eq!(source.extension, "wav");
+        assert_eq!(source.file_size_bytes, DEMO_AUDIO_BYTES);
+        let _ = std::fs::remove_dir_all(root);
+    }
+
+    #[test]
+    fn demo_audio_validation_rejects_wrong_name_size_magic_and_missing_files() {
+        let root = unique_test_dir("demo-reject");
+        std::fs::create_dir_all(&root).expect("demo root should be created");
+
+        let wrong_name = root.join("other.wav");
+        write_sized_demo_wav(&wrong_name, DEMO_AUDIO_BYTES, true, true);
+        assert!(validate_demo_audio_source(&wrong_name).is_err());
+
+        let wrong_size = root.join(DEMO_AUDIO_FILE_NAME);
+        write_sized_demo_wav(&wrong_size, 12, true, true);
+        assert!(validate_demo_audio_source(&wrong_size).is_err());
+
+        write_sized_demo_wav(&wrong_size, DEMO_AUDIO_BYTES, true, true);
+        let mut malformed = std::fs::read(&wrong_size).expect("valid demo fixture should be readable");
+        malformed[4..8].copy_from_slice(&(DEMO_AUDIO_BYTES as u32).to_le_bytes());
+        std::fs::write(&wrong_size, malformed).expect("malformed fixture should be writable");
+        assert!(validate_demo_audio_source(&wrong_size).is_err());
+
+        write_sized_demo_wav(&wrong_size, DEMO_AUDIO_BYTES, false, true);
+        assert!(validate_demo_audio_source(&wrong_size).is_err());
+
+        write_sized_demo_wav(&wrong_size, DEMO_AUDIO_BYTES, true, false);
+        assert!(validate_demo_audio_source(&wrong_size).is_err());
+
+        let missing = root.join("missing").join(DEMO_AUDIO_FILE_NAME);
+        assert!(validate_demo_audio_source(&missing).is_err());
+
+        #[cfg(unix)]
+        {
+            let valid = root.join("target.wav");
+            write_sized_demo_wav(&valid, DEMO_AUDIO_BYTES, true, true);
+            let linked = root.join(DEMO_AUDIO_FILE_NAME);
+            let _ = std::fs::remove_file(&linked);
+            std::os::unix::fs::symlink(&valid, &linked).expect("symlink should be created");
+            assert!(validate_demo_audio_source(&linked).is_err());
+        }
+
+        let _ = std::fs::remove_dir_all(root);
+    }
+
+
 }

apps/desktop/src-tauri/capabilities/main.json

@@ -2,13 +2,16 @@
   "$schema": "../gen/schemas/desktop-schema.json",
   "identifier": "main-capability",
   "description": "Capability for the main BandScope window to use the analysis orchestration commands.",
-  "windows": ["main"],
+  "windows": [
+    "main"
+  ],
   "permissions": [
     "core:event:allow-listen",
     "core:event:allow-unlisten",
     "allow-start-analysis-job",
     "allow-get-analysis-job-status",
     "allow-select-local-audio-source",
+    "allow-select-demo-audio-source",
     "allow-import-youtube-url",
     "allow-save-project",
     "allow-load-project",

apps/desktop/src-tauri/gen/schemas/capabilities.json

@@ -1 +1 @@
-{"main-capability":{"identifier":"main-capability","description":"Capability for the main BandScope window to use the analysis orchestration commands.","local":true,"windows":["main"],"permissions":["core:event:allow-listen","core:event:allow-unlisten","allow-start-analysis-job","allow-get-analysis-job-status","allow-select-local-audio-source","allow-import-youtube-url","allow-save-project","allow-load-project","allow-attach-score-pdf","allow-read-score-pdf","allow-remove-score-pdf"]}}
+{"main-capability":{"identifier":"main-capability","description":"Capability for the main BandScope window to use the analysis orchestration commands.","local":true,"windows":["main"],"permissions":["core:event:allow-listen","core:event:allow-unlisten","allow-start-analysis-job","allow-get-analysis-job-status","allow-select-local-audio-source","allow-select-demo-audio-source","allow-import-youtube-url","allow-save-project","allow-load-project","allow-attach-score-pdf","allow-read-score-pdf","allow-remove-score-pdf"]}}

apps/desktop/src-tauri/gen/schemas/desktop-schema.json

@@ -224,6 +224,12 @@
           "const": "allow-select-local-audio-source",
           "markdownDescription": "Enables the select_local_audio_source command without any pre-configured scope."
         },
+        {
+          "description": "Enables the select_demo_audio_source command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-select-demo-audio-source",
+          "markdownDescription": "Enables the select_demo_audio_source command without any pre-configured scope."
+        },
         {
           "description": "Enables the start_analysis_job command without any pre-configured scope.",
           "type": "string",
@@ -278,6 +284,12 @@
           "const": "deny-select-local-audio-source",
           "markdownDescription": "Denies the select_local_audio_source command without any pre-configured scope."
         },
+        {
+          "description": "Denies the select_demo_audio_source command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-select-demo-audio-source",
+          "markdownDescription": "Denies the select_demo_audio_source command without any pre-configured scope."
+        },
         {
           "description": "Denies the start_analysis_job command without any pre-configured scope.",
           "type": "string",

apps/desktop/src-tauri/gen/schemas/linux-schema.json

@@ -188,6 +188,12 @@
           "const": "allow-select-local-audio-source",
           "markdownDescription": "Enables the select_local_audio_source command without any pre-configured scope."
         },
+        {
+          "description": "Enables the select_demo_audio_source command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-select-demo-audio-source",
+          "markdownDescription": "Enables the select_demo_audio_source command without any pre-configured scope."
+        },
         {
           "description": "Enables the start_analysis_job command without any pre-configured scope.",
           "type": "string",
@@ -206,6 +212,12 @@
           "const": "deny-select-local-audio-source",
           "markdownDescription": "Denies the select_local_audio_source command without any pre-configured scope."
         },
+        {
+          "description": "Denies the select_demo_audio_source command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-select-demo-audio-source",
+          "markdownDescription": "Denies the select_demo_audio_source command without any pre-configured scope."
+        },
         {
           "description": "Denies the start_analysis_job command without any pre-configured scope.",
           "type": "string",

apps/desktop/src-tauri/gen/schemas/macOS-schema.json

@@ -224,6 +224,12 @@
           "const": "allow-select-local-audio-source",
           "markdownDescription": "Enables the select_local_audio_source command without any pre-configured scope."
         },
+        {
+          "description": "Enables the select_demo_audio_source command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-select-demo-audio-source",
+          "markdownDescription": "Enables the select_demo_audio_source command without any pre-configured scope."
+        },
         {
           "description": "Enables the start_analysis_job command without any pre-configured scope.",
           "type": "string",
@@ -278,6 +284,12 @@
           "const": "deny-select-local-audio-source",
           "markdownDescription": "Denies the select_local_audio_source command without any pre-configured scope."
         },
+        {
+          "description": "Denies the select_demo_audio_source command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-select-demo-audio-source",
+          "markdownDescription": "Denies the select_demo_audio_source command without any pre-configured scope."
+        },
         {
           "description": "Denies the start_analysis_job command without any pre-configured scope.",
           "type": "string",