Auto-KJ Field Manual

0. Window model (applies to everything below)

Tauri creates five webview windows at startup from src-tauri/tauri.conf.json:13-67, and they all load the same App.svelte. App.svelte:91-102 reads the window label and picks the root component:

• The aux windows are never created or destroyed at runtime. They are only shown or hidden. Closing any aux window with its OS close button is intercepted and hides it instead (src-tauri/src/lib.rs:9429-9435). Closing main destroys all aux windows, releases the license seat, stops the LAN server, and exits the process (lib.rs:9395-9427).
• In the aux windows (not main, not shortcuts), F11 toggles fullscreen through invoke toggle_window_fullscreen {label} (App.svelte:107-118).

1. APP SHELL (main window)

1.1 Layout (top to bottom)

1. Theme decorations (not interactive): - LCARS top frame when the theme is lcars (App.svelte:3283-3285) - Purple-rain overlay for purple-rain themes (3286-3288) - Cobwebs in the header corners for haunted (3290-3293)
2. Header bar <header> (App.svelte:3289-3451). There are two variants. - Standard variant (every theme except word95), left to right:
   1. Brand block: 🎤 logo, "Auto-KJ", version pill v1.27.0 (3372-3378)
   2. Primary tab bar (nav.tabs) (3379-3392)
   3. 🎧 DJ-profile dropdown, only when DJ profiles exist (3393-3405)
   4. Screen buttons cluster: 💬 DJ Inbox, 🖥️ singer screen, 📺 rotation display (3406-3430)
   5. Marquee bulbs, broadway theme only (3431-3433)
   6. Status badges: ● ONLINE (venue) / ● OFFLINE, "N singers", ● LIVE (3434-3446)
   7. Full-width status-message strip under the header row, shown only when a message exists (3448-3450) - Word95 variant ($themeStore === "word95", 3295-3370):
   8. Fake title bar "W Auto-KJ — Rotation.doc v… _ □ ×". Purely decorative spans with no handlers.
   9. Fake menu bar "File Edit View Insert Format Tools Help". Decorative, no handlers.
   10. Toolbar row: decorative icon glyphs ▣📂💾✂▤↶, then the tab buttons, the DJ dropdown, the 💬 (with unread count), 🖥️ and 📺 buttons, and status badges Online: <venue> / Offline, N singers, REC.
   11. The 💬 DJ Inbox button now exists in this variant too (3340-3352). It is the first button of the screen-buttons cluster, same handler and badge as the standard header.
3. Resume banner "▶ Resume <singers> — <title> by <artist> at m:ss?". Shown only when a resumable turn exists (3453-3474).
4. Theme strips: haunted CandleRow (3476-3478) and arcade ArcadeTicker with the venue name (3479-3481).
5. Active tab body (3483-4290): - rotation: Section 2 - break-wave: <DjMode /> - library: <LibraryManager onBack onLibraryChanged> - ghost-trax: <GhostTrax /> - inbox: inline Inbox markup - analytics: <Analytics> - settings: <Settings>
6. Clippy floating assistant, word95 theme only (4291-4293).
7. Global overlays, rendered outside the tab switch, so they show on whichever tab is active (4296-4513): - Queue-row context menu (4296-4334) - Seat conflict dialog (4341-4373) - Seat revoked dialog (4377-4393) - SetupWizard / TabTour (4396-4402) - DJ Inbox modal (4404-4424) - "Change Song in Queue" modal (4426-4485) - Queue "Quarantine File?" modal (4487-4513)

Structural note (changed in this release): The seat-conflict dialog, seat-revoked dialog, SetupWizard and TabTour used to sit inside the Rotation branch. They now live at the App level (App.svelte:4336-4402, under a comment saying they "must render on every tab"), after the tab switch. Only these modals are still declared inside the {#if activeTab === "rotation"} branch (App.svelte:3930-4130), so they only render while the Rotation tab is active: - Past Singers (3930-3986) - Interrupt confirm (3988-4009) - Edit singers (4011-4062) - Rename (4064-4101) - Merge (4103-4131)

What this means in practice (inferred from the code, not observed at runtime): - A seat-conflict or seat-revoked event now shows its dialog immediately, whichever tab the KJ is on. - selectTab() sets activeTour = <tab> for first-visit tabs (App.svelte:735-751, via maybeStartTour), and <TabTour> is mounted at the App level (4398-4401), so the Inbox, Break-Wave, Library, Ghost-Trax, Analytics and Settings tours now display on their own tabs. Leaving a tab mid-tour still marks that tour seen (741-744). - The first-run wizard no longer disappears when the KJ switches tabs (for example Alt+2). It stays up until Finish or Skip. - One-time migration: at startup the main window calls resetUnseenToursOnce() (App.svelte:258; onboarding.ts:29-44). Under the old behaviour those six tabs' tours were marked seen without ever rendering, so the first launch of this version clears their auto-kj-tour-seen-<tab> flags (guard key auto-kj-tours-reset-v1). The Rotation tour flag is left alone.

1.2 Controls: header and global

1.3 Global keyboard shortcuts (main window)

window.addEventListener("keydown", handleMainKeyDown) is registered at App.svelte:2796, and the handler is at 1799-1833.

• Ignored when the target is an editable field (input, textarea, select, contenteditable; keyboardShortcuts.ts:131-136) or is inside a button, a, or [role=button] element (App.svelte:1803). For example, Space on a focused singer row or a focused button does not trigger Play.
• Bindings are per DJ profile, stored in localStorage auto-kj-keyboard-shortcuts. They are reloaded on the auto-kj-keyboard-shortcuts-changed event and on cross-window storage events (1864-1875).
• Repeated keydowns (auto-repeat) are swallowed.
• A failure shows the status toast "Shortcut failed: …" (1812-1815).
• The same playPause / stopComplete / nextSinger handlers are also registered for MIDI controllers (setKaraokeHandlers, App.svelte:2690-2694), and initMidi() now runs at launch in the main window (2695), so mapped MIDI controls work on every tab.

Reserved combos cannot be bound (keyboardShortcuts.ts:67-79): Alt+F4, Ctrl+W/Q/R/C/X/V/Z/Y/A, F5.

Rotation-tab-only keys (from RotationGrid): - Delete or Backspace with a singer selected, focus not in a text field: opens the "Remove <name>?" confirm (RotationGrid.svelte:597-619). - Escape closes the row context menu.

1.4 Where the shortcut editor lives (shortcuts window)

Opened from: Settings, "⌨️ Keyboard Shortcuts" card, button Configure keyboard shortcuts (Settings.svelte:2139-2152). That calls openShortcutSettingsWindow() (lib/shortcutWindow.ts:3-9), which gets the shortcuts window by label and shows, unminimizes and focuses it. On failure it shows the inline error "Could not open keyboard shortcuts: …".

Controls (ShortcutSettings.svelte:164-233):

All controls are disabled when no DJ profile is active, and the window shows "Select or create a DJ profile in the main Settings window before assigning shortcuts." (178-180). Changes reach the main console through the localStorage storage event.

1.5 Auxiliary display windows: what they are and how they open

1.6 DJ Inbox modal (from the header 💬)

Component lib/DjInbox.svelte. Items come from djMessages, which the singer-message-received event fills (App.svelte:2949-2979). Opening the modal marks every current message read, and closing it does so again for anything that arrived while it was up. Each new message also shows a toast: "💖 Tip received from X!", "🎵 Song Buy Request from X: "title"", "↩ X replied: …", or "💬 Message from X: …".

1.7 First-run SetupWizard (lib/SetupWizard.svelte)

When it appears: rendered at the App level (App.svelte:4396-4397, outside the tab switch) when showWizard is true. showWizard starts as !wizardDone() (localStorage auto-kj-setup-wizard-done, App.svelte:259). It now shows on whichever tab is active and survives tab switches (see the note in 1.1). It is a full-screen overlay (z-index 89) and cannot be dismissed by clicking outside.

When it finishes: onFinish, which is finishWizard() (App.svelte:753-758). This marks the wizard done, hides it, and starts the Rotation tab tour.

The step state machine (step, SetupWizard.svelte:18-30):

1.8 TrialActivation (lib/TrialActivation.svelte)

Embedded in the Wizard "trial" step and in Settings, License card (Settings.svelte:1430). It renders nothing unless VITE_APP_TRIAL_ENABLED==="true". Heading: "Try Full version for 60 days", followed by disclosure paragraphs.

A live status line reads "Working…" while busy, or shows the last message. In Settings, a Use Free version button also appears when the source is trial (Settings.svelte:1431-1433; not part of TrialActivation).

1.9 TabTour (lib/TabTour.svelte)

Where and when: a bottom-right card over a dim overlay (z-index 88), mounted at the App level at App.svelte:4398-4401 with tabId=activeTour. It renders on whichever tab owns the tour, so all seven tabs' tours can now display (see the note in 1.1). Tour content comes from lib/onboarding.ts TOURS. Two tour bodies changed in this release: the Break-Wave "The paid extras" step no longer lists headphone CUE as a paid feature, and the Analytics "What your regulars sing" step now describes the two singer views, Most sung and Saved favorites.

Library tour, step "Health and curation" (onboarding.ts:115-120), changed in this commit: it now says library setup lives on the Library tab (Library folder card: Choose Folder…, Rescan now, relink a moved drive) instead of saying scanning happens on the Rotation tab. The Break-Wave "The paid extras" step now also describes AUTOMIX (re-orders the playlist, free; 🎲 New mix, Undo reorder; ▶ Start needs a paid plan), which belongs to the Break-Wave inventory.

The Rotation tour has 7 steps (onboarding.ts:60-92): 1. "This is the show floor" 2. "Add a singer" 3. "Give them a song" 4. "Press ▶" 5. "You're the boss" 6. "Numbers move, or names move" 7. "The header, at a glance"

1.10 PreShowCheck (lib/PreShowCheck.svelte)

This is not in the shell. It is a card on the Settings tab ("✅ Pre-show Check", Settings.svelte:1582-1587). The Rotation tour and the status toasts point to it.

1.11 Floating-license seat dialogs (App-level, rendered on every tab)

1.12 Shell flows

F-S1 First launch 1. App opens with activeTab = rotation and showWizard = true. 2. Welcome. The KJ picks "Skip setup" (go to step 9) or "Set up my show". 3. Plan: Free goes to step 6. Paid goes to "Have a key?". 4. Have a key? Yes goes to Activate (email + key, then refresh_license). Trial goes to TrialActivation (sign in, send code, verify, consent, activate_trial). Not yet goes to Signup (Open auto-kj.com, then either Continue Free, Start the trial, or I have my key now). 5. After activation, the trial, or a skip, the KJ lands on Library. 6. Library: Choose Library Folder, then scan_library_cmd and start_library_watcher (both via libraryScan.scanLibrary). Then Next. (Skipping is fine: the KJ can do the same later from the Library tab's Library folder card, and Rotation's song search will show a "Set up your library →" button until songs exist.) 7. Audio: pick a device (audio_set_output_device), then Next. 8. Lyrics: Launch Lyrics Screen (toggle_lyrics_window), then Next. 9. Done: Start the show calls finishWizard(), which marks the wizard done and opens the Rotation tour. 10. Rotation tour: Next ×6, then Done, which marks it seen.

F-S2 Switch tabs 1. The KJ clicks a tab or presses Alt+1..7. 2. selectTab sets activeTab and resyncs the 🖥️/📺 state. 3. If a tour for a different tab was open, it is marked seen. 4. If this tab's tour hasn't been seen, activeTour is set and the App-level TabTour card renders over the tab.

F-S3 Put screens up 1. Click 🖥️. The lyrics window shows and 🖥️ lights. 2. Drag the window to the TV and press F11 in it for fullscreen. 3. Click 📺. The rotation window shows. Drag it and press F11. 4. Clicking either button again hides that window.

F-S4 Change DJ 1. Pick a name in the 🎧 dropdown. 2. The outgoing settings are saved and the incoming settings are applied. 3. A confirm asks "Is X beginning a new show?". If yes, a second confirm asks "Clear the queue and reset the night?". If yes again, reset_session runs. 4. The host is seated at #1. 5. The window reloads.

F-S5 Read and answer singer messages 1. A message arrives and a toast shows; the 💬 badge count increments. 2. Click 💬 to open the DJ Inbox. The badge clears as it opens. 3. Click "↩ Reply to X", type, then Send Reply (send_direct_message_cmd). 4. Remove handled messages with ✕ per card, or with Clear All.

F-S6 Resume after a crash or close 1. At launch, get_resumable_turn returns the last song, and the banner shows "Resume X — Song at m:ss?". 2. Click "Resume at m:ss" to call resume_turn, which starts playback at that position. Or click ✕ to call dismiss_resumable_turn.

F-S7 Seat conflict 1. A seat-conflict event arrives. The dialog renders at once, on whichever tab is active. 2. Take over calls claim_license_seat(takeOver). If claimed, the app reconnects. Exit quits the app.

2. ROTATION TAB

2.1 Layout (for a wireframe)

The whole tab is div.rotation-shell (App.svelte:3484-3928), a CSS grid of three rows: [player {playerH}px] [5px splitter] [workbench].

┌──────────────────────────────────────────────────────────────────────────────┐
│ ROW 1  PLAYER / transport (Player.svelte) — height playerH (default 142px,   │
│        90–420)                                                               │
│  [VU meter] [mini lyrics monitor 208px] [Now deck title/artist 👏N 👥edit │ time] │
│                                          [playback error strip]              │
│                                          [──────── scrub bar ────────]       │
│                                          [▶/⏸][⏹] Vol── GHOST-TRAX── (GT2──) │
│                                          Key── Tempo── ☐Auto-advance        │
├═════════════════════ horizontal splitter (drag) ═════════════════════════════┤
│ ROW 3 WORKBENCH: columns [rotation {rotW}px, default 360, 240–900] [5px] [right] │
│ ┌──────────── ROTATION PANEL ────────┐║┌──────── RIGHT COLUMN ──────────────┐ │
│ │ (similar-name merge banner)        │║│ SONG SEARCH (searchPct%, def 50%,   │ │
│ │ [LINE][⏸ Paused/Waiting (n)] →Sel  │║│ 15–85%) [Replacing “X”… |Cancel]    │ │
│ │                      [👥+] [☰]     │║│  "Song search" / selected singer    │ │
│ │ 1 (avatars) Name 👏  NOW  [⇄][⊖]   │║│              N songs  M matches     │ │
│ │   ▶ song — artist                  │║│  results list: Title/Artist/Code ×N │ │
│ │ 2 Name ...        ~5m  ON DECK     │║│                        [Add|Taken]  │ │
│ │ 3 ...                              │║│  [Load more]                        │ │
│ │ ...                                │║│  status line (preview/watcher/etc.) │ │
│ │ [Add singer to the back...][+]     │║│  [🔍 Search artist or title...]     │ │
│ │ [Numbers move|Names move] hint     │║│  (empty library: 📁 "No songs in    │ │
│ │                                    │║│  your library yet" + [Set up your  │ │
│ │                                    │║│  library →] shown in results area)  │ │
│ │ ☐ Show applause 👏                 │║├═══ horizontal splitter (drag) ══════┤ │
│ │ ☐ Show singer photos 📷            │║│ SINGER DETAILS                      │ │
│ └────────────────────────────────────┘║│  "Singer: Name [✎][⇄]" / subtitle   │ │
│              vertical splitter (drag) ║│ ┌ Active Queue ──┐┌[History|Favorites]│ │
│                                       ║│ │ song ▲▼✕       ││ sort: Song Artist │ │
│                                       ║│ │ Sung tonight   ││  Times Last sung  │ │
│                                       ║│ │ song ✓ ↺       ││ rows (dbl-click)  │ │
│                                       ║│ └────────────────┘└───────────────────┘ │
│                                       ║└─────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘

