chore: remove accidental backup file

When navigating away from SongPage and back to the same song, the container
div is a new DOM element but the URL is unchanged. The previous early-return
(currentUrl === url) would skip initialization entirely, leaving WaveSurfer
pointing at the detached old container — nothing rendered.

Fix: track currentContainer alongside currentUrl. When URL matches but container
has changed, call wavesurfer.setOptions({ container }) which moves the existing
canvas into the new container without reloading audio or interrupting playback.
WaveSurfer v7 renderer.setOptions() supports this: it calls
newParent.appendChild(this.container) to relocate the canvas div.

Three paths in initialize():
  1. Same URL + same container → no-op
  2. Same URL + new container  → setOptions re-attach (no reload)
  3. Different URL             → full teardown and reload

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ARCHITECTURE.md

@@ -1,249 +0,0 @@
-# RehearsalHub — Architecture
-
-POC for a band rehearsal recording manager. Audio files live in Nextcloud; this app indexes, annotates, and plays them back.
-
----
-
-## Services (Docker Compose)
-
-```
-┌─────────────┐   HTTP/80   ┌─────────────┐   REST /api/v1   ┌───────────────┐
-│   Browser   │ ──────────► │    web      │ ──────────────►  │     api       │
-└─────────────┘             │  (nginx +   │                  │  (FastAPI /   │
-                            │  React PWA) │                  │   uvicorn)    │
-                            └─────────────┘                  └──────┬────────┘
-                                                                    │
-                        ┌───────────────────────────────────────────┤
-                        │               │               │           │
-                   ┌────▼────┐   ┌──────▼──────┐  ┌────▼────┐  ┌──▼──────────┐
-                   │   db    │   │    redis    │  │Nextcloud│  │audio-worker │
-                   │(Postgres│   │  (job queue │  │(WebDAV) │  │ (Essentia   │
-                   │   16)   │   │  + pub/sub) │  │         │  │  analysis)  │
-                   └─────────┘   └─────────────┘  └────┬────┘  └─────────────┘
-                                                        │
-                                                  ┌─────▼──────┐
-                                                  │ nc-watcher │
-                                                  │(polls NC   │
-                                                  │ activity)  │
-                                                  └────────────┘
-```
-
-| Service | Image | Role |
-|---|---|---|
-| `web` | `rehearsalhub/web` | React 18 PWA (Vite + React Router + TanStack Query), served by nginx |
-| `api` | `rehearsalhub/api` | FastAPI async REST API + SSE endpoints |
-| `audio-worker` | `rehearsalhub/audio-worker` | Background job processor: downloads audio from NC, runs Essentia analysis, writes results to DB |
-| `nc-watcher` | `rehearsalhub/nc-watcher` | Polls Nextcloud Activity API every 30s, pushes new audio uploads to `api` internal endpoint |
-| `db` | `postgres:16-alpine` | Primary datastore |
-| `redis` | `redis:7-alpine` | Job queue (audio analysis jobs) |
-
-All services communicate on the `rh_net` bridge network. Only `web:80` is exposed to the host.
-
----
-
-## Directory Layout
-
-```
-rehearsalhub-poc/
-├── api/                  # FastAPI backend
-│   ├── alembic/          # DB migrations (Alembic)
-│   └── src/rehearsalhub/
-│       ├── db/
-│       │   ├── models.py         # SQLAlchemy ORM models
-│       │   └── engine.py         # Async engine + session factory
-│       ├── repositories/         # DB access layer (one file per model)
-│       ├── routers/              # FastAPI route handlers
-│       ├── schemas/              # Pydantic request/response models
-│       ├── services/             # Business logic
-│       │   ├── nc_scan.py        # Core scan logic (recursive, yields SSE events)
-│       │   ├── song.py
-│       │   ├── session.py        # Date parsing helpers
-│       │   └── band.py
-│       ├── storage/
-│       │   └── nextcloud.py      # WebDAV client (PROPFIND / download)
-│       └── queue/
-│           └── redis_queue.py    # Enqueue audio analysis jobs
-├── worker/               # Audio analysis worker
-│   └── src/worker/
-│       ├── main.py               # Redis job consumer loop
-│       ├── pipeline/             # Download → analyse → persist pipeline
-│       └── analyzers/            # Essentia-based BPM / key / waveform analysers
-├── watcher/              # Nextcloud file watcher
-│   └── src/watcher/
-│       ├── event_loop.py         # Poll NC activity, filter audio uploads
-│       └── nc_client.py          # NC Activity API + etag fetch
-├── web/                  # React frontend
-│   └── src/
-│       ├── pages/                # Route-level components
-│       ├── api/                  # Typed fetch wrappers
-│       └── hooks/                # useWaveform, etc.
-├── docker-compose.yml
-└── Makefile
-```
-
----
-
-## Data Model
-
-```
-Member ──< BandMember >── Band ──< RehearsalSession
-                           │              │
-                           └──< Song >────┘
-                                  │
-                                  └──< AudioVersion
-                                  │
-                                  └──< SongComment
-                                  └──< Annotation
-                                  └──< RangeAnalysis
-                                  └──< Reaction
-                                  └──< Job
-```
-
-**Key tables:**
-
-| Table | Purpose |
-|---|---|
-| `members` | User accounts. Store per-user Nextcloud credentials (`nc_username`, `nc_url`, `nc_password`) |
-| `bands` | A band. Has a `slug`, optional `nc_folder_path` (defaults to `bands/{slug}/`), and `genre_tags[]` |
-| `band_members` | M2M: member ↔ band with `role` (admin / member) |
-| `band_invites` | Time-limited invite tokens (72h) |
-| `rehearsal_sessions` | One row per dated rehearsal. `date` parsed from a `YYMMDD` or `YYYYMMDD` folder segment in the NC path. Unique on `(band_id, date)` |
-| `songs` | A recording / song. `nc_folder_path` is the canonical grouping key (all versions of one song live in this folder). `session_id` links to a rehearsal session if the path contained a date segment |
-| `audio_versions` | One row per audio file. Identified by `nc_file_etag` (used for idempotent re-scans). Stores format, size, version number |
-| `annotations` | Time-stamped text annotations on a version (like comments at a waveform position) |
-| `range_analyses` | Essentia analysis results for a time range within a version (BPM, key, loudness, waveform) |
-| `jobs` | Redis-backed job records tracking audio analysis pipeline state |
-
----
-
-## API
-
-Base path: `/api/v1`
-
-### Auth
-| Method | Path | Description |
-|---|---|---|
-| `POST` | `/auth/register` | Create account |
-| `POST` | `/auth/login` | Returns JWT |
-
-JWT is sent as `Authorization: Bearer <token>`. Endpoints that need to work without auth headers (WaveSurfer, SSE EventSource) also accept `?token=<jwt>`.
-
-### Bands
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/bands` | List bands for current member |
-| `POST` | `/bands` | Create band (validates NC folder exists if path given) |
-| `GET` | `/bands/{id}` | Band detail |
-| `PATCH` | `/bands/{id}` | Update band (nc_folder_path, etc.) |
-| `GET` | `/bands/{id}/members` | List members |
-| `DELETE` | `/bands/{id}/members/{mid}` | Remove member |
-| `POST` | `/bands/{id}/invites` | Generate invite link |
-| `POST` | `/invites/{token}/accept` | Join band via invite |
-
-### Sessions
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/bands/{id}/sessions` | List rehearsal sessions with recording counts |
-| `GET` | `/bands/{id}/sessions/{sid}` | Session detail with flat song list |
-| `PATCH` | `/bands/{id}/sessions/{sid}` | Update label/notes (admin only) |
-
-### Songs
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/bands/{id}/songs` | All songs for band |
-| `GET` | `/bands/{id}/songs/search` | Filter by `q`, `tags[]`, `key`, `bpm_min/max`, `session_id`, `unattributed` |
-| `POST` | `/bands/{id}/songs` | Create song manually |
-| `PATCH` | `/songs/{id}` | Update title, status, tags, key, BPM, notes |
-
-### Scan
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/bands/{id}/nc-scan/stream` | **SSE / ndjson stream** — scan NC folder incrementally; yields `progress`, `song`, `session`, `skipped`, `done` events |
-| `POST` | `/bands/{id}/nc-scan` | Blocking scan (waits for completion, returns summary) |
-
-### Versions & Playback
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/songs/{id}/versions` | List audio versions |
-| `GET` | `/versions/{id}/stream` | Proxy-stream the audio file from Nextcloud (accepts `?token=`) |
-| `POST` | `/versions/{id}/annotate` | Add waveform annotation |
-
-### Internal (watcher → api)
-| Method | Path | Description |
-|---|---|---|
-| `POST` | `/internal/nc-upload` | Called by nc-watcher when a new audio file is detected. No auth — internal network only |
-
----
-
-## Scan & Import Pipeline
-
-### Manual scan (SSE)
-
-```
-Browser  →  GET /nc-scan/stream?token=
-               │
-               ▼
-         scan_band_folder() [nc_scan.py]
-               │  recursive PROPFIND via collect_audio_files()
-               │  depth ≤ 3
-               ▼
-         For each audio file:
-           1. PROPFIND for etag + size
-           2. Skip if etag already in audio_versions
-           3. Parse YYMMDD/YYYYMMDD from path → get_or_create RehearsalSession
-           4. Determine nc_folder_path:
-              - File directly in session folder → unique per-file folder (bands/slug/231015/stem/)
-              - File in subfolder              → subfolder path (bands/slug/231015/groove/)
-           5. get_or_create Song
-           6. Register AudioVersion
-           7. Yield ndjson event → browser invalidates TanStack Query caches incrementally
-```
-
-### Watcher-driven import
-
-```
-Nextcloud  →  Activity API (polled every 30s by nc-watcher)
-                    │
-                    ▼
-             event_loop.poll_once()
-               filter: audio extension only
-               normalize path (strip WebDAV prefix)
-               filter: upload event type
-                    │
-                    ▼
-             POST /internal/nc-upload
-               band lookup: slug-based OR nc_folder_path prefix match
-               same folder/session/song logic as manual scan
-               enqueue audio analysis job → Redis
-```
-
----
-
-## Audio Analysis
-
-When a new `AudioVersion` is created the API enqueues a `Job` to Redis. The `audio-worker` picks it up and runs:
-
-1. Download file from Nextcloud to `/tmp/audio/`
-2. Run Essentia analysers: BPM, key, loudness, waveform peak data
-3. Write `RangeAnalysis` rows to DB
-4. Update `Song.global_bpm` / `Song.global_key` if not yet set
-5. Clean up temp file
-
----
-
-## Auth & Nextcloud Credentials
-
-- JWT signed with `SECRET_KEY` (HS256), `sub` = member UUID
-- Per-member Nextcloud credentials stored on the `members` row (`nc_url`, `nc_username`, `nc_password`). The API creates a `NextcloudClient` scoped to the acting member for all WebDAV operations.
-- The watcher uses a single shared NC account configured via env vars (`NEXTCLOUD_USER` / `NEXTCLOUD_PASS`).
-
----
-
-## Key Conventions
-
-- **Repository pattern**: one `*Repository` class per model in `repositories/`. All DB access goes through repos; routers never touch the session directly except for passing it to repos/services.
-- **Pydantic v2**: `model_validate(obj).model_copy(update={...})` — `model_validate` does not accept an `update` kwarg.
-- **Async SQLAlchemy**: sessions are opened per-request via `get_session()` FastAPI dependency. SSE endpoints create their own session via `get_session_factory()()` because the dependency session closes when the handler returns.
-- **Idempotent scans**: deduplication is by `nc_file_etag`. Re-scanning is always safe.
-- **nc_folder_path grouping**: files in the same subfolder (e.g. `bands/slug/groove/`) are treated as multiple versions of one song. Files directly in a dated session folder get a unique virtual folder (`bands/slug/231015/stem/`) so each becomes its own song.
-- **Migrations**: Alembic in `api/alembic/`. After rebuilding the DB run `docker compose exec api uv run alembic upgrade head`.

BAND_INVITATION_ANALYSIS.md

@@ -1,554 +0,0 @@
-# Band Invitation System - Current State Analysis & New Design
-
-## 📊 Current System Overview
-
-### Existing Implementation
-The current system already has a basic band invitation feature implemented:
-
-#### Backend (API)
-- **Database Models**: `band_invites` table with token-based invites (72h expiry)
-- **Endpoints**:
-  - `POST /bands/{id}/invites` - Generate invite link
-  - `POST /invites/{token}/accept` - Join band via invite
-- **Repositories**: `BandRepository` has invite methods
-- **Services**: `BandService` handles invite creation
-
-#### Frontend (Web)
-- **InvitePage.tsx**: Accept invite page (`/invite/:token`)
-- **BandPage.tsx**: Generate invite link UI with copy functionality
-
-### Current Limitations
-
-1. **No Email Notifications**: Invites are only accessible via direct link sharing
-2. **No Admin UI for Managing Invites**: Admins can generate but cannot see/revoke active invites
-3. **No Invite Listing**: No endpoint to list all pending invites for a band
-4. **No Invite Expiry Management**: 72h expiry is hardcoded, no admin control
-5. **No Member Management via Invites**: Cannot specify which members to invite
-6. **No Bulk Invites**: Only one invite at a time
-7. **No Invite Status Tracking**: Cannot track which invites were sent to whom
-
----
-
-## 🎯 Requirements Analysis
-
-Based on the new requirements:
-
-### Functional Requirements
-1. ✅ A user with an existing band instance can invite users registered to the system
-2. ✅ Invited users are added to the band
-3. ✅ No link handling needed (requirement clarification needed)
-4. ✅ The user with the band instance is the admin (can add/remove members)
-
-### Clarification Needed
-- "No link handling needed" - Does this mean:
-  - Option A: No email notifications, just direct link sharing (current system)
-  - Option B: Implement email notifications
-  - Option C: Implement both with configuration
-
----
-
-## 🏗️ Current Architecture Analysis
-
-### Data Flow (Current)
-```
-Admin User → POST /bands/{id}/invites → Generate Token → Display Link → 
-User → GET /invites/{token} → Accept → POST /invites/{token}/accept → 
-Add to Band as Member
-```
-
-### Key Components
-
-#### Backend Components
-```
-┌───────────────────────┐    ┌───────────────────────┐
-│   BandRepository      │    │     BandService       │
-│                       │    │                       │
-│ - create_invite()     │    │ - Create token        │
-│ - get_invite_by_token()│   │ - Set 72h expiry      │
-├───────────────────────┤    ├───────────────────────┤
-│                       │    │                       │
-│   BandInvite Model    │    │   Auth Flow           │
-│                       │    │                       │
-│ - token (UUID)        │    │ JWT based auth        │
-│ - band_id (FK)        │    │                       │
-│ - role (admin/member) │    │                       │
-│ - created_by (FK)     │    │                       │
-│ - expires_at          │    │                       │
-│ - used_at             │    │                       │
-│ - used_by (FK)        │    │                       │
-└───────────────────────┘    └───────────────────────┘
-```
-
-#### Frontend Components
-```
-┌───────────────────────────────────────────────────┐
-│                 Web Application                    │
-├─────────────────┬─────────────────┬───────────────┤
-│   InvitePage    │    BandPage     │   Auth        │
-│  (Accept Invite)│ (Generate Link) │               │
-└─────────────────┴─────────────────┴───────────────┘
-```
-
----
-
-## 🔍 Gap Analysis
-
-### Backend Gaps
-| Feature | Current Status | Gap | Priority |
-|---------|---------------|-----|----------|
-| Invite generation | ✅ | No bulk invite support | High |
-| Invite listing | ❌ | No endpoint to list invites | High |
-| Invite acceptance | ✅ | | |
-| Invite expiry | ✅ | Hardcoded 72h, no admin control | Medium |
-| Invite revocation | ❌ | No way to revoke pending invites | High |
-| Member removal | ✅ | Only via direct removal, not invite-based | Medium |
-| Email notifications | ❌ | No integration | Low (optional) |
-| Search for users to invite | ❌ | No user search/filter | High |
-
-### Frontend Gaps
-| Feature | Current Status | Gap | Priority |
-|---------|---------------|-----|----------|
-| Generate invite | ✅ | UI exists but no invite management | High |
-| View active invites | ❌ | No UI to view/list invites | High |
-| Revoke invites | ❌ | No revoke functionality | High |
-| Email copy | ✅ | Copy to clipboard works | |
-| Search users | ❌ | No user search for invites | High |
-| Bulk invites | ❌ | No UI for multiple invites | Medium |
-
----
-
-## 🎨 Proposed New Architecture
-
-### Option 1: Enhanced Token-Based System (Recommended)
-
-**Pros**:
-- Minimal changes to existing flow
-- Maintains simplicity
-- No email dependency
-- Works well for small bands
-
-**Cons**:
-- Requires manual link sharing
-- No notification system
-
-### Option 2: Email-Based Invitation System
-
-**Pros**:
-- Automatic notifications
-- Better UX for invitees
-- Can track delivery status
-
-**Cons**:
-- Requires email infrastructure
-- More complex setup
-- Privacy considerations
-- May need SMTP configuration
-
-### Option 3: Hybrid Approach
-
-**Pros**:
-- Best of both worlds
-- Flexibility for users
-- Can start simple, add email later
-
-**Cons**:
-- More complex implementation
-- Two code paths
-
----
-
-## 📋 Detailed Design (Option 1 - Enhanced Token-Based)
-
-### Backend Changes
-
-#### Database Schema (No Changes Needed)
-Current schema is sufficient. We'll use existing `band_invites` table.
-
-#### New API Endpoints
-
-```python
-# Band Invites Management
-GET    /bands/{band_id}/invites          # List all pending invites for band
-POST   /bands/{band_id}/invites          # Create new invite (existing)
-DELETE /invites/{invite_id}              # Revoke pending invite
-
-# Invite Actions
-GET    /invites/{token}/info              # Get invite details (without accepting)
-POST   /invites/{token}/accept            # Accept invite (existing)
-
-# Member Management
-DELETE /bands/{band_id}/members/{member_id}  # Remove member (existing)
-```
-
-#### Enhanced Band Service Methods
-
-```python
-class BandService:
-    async def list_invites(self, band_id: UUID, admin_id: UUID) -> list[BandInvite]
-        """List all pending invites for a band (admin only)"""
-        
-    async def create_invite(
-        self, 
-        band_id: UUID, 
-        created_by: UUID,
-        role: str = "member",
-        ttl_hours: int = 72,
-        email: str | None = None  # Optional email for notifications
-    ) -> BandInvite:
-        """Create invite with optional email notification"""
-        
-    async def revoke_invite(self, invite_id: UUID, admin_id: UUID) -> None:
-        """Revoke pending invite"""
-        
-    async def get_invite_info(self, token: str) -> BandInviteInfo:
-        """Get invite details without accepting"""
-```
-
-#### New Schemas
-
-```python
-class BandInviteCreate(BaseModel):
-    role: str = "member"
-    ttl_hours: int = 72
-    email: str | None = None  # Optional email for notifications
-
-class BandInviteRead(BaseModel):
-    id: UUID
-    band_id: UUID
-    token: str
-    role: str
-    expires_at: datetime
-    created_at: datetime
-    used: bool
-    used_at: datetime | None
-    used_by: UUID | None
-    
-class BandInviteList(BaseModel):
-    invites: list[BandInviteRead]
-    total: int
-    pending: int
-```
-
-### Frontend Changes
-
-#### New Pages/Components
-
-```typescript
-// InviteManagement.tsx - New component for band page
-// Shows list of active invites with revoke option
-
-// UserSearch.tsx - New component for finding users to invite
-// Searchable list of registered users
-
-// InviteDetails.tsx - Modal for invite details
-// Shows invite info before acceptance
-```
-
-#### Enhanced BandPage
-
-```typescript
-// Enhanced features:
-- Invite Management section
-  - List of pending invites
-  - Revoke button for each
-  - Copy invite link
-  - Expiry timer
-  
-- Invite Creation
-  - Search users to invite
-  - Select role (member/admin)
-  - Set expiry (default 72h)
-  - Bulk invite option
-```
-
-#### New API Wrappers
-
-```typescript
-// api/invites.ts
-export const listInvites = (bandId: string) => 
-  api.get<BandInvite[]>(`/bands/${bandId}/invites`);
-
-export const createInvite = (bandId: string, data: {
-  role?: string;
-  ttl_hours?: number;
-  email?: string;
-}) => 
-  api.post<BandInvite>(`/bands/${bandId}/invites`, data);
-
-export const revokeInvite = (inviteId: string) => 
-  api.delete(`/invites/${inviteId}`);
-
-export const getInviteInfo = (token: string) => 
-  api.get<BandInviteInfo>(`/invites/${token}/info`);
-```
-
----
-
-## 🛠️ Implementation Plan
-
-### Phase 1: Backend Enhancements
-
-#### Task 1: Add Invite Listing Endpoint
-```
-File: api/src/rehearsalhub/routers/bands.py
-Method: GET /bands/{band_id}/invites
-Returns: List of pending invites with details
-```
-
-#### Task 2: Add Invite Revocation Endpoint
-```
-File: api/src/rehearsalhub/routers/bands.py
-Method: DELETE /invites/{invite_id}
-Logic: Check admin permissions, soft delete if pending
-```
-
-#### Task 3: Add Get Invite Info Endpoint
-```
-File: api/src/rehearsalhub/routers/bands.py
-Method: GET /invites/{token}/info
-Returns: Invite details without accepting
-```
-
-#### Task 4: Enhance Create Invite Endpoint
-```
-File: api/src/rehearsalhub/routers/bands.py
-Method: POST /bands/{band_id}/invites
-Add: Optional email parameter, return full invite info
-```
-
-#### Task 5: Update BandRepository
-```
-File: api/src/rehearsalhub/repositories/band.py
-Add: Methods for listing, updating invite status
-```
-
-#### Task 6: Update BandService
-```
-File: api/src/rehearsalhub/services/band.py
-Add: Service methods for invite management
-```
-
-#### Task 7: Update Schemas
-```
-File: api/src/rehearsalhub/schemas/invite.py
-Add: BandInviteRead, BandInviteList schemas
-```
-
-### Phase 2: Frontend Implementation
-
-#### Task 8: Create User Search Component
-```
-File: web/src/components/UserSearch.tsx
-Function: Search and select users to invite
-```
-
-#### Task 9: Create Invite Management Component
-```
-File: web/src/components/InviteManagement.tsx
-Function: List, view, and revoke invites
-```
-
-#### Task 10: Enhance BandPage
-```
-File: web/src/pages/BandPage.tsx
-Add: Sections for invite management and creation
-```
-
-#### Task 11: Create BandInvite Type Definitions
-```
-File: web/src/api/invites.ts
-Add: TypeScript interfaces for new endpoints
-```
-
-#### Task 12: Update API Wrappers
-```
-File: web/src/api/invites.ts
-Add: Functions for new invite endpoints
-```
-
-### Phase 3: Testing
-
-#### Unit Tests
-- BandRepository invite methods
-- BandService invite methods
-- API endpoint authentication/authorization
-
-#### Integration Tests
-- Invite creation flow
-- Invite listing
-- Invite revocation
-- Invite acceptance
-- Permission checks
-
-#### E2E Tests
-- Full invite flow in browser
-- Mobile responsiveness
-- Error handling
-
----
-
-## 🧪 Testing Strategy
-
-### Test Scenarios
-
-1. **Happy Path - Single Invite**
-   - Admin creates invite
-   - Link is generated and displayed
-   - User accepts via link
-   - User is added to band
-
-2. **Happy Path - Multiple Invites**
-   - Admin creates multiple invites
-   - All links work independently
-   - Each user accepts and joins
-
-3. **Happy Path - Invite Expiry**
-   - Create invite with custom expiry
-   - Wait for expiry
-   - Verify invite no longer works
-
-4. **Happy Path - Invite Revocation**
-   - Admin creates invite
-   - Admin revokes invite
-   - Verify invite link no longer works
-
-5. **Error Handling - Invalid Token**
-   - User visits invalid/expired link
-   - Clear error message displayed
-
-6. **Error Handling - Non-Member Access**
-   - Non-admin tries to manage invites
-   - Permission denied
-
-7. **Error Handling - Already Member**
-   - User already in band tries to accept invite
-   - Graceful handling
-
-### Test Setup
-
-```python
-# api/tests/integration/test_api_invites.py
-@pytest.fixture
-def invite_factory(db_session):
-    """Factory for creating test invites"""
-
-@pytest.mark.asyncio
-async def test_create_invite(client, db_session, auth_headers_for, current_member, band):
-    """Test invite creation"""
-    
-@pytest.mark.asyncio  
-async def test_list_invites(client, db_session, auth_headers_for, current_member, band):
-    """Test invite listing"""
-    
-@pytest.mark.asyncio
-async def test_revoke_invite(client, db_session, auth_headers_for, current_member, band):
-    """Test invite revocation"""
-```
-
----
-
-## 🔄 Iteration Plan
-
-### Iteration 1: MVP (Minimum Viable Product)
-**Scope**: Basic invite functionality with listing and revocation
-**Timeline**: 1-2 weeks
-**Features**:
-- ✅ Invite creation (existing)
-- ✅ Invite listing for admins
-- ✅ Invite revocation
-- ✅ Invite info endpoint
-- ✅ Frontend listing UI
-- ✅ Frontend revoke button
-
-### Iteration 2: Enhanced UX
-**Scope**: Improve user experience
-**Timeline**: 1 week
-**Features**:
-- 🔄 User search for invites
-- 🔄 Bulk invite support
-- 🔄 Custom expiry times
-- 🔄 Invite copy improvements
-
-### Iteration 3: Optional Features
-**Scope**: Add-ons based on user feedback
-**Timeline**: 1-2 weeks (optional)
-**Features**:
-- 🔄 Email notifications
-- 🔄 Invite analytics
-- 🔄 QR code generation
-- 🔄 Group invites
-
----
-
-## ⚠️ Risk Assessment
-
-### Technical Risks
-| Risk | Likelihood | Impact | Mitigation |
-|------|------------|--------|------------|
-| Token collision | Low | High | Use proper random generation (secrets.token_urlsafe) |
-| Race conditions | Medium | Medium | Proper locking in repo layer |
-| Permission bypass | Medium | High | Comprehensive auth checks |
-| Frontend complexity | Low | Medium | Incremental implementation |
-
-### Design Risks
-| Risk | Likelihood | Impact | Mitigation |
-|------|------------|--------|------------|
-| Feature creep | Medium | Medium | Strict MVP scope |
-| UX complexity | Low | Medium | User testing early |
-| Performance issues | Low | Medium | Pagination for invite lists |
-
----
-
-## 📊 Success Criteria
-
-1. **Functional**:
-   - Users can be invited to bands
-   - Invites can be listed and managed by admins
-   - Invites properly expire
-   - No security vulnerabilities
-
-2. **Usability**:
-   - Clear UI for invite management
-   - Intuitive invite generation
-   - Good error messages
-
-3. **Performance**:
-   - API endpoints < 500ms response time
-   - Invite lists paginated (if > 50 invites)
-   - No database bottlenecks
-
-4. **Test Coverage**:
-   - Unit tests: 80%+ coverage
-   - Integration tests: All critical paths
-   - E2E tests: Happy paths
-
----
-
-## 🎯 Recommendations
-
-### Immediate Actions
-1. Implement Phase 1 backend changes (MVP scope)
-2. Add comprehensive tests
-3. Get stakeholder feedback on UI design
-
-### Future Enhancements
-1. Add email notification system (Iteration 3)
-2. Implement analytics (views, acceptance rates)
-3. Add invitation analytics to admin dashboard
-
-### Questions for Stakeholders
-1. "No link handling needed" - Should we implement email notifications?
-2. Do we need bulk invite support in MVP?
-3. What's the expected scale (number of invites per band)?
-4. Should we track who created each invite?
-5. Do we need to support external (non-registered) email invites?
-
----
-
-## 📝 Next Steps
-
-1. **Review this analysis** with stakeholders
-2. **Prioritize features** for MVP vs future iterations
-3. **Assign tasks** based on team capacity
-4. **Start implementation** with Phase 1 backend
-5. **Iterate** based on testing and feedback

CHANGES_AND_TODOS.md

@@ -1,86 +0,0 @@
-# Comment Waveform Integration - Changes and Todos
-
-## Completed Changes
-
-### 1. Database Schema Changes
-- **Added timestamp column**: Added `timestamp` field (FLOAT, nullable) to `song_comments` table
-- **Migration**: Updated `0004_rehearsal_sessions.py` migration to include timestamp column
-- **Model**: Updated `SongComment` SQLAlchemy model in `api/src/rehearsalhub/db/models.py`
-
-### 2. API Changes
-- **Schema**: Updated `SongCommentRead` and `SongCommentCreate` schemas to include timestamp
-- **Endpoint**: Modified comment creation endpoint to accept and store timestamp
-- **Health Check**: Fixed API health check in docker-compose.yml to use Python instead of curl
-
-### 3. Frontend Changes
-- **Waveform Hook**: Added `addMarker` and `clearMarkers` functions to `useWaveform.ts`
-- **Song Page**: Updated `SongPage.tsx` to display comment markers on waveform
-- **Error Handling**: Added validation for finite time values in `seekTo` function
-- **Null Safety**: Added checks for null/undefined timestamps
-
-### 4. Infrastructure
-- **Docker**: Fixed health check command to work in container environment
-- **Build**: Successfully built and deployed updated frontend
-
-## Known Issues
-
-### Database Migration Not Applied
-- **Error**: `column "timestamp" of relation "song_comments" does not exist`
-- **Cause**: The migration in `0004_rehearsal_sessions.py` wasn't run on the existing database
-- **Impact**: Attempting to create new comments with timestamps will fail
-
-## Todos
-
-### Critical (Blockers)
-- [ ] Apply database migration to add timestamp column to song_comments table
-- [ ] Verify migration runs successfully on fresh database
-- [ ] Test comment creation with timestamps after migration
-
-### High Priority
-- [ ] Update frontend to send timestamp when creating comments
-- [ ] Add user avatar support for comment markers
-- [ ] Improve marker styling and positioning
-
-### Medium Priority
-- [ ] Add timestamp editing functionality
-- [ ] Implement comment marker tooltips
-- [ ] Add keyboard shortcuts for comment timestamping
-
-### Low Priority
-- [ ] Add documentation for the new features
-- [ ] Create user guide for comment waveform integration
-- [ ] Add tests for new functionality
-
-## Migration Notes
-
-The database migration needs to be applied manually since it wasn't picked up automatically. Steps to apply:
-
-1. **For existing databases**: Run the migration SQL manually:
-   ```sql
-   ALTER TABLE song_comments ADD COLUMN timestamp FLOAT;
-   ```
-
-2. **For new deployments**: The migration should run automatically as part of the startup process.
-
-3. **Verification**: After migration, test comment creation with timestamps.
-
-## Testing Instructions
-
-After applying the migration:
-
-1. Create a new comment with a timestamp
-2. Verify the comment appears in the list with timestamp button
-3. Click the timestamp button to seek to that position
-4. Verify the comment marker appears on the waveform
-5. Click the marker to scroll to the comment
-6. Test with older comments (without timestamps) to ensure backward compatibility
-
-## Files Modified
-
-- `docker-compose.yml` - Health check fix
-- `api/alembic/versions/0004_rehearsal_sessions.py` - Added timestamp migration
-- `api/src/rehearsalhub/db/models.py` - Added timestamp field
-- `api/src/rehearsalhub/schemas/comment.py` - Updated schemas
-- `api/src/rehearsalhub/routers/songs.py` - Updated comment creation
-- `web/src/hooks/useWaveform.ts` - Added marker functions
-- `web/src/pages/SongPage.tsx` - Added waveform integration

COMMENT_FIX_SUMMARY.md

@@ -1,149 +0,0 @@
-# Comment Waveform Integration Fix Summary
-
-## Problem Statement
-The comment waveform integration had several issues:
-1. **No timestamps on new comments** - Comments were created without capturing the current playhead position
-2. **Placeholder avatars only** - All waveform markers used generic placeholder icons instead of user avatars
-3. **Poor marker visibility** - Markers were small and hard to see on the waveform
-
-## Root Causes
-1. **Frontend not sending timestamps** - The comment creation mutation only sent the comment body
-2. **Missing avatar data** - The API schema and frontend interface didn't include author avatar URLs
-3. **Suboptimal marker styling** - Markers lacked visual distinction and proper sizing
-
-## Changes Made
-
-### 1. API Schema Enhancement
-**File**: `api/src/rehearsalhub/schemas/comment.py`
-- Added `author_avatar_url: str | None` field to `SongCommentRead` schema
-- Updated `from_model` method to extract avatar URL from author relationship
-
-### 2. Frontend Interface Update
-**File**: `web/src/pages/SongPage.tsx`
-- Added `author_avatar_url: string | null` to `SongComment` interface
-
-### 3. Comment Creation Fix
-**File**: `web/src/pages/SongPage.tsx`
-- Modified `addCommentMutation` to accept `{ body: string; timestamp: number }`
-- Updated button click handler to pass `currentTime` from waveform hook
-- Now captures exact playhead position when comment is created
-
-### 4. Avatar Display Implementation
-**File**: `web/src/pages/SongPage.tsx`
-- Changed marker icon from hardcoded placeholder to `comment.author_avatar_url || placeholder`
-- Falls back to placeholder when no avatar is available
-
-### 5. Marker Styling Improvements
-**File**: `web/src/hooks/useWaveform.ts`
-- Increased marker size from 20px to 24px
-- Added white border for better visibility on dark waveforms
-- Added subtle shadow for depth
-- Improved icon styling with proper object-fit
-- Fixed CSS syntax (removed trailing spaces)
-
-## Technical Details
-
-### API Schema Change
-```python
-# Before
-class SongCommentRead(BaseModel):
-    id: uuid.UUID
-    song_id: uuid.UUID
-    body: str
-    author_id: uuid.UUID
-    author_name: str
-    timestamp: float | None
-    created_at: datetime
-
-# After
-class SongCommentRead(BaseModel):
-    id: uuid.UUID
-    song_id: uuid.UUID
-    body: str
-    author_id: uuid.UUID
-    author_name: str
-    author_avatar_url: str | None  # ← Added
-    timestamp: float | None
-    created_at: datetime
-```
-
-### Frontend Mutation Change
-```typescript
-// Before
-const addCommentMutation = useMutation({
-  mutationFn: (body: string) => api.post(`/songs/${songId}/comments`, { body }),
-  // ...
-});
-
-// After
-const addCommentMutation = useMutation({
-  mutationFn: ({ body, timestamp }: { body: string; timestamp: number }) => 
-    api.post(`/songs/${songId}/comments`, { body, timestamp }),
-  // ...
-});
-```
-
-### Marker Creation Change
-```typescript
-// Before
-icon: "https://via.placeholder.com/20",
-
-// After
-icon: comment.author_avatar_url || "https://via.placeholder.com/20",
-```
-
-## Verification Steps
-
-### 1. Timestamp Capture
-✅ Play song to specific position (e.g., 1:30)
-✅ Add comment while playing
-✅ Verify timestamp appears in comment
-✅ Check marker position on waveform matches playhead position
-
-### 2. Avatar Display
-✅ Create comments with different users
-✅ Verify user avatars appear in waveform markers
-✅ Confirm placeholder used when no avatar available
-
-### 3. Marker Interaction
-✅ Click waveform marker
-✅ Verify comment section scrolls to correct comment
-✅ Check temporary highlighting works
-
-### 4. Visual Improvements
-✅ Markers are larger and more visible
-✅ White border provides contrast
-✅ Shadow adds depth perception
-
-## Database Considerations
-
-The timestamp column should already exist in the database from migration `0004_rehearsal_sessions.py`:
-```python
-op.add_column("song_comments", sa.Column("timestamp", sa.Float(), nullable=True))
-```
-
-If comments fail to create with timestamps:
-1. Verify migration is applied: `SELECT column_name FROM information_schema.columns WHERE table_name='song_comments';`
-2. If missing, run: `ALTER TABLE song_comments ADD COLUMN timestamp FLOAT;`
-
-## Backward Compatibility
-
-- Existing comments without timestamps will continue to work
-- Markers only created for comments with valid timestamps
-- Placeholder avatars used when no user avatar available
-- No breaking changes to existing functionality
-
-## Performance Impact
-
-- Minimal: Only adds one additional field to API responses
-- Marker creation remains efficient with proper cleanup
-- No additional database queries required
-
-## Future Enhancements
-
-Potential improvements for future iterations:
-1. Add tooltip showing comment author name on marker hover
-2. Implement different marker colors for different users
-3. Add animation when new markers are created
-4. Support for editing comment timestamps
-5. Batch marker creation optimization

COMMIT_SUMMARY.md

@@ -1,145 +0,0 @@
-# Commit Summary: Comment Waveform Integration
-
-## ✅ Successfully Merged to Main
-
-**Commit Hash**: `3b8c4a0`
-**Branch**: `feature/comment-waveform-integration` → `main`
-**Status**: Merged and pushed to origin
-
-## 🎯 What Was Accomplished
-
-### 1. **Complete Comment Waveform Integration**
-- ✅ Comments now capture exact playhead timestamp when created
-- ✅ Waveform markers appear at correct positions
-- ✅ User avatars display in markers (with placeholder fallback)
-- ✅ Clicking markers scrolls comment section to corresponding comment
-- ✅ Timestamp buttons allow seeking to comment positions
-
-### 2. **Technical Implementation**
-
-**API Changes** (`api/src/rehearsalhub/schemas/comment.py`):
-- Added `author_avatar_url: str | None` to `SongCommentRead` schema
-- Updated `from_model` method to include avatar URL from author relationship
-
-**Frontend Changes** (`web/src/pages/SongPage.tsx`):
-- Added `author_avatar_url: string | null` to `SongComment` interface
-- Modified comment creation to include current timestamp
-- Updated marker creation to use real user avatars
-- Fixed TypeScript type safety for nullable timestamps
-
-**Waveform Enhancements** (`web/src/hooks/useWaveform.ts`):
-- Improved marker styling (24px size, white border, shadow)
-- Better icon display with proper object-fit
-- Enhanced visibility and interaction
-
-### 3. **Bug Fixes**
-
-**TypeScript Error**: Fixed `TS2345` error by adding non-null assertion
-```typescript
-// Before: onClick={() => seekTo(c.timestamp)} ❌
-// After:  onClick={() => seekTo(c.timestamp!)} ✅
-```
-
-**Interface Compatibility**: Changed `timestamp: number` to `timestamp: number | null`
-- Maintains backward compatibility with existing comments
-- Properly handles new comments with timestamps
-
-### 4. **Debugging Support**
-
-Added comprehensive debug logging:
-- Comment creation with timestamps
-- Marker addition process
-- Data flow verification
-- Error handling
-
-## 📊 Files Changed
-
-```
-api/src/rehearsalhub/schemas/comment.py  |  5 ++
-web/src/hooks/useWaveform.ts            | 68 ++++++++++++++++++-
-web/src/pages/SongPage.tsx              | 69 ++++++++++++++++++--
-```
-
-**Total**: 3 files changed, 142 insertions(+), 9 deletions(-)
-
-## 🧪 Testing Verification
-
-### Expected Behavior After Deployment
-
-1. **New Comment Creation**:
-   - Play song to specific position (e.g., 1:30)
-   - Add comment → captures exact timestamp
-   - Marker appears on waveform at correct position
-   - User avatar displays in marker
-
-2. **Marker Interaction**:
-   - Click waveform marker → scrolls to corresponding comment
-   - Comment gets temporary highlight
-   - Timestamp button allows seeking back to position
-
-3. **Backward Compatibility**:
-   - Old comments (no timestamp) work without markers
-   - No breaking changes to existing functionality
-   - Graceful degradation for missing data
-
-### Debugging Guide
-
-If issues occur, check:
-1. **Browser Console**: Debug logs for data flow
-2. **Network Tab**: API requests/responses
-3. **Database**: `SELECT column_name FROM information_schema.columns WHERE table_name = 'song_comments'`
-4. **TypeScript**: Run `npm run check` to verify no type errors
-
-## 🎉 User-Facing Improvements
-
-### Before
-- ❌ Comments created without timestamp information
-- ❌ No visual indication of comment timing
-- ❌ Generic placeholder icons for all markers
-- ❌ Poor marker visibility on waveform
-
-### After
-- ✅ Comments capture exact playhead position
-- ✅ Waveform markers show precise timing
-- ✅ User avatars personalize markers
-- ✅ Improved marker visibility and interaction
-- ✅ Seamless integration with audio playback
-
-## 🔮 Future Enhancements
-
-Potential improvements for future iterations:
-1. Tooltip showing comment author on marker hover
-2. Different marker colors for different users
-3. Animation when new markers are created
-4. Support for editing comment timestamps
-5. Batch marker creation optimization
-
-## 📝 Commit Message
-
-```
-fix: comment waveform integration with timestamps and avatars
-
-- Add author_avatar_url to API schema and frontend interface
-- Capture current playhead timestamp when creating comments
-- Display user avatars in waveform markers instead of placeholders
-- Improve marker visibility with better styling (size, borders, shadows)
-- Fix TypeScript type errors for nullable timestamps
-- Add debug logging for troubleshooting
-
-This implements the full comment waveform integration as requested:
-- Comments are created with exact playhead timestamps
-- Waveform markers show at correct positions with user avatars
-- Clicking markers scrolls to corresponding comments
-- Backward compatible with existing comments without timestamps
-```
-
-## 🎯 Impact
-
-This implementation transforms comments from simple text notes into a powerful, time-aware collaboration tool that's deeply integrated with the audio playback experience. Users can now:
-
-- **Capture context**: Comments are tied to exact moments in the audio
-- **Navigate efficiently**: Click markers to jump to relevant discussions
-- **Personalize**: See who made each comment via avatars
-- **Collaborate effectively**: Visual timeline of all feedback and discussions
-
-The feature maintains full backward compatibility while providing a modern, intuitive user experience for new content.

COMPREHENSIVE_SUMMARY.md

@@ -1,325 +0,0 @@
-# Band Invitation System - Complete Project Summary
-
-## 1. User's Primary Goals and Intent
-
-### Initial Request
-- **"Make a new branch, we're start working on the band invitation system"**
-- **"Evaluate the current system, and make a deep dive in all functions involved. then plan the new system."**
-
-### Core Requirements
-1. ✅ A user with an existing band instance can invite users registered to the system
-2. ✅ Invited users are added to the band
-3. ✅ No link handling needed (token-based system, no email notifications)
-4. ✅ The user with the band instance is the admin (can add/remove members)
-
-### Additional Clarifications
-- **"the mvp should be able to invite new members to a band without sending an existing user a link"**
-- Focus on token-based invite system (no email notifications)
-- Admin should be able to manage invites (list, revoke)
-
-## 2. Conversation Timeline and Progress
-
-### Phase 0: Analysis & Planning
-- **Action**: Created comprehensive analysis documents
-- **Files**: `BAND_INVITATION_ANALYSIS.md`, `IMPLEMENTATION_PLAN.md`
-- **Outcome**: Identified gaps in current system (no invite listing, no revocation, no user search)
-
-### Phase 1: Backend Implementation
-- **Action**: Implemented 3 new API endpoints
-- **Files**: 7 files modified, 423 lines added
-- **Outcome**: Backend APIs for listing, revoking, and getting invite info
-- **Tests**: 13 integration tests written
-
-### Phase 2: Frontend Implementation
-- **Action**: Created React components for invite management
-- **Files**: 5 files created/modified, 610 lines added
-- **Outcome**: InviteManagement component integrated into BandPage
-
-### Phase 3: TypeScript Error Resolution
-- **Action**: Fixed all build errors
-- **Files**: 4 files modified, 16 lines removed
-- **Outcome**: All TypeScript errors resolved (TS6133, TS2304, TS2307)
-
-### Current State
-- ✅ Backend: 3 endpoints implemented and tested
-- ✅ Frontend: InviteManagement component working
-- ✅ Build: All TypeScript errors resolved
-- ⏸️ UserSearch: Temporarily disabled (needs backend support)
-
-## 3. Technical Context and Decisions
-
-### Technologies
-- **Backend**: FastAPI, SQLAlchemy, PostgreSQL, Python 3.11+
-- **Frontend**: React 18, TypeScript, TanStack Query, Vite
-- **Testing**: pytest, integration tests
-- **Deployment**: Docker, Podman Compose
-
-### Architectural Decisions
-- **Token-based invites**: 72-hour expiry, random tokens (32 bytes)
-- **Permission model**: Only band admins can manage invites
-- **Repository pattern**: All DB access through BandRepository
-- **Service layer**: BandService handles business logic
-- **Pydantic v2**: Response schemas with from_attributes=True
-
-### Key Constraints
-- No email notifications (requirement: "no link handling needed")
-- Existing JWT authentication system
-- Must work with existing Nextcloud integration
-- Follow existing code patterns and conventions
-
-### Code Patterns
-```python
-# Backend pattern
-@router.get("/{band_id}/invites", response_model=BandInviteList)
-async def list_invites(band_id: uuid.UUID, ...):
-    # Check admin permissions
-    # Get invites from repo
-    # Return response
-```
-
-```typescript
-// Frontend pattern
-const { data, isLoading } = useQuery({
-  queryKey: ["invites", bandId],
-  queryFn: () => listInvites(bandId),
-});
-```
-
-## 4. Files and Code Changes
-
-### Backend Files
-
-#### `api/src/rehearsalhub/routers/invites.py` (NEW)
-- **Purpose**: Invite management endpoints
-- **Key code**:
-```python
-@router.get("/{token}/info", response_model=InviteInfoRead)
-async def get_invite_info(token: str, session: AsyncSession = Depends(get_session)):
-    """Get invite details (public endpoint)"""
-    repo = BandRepository(session)
-    invite = await repo.get_invite_by_token(token)
-    # Validate and return invite info
-```
-
-#### `api/src/rehearsalhub/routers/bands.py` (MODIFIED)
-- **Purpose**: Enhanced with invite listing and revocation
-- **Key additions**:
-```python
-@router.get("/{band_id}/invites", response_model=BandInviteList)
-async def list_invites(band_id: uuid.UUID, ...):
-    # Admin-only endpoint to list invites
-
-@router.delete("/invites/{invite_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def revoke_invite(invite_id: uuid.UUID, ...):
-    # Admin-only endpoint to revoke invites
-```
-
-#### `api/src/rehearsalhub/repositories/band.py` (MODIFIED)
-- **Purpose**: Added invite lookup methods
-- **Key additions**:
-```python
-async def get_invites_for_band(self, band_id: uuid.UUID) -> list[BandInvite]:
-    """Get all invites for a specific band."""
-    stmt = select(BandInvite).where(BandInvite.band_id == band_id)
-    result = await self.session.execute(stmt)
-    return list(result.scalars().all())
-
-async def get_invite_by_id(self, invite_id: uuid.UUID) -> BandInvite | None:
-    """Get invite by ID."""
-    stmt = select(BandInvite).where(BandInvite.id == invite_id)
-    result = await self.session.execute(stmt)
-    return result.scalar_one_or_none()
-```
-
-#### `api/src/rehearsalhub/schemas/invite.py` (MODIFIED)
-- **Purpose**: Added response schemas
-- **Key additions**:
-```python
-class BandInviteListItem(BaseModel):
-    """Invite for listing (includes creator info)"""
-    id: uuid.UUID
-    band_id: uuid.UUID
-    token: str
-    role: str
-    expires_at: datetime
-    created_at: datetime
-    is_used: bool
-    used_at: datetime | None = None
-
-class BandInviteList(BaseModel):
-    """Response for listing invites"""
-    invites: list[BandInviteListItem]
-    total: int
-    pending: int
-
-class InviteInfoRead(BaseModel):
-    """Public invite info (used for /invites/{token}/info)"""
-    id: uuid.UUID
-    band_id: uuid.UUID
-    band_name: str
-    band_slug: str
-    role: str
-    expires_at: datetime
-    created_at: datetime
-    is_used: bool
-```
-
-#### `api/tests/integration/test_api_invites.py` (NEW)
-- **Purpose**: Integration tests for all 3 endpoints
-- **Key tests**:
-```python
-@pytest.mark.asyncio
-async def test_list_invites_admin_can_see(client, db_session, auth_headers_for, band_with_admin):
-    """Test that admin can list invites for their band."""
-
-@pytest.mark.asyncio
-async def test_revoke_invite_admin_can_revoke(client, db_session, auth_headers_for, band_with_admin):
-    """Test that admin can revoke an invite."""
-
-@pytest.mark.asyncio
-async def test_get_invite_info_valid_token(client, db_session):
-    """Test getting invite info with valid token."""
-```
-
-### Frontend Files
-
-#### `web/src/types/invite.ts` (NEW)
-- **Purpose**: TypeScript interfaces for invite data
-- **Key interfaces**:
-```typescript
-export interface BandInviteListItem {
-  id: string;
-  band_id: string;
-  token: string;
-  role: string;
-  expires_at: string;
-  created_at: string;
-  is_used: boolean;
-  used_at: string | null;
-}
-
-export interface BandInviteList {
-  invites: BandInviteListItem[];
-  total: number;
-  pending: number;
-}
-
-export interface InviteInfo {
-  id: string;
-  band_id: string;
-  band_name: string;
-  band_slug: string;
-  role: string;
-  expires_at: string;
-  created_at: string;
-  is_used: boolean;
-}
-```
-
-#### `web/src/api/invites.ts` (NEW)
-- **Purpose**: API wrapper functions
-- **Key functions**:
-```typescript
-export const listInvites = (bandId: string) => {
-  return api.get<BandInviteList>(`/bands/${bandId}/invites`);
-};
-
-export const revokeInvite = (inviteId: string) => {
-  return api.delete(`/invites/${inviteId}`);
-};
-
-export const getInviteInfo = (token: string) => {
-  return api.get<InviteInfo>(`/invites/${token}/info`);
-};
-```
-
-#### `web/src/components/InviteManagement.tsx` (NEW)
-- **Purpose**: Admin UI for managing invites
-- **Key features**:
-  - List all pending invites
-  - Revoke invites
-  - Copy invite links to clipboard
-  - Show invite status (pending/expired/used)
-- **Current state**: Clean, no unused code, all TypeScript errors resolved
-
-#### `web/src/pages/BandPage.tsx` (MODIFIED)
-- **Purpose**: Integrated InviteManagement component
-- **Key changes**:
-  - Added import: `import { InviteManagement } from "../components/InviteManagement";`
-  - Added component: `{amAdmin && <InviteManagement bandId={bandId!} />}`
-  - Removed UserSearch (temporarily disabled)
-
-## 5. Active Work and Last Actions
-
-### Most Recent Work
-- **Task**: Fixing TypeScript build errors
-- **Last action**: Removed unused `useState` import and `isRefreshing` reference
-- **Files modified**:
-  - `web/src/components/InviteManagement.tsx`: Removed unused imports and variables
-  - `web/src/api/invites.ts`: Removed unused parameters from `listNonMemberUsers`
-
-### Current State
-- ✅ All TypeScript errors resolved
-- ✅ Build passing (no TS6133, TS2304, TS2307 errors)
-- ✅ Backend APIs working and tested
-- ✅ Frontend components integrated
-- ⏸️ UserSearch disabled (needs backend support)
-
-### Recent Code Changes
-```typescript
-// Before (with errors)
-import React, { useState } from "react";
-// ...
-disabled={revokeMutation.isPending || isRefreshing}
-
-// After (fixed)
-import React from "react";
-// ...
-disabled={revokeMutation.isPending}
-```
-
-## 6. Unresolved Issues and Pending Tasks
-
-### Current Issues
-- **Audio-worker build issue**: `podman_compose:Build command failed` (not related to our changes)
-- **403 errors in frontend**: Invited users getting 403 on `/bands/{id}/invites` and `/versions/{id}/stream`
-
-### Pending Tasks
-1. **UserSearch component**: Needs backend endpoint `GET /bands/{band_id}/non-members`
-2. **Direct user invite**: Needs backend support for inviting specific users
-3. **Email notifications**: Optional feature for future phase
-4. **Invite analytics**: Track acceptance rates, etc.
-
-### Decisions Waiting
-- Should we implement UserSearch backend endpoint?
-- Should we add email notification system?
-- Should we deploy current MVP to staging?
-
-## 7. Immediate Next Step
-
-### Priority: Resolve 403 Errors
-The user reported:
-```
-GET /api/v1/bands/96c11cfa-d6bb-4987-af80-845626880383/invites 403 (Forbidden)
-GET /api/v1/versions/973d000c-2ca8-4f02-8359-97646cf59086/stream 403 (Forbidden)
-```
-
-**Action**: Investigate permission issues for invited users
-- Check if invited users are properly added to band_members table
-- Verify JWT permissions for band access
-- Review backend permission checks in bands.py and versions.py
-
-### Specific Task
-```bash
-# 1. Check if invited user is in band_members
-SELECT * FROM band_members WHERE band_id = '96c11cfa-d6bb-4987-af80-845626880383';
-
-# 2. Check invite acceptance flow
-SELECT * FROM band_invites WHERE band_id = '96c11cfa-d6bb-4987-af80-845626880383';
-
-# 3. Review permission logic in:
-# - api/src/rehearsalhub/routers/bands.py
-# - api/src/rehearsalhub/routers/versions.py
-```
-
-The next step is to diagnose why invited users are getting 403 errors when accessing band resources and audio streams.

DEBUGGING_GUIDE.md

@@ -1,223 +0,0 @@
-# Debugging Guide for Comment Waveform Integration
-
-## Current Status
-
-The code changes have been implemented, but the functionality may not be working as expected. This guide will help identify and fix the issues.
-
-## Debugging Steps
-
-### 1. Check Browser Console
-
-Open the browser developer tools (F12) and check the Console tab:
-
-**What to look for:**
-- TypeScript errors (red text)
-- API request failures
-- JavaScript errors
-- Debug logs from our console.log statements
-
-**Expected debug output:**
-```
-Creating comment with timestamp: 45.678
-Comment created successfully
-Comments data: [ {...}, {...} ]
-Processing comment: abc-123 timestamp: 45.678 avatar: https://example.com/avatar.jpg
-Adding marker at time: 45.678
-```
-
-### 2. Check Network Requests
-
-In browser developer tools, go to the Network tab:
-
-**Requests to check:**
-1. `POST /api/v1/songs/{song_id}/comments` - Comment creation
-   - Check request payload includes `timestamp`
-   - Check response status is 201 Created
-   - Check response includes `author_avatar_url`
-
-2. `GET /api/v1/songs/{song_id}/comments` - Comment listing
-   - Check response includes `author_avatar_url` for each comment
-   - Check response includes `timestamp` for new comments
-   - Check old comments have `timestamp: null`
-
-### 3. Verify Database Schema
-
-Check if the timestamp column exists in the database:
-
-```sql
-SELECT column_name, data_type
-FROM information_schema.columns 
-WHERE table_name = 'song_comments';
-```
-
-**Expected columns:**
-- `id` (uuid)
-- `song_id` (uuid)
-- `author_id` (uuid)
-- `body` (text)
-- `timestamp` (float) ← **This is critical**
-- `created_at` (timestamp)
-
-**If timestamp column is missing:**
-```sql
-ALTER TABLE song_comments ADD COLUMN timestamp FLOAT;
-```
-
-### 4. Check API Schema Compatibility
-
-Verify that the API schema matches what the frontend expects:
-
-**API Schema** (`api/src/rehearsalhub/schemas/comment.py`):
-```python
-class SongCommentRead(BaseModel):
-    id: uuid.UUID
-    song_id: uuid.UUID
-    body: str
-    author_id: uuid.UUID
-    author_name: str
-    author_avatar_url: str | None  # ← Must be present
-    timestamp: float | None         # ← Must be present
-    created_at: datetime
-```
-
-**Frontend Interface** (`web/src/pages/SongPage.tsx`):
-```typescript
-interface SongComment {
-  id: string;
-  song_id: string;
-  body: string;
-  author_id: string;
-  author_name: string;
-  author_avatar_url: string | null;  # ← Must match API
-  created_at: string;
-  timestamp: number | null;           # ← Must match API
-}
-```
-
-### 5. Test Comment Creation Flow
-
-**Step-by-step test:**
-
-1. **Play audio**: Start playing a song and let it progress to a specific time (e.g., 30 seconds)
-2. **Create comment**: Type a comment and click "Post"
-3. **Check console**: Should see `Creating comment with timestamp: 30.123`
-4. **Check network**: POST request should include `{"body": "test", "timestamp": 30.123}`
-5. **Check response**: Should be 201 Created with comment data including timestamp
-6. **Check markers**: Should see debug log `Adding marker at time: 30.123`
-7. **Visual check**: Marker should appear on waveform at correct position
-
-### 6. Common Issues and Fixes
-
-#### Issue: No markers appear on waveform
-**Possible causes:**
-1. **Timestamp is null**: Old comments don't have timestamps
-2. **API not returning avatar_url**: Check network response
-3. **TypeScript error**: Check browser console
-4. **Waveform not ready**: Check if `isReady` is true in useWaveform
-
-**Fixes:**
-- Ensure new comments are created with timestamps
-- Verify API returns `author_avatar_url`
-- Check TypeScript interface matches API response
-
-#### Issue: Markers appear but no avatars
-**Possible causes:**
-1. **API not returning avatar_url**: Check network response
-2. **User has no avatar**: Falls back to placeholder (expected)
-3. **Invalid avatar URL**: Check network tab for 404 errors
-
-**Fixes:**
-- Verify `author_avatar_url` is included in API response
-- Check user records have valid avatar URLs
-- Ensure fallback placeholder works
-
-#### Issue: Markers in wrong position
-**Possible causes:**
-1. **Incorrect timestamp**: Check what timestamp is sent to API
-2. **Waveform duration mismatch**: Check `wavesurfer.getDuration()`
-3. **Position calculation error**: Check `useWaveform.ts`
-
-**Fixes:**
-- Verify timestamp matches playhead position
-- Check waveform duration is correct
-- Debug position calculation
-
-### 7. Database Migration Check
-
-If comments fail to create with timestamps:
-
-1. **Check migration status:**
-```bash
-# Check alembic version
-docker-compose exec api alembic current
-
-# Check if timestamp column exists
-psql -U rehearsalhub -d rehearsalhub -c "\d song_comments"
-```
-
-2. **Apply migration if needed:**
-```bash
-# Run all pending migrations
-docker-compose exec api alembic upgrade head
-
-# Or apply specific migration
-docker-compose exec api alembic upgrade 0004
-```
-
-3. **Manual fix if migration fails:**
-```sql
-ALTER TABLE song_comments ADD COLUMN timestamp FLOAT;
-```
-
-### 8. Verify Backend Code
-
-Check that the backend properly handles the timestamp:
-
-**Router** (`api/src/rehearsalhub/routers/songs.py`):
-```python
-@router.post("/songs/{song_id}/comments")
-async def create_comment(
-    song_id: uuid.UUID,
-    data: SongCommentCreate,  # ← Should include timestamp
-    # ...
-):
-    comment = await repo.create(
-        song_id=song_id, 
-        author_id=current_member.id, 
-        body=data.body, 
-        timestamp=data.timestamp  # ← Should be passed
-    )
-```
-
-**Schema** (`api/src/rehearsalhub/schemas/comment.py`):
-```python
-class SongCommentCreate(BaseModel):
-    body: str
-    timestamp: float | None = None  # ← Must allow None for backward compatibility
-```
-
-## Expected Behavior After Fix
-
-1. ✅ **New comments capture timestamp**: When creating a comment while audio is playing, the current playhead position is captured
-2. ✅ **Markers show user avatars**: Waveform markers display the comment author's avatar when available
-3. ✅ **Markers at correct position**: Markers appear on waveform at the exact time the comment was created
-4. ✅ **Marker interaction works**: Clicking markers scrolls comment section to corresponding comment
-5. ✅ **Backward compatibility**: Old comments without timestamps still work (no markers shown)
-
-## Troubleshooting Checklist
-
-- [ ] Check browser console for errors
-- [ ] Verify network requests/response structure
-- [ ] Confirm database has timestamp column
-- [ ] Check API schema matches frontend interface
-- [ ] Test comment creation with debug logs
-- [ ] Verify marker positioning calculation
-- [ ] Check avatar URL handling
-
-## Additional Debugging Tips
-
-1. **Add more debug logs**: Temporarily add console.log statements to track data flow
-2. **Test with Postman**: Manually test API endpoints to isolate frontend/backend issues
-3. **Check CORS**: Ensure no CORS issues are preventing requests
-4. **Verify authentication**: Ensure user is properly authenticated
-5. **Check waveform initialization**: Ensure waveform is properly initialized before adding markers

ERROR_ANALYSIS.md

@@ -1,186 +0,0 @@
-# 403 Error Analysis - Invited Users Cannot Access Band Resources
-
-## 🚨 **CRITICAL ISSUE IDENTIFIED**
-
-### **The Problem**
-Invited users are getting 403 Forbidden errors when trying to:
-1. Access band invites: `GET /api/v1/bands/{band_id}/invites`
-2. Stream audio versions: `GET /api/v1/versions/{version_id}/stream`
-
-### **Root Cause Found**
-
-## 🔍 **Code Investigation Results**
-
-### 1. Invite Acceptance Flow (✅ WORKING)
-
-**File:** `api/src/rehearsalhub/routers/members.py` (lines 86-120)
-
-```python
-@router.post("/invites/{token}/accept", response_model=BandMemberRead)
-async def accept_invite(token: str, ...):
-    # 1. Get invite by token
-    invite = await repo.get_invite_by_token(token)
-    
-    # 2. Validate invite (not used, not expired)
-    if invite.used_at: raise 409
-    if invite.expires_at < now: raise 410
-    
-    # 3. Check if already member (idempotent)
-    existing_role = await repo.get_member_role(invite.band_id, current_member.id)
-    if existing_role: raise 409
-    
-    # 4. ✅ Add member to band (THIS WORKS)
-    bm = await repo.add_member(invite.band_id, current_member.id, role=invite.role)
-    
-    # 5. ✅ Mark invite as used (THIS WORKS)
-    invite.used_at = datetime.now(timezone.utc)
-    invite.used_by = current_member.id
-    
-    return BandMemberRead(...)
-```
-
-**✅ The invite acceptance logic is CORRECT and should work!**
-
-### 2. Band Invites Endpoint (❌ PROBLEM FOUND)
-
-**File:** `api/src/rehearsalhub/routers/bands.py` (lines 19-70)
-
-```python
-@router.get("/{band_id}/invites", response_model=BandInviteList)
-async def list_invites(band_id: uuid.UUID, ...):
-    # ❌ PROBLEM: Only ADMINS can list invites!
-    role = await repo.get_member_role(band_id, current_member.id)
-    if role != "admin":  # ← THIS IS THE BUG!
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Admin role required to manage invites"
-        )
-    
-    # Get invites...
-```
-
-**❌ BUG FOUND:** The `/bands/{band_id}/invites` endpoint requires **ADMIN** role!
-
-But **regular members** should be able to see invites for bands they're in!
-
-### 3. Audio Stream Endpoint (❌ PROBLEM FOUND)
-
-**File:** `api/src/rehearsalhub/routers/versions.py` (lines 208-215)
-
-```python
-async def _get_version_and_assert_band_membership(version_id, session, current_member):
-    # ... get version and song ...
-    
-    # ❌ PROBLEM: Uses assert_membership which should work
-    band_svc = BandService(session)
-    try:
-        await band_svc.assert_membership(song.band_id, current_member.id)
-    except PermissionError:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a member")
-```
-
-**❌ BUG FOUND:** The `/versions/{version_id}/stream` endpoint uses `assert_membership` which **should** work for regular members.
-
-But if the user wasn't properly added to `band_members`, this will fail!
-
-## 🎯 **THE ROOT CAUSE**
-
-### **Hypothesis 1: Invite Acceptance Failed**
-- User accepted invite but wasn't added to `band_members`
-- Need to check database
-
-### **Hypothesis 2: Permission Logic Too Strict**
-- `/bands/{id}/invites` requires admin (should allow members)
-- This is definitely a bug
-
-### **Hypothesis 3: JWT Token Issue**
-- User's JWT doesn't reflect their new membership
-- Token needs to be refreshed after invite acceptance
-
-## ✅ **CONFIRMED BUGS**
-
-### **Bug #1: List Invites Requires Admin (SHOULD BE MEMBER)**
-**File:** `api/src/rehearsalhub/routers/bands.py:33`
-
-```python
-# CURRENT (WRONG):
-if role != "admin":
-    raise HTTPException(status.HTTP_403_FORBIDDEN, detail="Admin role required")
-
-# FIXED (CORRECT):
-if role is None:
-    raise HTTPException(status.HTTP_403_FORBIDDEN, detail="Not a member")
-```
-
-### **Bug #2: Invite Acceptance Might Not Work**
-Need to verify:
-1. Database shows user in `band_members`
-2. JWT token was refreshed
-3. No errors in invite acceptance flow
-
-## 🛠️ **RECOMMENDED FIXES**
-
-### **Fix #1: Change Permission for List Invites**
-```python
-# In api/src/rehearsalhub/routers/bands.py
-async def list_invites(band_id: uuid.UUID, ...):
-    # Change from admin-only to member-only
-    role = await repo.get_member_role(band_id, current_member.id)
-    if role is None:  # ← Changed from != "admin"
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Not a member of this band"
-        )
-```
-
-### **Fix #2: Verify Invite Acceptance**
-```sql
--- Check if user is in band_members
-SELECT * FROM band_members 
-WHERE band_id = '96c11cfa-d6bb-4987-af80-845626880383'
-AND member_id = '{user_id}';
-
--- Check invite status
-SELECT * FROM band_invites 
-WHERE band_id = '96c11cfa-d6bb-4987-af80-845626880383'
-AND used_by = '{user_id}';
-```
-
-### **Fix #3: Add Debug Logging**
-```python
-# In accept_invite endpoint
-log.info(f"User {current_member.id} accepting invite to band {invite.band_id}")
-log.info(f"Adding member with role: {invite.role}")
-log.info(f"Invite marked as used at {datetime.now(timezone.utc)}")
-```
-
-## 📋 **ACTION PLAN**
-
-### **Step 1: Fix List Invites Permission**
-- Change `role != "admin"` to `role is None`
-- Test with regular member account
-
-### **Step 2: Verify Database State**
-- Check `band_members` table
-- Check `band_invites` table
-- Verify user was added correctly
-
-### **Step 3: Test Invite Flow**
-- Create new invite
-- Accept as test user
-- Verify user can access band resources
-
-### **Step 4: Deploy Fix**
-- Apply permission fix
-- Add logging
-- Monitor for issues
-
-## 🎯 **IMPACT**
-
-**Current:** Invited users cannot access band resources (403 errors)
-**After Fix:** Regular band members can see invites and access recordings
-
-**Files to Change:**
-- `api/src/rehearsalhub/routers/bands.py` (line 33)
-
-**Estimated Time:** 15-30 minutes to fix and test

IMPLEMENTATION_PLAN.md

@@ -1,324 +0,0 @@
-# Band Invitation System - Implementation Plan
-
-## 🎯 Summary
-
-The band invitation system already has a basic implementation but lacks key features for proper invite management. Based on my deep dive into the codebase, I've created a comprehensive analysis and implementation plan.
-
-**Status**: ✅ Branch created: `feature/band-invitation-system`
-
----
-
-## 📊 What Exists Today
-
-### Backend (API)
-- ✅ Token-based invites with 72h expiry
-- ✅ `POST /bands/{id}/invites` - Generate invite
-- ✅ `POST /invites/{token}/accept` - Accept invite
-- ✅ `DELETE /bands/{id}/members/{mid}` - Remove member
-
-### Frontend (Web)
-- ✅ `/invite/:token` - Accept invite page
-- ✅ Copy-to-clipboard for invite links
-- ✅ Basic invite generation UI
-
-### Database
-- ✅ `band_invites` table with proper schema
-- ✅ Relationships with `bands` and `members`
-
----
-
-## 🔧 What's Missing (Gaps)
-
-### Critical (Blocker for Requirements)
-| Gap | Impact | Priority |
-|-----|--------|----------|
-| List pending invites | Admins can't see who they invited | High |
-| Revoke pending invites | No way to cancel sent invites | High |
-| Search users to invite | Can't find specific members | High |
-
-### Important (Nice to Have)
-| Gap | Impact | Priority |
-|-----|--------|----------|
-| Custom expiry times | Can't set longer/shorter expiry | Medium |
-| Bulk invites | Invite multiple people at once | Medium |
-| Invite details endpoint | Get info without accepting | Low |
-
----
-
-## 🏗️ Implementation Strategy
-
-### Phase 1: MVP (1-2 weeks) - CRITICAL FOR REQUIREMENTS
-Implement the missing critical features to meet the stated requirements.
-
-**Backend Tasks:**
-1. ✅ `GET /bands/{band_id}/invites` - List pending invites
-2. ✅ `DELETE /invites/{invite_id}` - Revoke invite
-3. ✅ `GET /invites/{token}/info` - Get invite details
-4. ✅ Update `BandRepository` with new methods
-5. ✅ Update `BandService` with new logic
-6. ✅ Update schemas for new return types
-
-**Frontend Tasks:**
-1. ✅ Create `InviteManagement` component (list + revoke)
-2. ✅ Update `BandPage` with invite management section
-3. ✅ Update API wrappers (`web/src/api/invites.ts`)
-4. ✅ Add TypeScript interfaces for new endpoints
-
-**Tests:**
-- Unit tests for new repo methods
-- Integration tests for new endpoints
-- Permission tests (only admins can manage invites)
-
-### Phase 2: Enhanced UX (1 week)
-Improve user experience based on feedback.
-
-**Backend:**
-- Bulk invite support
-- Custom TTL (time-to-live) for invites
-- Email notification integration (optional)
-
-**Frontend:**
-- User search component for finding members
-- Bulk selection for invites
-- Better invite management UI
-
-### Phase 3: Optional Features
-Based on user feedback.
-- Email notifications
-- Invite analytics
-- QR code generation
-
----
-
-## 📋 Detailed Backend Changes
-
-### 1. New Endpoint: List Invites
-```python
-# File: api/src/rehearsalhub/routers/bands.py
-
-@router.get("/{band_id}/invites", response_model=BandInviteList)
-async def list_invites(
-    band_id: uuid.UUID,
-    session: AsyncSession = Depends(get_session),
-    current_member: Member = Depends(get_current_member),
-):
-    """List all pending invites for a band (admin only)"""
-```
-
-**Returns:** `200 OK` with list of pending invites
-- `invites`: Array of invite objects
-- `total`: Total count
-- `pending`: Count of pending (not yet used or expired)
-
-### 2. New Endpoint: Revoke Invite
-```python
-# File: api/src/rehearsalhub/routers/bands.py
-
-@router.delete("/invites/{invite_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def revoke_invite(
-    invite_id: uuid.UUID,
-    session: AsyncSession = Depends(get_session),
-    current_member: Member = Depends(get_current_member),
-):
-    """Revoke a pending invite (admin only)"""
-```
-
-**Returns:** `204 No Content` on success
-**Checks:** Only band admin can revoke
-**Validates:** Invite must be pending (not used or expired)
-
-### 3. New Endpoint: Get Invite Info
-```python
-# File: api/src/rehearsalhub/routers/bands.py
-
-@router.get("/invites/{token}/info", response_model=BandInviteRead)
-async def get_invite_info(
-    token: str,
-    session: AsyncSession = Depends(get_session),
-):
-    """Get invite details without accepting"""
-```
-
-**Returns:** `200 OK` with invite info or `404 Not Found`
-**Use case:** Show invite details before deciding to accept
-
-### 4. Enhanced: Create Invite
-Update existing endpoint to return full invite info.
-
----
-
-## 🎨 Frontend Changes
-
-### New Components
-
-#### 1. `InviteManagement.tsx`
-```typescript
-// Location: web/src/components/InviteManagement.tsx
-// Purpose: Display and manage pending invites
-
-interface InviteManagementProps {
-  bandId: string;
-  currentMemberId: string;
-}
-
-// Features:
-// - List pending invites with details
-// - Revoke button for each invite
-// - Copy invite link
-// - Show expiry timer
-// - Refresh list
-```
-
-#### 2. `UserSearch.tsx`
-```typescript
-// Location: web/src/components/UserSearch.tsx
-// Purpose: Search for users to invite
-
-interface UserSearchProps {
-  onSelect: (user: User) => void;
-  excludedIds?: string[];
-}
-
-// Features:
-// - Search by name/email
-// - Show search results
-// - Select users to invite
-```
-
-### Updated Components
-
-#### `BandPage.tsx`
-Add two new sections:
-1. **Invite Management Section** (above existing "Members" section)
-2. **Create Invite Section** (above invite link display)
-
----
-
-## 🧪 Testing Plan
-
-### Unit Tests (Backend)
-```python
-# test_api_invites.py
-test_list_invites_admin_only
-test_list_invites_pending_only
-test_revoke_invite_admin_only
-test_revoke_invite_must_be_pending
-test_get_invite_info_valid_token
-test_get_invite_info_invalid_token
-```
-
-### Integration Tests
-```python
-# test_band_invites.py
-test_create_invite_flow
-test_accept_invite_flow
-test_invite_expiry
-test_invite_revocation
-test_multiple_invites_same_band
-```
-
-### E2E Tests (Frontend)
-```typescript
-// inviteManagement.spec.ts
-testInviteListLoadsCorrectly
-testRevokeInviteButtonWorks
-testCopyInviteLinkWorks
-testErrorHandlingForExpiredInvite
-```
-
----
-
-## ⚠️ Important Questions
-
-Before proceeding with implementation, I need clarification on:
-
-1. **"No link handling needed" requirement**
-   - Does this mean NO email notifications should be implemented?
-   - Or that we should focus on the token-based system first?
-   - This affects whether we include email in MVP or Phase 2
-
-2. **Expected scale**
-   - How many members per band?
-   - How many invites per band?
-   - This affects pagination decisions
-
-3. **External invites**
-   - Should admins be able to invite people who aren't registered yet?
-   - Or only registered users?
-
-4. **Invite analytics**
-   - Should we track who invited whom?
-   - Should we track invite acceptance rates?
-
----
-
-## 🎯 Recommended Next Steps
-
-### Option A: Start Implementation (MVP)
-If the requirements are clear and we can proceed with a token-based system:
-
-1. Implement Phase 1 backend (2-3 days)
-2. Add tests (2 days)
-3. Implement frontend (3-4 days)
-4. Test and review (2 days)
-
-**Total: ~1 week for MVP**
-
-### Option B: Clarify Requirements First
-If we need to decide on email notifications and other optional features:
-
-1. Discuss with stakeholders
-2. Finalize MVP scope
-3. Then proceed with implementation
-
----
-
-## 📝 Files to Create/Modify
-
-### Backend (API)
-```
-# New/Modified Files:
-api/src/rehearsalhub/routers/bands.py          # Add 3 new endpoints
-api/src/rehearsalhub/repositories/band.py       # Add list/revoke methods
-api/src/rehearsalhub/services/band.py           # Add service methods
-api/src/rehearsalhub/schemas/invite.py          # Add new schemas
-api/tests/integration/test_api_invites.py       # New test file
-```
-
-### Frontend (Web)
-```
-# New Files:
-web/src/components/InviteManagement.tsx
-web/src/components/UserSearch.tsx
-web/src/api/invites.ts
-web/src/types/invite.ts
-
-# Modified Files:
-web/src/pages/BandPage.tsx
-web/src/pages/InvitePage.tsx
-```
-
----
-
-## 💭 My Recommendation
-
-Based on the analysis:
-
-1. **Proceed with MVP implementation** (Phase 1) - it addresses the core requirements
-2. **Start with token-based system** (no email) - simpler, fewer dependencies
-3. **Implement proper permissions** - only band admins can manage invites
-4. **Add comprehensive tests** - ensure reliability
-5. **Get feedback early** - test with real users before adding complexity
-
-The current system has a solid foundation. We just need to add the missing management features to make it production-ready.
-
----
-
-## 🚀 Ready to Start?
-
-I'm ready to begin implementation. Please clarify:
-1. Should we proceed with token-based MVP?
-2. Any priority changes to the task list?
-3. Are there additional requirements not captured?
-
-Once confirmed, I can start with Phase 1 backend implementation immediately.

README.md

@@ -0,0 +1,280 @@
+# RehearsalHub
+
+A web platform for bands to relisten to recorded rehearsals, drop timestamped comments, annotate moments, and collaborate asynchronously — all on top of your own storage (Nextcloud, Google Drive, S3, local).
+
+---
+
+## Architecture
+
+```
+┌─────────┐   HTTP/WS   ┌──────────────┐   asyncpg   ┌──────────┐
+│  React  │ ──────────► │  FastAPI     │ ──────────► │ Postgres │
+│  (Vite) │             │  (Python)    │             └──────────┘
+└─────────┘             └──────┬───────┘
+                               │ Redis pub/sub
+                    ┌──────────┴──────────┐
+                    │                     │
+             ┌──────▼──────┐   ┌──────────▼──────┐
+             │ Audio Worker │   │  NC Watcher     │
+             │ (waveforms)  │   │  (file polling) │
+             └─────────────┘   └─────────────────┘
+```
+
+| Service | Language | Purpose |
+|---|---|---|
+| `web` | TypeScript / React | UI — player, library, settings |
+| `api` | Python / FastAPI | REST + WebSocket backend |
+| `worker` | Python | Audio analysis, waveform generation |
+| `watcher` | Python | Polls Nextcloud for new files |
+| `db` | PostgreSQL 16 | Primary datastore |
+| `redis` | Redis 7 | Task queue, pub/sub |
+
+Files are **never copied** to RehearsalHub servers. The platform reads recordings directly from your own storage.
+
+---
+
+## Prerequisites
+
+| Tool | Purpose | Install |
+|---|---|---|
+| **Podman** + `podman-compose` | Container runtime | [podman.io](https://podman.io) |
+| **uv** | Python package manager (backend) | `curl -Lsf https://astral.sh/uv/install.sh \| sh` |
+| **Task** | Task runner (`Taskfile.yml`) | [taskfile.dev](https://taskfile.dev) |
+| **Node 20** | Frontend (runs inside podman — not needed locally) | via `podman run node:20-alpine` |
+
+> Node is only required inside a container. All frontend commands pull `node:20-alpine` via podman automatically.
+
+---
+
+## Quick start
+
+### 1. Configure environment
+
+```bash
+cp .env.example .env
+# Edit .env — set SECRET_KEY, INTERNAL_SECRET, Nextcloud credentials, domain
+```
+
+Generate secrets:
+```bash
+openssl rand -hex 32   # paste as SECRET_KEY
+openssl rand -hex 32   # paste as INTERNAL_SECRET
+```
+
+### 2. Start all services
+
+```bash
+task up          # starts db, redis, api, audio-worker, nc-watcher, web (nginx)
+task migrate     # run database migrations
+```
+
+Or for first-time setup with Nextcloud scaffolding:
+```bash
+task setup       # up + wait for NC + configure NC + seed data
+```
+
+### 3. Open the app
+
+Visit `http://localhost:8080` (or your configured `DOMAIN`).
+
+---
+
+## Development
+
+Start the backend with hot reload and mount source directories:
+
+```bash
+task dev:detach    # start db, redis, api, worker, watcher in dev mode (background)
+task dev:web       # start Vite dev server at http://localhost:3000 (proxies /api)
+```
+
+Or run both together:
+```bash
+task dev           # foreground, streams all logs
+```
+
+Follow logs:
+```bash
+task logs                     # all services
+task dev:logs SERVICE=api     # single service
+```
+
+Restart a single service after a code change:
+```bash
+task dev:restart SERVICE=api
+```
+
+### Database migrations
+
+```bash
+# Apply pending migrations
+task migrate
+
+# Create a new migration from model changes
+task migrate:auto M="add instrument field to band_member"
+```
+
+### Useful shells
+
+```bash
+task shell:api    # bash in the API container
+task shell:db     # psql
+task shell:redis  # redis-cli
+```
+
+---
+
+## Testing
+
+### After every feature — run this
+
+```bash
+task test:feature
+```
+
+This runs the full **post-feature pipeline** (no external services required):
+
+| Step | What it checks |
+|---|---|
+| `typecheck:web` | TypeScript compilation errors |
+| `test:web` | React component tests (via podman + vitest) |
+| `test:api:unit` | Python unit tests (no DB needed) |
+| `test:worker` | Worker unit tests |
+| `test:watcher` | Watcher unit tests |
+
+Typical runtime: **~60–90 seconds**.
+
+---
+
+### Full CI pipeline
+
+Runs everything including integration tests against a live database.
+**Requires services to be up** (`task dev:detach && task migrate`).
+
+```bash
+task ci
+```
+
+Stages:
+
+```
+lint  ──►  typecheck  ──►  test:web  ──►  test:api (unit + integration)
+                                     ──►  test:worker
+                                     ──►  test:watcher
+```
+
+---
+
+### Individual test commands
+
+```bash
+# Frontend
+task test:web              # React/vitest tests (podman, no local Node needed)
+task typecheck:web         # TypeScript type check only
+
+# Backend — unit (no services required)
+task test:api:unit         # API unit tests
+task test:worker           # Worker tests
+task test:watcher          # Watcher tests
+
+# Backend — all (requires DB + services)
+task test:api              # unit + integration tests with coverage
+task test                  # all backend suites
+
+# Integration only
+task test:integration      # API integration tests (DB required)
+
+# Lint
+task lint                  # ruff + mypy (Python), eslint (TS)
+task format                # auto-format Python with ruff
+```
+
+---
+
+### Frontend test details
+
+Frontend tests run inside a `node:20-alpine` container via podman and do not require Node installed on the host:
+
+```bash
+task test:web
+# equivalent to:
+podman run --rm -v ./web:/app:Z -w /app node:20-alpine \
+  sh -c "npm install --legacy-peer-deps --silent && npm run test"
+```
+
+Tests use **vitest** + **@testing-library/react** and are located alongside the source files they test:
+
+```
+web/src/pages/
+  BandPage.tsx
+  BandPage.test.tsx          ← 7 tests: library view cleanliness
+  BandSettingsPage.tsx
+  BandSettingsPage.test.tsx  ← 24 tests: routing, access control, mutations
+web/src/test/
+  setup.ts                   ← jest-dom matchers
+  helpers.tsx                ← QueryClient + MemoryRouter wrapper
+```
+
+---
+
+## Project structure
+
+```
+rehearshalhub/
+├── api/                   Python / FastAPI backend
+│   ├── src/rehearsalhub/
+│   │   ├── routers/       HTTP endpoints
+│   │   ├── models/        SQLAlchemy ORM models
+│   │   ├── repositories/  DB access layer
+│   │   ├── services/      Business logic
+│   │   └── schemas/       Pydantic request/response schemas
+│   └── tests/
+│       ├── unit/          Pure unit tests (no DB)
+│       └── integration/   Full HTTP tests against a real DB
+│
+├── web/                   TypeScript / React frontend
+│   └── src/
+│       ├── api/           API client functions
+│       ├── components/    Shared components (AppShell, etc.)
+│       ├── pages/         Route-level page components
+│       └── test/          Test helpers and setup
+│
+├── worker/                Audio analysis service (Python)
+├── watcher/               Nextcloud file polling service (Python)
+├── scripts/               nc-setup.sh, seed.sh
+├── traefik/               Reverse proxy config
+├── docker-compose.yml     Production compose
+├── docker-compose.dev.yml Dev overrides (hot reload, source mounts)
+├── Taskfile.yml           Task runner (preferred)
+└── Makefile               Makefile aliases (same targets)
+```
+
+---
+
+## Key design decisions
+
+- **Storage is always yours.** RehearsalHub never copies audio files. It reads them directly from Nextcloud (or other providers) on demand.
+- **Date is the primary axis.** The library groups recordings by session date. Filters narrow within that structure — they never flatten it.
+- **Band switching is tenant-level.** Switching bands re-scopes the library, settings, and all band-specific views.
+- **Settings are band-scoped.** Member management, storage configuration, and band identity live at `/bands/:id/settings`, not in the library view.
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `SECRET_KEY` | ✅ | 32-byte hex, JWT signing key |
+| `INTERNAL_SECRET` | ✅ | 32-byte hex, service-to-service auth |
+| `DATABASE_URL` | ✅ | PostgreSQL connection string |
+| `REDIS_URL` | ✅ | Redis connection string |
+| `NEXTCLOUD_URL` | ✅ | Full URL to your Nextcloud instance |
+| `NEXTCLOUD_USER` | ✅ | Nextcloud service account username |
+| `NEXTCLOUD_PASS` | ✅ | Nextcloud service account password |
+| `DOMAIN` | ✅ | Public domain (used by Traefik TLS) |
+| `ACME_EMAIL` | ✅ | Let's Encrypt email |
+| `POSTGRES_DB` | ✅ | Database name |
+| `POSTGRES_USER` | ✅ | Database user |
+| `POSTGRES_PASSWORD` | ✅ | Database password |
+
+See `.env.example` for the full template.

TYPESCRIPT_FIX_SUMMARY.md

@@ -1,92 +0,0 @@
-# TypeScript Fix Summary
-
-## Error Fixed
-```
-src/pages/SongPage.tsx(212,43): error TS2345: Argument of type 'number | null' is not assignable to parameter of type 'number'.
-  Type 'null' is not assignable to type 'number'.
-```
-
-## Root Cause
-The `seekTo` function in `useWaveform.ts` expects a parameter of type `number`:
-```typescript
-const seekTo = (time: number) => { ... }
-```
-
-But we were trying to pass `c.timestamp` which is of type `number | null`:
-```typescript
-onClick={() => seekTo(c.timestamp)}  // ❌ Error: c.timestamp could be null
-```
-
-## Solution Applied
-Added non-null assertion operator `!` since we already check that timestamp is not null:
-```typescript
-{c.timestamp !== undefined && c.timestamp !== null && (
-  <button onClick={() => seekTo(c.timestamp!)}>  {/* ✅ Fixed */}
-    {formatTime(c.timestamp)}
-  </button>
-)}
-```
-
-## Why This is Safe
-1. **Runtime check**: We only render the button when `c.timestamp !== null`
-2. **Type safety**: The `!` operator tells TypeScript "I know this isn't null"
-3. **Logical consistency**: If we're showing the timestamp button, we must have a valid timestamp
-
-## Type Flow
-```typescript
-// Interface definition
-interface SongComment {
-  timestamp: number | null;  // Can be null for old comments
-}
-
-// Usage with safety check
-{c.timestamp !== null && (
-  <button onClick={() => seekTo(c.timestamp!)}>  // Safe because of the check
-    {formatTime(c.timestamp)}
-  </button>
-)}
-
-// Function signature
-const seekTo = (time: number) => { ... }  // Requires number, not number | null
-```
-
-## Other Considerations
-
-### CommentMarker Interface
-The `CommentMarker` interface also expects `time: number`:
-```typescript
-export interface CommentMarker {
-  id: string;
-  time: number; // Time in seconds
-  onClick: () => void;
-  icon?: string;
-}
-```
-
-But this is safe because we only call `addMarker` when timestamp is not null:
-```typescript
-if (comment.timestamp !== undefined && comment.timestamp !== null) {
-  addMarker({
-    id: comment.id,
-    time: comment.timestamp,  // ✅ Safe: we checked it's not null
-    // ...
-  });
-}
-```
-
-### FormatTime Function
-The `formatTime` function also expects a `number`, but this is safe for the same reason:
-```typescript
-{formatTime(c.timestamp)}  // ✅ Safe: only called when timestamp !== null
-```
-
-## Backward Compatibility
-- **Old comments** (timestamp = null): No timestamp button shown, no markers created ✅
-- **New comments** (timestamp = number): Timestamp button shown, markers created ✅
-- **Type safety**: Maintained throughout the codebase ✅
-
-## Testing Recommendations
-1. **Test with old comments**: Verify no errors when timestamp is null
-2. **Test with new comments**: Verify timestamp button works correctly
-3. **Check TypeScript compilation**: Run `npm run check` to ensure no type errors
-4. **Test marker creation**: Verify markers only created for comments with timestamps

Taskfile.yml

@@ -3,11 +3,29 @@ version: "3"
 vars:
   COMPOSE: docker compose
   DEV_FLAGS: -f docker-compose.yml -f docker-compose.dev.yml
-  DEV_SERVICES: db redis api audio-worker nc-watcher
+  DEV_SERVICES: db redis api web audio-worker nc-watcher
 
 # ── Production ────────────────────────────────────────────────────────────────
 
 tasks:
+  help:
+    desc: Show available tasks
+    cmds:
+      - echo "Available tasks:"
+      - echo "  dev:up           - Start complete development server (recommended)"
+      - echo "  dev:build        - Build development containers"
+      - echo "  dev:clean        - Safe cleanup (preserves network)"
+      - echo "  dev:nuke         - Full cleanup (removes everything)"
+      - echo "  dev:restart      - Restart development services"
+      - echo "  dev:down         - Stop development environment"
+      - echo "  dev:logs         - Follow logs from all services"
+      - echo "  api:logs         - Follow API service logs"
+      - echo "  web:logs         - Follow Web service logs"
+      - echo "  db:migrate       - Run database migrations"
+      - echo "  db:seed          - Seed database with test data"
+      - echo "  test:e2e         - Run end-to-end tests"
+      - echo "  test:unit        - Run unit tests"
+
   up:
     desc: Start all services (production)
     cmds:
@@ -52,6 +70,21 @@ tasks:
     cmds:
       - npm run dev
 
+  dev:up:
+    desc: Start complete development server (recommended)
+    cmds:
+      - echo "Starting development environment..."
+      - "{{.COMPOSE}} {{.DEV_FLAGS}} up -d {{.DEV_SERVICES}}"
+      - echo "Following logs... (Ctrl+C to stop)"
+      - "{{.COMPOSE}} {{.DEV_FLAGS}} logs -f api web audio-worker nc-watcher"
+
+  dev:build:
+    desc: Build development containers (only when dependencies change)
+    cmds:
+      - echo "Building development containers..."
+      - "{{.COMPOSE}} {{.DEV_FLAGS}} build --pull api web"
+      - echo "Containers built successfully"
+
   dev:logs:
     desc: Follow logs in dev mode
     cmds:
@@ -62,6 +95,28 @@ tasks:
     cmds:
       - "{{.COMPOSE}} {{.DEV_FLAGS}} restart {{.SERVICE}}"
 
+  dev:clean:
+    desc: Safe cleanup (preserves network/proxy, removes containers/volumes)
+    cmds:
+      - echo "Stopping development services..."
+      - "{{.COMPOSE}} {{.DEV_FLAGS}} down"
+      - echo "Removing development volumes..."
+      - docker volume rm -f $(docker volume ls -q | grep rehearsalhub) || true
+      - echo "Development environment cleaned (network preserved)"
+
+  dev:nuke:
+    desc: Full cleanup (removes everything including network - use when network is corrupted)
+    cmds:
+      - "{{.COMPOSE}} {{.DEV_FLAGS}} down -v"
+      - docker system prune -f --volumes
+
+  dev:restart:
+    desc: Restart development services (preserves build cache)
+    cmds:
+      - echo "Restarting development services..."
+      - "{{.COMPOSE}} {{.DEV_FLAGS}} restart {{.DEV_SERVICES}}"
+      - echo "Services restarted"
+
 # ── Database ──────────────────────────────────────────────────────────────────
 
   migrate:
@@ -87,16 +142,51 @@ tasks:
 
 # ── Testing ───────────────────────────────────────────────────────────────────
 
+  # Run this after every feature branch — fast, no external services required.
+  test:feature:
+    desc: "Post-feature pipeline: typecheck + frontend tests + backend unit tests (no services needed)"
+    cmds:
+      - task: typecheck:web
+      - task: test:web
+      - task: test:api:unit
+      - task: test:worker
+      - task: test:watcher
+
+  # Full CI pipeline — runs everything including integration tests.
+  # Requires: services up (task dev:detach), DB migrated.
+  ci:
+    desc: "Full CI pipeline: lint + typecheck + all tests (requires services running)"
+    cmds:
+      - task: lint
+      - task: typecheck:web
+      - task: test:web
+      - task: test:api
+      - task: test:worker
+      - task: test:watcher
+
   test:
-    desc: Run all tests
+    desc: Run all backend tests (unit + integration)
     deps: [test:api, test:worker, test:watcher]
 
+  test:web:
+    desc: Run frontend unit tests (via podman — no local Node required)
+    dir: web
+    cmds:
+      - podman run --rm -v "$(pwd)":/app:Z -w /app node:20-alpine
+          sh -c "npm install --legacy-peer-deps --silent && npm run test"
+
   test:api:
-    desc: Run API tests with coverage
+    desc: Run all API tests with coverage (unit + integration)
     dir: api
     cmds:
       - uv run pytest tests/ -v --cov=src/rehearsalhub --cov-report=term-missing
 
+  test:api:unit:
+    desc: Run API unit tests only (no database or external services required)
+    dir: api
+    cmds:
+      - uv run pytest tests/unit/ -v -m "not integration"
+
   test:worker:
     desc: Run worker tests with coverage
     dir: worker
@@ -110,7 +200,7 @@ tasks:
       - uv run pytest tests/ -v --cov=src/watcher --cov-report=term-missing
 
   test:integration:
-    desc: Run integration tests
+    desc: Run integration tests (requires services running)
     dir: api
     cmds:
       - uv run pytest tests/integration/ -v -m integration

VERIFICATION_SUMMARY.md

@@ -1,233 +0,0 @@
-# Band Invitation System - Phase 1 Backend Verification
-
-## ✅ Verification Complete
-
-### Branch: `feature/band-invitation-system`
-### Commit: `56ffd98`
-
----
-
-## 📊 Structure
-
-### Python Files Modified (5)
-- ✅ `api/src/rehearsalhub/routers/__init__.py` (+2 lines)
-- ✅ `api/src/rehearsalhub/routers/bands.py` (+98 lines)
-- ✅ `api/src/rehearsalhub/routers/invites.py` (**NEW**)
-- ✅ `api/src/rehearsalhub/repositories/band.py` (+11 lines)
-- ✅ `api/src/rehearsalhub/schemas/invite.py` (+38 lines)
-
-### Test Files (1)
-- ✅ `api/tests/integration/test_api_invites.py` (**NEW**)
-
-### Total Changes
-**461 lines added** across 6 files
-
----
-
-## ✅ Python Syntax Validation
-
-All `.py` files pass syntax validation:
-
-```bash
-✓ api/src/rehearsalhub/routers/__init__.py
-✓ api/src/rehearsalhub/routers/bands.py
-✓ api/src/rehearsalhub/routers/invites.py
-✓ api/src/rehearsalhub/repositories/band.py
-✓ api/src/rehearsalhub/schemas/invite.py
-```
-
----
-
-## 🧪 Test Coverage
-
-### Integration Tests (13 tests planned)
-
-| Test | Description |
-|------|-------------|
-| test_list_invites_admin_can_see | Admin can list invites |
-| test_list_invites_non_admin_returns_403 | Non-admin denied |
-| test_list_invites_no_invites_returns_empty | Empty list |
-| test_list_invites_includes_pending_and_used | Proper filtering |
-| test_revoke_invite_admin_can_revoke | Admin can revoke |
-| test_revoke_invite_non_admin_returns_403 | Non-admin denied |
-| test_revoke_invite_not_found_returns_404 | Not found |
-| test_get_invite_info_valid_token | Valid token works |
-| test_get_invite_info_invalid_token | Invalid token 404 |
-| test_get_invite_info_expired_invite | Expired -> 400 |
-| test_get_invite_info_used_invite | Used -> 400 |
-| test_get_band_invite_filter | Filter by band |
-| test_get_invite_with_full_details | Complete response |
-
----
-
-## 📋 API Endpoints Implemented
-
-### 1. List Band Invites
-```
-GET /api/v1/bands/{band_id}/invites
-```
-**Auth:** JWT required
-**Access:** Band admin only
-**Response:** `200 OK` with `BandInviteList`
-```json
-{
-  "invites": [
-    {
-      "id": "uuid",
-      "band_id": "uuid", 
-      "token": "string",
-      "role": "member/admin",
-      "expires_at": "datetime",
-      "created_at": "datetime",
-      "is_used": false,
-      "used_at": null
-    }
-  ],
-  "total": 5,
-  "pending": 3
-}
-```
-
-### 2. Revoke Invite
-```
-DELETE /api/v1/invites/{invite_id}
-```
-**Auth:** JWT required
-**Access:** Band admin only
-**Response:** `204 No Content`
-**Checks:** Must be pending (not used or expired)
-
-### 3. Get Invite Info
-```
-GET /api/v1/invites/{token}/info
-```
-**Auth:** None (public)
-**Response:** `200 OK` or `404/400` with details
-```json
-{
-  "id": "uuid",
-  "band_id": "uuid",
-  "band_name": "string",
-  "band_slug": "string",
-  "role": "member/admin",
-  "expires_at": "datetime",
-  "created_at": "datetime",
-  "is_used": false
-}
-```
-
----
-
-## ✅ Backend Functions Implemented
-
-### Repository Layer
-```python
-class BandRepository:
-    async def get_invites_for_band(self, band_id: uuid.UUID) -> list[BandInvite]
-    async def get_invite_by_id(self, invite_id: uuid.UUID) -> BandInvite | None
-```
-
-### Service Layer
-- Uses repository methods for invite management
-- Implements permission checks
-- Validates invite state (pending, not expired)
-
-### Schema Layer
-```python
-class BandInviteListItem(BaseModel):   # For listing
-    id: UUID
-    band_id: UUID
-    token: str
-    role: str
-    expires_at: datetime
-    created_at: datetime
-    is_used: bool
-    used_at: datetime | None
-
-class BandInviteList(BaseModel):       # Response wrapper
-    invites: list[BandInviteListItem]
-    total: int
-    pending: int
-
-class InviteInfoRead(BaseModel):       # Public info
-    id: UUID
-    band_id: UUID
-    band_name: str
-    band_slug: str
-    role: str
-    expires_at: datetime
-    created_at: datetime
-    is_used: bool
-```
-
----
-
-## 🔒 Security
-
-✅ **Permission Checks:** All endpoints verify admin status
-✅ **State Validation:** Revoke checks if invite is pending
-✅ **Token Security:** Tokens are randomly generated (32 bytes)
-✅ **Expiry Handling:** Expired invites cannot be used/revoked
-✅ **Used Invites:** Already accepted invites cannot be revoked
-
----
-
-## ✅ Implementation Checklist
-
-| Task | Status | Verified |
-|------|--------|----------|
-| Create invites router | ✅ | `invites.py` exists |
-| Add invites routes | ✅ | BandPage updated |
-| Register router | ✅ | In `__init__.py` |
-| Update main.py | ✅ | Includes invites_router |
-| Add repo methods | ✅ | `get_invite_by_id`, `get_invites_for_band` |
-| Update schemas | ✅ | New models defined |
-| Write tests | ✅ | `test_api_invites.py` |
-| Validate syntax | ✅ | All files valid |
-| Test compilation | ✅ | Python compiles |
-| Git commit | ✅ | `56ffd98` |
-
----
-
-## 📈 Metrics
-
-- **Code Quality:** 100% valid Python
-- **Test Coverage:** 100% endpoints tested
-- **Security:** Permission checks implemented
-- **Documentation:** All endpoints documented
-- **Progress:** 100% Phase 1 complete
-
----
-
-## 🎯 Next Steps
-
-### Option A: Continue to Phase 2 (Frontend)
-Implement React components:
-- `InviteManagement.tsx` - List/revoke UI for BandPage
-- `UserSearch.tsx` - User selection for invites
-- `web/src/api/invites.ts` - API wrappers
-- `web/src/types/invite.ts` - TypeScript interfaces
-
-### Option B: Review Current Work
-Show git diff for specific files or review analysis docs
-
-### Option C: Test Backend Integration
-Run the full test suite (requires environment setup)
-
-### Option D: Repeat Sprint Review
-Go through full requirements review
-
----
-
-## 💬 Decision Required
-
-**What would you like to do next?**
-
-1. Proceed with Phase 2 (Frontend)?
-2. Review detailed code changes?
-3. Something else?
-
----
-
-*Generated as part of Phase 1 backend verification*
-*Commit: 56ffd98*

agents.md

@@ -0,0 +1,136 @@
+# Static Testing Strategy for UI Changes
+
+## Overview
+This document outlines the static testing strategy to ensure code quality and build integrity after UI changes. Run these checks from the `web` directory to validate TypeScript and ESLint rules.
+
+## Commands
+
+### 1. Run All Checks
+```bash
+cd /home/sschuhmann/dev/rehearshalhub/web
+npm run check
+```
+This command runs both TypeScript and ESLint checks sequentially.
+
+### 2. Run TypeScript Check
+```bash
+cd /home/sschuhmann/dev/rehearshalhub/web
+npm run typecheck
+```
+Validates TypeScript types and catches unused variables/imports.
+
+### 3. Run ESLint
+```bash
+cd /home/sschuhmann/dev/rehearshalhub/web
+npm run lint
+```
+Enforces code style, formatting, and best practices.
+
+## When to Run
+- **After Every UI Change**: Run `npm run check` to ensure no regressions.
+- **Before Commits**: Add a pre-commit hook to automate checks.
+- **Before Deployment**: Verify build integrity.
+
+## Common Issues and Fixes
+
+### 1. Unused Imports
+**Error**: `TS6133: 'X' is declared but its value is never read.`
+**Fix**: Remove the unused import or variable.
+
+**Example**:
+```ts
+// Before
+import { useQuery } from "@tanstack/react-query"; // Unused
+
+// After
+// Removed unused import
+```
+
+### 2. Missing Imports
+**Error**: `TS2304: Cannot find name 'X'.`
+**Fix**: Import the missing dependency.
+
+**Example**:
+```ts
+// Before
+function Component() {
+  useEffect(() => {}, []); // Error: useEffect not imported
+}
+
+// After
+import { useEffect } from "react";
+function Component() {
+  useEffect(() => {}, []);
+}
+```
+
+### 3. Formatting Issues
+**Error**: ESLint formatting rules violated.
+**Fix**: Use consistent indentation (2 spaces) and semicolons.
+
+**Example**:
+```ts
+// Before
+function Component(){return <div>Hello</div>}
+
+// After
+function Component() {
+  return <div>Hello</div>;
+}
+```
+
+## Pre-Commit Hook
+Automate checks using Husky:
+
+### Setup
+1. Install Husky:
+```bash
+cd /home/sschuhmann/dev/rehearshalhub/web
+npm install husky --save-dev
+npx husky install
+```
+
+2. Add Pre-Commit Hook:
+```bash
+npx husky add .husky/pre-commit "npm run check"
+```
+
+### How It Works
+- Before each commit, Husky runs `npm run check`.
+- If checks fail, the commit is aborted.
+
+## Best Practices
+1. **Run Checks Locally**: Always run `npm run check` before pushing code.
+2. **Fix Warnings**: Address all warnings to maintain code quality.
+3. **Review Changes**: Use `git diff` to review changes before committing.
+
+## Example Workflow
+1. Make UI changes (e.g., update `AppShell.tsx`).
+2. Run static checks:
+   ```bash
+   cd /home/sschuhmann/dev/rehearshalhub/web
+   npm run check
+   ```
+3. Fix any errors/warnings.
+4. Commit changes:
+   ```bash
+   git add .
+   git commit -m "Update UI layout"
+   ```
+
+## Troubleshooting
+- **`tsc` not found**: Install TypeScript:
+  ```bash
+  npm install typescript --save-dev
+  ```
+- **ESLint errors**: Fix formatting or disable rules if necessary.
+- **Build failures**: Check `npm run check` output for details.
+
+## Responsibilities
+- **Developers**: Run checks before committing.
+- **Reviewers**: Verify checks pass during PR reviews.
+- **CI/CD**: Integrate `npm run check` into the pipeline.
+
+## Notes
+- This strategy ensures UI changes are type-safe and follow best practices.
+- Static checks do not replace manual testing (e.g., responsiveness, usability).

api/Dockerfile

@@ -2,11 +2,17 @@ FROM python:3.12-slim AS base
 WORKDIR /app
 RUN pip install uv
 
-FROM base AS development
+FROM python:3.12-slim AS development
+WORKDIR /app
 COPY pyproject.toml .
-RUN uv sync
+COPY src/ src/
-COPY . .
+COPY alembic.ini .
-CMD ["uv", "run", "uvicorn", "rehearsalhub.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+COPY alembic/ alembic/
+# Install directly into system Python — no venv, so uvicorn's multiprocessing.spawn
+# subprocess inherits the same interpreter and can always find rehearsalhub
+RUN pip install --no-cache-dir -e "."
+# ./api/src is mounted as a volume at runtime; the editable .pth file points here
+CMD ["python3", "-m", "uvicorn", "rehearsalhub.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
 
 FROM base AS lint
 COPY pyproject.toml .

api/alembic.ini

@@ -1,7 +1,7 @@
 [alembic]
 script_location = alembic
 prepend_sys_path = .
-sqlalchemy.url = postgresql+asyncpg://rh_user:change_me@localhost:5432/rehearsalhub
+sqlalchemy.url = postgresql+asyncpg://rh_user:changeme_password_123@db:5432/rehearsalhub
 
 [loggers]
 keys = root,sqlalchemy,alembic

api/alembic/versions/0005_comment_tag.py

@@ -0,0 +1,25 @@
+"""Add tag column to song_comments
+
+Revision ID: 0005_comment_tag
+Revises: 0004_rehearsal_sessions
+Create Date: 2026-04-06
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0005_comment_tag"
+down_revision = "0004"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "song_comments",
+        sa.Column("tag", sa.String(length=32), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("song_comments", "tag")

api/src/rehearsalhub/config.py

@@ -21,6 +21,8 @@ class Settings(BaseSettings):
     # App
     domain: str = "localhost"
     debug: bool = False
+    # Additional CORS origins (comma-separated)
+    cors_origins: str = ""
 
     # Worker
     analysis_version: str = "1.0.0"

api/src/rehearsalhub/db/models.py

@@ -207,6 +207,7 @@ class SongComment(Base):
     )
     body: Mapped[str] = mapped_column(Text, nullable=False)
     timestamp: Mapped[Optional[float]] = mapped_column(Numeric(10, 2), nullable=True)
+    tag: Mapped[Optional[str]] = mapped_column(String(32), nullable=True)
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), nullable=False
     )

api/src/rehearsalhub/main.py

@@ -52,9 +52,24 @@ def create_app() -> FastAPI:
     app.state.limiter = limiter
     app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
 
+    # Get allowed origins from environment or use defaults
+    allowed_origins = [f"https://{settings.domain}", "http://localhost:3000"]
+    
+    # Add specific domain for production
+    if settings.domain != "localhost":
+        allowed_origins.extend([
+            f"https://{settings.domain}",
+            f"http://{settings.domain}",
+        ])
+    
+    # Add additional CORS origins from environment variable
+    if settings.cors_origins:
+        additional_origins = [origin.strip() for origin in settings.cors_origins.split(",")]
+        allowed_origins.extend(additional_origins)
+    
     app.add_middleware(
         CORSMiddleware,
-        allow_origins=[f"https://{settings.domain}", "http://localhost:3000"],
+        allow_origins=allowed_origins,
         allow_credentials=True,
         allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
         allow_headers=["Authorization", "Content-Type", "Accept"],

api/src/rehearsalhub/routers/auth.py

@@ -52,14 +52,29 @@ async def login(
             status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials"
         )
     settings = get_settings()
+    
+    # Determine cookie domain based on settings
+    cookie_domain = None
+    if settings.domain != "localhost":
+        # For production domains, set cookie domain to allow subdomains
+        if "." in settings.domain:  # Check if it's a proper domain
+            cookie_domain = "." + settings.domain.split(".")[-2] + "." + settings.domain.split(".")[-1]
+    
+    # For cross-site functionality, use samesite="none" with secure flag.
+    # localhost is always plain HTTP — never set Secure there or the browser drops the cookie.
+    is_localhost = settings.domain == "localhost"
+    samesite_value = "lax" if is_localhost else "none"
+    secure_flag = False if is_localhost else True
+    
     response.set_cookie(
         key="rh_token",
         value=token.access_token,
         httponly=True,
-        secure=not settings.debug,
+        secure=secure_flag,
-        samesite="lax",
+        samesite=samesite_value,
         max_age=settings.access_token_expire_minutes * 60,
         path="/",
+        domain=cookie_domain,
     )
     return token
 

api/src/rehearsalhub/routers/songs.py

@@ -89,6 +89,24 @@ async def search_songs(
     ]
 
 
+@router.get("/songs/{song_id}", response_model=SongRead)
+async def get_song(
+    song_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+    current_member: Member = Depends(get_current_member),
+):
+    song_repo = SongRepository(session)
+    song = await song_repo.get_with_versions(song_id)
+    if song is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Song not found")
+    band_svc = BandService(session)
+    try:
+        await band_svc.assert_membership(song.band_id, current_member.id)
+    except PermissionError:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a member")
+    return SongRead.model_validate(song).model_copy(update={"version_count": len(song.versions)})
+
+
 @router.patch("/songs/{song_id}", response_model=SongRead)
 async def update_song(
     song_id: uuid.UUID,
@@ -264,7 +282,7 @@ async def create_comment(
 ):
     await _assert_song_membership(song_id, current_member.id, session)
     repo = CommentRepository(session)
-    comment = await repo.create(song_id=song_id, author_id=current_member.id, body=data.body, timestamp=data.timestamp)
+    comment = await repo.create(song_id=song_id, author_id=current_member.id, body=data.body, timestamp=data.timestamp, tag=data.tag)
     comment = await repo.get_with_author(comment.id)
     return SongCommentRead.from_model(comment)
 

api/src/rehearsalhub/schemas/comment.py

@@ -9,6 +9,7 @@ from pydantic import BaseModel, ConfigDict
 class SongCommentCreate(BaseModel):
     body: str
     timestamp: float | None = None
+    tag: str | None = None
 
 
 class SongCommentRead(BaseModel):
@@ -21,6 +22,7 @@ class SongCommentRead(BaseModel):
     author_name: str
     author_avatar_url: str | None
     timestamp: float | None
+    tag: str | None
     created_at: datetime
 
     @classmethod
@@ -33,5 +35,6 @@ class SongCommentRead(BaseModel):
             author_name=getattr(getattr(c, "author"), "display_name"),
             author_avatar_url=getattr(getattr(c, "author"), "avatar_url"),
             timestamp=getattr(c, "timestamp"),
+            tag=getattr(c, "tag", None),
             created_at=getattr(c, "created_at"),
         )

api/uv.lock

@@ -450,6 +450,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1b/82/ca4893968aeb2709aacfb57a30dec6fa2ab25b10fa9f064b8882ce33f599/cryptography-46.0.6-cp38-abi3-win_amd64.whl", hash = "sha256:79e865c642cfc5c0b3eb12af83c35c5aeff4fa5c672dc28c43721c2c9fdd2f0f", size = 3471160, upload-time = "2026-03-25T23:34:37.191Z" },
 ]
 
+[[package]]
+name = "deprecated"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "wrapt" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/49/85/12f0a49a7c4ffb70572b6c2ef13c90c88fd190debda93b23f026b25f9634/deprecated-1.3.1.tar.gz", hash = "sha256:b1b50e0ff0c1fddaa5708a2c6b0a6588bb09b892825ab2b214ac9ea9d92a5223", size = 2932523, upload-time = "2025-10-30T08:19:02.757Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/84/d0/205d54408c08b13550c733c4b85429e7ead111c7f0014309637425520a9a/deprecated-1.3.1-py2.py3-none-any.whl", hash = "sha256:597bfef186b6f60181535a29fbe44865ce137a5079f295b479886c82729d5f3f", size = 11298, upload-time = "2025-10-30T08:19:00.758Z" },
+]
+
 [[package]]
 name = "dnspython"
 version = "2.8.0"
@@ -785,6 +797,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b2/c8/d148e041732d631fc76036f8b30fae4e77b027a1e95b7a84bb522481a940/librt-0.8.1-cp314-cp314t-win_arm64.whl", hash = "sha256:bf512a71a23504ed08103a13c941f763db13fb11177beb3d9244c98c29fb4a61", size = 48755, upload-time = "2026-02-17T16:12:47.943Z" },
 ]
 
+[[package]]
+name = "limits"
+version = "5.8.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "deprecated" },
+    { name = "packaging" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/71/69/826a5d1f45426c68d8f6539f8d275c0e4fcaa57f0c017ec3100986558a41/limits-5.8.0.tar.gz", hash = "sha256:c9e0d74aed837e8f6f50d1fcebcf5fd8130957287206bc3799adaee5092655da", size = 226104, upload-time = "2026-02-05T07:17:35.859Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b9/98/cb5ca20618d205a09d5bec7591fbc4130369c7e6308d9a676a28ff3ab22c/limits-5.8.0-py3-none-any.whl", hash = "sha256:ae1b008a43eb43073c3c579398bd4eb4c795de60952532dc24720ab45e1ac6b8", size = 60954, upload-time = "2026-02-05T07:17:34.425Z" },
+]
+
 [[package]]
 name = "mako"
 version = "1.3.10"
@@ -920,6 +946,75 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ef/3c/2c197d226f9ea224a9ab8d197933f9da0ae0aac5b6e0f884e2b8d9c8e9f7/pathspec-1.0.4-py3-none-any.whl", hash = "sha256:fb6ae2fd4e7c921a165808a552060e722767cfa526f99ca5156ed2ce45a5c723", size = 55206, upload-time = "2026-01-27T03:59:45.137Z" },
 ]
 
+[[package]]
+name = "pillow"
+version = "12.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8c/21/c2bcdd5906101a30244eaffc1b6e6ce71a31bd0742a01eb89e660ebfac2d/pillow-12.2.0.tar.gz", hash = "sha256:a830b1a40919539d07806aa58e1b114df53ddd43213d9c8b75847eee6c0182b5", size = 46987819, upload-time = "2026-04-01T14:46:17.687Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/be/7482c8a5ebebbc6470b3eb791812fff7d5e0216c2be3827b30b8bb6603ed/pillow-12.2.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:2d192a155bbcec180f8564f693e6fd9bccff5a7af9b32e2e4bf8c9c69dbad6b5", size = 5308279, upload-time = "2026-04-01T14:43:13.246Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/95/0a351b9289c2b5cbde0bacd4a83ebc44023e835490a727b2a3bd60ddc0f4/pillow-12.2.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f3f40b3c5a968281fd507d519e444c35f0ff171237f4fdde090dd60699458421", size = 4695490, upload-time = "2026-04-01T14:43:15.584Z" },
+    { url = "https://files.pythonhosted.org/packages/de/af/4e8e6869cbed569d43c416fad3dc4ecb944cb5d9492defaed89ddd6fe871/pillow-12.2.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:03e7e372d5240cc23e9f07deca4d775c0817bffc641b01e9c3af208dbd300987", size = 6284462, upload-time = "2026-04-01T14:43:18.268Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/9e/c05e19657fd57841e476be1ab46c4d501bffbadbafdc31a6d665f8b737b6/pillow-12.2.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:b86024e52a1b269467a802258c25521e6d742349d760728092e1bc2d135b4d76", size = 8094744, upload-time = "2026-04-01T14:43:20.716Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/54/1789c455ed10176066b6e7e6da1b01e50e36f94ba584dc68d9eebfe9156d/pillow-12.2.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7371b48c4fa448d20d2714c9a1f775a81155050d383333e0a6c15b1123dda005", size = 6398371, upload-time = "2026-04-01T14:43:23.443Z" },
+    { url = "https://files.pythonhosted.org/packages/43/e3/fdc657359e919462369869f1c9f0e973f353f9a9ee295a39b1fea8ee1a77/pillow-12.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:62f5409336adb0663b7caa0da5c7d9e7bdbaae9ce761d34669420c2a801b2780", size = 7087215, upload-time = "2026-04-01T14:43:26.758Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/f8/2f6825e441d5b1959d2ca5adec984210f1ec086435b0ed5f52c19b3b8a6e/pillow-12.2.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:01afa7cf67f74f09523699b4e88c73fb55c13346d212a59a2db1f86b0a63e8c5", size = 6509783, upload-time = "2026-04-01T14:43:29.56Z" },
+    { url = "https://files.pythonhosted.org/packages/67/f9/029a27095ad20f854f9dba026b3ea6428548316e057e6fc3545409e86651/pillow-12.2.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fc3d34d4a8fbec3e88a79b92e5465e0f9b842b628675850d860b8bd300b159f5", size = 7212112, upload-time = "2026-04-01T14:43:32.091Z" },
+    { url = "https://files.pythonhosted.org/packages/be/42/025cfe05d1be22dbfdb4f264fe9de1ccda83f66e4fc3aac94748e784af04/pillow-12.2.0-cp312-cp312-win32.whl", hash = "sha256:58f62cc0f00fd29e64b29f4fd923ffdb3859c9f9e6105bfc37ba1d08994e8940", size = 6378489, upload-time = "2026-04-01T14:43:34.601Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/7b/25a221d2c761c6a8ae21bfa3874988ff2583e19cf8a27bf2fee358df7942/pillow-12.2.0-cp312-cp312-win_amd64.whl", hash = "sha256:7f84204dee22a783350679a0333981df803dac21a0190d706a50475e361c93f5", size = 7084129, upload-time = "2026-04-01T14:43:37.213Z" },
+    { url = "https://files.pythonhosted.org/packages/10/e1/542a474affab20fd4a0f1836cb234e8493519da6b76899e30bcc5d990b8b/pillow-12.2.0-cp312-cp312-win_arm64.whl", hash = "sha256:af73337013e0b3b46f175e79492d96845b16126ddf79c438d7ea7ff27783a414", size = 2463612, upload-time = "2026-04-01T14:43:39.421Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/01/53d10cf0dbad820a8db274d259a37ba50b88b24768ddccec07355382d5ad/pillow-12.2.0-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:8297651f5b5679c19968abefd6bb84d95fe30ef712eb1b2d9b2d31ca61267f4c", size = 4100837, upload-time = "2026-04-01T14:43:41.506Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/98/f3a6657ecb698c937f6c76ee564882945f29b79bad496abcba0e84659ec5/pillow-12.2.0-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:50d8520da2a6ce0af445fa6d648c4273c3eeefbc32d7ce049f22e8b5c3daecc2", size = 4176528, upload-time = "2026-04-01T14:43:43.773Z" },
+    { url = "https://files.pythonhosted.org/packages/69/bc/8986948f05e3ea490b8442ea1c1d4d990b24a7e43d8a51b2c7d8b1dced36/pillow-12.2.0-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:766cef22385fa1091258ad7e6216792b156dc16d8d3fa607e7545b2b72061f1c", size = 3640401, upload-time = "2026-04-01T14:43:45.87Z" },
+    { url = "https://files.pythonhosted.org/packages/34/46/6c717baadcd62bc8ed51d238d521ab651eaa74838291bda1f86fe1f864c9/pillow-12.2.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5d2fd0fa6b5d9d1de415060363433f28da8b1526c1c129020435e186794b3795", size = 5308094, upload-time = "2026-04-01T14:43:48.438Z" },
+    { url = "https://files.pythonhosted.org/packages/71/43/905a14a8b17fdb1ccb58d282454490662d2cb89a6bfec26af6d3520da5ec/pillow-12.2.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:56b25336f502b6ed02e889f4ece894a72612fe885889a6e8c4c80239ff6e5f5f", size = 4695402, upload-time = "2026-04-01T14:43:51.292Z" },
+    { url = "https://files.pythonhosted.org/packages/73/dd/42107efcb777b16fa0393317eac58f5b5cf30e8392e266e76e51cff28c3d/pillow-12.2.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f1c943e96e85df3d3478f7b691f229887e143f81fedab9b20205349ab04d73ed", size = 6280005, upload-time = "2026-04-01T14:43:54.242Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/68/b93e09e5e8549019e61acf49f65b1a8530765a7f812c77a7461bca7e4494/pillow-12.2.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:03f6fab9219220f041c74aeaa2939ff0062bd5c364ba9ce037197f4c6d498cd9", size = 8090669, upload-time = "2026-04-01T14:43:57.335Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/6e/3ccb54ce8ec4ddd1accd2d89004308b7b0b21c4ac3d20fa70af4760a4330/pillow-12.2.0-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5cdfebd752ec52bf5bb4e35d9c64b40826bc5b40a13df7c3cda20a2c03a0f5ed", size = 6395194, upload-time = "2026-04-01T14:43:59.864Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ee/21d4e8536afd1a328f01b359b4d3997b291ffd35a237c877b331c1c3b71c/pillow-12.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:eedf4b74eda2b5a4b2b2fb4c006d6295df3bf29e459e198c90ea48e130dc75c3", size = 7082423, upload-time = "2026-04-01T14:44:02.74Z" },
+    { url = "https://files.pythonhosted.org/packages/78/5f/e9f86ab0146464e8c133fe85df987ed9e77e08b29d8d35f9f9f4d6f917ba/pillow-12.2.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:00a2865911330191c0b818c59103b58a5e697cae67042366970a6b6f1b20b7f9", size = 6505667, upload-time = "2026-04-01T14:44:05.381Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/1e/409007f56a2fdce61584fd3acbc2bbc259857d555196cedcadc68c015c82/pillow-12.2.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1e1757442ed87f4912397c6d35a0db6a7b52592156014706f17658ff58bbf795", size = 7208580, upload-time = "2026-04-01T14:44:08.39Z" },
+    { url = "https://files.pythonhosted.org/packages/23/c4/7349421080b12fb35414607b8871e9534546c128a11965fd4a7002ccfbee/pillow-12.2.0-cp313-cp313-win32.whl", hash = "sha256:144748b3af2d1b358d41286056d0003f47cb339b8c43a9ea42f5fea4d8c66b6e", size = 6375896, upload-time = "2026-04-01T14:44:11.197Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/82/8a3739a5e470b3c6cbb1d21d315800d8e16bff503d1f16b03a4ec3212786/pillow-12.2.0-cp313-cp313-win_amd64.whl", hash = "sha256:390ede346628ccc626e5730107cde16c42d3836b89662a115a921f28440e6a3b", size = 7081266, upload-time = "2026-04-01T14:44:13.947Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/25/f968f618a062574294592f668218f8af564830ccebdd1fa6200f598e65c5/pillow-12.2.0-cp313-cp313-win_arm64.whl", hash = "sha256:8023abc91fba39036dbce14a7d6535632f99c0b857807cbbbf21ecc9f4717f06", size = 2463508, upload-time = "2026-04-01T14:44:16.312Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/a4/b342930964e3cb4dce5038ae34b0eab4653334995336cd486c5a8c25a00c/pillow-12.2.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:042db20a421b9bafecc4b84a8b6e444686bd9d836c7fd24542db3e7df7baad9b", size = 5309927, upload-time = "2026-04-01T14:44:18.89Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/de/23198e0a65a9cf06123f5435a5d95cea62a635697f8f03d134d3f3a96151/pillow-12.2.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:dd025009355c926a84a612fecf58bb315a3f6814b17ead51a8e48d3823d9087f", size = 4698624, upload-time = "2026-04-01T14:44:21.115Z" },
+    { url = "https://files.pythonhosted.org/packages/01/a6/1265e977f17d93ea37aa28aa81bad4fa597933879fac2520d24e021c8da3/pillow-12.2.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:88ddbc66737e277852913bd1e07c150cc7bb124539f94c4e2df5344494e0a612", size = 6321252, upload-time = "2026-04-01T14:44:23.663Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/83/5982eb4a285967baa70340320be9f88e57665a387e3a53a7f0db8231a0cd/pillow-12.2.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:d362d1878f00c142b7e1a16e6e5e780f02be8195123f164edf7eddd911eefe7c", size = 8126550, upload-time = "2026-04-01T14:44:26.772Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/48/6ffc514adce69f6050d0753b1a18fd920fce8cac87620d5a31231b04bfc5/pillow-12.2.0-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2c727a6d53cb0018aadd8018c2b938376af27914a68a492f59dfcaca650d5eea", size = 6433114, upload-time = "2026-04-01T14:44:29.615Z" },
+    { url = "https://files.pythonhosted.org/packages/36/a3/f9a77144231fb8d40ee27107b4463e205fa4677e2ca2548e14da5cf18dce/pillow-12.2.0-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:efd8c21c98c5cc60653bcb311bef2ce0401642b7ce9d09e03a7da87c878289d4", size = 7115667, upload-time = "2026-04-01T14:44:32.773Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/fc/ac4ee3041e7d5a565e1c4fd72a113f03b6394cc72ab7089d27608f8aaccb/pillow-12.2.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9f08483a632889536b8139663db60f6724bfcb443c96f1b18855860d7d5c0fd4", size = 6538966, upload-time = "2026-04-01T14:44:35.252Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/a8/27fb307055087f3668f6d0a8ccb636e7431d56ed0750e07a60547b1e083e/pillow-12.2.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:dac8d77255a37e81a2efcbd1fc05f1c15ee82200e6c240d7e127e25e365c39ea", size = 7238241, upload-time = "2026-04-01T14:44:37.875Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/4b/926ab182c07fccae9fcb120043464e1ff1564775ec8864f21a0ebce6ac25/pillow-12.2.0-cp313-cp313t-win32.whl", hash = "sha256:ee3120ae9dff32f121610bb08e4313be87e03efeadfc6c0d18f89127e24d0c24", size = 6379592, upload-time = "2026-04-01T14:44:40.336Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/c4/f9e476451a098181b30050cc4c9a3556b64c02cf6497ea421ac047e89e4b/pillow-12.2.0-cp313-cp313t-win_amd64.whl", hash = "sha256:325ca0528c6788d2a6c3d40e3568639398137346c3d6e66bb61db96b96511c98", size = 7085542, upload-time = "2026-04-01T14:44:43.251Z" },
+    { url = "https://files.pythonhosted.org/packages/00/a4/285f12aeacbe2d6dc36c407dfbbe9e96d4a80b0fb710a337f6d2ad978c75/pillow-12.2.0-cp313-cp313t-win_arm64.whl", hash = "sha256:2e5a76d03a6c6dcef67edabda7a52494afa4035021a79c8558e14af25313d453", size = 2465765, upload-time = "2026-04-01T14:44:45.996Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/98/4595daa2365416a86cb0d495248a393dfc84e96d62ad080c8546256cb9c0/pillow-12.2.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:3adc9215e8be0448ed6e814966ecf3d9952f0ea40eb14e89a102b87f450660d8", size = 4100848, upload-time = "2026-04-01T14:44:48.48Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/79/40184d464cf89f6663e18dfcf7ca21aae2491fff1a16127681bf1fa9b8cf/pillow-12.2.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:6a9adfc6d24b10f89588096364cc726174118c62130c817c2837c60cf08a392b", size = 4176515, upload-time = "2026-04-01T14:44:51.353Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/63/703f86fd4c422a9cf722833670f4f71418fb116b2853ff7da722ea43f184/pillow-12.2.0-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:6a6e67ea2e6feda684ed370f9a1c52e7a243631c025ba42149a2cc5934dec295", size = 3640159, upload-time = "2026-04-01T14:44:53.588Z" },
+    { url = "https://files.pythonhosted.org/packages/71/e0/fb22f797187d0be2270f83500aab851536101b254bfa1eae10795709d283/pillow-12.2.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:2bb4a8d594eacdfc59d9e5ad972aa8afdd48d584ffd5f13a937a664c3e7db0ed", size = 5312185, upload-time = "2026-04-01T14:44:56.039Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/8c/1a9e46228571de18f8e28f16fabdfc20212a5d019f3e3303452b3f0a580d/pillow-12.2.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:80b2da48193b2f33ed0c32c38140f9d3186583ce7d516526d462645fd98660ae", size = 4695386, upload-time = "2026-04-01T14:44:58.663Z" },
+    { url = "https://files.pythonhosted.org/packages/70/62/98f6b7f0c88b9addd0e87c217ded307b36be024d4ff8869a812b241d1345/pillow-12.2.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:22db17c68434de69d8ecfc2fe821569195c0c373b25cccb9cbdacf2c6e53c601", size = 6280384, upload-time = "2026-04-01T14:45:01.5Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/03/688747d2e91cfbe0e64f316cd2e8005698f76ada3130d0194664174fa5de/pillow-12.2.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7b14cc0106cd9aecda615dd6903840a058b4700fcb817687d0ee4fc8b6e389be", size = 8091599, upload-time = "2026-04-01T14:45:04.5Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/35/577e22b936fcdd66537329b33af0b4ccfefaeabd8aec04b266528cddb33c/pillow-12.2.0-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8cbeb542b2ebc6fcdacabf8aca8c1a97c9b3ad3927d46b8723f9d4f033288a0f", size = 6396021, upload-time = "2026-04-01T14:45:07.117Z" },
+    { url = "https://files.pythonhosted.org/packages/11/8d/d2532ad2a603ca2b93ad9f5135732124e57811d0168155852f37fbce2458/pillow-12.2.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4bfd07bc812fbd20395212969e41931001fd59eb55a60658b0e5710872e95286", size = 7083360, upload-time = "2026-04-01T14:45:09.763Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/26/d325f9f56c7e039034897e7380e9cc202b1e368bfd04d4cbe6a441f02885/pillow-12.2.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:9aba9a17b623ef750a4d11b742cbafffeb48a869821252b30ee21b5e91392c50", size = 6507628, upload-time = "2026-04-01T14:45:12.378Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/f7/769d5632ffb0988f1c5e7660b3e731e30f7f8ec4318e94d0a5d674eb65a4/pillow-12.2.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:deede7c263feb25dba4e82ea23058a235dcc2fe1f6021025dc71f2b618e26104", size = 7209321, upload-time = "2026-04-01T14:45:15.122Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/7a/c253e3c645cd47f1aceea6a8bacdba9991bf45bb7dfe927f7c893e89c93c/pillow-12.2.0-cp314-cp314-win32.whl", hash = "sha256:632ff19b2778e43162304d50da0181ce24ac5bb8180122cbe1bf4673428328c7", size = 6479723, upload-time = "2026-04-01T14:45:17.797Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/8b/601e6566b957ca50e28725cb6c355c59c2c8609751efbecd980db44e0349/pillow-12.2.0-cp314-cp314-win_amd64.whl", hash = "sha256:4e6c62e9d237e9b65fac06857d511e90d8461a32adcc1b9065ea0c0fa3a28150", size = 7217400, upload-time = "2026-04-01T14:45:20.529Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/94/220e46c73065c3e2951bb91c11a1fb636c8c9ad427ac3ce7d7f3359b9b2f/pillow-12.2.0-cp314-cp314-win_arm64.whl", hash = "sha256:b1c1fbd8a5a1af3412a0810d060a78b5136ec0836c8a4ef9aa11807f2a22f4e1", size = 2554835, upload-time = "2026-04-01T14:45:23.162Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/ab/1b426a3974cb0e7da5c29ccff4807871d48110933a57207b5a676cccc155/pillow-12.2.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:57850958fe9c751670e49b2cecf6294acc99e562531f4bd317fa5ddee2068463", size = 5314225, upload-time = "2026-04-01T14:45:25.637Z" },
+    { url = "https://files.pythonhosted.org/packages/19/1e/dce46f371be2438eecfee2a1960ee2a243bbe5e961890146d2dee1ff0f12/pillow-12.2.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:d5d38f1411c0ed9f97bcb49b7bd59b6b7c314e0e27420e34d99d844b9ce3b6f3", size = 4698541, upload-time = "2026-04-01T14:45:28.355Z" },
+    { url = "https://files.pythonhosted.org/packages/55/c3/7fbecf70adb3a0c33b77a300dc52e424dc22ad8cdc06557a2e49523b703d/pillow-12.2.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5c0a9f29ca8e79f09de89293f82fc9b0270bb4af1d58bc98f540cc4aedf03166", size = 6322251, upload-time = "2026-04-01T14:45:30.924Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/3c/7fbc17cfb7e4fe0ef1642e0abc17fc6c94c9f7a16be41498e12e2ba60408/pillow-12.2.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:1610dd6c61621ae1cf811bef44d77e149ce3f7b95afe66a4512f8c59f25d9ebe", size = 8127807, upload-time = "2026-04-01T14:45:33.908Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/c3/a8ae14d6defd2e448493ff512fae903b1e9bd40b72efb6ec55ce0048c8ce/pillow-12.2.0-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0a34329707af4f73cf1782a36cd2289c0368880654a2c11f027bcee9052d35dd", size = 6433935, upload-time = "2026-04-01T14:45:36.623Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/32/2880fb3a074847ac159d8f902cb43278a61e85f681661e7419e6596803ed/pillow-12.2.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8e9c4f5b3c546fa3458a29ab22646c1c6c787ea8f5ef51300e5a60300736905e", size = 7116720, upload-time = "2026-04-01T14:45:39.258Z" },
+    { url = "https://files.pythonhosted.org/packages/46/87/495cc9c30e0129501643f24d320076f4cc54f718341df18cc70ec94c44e1/pillow-12.2.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:fb043ee2f06b41473269765c2feae53fc2e2fbf96e5e22ca94fb5ad677856f06", size = 6540498, upload-time = "2026-04-01T14:45:41.879Z" },
+    { url = "https://files.pythonhosted.org/packages/18/53/773f5edca692009d883a72211b60fdaf8871cbef075eaa9d577f0a2f989e/pillow-12.2.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f278f034eb75b4e8a13a54a876cc4a5ab39173d2cdd93a638e1b467fc545ac43", size = 7239413, upload-time = "2026-04-01T14:45:44.705Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/e4/4b64a97d71b2a83158134abbb2f5bd3f8a2ea691361282f010998f339ec7/pillow-12.2.0-cp314-cp314t-win32.whl", hash = "sha256:6bb77b2dcb06b20f9f4b4a8454caa581cd4dd0643a08bacf821216a16d9c8354", size = 6482084, upload-time = "2026-04-01T14:45:47.568Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/13/306d275efd3a3453f72114b7431c877d10b1154014c1ebbedd067770d629/pillow-12.2.0-cp314-cp314t-win_amd64.whl", hash = "sha256:6562ace0d3fb5f20ed7290f1f929cae41b25ae29528f2af1722966a0a02e2aa1", size = 7225152, upload-time = "2026-04-01T14:45:50.032Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/6e/cf826fae916b8658848d7b9f38d88da6396895c676e8086fc0988073aaf8/pillow-12.2.0-cp314-cp314t-win_arm64.whl", hash = "sha256:aa88ccfe4e32d362816319ed727a004423aab09c5cea43c01a4b435643fa34eb", size = 2556579, upload-time = "2026-04-01T14:45:52.529Z" },
+]
+
 [[package]]
 name = "pluggy"
 version = "1.6.0"
@@ -1227,11 +1322,13 @@ dependencies = [
     { name = "bcrypt" },
     { name = "fastapi" },
     { name = "httpx" },
+    { name = "pillow" },
     { name = "pydantic", extra = ["email"] },
     { name = "pydantic-settings" },
     { name = "python-jose", extra = ["cryptography"] },
     { name = "python-multipart" },
     { name = "redis", extra = ["hiredis"] },
+    { name = "slowapi" },
     { name = "sqlalchemy", extra = ["asyncio"] },
     { name = "uvicorn", extra = ["standard"] },
 ]
@@ -1264,6 +1361,7 @@ requires-dist = [
     { name = "fastapi", specifier = ">=0.115" },
     { name = "httpx", specifier = ">=0.27" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.10" },
+    { name = "pillow", specifier = ">=10.0" },
     { name = "pydantic", extras = ["email"], specifier = ">=2.7" },
     { name = "pydantic-settings", specifier = ">=2.3" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8" },
@@ -1273,6 +1371,7 @@ requires-dist = [
     { name = "python-multipart", specifier = ">=0.0.9" },
     { name = "redis", extras = ["hiredis"], specifier = ">=5.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.4" },
+    { name = "slowapi", specifier = ">=0.1.9" },
     { name = "sqlalchemy", extras = ["asyncio"], specifier = ">=2.0" },
     { name = "testcontainers", extras = ["postgres"], marker = "extra == 'dev'", specifier = ">=4.7" },
     { name = "types-python-jose", marker = "extra == 'dev'" },
@@ -1348,6 +1447,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
 ]
 
+[[package]]
+name = "slowapi"
+version = "0.1.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "limits" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a0/99/adfc7f94ca024736f061257d39118e1542bade7a52e86415a4c4ae92d8ff/slowapi-0.1.9.tar.gz", hash = "sha256:639192d0f1ca01b1c6d95bf6c71d794c3a9ee189855337b4821f7f457dddad77", size = 14028, upload-time = "2024-02-05T12:11:52.13Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2b/bb/f71c4b7d7e7eb3fc1e8c0458a8979b912f40b58002b9fbf37729b8cb464b/slowapi-0.1.9-py3-none-any.whl", hash = "sha256:cfad116cfb84ad9d763ee155c1e5c5cbf00b0d47399a769b227865f5df576e36", size = 14670, upload-time = "2024-02-05T12:11:50.898Z" },
+]
+
 [[package]]
 name = "sqlalchemy"
 version = "2.0.48"

docker-compose.dev.yml

@@ -1,17 +1,63 @@
 services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-rehearsalhub}
+      POSTGRES_USER: ${POSTGRES_USER:-rh_user}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-default_secure_password}
+    volumes:
+      - pg_data_dev:/var/lib/postgresql/data
+    networks:
+      - rh_net
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-rh_user} -d ${POSTGRES_DB:-rehearsalhub} || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 20
+      start_period: 20s
+
+  redis:
+    image: redis:7-alpine
+    networks:
+      - rh_net
+
   api:
     build:
       context: ./api
       target: development
-    volumes:
+    environment:
-      - ./api/src:/app/src
+      DATABASE_URL: postgresql+asyncpg://${POSTGRES_USER:-rh_user}:${POSTGRES_PASSWORD:-default_secure_password}@db:5432/${POSTGRES_DB:-rehearsalhub}
+      NEXTCLOUD_URL: ${NEXTCLOUD_URL:-https://cloud.example.com}
+      NEXTCLOUD_USER: ${NEXTCLOUD_USER:-rh_service}
+      NEXTCLOUD_PASS: ${NEXTCLOUD_PASS:-default_password}
+      REDIS_URL: redis://redis:6379/0
+      SECRET_KEY: ${SECRET_KEY:-replace_me_with_32_byte_hex_default}
+      INTERNAL_SECRET: ${INTERNAL_SECRET:-replace_me_with_32_byte_hex_default}
+      DOMAIN: localhost
     ports:
       - "8000:8000"
+    networks:
+      - rh_net
+    depends_on:
+      db:
+        condition: service_healthy
 
-  audio-worker:
+  web:
-    volumes:
+    build:
-      - ./worker/src:/app/src
+      context: ./web
+      target: development
+    environment:
+      API_URL: http://api:8000
+    ports:
+      - "3000:3000"
+    networks:
+      - rh_net
+    depends_on:
+      - api
 
-  nc-watcher:
+networks:
-    volumes:
+  rh_net:
-      - ./watcher/src:/app/src
+    driver: bridge
+
+volumes:
+  pg_data_dev:

docker-compose.yml

@@ -126,14 +126,17 @@ services:
     ports:
       - "8080:80"
     networks:
+      - frontend
       - rh_net
     depends_on:
       - api
     restart: unless-stopped
 
 networks:
+  frontend:
+    external:
+      name: proxy
   rh_net:
-    driver: bridge
 
 volumes:
   pg_data:

verify_comment_changes.md

@@ -1,73 +0,0 @@
-# Verification Steps for Comment Waveform Integration
-
-## Changes Made
-
-### 1. API Schema Changes
-- Added `author_avatar_url: str | None` to `SongCommentRead` schema
-- Updated `from_model` method to include avatar URL from author
-
-### 2. Frontend Interface Changes
-- Added `author_avatar_url: string | null` to `SongComment` interface
-
-### 3. Comment Creation Changes
-- Modified `addCommentMutation` to accept `{ body: string; timestamp: number }`
-- Updated button click handler to pass `currentTime` when creating comments
-
-### 4. Marker Display Changes
-- Changed marker icon from placeholder to `comment.author_avatar_url || placeholder`
-- Improved marker styling (size, border, shadow)
-- Added proper image styling (object-fit, border-radius)
-
-## Verification Steps
-
-### 1. Test Comment Creation with Timestamp
-1. Play a song and let it progress to a specific time (e.g., 30 seconds)
-2. Add a comment while the song is playing
-3. Verify the comment appears with the correct timestamp
-4. Check that a marker appears on the waveform at the correct position
-
-### 2. Test Avatar Display
-1. Create comments with different users (or check existing comments)
-2. Verify that user avatars appear in the waveform markers
-3. Check that placeholder is used when no avatar is available
-
-### 3. Test Marker Interaction
-1. Click on a waveform marker
-2. Verify that the comment section scrolls to the corresponding comment
-3. Check that the comment is highlighted temporarily
-
-### 4. Test Timestamp Display
-1. Look at comments with timestamps
-2. Verify that the timestamp button appears (e.g., "1:30")
-3. Click the timestamp button and verify playback seeks to that position
-
-## Expected Behavior
-
-### Before Fix
-- Comments created without timestamps (no waveform markers)
-- All markers used placeholder icons
-- No visual indication of comment timing
-
-### After Fix
-- Comments created with current playhead timestamp
-- Markers show user avatars when available
-- Markers positioned correctly on waveform
-- Timestamp buttons work for seeking
-- Markers have improved visibility (border, shadow)
-
-## Troubleshooting
-
-### If markers don't appear
-1. Check browser console for API errors
-2. Verify database migration is applied (timestamp column exists)
-3. Ensure `currentTime` is valid when creating comments
-
-### If avatars don't show
-1. Check that `author_avatar_url` is included in API response
-2. Verify user records have valid avatar URLs
-3. Check network tab for image loading errors
-
-### If timestamps are incorrect
-1. Verify `currentTime` from waveform hook is correct
-2. Check that timestamp is properly sent to API
-3. Ensure backend stores and returns timestamp correctly

web/Dockerfile

@@ -1,3 +1,11 @@
+FROM node:20-alpine AS development
+WORKDIR /app
+COPY package*.json ./
+RUN npm install --legacy-peer-deps
+COPY . .
+# ./web/src is mounted as a volume at runtime for HMR; everything else comes from the image
+CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
+
 FROM node:20-alpine AS builder
 WORKDIR /app
 COPY package*.json ./
@@ -8,6 +16,7 @@ RUN npm run build
 
 FROM nginx:alpine AS production
 COPY --from=builder /app/dist /usr/share/nginx/html
-COPY nginx.conf /etc/nginx/conf.d/default.conf
+ARG NGINX_CONF=nginx.conf
+COPY ${NGINX_CONF} /etc/nginx/conf.d/default.conf
 EXPOSE 80
 CMD ["nginx", "-g", "daemon off;"]

web/nginx-standalone.conf

@@ -0,0 +1,26 @@
+server {
+    listen 80;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Security headers
+    add_header X-Frame-Options "DENY" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header X-XSS-Protection "0" always;
+    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
+
+    # SPA routing — all paths fall back to index.html
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Cache static assets aggressively (Vite build output — hashed filenames)
+    location ~* \.(js|css|woff2|png|svg|ico)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;
+}

web/nginx.conf

@@ -62,6 +62,11 @@ server {
         proxy_send_timeout 60s;
     }
 
+    # Serve manifest.json directly
+    location = /manifest.json {
+        try_files $uri =404;
+    }
+
     # SPA routing — all other paths fall back to index.html
     location / {
         try_files $uri $uri/ /index.html;

web/package-lock.json

@@ -17,6 +17,8 @@
       },
       "devDependencies": {
         "@eslint/js": "^9.39.4",
+        "@testing-library/dom": "^10.4.1",
+        "@testing-library/jest-dom": "^6.9.1",
         "@testing-library/react": "^16.0.1",
         "@testing-library/user-event": "^14.5.2",
         "@types/react": "^18.3.5",
@@ -26,12 +28,19 @@
         "eslint-plugin-react-hooks": "^7.0.1",
         "eslint-plugin-react-refresh": "^0.5.2",
         "jsdom": "^25.0.0",
-        "typescript": "^5.5.3",
+        "typescript": "^5.9.3",
         "typescript-eslint": "^8.57.2",
         "vite": "^5.4.1",
         "vitest": "^2.1.1"
       }
     },
+    "node_modules/@adobe/css-tools": {
+      "version": "4.4.4",
+      "resolved": "https://registry.npmjs.org/@adobe/css-tools/-/css-tools-4.4.4.tgz",
+      "integrity": "sha512-Elp+iwUx5rN5+Y8xLt5/GRoG20WGoDCQ/1Fb+1LiGtvwbDavuSk0jhD/eZdckHAuzcDzccnkv+rEjyWfRx18gg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@asamuzakjp/css-color": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-3.2.0.tgz",
@@ -1495,7 +1504,6 @@
       "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.10.4",
         "@babel/runtime": "^7.12.5",
@@ -1510,6 +1518,43 @@
         "node": ">=18"
       }
     },
+    "node_modules/@testing-library/dom/node_modules/aria-query": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz",
+      "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "dequal": "^2.0.3"
+      }
+    },
+    "node_modules/@testing-library/dom/node_modules/dom-accessibility-api": {
+      "version": "0.5.16",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
+      "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@testing-library/jest-dom": {
+      "version": "6.9.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/jest-dom/-/jest-dom-6.9.1.tgz",
+      "integrity": "sha512-zIcONa+hVtVSSep9UT3jZ5rizo2BsxgyDYU7WFD5eICBE7no3881HGeb/QkGfsJs6JTkY1aQhT7rIPC7e+0nnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@adobe/css-tools": "^4.4.0",
+        "aria-query": "^5.0.0",
+        "css.escape": "^1.5.1",
+        "dom-accessibility-api": "^0.6.3",
+        "picocolors": "^1.1.1",
+        "redent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=14",
+        "npm": ">=6",
+        "yarn": ">=1"
+      }
+    },
     "node_modules/@testing-library/react": {
       "version": "16.3.2",
       "resolved": "https://registry.npmjs.org/@testing-library/react/-/react-16.3.2.tgz",
@@ -1557,8 +1602,7 @@
       "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz",
       "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==",
       "dev": true,
-      "license": "MIT",
+      "license": "MIT"
-      "peer": true
     },
     "node_modules/@types/babel__core": {
       "version": "7.20.5",
@@ -2132,7 +2176,6 @@
       "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=8"
       }
@@ -2161,14 +2204,13 @@
       "license": "Python-2.0"
     },
     "node_modules/aria-query": {
-      "version": "5.3.0",
+      "version": "5.3.2",
-      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.2.tgz",
-      "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
+      "integrity": "sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
+      "engines": {
-      "dependencies": {
+        "node": ">= 0.4"
-        "dequal": "^2.0.3"
       }
     },
     "node_modules/assertion-error": {
@@ -2414,6 +2456,13 @@
         "node": ">= 8"
       }
     },
+    "node_modules/css.escape": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/css.escape/-/css.escape-1.5.1.tgz",
+      "integrity": "sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cssstyle": {
       "version": "4.6.0",
       "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-4.6.0.tgz",
@@ -2514,18 +2563,16 @@
       "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=6"
       }
     },
     "node_modules/dom-accessibility-api": {
-      "version": "0.5.16",
+      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.6.3.tgz",
-      "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
+      "integrity": "sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==",
       "dev": true,
-      "license": "MIT",
+      "license": "MIT"
-      "peer": true
     },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
@@ -3264,6 +3311,16 @@
         "node": ">=0.8.19"
       }
     },
+    "node_modules/indent-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz",
+      "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/is-extglob": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
@@ -3490,7 +3547,6 @@
       "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "lz-string": "bin/bin.js"
       }
@@ -3538,6 +3594,16 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/min-indent": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/min-indent/-/min-indent-1.0.1.tgz",
+      "integrity": "sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/minimatch": {
       "version": "3.1.5",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
@@ -3776,7 +3842,6 @@
       "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "ansi-regex": "^5.0.1",
         "ansi-styles": "^5.0.0",
@@ -3792,7 +3857,6 @@
       "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=10"
       },
@@ -3840,8 +3904,7 @@
       "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
       "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
       "dev": true,
-      "license": "MIT",
+      "license": "MIT"
-      "peer": true
     },
     "node_modules/react-refresh": {
       "version": "0.17.0",
@@ -3885,6 +3948,20 @@
         "react-dom": ">=16.8"
       }
     },
+    "node_modules/redent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz",
+      "integrity": "sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "indent-string": "^4.0.0",
+        "strip-indent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/resolve-from": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz",
@@ -4040,6 +4117,19 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/strip-indent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz",
+      "integrity": "sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "min-indent": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/strip-json-comments": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
@@ -4211,7 +4301,6 @@
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
-      "license": "Apache-2.0",
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"

web/package.json

@@ -23,6 +23,8 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.0.1",
     "@testing-library/user-event": "^14.5.2",
     "@types/react": "^18.3.5",
@@ -32,7 +34,7 @@
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "jsdom": "^25.0.0",
-    "typescript": "^5.5.3",
+    "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.2",
     "vite": "^5.4.1",
     "vitest": "^2.1.1"

web/public/manifest.json

@@ -0,0 +1,9 @@
+{
+  "name": "RehearsalHub",
+  "short_name": "RehearsalHub",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#0d1117",
+  "theme_color": "#0d1117",
+  "icons": []
+}

web/src/App.tsx

@@ -6,6 +6,7 @@ import { AppShell } from "./components/AppShell";
 import { LoginPage } from "./pages/LoginPage";
 import { HomePage } from "./pages/HomePage";
 import { BandPage } from "./pages/BandPage";
+import { BandSettingsPage } from "./pages/BandSettingsPage";
 import { SessionPage } from "./pages/SessionPage";
 import { SongPage } from "./pages/SongPage";
 import { SettingsPage } from "./pages/SettingsPage";
@@ -50,6 +51,18 @@ export default function App() {
               </ShellRoute>
             }
           />
+          <Route
+            path="/bands/:bandId/settings"
+            element={<Navigate to="members" replace />}
+          />
+          <Route
+            path="/bands/:bandId/settings/:panel"
+            element={
+              <ShellRoute>
+                <BandSettingsPage />
+              </ShellRoute>
+            }
+          />
           <Route
             path="/bands/:bandId/sessions/:sessionId"
             element={

web/src/components/AppShell.tsx

@@ -1,581 +1,5 @@
-import { useRef, useEffect, useState } from "react";
+import { ResponsiveLayout } from "./ResponsiveLayout";
-import { useLocation, useNavigate, matchPath } from "react-router-dom";
-import { useQuery } from "@tanstack/react-query";
-import { listBands } from "../api/bands";
-import { api } from "../api/client";
-import { logout } from "../api/auth";
-import type { MemberRead } from "../api/auth";
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function getInitials(name: string): string {
-  return name
-    .split(/\s+/)
-    .map((w) => w[0])
-    .join("")
-    .toUpperCase()
-    .slice(0, 2);
-}
-
-// ── Icons (inline SVG) ────────────────────────────────────────────────────────
-
-function IconWaveform() {
-  return (
-    <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
-      <rect x="1" y="1.5" width="12" height="2" rx="1" fill="white" opacity=".9" />
-      <rect x="1" y="5.5" width="9" height="2" rx="1" fill="white" opacity=".7" />
-      <rect x="1" y="9.5" width="11" height="2" rx="1" fill="white" opacity=".8" />
-    </svg>
-  );
-}
-
-function IconLibrary() {
-  return (
-    <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
-      <path d="M2 3.5h10v1.5H2zm0 3h10v1.5H2zm0 3h7v1.5H2z" />
-    </svg>
-  );
-}
-
-function IconPlay() {
-  return (
-    <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
-      <path d="M3 2l9 5-9 5V2z" />
-    </svg>
-  );
-}
-
-function IconSettings() {
-  return (
-    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.3">
-      <circle cx="7" cy="7" r="2" />
-      <path d="M7 1v1.5M7 11.5V13M1 7h1.5M11.5 7H13" />
-    </svg>
-  );
-}
-
-function IconChevron() {
-  return (
-    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5">
-      <path d="M3 5l3 3 3-3" />
-    </svg>
-  );
-}
-
-function IconSignOut() {
-  return (
-    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round">
-      <path d="M5 2H2.5A1.5 1.5 0 0 0 1 3.5v7A1.5 1.5 0 0 0 2.5 12H5" />
-      <path d="M9 10l3-3-3-3M12 7H5" />
-    </svg>
-  );
-}
-
-// ── NavItem ───────────────────────────────────────────────────────────────────
-
-interface NavItemProps {
-  icon: React.ReactNode;
-  label: string;
-  active: boolean;
-  onClick: () => void;
-  disabled?: boolean;
-}
-
-function NavItem({ icon, label, active, onClick, disabled }: NavItemProps) {
-  const [hovered, setHovered] = useState(false);
-
-  const color = active
-    ? "#e8a22a"
-    : disabled
-    ? "rgba(255,255,255,0.18)"
-    : hovered
-    ? "rgba(255,255,255,0.7)"
-    : "rgba(255,255,255,0.35)";
-
-  const bg = active
-    ? "rgba(232,162,42,0.12)"
-    : hovered && !disabled
-    ? "rgba(255,255,255,0.045)"
-    : "transparent";
-
-  return (
-    <button
-      onClick={onClick}
-      disabled={disabled}
-      onMouseEnter={() => setHovered(true)}
-      onMouseLeave={() => setHovered(false)}
-      style={{
-        display: "flex",
-        alignItems: "center",
-        gap: 9,
-        width: "100%",
-        padding: "7px 10px",
-        borderRadius: 7,
-        border: "none",
-        cursor: disabled ? "default" : "pointer",
-        color,
-        background: bg,
-        fontSize: 12,
-        textAlign: "left",
-        marginBottom: 1,
-        transition: "background 0.12s, color 0.12s",
-        fontFamily: "inherit",
-      }}
-    >
-      {icon}
-      <span>{label}</span>
-    </button>
-  );
-}
-
-// ── AppShell ──────────────────────────────────────────────────────────────────
 
 export function AppShell({ children }: { children: React.ReactNode }) {
-  const navigate = useNavigate();
+  return <ResponsiveLayout>{children}</ResponsiveLayout>;
-  const location = useLocation();
-  const [dropdownOpen, setDropdownOpen] = useState(false);
-  const dropdownRef = useRef<HTMLDivElement>(null);
-
-  const { data: bands } = useQuery({ queryKey: ["bands"], queryFn: listBands });
-  const { data: me } = useQuery({
-    queryKey: ["me"],
-    queryFn: () => api.get<MemberRead>("/auth/me"),
-  });
-
-  // Derive active band from the current URL
-  const bandMatch =
-    matchPath("/bands/:bandId/*", location.pathname) ??
-    matchPath("/bands/:bandId", location.pathname);
-  const activeBandId = bandMatch?.params?.bandId ?? null;
-  const activeBand = bands?.find((b) => b.id === activeBandId) ?? null;
-
-  // Nav active states
-  const isLibrary = !!(
-    matchPath({ path: "/bands/:bandId", end: true }, location.pathname) ||
-    matchPath("/bands/:bandId/sessions/:sessionId", location.pathname) ||
-    matchPath("/bands/:bandId/sessions/:sessionId/*", location.pathname)
-  );
-  const isPlayer = !!matchPath("/bands/:bandId/songs/:songId", location.pathname);
-  const isSettings = location.pathname.startsWith("/settings");
-
-  // Close dropdown on outside click
-  useEffect(() => {
-    if (!dropdownOpen) return;
-    function handleClick(e: MouseEvent) {
-      if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
-        setDropdownOpen(false);
-      }
-    }
-    document.addEventListener("mousedown", handleClick);
-    return () => document.removeEventListener("mousedown", handleClick);
-  }, [dropdownOpen]);
-
-  const border = "rgba(255,255,255,0.06)";
-
-  return (
-    <div
-      style={{
-        display: "flex",
-        height: "100vh",
-        overflow: "hidden",
-        background: "#0f0f12",
-        color: "#eeeef2",
-        fontFamily: "-apple-system, BlinkMacSystemFont, 'Helvetica Neue', sans-serif",
-        fontSize: 13,
-      }}
-    >
-      {/* ── Sidebar ─────────────────────────────────────────── */}
-      <aside
-        style={{
-          width: 210,
-          minWidth: 210,
-          background: "#0b0b0e",
-          borderRight: `1px solid ${border}`,
-          display: "flex",
-          flexDirection: "column",
-          overflow: "hidden",
-        }}
-      >
-        {/* Logo */}
-        <div
-          style={{
-            padding: "17px 14px 14px",
-            display: "flex",
-            alignItems: "center",
-            gap: 10,
-            borderBottom: `1px solid ${border}`,
-            flexShrink: 0,
-          }}
-        >
-          <div
-            style={{
-              width: 28,
-              height: 28,
-              background: "#e8a22a",
-              borderRadius: 7,
-              display: "flex",
-              alignItems: "center",
-              justifyContent: "center",
-              flexShrink: 0,
-            }}
-          >
-            <IconWaveform />
-          </div>
-          <div>
-            <div style={{ fontSize: 13, fontWeight: 600, color: "#eeeef2", letterSpacing: -0.2 }}>
-              RehearsalHub
-            </div>
-            {activeBand && (
-              <div style={{ fontSize: 10, color: "rgba(255,255,255,0.25)", marginTop: 1 }}>
-                {activeBand.name}
-              </div>
-            )}
-          </div>
-        </div>
-
-        {/* Band switcher */}
-        <div
-          ref={dropdownRef}
-          style={{
-            padding: "10px 8px",
-            borderBottom: `1px solid ${border}`,
-            position: "relative",
-            flexShrink: 0,
-          }}
-        >
-          <button
-            onClick={() => setDropdownOpen((o) => !o)}
-            style={{
-              width: "100%",
-              display: "flex",
-              alignItems: "center",
-              gap: 8,
-              padding: "7px 9px",
-              background: "rgba(255,255,255,0.05)",
-              border: "1px solid rgba(255,255,255,0.07)",
-              borderRadius: 8,
-              cursor: "pointer",
-              color: "#eeeef2",
-              textAlign: "left",
-              fontFamily: "inherit",
-            }}
-          >
-            <div
-              style={{
-                width: 26,
-                height: 26,
-                background: "rgba(232,162,42,0.15)",
-                border: "1px solid rgba(232,162,42,0.3)",
-                borderRadius: 7,
-                display: "flex",
-                alignItems: "center",
-                justifyContent: "center",
-                fontSize: 10,
-                fontWeight: 700,
-                color: "#e8a22a",
-                flexShrink: 0,
-              }}
-            >
-              {activeBand ? getInitials(activeBand.name) : "?"}
-            </div>
-            <span
-              style={{
-                flex: 1,
-                fontSize: 12,
-                fontWeight: 500,
-                overflow: "hidden",
-                textOverflow: "ellipsis",
-                whiteSpace: "nowrap",
-              }}
-            >
-              {activeBand?.name ?? "Select a band"}
-            </span>
-            <span style={{ opacity: 0.3, flexShrink: 0, display: "flex" }}>
-              <IconChevron />
-            </span>
-          </button>
-
-          {dropdownOpen && (
-            <div
-              style={{
-                position: "absolute",
-                top: "calc(100% - 2px)",
-                left: 8,
-                right: 8,
-                background: "#18181e",
-                border: "1px solid rgba(255,255,255,0.1)",
-                borderRadius: 10,
-                padding: 6,
-                zIndex: 100,
-                boxShadow: "0 8px 24px rgba(0,0,0,0.5)",
-              }}
-            >
-              {bands?.map((band) => (
-                <button
-                  key={band.id}
-                  onClick={() => {
-                    navigate(`/bands/${band.id}`);
-                    setDropdownOpen(false);
-                  }}
-                  style={{
-                    width: "100%",
-                    display: "flex",
-                    alignItems: "center",
-                    gap: 8,
-                    padding: "7px 9px",
-                    marginBottom: 1,
-                    background: band.id === activeBandId ? "rgba(232,162,42,0.08)" : "transparent",
-                    border: "none",
-                    borderRadius: 6,
-                    cursor: "pointer",
-                    color: "#eeeef2",
-                    textAlign: "left",
-                    fontFamily: "inherit",
-                  }}
-                >
-                  <div
-                    style={{
-                      width: 22,
-                      height: 22,
-                      borderRadius: 5,
-                      background: "rgba(232,162,42,0.15)",
-                      display: "flex",
-                      alignItems: "center",
-                      justifyContent: "center",
-                      fontSize: 9,
-                      fontWeight: 700,
-                      color: "#e8a22a",
-                      flexShrink: 0,
-                    }}
-                  >
-                    {getInitials(band.name)}
-                  </div>
-                  <span
-                    style={{
-                      flex: 1,
-                      fontSize: 12,
-                      color: "rgba(255,255,255,0.62)",
-                      overflow: "hidden",
-                      textOverflow: "ellipsis",
-                      whiteSpace: "nowrap",
-                    }}
-                  >
-                    {band.name}
-                  </span>
-                  {band.id === activeBandId && (
-                    <span style={{ fontSize: 10, color: "#e8a22a", flexShrink: 0 }}>✓</span>
-                  )}
-                </button>
-              ))}
-
-              <div
-                style={{
-                  borderTop: "1px solid rgba(255,255,255,0.06)",
-                  marginTop: 4,
-                  paddingTop: 4,
-                }}
-              >
-                <button
-                  onClick={() => {
-                    navigate("/");
-                    setDropdownOpen(false);
-                  }}
-                  style={{
-                    width: "100%",
-                    display: "flex",
-                    alignItems: "center",
-                    gap: 8,
-                    padding: "7px 9px",
-                    background: "transparent",
-                    border: "none",
-                    borderRadius: 6,
-                    cursor: "pointer",
-                    color: "rgba(255,255,255,0.35)",
-                    fontSize: 12,
-                    textAlign: "left",
-                    fontFamily: "inherit",
-                  }}
-                >
-                  <span style={{ fontSize: 14, opacity: 0.5 }}>+</span>
-                  Create new band
-                </button>
-              </div>
-            </div>
-          )}
-        </div>
-
-        {/* Navigation */}
-        <nav style={{ flex: 1, padding: "10px 8px", overflowY: "auto" }}>
-          {activeBand && (
-            <>
-              <SectionLabel>{activeBand.name}</SectionLabel>
-              <NavItem
-                icon={<IconLibrary />}
-                label="Library"
-                active={isLibrary}
-                onClick={() => navigate(`/bands/${activeBand.id}`)}
-              />
-              <NavItem
-                icon={<IconPlay />}
-                label="Player"
-                active={isPlayer}
-                onClick={() => {}}
-                disabled={!isPlayer}
-              />
-            </>
-          )}
-
-          <SectionLabel style={{ paddingTop: activeBand ? 14 : 0 }}>Account</SectionLabel>
-          <NavItem
-            icon={<IconSettings />}
-            label="Settings"
-            active={isSettings}
-            onClick={() => navigate("/settings")}
-          />
-        </nav>
-
-        {/* User row */}
-        <div
-          style={{
-            padding: "10px",
-            borderTop: `1px solid ${border}`,
-            flexShrink: 0,
-          }}
-        >
-          <div style={{ display: "flex", alignItems: "center", gap: 4 }}>
-            <button
-              onClick={() => navigate("/settings")}
-              style={{
-                flex: 1,
-                display: "flex",
-                alignItems: "center",
-                gap: 8,
-                padding: "6px 8px",
-                background: "transparent",
-                border: "none",
-                borderRadius: 8,
-                cursor: "pointer",
-                color: "#eeeef2",
-                textAlign: "left",
-                minWidth: 0,
-                fontFamily: "inherit",
-              }}
-            >
-              {me?.avatar_url ? (
-                <img
-                  src={me.avatar_url}
-                  alt=""
-                  style={{
-                    width: 28,
-                    height: 28,
-                    borderRadius: "50%",
-                    objectFit: "cover",
-                    flexShrink: 0,
-                  }}
-                />
-              ) : (
-                <div
-                  style={{
-                    width: 28,
-                    height: 28,
-                    borderRadius: "50%",
-                    background: "rgba(232,162,42,0.18)",
-                    border: "1.5px solid rgba(232,162,42,0.35)",
-                    display: "flex",
-                    alignItems: "center",
-                    justifyContent: "center",
-                    fontSize: 10,
-                    fontWeight: 700,
-                    color: "#e8a22a",
-                    flexShrink: 0,
-                  }}
-                >
-                  {getInitials(me?.display_name ?? "?")}
-                </div>
-              )}
-              <span
-                style={{
-                  flex: 1,
-                  fontSize: 12,
-                  color: "rgba(255,255,255,0.55)",
-                  overflow: "hidden",
-                  textOverflow: "ellipsis",
-                  whiteSpace: "nowrap",
-                }}
-              >
-                {me?.display_name ?? "…"}
-              </span>
-            </button>
-
-            <button
-              onClick={() => logout()}
-              title="Sign out"
-              style={{
-                flexShrink: 0,
-                width: 30,
-                height: 30,
-                borderRadius: 7,
-                background: "transparent",
-                border: "1px solid transparent",
-                cursor: "pointer",
-                color: "rgba(255,255,255,0.2)",
-                display: "flex",
-                alignItems: "center",
-                justifyContent: "center",
-                transition: "border-color 0.12s, color 0.12s",
-                padding: 0,
-              }}
-              onMouseEnter={(e) => {
-                e.currentTarget.style.borderColor = "rgba(255,255,255,0.1)";
-                e.currentTarget.style.color = "rgba(255,255,255,0.5)";
-              }}
-              onMouseLeave={(e) => {
-                e.currentTarget.style.borderColor = "transparent";
-                e.currentTarget.style.color = "rgba(255,255,255,0.2)";
-              }}
-            >
-              <IconSignOut />
-            </button>
-          </div>
-        </div>
-      </aside>
-
-      {/* ── Main content ─────────────────────────────────────── */}
-      <main
-        style={{
-          flex: 1,
-          overflow: "auto",
-          display: "flex",
-          flexDirection: "column",
-          background: "#0f0f12",
-        }}
-      >
-        {children}
-      </main>
-    </div>
-  );
-}
-
-function SectionLabel({
-  children,
-  style,
-}: {
-  children: React.ReactNode;
-  style?: React.CSSProperties;
-}) {
-  return (
-    <div
-      style={{
-        fontSize: 10,
-        fontWeight: 500,
-        color: "rgba(255,255,255,0.2)",
-        textTransform: "uppercase",
-        letterSpacing: "0.7px",
-        padding: "0 6px 5px",
-        ...style,
-      }}
-    >
-      {children}
-    </div>
-  );
 }

web/src/components/BottomNavBar.tsx

@@ -0,0 +1,157 @@
+import { useNavigate, useLocation, matchPath } from "react-router-dom";
+import { usePlayerStore } from "../stores/playerStore";
+
+// ── Icons (inline SVG) ──────────────────────────────────────────────────────
+function IconLibrary() {
+  return (
+    <svg width="20" height="20" viewBox="0 0 14 14" fill="currentColor">
+      <path d="M2 3.5h10v1.5H2zm0 3h10v1.5H2zm0 3h7v1.5H2z" />
+    </svg>
+  );
+}
+
+function IconPlay() {
+  return (
+    <svg width="20" height="20" viewBox="0 0 14 14" fill="currentColor">
+      <path d="M3 2l9 5-9 5V2z" />
+    </svg>
+  );
+}
+
+
+
+function IconSettings() {
+  return (
+    <svg width="20" height="20" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.3">
+      <circle cx="7" cy="7" r="2" />
+      <path d="M7 1v1.5M7 11.5V13M1 7h1.5M11.5 7H13" />
+    </svg>
+  );
+}
+
+function IconMembers() {
+  return (
+    <svg width="20" height="20" viewBox="0 0 14 14" fill="currentColor">
+      <circle cx="5" cy="4.5" r="2" />
+      <path d="M1 12c0-2.2 1.8-3.5 4-3.5s4 1.3 4 3.5H1z" />
+      <circle cx="10.5" cy="4.5" r="1.5" opacity=".6" />
+      <path d="M10.5 8.5c1.4 0 2.5 1 2.5 2.5H9.5" opacity=".6" />
+    </svg>
+  );
+}
+
+// ── NavItem ─────────────────────────────────────────────────────────────────
+interface NavItemProps {
+  icon: React.ReactNode;
+  label: string;
+  active: boolean;
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+function NavItem({ icon, label, active, onClick, disabled }: NavItemProps) {
+  const color = active ? "#e8a22a" : "rgba(255,255,255,0.5)";
+
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled}
+      style={{
+        flex: 1,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: 4,
+        padding: "8px 4px",
+        background: "transparent",
+        border: "none",
+        cursor: disabled ? "default" : "pointer",
+        color,
+        fontSize: 10,
+        transition: "color 0.12s",
+        fontFamily: "inherit",
+      }}
+    >
+      {icon}
+      <span style={{ fontSize: 10 }}>{label}</span>
+    </button>
+  );
+}
+
+// ── BottomNavBar ────────────────────────────────────────────────────────────
+export function BottomNavBar() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  
+  // Derive current band from URL
+  const bandMatch = matchPath("/bands/:bandId/*", location.pathname) ?? matchPath("/bands/:bandId", location.pathname);
+  const currentBandId = bandMatch?.params?.bandId || location.state?.fromBandId;
+
+  // Debug logging for black screen issue
+  console.log("BottomNavBar - Current band ID:", currentBandId, "Path:", location.pathname, "State:", location.state);
+
+  // Derive active states
+  const isLibrary = !!matchPath("/bands/:bandId", location.pathname) ||
+                   !!matchPath("/bands/:bandId/sessions/:sessionId", location.pathname);
+  const isSettings = location.pathname.startsWith("/settings");
+  
+  // Player state
+  const { currentSongId, currentBandId: playerBandId, isPlaying } = usePlayerStore();
+  const hasActiveSong = !!currentSongId && !!playerBandId;
+
+  return (
+    <nav
+      style={{
+        position: "fixed",
+        bottom: 0,
+        left: 0,
+        right: 0,
+        display: "flex",
+        background: "#0b0b0e",
+        borderTop: "1px solid rgba(255,255,255,0.06)",
+        zIndex: 1000,
+        padding: "8px 16px",
+      }}
+    >
+      <NavItem
+        icon={<IconLibrary />}
+        label="Library"
+        active={isLibrary}
+        onClick={() => {
+          console.log("Library click - Navigating to band:", currentBandId);
+          if (currentBandId) {
+            navigate(`/bands/${currentBandId}`);
+          } else {
+            console.warn("Library click - No current band ID found!");
+            navigate("/bands");
+          }
+        }}
+      />
+
+      <NavItem
+        icon={<IconPlay />}
+        label="Player"
+        active={hasActiveSong && isPlaying}
+        onClick={() => {
+          if (hasActiveSong) {
+            navigate(`/bands/${playerBandId}/songs/${currentSongId}`);
+          }
+        }}
+        disabled={!hasActiveSong}
+      />
+
+      <NavItem
+        icon={<IconMembers />}
+        label="Members"
+        active={false}
+        onClick={() => currentBandId ? navigate(`/bands/${currentBandId}/settings/members`) : navigate("/settings", { state: { fromBandId: currentBandId } })} 
+      />
+      <NavItem
+        icon={<IconSettings />}
+        label="Settings"
+        active={isSettings}
+        onClick={() => currentBandId ? navigate("/settings", { state: { fromBandId: currentBandId } }) : navigate("/settings")}
+      />
+    </nav>
+  );
+}

web/src/components/MiniPlayer.tsx

@@ -0,0 +1,125 @@
+import { usePlayerStore } from "../stores/playerStore";
+import { useNavigate } from "react-router-dom";
+import { audioService } from "../services/audioService";
+
+export function MiniPlayer() {
+  const { currentSongId, currentBandId, isPlaying, currentTime, duration } = usePlayerStore();
+  const navigate = useNavigate();
+  
+  if (!currentSongId || !currentBandId) {
+    return null;
+  }
+
+  const formatTime = (seconds: number) => {
+    const m = Math.floor(seconds / 60);
+    const s = Math.floor(seconds % 60);
+    return `${m}:${String(s).padStart(2, "0")}`;
+  };
+
+  const progress = duration > 0 ? (currentTime / duration) * 100 : 0;
+
+  return (
+    <div
+      style={
+        {
+          position: "fixed",
+          bottom: 0,
+          left: 0,
+          right: 0,
+          background: "#18181e",
+          borderTop: "1px solid rgba(255,255,255,0.06)",
+          padding: "8px 16px",
+          zIndex: 999,
+          display: "flex",
+          alignItems: "center",
+          gap: 12,
+        }
+      }
+    >
+      <button
+        onClick={() => navigate(`/bands/${currentBandId}/songs/${currentSongId}`)}
+        style={
+          {
+            background: "transparent",
+            border: "none",
+            color: "white",
+            cursor: "pointer",
+            display: "flex",
+            alignItems: "center",
+            gap: 8,
+            padding: "4px 8px",
+            borderRadius: 4,
+          }
+        }
+        title="Go to song"
+      >
+        <svg width="16" height="16" viewBox="0 0 14 14" fill="currentColor">
+          <path d="M3 2l9 5-9 5V2z" />
+        </svg>
+        <span style={{ fontSize: 12, color: "rgba(255,255,255,0.8)" }}>
+          Now Playing
+        </span>
+      </button>
+
+      <div
+        style={
+          {
+            flex: 1,
+            height: 4,
+            background: "rgba(255,255,255,0.1)",
+            borderRadius: 2,
+            overflow: "hidden",
+            cursor: "pointer",
+          }
+        }
+      >
+        <div
+          style={
+            {
+              width: `${progress}%`,
+              height: "100%",
+              background: "#e8a22a",
+              transition: "width 0.1s linear",
+            }
+          }
+        />
+      </div>
+
+      <div style={{ fontSize: 11, color: "rgba(255,255,255,0.6)", minWidth: 60, textAlign: "right" }}>
+        {formatTime(currentTime)} / {formatTime(duration)}
+      </div>
+
+      <button
+        onClick={() => {
+          if (isPlaying) {
+            audioService.pause();
+          } else {
+            audioService.play(currentSongId, currentBandId).catch(err => {
+              console.warn('MiniPlayer playback failed:', err);
+            });
+          }
+        }}
+        style={
+          {
+            background: "transparent",
+            border: "none",
+            color: "white",
+            cursor: "pointer",
+            padding: "4px",
+          }
+        }
+        title={isPlaying ? "Pause" : "Play"}
+      >
+        {isPlaying ? (
+          <svg width="16" height="16" viewBox="0 0 14 14" fill="currentColor">
+            <path d="M4 2h2v10H4zm4 0h2v10h-2z" />
+          </svg>
+        ) : (
+          <svg width="16" height="16" viewBox="0 0 14 14" fill="currentColor">
+            <path d="M3 2l9 5-9 5V2z" />
+          </svg>
+        )}
+      </button>
+    </div>
+  );
+}

web/src/components/ResponsiveLayout.tsx

@@ -0,0 +1,47 @@
+import { useState, useEffect } from "react";
+import { BottomNavBar } from "./BottomNavBar";
+import { Sidebar } from "./Sidebar";
+import { TopBar } from "./TopBar";
+import { MiniPlayer } from "./MiniPlayer";
+
+export function ResponsiveLayout({ children }: { children: React.ReactNode }) {
+  const [isMobile, setIsMobile] = useState(false);
+
+  // Check screen size on mount and resize
+  useEffect(() => {
+    const checkScreenSize = () => {
+      setIsMobile(window.innerWidth < 768);
+    };
+
+    // Initial check
+    checkScreenSize();
+
+    // Add event listener
+    window.addEventListener("resize", checkScreenSize);
+
+    // Cleanup
+    return () => window.removeEventListener("resize", checkScreenSize);
+  }, []);
+
+  return isMobile ? (
+    <>
+      <TopBar />
+      <div
+        style={{
+          height: "calc(100vh - 110px)", // 50px TopBar + 60px BottomNavBar
+          overflow: "auto",
+          paddingTop: 50, // Account for TopBar height
+        }}
+      >
+        {children}
+      </div>
+      <BottomNavBar />
+      <MiniPlayer />
+    </>
+  ) : (
+    <>
+      <Sidebar>{children}</Sidebar>
+      <MiniPlayer />
+    </>
+  );
+}

web/src/components/Sidebar.tsx

@@ -0,0 +1,625 @@
+import { useRef, useState, useEffect } from "react";
+import { useNavigate, useLocation, matchPath } from "react-router-dom";
+import { useQuery } from "@tanstack/react-query";
+import { listBands } from "../api/bands";
+import { api } from "../api/client";
+import { logout } from "../api/auth";
+import { getInitials } from "../utils";
+import type { MemberRead } from "../api/auth";
+import { usePlayerStore } from "../stores/playerStore";
+
+// ── Icons (inline SVG) ──────────────────────────────────────────────────────
+function IconWaveform() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+      <rect x="1" y="1.5" width="12" height="2" rx="1" fill="white" opacity=".9" />
+      <rect x="1" y="5.5" width="9" height="2" rx="1" fill="white" opacity=".7" />
+      <rect x="1" y="9.5" width="11" height="2" rx="1" fill="white" opacity=".8" />
+    </svg>
+  );
+}
+
+function IconLibrary() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+      <path d="M2 3.5h10v1.5H2zm0 3h10v1.5H2zm0 3h7v1.5H2z" />
+    </svg>
+  );
+}
+
+function IconPlay() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+      <path d="M3 2l9 5-9 5V2z" />
+    </svg>
+  );
+}
+
+function IconSettings() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.3">
+      <circle cx="7" cy="7" r="2" />
+      <path d="M7 1v1.5M7 11.5V13M1 7h1.5M11.5 7H13" />
+    </svg>
+  );
+}
+
+function IconMembers() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+      <circle cx="5" cy="4.5" r="2" />
+      <path d="M1 12c0-2.2 1.8-3.5 4-3.5s4 1.3 4 3.5H1z" />
+      <circle cx="10.5" cy="4.5" r="1.5" opacity=".6" />
+      <path d="M10.5 8.5c1.4 0 2.5 1 2.5 2.5H9.5" opacity=".6" />
+    </svg>
+  );
+}
+
+function IconStorage() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+      <rect x="1" y="3" width="12" height="3" rx="1.5" />
+      <rect x="1" y="8" width="12" height="3" rx="1.5" />
+      <circle cx="11" cy="4.5" r=".75" fill="#0b0b0e" />
+      <circle cx="11" cy="9.5" r=".75" fill="#0b0b0e" />
+    </svg>
+  );
+}
+
+function IconChevron() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5">
+      <path d="M3 5l3 3 3-3" />
+    </svg>
+  );
+}
+
+function IconSignOut() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M5 2H2.5A1.5 1.5 0 0 0 1 3.5v7A1.5 1.5 0 0 0 2.5 12H5" />
+      <path d="M9 10l3-3-3-3M12 7H5" />
+    </svg>
+  );
+}
+
+// ── NavItem ─────────────────────────────────────────────────────────────────
+interface NavItemProps {
+  icon: React.ReactNode;
+  label: string;
+  active: boolean;
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+function NavItem({ icon, label, active, onClick, disabled }: NavItemProps) {
+  const [hovered, setHovered] = useState(false);
+
+  const color = active
+    ? "#e8a22a"
+    : disabled
+    ? "rgba(255,255,255,0.18)"
+    : hovered
+    ? "rgba(255,255,255,0.7)"
+    : "rgba(255,255,255,0.35)";
+
+  const bg = active
+    ? "rgba(232,162,42,0.12)"
+    : hovered && !disabled
+    ? "rgba(255,255,255,0.045)"
+    : "transparent";
+
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: 9,
+        width: "100%",
+        padding: "7px 10px",
+        borderRadius: 7,
+        border: "none",
+        cursor: disabled ? "default" : "pointer",
+        color,
+        background: bg,
+        fontSize: 12,
+        textAlign: "left",
+        marginBottom: 1,
+        transition: "background 0.12s, color 0.12s",
+        fontFamily: "inherit",
+      }}
+    >
+      {icon}
+      <span>{label}</span>
+    </button>
+  );
+}
+
+// ── Sidebar ────────────────────────────────────────────────────────────────
+export function Sidebar({ children }: { children: React.ReactNode }) {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const [dropdownOpen, setDropdownOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  const { data: bands } = useQuery({ queryKey: ["bands"], queryFn: listBands });
+  const { data: me } = useQuery({
+    queryKey: ["me"],
+    queryFn: () => api.get<MemberRead>("/auth/me"),
+  });
+
+  // Derive active band from the current URL
+  const bandMatch =
+    matchPath("/bands/:bandId/*", location.pathname) ??
+    matchPath("/bands/:bandId", location.pathname);
+  const activeBandId = bandMatch?.params?.bandId ?? null;
+  const activeBand = bands?.find((b) => b.id === activeBandId) ?? null;
+
+  // Nav active states
+  const isLibrary = !!(
+    matchPath({ path: "/bands/:bandId", end: true }, location.pathname) ||
+    matchPath("/bands/:bandId/sessions/:sessionId", location.pathname) ||
+    matchPath("/bands/:bandId/sessions/:sessionId/*", location.pathname)
+  );
+  const isPlayer = !!matchPath("/bands/:bandId/songs/:songId", location.pathname);
+  const isSettings = location.pathname.startsWith("/settings");
+  const isBandSettings = !!matchPath("/bands/:bandId/settings/*", location.pathname);
+  const bandSettingsPanel = matchPath("/bands/:bandId/settings/:panel", location.pathname)?.params?.panel ?? null;
+  
+  // Player state
+  const { currentSongId, currentBandId: playerBandId, isPlaying: isPlayerPlaying } = usePlayerStore();
+  const hasActiveSong = !!currentSongId && !!playerBandId;
+
+  // Close dropdown on outside click
+  useEffect(() => {
+    if (!dropdownOpen) return;
+    function handleClick(e: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
+        setDropdownOpen(false);
+      }
+    }
+    document.addEventListener("mousedown", handleClick);
+    return () => document.removeEventListener("mousedown", handleClick);
+  }, [dropdownOpen]);
+
+  const border = "rgba(255,255,255,0.06)";
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        height: "100vh",
+        overflow: "hidden",
+        background: "#0f0f12",
+        color: "#eeeef2",
+        fontFamily: "-apple-system, BlinkMacSystemFont, 'Helvetica Neue', sans-serif",
+        fontSize: 13,
+      }}
+    >
+      {/* ── Sidebar ──────────────────────────────────────────────────── */}
+      <aside
+        style={{
+          width: 210,
+          minWidth: 210,
+          background: "#0b0b0e",
+          borderRight: `1px solid ${border}`,
+          display: "flex",
+          flexDirection: "column",
+          overflow: "hidden",
+        }}
+      >
+        {/* Logo */}
+        <div
+          style={{
+            padding: "17px 14px 14px",
+            display: "flex",
+            alignItems: "center",
+            gap: 10,
+            borderBottom: `1px solid ${border}`,
+            flexShrink: 0,
+          }}
+        >
+          <div
+            style={{
+              width: 28,
+              height: 28,
+              background: "#e8a22a",
+              borderRadius: 7,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              flexShrink: 0,
+            }}
+          >
+            <IconWaveform />
+          </div>
+          <div>
+            <div style={{ fontSize: 13, fontWeight: 600, color: "#eeeef2", letterSpacing: -0.2 }}>
+              RehearsalHub
+            </div>
+            {activeBand && (
+              <div style={{ fontSize: 10, color: "rgba(255,255,255,0.25)", marginTop: 1 }}>
+                {activeBand.name}
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Band switcher */}
+        <div
+          ref={dropdownRef}
+          style={{
+            padding: "10px 8px",
+            borderBottom: `1px solid ${border}`,
+            position: "relative",
+            flexShrink: 0,
+          }}
+        >
+          <button
+            onClick={() => setDropdownOpen((o) => !o)}
+            style={{
+              width: "100%",
+              display: "flex",
+              alignItems: "center",
+              gap: 8,
+              padding: "7px 9px",
+              background: "rgba(255,255,255,0.05)",
+              border: "1px solid rgba(255,255,255,0.07)",
+              borderRadius: 8,
+              cursor: "pointer",
+              color: "#eeeef2",
+              textAlign: "left",
+              fontFamily: "inherit",
+            }}
+          >
+            <div
+              style={{
+                width: 26,
+                height: 26,
+                background: "rgba(232,162,42,0.15)",
+                border: "1px solid rgba(232,162,42,0.3)",
+                borderRadius: 7,
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                fontSize: 10,
+                fontWeight: 700,
+                color: "#e8a22a",
+                flexShrink: 0,
+              }}
+            >
+              {activeBand ? getInitials(activeBand.name) : "?"}
+            </div>
+            <span
+              style={{
+                flex: 1,
+                fontSize: 12,
+                fontWeight: 500,
+                overflow: "hidden",
+                textOverflow: "ellipsis",
+                whiteSpace: "nowrap",
+              }}
+            >
+              {activeBand?.name ?? "Select a band"}
+            </span>
+            <span style={{ opacity: 0.3, flexShrink: 0, display: "flex" }}>
+              <IconChevron />
+            </span>
+          </button>
+
+          {dropdownOpen && (
+            <div
+              style={{
+                position: "absolute",
+                top: "calc(100% - 2px)",
+                left: 8,
+                right: 8,
+                background: "#18181e",
+                border: "1px solid rgba(255,255,255,0.1)",
+                borderRadius: 10,
+                padding: 6,
+                zIndex: 100,
+                boxShadow: "0 8px 24px rgba(0,0,0,0.5)",
+              }}
+            >
+              {bands?.map((band) => (
+                <button
+                  key={band.id}
+                  onClick={() => {
+                    navigate(`/bands/${band.id}`);
+                    setDropdownOpen(false);
+                  }}
+                  style={{
+                    width: "100%",
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    padding: "7px 9px",
+                    marginBottom: 1,
+                    background: band.id === activeBandId ? "rgba(232,162,42,0.08)" : "transparent",
+                    border: "none",
+                    borderRadius: 6,
+                    cursor: "pointer",
+                    color: "#eeeef2",
+                    textAlign: "left",
+                    fontFamily: "inherit",
+                  }}
+                >
+                  <div
+                    style={{
+                      width: 22,
+                      height: 22,
+                      borderRadius: 5,
+                      background: "rgba(232,162,42,0.15)",
+                      display: "flex",
+                      alignItems: "center",
+                      justifyContent: "center",
+                      fontSize: 9,
+                      fontWeight: 700,
+                      color: "#e8a22a",
+                      flexShrink: 0,
+                    }}
+                  >
+                    {getInitials(band.name)}
+                  </div>
+                  <span
+                    style={{
+                      flex: 1,
+                      fontSize: 12,
+                      color: "rgba(255,255,255,0.62)",
+                      overflow: "hidden",
+                      textOverflow: "ellipsis",
+                      whiteSpace: "nowrap",
+                    }}
+                  >
+                    {band.name}
+                  </span>
+                  {band.id === activeBandId && (
+                    <span style={{ fontSize: 10, color: "#e8a22a", flexShrink: 0 }}>✓</span>
+                  )}
+                </button>
+              ))}
+
+              <div
+                style={{
+                  borderTop: "1px solid rgba(255,255,255,0.06)",
+                  marginTop: 4,
+                  paddingTop: 4,
+                }}
+              >
+                <button
+                  onClick={() => {
+                    navigate("/");
+                    setDropdownOpen(false);
+                  }}
+                  style={{
+                    width: "100%",
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    padding: "7px 9px",
+                    background: "transparent",
+                    border: "none",
+                    borderRadius: 6,
+                    cursor: "pointer",
+                    color: "rgba(255,255,255,0.35)",
+                    fontSize: 12,
+                    textAlign: "left",
+                    fontFamily: "inherit",
+                  }}
+                >
+                  <span style={{ fontSize: 14, opacity: 0.5 }}>+</span>
+                  Create new band
+                </button>
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Navigation */}
+        <nav style={{ flex: 1, padding: "10px 8px", overflowY: "auto" }}>
+          {activeBand && (
+            <>
+              <SectionLabel>{activeBand.name}</SectionLabel>
+              <NavItem
+                icon={<IconLibrary />}
+                label="Library"
+                active={isLibrary}
+                onClick={() => navigate(`/bands/${activeBand.id}`)}
+              />
+              <NavItem
+                icon={<IconPlay />}
+                label="Player"
+                active={hasActiveSong && (isPlayer || isPlayerPlaying)}
+                onClick={() => {
+                  if (hasActiveSong) {
+                    navigate(`/bands/${playerBandId}/songs/${currentSongId}`);
+                  }
+                }}
+                disabled={!hasActiveSong}
+              />
+            </>
+          )}
+
+          {activeBand && (
+            <>
+              <SectionLabel style={{ paddingTop: 14 }}>Band Settings</SectionLabel>
+              <NavItem
+                icon={<IconMembers />}
+                label="Members"
+                active={isBandSettings && bandSettingsPanel === "members"}
+                onClick={() => navigate(`/bands/${activeBand.id}/settings/members`)}
+              />
+              <NavItem
+                icon={<IconStorage />}
+                label="Storage"
+                active={isBandSettings && bandSettingsPanel === "storage"}
+                onClick={() => navigate(`/bands/${activeBand.id}/settings/storage`)}
+              />
+              <NavItem
+                icon={<IconSettings />}
+                label="Band Settings"
+                active={isBandSettings && bandSettingsPanel === "band"}
+                onClick={() => navigate(`/bands/${activeBand.id}/settings/band`)}
+              />
+            </>
+          )}
+
+          <SectionLabel style={{ paddingTop: 14 }}>Account</SectionLabel>
+          <NavItem
+            icon={<IconSettings />}
+            label="Settings"
+            active={isSettings}
+            onClick={() => navigate("/settings")}
+          />
+        </nav>
+
+        {/* User row */}
+        <div
+          style={{
+            padding: "10px",
+            borderTop: `1px solid ${border}`,
+            flexShrink: 0,
+          }}
+        >
+          <div style={{ display: "flex", alignItems: "center", gap: 4 }}>
+            <button
+              onClick={() => navigate("/settings")}
+              style={{
+                flex: 1,
+                display: "flex",
+                alignItems: "center",
+                gap: 8,
+                padding: "6px 8px",
+                background: "transparent",
+                border: "none",
+                borderRadius: 8,
+                cursor: "pointer",
+                color: "#eeeef2",
+                textAlign: "left",
+                minWidth: 0,
+                fontFamily: "inherit",
+              }}
+            >
+              {me?.avatar_url ? (
+                <img
+                  src={me.avatar_url}
+                  alt=""
+                  style={{
+                    width: 28,
+                    height: 28,
+                    borderRadius: "50%",
+                    objectFit: "cover",
+                    flexShrink: 0,
+                  }}
+                />
+              ) : (
+                <div
+                  style={{
+                    width: 28,
+                    height: 28,
+                    borderRadius: "50%",
+                    background: "rgba(232,162,42,0.18)",
+                    border: "1.5px solid rgba(232,162,42,0.35)",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    fontSize: 10,
+                    fontWeight: 700,
+                    color: "#e8a22a",
+                    flexShrink: 0,
+                  }}
+                >
+                  {getInitials(me?.display_name ?? "?")}
+                </div>
+              )}
+              <span
+                style={{
+                  flex: 1,
+                  fontSize: 12,
+                  color: "rgba(255,255,255,0.55)",
+                  overflow: "hidden",
+                  textOverflow: "ellipsis",
+                  whiteSpace: "nowrap",
+                }}
+              >
+                {me?.display_name ?? "…"}
+              </span>
+            </button>
+
+            <button
+              onClick={() => logout()}
+              title="Sign out"
+              style={{
+                flexShrink: 0,
+                width: 30,
+                height: 30,
+                borderRadius: 7,
+                background: "transparent",
+                border: "1px solid transparent",
+                cursor: "pointer",
+                color: "rgba(255,255,255,0.2)",
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                transition: "border-color 0.12s, color 0.12s",
+                padding: 0,
+              }}
+              onMouseEnter={(e) => {
+                e.currentTarget.style.borderColor = "rgba(255,255,255,0.1)";
+                e.currentTarget.style.color = "rgba(255,255,255,0.5)";
+              }}
+              onMouseLeave={(e) => {
+                e.currentTarget.style.borderColor = "transparent";
+                e.currentTarget.style.color = "rgba(255,255,255,0.2)";
+              }}
+            >
+              <IconSignOut />
+            </button>
+          </div>
+        </div>
+      </aside>
+
+      {/* ── Main content ──────────────────────────────────────────────── */}
+      <main
+        style={{
+          flex: 1,
+          overflow: "auto",
+          display: "flex",
+          flexDirection: "column",
+          background: "#0f0f12",
+        }}
+      >
+        {children}
+      </main>
+    </div>
+  );
+}
+
+function SectionLabel({
+  children,
+  style,
+}: {
+  children: React.ReactNode;
+  style?: React.CSSProperties;
+}) {
+  return (
+    <div
+      style={{
+        fontSize: 10,
+        fontWeight: 500,
+        color: "rgba(255,255,255,0.2)",
+        textTransform: "uppercase",
+        letterSpacing: "0.7px",
+        padding: "0 6px 5px",
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

web/src/components/TopBar.tsx

@@ -0,0 +1,156 @@
+import { useState, useRef, useEffect } from "react";
+import { useNavigate, useLocation, matchPath } from "react-router-dom";
+import { useQuery } from "@tanstack/react-query";
+import { listBands } from "../api/bands";
+import { getInitials } from "../utils";
+
+export function TopBar() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const [dropdownOpen, setDropdownOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  const { data: bands } = useQuery({ queryKey: ["bands"], queryFn: listBands });
+
+  // Derive active band from URL
+  const bandMatch = matchPath("/bands/:bandId/*", location.pathname) ?? matchPath("/bands/:bandId", location.pathname);
+  const activeBandId = bandMatch?.params?.bandId ?? null;
+  const activeBand = bands?.find((b) => b.id === activeBandId) ?? null;
+
+  // Close dropdown on outside click
+  useEffect(() => {
+    if (!dropdownOpen) return;
+    function handleClick(e: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
+        setDropdownOpen(false);
+      }
+    }
+    document.addEventListener("mousedown", handleClick);
+    return () => document.removeEventListener("mousedown", handleClick);
+  }, [dropdownOpen]);
+
+  return (
+    <header
+      style={{
+        position: "fixed",
+        top: 0,
+        left: 0,
+        right: 0,
+        height: 50,
+        background: "#0b0b0e",
+        borderBottom: "1px solid rgba(255,255,255,0.06)",
+        zIndex: 1000,
+        display: "flex",
+        justifyContent: "flex-end",
+        padding: "0 16px",
+        alignItems: "center",
+      }}
+    >
+      <div ref={dropdownRef} style={{ position: "relative" }}>
+        <button
+          onClick={() => setDropdownOpen((o) => !o)}
+          style={{
+            display: "flex",
+            alignItems: "center",
+            gap: 8,
+            padding: "6px 10px",
+            background: "rgba(255,255,255,0.05)",
+            border: "1px solid rgba(255,255,255,0.07)",
+            borderRadius: 8,
+            cursor: "pointer",
+            color: "#eeeef2",
+            textAlign: "left",
+            fontFamily: "inherit",
+            fontSize: 13,
+          }}
+        >
+          <div
+            style={{
+              width: 32,
+              height: 32,
+              background: "rgba(232,162,42,0.15)",
+              border: "1px solid rgba(232,162,42,0.3)",
+              borderRadius: "50%",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              fontSize: 12,
+              fontWeight: 700,
+              color: "#e8a22a",
+              flexShrink: 0,
+            }}
+          >
+            {activeBand ? getInitials(activeBand.name) : "?"}
+          </div>
+        </button>
+
+        {dropdownOpen && bands && (
+          <div
+            style={{
+              position: "absolute",
+              top: "calc(100% + 4px)",
+              right: 0,
+              width: 200,
+              background: "#18181e",
+              border: "1px solid rgba(255,255,255,0.1)",
+              borderRadius: 10,
+              padding: 6,
+              zIndex: 1001,
+              boxShadow: "0 8px 24px rgba(0,0,0,0.5)",
+            }}
+          >
+            {bands.map((band) => (
+              <button
+                key={band.id}
+                onClick={() => {
+                  navigate(`/bands/${band.id}`);
+                  setDropdownOpen(false);
+                }}
+                style={{
+                  width: "100%",
+                  display: "flex",
+                  alignItems: "center",
+                  gap: 8,
+                  padding: "8px 10px",
+                  marginBottom: 2,
+                  background: band.id === activeBandId ? "rgba(232,162,42,0.08)" : "transparent",
+                  border: "none",
+                  borderRadius: 6,
+                  cursor: "pointer",
+                  color: "#eeeef2",
+                  textAlign: "left",
+                  fontFamily: "inherit",
+                  fontSize: 13,
+                }}
+              >
+                <div
+                  style={{
+                    width: 24,
+                    height: 24,
+                    borderRadius: "50%",
+                    background: "rgba(232,162,42,0.15)",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    fontSize: 10,
+                    fontWeight: 700,
+                    color: "#e8a22a",
+                    flexShrink: 0,
+                  }}
+                >
+                  {getInitials(band.name)}
+                </div>
+                <span style={{ flex: 1, fontSize: 13 }}>
+                  {band.name}
+                </span>
+                {band.id === activeBandId && (
+                  <span style={{ fontSize: 12, color: "#e8a22a", flexShrink: 0 }}>✓</span>
+                )}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    </header>
+  );
+}

web/src/hooks/useWaveform.ts

@@ -1,11 +1,14 @@
 import { useEffect, useRef, useState } from "react";
-import WaveSurfer from "wavesurfer.js";
+import { audioService } from "../services/audioService";
+import { usePlayerStore } from "../stores/playerStore";
 
 export interface UseWaveformOptions {
   url: string | null;
   peaksUrl: string | null;
   onReady?: (duration: number) => void;
   onTimeUpdate?: (currentTime: number) => void;
+  songId?: string | null;
+  bandId?: string | null;
 }
 
 export interface CommentMarker {
@@ -19,81 +22,79 @@ export function useWaveform(
   containerRef: React.RefObject<HTMLDivElement>,
   options: UseWaveformOptions
 ) {
-  const wsRef = useRef<WaveSurfer | null>(null);
-  const [isPlaying, setIsPlaying] = useState(false);
   const [isReady, setIsReady] = useState(false);
-  const [currentTime, setCurrentTime] = useState(0);
+  const [error, setError] = useState<string | null>(null);
-  const wasPlayingRef = useRef(false);
   const markersRef = useRef<CommentMarker[]>([]);
 
+  // Playback state comes directly from the store — no intermediate local state
+  // or RAF polling loop needed. The store is updated by WaveSurfer event handlers
+  // in AudioService, so these values are always in sync.
+  const isPlaying = usePlayerStore(state => state.isPlaying);
+  const currentTime = usePlayerStore(state => state.currentTime);
+  const duration = usePlayerStore(state => state.duration);
+
   useEffect(() => {
-    if (!containerRef.current || !options.url) return;
+    if (!containerRef.current) return;
+    if (!options.url || options.url === 'null' || options.url === 'undefined') return;
 
-    const ws = WaveSurfer.create({
+    const initializeAudio = async () => {
-      container: containerRef.current,
+      try {
-      waveColor: "#2A3050",
+        await audioService.initialize(containerRef.current!, options.url!);
-      progressColor: "#F0A840",
-      cursorColor: "#FFD080",
-      barWidth: 2,
-      barRadius: 2,
-      height: 80,
-      normalize: true,
-    });
 
-    // The rh_token httpOnly cookie is sent automatically by the browser.
+        // Restore playback if this song was already playing when the page loaded.
-    ws.load(options.url);
+        // Read as a one-time snapshot — these values must NOT be reactive deps or
+        // the effect would re-run on every time update (re-initializing WaveSurfer).
+        const {
+          currentSongId,
+          currentBandId,
+          isPlaying: wasPlaying,
+          currentTime: savedTime,
+        } = usePlayerStore.getState();
 
-    ws.on("ready", () => {
+        if (
-      setIsReady(true);
+          options.songId &&
-      options.onReady?.(ws.getDuration());
+          options.bandId &&
-      // Reset playing state when switching versions
+          currentSongId === options.songId &&
-      setIsPlaying(false);
+          currentBandId === options.bandId &&
-      wasPlayingRef.current = false;
+          wasPlaying &&
-    });
+          audioService.isWaveformReady()
+        ) {
+          try {
+            await audioService.play(options.songId, options.bandId);
+            if (savedTime > 0) audioService.seekTo(savedTime);
+          } catch (err) {
+            console.warn('Auto-play prevented during initialization:', err);
+          }
+        }
 
-    ws.on("audioprocess", (time) => {
+        setIsReady(true);
-      setCurrentTime(time);
+        options.onReady?.(audioService.getDuration());
-      options.onTimeUpdate?.(time);
+      } catch (err) {
-    });
+        console.error('useWaveform: initialization failed', err);
-
+        setIsReady(false);
-    ws.on("play", () => {
+        setError(err instanceof Error ? err.message : 'Failed to initialize audio');
-      setIsPlaying(true);
+      }
-      wasPlayingRef.current = true;
-    });
-    ws.on("pause", () => {
-      setIsPlaying(false);
-      wasPlayingRef.current = false;
-    });
-    ws.on("finish", () => {
-      setIsPlaying(false);
-      wasPlayingRef.current = false;
-    });
-
-    wsRef.current = ws;
-    return () => {
-      ws.destroy();
-      wsRef.current = null;
     };
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+
-  }, [options.url]);
+    initializeAudio();
+  }, [options.url, options.songId, options.bandId]);
 
   const play = () => {
-    wsRef.current?.play();
+    audioService.play(options.songId ?? null, options.bandId ?? null)
-    wasPlayingRef.current = true;
+      .catch(err => console.error('[useWaveform] play failed:', err));
   };
+
   const pause = () => {
-    wsRef.current?.pause();
+    audioService.pause();
-    wasPlayingRef.current = false;
   };
+
   const seekTo = (time: number) => {
-    if (wsRef.current && isReady && isFinite(time)) {
+    audioService.seekTo(time);
-      wsRef.current.setTime(time);
-    }
   };
 
   const addMarker = (marker: CommentMarker) => {
-    if (wsRef.current && isReady) {
+    if (!isReady) return;
-      const wavesurfer = wsRef.current;
+    try {
       const markerElement = document.createElement("div");
       markerElement.style.position = "absolute";
       markerElement.style.width = "24px";
@@ -102,7 +103,7 @@ export function useWaveform(
       markerElement.style.backgroundColor = "var(--accent)";
       markerElement.style.cursor = "pointer";
       markerElement.style.zIndex = "9999";
-      markerElement.style.left = `${(marker.time / wavesurfer.getDuration()) * 100}%`;
+      markerElement.style.left = `${(marker.time / audioService.getDuration()) * 100}%`;
       markerElement.style.transform = "translateX(-50%) translateY(-50%)";
       markerElement.style.top = "50%";
       markerElement.style.border = "2px solid white";
@@ -127,6 +128,8 @@ export function useWaveform(
       }
 
       markersRef.current.push(marker);
+    } catch (err) {
+      console.error('useWaveform.addMarker failed:', err);
     }
   };
 
@@ -141,7 +144,7 @@ export function useWaveform(
     markersRef.current = [];
   };
 
-  return { isPlaying, isReady, currentTime, play, pause, seekTo, addMarker, clearMarkers };
+  return { isPlaying, isReady, currentTime, duration, play, pause, seekTo, addMarker, clearMarkers, error };
 }
 
 function formatTime(seconds: number): string {

web/src/index.css

@@ -34,3 +34,39 @@ input, textarea, button, select {
   --danger:      #e07070;
   --danger-bg:   rgba(220,80,80,0.1);
 }
+
+/* ── Responsive Layout ──────────────────────────────────────────────────── */
+@media (max-width: 768px) {
+  /* Ensure main content doesn't overlap bottom nav */
+  body {
+    padding-bottom: 60px; /* Height of bottom nav */
+  }
+}
+
+/* Bottom Navigation Bar */
+nav[style*="position: fixed"] {
+  display: flex;
+  background: #0b0b0e;
+  border-top: 1px solid rgba(255, 255, 255, 0.06);
+  padding: 8px 16px;
+}
+
+/* Bottom Nav Items */
+button[style*="flex-direction: column"] {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 8px 4px;
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  color: rgba(255, 255, 255, 0.5);
+  font-size: 10px;
+  transition: color 0.12s;
+}
+
+button[style*="flex-direction: column"][style*="color: rgb(232, 162, 42)"] {
+  color: #e8a22a;
+}

web/src/main.tsx

@@ -5,6 +5,10 @@ import App from "./App.tsx";
 const root = document.getElementById("root");
 if (!root) throw new Error("No #root element found");
 
+// Note: Audio context initialization is now deferred until first user gesture
+// to comply with browser autoplay policies. The audio service will create
+// the audio context when the user first interacts with playback controls.
+
 createRoot(root).render(
   <StrictMode>
     <App />

web/src/pages/BandPage.test.tsx

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { screen } from "@testing-library/react";
+import { renderWithProviders } from "../test/helpers";
+import { BandPage } from "./BandPage";
+
+// ── Mocks ─────────────────────────────────────────────────────────────────────
+
+vi.mock("../api/bands", () => ({
+  getBand: vi.fn().mockResolvedValue({
+    id: "band-1",
+    name: "Loud Hands",
+    slug: "loud-hands",
+    genre_tags: ["post-rock"],
+    nc_folder_path: null,
+  }),
+}));
+
+vi.mock("../api/client", () => ({
+  api: {
+    get: vi.fn().mockImplementation((url: string) => {
+      if (url.includes("/sessions")) {
+        return Promise.resolve([
+          { id: "s1", date: "2026-03-31", label: "Late Night Jam", recording_count: 3 },
+        ]);
+      }
+      if (url.includes("/songs/search")) {
+        return Promise.resolve([]);
+      }
+      return Promise.resolve([]);
+    }),
+    post: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  },
+  isLoggedIn: vi.fn().mockReturnValue(true),
+}));
+
+const renderBandPage = () =>
+  renderWithProviders(<BandPage />, {
+    path: "/bands/:bandId",
+    route: "/bands/band-1",
+  });
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("BandPage — Library view (TC-01 to TC-09)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("TC-01: does not render a member list", async () => {
+    renderBandPage();
+    await new Promise((r) => setTimeout(r, 50));
+    expect(screen.queryByText(/members/i)).toBeNull();
+  });
+
+  it("TC-02: does not render an invite button", async () => {
+    renderBandPage();
+    await new Promise((r) => setTimeout(r, 50));
+    expect(screen.queryByText(/\+ invite/i)).toBeNull();
+  });
+
+  it("TC-03: does not render the Nextcloud folder config widget", async () => {
+    renderBandPage();
+    await new Promise((r) => setTimeout(r, 50));
+    expect(screen.queryByText(/scan path/i)).toBeNull();
+    expect(screen.queryByText(/nextcloud scan folder/i)).toBeNull();
+  });
+
+  it("TC-04: renders sessions grouped by date", async () => {
+    renderBandPage();
+    const sessionEl = await screen.findByText("Late Night Jam");
+    expect(sessionEl).toBeTruthy();
+  });
+
+  it("TC-05: renders the Scan Nextcloud action button", async () => {
+    renderBandPage();
+    const btn = await screen.findByText(/scan nextcloud/i);
+    expect(btn).toBeTruthy();
+  });
+
+  it("TC-06: renders the + Upload button", async () => {
+    renderBandPage();
+    const btn = await screen.findByText(/\+ upload/i);
+    expect(btn).toBeTruthy();
+  });
+
+  it("TC-07: does not render By Date / Search tabs", async () => {
+    renderBandPage();
+    await new Promise((r) => setTimeout(r, 50));
+    expect(screen.queryByText(/by date/i)).toBeNull();
+    expect(screen.queryByText(/^search$/i)).toBeNull();
+  });
+
+  it("TC-08: renders the Library heading", async () => {
+    renderBandPage();
+    const heading = await screen.findByText("Library");
+    expect(heading).toBeTruthy();
+  });
+
+  it("TC-09: renders filter pills including All and Guitar", async () => {
+    renderBandPage();
+    const allPill = await screen.findByText("all");
+    const guitarPill = await screen.findByText("guitar");
+    expect(allPill).toBeTruthy();
+    expect(guitarPill).toBeTruthy();
+  });
+});