feat(workspace): loop tonight's first section from the map

AGENTS.md

@@ -1,7 +1,9 @@
 # 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.
+- The ready workspace must name a next rehearsal action. Tonight's first playable section loop (count-in, pause, stop) is the #961 transport slice; #1063 adds bounded pitch-preserving playback rate, while stem playback remains later work.
 - 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.
@@ -12,15 +14,19 @@
 - Repository governance and Gitflow rules live in `docs/repository/governance.md`, `docs/repository/bootstrap-plan.md`, and `docs/repository/gitflow.md`.
 
 ## Security workflow
+
 - Before writing PRDs, TRDs, UX copy, architecture changes, or implementation plans that touch risky boundaries, read `docs/security/app-security.md`.
 - If a task touches files, URLs, subprocesses, ffmpeg or native tools, WebView, local backend or IPC, updates, model downloads, project formats, logs, telemetry, or exports, the result must include `Security Notes`.
 - `Security Notes` should cover untrusted inputs, trust boundaries, allowlists or validation, safe failure, logging/privacy impact, and test points.
 
 <!-- BEGIN cwl-agent-guidance -->
+
 ## Agent guidance (CWL governance)
+
 This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working in this repo.
 
 ### Security & review gate
+
 - Every PR runs a central **Security Scan** required gate: `osv-scan` + `dependency-review` (diff-scoped) and `trivy-fs` (repo-wide, CRITICAL/HIGH, fixable). It runs on every PR base, **including stacked PRs**. Gating is by the Security Scan **job result**.
 - A failing `trivy-fs` is a **REAL finding, not a flake.** Read the job log (it prints each finding's rule id / severity / file) or the run's SARIF results, then **remediate**:
   - This repo ships **no Dockerfile and no k8s manifests**, so findings are almost always dependency vulns. Bump the offending package in the relevant lockfile — `apps/desktop/src-tauri/Cargo.lock` (Rust/Tauri), `package-lock.json` (Node), or `uv.lock` / `services/analysis-engine` (Python).
@@ -30,37 +36,45 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 - The org `code_scanning` ruleset is intentionally **CodeQL-only** (multiple code-scanning tools can't converge on one PR ref). Do **not** add tools to the `code_scanning` rule; enforcement stays on the Security Scan job.
 
 ### Code exploration
+
 - This repo has **no `.codegraph/` index**, so use normal search (grep/find/ripgrep) to locate and understand code. If a `.codegraph/` directory is later added at the repo root, prefer CodeGraph (`codegraph explore "<query>"`, or the code-review-graph MCP tools) **before** grep/find — it surfaces callers/callees/impact that text search misses.
+
 <!-- END cwl-agent-guidance -->
 
 ## Supply chain workflow
+
 - Before adding or changing dependencies, GitHub Actions, bundled binaries, or model artifacts, read `docs/security/dependency-policy.md`.
 - New direct dependencies must include admission rationale covering purpose, dependency class, alternatives, maintainer trust, license fit, known security issues, transitive footprint, and BandScope release risk.
 - Lockfiles, dependency review, audit, SBOM generation, and supplemental component inventory are mandatory and must not be skipped or loosened.
 - Supply-chain work is not complete without evidence: workflow paths, required check names for `main` and `develop`, SBOM format and retention, Dependabot baseline state, and the bundled-binary/model inventory path.
 - Use `FAILED` when repo-controlled supply-chain artifacts are missing; use `BLOCKED` only when GitHub permission, auth, network, or platform capability prevents enforcement.
 
 ## Cross-platform build workflow
+
 - Before changing CI, packaging, release flows, or native desktop build settings, read `docs/security/cross-platform-build-policy.md`.
 - Windows and macOS builds are required security controls for `develop`, `main`, and release validation.
 - Protected-branch build checks for Windows and macOS must not be removed, downgraded, or treated as optional.
 
 ## GitHub bootstrap workflow
+
 - Before declaring a GitHub task blocked, read `docs/workflow/github-bootstrap-execution-policy.md`.
 - Missing local git state, missing GitHub repo, missing `main`, missing `develop`, or missing initial workflows are bootstrap conditions, not default blockers.
 - For GitHub tasks, only use `BLOCKED` when the failure is caused by missing GitHub permissions, missing auth, missing network access, or platform-level feature limits.
 
 ## Setup commands
+
 - Node: `npm install`
 - Python: `uv sync --project services/analysis-engine --group dev`
 
 ## Build / Test commands
+
 - Full harness check: `./scripts/harness/quickcheck.sh`
 - Frontend tests: `npm run test --workspaces --if-present`
-- Python tests: `uv run --project services/analysis-engine pytest --cov=src/bandscope_analysis --cov-report=term-missing --cov-fail-under=100`
-- Typecheck: `npm run typecheck --workspaces --if-present && uv run --project services/analysis-engine mypy src`
+- Python tests: `uv run --directory services/analysis-engine pytest --cov=src/bandscope_analysis --cov-report=term-missing --cov-fail-under=100`
+- Typecheck: `npm run typecheck --workspaces --if-present && uv run --directory services/analysis-engine mypy src`
 
 ## Architecture references
+
 - `ARCHITECTURE.md`
 - `docs/engineering/acceptance-criteria.md`
 - `docs/engineering/harness-engineering.md`
@@ -80,13 +94,15 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 - `docs/plans/2026-03-10-bandscope-harness.md`
 
 ## Code style
+
 - Keep UI and analysis engine decoupled through shared contracts.
 - Prefer minimal, test-first changes for production code.
 - Prefer practical, friendly, rehearsal-first wording over academic or authority-heavy language.
 - Do not reduce the product to a chord analyzer when form, timing, player coordination, playable ranges, simplification, and setup cues are the real rehearsal blockers.
 - Do not frame usability as a reason to accept weak analysis quality; BandScope should aim for both easy use and high accuracy.
 
 ## Safety
+
 - Do not add network-dependent runtime paths for local analysis.
 - Treat YouTube import as policy-constrained and fallback-friendly.
 - Treat files, URLs, metadata, model artifacts, and project files as untrusted input.

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # ARCHITECTURE.md
 
-Last updated: 2026-03-11
+Last updated: 2026-08-21
 
 ## Brand source
 
@@ -86,6 +86,7 @@ Last updated: 2026-03-11
   - 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
+  - a local rehearsal transport that arms the first valid section loop, counts in at the admitted tempo, and names the next play/pause/stop action without pretending disk audio is playing when no local song is loaded
 
 ## Confidence, edits, and provenance
 

CHANGELOG.md

@@ -4,8 +4,10 @@
 
 ### Added
 
+- Tonight's rehearsal player now arms the first valid section loop, runs a tempo count-in, and plays validated local audio through a scoped Tauri asset URL in the browser media element; the React layer does not decode audio bytes itself, and admitted section timing and picker copy use the same descriptor-snapshotted transport window.
 - 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.
+- Move between playable section cues with Left and Right Arrow and keep the selected cue focused.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 
 ### Changed
@@ -15,6 +17,8 @@
 
 ### Fixed
 
+- Kept the rehearsal player section picker aligned with the selected player or
+  vocal role while preserving the full song-form roadmap.
 - Upgraded the local score PDF parser to `pdfjs-dist` 6.2.108, pinned Undici 7.29.0 across the workspace, and constrained PDF loading to copied in-memory bytes with a same-origin bundled worker and npm-generated lock provenance.
 
 ## [0.1.3] - 2026-04-29
@@ -49,7 +53,6 @@
 - Resolve npm audit vulnerabilities
 - Fix ruff import sorting and formatting errors
 - Add missing docstrings to tests
-- Fix test configuration and typing issues
 
 ## [0.1.0] - 2026-03-27
 

CLAUDE.md

@@ -41,8 +41,8 @@ npm --workspace @bandscope/desktop exec vitest run src/lib/export.test.ts   # on
 npm run dev --workspace @bandscope/desktop                 # Vite dev server (browser fallback mode)
 npm run storybook --workspace @bandscope/desktop           # component workbench
 
-uv run --project services/analysis-engine pytest tests/test_chords.py       # one Python test file (no coverage gate)
-uv run --project services/analysis-engine pytest --cov=src/bandscope_analysis --cov-report=term-missing --cov-fail-under=100   # full Python gate
+uv run --directory services/analysis-engine pytest tests/test_chords.py       # one Python test file (no coverage gate)
+uv run --directory services/analysis-engine pytest --cov=src/bandscope_analysis --cov-report=term-missing --cov-fail-under=100   # full Python gate
 ```
 
 ## Architecture
@@ -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 workspace `RehearsalPlayer` owns tonight's first section loop and count-in clock. It does not decode local audio bytes in React; after native admission, its browser media element plays the authorized source through a scoped Tauri asset URL. The ready workspace also 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/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-tauri/src/main.rs

@@ -1,13 +1,16 @@
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
+mod playback_protocol;
+
 use bandscope_desktop_core::*;
+use playback_protocol::{playback_authority_uri, PlaybackAuthority, PLAYBACK_SCHEME};
 use rfd::FileDialog;
 use serde_json::{json, Value};
 use std::{
     io::{BufRead, BufReader, Read, Write},
     path::{Path, PathBuf},
     process::{Command, Stdio},
-    sync::{atomic::Ordering, mpsc},
+    sync::{atomic::Ordering, mpsc, Arc},
     thread,
     time::Instant,
 };
@@ -317,6 +320,15 @@ fn lookup_bootstrap_source(
         .ok_or_else(|| "Analysis job source was not found. Choose local audio again.".to_string())
 }
 
+/// Return a renderer-safe bootstrap while retaining the native source only in
+/// BandScope's process-local analysis and playback authority stores.
+fn renderer_bootstrap_summary(
+    mut summary: ProjectBootstrapSummaryPayload,
+) -> Result<ProjectBootstrapSummaryPayload, String> {
+    summary.source.source_path = playback_authority_uri(&summary.project_id)?;
+    Ok(summary)
+}
+
 fn drain_analysis_status_updates(
     state: &AppState,
     app: &tauri::AppHandle<impl Runtime>,
@@ -637,6 +649,7 @@ fn get_analysis_job_status(job_id: String, state: tauri::State<'_, AppState>) ->
 fn select_local_audio_source(
     app: tauri::AppHandle<impl Runtime>,
     state: tauri::State<'_, AppState>,
+    playback_authority: tauri::State<'_, Arc<PlaybackAuthority>>,
 ) -> Result<ProjectBootstrapSummaryPayload, String> {
     let path = FileDialog::new()
         .add_filter("Audio", &AUDIO_EXTENSIONS)
@@ -656,16 +669,18 @@ fn select_local_audio_source(
         temp_root: temp_root.to_string_lossy().into_owned(),
         source,
     };
+    playback_authority.activate(&summary.project_id, &summary.source)?;
     store_bootstrap_source(&state, summary.clone());
 
-    Ok(summary)
+    renderer_bootstrap_summary(summary)
 }
 
 #[tauri::command]
 async fn import_youtube_url(
     url: String,
     app: tauri::AppHandle<impl Runtime>,
     state: tauri::State<'_, AppState>,
+    playback_authority: tauri::State<'_, Arc<PlaybackAuthority>>,
 ) -> Result<ProjectBootstrapSummaryPayload, String> {
     if !is_supported_youtube_url(&url) {
         return Err("Only standard YouTube URLs are supported.".to_string());
@@ -721,8 +736,9 @@ async fn import_youtube_url(
                 temp_root: temp_root.to_string_lossy().into_owned(),
                 source,
             };
+            playback_authority.activate(&summary.project_id, &summary.source)?;
             store_bootstrap_source(&state, summary.clone());
-            return Ok(summary);
+            return renderer_bootstrap_summary(summary);
         }
         return Err(youtube_missing_metadata_error(&parsed));
     }
@@ -866,8 +882,15 @@ fn remove_score_pdf(
 }
 
 fn main() {
+    let playback_authority = Arc::new(PlaybackAuthority::default());
+    let protocol_authority = Arc::clone(&playback_authority);
+
     tauri::Builder::default()
         .manage(AppState::default())
+        .manage(playback_authority)
+        .register_uri_scheme_protocol(PLAYBACK_SCHEME, move |_context, request| {
+            protocol_authority.respond(request)
+        })
         .invoke_handler(tauri::generate_handler![
             select_local_audio_source,
             import_youtube_url,