Region order:

1. Player panel (App.svelte:3489-3500 → Player.svelte:320-455)
2. Splitter "player" (3502-3508)
3. Workbench (3510-3927): - 3a. Rotation panel (3514-3562): optional similar-name banner (3515-3532), then RotationGrid (3533-3561):
   • grid header: list tabs and buttons (RotationGrid 779-802)
   • list (804-1041)
   • add-singer row (1043-1051)
   • display-mode toggle (1059-1086)
   • applause checkbox (1088-1091)
   • photos checkbox (1093-1096)
   • 3b. Splitter "rotation" (vertical) (3564-3570)
   • 3c. Right column (3572-3926):
   • Song search (3577-3593 → SongSearch.svelte:441-661): an optional replace-mode banner (3578-3583), then header, results, and a bottom bar holding only the status line and the search input (at the bottom; the Choose Library Folder button and scan progress bar are gone)
   • Splitter "search" (3595-3601)
   • Singer details (3603-3925): header, then two columns: Active Queue (3641-3785) and History | Favorites (3788-3923)
4. Overlays (modals and menus) described in 2.5, 2.7, 2.9 and 2.10.

Splitter sizes persist in localStorage: auto-kj-layout-player-h, auto-kj-layout-rot-w, auto-kj-layout-search-pct (App.svelte:1664-1702).

2.2 Controls: layout splitters

2.3 Controls: Player / transport (lib/Player.svelte, props from App.svelte:3490-3499)

The Player receives nowPlaying, nextUp, liveApplause, onStart=handleStart, onStop=handleStop, onKnobsChanged=handleKnobsChanged, hasSelectedTarget = (selectedPlayableEntry !== null), and onEditSingers=openEditSingers. Its live state comes from backend events playback-info, cdg-frame and meter-levels (Player.svelte:287-309).

2.4 Controls: rotation panel (App banner + lib/RotationGrid.svelte)

Similar-name banner (App.svelte:3515-3532)

This banner is shown when similarPair is non-null. That happens when two singers in the line have near-identical names (similarNames) and the pair wasn't dismissed this session. The text reads "🤔 Are A and B the same singer?".

Grid header (RotationGrid.svelte:779-802)

Line list rows (listTab === "line", RotationGrid.svelte:860-1032)

Rows are ordered by calculateDisplaySlots(numbered, displayMode). Each row shows: - position number - optional avatars (when "Show singer photos" is on: cloud avatar from api.auto-kj.com/api/singer/<acct>/avatar, or an initial letter) - 🎸 (band) or 👥 (group) icon, then the label (band name or "A + B"), plus a "(n)" member count for bands - 👏 applause badge (when "Show applause" is on and applause > 0) - status line, one of: - "▶ song — artist" (current) - "⏳ waiting on X" - "song — artist", optionally with "✔ Ready to go" or "⏳ member paused" - "picking a song…" - group consent badges ✓ / ✗ / ⏳ member - NO SHOW row - right side: ⇄ (solo), NEW badge, ~Nm wait badge, and one of NOW / ON DECK (row #2) / ⏸ / ✓ (selected), then the ⊖ remove button

Paused/Waiting list rows (listTab === "paused", RotationGrid.svelte:805-857)

Each row shows ⏸ (paused) or ⏳ (waiting), 👥 for groups, the label, the song, and one of these status lines: - "⏳ waiting on X" - "⏳ waiting on group partners" - "returns at #3 on unpause" (paused rows)

The "returns at #3" wording contradicts the engine rule and the Unpause tooltip. Per AGENTS.md and SPEC §5.3, an unpaused singer returns just behind on-deck in FIFO order, not at a fixed #3.

Below the list (RotationGrid.svelte:1043-1096)

2.5 Row context menu (right-click a Line or Paused row; RotationGrid.svelte:1183-1415)

The title is the slot label. The menu closes on any window click, window resize, or Escape (777, 597-601). Items appear in this order:

2.6 Controls: Song search (lib/SongSearch.svelte; App props at 3584-3592)

The panel receives selectedSinger (label), takenSongs, queuedSingers = singers, onAddSong = handleAddSong, onQueueForSinger = handleQueueForSinger, onScanComplete = handleScanComplete and, new, onOpenLibrary={() => selectTab("library")} (App.svelte:3592). onScanComplete is no longer called from inside SongSearch (it had no scan of its own left to report); the Library tab now reports scans through LibraryManager's onLibraryChanged=handleScanComplete (App.svelte:4135).

On mount refreshCount() (SongSearch.svelte:353-366, called at 369) invokes get_song_count_cmd, sets countKnown = true once it answers (a failed count leaves countKnown as it was, so a backend error can't show the "no library" state), and, if the library is non-empty, runs an empty-query search_songs_cmd, which browses the first 50 default-version songs (catalog/src/search.rs:17-38). It also listens to these events (the scan-progress listener was removed with the scan progress bar; the Library tab and Setup Wizard listen for it now): - library-file-added (trailing re-search plus cloud sync after 800 ms) - library-file-removed - library-watcher-error - queue-verify-notice - preview-error - preview-window-error - preview-ended

2.7 Search-result context menu (SongSearch.svelte:495-614) and its dialogs

Dialogs opened from this menu:

2.8 Controls: Singer details panel (App.svelte:3603-3925)

Header

Active Queue column (3641-3785)

This column is a drop target when a singer is selected: dropping a History or Favorites row here requests that song again (handleQueueDragOver/Leave/Drop, 1736-1761, calling handleAddSongFromHistory). In replace mode that drop replaces the target song like any other pick.

History / Favorites column (3788-3923)

2.9 Queue-row context menu (App.svelte:4296-4334; right-click a pending Active Queue row)

The title is the song title, with the subtitle "Song actions & versions". It is positioned at the cursor, clamped to the window minus 320×260. A backdrop click or right-click closes it.

2.10 Modals on the Rotation tab (full contents)

2.10.1 Past Singers (App.svelte:3930-3986). Opened by the grid's ☰.

2.10.2 Interrupt current song? (3988-4009). Opened by handlePlayNow when a different song is on the mic and the Settings "warn before interrupt" option is on (auto-kj-warn-interrupt). Text: "<current> is still on the mic ("song"). Starting X's "Y" now will stop it and mark it completed."

2.10.3 Change Song in Queue (4426-4485). Opened from the queue context menu. Heading "🔄 Change Song: T", "For: <selected singer>".

For a group queue entry queueEntryPick passes no request id and startReplace refuses with the toast "Group songs can't be swapped in place — remove it and add the new song" (or "That slot has no queued song to replace").

2.10.4 Quarantine File? (queue) (4487-4513). Text: "Are you sure you want to quarantine "T"? The file and its CDG will be safely moved to Library - Quarantine/host-quarantined…"

2.10.5 Who's singing this song? (4011-4062). Opened from the Player's 👥 edit. It shows the song line, a "🎤 <lead>" row tagged "lead", and one row per extra singer.

2.10.6 Rename Singer / Rename which singer? (4064-4101)

Backdrop and Esc close in both modes.

2.10.7 Merge X into… (4103-4131). Hint: "Same person, duplicate entry. The chosen singer keeps their name and the longest-waiting spot; song queues combine. Works when the target is inside a group."

2.10.8 Remove X? (RotationGrid.svelte:1098-1116). Text: "Their seat and every queued song go with them. This can't be undone."

2.10.9 👥 Group / Band Song (RotationGrid.svelte:1118-1181)

2.10.10 ✉ Message X (RotationGrid.svelte:1417-1437). Text: "This will pop up an alert on their phone with a reply option."

2.10.11 🖼 Profile Photo: X (RotationGrid.svelte:1439-1477)

2.10.12 🔄 Change Song: X (grid) (RotationGrid.svelte:1479-1520). Text: "Current: T — A".

App now passes all three callbacks (App.svelte:3555-3557), so the options are live. startReplace refuses when the slot is a group (more than one singer id, toast "Group songs can't be swapped in place — remove it and add the new song") or has no request id (toast "That slot has no queued song to replace"). The menu item also shows for the slot on the mic; picking a replacement for it fails on the backend with "Error: That song is on the mic — it can't be replaced" and replace mode stays on.

2.10.13 ☣️ Quarantine File? (grid) (RotationGrid.svelte:1522-1548). Same text as 2.10.4.

2.10.14 Replace mode (not a modal; App.svelte:372-501, banner 3578-3583, lib/replaceMode.ts). Entered from the grid "Change song…" modal (2.10.12) or the queue "Change Song in Queue" modal (2.10.3).

Grant toast (RotationGrid.svelte:1550-1552): a bottom-centre pill that clears after 4 s. Used by badge, message, photo, quarantine, version-switch, key-change and ban results in the grid.

2.11 Background behaviour visible on the Rotation tab

• The line refreshes on backend events: singer-connected, singer-disconnected, singer-paused and singer-unpaused (debounced 200 ms), plus line-skip-events and remote-control events. refresh() invokes get_line_view, get_singers, get_taken_songs and get_next_up (837-857, 893-910). Refreshes are deferred while a drag is in progress (794-800).
• The KJ's singer order persists in localStorage auto-kj-singer-order (717-733).
• Natural song end fires the song-completed event. The app invokes broadcast_song_completed (or reset_applause) and then runs handleSongCompleted (auto-advance / break music logic, 1416-1517). With completion mode auto_crossfade_break, a song end (and "Rotation complete") starts break music through break_wave_play on the Break-Wave engine rather than the old play_break_track.
• Skip toasts: "🚫 X removed — no song two turns in a row", "⚠ X skipped (no song) — flagged in the line", "⏸ X moved to the pause queue".
• Remote (phone or remote-control) toasts: "▶ Remote: play", "■ Remote: stop", "⏭ Remote: next singer", "Remote: Added X - T", and others (3013-3152). The phone-remote break buttons now drive only the Break-Wave engine (break_wave_play / break_wave_stop / break_wave_skip, listeners at 3046-3069), so Stop Break can no longer cut a singer's karaoke song.
• On startup, on gig change and whenever the gig blocklist refreshes, refreshAlwaysHiddenAvatars() (1880-1895) loads the host's cloud "always hide at my shows" photo list (falling back to the cached list offline) and pushes it into the show via set_always_hidden_avatars. refreshGigBlocklist() (1901-) also sets the active gig first and migrates legacy local blocklist entries into the gig's cloud list.

2.12 Rotation flows

F-R1 Walk-up singer: add a singer, give them a song, play 1. Type a name in "Add singer to the back of the line..." and press Enter or click +. 2. add_singer runs. The toast reads "X joined the back of the line" and the new singer is auto-selected. 3. The search header shows "X". Type in the bottom search box; search_songs_cmd runs after 180 ms. 4. Click Add on a result (the button is greyed out until a singer is selected; the new walk-up singer is auto-selected in step 2). add_song_request runs. If the duplicate policy blocks it, a confirm "Add it anyway?" appears, and OK re-runs with forceDuplicate. Then the result toast appears and the grid refreshes. 5. The song appears in Active Queue and on the singer's grid row. 6. With the player idle, press ▶ or Space. Because X is selected with a Queued song, handlePlayNow runs and the toast reads "Now playing: T". If a song is already playing or paused, ▶ or Space now pauses or resumes it instead. To cut in on the current song, double-click X's queue row (or right-click the grid row and choose ▶ Play now): the Interrupt confirm opens and the KJ chooses Cancel or Interrupt & Play, then play_request_now runs.

F-R2 Normal rotation advance 1. With no singer selected (or the selected singer has no queued song), press ▶. 2. start_playing plays the next rotation slot. 3. The song ends and the song-completed event fires. 4. If Auto-advance is on (or the completion mode is delay_then_auto_play), the toast "Next singer in Ns…" appears, then start_playing runs. If it is off, the toast "Song completed" appears. With completion mode auto_crossfade_break, break_wave_play starts the Break-Wave playlist. 5. Alternatively, press ⏹ (or Ctrl+Shift+S) to run audio_stop and complete_current ("Song completed"), or Ctrl+Shift+N to stop and start the next slot.

F-R3 Queue a song for someone else without changing the selection 1. Right-click a search result. 2. Under "Queue for…", click a singer's name. Or click "＋ Add new singer…", type a name, and press Add. 3. add_singer runs if the name is new, then add_song_request, and the result toast appears.

F-R4 Reorder the line 1. Drag row A onto row B's position. On drop, move_singer {toSlot} runs, followed by a refresh. 2. Alternatively, right-click the row and choose ⏫ Mark as now or 🔼 Mark as on deck; move_singer runs.

F-R5 Re-request from history 1. Select a singer. 2. In History (or Favorites), double-click a row, or drag it onto Active Queue. 3. handleAddSongFromHistory runs add_song_request. If the file is missing, the toast reads ""T" isn't in the current library".

F-R6 Reorder or trim one singer's queue 1. Select the singer. 2. In Active Queue, use ▲/▼ or drag a row; swap_queue_entries runs (chained for a drag). 3. ✕ removes the song immediately (delete_request, no confirm). 4. ↺ on a "Sung tonight" row runs requeue_request.

F-R7 Pause and unpause 1. Right-click the row and choose ⏸ Pause. pause_singer runs and the seat moves to the "⏸ Paused/Waiting" tab, which pulses. 2. Open the Paused/Waiting tab and click ▶ Unpause (or right-click and choose ▶ Unpause). unpause_singer runs and the seat returns just behind on-deck.

F-R8 Duplicate-person cleanup 1. The similar-name banner appears. Click a Merge button (merge_singers) or "Not the same". 2. Or click the row ⇄ (or the details ⇄) to open the "Merge X into…" modal, pick a survivor, and click Merge (merge_singers). 3. Or right-click and use ⇄ Merge with… to pick a survivor; merge_singers runs.

F-R9 Remove a singer 1. Click ⊖, press Delete/Backspace on a selected row, choose "remove" on a NO SHOW row, or right-click and choose 🗑 Remove…. 2. The confirm "Remove X?" appears. Remove runs delete_singer for each member, then the toast and a refresh.

F-R10 Group or band song 1. Click 👥+, or right-click a row and choose 👥 Add to group song… (Mic 1 is pre-filled). 2. Choose 2, 3 or 4 singers, pick each mic (or "+ Add new singer…" and type a name), and optionally a band name. 3. Search for the song and click a result. 4. Click "Add to their queues". add_group_song_request_by_names runs (with the duplicate confirm), then the modal closes and the grid refreshes. 5. The row shows 👥 or 🎸 with consent badges, "⏳ waiting on …", or "✔ Ready to go".

Alternative path: multi-select is not exposed in the grid UI (a click selects the slot's own member ids). A group slot selection plus Add in search uses add_group_song_request.

F-R11 Live lineup edit 1. While a song plays, click "👥 edit" in the Player. 2. Remove extras with ✕, or add singers via "+ Add a singer…" (up to 3 extras). 3. Click Apply. set_current_song_extras runs and the toast reads "Lineup updated.".

F-R12 Headphone preview and version management 1. Right-click a search result and choose 🎧 Preview karaoke song. preview_start runs and the Preview popup window opens. 2. Right-click again and choose ⏹ Stop preview, which runs preview_stop. Closing the popup also stops the preview. 3. Right-click and choose 🎶 Select alternate version…, then pick a version. The "Make this the new default version?" dialog appears, and Yes runs override_song_version_cmd. 4. On a grid row, use 🎚 Song version… to pick a version, or on an Active Queue row, right-click and pick a version. Both run override_song_version_cmd.

F-R13 Bad file 1. Right-click the search result (or the grid row, or the queue row) and choose ☣️ Quarantine…. 2. The confirm names the exact file ("File: <filename>"). Confirm. quarantine_song_cmd runs on that file, it moves to the Quarantine folder, and the list refreshes. (From the search menu the file is the one right-clicked.)

F-R14 Singer relations 1. Right-click a row and choose ✉ Message X…. Type a message and click Send Message (send_direct_message_cmd). 2. Or choose 🏅 Award badge… and pick a badge (POST /api/achievements/grant). 3. Or choose 🚫 Ban X…, confirm, and ban_singer runs (toast "Banned X from this show"). 4. Or choose Hide photo (tonight only), or 🖼 Photo moderation… and pick Hide tonight (set_avatar_hidden), Always hide at my shows (cloud list plus set_always_hidden_avatars) or Report photo to Auto-KJ, then Apply / Send report.

F-R15 Past singers 1. Click ☰ to open the Past Singers modal (get_past_singers). 2. Filter the list and double-click a name. add_singer runs, the modal closes, and the singer is selected.

F-R16 Replace a queued song 1. Right-click the singer's grid row and choose 🔄 Change song… (then 🔍 / 📥 / 📋), or right-click the song in Active Queue and choose 🔄 Change song…. The singer is selected and the banner "Replacing “T” for X…" appears above Song search, with the old song outlined and tagged "Replacing". 2. Pick the new song one of three ways: click Add on a search result; press Use this on another Queued song in Active Queue (swap_queue_entries, then delete_request on the old one); or press Use this (or double-click) on a History or Favorites row (handleAddSongFromHistory, which replaces). 3. For search and history picks replace_request_song runs (with the duplicate confirm). The new song takes the old one's position and the old request is removed only after that succeeds. The toast reads "Replaced “T” with “N” for X" and replace mode ends. 4. Cancel, Esc, switching tab or selecting another singer leaves everything untouched. If the old song plays or is removed meanwhile, the toast "“T” is no longer queued — replace cancelled" appears.

F-R17 First-time library setup from the Rotation tab (new) 1. On a fresh install with an empty catalog, the Song search results area shows 📁 "No songs in your library yet / Pick your karaoke folder on the Library tab." (nothing shows until get_song_count_cmd has answered). 2. Click Set up your library →. onOpenLibrary runs selectTab("library") and the Library tab opens (its first-visit tour may start). 3. On the Library tab, the Library folder card's Choose Folder… opens the native folder dialog and scans it through libraryScan.scanLibrary (scan_library_cmd, then start_library_watcher after a clean scan). Progress and "Imported N songs" show on that card. 4. When the scan finishes, the Library tab calls onLibraryChanged, which is App handleScanComplete (refresh() plus paid-tier syncLibraryToCloud()). 5. Back on Rotation, SongSearch mounts again, refreshCount() finds songs, and the search box and results work normally. (The Setup Wizard's "Your songs" step is the other entry to the same scan code.)

Purpose

The Inbox is the host's triage queue for things singers' phones send that need a host decision before touching the rotation: - Song requests from the singer PWA / kiosk (solo, group/duet, or band), to Approve (optionally reassigned to another singer and/or a different manufacturer version), Reject, or reorder. - Account claims (🪪): a logged-in PWA user asking to take over an "unclaimed" singer entry (e.g. one the host typed in at the desk). Never auto-approved. - GPS departure alerts (📍): a checked-in singer whose phone has been >200 m from the venue for 45+ minutes; the host decides to remove them (after a confirm) or keep them. - Two header toggles control whether singers can send requests at all ("Accept Requests Online") and whether clean requests skip the inbox ("Auto-Approve").

Messages, tips and "buy this song" requests do not land in this tab; they go to the separate DJ Inbox modal (lib/DjInbox.svelte), opened from the 💬 header button. That modal is documented at the end of this section because it is the other "inbox".

Layout (Inbox tab, App.svelte:4137-4284)

+--------------------------------------------------------------------+
| inbox-header:  "📥 Singer Request Inbox"      [x] Auto-Approve     |
|                                               [x] Accept Requests  |
|                                                   Online           |
+--------------------------------------------------------------------+
| inbox-list (vertical stack of cards, in this order):               |
|  1. Departure alert cards (📍 name ... [Remove from line][Keep them])|
|     -> after "Remove from line": "Remove X and their queued songs?" |
|        [Yes, remove][Cancel];  failure => ⚠️ error line under card   |
|  2. Claim cards (🪪 account ... "target" [Approve][Deny])          |
|  3a. Empty state (📥 "No pending requests" ...) if 0 requests AND   |
|      0 claims                                                      |
|  3b. else Request cards (draggable), each:                         |
|      [singer badge + song title/artist] [Version ▼][Assign to ▼]   |
|                                         [Approve | Add to X's queue][Reject] |
+--------------------------------------------------------------------+

Each card is a 3-column row: inbox-info (left), inbox-controls (middle, request cards only), inbox-actions (right).

Note: the empty state checks only requests and claims; departure alerts can show above the "No pending requests" empty state at the same time.

Controls

Non-click behaviors affecting the tab: - singer-request event → new card (or auto-approve) + toast "New request from {singer}!" (App.svelte:2859-2874). - singer-cancelled event → removes all of that singer's pending cards, toast "{singer} withdrew their request" (App.svelte:2930-2944). - session-reset event → clears requests and claims (App.svelte:2845-2849). - F3 persistence: every change to the request list is mirrored with invoke("sync_pending_requests") and restored at launch via get_persisted_pending_requests (App.svelte:2609-2617, 2763-2768). Claims and departure alerts are NOT persisted.

Flows (Inbox tab)

I-1 Open requests online 1. Click tab "Inbox". 2. Tick "Accept Requests Online" → toggle_requests_accepting(true) → toast "Accepting requests online!". 3. (If the backend call fails) checkbox reverts, toast "Failed to enable requests: …".

I-2 Receive a request (manual mode) 1. Singer submits on phone → backend emits singer-request. 2. autoApprove is off → card appended; toast "New request from X!"; Inbox tab label becomes "Inbox (N)" and highlights. 3. Background: get_versions_for_song_cmd → if >1 version, "Version" select appears on the card.

I-3 Approve a request 1. (Optional) choose "Version"; (optional) choose "Assign to" another singer (button relabels "Add to Y's queue"). 2. Click Approve. 3. Reserved-name gate (resolveReservedName, App.svelte:2088-2131): - Name already seated → pass. - Name not reserved by a DJ profile → pass. - Request from the phone account linked to that DJ profile (requester's own name only; req.account_id) → pass. - Reserved by another (non-active) DJ profile → confirm("\"X\" is reserved by DJ P.\n\nIs that really P singing tonight?\n\nOK — yes, it's P\nCancel — someone else"). OK → pass; Cancel → forced rename. - Reserved by the active host → forced rename without asking. - Forced rename: picks name + random 1-999, invoke("notify_forced_rename", …) tells the phone. 4. Group path (co-performers present): each extra name goes through the same gate; then add_group_song_request_by_names (with band name if a band request; requester name for consent invites unless band). Toast "Approved: "Song" for A + B" or "…for 🎸 Band". 5. Solo path: if the target singer does not exist → add_singer; then add_song_request. Toast "Approved request for X" or "Approved: "Song" added to Y's queue (requested by X)". 6. Card removed by key; rotation refresh(). 7. Error branches: - Duplicate policy refusal → confirm("<msg>\n\nAdd it anyway?"). OK → retried with forceDuplicate: true. Cancel → reject_singer_request with reason ""Song" is already taken tonight — pick another song", card removed, toast "Duplicate refused: … — X was notified". - Gig blocked-song list → reject_singer_request with "…not available at this show…", card removed, toast "Blocked song refused: …". - Other error → toast "Failed to approve: …", card stays.

I-4 Reject a request: Click Reject → reject_singer_request → card removed → toast.

I-5 Reorder: Drag a request card onto another card → card moves to that index (local only).

I-6 Auto-Approve mode 1. Tick "Auto-Approve" (toast). 2. Each new singer-request runs approveRequest(req, interactive=false): no confirm dialogs. Duplicates go straight to the hard-refuse path (singer notified); blocklisted songs refused. Reserved names: a name reserved by another (non-active) DJ profile makes resolveReservedName return null, so autoRejectReservedName (App.svelte:2165-2176) calls reject_singer_request with "That name is reserved at this venue — please pick another name", drops the request and shows toast "Auto-rejected "X" — reserved DJ name" (for group requests the offending co-performer's name is the one reported). A name reserved by the ACTIVE host is not rejected: it is force-renamed (digits appended, phone notified) and approved. In auto mode the card is never added to the list, so nothing appears in the inbox either way. Claims and departure alerts are unaffected.

I-7 Account claim: claim-request → claim card → Approve (approve_claim, phone told accepted) or Deny (deny_claim, phone told denied).

I-8 Departure alert: singer-departure-alert → 10 s toast + card → "Remove from line" → confirm "Remove X and their queued songs?" → "Yes, remove" (delete_singer + dismiss_departure_alert, toast "Removed X from the line") or "Cancel"; on failure the card stays with "⚠️ Couldn't remove X: …". Or "Keep them" (dismiss_departure_alert).

DJ Inbox modal (messages, buy requests, tips) — lib/DjInbox.svelte

Purpose: a modal for free-form singer-to-host communication: chat messages, replies, "Ask the DJ to buy this song" requests, and tips. The host can dismiss items or reply to a singer.

How it opens: header button 💬 (class inbox-badge-btn, title "DJ Inbox (Messages, Buy Requests, Tips)") in the standard header (App.svelte:3407-3417) and, now, also in the Word95 skin header (App.svelte:3341-3351, next to 🖥️/📺). The click handler is openDjInbox (App.svelte:354-357); a red unread count badge shows when unreadDjMessagesCount > 0. Items come from singer-message-received events (App.svelte:2949-2979), newest first, each with a toast (💖 tip / 🎵 buy request / ↩ reply / 💬 message). Messages are in memory only (lost on restart). Unread tracking: new messages are read: false; openDjInbox and closeDjInbox both call markDjMessagesRead() (App.svelte:347-361), so the badge clears on open and again on close (covering messages that arrived while the modal was up). While the modal is open, newly arrived messages still bump the badge until it is closed.

Layout:

backdrop (click = close)
+------------------------------------------------+
| 📥 DJ Inbox [count]            [Clear All] [✕] |
+------------------------------------------------+
| empty: 📭 "No messages in your inbox"          |
|   or list of cards:                            |
|  [🎵 Buy Request|💰 Tip|✉ Message] Name [+$x] [✕]|
|  (buy: Title: … / Artist: …)                   |
|  message text                                  |
|  [↩ Reply to Name]  -- or reply box:           |
|  [textarea "Reply to Name…"]                   |
|  (success text) [Cancel] [Send Reply]          |
+------------------------------------------------+

Buy cards have a blue left border, tip cards green.

Modal mount: {#if showDjInboxModal}<DjInbox …/> at App.svelte:4403-4422.

Flow D-1: 💬 → modal (badge clears) → "↩ Reply to X" → type → "Send Reply" → "Reply sent to X!" → (1.5 s) box closes → ✕ on the card to dismiss or ✕/backdrop to close the modal.

All paths are relative to host-app/src/. Line numbers are 1-based and refer to the file named in each row. Rust rows: src-tauri/... means host-app/src-tauri/...; dj-engine/... is at the repo root.

Purpose

Break-Wave is the host app's DJ mode. When no one is singing (between singers, during breaks, before and after the show), the host (KJ) uses it to play "break music" (filler music) so the room is never silent. It is a two-deck DJ console with its own audio engine in Rust (dj_* Tauri commands). That engine plays on its own output device, which you pick in Settings > "Break-Wave (Deck) Output". The tab provides:

• Two decks (A and B). Each deck has load/eject, play/pause, CUE (go back to the start), a pitch/tempo fader, keylock, nudge, tap-tempo beatgrid correction, beatgrid re-analysis, SYNC, 4 saved hot-cue pads, and zoomed plus full-track waveforms.
• A center mixer. It has a 3-band EQ with kill buttons per channel, channel faders with VU meters, a master gain with VU meters and a limiter LED, a crossfader with a curve selector and AutoFade (AF), an optional headphone cue (PFL) with a cue/master blend, and the Automix panel. Automix plays a hands-free set: it re-orders the Break-Wave playlist by BPM, key, energy and artist spread (never the same artist back to back unless unavoidable, unless you tick the checkbox), then crossfades between tracks by itself.
• The Break-Wave playlist (shown under Deck A). It is the ONE break-music playlist for the whole app: the old karaoke-side filler playlist and Deck B's hidden queue were merged into it once at startup. You can edit, shuffle, save, load and analyze it. While an Automix set runs it IS the queue. Automix, the rotation "crossfade to break" mode and the phone remote's Play / Skip / Stop Break buttons all use it.
• The Pro Control Hub (shown under Deck B in place of a playlist). It has deck reset buttons (rate, keylock, EQ, kills and that deck's FX), a 12-pad SFX soundboard, a 16-step drum machine with live pads and a looper, and a per-deck FX rack (filter, delay, reverb, flanger).
• A library browser dock at the bottom (lib/BreakTracks.svelte in dock mode). It lists the break-music folder in Search or Explorer view, and from it you load tracks to a deck or queue them into the playlist.
• MIDI controller support. MIDI starts at app launch (not just when Settings is opened). Built-in presets auto-apply by device name, and Settings > MIDI Controllers & DJ Hardware has a per-action MIDI Learn table (see the MIDI sections below). Mapped controls drive the decks, mixer, Automix, soundboard, drum sequencer and the karaoke transport.

The tab is opened from the main tab bar as "Break-Wave" (App.svelte:238, rendered at App.svelte:4131-4132), or with the default shortcut Alt+3 (lib/keyboardShortcuts.ts:55).

Engine lifecycle. - On mount (lib/dj/DjMode.svelte:25-58), in order: 1. Start listening to the event stream: dj-state at 30 Hz, dj-analysis-ready, dj-analysis-failed, dj-engine-error, automix-state and dj-cue-error (lib/dj/djStore.ts:73-103). 2. invoke("dj_start"). If this fails, a red banner reads "Could not start the audio engine: … Check the Break-Wave output device in Settings." 3. dj_get_snapshot seeds the UI. 4. dj_get_restored_deck_paths handles crash recovery. Whatever was on each deck when the app last closed is re-loaded paused and never auto-played. This happens once per app run. - On unmount (tab exit, DjMode.svelte:60-66): dj_release_if_idle. The engine stops only if no deck is playing, so a playing deck keeps the music going across tab switches (handoff rule H1). - Break music started from outside this tab: the rotation "crossfade to break" completion mode and the phone remote's Play / Skip / Stop Break buttons no longer use a separate karaoke-side filler player (the old play_break_track path is gone). They call break_wave_play, break_wave_skip and break_wave_stop (src-tauri/src/dj.rs:1840-1977), which run this engine and the single Break-Wave playlist even when the tab is not open. See "Remote (tablet or cloud) triggers" for the exact rules. - Karaoke wins over the decks: starting a rotation song stops any Automix run and fades both decks out, then pauses them (dj::on_karaoke_play, src-tauri/src/dj.rs:372-380; called from src-tauri/src/lib.rs:3770 and 4226).

Layout

The page is a vertical flex column that fills the window below the app chrome, with 8 px gaps (DjMode.svelte:85-106):

┌──────────────────────────────────────────────────────────────────────────────┐
│ [⚠️ DJ engine: <error>                                            ✕]  (only on error)
│ [status alert: "Failed to load track onto Deck A: …"]       (5 s, only on failure)
├───────────────────────────┬──────────────────┬───────────────────────────────┤
│ DECK A (1fr)              │ MIXER STRIP      │ DECK B (1fr)                  │
│                           │ (fixed 300 px)   │                               │
│ header: [A] Title ⏏ /     │ A | MASTER | B   │ header: [B] Title ⏏ / Artist  │
│   Artist  KEY  BPM TAPPED✕│ HI  [0] knob KILL│   KEY  BPM                    │
│ ┌wave column──────┬pitch┐ │ MID [0] knob KILL│ ┌wave column──────┬pitch┐     │
│ │zoom waveform 68px│±8  │ │ LOW [0] knob KILL│ │ same as Deck A  │rail │     │
│ │full waveform 34px│±16 │ │ (🎧 CUE)         │ └─────────────────┴─────┘     │
│ │0:00 ●playing -3:12│±50│ │ vfader+VU        │                               │
│ │CUE ▶ ◀ ▶ TAP BG  │fader│ │ MASTER: LIMIT   │ PRO CONTROL HUB               │
│ │ SYNC             │+0.0%│ │ LED, L/R VU,    │ [⚡RESET DECK A][⚡RESET DECK B]│
│ │[1][2][3][4] cues │KEY │ │ master fader %   │ [🎛️SOUNDBOARD][🥁DRUMS][✨FX]  │
│ │deck status line  │    │ │ ─────────────    │ (✓ reset msg · ● MIDI LIVE)   │
│ └──────────────────┴─────┘ │ A [crossfader] B │ ┌ active hub pane ─────────┐  │
│ BREAK-WAVE PLAYLIST (n)   │ [AF]             │ │ Soundboard / Drums / FX  │  │
│              🔀 💾 📂     │ Curve [select]   │ └──────────────────────────┘  │
│ (Save-as / Load popover)  │ (CUE ─── MASTER) │                               │
│ 1 [NOW] Title Artist BPM  │ mixer status     │                               │
│   Key ⚡ [▶next][A][B][▲][▼][✕]│ ─────────────    │                               │
│ …(25 visible, scroll)     │ AUTOMIX Start    │
│                           │ (🎲 New mix)(Undo)│
│                           │ [x] same artist  │                               │
│ [Break-music folder…]     │ mix #a3f9 summary│
│                           │ [Search|Explorer]│                               │
│ [Browse…] [Identify]      │                  │                               │
├───────────────────────────┴──────────────────┴───────────────────────────────┤
│ LIBRARY DOCK (BreakTracks dock; fills remaining height, scrolls)            │
│ (status alert)                                                              │
│ Search pane:  [🔍 Search artist or title...]                                │
│               "N tracks"  (batch status)  [⚡ Analyze All (k)]              │
│               rows: Title/Artist · BPM · Key · [⚡Analyze][→A][→B][⤒Next][+End]
│ Explorer pane: [Library] / sub / sub  [↑ Up]                                │
│               "F folders · T tracks" … [⚡ Analyze All (k)]                 │
│               📁 folder rows, then track rows (same buttons)                │
│ (identify progress bar while AcoustID identify runs)                        │
└──────────────────────────────────────────────────────────────────────────────┘

Region details

1. Engine error banner (DjMode.svelte:86-91). Shown only while $djError is set. Sources: a dj_start failure, the dj-engine-error event (for example, device lost), or dj-cue-error, shown as "Headphone cue: …".
2. Load-failure alert (DjMode.svelte:93-95). Transient (5 s). Only for loads started from the dock or by crash-restore.
3. Deck grid (DjMode.svelte:97-101): three columns, Deck A | MixerStrip | Deck B (minmax(0,1fr) auto minmax(0,1fr)). - Deck (lib/dj/Deck.svelte:592-952). A vertical card:
   • Header row: deck badge (A/B; lit while playing), track info, KEY block, BPM block.
   • Deck body: a 2-column grid, the wave column (flexible) and a pitch rail (64 px on the right).
   • Wave column, top to bottom: zoom waveform (68 px) → full waveform (34 px); or a single dashed "empty deck" placeholder (108 px) when nothing is loaded. Then the time row (elapsed · beat LED + state word · remaining) → transport row → 4 cue pads → deck status line.
   • Pitch rail, top to bottom: range buttons ±8/±16/±50 → vertical pitch fader (top = faster) → "+x.x%" readout → KEY (keylock) button.
   • Below the body: Deck A shows the Break-Wave playlist; Deck B shows the Pro Control Hub.
   • Mixer strip (lib/dj/MixerStrip.svelte:364-481). Fixed 300 px wide:
   • A 3-column grid: channel A | MASTER | channel B.
   • Each channel column: label → HI, MID, LOW cells (label + "0" reset, rotary knob, KILL) → optional 🎧 CUE → vertical fader with stereo VU.
   • MASTER column: label → LIMIT LED → L/R VU → vertical master fader → "%" readout.
   • Crossfader section: A–B horizontal slider → AF button → Curve select → optional CUE–MASTER blend.
   • Mixer status line.
   • Tools: Automix panel (embedded: idle = ▶ RESUME (if resumable), AUTOMIX, ▶ Start, 🎲 New mix, Undo reorder, the "Allow same artist back-to-back" checkbox and a plan summary; running = NOW / NEXT lines with SKIP / STOP / PANIC), then the Search/Explorer tab pair that controls the dock.
4. Library dock (DjMode.svelte:103-105 → lib/BreakTracks.svelte:452-702 with dock=true). One card that fills the rest of the height. The component now contains only the library browser (the old standalone page code was removed). The Search/Explorer tabs are NOT drawn in the dock; they live in the mixer strip. The folder path input is NOT in the dock; it lives in Deck A's playlist section.

Pro Control Hub (lib/dj/ProControlHub.svelte:49-103, under Deck B): - A reset bar: two big buttons side by side (each also switches that deck's FX rack off), then 4 hub tabs. - A reset alert. - The content area. All four panes stay mounted and are hidden with CSS, so drum patterns, loops and FX survive tab switches inside the hub. - Soundboard (SoundboardStreamDeck.svelte:709-773): header (SOUND DECK · SFX badge · ✎ EDIT PADS toggle | 🔊 volume slider) → optional edit hint → status line → a 4-column grid of 12 pads (3 rows). - Drum sequencer (DrumSequencer.svelte:636-798): - Header: TR-PRO brand; transport (▶ START/⏹ STOP, BPM number, SWING slider, SYNC A, SYNC B, preset select, CLR). - Step matrix: left column of 6 track names with S/M buttons; right side has a 16-LED playhead row, then 6 rows × 16 step buttons. - LIVE PADS section: REC arm, hint, then 8 pads in a row. - LOOPER section: bars select, REC MIC, LOAD FILE, status, then the layer list. - Footer: LEVEL slider. - FX rack (DeckFxRack.svelte:118-237): two columns, "FX — DECK A" and "FX — DECK B". Each has a RESET button, then 4 stacked modules: HPF/LPF, ECHO/DELAY, REVERB/SPACE, FLANGER/JET. Each module has an ON/OFF toggle and knobs.

Context menus (lib/dj/ContextMenu.svelte). A fixed-position popup clamped to the viewport. It closes on an outside pointerdown, Escape, any scroll, or a window resize. Clicking an item runs it and then closes the menu. Used by the Deck A playlist rows and the dock library rows.

Controls

DjMode shell (lib/dj/DjMode.svelte)

Deck (lib/dj/Deck.svelte), identical for A and B unless noted

Deck A only: Break-Wave playlist (deck === 0, Deck.svelte:818-948). There is ONE Break-Wave playlist: deck 0's persisted queue. Every dj_*_deck_* / saved-playlist command still takes a deck argument, but the backend validates it and then always uses deck 0 (src-tauri/src/dj.rs:3064-3067). Deck B has no list of its own (its old rows were merged into Deck A's at startup). Automix (dj.rs:1313), the rotation "crossfade to break" mode and the phone remote all read this same list. While a set is running the rows are the queue: every playlist edit calls after_playlist_edit (dj.rs:1477), which re-syncs the running queue (sync_automix_queue_from_playlist, dj.rs:1483; dj-engine/src/automix.rs:1044) and clears the Undo-reorder snapshot. Rows above the playing row that already played are not re-queued; unplayed rows above it wrap round after the rows below it; during a transition the incoming track stays put.

Deck A playlist context menu (Deck.svelte:373-400, rendered at 945-947). The menu acts on the selection, or on the clicked row when nothing is selected. n = number of rows it acts on.

Deck B only: renders <ProControlHub /> in place of the playlist (Deck.svelte:949-951).

Background listeners in Deck: - deck-playlist-updated (payload is the deck number) reloads the playlist. It fires after AUTOMIX / 🎲 New mix / Undo reorder re-order it, after automix_set_next, and after any add / remove / move / shuffle / load-saved. The AutomixPanel also listens to it to refresh whether Undo reorder is available. - dj-analysis-ready patches BPM and key into the playlist rows (Deck.svelte:553-576). - When the track changes, cues are fetched (dj_get_cues) and the TAP count resets (Deck.svelte:56-63).

CuePads (lib/dj/CuePads.svelte), 4 per deck

Waveform (lib/dj/Waveform.svelte)

MixerStrip (lib/dj/MixerStrip.svelte)

All continuous controls follow a debounced write-hold pattern: the invoke is sent 100 ms after the last move, and snapshot updates don't overwrite the control for 600 ms.

AutomixPanel (lib/dj/AutomixPanel.svelte, embedded in the mixer)

The panel now has two states: idle and running. There is no separate plan preview: AUTOMIX re-orders the Break-Wave playlist under Deck A in place (one list). The old "AUTOMIX PLAN - N tracks" list, its Cancel button, its plan rows and the "Upcoming" list were removed. $automixState comes from automix-state events; plan is local component state (the last automix_plan result, lost when the tab is closed).

ProControlHub (lib/dj/ProControlHub.svelte, under Deck B)

SoundboardStreamDeck (lib/dj/SoundboardStreamDeck.svelte), Hub > Soundboard

Audio path: pad → masterGain (volume) → compressor limiter → shared Web Audio bus (webAudioBridge.ts). An AudioWorklet taps the bus and streams it to the Rust engine via invoke("dj_aux_push", …), so SFX come out of the Break-Wave output device, mixed in before the engine limiter. If the engine isn't running, the audio plays through the webview's default device (webAudioBridge.ts:1-124).

Sound source priority per pad: 1. The host-assigned file (read with invoke("dj_read_audio_file",{path}), then decoded). 2. The bundled /sfx/<id>.mp3. 3. The built-in synth patch.

DrumSequencer (lib/dj/DrumSequencer.svelte), Hub > Drum Sequencer

All synthesized with Web Audio on the same shared bus as the soundboard, so it goes to the Break-Wave output. It uses a lookahead scheduler (120 ms lookahead, 25 ms tick).

DeckFxRack + FxKnob (lib/dj/DeckFxRack.svelte, lib/dj/FxKnob.svelte), Hub > Pro FX Rack

Every change sends the deck's FULL FX state: invoke("dj_set_fx",{deck, filter, filterOn, filterWet, delayWet, delayBeats, delayFeedback, delayOn, reverbWet, reverbSize, reverbOn, flangerWet, flangerDepth, flangerOn}). The FX run in the Rust engine, after the EQ and before the fader, so the headphone cue hears them too. If the engine is "not running", the call is retried every 1.5 s (DeckFxRack.svelte:56-90). The same set exists for "FX — DECK A" and "FX — DECK B".

Library dock (lib/BreakTracks.svelte, dock=true)

This is the only place BreakTracks.svelte is used (its one import is DjMode.svelte:9). The component now holds only the library browser: the former standalone "Filler Music & Break Tracks" page (← Back, folder sidebar with "Load All Into Queue", "Play Random Filler Track", the Identify card with Cancel, the "Break Tracks Queue" table with drag-reorder / ▲▼ / Remove / 🔀 Shuffle) and its onBack prop were deleted, along with the legacy filler-playlist calls (get_break_track_playlist, add_break_track, add_all_break_tracks, ...). The dock prop is still declared and the only caller passes it; the right-click menu only works when it is true (BreakTracks.svelte:259-261).

The folder comes from breakLibraryPath (set in Deck A's playlist section). The pane comes from breakLibraryPane (set by the mixer's Search/Explorer tabs).

Library row context menu (BreakTracks.svelte:287-320). Acts on the selection, or on the clicked row.

MIDI mapping (lib/dj/MidiMapping.svelte, Settings > "🎛️ MIDI Controllers & DJ Hardware")

The card in Settings (Settings.svelte:2507-2541) shows the MIDI status dot and "MIDI ACTIVITY" chip, the list of available inputs, and then this panel. Learned bindings are stored in localStorage auto-kj-midi-mappings and follow the DJ profile (they are not a rig key, djProfiles.ts:152-155).

Built-in presets (auto-selected by input port name, first match wins; lib/dj/midiPresets/): - Pioneer DDJ-400 and DDJ-FLX4: per deck Play, Cue, Sync, EQ High/Mid/Low, channel fader, tempo slider as the Pitch fader, performance pads 1-4 as Hot cues 1-4; crossfader (pioneer.ts). - Numark Mixtrack Pro 3 / Pro FX and Mixtrack Platinum FX: per deck Play, Cue, Sync only (numark.ts). - Novation Launchpad Mini MK3 and Launchpad X (Programmer mode): bottom-left 4×3 block = soundboard pads 1-12, the columns to its right = drum live pads 1-8. No LED feedback (novation.ts). - Akai APC mini: pad grid = soundboard 1-12 and drum live pads 1-8; faders = channel faders A/B, crossfader, master. Akai APC40: the same idea on clip pads and its track faders / crossfader / master. Akai MPD218: pads 1-12 = soundboard, pads 13-16 = drum live pads 1-4 (akai.ts).

ContextMenu (lib/dj/ContextMenu.svelte), shared

Keyboard and MIDI mappings (whole tab)

Remote (tablet or cloud) triggers and rotation completion affecting this tab (App.svelte:3039-3069, 1446, 1499): - remote-trigger-soundboard plays an SFX through the shared bus and flashes the pad (at the saved soundboard volume). - Rotation completion. When the completion mode is auto_crossfade_break, the end of a song and "Rotation complete" both call break_wave_play and show its message (or its error, e.g. the empty-playlist message) in the status bar. - remote-play-break → break_wave_play (src-tauri/src/dj.rs:1840-1892, 1931-1943, decided by dj-engine/src/break_plan.rs:24-45). In order: an Automix set is already running → "Break-Wave automix is already running"; a deck is already playing → "Break-Wave is already playing"; the playlist is empty → error "Break-Wave playlist is empty — add tracks on the Break-Wave tab"; free tier → loads the first playlist track on Deck A and plays it; paid and a stopped set is resumable → resumes Automix with the remaining tracks (falls back to a fresh set of the whole playlist); paid otherwise → plan_and_start_fresh: re-orders the playlist with a fresh seed and the saved same-artist checkbox (the same planner as AUTOMIX; a failed re-plan is logged and the set still starts from the list as it stands), then starts the set. The new order is kept in the playlist. Starts the engine if needed. - remote-skip-break → break_wave_skip (dj.rs:1894-1929, 1945-1957, break_plan.rs:59-69). Automix running → mixes to the next track now; empty playlist → the same empty-playlist error; free tier → error "Skipping break tracks needs Automix (paid plan)"; paid with no set running → pauses the decks instantly (no fade), clears the resumable set and starts a fresh set at the playlist track after the one playing (wrapping; the first track if unknown) via the same re-plan (plan_and_start_fresh), so the playlist is re-ordered here too. - remote-stop-break → break_wave_stop (dj.rs:1961-1977). Stops any Automix run and fades both decks out over the Crossfade Transition length, then pauses them ("Break music stopped (fading out)"), or says "No break music is playing". It never touches the karaoke player, so a singer's song is not cut. (This differs from the panel's STOP button, which leaves the music playing.)

Flows

F1. First-time setup: point Break-Wave at a break-music folder 1. Open the Break-Wave tab (tab bar or Alt+3). The engine starts (dj_start). If it fails, a red banner points you to Settings > Break-Wave output device. 2. Under Deck A, at the bottom of the playlist section, click Browse… and pick a folder in the native dialog. (Or type a path in "Break-music folder…" and press Enter or blur the field.) 3. The path is saved (localStorage). The dock at the bottom scans it: in Search view, search_break_track_library_cmd lists every track; in Explorer view, list_break_track_dir_cmd shows sub-folders and tracks. 4. Optional: click ⚡ Analyze All (k) in the dock toolbar to compute BPM and key for the unanalyzed tracks. 5. Optional (paid, AcoustID key set in Settings): click Identify under Deck A. A progress bar appears at the bottom of the dock, and artist/title are filled in when it finishes.

F2. Load a track to Deck A and play it 1. In the dock, find the track: type in 🔍 Search, or switch to Explorer (mixer tab) and click 📁 folders or crumbs. 2. Click →A on the row, or right-click → Load in Deck A. This runs dj_load_track deck 0; the track loads paused. 3. The Deck A header shows the title, artist, KEY and BPM ("—" until analysis finishes). The waveforms show "analyzing…" and then draw. 4. Make sure the crossfader is toward A (or centered) and the A channel fader is up. 5. Click ▶ on Deck A (dj_play). The badge glows, the time runs, and the beat LED flashes. 6. Optional: click the full-track waveform to jump (dj_seek), or press CUE to go back to 0:00 paused.

F3. Crossfade manually from Deck A to Deck B 1. With A playing, load the next track to Deck B (dock →B, or playlist row B). 2. Optional: on Deck B press SYNC (paid) to match B's tempo and phase to A. Or match by ear with B's pitch fader, holding the ◀/▶ nudge buttons. 3. Optional: to pre-listen B, with a cue device configured, press 🎧 CUE on channel B and set the CUE⟷MASTER blend. 4. Press ▶ on Deck B. 5. Drag the crossfader from A to B. Alternatively press AF, which animates it to B over the Crossfade Transition time (default 3 s). 6. Optional: use B's EQ knobs or KILL during the blend. Double-click a knob or press "0" to return it to flat. 7. When A has faded out, press ⏸ or CUE on Deck A, or ⏏ to unload it.

F4. Build the Break-Wave playlist 1. In the dock, click + End to append a track, or ⤒ Next to put it at the top. For several tracks, Ctrl/Shift-click rows, right-click → Add n at end / Add n as next. 2. Deck A's "BREAK-WAVE PLAYLIST (n)" updates (deck-playlist-updated). BPM/key fill in as background analysis finishes (⏳ until then). 3. Reorder with ▲/▼, remove with ✕, or select and right-click → Remove n tracks from playlist. 🔀 shuffles. 4. Save: 💾, type a name, Save (or Enter). 5. Later, restore it: 📂, click a saved name. This REPLACES the current playlist. ✕ next to a name deletes the saved playlist. 6. From any playlist row: A / B, or right-click → Load in Deck A/B, loads that track directly onto a deck.

F5. Run an Automix set (hands-free breaks) 1. Build the playlist (F4). Optional: start a track on a deck first; the planner keeps it first and Automix adopts it as the opener. 2. In the mixer's Automix panel, click AUTOMIX (free). Deck A's playlist re-orders itself in place (automix_plan, seeded and artist-aware), and the panel shows "mix #xxxx · N tracks ordered in the Break-Wave playlist · ⚡ k/m". ⚡ / ∿ icons appear on the playlist rows that have a planned hop. 3. Optional: tick or untick Allow same artist back-to-back (default off), then click 🎲 New mix (also offered in the "Applies to the next plan." hint) to re-order with a fresh seed. Click Undo reorder to put the playlist back in its earlier order. Move rows by hand with ▲ / ▼ / ✕ if you like; that keeps your order but clears Undo. 4. Click ▶ Start (paid). It plays the playlist exactly as it stands now. On the free tier the status line says "Automix requires a paid plan"; stop here. 5. The panel switches to running: "Next: <title> in m:ss", then "mixing…" with a progress bar during each crossfade. NOW and NEXT lines show the current and next track; the playlist rows carry NOW / NEXT tags. 6. During the set: - SKIP mixes to the next track now. - ▶ next on any other playlist row makes that track the next one (it moves to just below the playing row). - Adding from the dock (⤒ Next, + End, right-click menu), removing, moving, shuffling or loading a saved playlist changes the running queue immediately, because the playlist is the queue. 7. To end the set: - STOP: automation stops and the music keeps playing. - PANIC: an instant clean cut to the current track, then stop. 8. After STOP or PANIC, the idle row shows ▶ RESUME. Click it to continue with the playlist as it stands minus what already played, or click AUTOMIX to re-order the whole playlist again.

F6. Set and use hot cues 1. Load a track and play or seek to a point. 2. Click an empty cue pad (e.g. 1). dj_set_cue saves the current position. The pad fills with its color and time, and a colored marker appears on both waveforms. 3. Later, click the filled pad to jump there (dj_jump_cue). Playback state is kept. 4. To clear it, right-click the pad or press and hold for 600 ms (dj_clear_cue).

F7. Fix a wrong beatgrid 1. Look for a "?" after the BPM (low confidence) or beatgrid ticks in the zoom waveform that don't line up. 2. Option A: click BG to force a fresh automatic analysis. 3. Option B: play the deck and click TAP in time with the beat, 4 or more times. The grid is refit, the status says "Beatgrid set from taps — X BPM", and the header shows the TAPPED ✕ chip. 4. To undo taps, click TAPPED ✕ (dj_clear_manual_grid).

F8. Change pitch range and keylock 1. Click ±16 (or ±50) above the pitch fader for a wider range. 2. Drag the pitch fader (up = faster). The readout shows "+x.x%" and the BPM updates. 3. Toggle KEY to keep the vocal pitch natural while the tempo changes. 4. To return to neutral: ⚡ RESET DECK A/B in the Pro Control Hub. This sets rate 1.00×, keylock OFF, all EQs to 0 dB un-killed, and that deck's FX rack off; the channel fader is left where it is.

F9. Fire a sound effect 1. In the Deck B area, open 🎛️ SOUNDBOARD (default tab). 2. Click a pad (e.g. 📢 AIR HORN) or press its key (1). It plays through the Break-Wave output. 3. Adjust the 🔊 slider for soundboard level. The level is saved and also applies to pads fired from the phone remote or a MIDI controller. 4. To use your own sound: click ✎ EDIT PADS, click a pad, pick an audio file. The pad label becomes the file name. Click ✓ DONE. To revert, in edit mode click the pad's ✕.

F10. Drum machine and looper under break music 1. Open 🥁 DRUM SEQUENCER. 2. Pick a preset (e.g. "House 4/4"), or CLR and click step buttons. 3. Click SYNC A (or B) to copy the deck's current BPM. Optionally set SWING. 4. Click ▶ START. Use S/M per track and LEVEL for volume. 5. Finger-drum with the LIVE PADS (or keys Q–I). Arm ● REC to quantize hits into the pattern. 6. Looper: choose the bar count, click ● REC MIC. It waits for the next bar if the sequencer is running, then captures a looping layer. Or click 📂 LOAD FILE. Toggle, adjust or remove layers with ▶/⏸, the slider and ✕. 7. Click ⏹ STOP to stop the sequencer. Loop layers keep running until toggled off.

F11. Apply performance FX to a deck 1. Open ✨ PRO FX RACK. 2. In "FX — DECK A", click ON on a module (e.g. ECHO / DELAY). 3. Drag the MIX/INTENSITY knobs vertically and choose a delay time (1/8…1/1). Each change is sent to the engine immediately (dj_set_fx). 4. Double-click a knob to reset it, or click RESET to restore that deck's defaults (all modules OFF).

F12. Leaving the tab mid-set 1. Switch to another tab while a deck plays. dj_release_if_idle keeps the engine alive because a deck is playing, and the music continues. 2. Break music started elsewhere (rotation completion, the phone remote's Play / Skip / Stop Break) still runs on this engine and playlist. Starting a rotation song fades the decks out and pauses them. 3. Come back to Break-Wave. The UI re-seeds from dj_get_snapshot and the event stream. If no deck was playing when you left, the engine was released; it restarts on return. 4. After an app restart, the tracks that were on the decks reload paused (crash recovery, once per run).

F13. Break music when a song ends, or from the phone 1. Put tracks in the Break-Wave playlist (F4). It is the only break playlist; there is no separate filler list any more. 2. In Settings, choose the completion mode that crossfades to break music. When a song ends or the rotation completes, the app runs break_wave_play: the free tier plays the first playlist track on Deck A, a paid plan starts (or resumes) Automix; a fresh start first re-orders the playlist with a new seed and the saved same-artist checkbox. An empty playlist shows "Break-Wave playlist is empty — add tracks on the Break-Wave tab" in the status bar. 3. From the phone remote, Play Break does the same, Skip Break mixes to the next track (paid; the free tier is told Automix is needed) and Stop Break fades the decks out over the Crossfade Transition time and pauses them. 4. Starting the next singer's song fades the decks out under it and pauses them.

F14. Map a MIDI control 1. Plug in a class-compliant USB or Bluetooth MIDI controller. Nothing needs to be opened first; MIDI starts with the app. Known controllers get a preset automatically. 2. Open Settings and find "🎛️ MIDI Controllers & DJ Hardware". The device row shows its light and "Preset: …" (or "No built-in preset — use Learn"). 3. Open a group (e.g. "Deck A mixer"), click Learn on "EQ High", then turn the knob. The row shows the new "CC n · ch m" tagged "custom". Press Esc or Cancel to abort. 4. Clear removes a binding (and hides its preset binding); Reset to preset drops all custom bindings. Bindings are saved per DJ profile.

Quirks and observations

This document had no standing issue list before the previous release. The items below are problems noticed in the changed code; nothing from the Automix rework fixed an earlier item, so none were dropped.

• (new) MIDI errors are silent. midiActions.ts runs every action through call() / fail(), which only console.warns (midiActions.ts:56-66). A paid-only action on the free tier (e.g. Automix start), or any dj_* command while the engine isn't running (the engine is only started by opening Break-Wave or by loading a track or starting a set), does nothing visible on stage.
• (new) The MIDI Pitch fader action is hard-coded to ±8 % (midiActions.ts:52, 167); it ignores the ±16 / ±50 range buttons on the deck.
• (new) Several preset bindings are unverified guesses, flagged "TODO verify on hardware" in the code: the DDJ tempo-slider direction (may need invert), the FLX4 numbers, the Numark note numbers, and the APC40 and MPD218 note / CC numbers (midiPresets/pioneer.ts:20-21, 43-44, numark.ts:10, akai.ts:42, 72). Users can fix any of them with Learn.
• (new) Web MIDI is missing in some webviews (the code names WebKitGTK). The only sign is the warning line inside the Settings panel (MidiMapping.svelte:44-46); the Break-Wave tab shows nothing.
• (new) Break music started while the Break-Wave tab is closed leaves the engine's tab_active flag set. load_track_blocking and start_automix_set set it to true (dj.rs:2099, 2550), and only opening and then leaving the tab clears it (dj_release_if_idle, dj.rs:2006-2009). The emitter's idle release of the audio device requires tab_active to be false (dj.rs:874), so after such a track or set ends the output device appears to stay held until the tab is visited. The comment at dj.rs:2098 ("Loading is only reachable from the dock inside the tab") is stale now.
• (new) The free-tier Play Break path only loads and plays the first playlist track on Deck A (dj.rs:1884-1890), and Skip Break is refused on the free tier, so nothing in this path queues a following track.
• (new) Skip Break on a paid plan with no Automix running cuts the decks with PauseAll (no fade) before starting the new set (dj.rs:1908-1914), unlike Stop Break, which fades.
• (new) Stop Break (phone) and the Automix panel's STOP behave differently: the panel STOP keeps the current track playing, while the remote Stop fades everything out and pauses.
• (new) Stale wording left in code comments: MixerStrip.svelte:186 still says a cue toggle can be "rejected (free tier / no engine)", and the doc comment above dj_set_cue_enabled (dj.rs:2662) still says "PAID". Only the no-engine and no-cue-device rejections remain.
• (new) Leaving and re-opening the Break-Wave tab loses the panel's local plan: the plan summary and the 🎲 New mix button disappear, while Undo reorder (backend state via automix_can_undo) and the hop icons on the rows (the automixPlanHops store) survive. AUTOMIX has to be pressed again to get New mix back (AutomixPanel.svelte:28, 304).
• (new) The MIDI "Automix start" action and the phone remote / end-of-song start silently re-order the playlist with a fresh seed (replan: true, plan_and_start_fresh, dj.rs:1809-1823), and the new order is permanent. It records an Undo snapshot, but the set start then clears it (dj.rs:2564), so the old order cannot be restored. The on-screen ▶ Start does not re-order. A failed re-plan is only logged with eprintln!.
• (new) The panel's ▶ Start on a playlist that was never planned just plays it in its saved order (no artist spreading and no hop icons except the live one on the playing row); only AUTOMIX / 🎲 New mix apply the artist rule.
• (new) The checkbox is saved and mirrored to the backend only when it changes or the panel mounts (AutomixPanel.svelte:69-71, 143-146); if the mirror fails, the failure is only logged (automixPrefs.ts:42-44), and the phone / MIDI starts keep using the old backend value.
• (new) automix_set_next and the playlist re-sync move rows in the saved playlist: ▶ next permanently re-orders Deck A's list (row moved to just below the playing row), and it also clears the Undo snapshot (dj.rs:2613-2637, 1477-1481).

Source: host-app/src/lib/LibraryManager.svelte (LM), mounted from host-app/src/App.svelte:4134-4135 as <LibraryManager onBack={() => selectTab("rotation")} onLibraryChanged={handleScanComplete} /> — two props: onBack, and onLibraryChanged, called after a folder pick or Rescan now so the App refreshes its song data and syncs the library to the cloud (handleScanComplete, App.svelte:1519). Helpers: host-app/src/lib/libraryScan.ts (pickLibraryFolder, scanLibrary, onScanProgress, scanProgressText; shared with the Setup Wizard), host-app/src/lib/previewPopup.ts (ensurePreviewWindow), popup window host-app/src/lib/PreviewWindow.svelte. First-visit tour text: host-app/src/lib/onboarding.ts:114-136.

Reached by the Library tab in the main tab strip (App.svelte:239) or keyboard shortcut Alt+4 (keyboardShortcuts.ts:39,56, action tabLibrary). The first time it is opened, the TabTour overlay ("The Library tab", 5 steps) shows.

Purpose

The Library tab is the KJ's library-setup and catalog-maintenance console. The Library folder card at the top is where a folder is chosen and scanned (the first-run Setup Wizard does the same through the shared libraryScan.ts). The Rotation tab's song search no longer has a folder button: with an empty catalog it shows a "Set up your library" empty state that opens this tab (onOpenLibrary → selectTab("library"), App.svelte:3591). The rest of the tab keeps the scanned collection healthy:

• shows the library folder, song count and watcher state; picks or changes the folder (Choose Folder…), rescans it (Rescan now) and relinks it to a moved drive/folder without a rescan (Relink Folder);
• shows catalog stats (songs, artists, duplicate groups, unparsed, missing files, top brands) and exports a songbook CSV;
• sets the brand (manufacturer) priority that decides which copy of a song is the default when you own several;
• lets you override the default version of one song (clicking a duplicate scrolls to and flashes its Version Options card), audition versions in headphones (🎧 cue device, paid, with key shift), rename or quarantine individual files;
• repairs bad metadata (unparsed filenames, wrong artist/title/brand) and can rename the files to match;
• cleans up loose MP3+CDG pairs, removes catalog rows whose files are missing, audits zips for corruption, quarantines redundant exact copies, merges near-duplicate title spellings and consolidates artist spelling variants;
• reloads everything on demand (↻ Refresh);
• starts/stops the live folder watcher.

Throughout, nothing is deleted. "Quarantine" moves files to a sibling folder <LibraryName> - Quarantine/<reason>/ next to the library root (catalog/src/maintenance.rs:41-51; reasons used: host-quarantined, corrupt, duplicates). "Remove from catalog" only deletes DB rows.

The only progress bar on the tab is the one in the Library folder card, shown while Choose Folder… or Rescan now runs. Everything else is reported through one status banner (statusMessage, also used by Relink Folder and the Start/Stop Watcher button) and through button labels that change ("Saving…", "Working…", "Auditing…", "Searching…"). The Library folder card has its own status line (folderStatus) for pick/scan/rescan results, which never clears itself. Most banner messages clear themselves after 3–12 s. Every bulk action (remove all missing, quarantine flagged / extra copies, run cleanup, merge, consolidate, and Rescan now) first asks a confirmation ("bulk-confirm modal").

Layout

The whole page (section.library-page) scrolls vertically inside the console, with 24px padding (LM:1978-1984).

1. Header row (flex, left to right) (LM:1056-1071) - ← Back button - H1 "Library Management" - Header actions: Watcher badge (dot + "Watcher: Active/Stopped"; highlighted when active), ↻ Refresh button, Start Watcher / Stop Watcher button. (Relink Folder is no longer here; it moved to the Library folder card.)
2. Status banner (div.status-alert, full width). Shown only while statusMessage is non-empty (LM:1073-1075).
3. Library folder card (div.folder-card; new; LM:1077-1113): a two-column grid. Left: the label "Library folder"; the saved path (monospace, ellipsised, full path in the tooltip) or "No library folder chosen yet — pick the folder that holds your karaoke files."; and a meta line "N songs · Watcher: Active/Stopped". Right: Choose Folder… (accent button, label "Scanning…" while busy), Rescan now, Relink Folder. Full width below: the card status line (folderStatus, only when non-empty) and, while a scan is running and a progress event has arrived, a thin progress bar (an indeterminate sliding indicator while the total is still 0).
4. Stats row (flex-wrap; shown once get_library_stats_cmd has returned) (LM:1115-1129): tiles for songs, artists, duplicate groups, unparsed (warning style if >0), missing files (warning style if >0); then up to 10 brand chips ("SC 12,345"); then the Export Songbook CSV button.
5. Card grid (div.library-grid): CSS grid with repeat(auto-fit, minmax(400px, 1fr)), 20px gap, max width 1000px, so it is two columns on a wide window. Cards marked (full) span both columns. In DOM order:
6. Brand Priority Order (left half), always shown: description; unsaved bar (only when the order is changed: "Order changed — not saved yet." + 💾 Save Order + Revert); adder row (text input + Add Code); ranked list of draggable rows #n CODE [⤒][▲][▼][⤓][✕] (scrolls after about 25 rows).
7. Duplicate Tracks (N) (right half), always shown: description; filter input; scrollable list of buttons (bold title and artist below it); the selected group is highlighted. Renders the first 200 matching groups; when more match, a footer "Showing 200 of N. [Show more]" appears (each click adds 200; the count resets to 200 when the filter text changes).
8. Fix Unparsed Songs (N) (full), always shown: rows of filename + [Fix…] [Quarantine]; a row in edit mode shows an optional 💡 suggestion note plus an inline editor (Artist, Title, Brand, ☑ Rename file to match, Save, Cancel). Capped at 200 rows, with a "Showing the first 200…" footer.
9. Edit Song Details (full), always shown: search input; then "Searching…", "No songs match", or result rows ("Artist - Title" [BRAND badge] filename) + [Edit…], which expand into the same inline editor.
10. Loose File Cleanup (full), always shown: description; [Preview] [Run Cleanup]; summary box after a run (bold count line, "Moved files go to: …", then per-file lines 📦 zipped / 📤 moved / ⚠️ skipped, or "Library is already clean").
11. Missing Files (N) (full), only when missing files are >0: [Remove All From Catalog]; rows "Artist - Title" + filepath + [Remove]. Capped at 200 rows, with an "…and N more" footer.
12. Corrupt File Audit (full), always shown: [Run Audit] and, when problems are found, [Quarantine All Flagged (N)]; result area ("Every zip opened cleanly…" or ⚠️ lines "path — reason").
13. Library Health — some checks failed (full), only when a health report failed: one ⚠️ line per failed check.
14. Redundant Copies (N groups) (full), only when exact duplicates exist: [Quarantine Extra Copies (N)]; optional "Showing the first X of Y" note; lines "✅ keep: path" / "📤 quarantine: path".
15. Possible Duplicate Spellings (N) (full), only when near-duplicates exist: optional "Showing first X of Y"; rows with the artist (bold), "Title A" (countA) vs "Title B" (countB), a merged-title text input, [Merge & rename files], and [Not a duplicate].
16. Artist Spelling Variants (N) (full), only when clusters exist: optional "Showing first…"; rows with a radio group of spellings Variant (count) + [Consolidate].
17. Version Options: Artist - Title (full), only after a Duplicate Tracks entry is clicked. It is the last card on the page; clicking a duplicate smooth-scrolls it to the top of the view and flashes it with an accent glow for about 1.8 s. It holds a preview bar ("🎧 Karaoke preview (cue device)" label, Key range slider −6…+6 in 0.5 steps with a signed value, [⏹ Stop preview] while previewing, and a red preview-error text when there is an error) and a versions table (columns: Default | Brand | Disk/Track | Filename | Action). The default row is highlighted with a DEFAULT badge. The Action cell has a 🎧/⏹ button and either [Make Default] or the "Selected" label. The table scrolls after about 25 rows. You can right-click a row.
18. Overlays (fixed position, z-index 900/901, outside the section): - Version context menu: appears at the cursor, clamped so it stays on screen (LM:1786-1833). The title is the filename. Items: ⭐ Make this the default version (only on a non-default row), ✏️ Rename file…, ☣️ Quarantine this file… (danger red). A transparent full-screen backdrop closes it on click or right-click. - Rename file modal: centred (LM:1835-1861). H4 "Rename file", a hint, a text input (autofocus, pre-filled with the current filename), [Cancel] [Rename]. - Bulk-confirm modal (.ver-modal look, aria-label="Confirm bulk action"; LM:1863-1874): shown before every bulk action. H4 = a counted question, a hint sentence, [Cancel] [action button]. Backdrop click or Cancel closes it without doing anything; there is no Escape handler. The action buttons are: "Remove them" (Remove N missing entries from the catalog?), "Quarantine them" (Move N files to Quarantine?, flagged files), "Quarantine extras" (Move N files to Quarantine?, redundant copies), "Run cleanup" (Clean up N loose file groups?, hint gives pairs to zip and bare MP3s to move), "Merge & rename" (Merge N files as "Title"?), "Consolidate" (Consolidate N songs under "Artist"?) and "Rescan" (Rescan the whole library?, hint "New and changed files are picked up; nothing is deleted."). Counts use thousands separators and singular/plural wording. - Quarantine confirm modal: centred (LM:1875-1889). H4 "Quarantine this file?", a hint naming the file, [Cancel] [Quarantine it].
19. Preview popup window: a separate Tauri window (PreviewWindow.svelte), a small always-on-top CDG monitor docked to the main window. The top bar shows the file name, a "🔇 silent" badge when there is no audio, and position / duration. Below it is the CDG frame or a placeholder ("Waiting for preview…", "No lyrics graphics in this file — audio preview only", or the error text in amber). The window has no buttons. Closing it with the OS close button calls preview_stop and hides the window instead of destroying it (PreviewWindow.svelte:34-41).

On mount (LM:1027-1052), the tab loads in parallel: get_manufacturer_prefs_cmd, get_duplicate_groups_cmd, get_unparsed_songs_cmd, the health set (get_library_stats_cmd, get_missing_files_cmd, get_exact_duplicates_cmd, get_near_duplicates_cmd, get_artist_variants_cmd, each independent so that one failure only adds a line to the "some checks failed" card), and get_library_watcher_status, and the Library folder card's get_library_path_cmd + get_song_count_cmd (loadLibraryFolder). It also subscribes to the preview-window-error event and to the backend scan-progress event (onScanProgress; ignored unless a Choose Folder…/Rescan now scan is running). ↻ Refresh (header) reloads the same data on demand (see Controls). Data also reloads after actions, or when you leave the tab and come back (the component remounts).

Controls