Merge branch 'main' into feat/waveform-loudness-cache

# Conflicts: # src/store/playerStore.ts
2026-07-22 14:35:41 +00:00 · 2026-04-25 21:47:48 +02:00
parent e009fd1823 f3acb795fb
commit 453151f1fc
76 changed files with 9658 additions and 263 deletions
@@ -57,6 +57,8 @@ interface AlbumTrackListProps {
  userRatingOverrides: Record<string, number>;
  starredSongs: Set<string>;
  onPlaySong: (song: SubsonicSong) => void;
+  /** Optional dbl-click handler — currently set only in Orbit mode so the list knows to bind it. */
+  onDoubleClickSong?: (song: SubsonicSong) => void;
  onRate: (songId: string, rating: number) => void;
  onToggleSongStar: (song: SubsonicSong, e: React.MouseEvent) => void;
  onContextMenu: (x: number, y: number, track: Track, type: 'song' | 'album' | 'artist' | 'queue-item' | 'album-song') => void;
@@ -80,6 +82,7 @@ interface TrackRowProps {
  inSelectMode: boolean;
  isContextMenuSong: boolean;
  onPlaySong: (song: SubsonicSong) => void;
+  onDoubleClickSong?: (song: SubsonicSong) => void;
  onRate: (songId: string, rating: number) => void;
  onToggleSongStar: (song: SubsonicSong, e: React.MouseEvent) => void;
  onContextMenu: AlbumTrackListProps['onContextMenu'];
@@ -100,6 +103,7 @@ const TrackRow = React.memo(function TrackRow({
  inSelectMode,
  isContextMenuSong,
  onPlaySong,
+  onDoubleClickSong,
  onRate,
  onToggleSongStar,
  onContextMenu,
@@ -224,6 +228,11 @@ const TrackRow = React.memo(function TrackRow({
          onPlaySong(song);
        }
      }}
+      onDoubleClick={onDoubleClickSong ? e => {
+        if ((e.target as HTMLElement).closest('button, a, input')) return;
+        if (e.ctrlKey || e.metaKey || inSelectMode) return;
+        onDoubleClickSong(song);
+      } : undefined}
      onContextMenu={e => {
        e.preventDefault();
        setContextMenuSongId(song.id);
@@ -266,6 +275,7 @@ export default function AlbumTrackList({
  userRatingOverrides,
  starredSongs,
  onPlaySong,
+  onDoubleClickSong,
  onRate,
  onToggleSongStar,
  onContextMenu,
@@ -644,6 +654,7 @@ export default function AlbumTrackList({
                inSelectMode={inSelectMode}
                isContextMenuSong={contextMenuSongId === song.id}
                onPlaySong={onPlaySong}
+                onDoubleClickSong={onDoubleClickSong}
                onRate={onRate}
                onToggleSongStar={onToggleSongStar}
                onContextMenu={onContextMenu}
@@ -7,10 +7,15 @@ interface ConfirmModalProps {
  title: string;
  message: string;
  confirmLabel: string;
-  cancelLabel: string;
+  /**
+   * Cancel button label. Omit (together with `onCancel`) to render the
+   * modal as a single-button info dialog — Esc / outside-click / X then
+   * also resolve via `onConfirm`.
+   */
+  cancelLabel?: string;
  danger?: boolean;
  onConfirm: () => void;
-  onCancel: () => void;
+  onCancel?: () => void;
 }

 export default function ConfirmModal({
@@ -23,15 +28,17 @@ export default function ConfirmModal({
  onConfirm,
  onCancel,
 }: ConfirmModalProps) {
+  const dismiss = onCancel ?? onConfirm;
+
  useEffect(() => {
    if (!open) return;
    const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onCancel();
+      if (e.key === 'Escape') dismiss();
      else if (e.key === 'Enter') onConfirm();
    };
    window.addEventListener('keydown', onKey);
    return () => window.removeEventListener('keydown', onKey);
-  }, [open, onCancel, onConfirm]);
+  }, [open, dismiss, onConfirm]);

  if (!open) return null;

@@ -42,7 +49,7 @@ export default function ConfirmModal({
  return createPortal(
    <div
      className="modal-overlay"
-      onClick={onCancel}
+      onClick={dismiss}
      role="dialog"
      aria-modal="true"
      style={{ alignItems: 'center', paddingTop: 0 }}
@@ -52,7 +59,7 @@ export default function ConfirmModal({
        onClick={e => e.stopPropagation()}
        style={{ maxWidth: '380px' }}
      >
-        <button className="modal-close" onClick={onCancel} aria-label={cancelLabel}>
+        <button className="modal-close" onClick={dismiss} aria-label={cancelLabel ?? confirmLabel}>
          <X size={18} />
        </button>
        <h3 style={{ marginBottom: '0.5rem', fontFamily: 'var(--font-display)' }}>{title}</h3>
@@ -60,10 +67,12 @@ export default function ConfirmModal({
          {message}
        </p>
        <div style={{ display: 'flex', justifyContent: 'flex-end', gap: '8px' }}>
-          <button className="btn btn-ghost" onClick={onCancel} autoFocus>
-            {cancelLabel}
-          </button>
-          <button className="btn btn-primary" style={confirmStyle} onClick={onConfirm}>
+          {cancelLabel && onCancel && (
+            <button className="btn btn-ghost" onClick={onCancel} autoFocus>
+              {cancelLabel}
+            </button>
+          )}
+          <button className="btn btn-primary" style={confirmStyle} onClick={onConfirm} autoFocus={!cancelLabel}>
            {confirmLabel}
          </button>
        </div>
@@ -1,5 +1,12 @@
 import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
-import { Play, ListPlus, Radio, Heart, Download, ChevronRight, User, Disc3, ListMusic, Plus, Info, Sparkles, Star, Trash2, HeartCrack, Share2 } from 'lucide-react';
+import { Play, ListPlus, Radio, Heart, Download, ChevronRight, User, Disc3, ListMusic, Plus, Info, Sparkles, Star, Trash2, HeartCrack, Share2, Orbit as OrbitIcon } from 'lucide-react';
+import { useOrbitStore } from '../store/orbitStore';
+import {
+  suggestOrbitTrack,
+  hostEnqueueToOrbit,
+  evaluateOrbitSuggestGate,
+  OrbitSuggestBlockedError,
+} from '../utils/orbit';
 import LastfmIcon from './LastfmIcon';
 import StarRating from './StarRating';
 import { lastfmLoveTrack, lastfmUnloveTrack } from '../api/lastfm';
@@ -962,6 +969,7 @@ function MultiPlaylistToPlaylistSubmenu({ playlists, onDone, triggerId }: { play

 export default function ContextMenu() {
  const { t } = useTranslation();
+  const orbitRole = useOrbitStore(s => s.role);
  const { contextMenu, closeContextMenu, playTrack, enqueue, queue, currentTrack, removeTrack, lastfmLovedCache, setLastfmLovedForSong, starredOverrides, setStarredOverride, openSongInfo, userRatingOverrides, setUserRatingOverride } = usePlayerStore(
    useShallow(s => ({
      contextMenu: s.contextMenu,
@@ -1454,6 +1462,38 @@ export default function ContextMenu() {
              <div className="context-menu-item" onClick={() => handleAction(() => enqueue([song]))}>
                <ListPlus size={14} /> {t('contextMenu.addToQueue')}
              </div>
+              {orbitRole === 'guest' && (() => {
+                const muted = evaluateOrbitSuggestGate().reason === 'muted';
+                return (
+                  <div
+                    className={`context-menu-item${muted ? ' is-disabled' : ''}`}
+                    {...(muted ? { 'data-tooltip': t('orbit.suggestBlockedMuted') } : {})}
+                    onClick={() => handleAction(() => {
+                      if (muted) { showToast(t('orbit.suggestBlockedMuted'), 3500, 'error'); return; }
+                      suggestOrbitTrack(song.id)
+                        .then(() => showToast(t('orbit.ctxSuggestedToast'), 2200, 'info'))
+                        .catch(err => {
+                          if (err instanceof OrbitSuggestBlockedError && err.reason === 'muted') {
+                            showToast(t('orbit.suggestBlockedMuted'), 3500, 'error');
+                          } else {
+                            showToast(t('orbit.ctxSuggestFailed'), 3000, 'error');
+                          }
+                        });
+                    })}
+                  >
+                    <OrbitIcon size={14} /> {t('orbit.ctxAddToSession')}
+                  </div>
+                );
+              })()}
+              {orbitRole === 'host' && (
+                <div className="context-menu-item" onClick={() => handleAction(() => {
+                  hostEnqueueToOrbit(song.id)
+                    .then(() => showToast(t('orbit.ctxAddedHostToast'), 2200, 'info'))
+                    .catch(() => showToast(t('orbit.ctxAddHostFailed'), 3000, 'error'));
+                })}>
+                  <OrbitIcon size={14} /> {t('orbit.ctxAddToSessionHost')}
+                </div>
+              )}
              <div
                className={`context-menu-item context-menu-item--submenu ${playlistSubmenuOpen && playlistSongIds[0] === song.id ? 'active' : ''}`}
                data-playlist-trigger-id={song.id}
@@ -1586,6 +1626,38 @@ export default function ContextMenu() {
              <div className="context-menu-item" onClick={() => handleAction(() => enqueue([song]))}>
                <ListPlus size={14} /> {t('contextMenu.addToQueue')}
              </div>
+              {orbitRole === 'guest' && (() => {
+                const muted = evaluateOrbitSuggestGate().reason === 'muted';
+                return (
+                  <div
+                    className={`context-menu-item${muted ? ' is-disabled' : ''}`}
+                    {...(muted ? { 'data-tooltip': t('orbit.suggestBlockedMuted') } : {})}
+                    onClick={() => handleAction(() => {
+                      if (muted) { showToast(t('orbit.suggestBlockedMuted'), 3500, 'error'); return; }
+                      suggestOrbitTrack(song.id)
+                        .then(() => showToast(t('orbit.ctxSuggestedToast'), 2200, 'info'))
+                        .catch(err => {
+                          if (err instanceof OrbitSuggestBlockedError && err.reason === 'muted') {
+                            showToast(t('orbit.suggestBlockedMuted'), 3500, 'error');
+                          } else {
+                            showToast(t('orbit.ctxSuggestFailed'), 3000, 'error');
+                          }
+                        });
+                    })}
+                  >
+                    <OrbitIcon size={14} /> {t('orbit.ctxAddToSession')}
+                  </div>
+                );
+              })()}
+              {orbitRole === 'host' && (
+                <div className="context-menu-item" onClick={() => handleAction(() => {
+                  hostEnqueueToOrbit(song.id)
+                    .then(() => showToast(t('orbit.ctxAddedHostToast'), 2200, 'info'))
+                    .catch(() => showToast(t('orbit.ctxAddHostFailed'), 3000, 'error'));
+                })}>
+                  <OrbitIcon size={14} /> {t('orbit.ctxAddToSessionHost')}
+                </div>
+              )}
              <div
                className={`context-menu-item context-menu-item--submenu ${playlistSubmenuOpen && playlistSongIds[0] === song.id ? 'active' : ''}`}
                data-playlist-trigger-id={song.id}
@@ -0,0 +1,25 @@
+import { useConfirmModalStore } from '../store/confirmModalStore';
+import ConfirmModal from './ConfirmModal';
+
+/**
+ * App-level singleton renderer for the global confirm modal. Mount once
+ * in App.tsx; any code path can then call
+ * `useConfirmModalStore.getState().request(...)` and await the user's decision.
+ */
+export default function GlobalConfirmModal() {
+  const { isOpen, title, message, confirmLabel, cancelLabel, danger, confirm, cancel } =
+    useConfirmModalStore();
+
+  return (
+    <ConfirmModal
+      open={isOpen}
+      title={title}
+      message={message}
+      confirmLabel={confirmLabel}
+      cancelLabel={cancelLabel}
+      danger={danger}
+      onConfirm={confirm}
+      onCancel={cancelLabel ? cancel : undefined}
+    />
+  );
+}
@@ -0,0 +1,133 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Check, X, Inbox } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import {
+  approveOrbitSuggestion,
+  declineOrbitSuggestion,
+  suggestionKey,
+} from '../utils/orbit';
+import {
+  getSong,
+  buildCoverArtUrl,
+  coverArtCacheKey,
+  type SubsonicSong,
+} from '../api/subsonic';
+import CachedImage from './CachedImage';
+import { ORBIT_DEFAULT_SETTINGS } from '../api/orbit';
+
+/**
+ * Host-only approval strip. Renders directly below the OrbitQueueHead
+ * when `autoApprove === false` and at least one guest suggestion is
+ * waiting. Shows each pending track with Approve / Decline controls.
+ *
+ * Only rendered by the host-side render path (QueuePanel); guests never
+ * see this section — they watch their own pending list.
+ */
+export default function HostApprovalQueue() {
+  const { t } = useTranslation();
+  const role = useOrbitStore(s => s.role);
+  const state = useOrbitStore(s => s.state);
+  const mergedKeys = useOrbitStore(s => s.mergedSuggestionKeys);
+  const declinedKeys = useOrbitStore(s => s.declinedSuggestionKeys);
+
+  const settings = state?.settings ?? ORBIT_DEFAULT_SETTINGS;
+  const autoApproveOff = settings.autoApprove === false;
+
+  // Pending = everything in the session's suggestion history that isn't
+  // host-authored, isn't already merged, and hasn't been declined.
+  const pendingItems = useMemo(() => {
+    if (!state) return [];
+    const mergedSet = new Set(mergedKeys);
+    const declinedSet = new Set(declinedKeys);
+    return state.queue.filter(q =>
+      q.addedBy !== state.host
+      && !mergedSet.has(suggestionKey(q))
+      && !declinedSet.has(suggestionKey(q))
+    );
+  }, [state, mergedKeys, declinedKeys]);
+
+  // Track-metadata cache (title/artist/cover) for the pending items.
+  const [songs, setSongs] = useState<Record<string, SubsonicSong>>({});
+  const wantedKey = useMemo(
+    () => Array.from(new Set(pendingItems.map(q => q.trackId))).sort().join('|'),
+    [pendingItems],
+  );
+  useEffect(() => {
+    const wanted = wantedKey ? wantedKey.split('|') : [];
+    const missing = wanted.filter(id => id && !songs[id]);
+    if (missing.length === 0) return;
+    let cancelled = false;
+    void Promise.all(missing.map(id => getSong(id).catch(() => null)))
+      .then(results => {
+        if (cancelled) return;
+        setSongs(prev => {
+          const next = { ...prev };
+          results.forEach((s, i) => { if (s) next[missing[i]] = s; });
+          return next;
+        });
+      });
+    return () => { cancelled = true; };
+  }, [wantedKey]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  if (role !== 'host' || !state || !autoApproveOff || pendingItems.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="host-approval">
+      <div className="host-approval__head">
+        <Inbox size={12} />
+        <span>{t('orbit.approvalTitle')}</span>
+        <span className="host-approval__count">{pendingItems.length}</span>
+      </div>
+      <div className="host-approval__list">
+        {pendingItems.map(q => {
+          const song = songs[q.trackId];
+          const key = suggestionKey(q);
+          return (
+            <div key={key} className="host-approval__item">
+              {song?.coverArt ? (
+                <CachedImage
+                  src={buildCoverArtUrl(song.coverArt, 48)}
+                  cacheKey={coverArtCacheKey(song.coverArt, 48)}
+                  alt=""
+                  className="host-approval__cover"
+                />
+              ) : (
+                <div className="host-approval__cover host-approval__cover--ph" />
+              )}
+              <div className="host-approval__info">
+                <div className="host-approval__title">{song?.title ?? '…'}</div>
+                <div className="host-approval__artist">{song?.artist ?? ''}</div>
+                <div className="host-approval__submitter">
+                  {t('orbit.approvalFrom', { user: q.addedBy })}
+                </div>
+              </div>
+              <div className="host-approval__actions">
+                <button
+                  type="button"
+                  className="host-approval__btn host-approval__btn--approve"
+                  onClick={() => { void approveOrbitSuggestion(q); }}
+                  data-tooltip={t('orbit.approvalAccept')}
+                  aria-label={t('orbit.approvalAccept')}
+                >
+                  <Check size={13} />
+                </button>
+                <button
+                  type="button"
+                  className="host-approval__btn host-approval__btn--decline"
+                  onClick={() => { declineOrbitSuggestion(q); }}
+                  data-tooltip={t('orbit.approvalDecline')}
+                  aria-label={t('orbit.approvalDecline')}
+                >
+                  <X size={13} />
+                </button>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
@@ -157,9 +157,14 @@ export default function LiveSearch() {
                  <div className="search-section-label"><Users size={12} /> {t('search.artists')}</div>
                  {results.artists.map(a => {
                    const i = idx++;
+                    const isCtxActive = ctxIsOpen && ctxType === 'artist' && ctxItemId === a.id;
                    return (
-                      <button key={a.id} className={`search-result-item${activeIndex === i ? ' active' : ''}`}
+                      <button key={a.id} className={`search-result-item${activeIndex === i ? ' active' : ''}${isCtxActive ? ' context-active' : ''}`}
                        onClick={() => { navigate(`/artist/${a.id}`); setOpen(false); setQuery(''); }}
+                        onContextMenu={(e) => {
+                          e.preventDefault();
+                          openContextMenu(e.clientX, e.clientY, a, 'artist');
+                        }}
                        role="option" aria-selected={activeIndex === i}>
                        <div className="search-result-icon"><Users size={14} /></div>
                        <span>{a.name}</span>
@@ -174,9 +179,14 @@ export default function LiveSearch() {
                  <div className="search-section-label"><Disc3 size={12} /> {t('search.albums')}</div>
                  {results.albums.map(a => {
                    const i = idx++;
+                    const isCtxActive = ctxIsOpen && ctxType === 'album' && ctxItemId === a.id;
                    return (
-                      <button key={a.id} className={`search-result-item${activeIndex === i ? ' active' : ''}`}
+                      <button key={a.id} className={`search-result-item${activeIndex === i ? ' active' : ''}${isCtxActive ? ' context-active' : ''}`}
                        onClick={() => { navigate(`/album/${a.id}`); setOpen(false); setQuery(''); }}
+                        onContextMenu={(e) => {
+                          e.preventDefault();
+                          openContextMenu(e.clientX, e.clientY, a, 'album');
+                        }}
                        role="option" aria-selected={activeIndex === i}>
                        {a.coverArt ? (
                          <CachedImage
@@ -0,0 +1,101 @@
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { X, User } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitAccountPickerStore } from '../store/orbitAccountPickerStore';
+
+/**
+ * Modal shown when joining an Orbit session and the user has more than
+ * one account for the target server URL. Lets them pick which account
+ * to switch to before the join flow continues. Mount once in App.tsx —
+ * any caller can invoke it via `useOrbitAccountPickerStore.request(...)`.
+ */
+export default function OrbitAccountPicker() {
+  const { t } = useTranslation();
+  const { isOpen, accounts, pick, cancel } = useOrbitAccountPickerStore();
+  const [selected, setSelected] = useState(0);
+  const itemRefs = useRef<(HTMLButtonElement | null)[]>([]);
+
+  // Reset + focus first item each time the picker re-opens.
+  useEffect(() => {
+    if (!isOpen) return;
+    setSelected(0);
+    // Defer focus to the next tick so the DOM has actually mounted.
+    queueMicrotask(() => itemRefs.current[0]?.focus());
+  }, [isOpen]);
+
+  // Move DOM focus with the arrow-key selection so the browser's focus
+  // ring follows, and the currently active button is readable to AT.
+  useEffect(() => {
+    if (!isOpen) return;
+    itemRefs.current[selected]?.focus();
+  }, [selected, isOpen]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') { cancel(); return; }
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        setSelected(s => (s + 1) % Math.max(1, accounts.length));
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        setSelected(s => (s - 1 + accounts.length) % Math.max(1, accounts.length));
+      } else if (e.key === 'Enter') {
+        e.preventDefault();
+        const target = accounts[selected];
+        if (target) pick(target);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [isOpen, accounts, selected, pick, cancel]);
+
+  if (!isOpen) return null;
+
+  return createPortal(
+    <div
+      className="modal-overlay"
+      onClick={e => { if (e.target === e.currentTarget) cancel(); }}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="orbit-account-picker-title"
+      style={{ alignItems: 'center', paddingTop: 0 }}
+    >
+      <div className="modal-content orbit-account-picker">
+        <button type="button" className="modal-close" onClick={cancel} aria-label={t('orbit.btnCancel')}>
+          <X size={18} />
+        </button>
+        <h3 id="orbit-account-picker-title" className="orbit-account-picker__title">
+          {t('orbit.accountPickerTitle')}
+        </h3>
+        <p className="orbit-account-picker__sub">
+          {t('orbit.accountPickerSub', { url: accounts[0]?.url ?? '' })}
+        </p>
+        <ul className="orbit-account-picker__list" role="listbox">
+          {accounts.map((a, i) => (
+            <li key={a.id} role="option" aria-selected={i === selected}>
+              <button
+                ref={el => { itemRefs.current[i] = el; }}
+                type="button"
+                className={`orbit-account-picker__item${i === selected ? ' is-active' : ''}`}
+                onClick={() => pick(a)}
+                onMouseEnter={() => setSelected(i)}
+              >
+                <User size={14} />
+                <span className="orbit-account-picker__user">{a.username}</span>
+                {a.name && <span className="orbit-account-picker__name">· {a.name}</span>}
+              </button>
+            </li>
+          ))}
+        </ul>
+        <div className="orbit-account-picker__actions">
+          <button type="button" className="btn btn-ghost" onClick={cancel}>
+            {t('orbit.btnCancel')}
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
@@ -0,0 +1,87 @@
+import { useEffect } from 'react';
+import { createPortal } from 'react-dom';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import { leaveOrbitSession } from '../utils/orbit';
+
+/**
+ * Orbit — exit notification modal.
+ *
+ * Shown when:
+ *   - `phase === 'ended'` (host closed the session; guest sees it)
+ *   - `phase === 'error' && errorMessage === 'kicked'`  (host permanently banned us)
+ *   - `phase === 'error' && errorMessage === 'removed'` (host soft-removed us;
+ *     re-join via invite link still works)
+ *
+ * "OK" cleans up the guest-side outbox + resets the local store.
+ */
+export default function OrbitExitModal() {
+  const { t } = useTranslation();
+  const phase        = useOrbitStore(s => s.phase);
+  const errorMessage = useOrbitStore(s => s.errorMessage);
+  const role         = useOrbitStore(s => s.role);
+  const sessionName  = useOrbitStore(s => s.state?.name);
+  const hostName     = useOrbitStore(s => s.state?.host);
+
+  const isEnded       = phase === 'ended';
+  const isKicked      = phase === 'error' && errorMessage === 'kicked';
+  const isRemoved     = phase === 'error' && errorMessage === 'removed';
+  const isHostTimeout = phase === 'error' && errorMessage === 'host-timeout';
+  const isOpen = isEnded || isKicked || isRemoved || isHostTimeout;
+
+  const onOk = async () => {
+    try {
+      if (role === 'guest') await leaveOrbitSession();
+      else useOrbitStore.getState().reset();
+    } catch {
+      useOrbitStore.getState().reset();
+    }
+  };
+
+  // Modal is informational with a single action — Enter / Escape both fire OK.
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Enter' || e.key === 'Escape') { e.preventDefault(); void onOk(); }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  const title = isKicked
+    ? t('orbit.exitKickedTitle')
+    : isRemoved
+      ? t('orbit.exitRemovedTitle')
+      : isHostTimeout
+        ? t('orbit.exitHostTimeoutTitle')
+        : t('orbit.exitEndedTitle');
+  const body = isKicked
+    ? t('orbit.exitKickedBody',  { host: hostName ?? '', name: sessionName ?? '' })
+    : isRemoved
+      ? t('orbit.exitRemovedBody', { host: hostName ?? '', name: sessionName ?? '' })
+      : isHostTimeout
+        ? t('orbit.exitHostTimeoutBody', { host: hostName ?? '', name: sessionName ?? '' })
+        : t('orbit.exitEndedBody',   { name: sessionName ?? '' });
+
+  return createPortal(
+    <div
+      className="modal-overlay orbit-exit-overlay"
+      onClick={e => { if (e.target === e.currentTarget) onOk(); }}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="orbit-exit-title"
+    >
+      <div className="modal-content orbit-exit-modal">
+        <h3 id="orbit-exit-title" className="orbit-exit-modal__title">{title}</h3>
+        <p className="orbit-exit-modal__body">{body}</p>
+        <div className="orbit-exit-modal__actions">
+          <button type="button" className="btn btn-primary" onClick={onOk} autoFocus>{t('orbit.exitOk')}</button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
@@ -0,0 +1,192 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Radio, Clock } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import {
+  getSong,
+  buildCoverArtUrl,
+  coverArtCacheKey,
+  type SubsonicSong,
+} from '../api/subsonic';
+import CachedImage from './CachedImage';
+import OrbitQueueHead from './OrbitQueueHead';
+
+/**
+ * Orbit — guest-side queue view.
+ *
+ * Rendered in place of the normal QueuePanel contents while `role === 'guest'`.
+ * Read-only: shows the host's current track + the host's actual upcoming
+ * play queue (`state.playQueue`, capped at `ORBIT_PLAY_QUEUE_LIMIT`). No
+ * reorder / remove / save — those belong to the host.
+ *
+ * Track metadata is resolved lazily via `getSong` and cached locally so the
+ * list doesn't flicker while the 2.5 s state tick refreshes the snapshot.
+ */
+export default function OrbitGuestQueue() {
+  const { t } = useTranslation();
+  const state        = useOrbitStore(s => s.state);
+  const pending      = useOrbitStore(s => s.pendingSuggestions);
+  const queueItems   = state?.playQueue ?? [];
+  const totalUpcoming = state?.playQueueTotal ?? queueItems.length;
+  const truncatedBy  = Math.max(0, totalUpcoming - queueItems.length);
+  const currentTrack = state?.currentTrack ?? null;
+
+  // Local song cache — keyed by trackId. Survives parent re-renders triggered
+  // by the store tick so list rows don't remount and recomputed URLs don't
+  // kick off duplicate `getSong` calls.
+  const [songs, setSongs] = useState<Record<string, SubsonicSong>>({});
+
+  // Track IDs we need but don't yet have. String-joined so useEffect deps
+  // stay stable across identical queue snapshots (e.g. reshuffle).
+  const wantedKey = useMemo(() => {
+    const ids: string[] = [];
+    if (currentTrack) ids.push(currentTrack.trackId);
+    queueItems.forEach(q => ids.push(q.trackId));
+    pending.forEach(id => ids.push(id));
+    return Array.from(new Set(ids)).sort().join('|');
+  }, [currentTrack, queueItems, pending]);
+
+  useEffect(() => {
+    const wanted = wantedKey ? wantedKey.split('|') : [];
+    const missing = wanted.filter(id => id && !songs[id]);
+    if (missing.length === 0) return;
+
+    let cancelled = false;
+    void Promise.all(missing.map(id => getSong(id).catch(() => null)))
+      .then(results => {
+        if (cancelled) return;
+        setSongs(prev => {
+          const next = { ...prev };
+          results.forEach((s, i) => { if (s) next[missing[i]] = s; });
+          return next;
+        });
+      });
+    return () => { cancelled = true; };
+  }, [wantedKey]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  if (!state) return null;
+
+  const currentSong = currentTrack ? songs[currentTrack.trackId] : null;
+
+  return (
+    <div className="orbit-guest-queue">
+      <OrbitQueueHead state={state} />
+
+      {currentTrack && (
+        <div className="orbit-guest-queue__current">
+          <div className="orbit-guest-queue__live-badge">
+            <Radio size={10} /> {t('orbit.guestLive')}
+          </div>
+          <div className="orbit-guest-queue__current-body">
+            {currentSong?.coverArt ? (
+              <CachedImage
+                src={buildCoverArtUrl(currentSong.coverArt, 96)}
+                cacheKey={coverArtCacheKey(currentSong.coverArt, 96)}
+                alt=""
+                className="orbit-guest-queue__cover orbit-guest-queue__cover--lg"
+              />
+            ) : (
+              <div className="orbit-guest-queue__cover orbit-guest-queue__cover--lg orbit-guest-queue__cover--ph" />
+            )}
+            <div className="orbit-guest-queue__info">
+              <div className="orbit-guest-queue__track-title">
+                {currentSong?.title ?? t('orbit.guestLoading')}
+              </div>
+              <div className="orbit-guest-queue__track-artist">
+                {currentSong?.artist ?? ''}
+              </div>
+              <div className="orbit-guest-queue__note">
+                {state.isPlaying ? t('orbit.guestPlaying') : t('orbit.guestPaused')}
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {pending.length > 0 && (
+        <div className="orbit-guest-queue__pending">
+          <div className="orbit-guest-queue__section-head orbit-guest-queue__section-head--pending">
+            <Clock size={11} />
+            <span>{t('orbit.guestPendingTitle')}</span>
+            <span className="orbit-guest-queue__count">{pending.length}</span>
+          </div>
+          {pending.map(trackId => {
+            const song = songs[trackId];
+            return (
+              <div key={trackId} className="orbit-guest-queue__item orbit-guest-queue__item--pending">
+                {song?.coverArt ? (
+                  <CachedImage
+                    src={buildCoverArtUrl(song.coverArt, 48)}
+                    cacheKey={coverArtCacheKey(song.coverArt, 48)}
+                    alt=""
+                    className="orbit-guest-queue__cover"
+                  />
+                ) : (
+                  <div className="orbit-guest-queue__cover orbit-guest-queue__cover--ph" />
+                )}
+                <div className="orbit-guest-queue__info">
+                  <div className="orbit-guest-queue__track-title">{song?.title ?? '…'}</div>
+                  <div className="orbit-guest-queue__track-artist">{song?.artist ?? ''}</div>
+                  <div className="orbit-guest-queue__pending-hint">{t('orbit.guestPendingHint')}</div>
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      <div className="orbit-guest-queue__section-head">
+        {t('orbit.guestUpNext')} <span className="orbit-guest-queue__count">{totalUpcoming}</span>
+      </div>
+
+      <div className="orbit-guest-queue__list">
+        {queueItems.length === 0 && (
+          <div className="orbit-guest-queue__empty">{t('orbit.guestUpNextEmpty')}</div>
+        )}
+
+        {queueItems.map((q, i) => {
+          const song = songs[q.trackId];
+          const isHostPick = q.addedBy === state.host;
+          return (
+            <div
+              key={`${q.trackId}-${i}`}
+              className="orbit-guest-queue__item"
+            >
+              {song?.coverArt ? (
+                <CachedImage
+                  src={buildCoverArtUrl(song.coverArt, 48)}
+                  cacheKey={coverArtCacheKey(song.coverArt, 48)}
+                  alt=""
+                  className="orbit-guest-queue__cover"
+                />
+              ) : (
+                <div className="orbit-guest-queue__cover orbit-guest-queue__cover--ph" />
+              )}
+              <div className="orbit-guest-queue__info">
+                <div className="orbit-guest-queue__track-title">
+                  {song?.title ?? '…'}
+                </div>
+                <div className="orbit-guest-queue__track-artist">
+                  {song?.artist ?? ''}
+                </div>
+                <div className="orbit-guest-queue__submitter">
+                  {isHostPick
+                    ? t('orbit.queueAddedByHost')
+                    : t('orbit.guestSubmitter', { user: q.addedBy })}
+                </div>
+              </div>
+            </div>
+          );
+        })}
+
+        {truncatedBy > 0 && (
+          <div className="orbit-guest-queue__more">
+            {t('orbit.guestUpNextMore', { count: truncatedBy })}
+          </div>
+        )}
+      </div>
+
+      <div className="orbit-guest-queue__footer">{t('orbit.guestFooter')}</div>
+    </div>
+  );
+}
@@ -0,0 +1,131 @@
+import { useEffect, useRef } from 'react';
+import { createPortal } from 'react-dom';
+import {
+  X, Sparkles, Users, Share2, LogIn, MousePointerClick,
+  ListMusic, Inbox, Sliders, LogOut,
+} from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useHelpModalStore } from '../store/helpModalStore';
+import SettingsSubSection from './SettingsSubSection';
+
+/**
+ * Orbit help modal. Rendered once at the app root; triggered from the
+ * launch popover ("How does this work?") and the in-session bar's help
+ * button. 9 accordion sections built on SettingsSubSection; all default
+ * closed so the modal opens compact. Does not touch playback.
+ */
+export default function OrbitHelpModal() {
+  const { t } = useTranslation();
+  const { isOpen, close } = useHelpModalStore();
+  const bodyRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    // Focus the first accordion summary so arrow keys work immediately.
+    // Uses a short setTimeout because the browser re-focuses the clicked
+    // trigger button after the click handler returns — our focus call has
+    // to happen *after* that, otherwise the browser silently overrides it
+    // and the user only gets keyboard nav after pressing Tab first.
+    const id = window.setTimeout(() => {
+      const first = bodyRef.current?.querySelector<HTMLElement>('summary');
+      first?.focus();
+    }, 60);
+    return () => window.clearTimeout(id);
+  }, [isOpen]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') { close(); return; }
+      if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return;
+      const summaries = Array.from(
+        bodyRef.current?.querySelectorAll<HTMLElement>('summary') ?? [],
+      );
+      if (summaries.length === 0) return;
+      const current = document.activeElement as HTMLElement | null;
+      const idx = summaries.indexOf(current as HTMLElement);
+      e.preventDefault();
+      const next = e.key === 'ArrowDown'
+        ? summaries[(idx + 1 + summaries.length) % summaries.length]
+        : summaries[(idx - 1 + summaries.length) % summaries.length];
+      next?.focus();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [isOpen, close]);
+
+  if (!isOpen) return null;
+
+  const hostOnlyLabel = t('orbit.helpHostOnly');
+
+  return createPortal(
+    <div
+      className="modal-overlay"
+      onClick={e => { if (e.target === e.currentTarget) close(); }}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="orbit-help-title"
+      style={{ alignItems: 'center', paddingTop: 0 }}
+    >
+      <div className="modal-content orbit-help-modal">
+        <button type="button" className="modal-close" onClick={close} aria-label={t('orbit.closeAria')}>
+          <X size={18} />
+        </button>
+
+        <h3 id="orbit-help-title" className="orbit-help-modal__title">
+          {t('orbit.helpTitle')}
+        </h3>
+        <p className="orbit-help-modal__intro">{t('orbit.helpIntro')}</p>
+
+        <div className="orbit-help-modal__body" ref={bodyRef}>
+          <SettingsSubSection title={t('orbit.helpSec1Title')} icon={<Sparkles size={16} />}>
+            <p>{t('orbit.helpSec1Body')}</p>
+          </SettingsSubSection>
+
+          <SettingsSubSection title={t('orbit.helpSec2Title')} icon={<Users size={16} />}>
+            <p>{t('orbit.helpSec2Body')}</p>
+            <div className="orbit-help-modal__warn">
+              <strong>{t('orbit.helpSec2WarnHead')}</strong>
+              <span>{t('orbit.helpSec2WarnBody')}</span>
+            </div>
+          </SettingsSubSection>
+
+          <SettingsSubSection title={t('orbit.helpSec3Title')} icon={<Share2 size={16} />}>
+            <p>{t('orbit.helpSec3Body')}</p>
+          </SettingsSubSection>
+
+          <SettingsSubSection title={t('orbit.helpSec4Title')} icon={<LogIn size={16} />}>
+            <p>{t('orbit.helpSec4Body')}</p>
+          </SettingsSubSection>
+
+          <SettingsSubSection title={t('orbit.helpSec5Title')} icon={<MousePointerClick size={16} />}>
+            <p>{t('orbit.helpSec5Body')}</p>
+          </SettingsSubSection>
+
+          <SettingsSubSection title={t('orbit.helpSec6Title')} icon={<ListMusic size={16} />}>
+            <p>{t('orbit.helpSec6Body')}</p>
+          </SettingsSubSection>
+
+          <SettingsSubSection
+            title={`${t('orbit.helpSec7Title')} ${hostOnlyLabel}`}
+            icon={<Inbox size={16} />}
+          >
+            <p>{t('orbit.helpSec7Body')}</p>
+          </SettingsSubSection>
+
+          <SettingsSubSection
+            title={`${t('orbit.helpSec8Title')} ${hostOnlyLabel}`}
+            icon={<Sliders size={16} />}
+          >
+            <p>{t('orbit.helpSec8Body')}</p>
+          </SettingsSubSection>
+
+          <SettingsSubSection title={t('orbit.helpSec9Title')} icon={<LogOut size={16} />}>
+            <p>{t('orbit.helpSec9Body')}</p>
+          </SettingsSubSection>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
@@ -0,0 +1,158 @@
+import { useState } from 'react';
+import { createPortal } from 'react-dom';
+import { X, LogIn, ClipboardPaste } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useAuthStore } from '../store/authStore';
+import {
+  parseOrbitShareLink,
+  findSessionPlaylistId,
+  readOrbitState,
+  joinOrbitSession,
+} from '../utils/orbit';
+import { switchActiveServer } from '../utils/switchActiveServer';
+import { useOrbitAccountPickerStore } from '../store/orbitAccountPickerStore';
+import { showToast } from '../utils/toast';
+
+interface Props {
+  onClose: () => void;
+}
+
+/**
+ * Orbit — manual join modal. Alternative to the Ctrl+V paste shortcut for
+ * users who don't want to (or can't) paste the invite link into the app
+ * directly. Reuses the same parse + preflight pipeline the clipboard
+ * handler uses, so error surfaces stay consistent.
+ */
+export default function OrbitJoinModal({ onClose }: Props) {
+  const { t } = useTranslation();
+  const [link, setLink] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const onPaste = async () => {
+    try {
+      const clip = await navigator.clipboard.readText();
+      if (clip) setLink(clip);
+    } catch { /* silent — clipboard perms vary */ }
+  };
+
+  const onJoin = async () => {
+    setError(null);
+    const text = link.trim();
+    if (!text) { setError(t('orbit.joinErrEmpty')); return; }
+    const parsed = parseOrbitShareLink(text);
+    if (!parsed) { setError(t('orbit.joinErrInvalid')); return; }
+
+    const active = useAuthStore.getState().getActiveServer();
+    const activeUrl = (active?.url ?? '').replace(/\/+$/, '');
+    const wantUrl   = parsed.serverBase.replace(/\/+$/, '');
+
+    setBusy(true);
+    try {
+      // Auto-switch to the link's server if the user has an account for it.
+      // Multiple candidates → picker modal. switch tears down any lingering
+      // orbit session.
+      if (activeUrl !== wantUrl) {
+        const candidates = useAuthStore.getState().servers
+          .filter(s => s.url.replace(/\/+$/, '') === wantUrl);
+        if (candidates.length === 0) {
+          setError(t('orbit.toastNoAccountForServer', { url: wantUrl }));
+          return;
+        }
+        const target = candidates.length === 1
+          ? candidates[0]
+          : await useOrbitAccountPickerStore.getState().request(candidates);
+        if (!target) { setBusy(false); return; }
+        const switched = await switchActiveServer(target);
+        if (!switched) {
+          setError(t('orbit.toastSwitchFailed', { url: wantUrl }));
+          return;
+        }
+      }
+
+      const playlistId = await findSessionPlaylistId(parsed.sid);
+      if (!playlistId) { setError(t('orbit.joinErrNotFound')); return; }
+      const state = await readOrbitState(playlistId);
+      if (!state)      { setError(t('orbit.joinErrNotFound')); return; }
+      if (state.ended) { setError(t('orbit.joinErrEnded')); return; }
+      await joinOrbitSession(parsed.sid);
+      showToast(t('orbit.toastJoined'), 2200, 'info');
+      onClose();
+    } catch (e) {
+      setError(e instanceof Error ? e.message : t('orbit.toastJoinFail'));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return createPortal(
+    <div
+      className="modal-overlay orbit-start-overlay"
+      onClick={e => { if (e.target === e.currentTarget) onClose(); }}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="orbit-join-title"
+    >
+      <div className="modal-content orbit-start-modal">
+        <button type="button" className="modal-close" onClick={onClose} aria-label={t('orbit.closeAria')}>
+          <X size={18} />
+        </button>
+
+        <div className="orbit-start-modal__hero">
+          <div className="orbit-start-modal__hero-icon">
+            <LogIn size={24} />
+          </div>
+          <h3 id="orbit-join-title" className="orbit-start-modal__title">
+            {t('orbit.joinModalTitle')}
+          </h3>
+          <p className="orbit-start-modal__sub">{t('orbit.joinModalSub')}</p>
+        </div>
+
+        <div className="orbit-start-modal__field">
+          <label className="orbit-start-modal__label" htmlFor="orbit-join-link">
+            {t('orbit.joinModalLinkLabel')}
+          </label>
+          <div className="orbit-start-modal__input-row">
+            <input
+              id="orbit-join-link"
+              type="text"
+              autoFocus
+              value={link}
+              onChange={e => { setLink(e.target.value); setError(null); }}
+              onKeyDown={e => { if (e.key === 'Enter' && !busy) void onJoin(); }}
+              placeholder={t('orbit.joinModalLinkPlaceholder')}
+              className="orbit-start-modal__input"
+            />
+            <button
+              type="button"
+              className="orbit-start-modal__reshuffle"
+              onClick={onPaste}
+              data-tooltip={t('orbit.joinModalPasteTooltip')}
+              aria-label={t('orbit.joinModalPasteTooltip')}
+            >
+              <ClipboardPaste size={15} />
+            </button>
+          </div>
+          <div className="orbit-start-modal__helper">{t('orbit.joinModalLinkHelper')}</div>
+        </div>
+
+        {error && <div className="orbit-start-modal__error">{error}</div>}
+
+        <div className="orbit-start-modal__actions">
+          <button type="button" className="btn btn-surface" onClick={onClose}>
+            {t('orbit.btnCancel')}
+          </button>
+          <button
+            type="button"
+            className="btn btn-primary"
+            onClick={onJoin}
+            disabled={busy || !link.trim()}
+          >
+            {busy ? t('orbit.joinModalBusy') : t('orbit.joinModalSubmit')}
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
@@ -0,0 +1,157 @@
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Crown, User, UserMinus, ShieldOff, Mic, MicOff } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import { kickOrbitParticipant, removeOrbitParticipant, setOrbitSuggestionBlocked } from '../utils/orbit';
+import ConfirmModal from './ConfirmModal';
+
+interface Props {
+  /** Anchor — we position the popover directly below its bottom-right. */
+  anchorRef: React.RefObject<HTMLElement | null>;
+  onClose: () => void;
+}
+
+function joinedFor(fromMs: number, nowMs: number): string {
+  const sec = Math.max(0, Math.round((nowMs - fromMs) / 1000));
+  if (sec < 60) return `${sec}s`;
+  const m = Math.floor(sec / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  return `${h}h${rm.toString().padStart(2, '0')}`;
+}
+
+export default function OrbitParticipantsPopover({ anchorRef, onClose }: Props) {
+  const { t } = useTranslation();
+  const state = useOrbitStore(s => s.state);
+  const role  = useOrbitStore(s => s.role);
+  const popRef = useRef<HTMLDivElement>(null);
+  const [confirm, setConfirm] = useState<{ user: string; mode: 'remove' | 'ban' } | null>(null);
+  const nowMs = Date.now();
+
+  // Close on outside click / Escape — unless a confirm dialog is open
+  // (otherwise outside-clicking the modal would dismiss the popover too,
+  // and re-opening would lose the in-flight confirm context).
+  useEffect(() => {
+    const onDown = (e: MouseEvent) => {
+      if (confirm) return;
+      const t = e.target as Node | null;
+      if (popRef.current?.contains(t)) return;
+      if (anchorRef.current?.contains(t)) return;
+      onClose();
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (confirm) return;
+      if (e.key === 'Escape') onClose();
+    };
+    document.addEventListener('mousedown', onDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [anchorRef, onClose, confirm]);
+
+  if (!state) return null;
+
+  const anchor = anchorRef.current?.getBoundingClientRect();
+  const style: React.CSSProperties = anchor
+    ? {
+        position: 'fixed',
+        top:  anchor.bottom + 12,
+        left: Math.max(8, anchor.left - 100),
+        zIndex: 9999,
+      }
+    : { display: 'none' };
+
+  const onConfirm = async () => {
+    if (!confirm) return;
+    const { user, mode } = confirm;
+    setConfirm(null);
+    if (mode === 'remove') await removeOrbitParticipant(user);
+    else                   await kickOrbitParticipant(user);
+  };
+
+  return createPortal(
+    <>
+    <div ref={popRef} className="orbit-participants-pop" style={style} role="menu">
+      <div className="orbit-participants-pop__head">
+        {t('orbit.participantsCountLabel', { count: state.participants.length + 1 })}
+      </div>
+
+      <div className="orbit-participants-pop__row orbit-participants-pop__row--host">
+        <Crown size={13} />
+        <span className="orbit-participants-pop__name">{state.host}</span>
+        <span className="orbit-participants-pop__meta">{t('orbit.participantsHost')}</span>
+      </div>
+
+      {state.participants.length === 0 && (
+        <div className="orbit-participants-pop__empty">{t('orbit.participantsEmpty')}</div>
+      )}
+
+      {state.participants.map(p => {
+        const isMuted = state.suggestionBlocked?.includes(p.user) ?? false;
+        return (
+          <div key={p.user} className="orbit-participants-pop__row">
+            <User size={13} />
+            <span className="orbit-participants-pop__name">{p.user}</span>
+            <span className="orbit-participants-pop__meta">{joinedFor(p.joinedAt, nowMs)}</span>
+            {role === 'host' && (
+              <div className="orbit-participants-pop__actions">
+                <button
+                  type="button"
+                  className={`orbit-participants-pop__kick${isMuted ? ' is-active' : ''}`}
+                  onClick={() => { void setOrbitSuggestionBlocked(p.user, !isMuted); }}
+                  data-tooltip={isMuted ? t('orbit.participantsUnmuteTooltip') : t('orbit.participantsMuteTooltip')}
+                  aria-label={isMuted
+                    ? t('orbit.participantsUnmuteAria', { user: p.user })
+                    : t('orbit.participantsMuteAria',   { user: p.user })}
+                  aria-pressed={isMuted}
+                >
+                  {isMuted ? <MicOff size={12} /> : <Mic size={12} />}
+                </button>
+                <button
+                  type="button"
+                  className="orbit-participants-pop__kick"
+                  onClick={() => setConfirm({ user: p.user, mode: 'remove' })}
+                  data-tooltip={t('orbit.participantsRemoveTooltip')}
+                  aria-label={t('orbit.participantsRemoveAria', { user: p.user })}
+                >
+                  <UserMinus size={12} />
+                </button>
+                <button
+                  type="button"
+                  className="orbit-participants-pop__kick orbit-participants-pop__kick--ban"
+                  onClick={() => setConfirm({ user: p.user, mode: 'ban' })}
+                  data-tooltip={t('orbit.participantsBanTooltip')}
+                  aria-label={t('orbit.participantsBanAria', { user: p.user })}
+                >
+                  <ShieldOff size={12} />
+                </button>
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+    <ConfirmModal
+      open={!!confirm}
+      title={confirm?.mode === 'ban'
+        ? t('orbit.confirmBanTitle')
+        : t('orbit.confirmRemoveTitle')}
+      message={confirm?.mode === 'ban'
+        ? t('orbit.confirmBanBody',    { user: confirm?.user ?? '' })
+        : t('orbit.confirmRemoveBody', { user: confirm?.user ?? '' })}
+      confirmLabel={confirm?.mode === 'ban'
+        ? t('orbit.confirmBanConfirm')
+        : t('orbit.confirmRemoveConfirm')}
+      cancelLabel={t('orbit.confirmCancel')}
+      danger={confirm?.mode === 'ban'}
+      onConfirm={() => { void onConfirm(); }}
+      onCancel={() => setConfirm(null)}
+    />
+    </>,
+    document.body,
+  );
+}
@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'react';
+import { Users, Wifi, WifiOff } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import type { OrbitState } from '../api/orbit';
+
+interface Props {
+  state: OrbitState;
+}
+
+/** Host's state hasn't updated for this long → guest treats them as offline. */
+const HOST_AWAY_THRESHOLD_MS = 15_000;
+
+/**
+ * Shared Orbit head strip rendered at the top of the queue for both host
+ * and guest. Shows the session name and a comma-separated list of every
+ * participant (host first, then guests in join order).
+ *
+ * Guest view additionally surfaces host-presence: when the host's tick
+ * hasn't been seen for 15 s we render a subtle "host offline" badge so
+ * the guest knows the stalled playback isn't a local problem.
+ */
+export default function OrbitQueueHead({ state }: Props) {
+  const { t } = useTranslation();
+  const role = useOrbitStore(s => s.role);
+  const [nowMs, setNowMs] = useState(() => Date.now());
+
+  // Guest-only clock tick — React wouldn't re-render a stale state blob
+  // on its own, and the presence threshold is time-based.
+  useEffect(() => {
+    if (role !== 'guest') return;
+    const id = window.setInterval(() => setNowMs(Date.now()), 2000);
+    return () => window.clearInterval(id);
+  }, [role]);
+
+  const names = [state.host, ...state.participants.map(p => p.user)];
+  const showPresence = role === 'guest' && state.positionAt > 0;
+  const hostAway = showPresence && (nowMs - state.positionAt) > HOST_AWAY_THRESHOLD_MS;
+
+  return (
+    <div className="orbit-queue-head">
+      <div className="orbit-queue-head__title-row">
+        <h2 className="orbit-queue-head__title">{state.name}</h2>
+        {showPresence && (
+          <span
+            className={`orbit-queue-head__presence orbit-queue-head__presence--${hostAway ? 'away' : 'online'}`}
+            role="status"
+          >
+            {hostAway ? <WifiOff size={11} /> : <Wifi size={11} />}
+            <span>{t(hostAway ? 'orbit.hostAway' : 'orbit.hostOnline')}</span>
+          </span>
+        )}
+      </div>
+      <div className="orbit-queue-head__meta">
+        <Users size={11} />
+        <span className="orbit-queue-head__names">{names.join(', ')}</span>
+      </div>
+    </div>
+  );
+}
@@ -0,0 +1,269 @@
+import { useEffect, useRef, useState } from 'react';
+import { X, RefreshCw, Shuffle, Settings2, Share2, HelpCircle } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import { useHelpModalStore } from '../store/helpModalStore';
+import { usePlayerStore, songToTrack } from '../store/playerStore';
+import { getSong } from '../api/subsonic';
+import {
+  endOrbitSession,
+  leaveOrbitSession,
+  computeOrbitDriftMs,
+  effectiveShuffleIntervalMs,
+} from '../utils/orbit';
+import { estimateLivePosition } from '../api/orbit';
+import OrbitParticipantsPopover from './OrbitParticipantsPopover';
+import OrbitExitModal from './OrbitExitModal';
+import OrbitSettingsPopover from './OrbitSettingsPopover';
+import OrbitSharePopover from './OrbitSharePopover';
+import ConfirmModal from './ConfirmModal';
+
+/**
+ * Orbit — top-strip session indicator.
+ *
+ * Visible whenever the local store reports an active (or just-ended)
+ * session. Shows session name, host, participant count, shuffle countdown,
+ * and role-appropriate action buttons (catch-up for guests, exit for
+ * everyone).
+ *
+ * Deliberately low-chrome: sits above the rest of the app without
+ * reshaping the layout.
+ */
+
+const CATCH_UP_DRIFT_THRESHOLD_MS = 3_000;
+
+function formatCountdown(ms: number): string {
+  const clamped = Math.max(0, Math.round(ms / 1000));
+  const m = Math.floor(clamped / 60);
+  const s = clamped % 60;
+  return `${m}:${s.toString().padStart(2, '0')}`;
+}
+
+export default function OrbitSessionBar() {
+  const { t } = useTranslation();
+  const state              = useOrbitStore(s => s.state);
+  const role               = useOrbitStore(s => s.role);
+  const phase              = useOrbitStore(s => s.phase);
+  const errorMessage       = useOrbitStore(s => s.errorMessage);
+  const [nowMs, setNowMs]  = useState(() => Date.now());
+  const [peopleOpen, setPeopleOpen] = useState(false);
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [shareOpen, setShareOpen] = useState(false);
+  const [confirmLeave, setConfirmLeave] = useState(false);
+  const peopleBtnRef = useRef<HTMLButtonElement>(null);
+  const settingsBtnRef = useRef<HTMLButtonElement>(null);
+  const shareBtnRef = useRef<HTMLButtonElement>(null);
+
+  // Second-level tick just for the shuffle countdown + drift readout —
+  // the store itself only ticks at 2.5 s which is too coarse for a smooth
+  // countdown.
+  useEffect(() => {
+    if (!state || phase !== 'active') return;
+    const id = window.setInterval(() => setNowMs(Date.now()), 1000);
+    return () => window.clearInterval(id);
+  }, [state, phase]);
+
+  // Bar is visible while active, ended (pre-ack), or explicitly kicked / soft-removed.
+  const shouldShowBar = !!state && (
+    phase === 'active'
+    || phase === 'ended'
+    || (phase === 'error' && (errorMessage === 'kicked' || errorMessage === 'removed'))
+  );
+  if (!shouldShowBar || !state) return (
+    <OrbitExitModal />
+  );
+
+  const untilShuffle = Math.max(0, (state.lastShuffle + effectiveShuffleIntervalMs(state)) - nowMs);
+
+  // Guest-only: detect drift from the host's estimated live position.
+  const guestPlayback = usePlayerStore.getState();
+  const localPositionMs = Math.round((guestPlayback.currentTime ?? 0) * 1000);
+  const driftMs = role === 'guest' && state.currentTrack && guestPlayback.currentTrack?.id === state.currentTrack.trackId
+    ? computeOrbitDriftMs(state, localPositionMs, nowMs)
+    : null;
+  const showCatchUp = role === 'guest'
+    && state.isPlaying
+    && state.currentTrack
+    && (driftMs == null || Math.abs(driftMs) > CATCH_UP_DRIFT_THRESHOLD_MS);
+
+  const performExit = async () => {
+    try {
+      if (role === 'host') await endOrbitSession();
+      else if (role === 'guest') await leaveOrbitSession();
+      else useOrbitStore.getState().reset();
+    } catch {
+      useOrbitStore.getState().reset();
+    }
+  };
+
+  const onExit = () => {
+    // Active-session exits get a confirm — guests don't want to drop out on
+    // a fat-finger, and the host's X ends the session for everyone, so
+    // accidentally clicking it is even worse. Post-end/kicked dismissals
+    // skip the confirm (the session is already over there).
+    if (phase === 'active' && (role === 'guest' || role === 'host')) {
+      setConfirmLeave(true);
+      return;
+    }
+    void performExit();
+  };
+
+  const onCatchUp = async () => {
+    if (!state.currentTrack) return;
+    const trackId = state.currentTrack.trackId;
+    const targetMs = estimateLivePosition(state, Date.now());
+    const targetSec = Math.max(0, targetMs / 1000);
+    const hostPlaying = state.isPlaying;
+    try {
+      const song = await getSong(trackId);
+      if (!song) return;
+      const track = songToTrack(song);
+      const player = usePlayerStore.getState();
+      const fraction = targetSec / Math.max(1, track.duration);
+      if (player.currentTrack?.id === trackId) {
+        player.seek(fraction);
+        if (hostPlaying && !player.isPlaying) player.resume();
+        else if (!hostPlaying && player.isPlaying) player.pause();
+      } else {
+        // Different track: play + seek on next tick once engine is ready.
+        player.playTrack(track, [track]);
+        window.setTimeout(() => {
+          const p = usePlayerStore.getState();
+          if (p.currentTrack?.id !== trackId) return;
+          p.seek(fraction);
+          if (!hostPlaying && p.isPlaying) p.pause();
+        }, 400);
+      }
+    } catch {
+      // silent — if the track is gone from the host's library, nothing we can do.
+    }
+  };
+
+  const participantCount = state.participants.length + 1; // +1 for the host
+
+  return (
+    <div className="orbit-bar">
+      <div className="orbit-bar__left">
+        <span className="orbit-bar__dot" aria-hidden="true" />
+        <span className="orbit-bar__name">{state.name}</span>
+        <span className="orbit-bar__sep">·</span>
+        <button
+          ref={peopleBtnRef}
+          type="button"
+          className="orbit-bar__count"
+          onClick={() => setPeopleOpen(v => !v)}
+          data-tooltip={t('orbit.participantsTooltip')}
+          aria-haspopup="menu"
+          aria-expanded={peopleOpen || undefined}
+        >
+          {participantCount}/{state.maxUsers}
+        </button>
+        <span className="orbit-bar__sep">·</span>
+        <span className="orbit-bar__host">{t('orbit.hostLabel', { name: state.host })}</span>
+      </div>
+
+      <div className="orbit-bar__center">
+        <span className="orbit-bar__shuffle">
+          <Shuffle size={13} className="orbit-bar__shuffle-icon" />
+          <span>{t('orbit.shuffleLabel')}</span>
+          <strong className="orbit-bar__shuffle-time">{formatCountdown(untilShuffle)}</strong>
+        </span>
+      </div>
+
+      <div className="orbit-bar__right">
+        {role === 'host' && (
+          <button
+            ref={settingsBtnRef}
+            type="button"
+            className="orbit-bar__settings"
+            onClick={() => setSettingsOpen(v => !v)}
+            data-tooltip={t('orbit.settingsTooltip')}
+            aria-haspopup="menu"
+            aria-expanded={settingsOpen || undefined}
+          >
+            <Settings2 size={14} />
+          </button>
+        )}
+        {role === 'host' && (
+          <button
+            ref={shareBtnRef}
+            type="button"
+            className="orbit-bar__settings"
+            onClick={() => setShareOpen(v => !v)}
+            data-tooltip={t('orbit.shareTooltip')}
+            aria-haspopup="menu"
+            aria-expanded={shareOpen || undefined}
+            aria-label={t('orbit.shareTooltip')}
+          >
+            <Share2 size={14} />
+          </button>
+        )}
+        {showCatchUp && (
+          <button
+            type="button"
+            className="orbit-bar__catchup"
+            onClick={onCatchUp}
+            data-tooltip={t('orbit.catchUpTooltip')}
+          >
+            <RefreshCw size={13} />
+            <span>{t('orbit.catchUpLabel')}</span>
+          </button>
+        )}
+        <button
+          type="button"
+          className="orbit-bar__settings"
+          onClick={() => useHelpModalStore.getState().open()}
+          data-tooltip={t('orbit.helpTooltip')}
+          aria-label={t('orbit.helpTooltip')}
+        >
+          <HelpCircle size={14} />
+        </button>
+        <button
+          type="button"
+          className="orbit-bar__exit"
+          onClick={onExit}
+          data-tooltip={role === 'host' ? t('orbit.endTooltip') : t('orbit.leaveTooltip')}
+          aria-label={role === 'host' ? t('orbit.endTooltip') : t('orbit.leaveTooltip')}
+        >
+          <X size={15} />
+        </button>
+      </div>
+
+      {peopleOpen && (
+        <OrbitParticipantsPopover
+          anchorRef={peopleBtnRef}
+          onClose={() => setPeopleOpen(false)}
+        />
+      )}
+      {settingsOpen && (
+        <OrbitSettingsPopover
+          anchorRef={settingsBtnRef}
+          onClose={() => setSettingsOpen(false)}
+        />
+      )}
+      {shareOpen && (
+        <OrbitSharePopover
+          anchorRef={shareBtnRef}
+          onClose={() => setShareOpen(false)}
+        />
+      )}
+      <OrbitExitModal />
+      <ConfirmModal
+        open={confirmLeave}
+        title={role === 'host'
+          ? t('orbit.confirmEndTitle')
+          : t('orbit.confirmLeaveTitle')}
+        message={role === 'host'
+          ? t('orbit.confirmEndBody', { name: state.name })
+          : t('orbit.confirmLeaveBody', { name: state.name, host: state.host })}
+        confirmLabel={role === 'host'
+          ? t('orbit.confirmEndConfirm')
+          : t('orbit.confirmLeaveConfirm')}
+        cancelLabel={t('orbit.confirmCancel')}
+        danger={role === 'host'}
+        onConfirm={() => { setConfirmLeave(false); void performExit(); }}
+        onCancel={() => setConfirmLeave(false)}
+      />
+    </div>
+  );
+}
@@ -0,0 +1,131 @@
+import { useEffect, useRef } from 'react';
+import { createPortal } from 'react-dom';
+import { Shuffle } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import { updateOrbitSettings, triggerOrbitShuffleNow } from '../utils/orbit';
+import { ORBIT_DEFAULT_SETTINGS, ORBIT_SHUFFLE_INTERVAL_PRESETS_MIN, type OrbitShuffleIntervalMin } from '../api/orbit';
+import { showToast } from '../utils/toast';
+
+interface Props {
+  anchorRef: React.RefObject<HTMLElement | null>;
+  onClose: () => void;
+}
+
+/**
+ * Host-only popover anchored below the settings button in the Orbit bar.
+ * Two toggles; writes are pushed immediately to Navidrome via
+ * `updateOrbitSettings`.
+ */
+export default function OrbitSettingsPopover({ anchorRef, onClose }: Props) {
+  const { t } = useTranslation();
+  const settings = useOrbitStore(s => s.state?.settings) ?? ORBIT_DEFAULT_SETTINGS;
+  const popRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const onDown = (e: MouseEvent) => {
+      const target = e.target as Node | null;
+      if (popRef.current?.contains(target)) return;
+      if (anchorRef.current?.contains(target)) return;
+      onClose();
+    };
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose(); };
+    document.addEventListener('mousedown', onDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [anchorRef, onClose]);
+
+  const anchor = anchorRef.current?.getBoundingClientRect();
+  const style: React.CSSProperties = anchor
+    ? {
+        position: 'fixed',
+        top:   anchor.bottom + 12,
+        right: Math.max(8, window.innerWidth - anchor.right),
+        zIndex: 9999,
+      }
+    : { display: 'none' };
+
+  return createPortal(
+    <div ref={popRef} className="orbit-settings-pop" style={style} role="menu">
+      <div className="orbit-settings-pop__head">{t('orbit.settingsTitle')}</div>
+
+      <label className="orbit-settings-pop__row">
+        <div className="orbit-settings-pop__text">
+          <div className="orbit-settings-pop__label">{t('orbit.settingAutoApprove')}</div>
+          <div className="orbit-settings-pop__hint">{t('orbit.settingAutoApproveHint')}</div>
+        </div>
+        <span className="toggle-switch">
+          <input
+            type="checkbox"
+            checked={settings.autoApprove}
+            onChange={e => { void updateOrbitSettings({ autoApprove: e.target.checked }); }}
+          />
+          <span className="toggle-track" />
+        </span>
+      </label>
+
+      <label className="orbit-settings-pop__row">
+        <div className="orbit-settings-pop__text">
+          <div className="orbit-settings-pop__label">{t('orbit.settingAutoShuffle')}</div>
+          <div className="orbit-settings-pop__hint">{t('orbit.settingAutoShuffleHint')}</div>
+        </div>
+        <span className="toggle-switch">
+          <input
+            type="checkbox"
+            checked={settings.autoShuffle}
+            onChange={e => { void updateOrbitSettings({ autoShuffle: e.target.checked }); }}
+          />
+          <span className="toggle-track" />
+        </span>
+      </label>
+
+      <div className="orbit-settings-pop__row orbit-settings-pop__row--stacked">
+        <div className="orbit-settings-pop__text">
+          <div className="orbit-settings-pop__label">{t('orbit.settingShuffleInterval')}</div>
+          <div className="orbit-settings-pop__hint">{t('orbit.settingShuffleIntervalHint')}</div>
+        </div>
+        <div
+          className="orbit-settings-pop__preset-group"
+          role="radiogroup"
+          aria-label={t('orbit.settingShuffleInterval')}
+        >
+          {ORBIT_SHUFFLE_INTERVAL_PRESETS_MIN.map(min => {
+            const active = (settings.shuffleIntervalMin ?? 15) === min;
+            return (
+              <button
+                key={min}
+                type="button"
+                role="radio"
+                aria-checked={active}
+                className={`orbit-settings-pop__preset${active ? ' is-active' : ''}`}
+                disabled={!settings.autoShuffle}
+                onClick={() => {
+                  void updateOrbitSettings({ shuffleIntervalMin: min as OrbitShuffleIntervalMin });
+                }}
+              >
+                {t('orbit.settingShuffleIntervalValue', { count: min })}
+              </button>
+            );
+          })}
+        </div>
+      </div>
+
+      <button
+        type="button"
+        className="orbit-settings-pop__action"
+        onClick={() => {
+          void triggerOrbitShuffleNow();
+          showToast(t('orbit.toastShuffled'), 2200, 'info');
+          onClose();
+        }}
+      >
+        <Shuffle size={13} />
+        <span>{t('orbit.settingShuffleNow')}</span>
+      </button>
+    </div>,
+    document.body,
+  );
+}
@@ -0,0 +1,84 @@
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Copy, Check } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import { useAuthStore } from '../store/authStore';
+import { buildOrbitShareLink } from '../utils/orbit';
+
+interface Props {
+  anchorRef: React.RefObject<HTMLElement | null>;
+  onClose: () => void;
+}
+
+/**
+ * Host-only popover anchored below the share button in the Orbit bar.
+ * Surfaces the session invite link with a copy affordance. Lives on its
+ * own so the participants popover can stay focused on participants.
+ */
+export default function OrbitSharePopover({ anchorRef, onClose }: Props) {
+  const { t } = useTranslation();
+  const sessionId = useOrbitStore(s => s.sessionId);
+  const popRef = useRef<HTMLDivElement>(null);
+  const [copied, setCopied] = useState(false);
+
+  const shareLink = sessionId
+    ? buildOrbitShareLink(useAuthStore.getState().getActiveServer()?.url ?? '', sessionId)
+    : null;
+
+  useEffect(() => {
+    const onDown = (e: MouseEvent) => {
+      const target = e.target as Node | null;
+      if (popRef.current?.contains(target)) return;
+      if (anchorRef.current?.contains(target)) return;
+      onClose();
+    };
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose(); };
+    document.addEventListener('mousedown', onDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [anchorRef, onClose]);
+
+  const onCopy = async () => {
+    if (!shareLink) return;
+    try {
+      await navigator.clipboard.writeText(shareLink);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1500);
+    } catch { /* silent */ }
+  };
+
+  if (!shareLink) return null;
+
+  const anchor = anchorRef.current?.getBoundingClientRect();
+  const style: React.CSSProperties = anchor
+    ? {
+        position: 'fixed',
+        top:   anchor.bottom + 12,
+        right: Math.max(8, window.innerWidth - anchor.right),
+        zIndex: 9999,
+      }
+    : { display: 'none' };
+
+  return createPortal(
+    <div ref={popRef} className="orbit-share-pop" style={style} role="menu">
+      <div className="orbit-share-pop__label">{t('orbit.participantsInviteLabel')}</div>
+      <div className="orbit-share-pop__row">
+        <code className="orbit-share-pop__link">{shareLink}</code>
+        <button
+          type="button"
+          className="orbit-share-pop__copy"
+          onClick={onCopy}
+          data-tooltip={copied ? t('orbit.tooltipCopied') : t('orbit.tooltipCopy')}
+          aria-label={t('orbit.ariaCopyLink')}
+        >
+          {copied ? <Check size={13} /> : <Copy size={13} />}
+        </button>
+      </div>
+    </div>,
+    document.body,
+  );
+}
@@ -0,0 +1,233 @@
+import { useMemo, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { useTranslation } from 'react-i18next';
+import {
+  X, Check, Copy, Orbit as OrbitIcon,
+  Dices, AlertTriangle, Globe2,
+} from 'lucide-react';
+import {
+  startOrbitSession,
+  buildOrbitShareLink,
+  generateSessionId,
+} from '../utils/orbit';
+import { randomOrbitSessionName } from '../utils/orbitNames';
+import { useAuthStore } from '../store/authStore';
+import { usePlayerStore } from '../store/playerStore';
+import { isLanUrl } from '../hooks/useConnectionStatus';
+import { ORBIT_DEFAULT_MAX_USERS } from '../api/orbit';
+
+interface Props { onClose: () => void; }
+
+/**
+ * Orbit — start-session modal.
+ *
+ * One-screen flow: a share-link is shown immediately (built from a
+ * pre-generated session id + a slug derived from the live name). The host
+ * can copy it any time; pressing "Start" creates the session under that
+ * same id and auto-copies the link if it hasn't been copied yet.
+ */
+export default function OrbitStartModal({ onClose }: Props) {
+  const { t } = useTranslation();
+  const [sid]                     = useState(() => generateSessionId());
+  const [name, setName]           = useState(() => randomOrbitSessionName());
+  const [maxUsers, setMaxUsers]   = useState(ORBIT_DEFAULT_MAX_USERS);
+  const [busy, setBusy]           = useState(false);
+  const [error, setError]         = useState<string | null>(null);
+  const [copied, setCopied]       = useState(false);
+  const [hasCopied, setHasCopied] = useState(false);
+  const [clearQueue, setClearQueue] = useState(false);
+
+  const server     = useAuthStore.getState().getActiveServer();
+  const serverBase = server?.url ?? '';
+  const serverName = server?.name ?? server?.url ?? t('orbit.fallbackServer');
+  const onLan      = isLanUrl(serverBase);
+
+  const shareLink = useMemo(
+    () => buildOrbitShareLink(serverBase, sid),
+    [serverBase, sid],
+  );
+
+  const writeLinkToClipboard = async (): Promise<boolean> => {
+    try {
+      await navigator.clipboard.writeText(shareLink);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const onCopy = async () => {
+    const ok = await writeLinkToClipboard();
+    if (ok) {
+      setCopied(true);
+      setHasCopied(true);
+      window.setTimeout(() => setCopied(false), 1500);
+    }
+  };
+
+  const onStart = async () => {
+    setError(null);
+    const trimmed = name.trim();
+    if (!trimmed) { setError(t('orbit.errNameRequired')); return; }
+
+    if (!hasCopied) {
+      const ok = await writeLinkToClipboard();
+      if (ok) setHasCopied(true);
+    }
+
+    setBusy(true);
+    try {
+      if (clearQueue) usePlayerStore.getState().clearQueue();
+      await startOrbitSession({ name: trimmed, maxUsers, sid });
+      onClose();
+    } catch (e) {
+      setError(e instanceof Error ? e.message : t('orbit.errStartFailed'));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const heroSubParts = t('orbit.heroSub', { server: serverName }).split(String(serverName));
+
+  return createPortal(
+    <div
+      className="modal-overlay orbit-start-overlay"
+      onClick={e => { if (e.target === e.currentTarget) onClose(); }}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="orbit-start-title"
+    >
+      <div className="modal-content orbit-start-modal">
+        <button type="button" className="modal-close" onClick={onClose} aria-label={t('orbit.closeAria')}>
+          <X size={18} />
+        </button>
+
+        <div className="orbit-start-modal__hero">
+          <div className="orbit-start-modal__hero-icon">
+            <OrbitIcon size={24} />
+          </div>
+          <h3 id="orbit-start-title" className="orbit-start-modal__title">
+            {t('orbit.heroTitlePrefix')}{' '}
+            <span className="orbit-start-modal__brand">{t('orbit.heroTitleBrand')}</span>
+          </h3>
+          <p className="orbit-start-modal__sub">
+            {heroSubParts[0]}
+            <strong>{serverName}</strong>
+            {heroSubParts[1] ?? ''}
+          </p>
+        </div>
+
+        <div
+          className={`orbit-start-modal__tip${onLan ? ' orbit-start-modal__tip--warn' : ''}`}
+          role={onLan ? 'alert' : undefined}
+        >
+          {onLan ? <AlertTriangle size={15} /> : <Globe2 size={15} />}
+          <span>{onLan ? t('orbit.tipLan') : t('orbit.tipRemote')}</span>
+        </div>
+
+        <div className="orbit-start-modal__field">
+          <label className="orbit-start-modal__label" htmlFor="orbit-name">
+            {t('orbit.labelName')}
+          </label>
+          <div className="orbit-start-modal__input-row">
+            <input
+              id="orbit-name"
+              type="text"
+              autoFocus
+              value={name}
+              onChange={e => { setName(e.target.value); setHasCopied(false); }}
+              onKeyDown={e => {
+                if (e.key !== 'Enter') return;
+                if (busy || !name.trim()) return;
+                e.preventDefault();
+                void onStart();
+              }}
+              placeholder={t('orbit.namePlaceholder')}
+              maxLength={40}
+              className="orbit-start-modal__input"
+            />
+            <button
+              type="button"
+              className="orbit-start-modal__reshuffle"
+              onClick={() => { setName(randomOrbitSessionName()); setHasCopied(false); }}
+              data-tooltip={t('orbit.reshuffleTooltip')}
+              aria-label={t('orbit.reshuffleAria')}
+            >
+              <Dices size={15} />
+            </button>
+          </div>
+          <div className="orbit-start-modal__helper">{t('orbit.helperName')}</div>
+        </div>
+
+        <div className="orbit-start-modal__field">
+          <label className="orbit-start-modal__label" htmlFor="orbit-max">
+            {t('orbit.labelMax')}: <strong>{maxUsers}</strong>
+          </label>
+          <input
+            id="orbit-max"
+            type="range"
+            min={1}
+            max={32}
+            value={maxUsers}
+            onChange={e => setMaxUsers(Number(e.target.value))}
+            className="orbit-start-modal__range"
+          />
+          <div className="orbit-start-modal__helper">{t('orbit.helperMax')}</div>
+        </div>
+
+        <div className="orbit-start-modal__field">
+          <label className="orbit-start-modal__toggle-row">
+            <div className="orbit-start-modal__toggle-text">
+              <div className="orbit-start-modal__label">{t('orbit.labelClearQueue')}</div>
+              <div className="orbit-start-modal__helper">{t('orbit.helperClearQueue')}</div>
+            </div>
+            <span className="toggle-switch">
+              <input
+                type="checkbox"
+                checked={clearQueue}
+                onChange={e => setClearQueue(e.target.checked)}
+              />
+              <span className="toggle-track" />
+            </span>
+          </label>
+        </div>
+
+        <div className="orbit-start-modal__field">
+          <label className="orbit-start-modal__label">{t('orbit.labelLink')}</label>
+          <div className="orbit-start-modal__link">
+            <code>{shareLink}</code>
+            <button
+              type="button"
+              className="orbit-start-modal__copy"
+              onClick={onCopy}
+              data-tooltip={copied ? t('orbit.tooltipCopied') : t('orbit.tooltipCopy')}
+              aria-label={t('orbit.ariaCopyLink')}
+            >
+              {copied ? <Check size={14} /> : <Copy size={14} />}
+            </button>
+          </div>
+          <div className="orbit-start-modal__helper">{t('orbit.helperLink')}</div>
+        </div>
+
+        {error && <div className="orbit-start-modal__error">{error}</div>}
+
+        <div className="orbit-start-modal__actions">
+          <button type="button" className="btn btn-surface" onClick={onClose}>
+            {t('orbit.btnCancel')}
+          </button>
+          <button
+            type="button"
+            className="btn btn-primary"
+            onClick={onStart}
+            disabled={busy || !name.trim()}
+          >
+            {busy
+              ? t('orbit.btnStarting')
+              : hasCopied ? t('orbit.btnStart') : t('orbit.btnCopyAndStart')}
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
@@ -0,0 +1,110 @@
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Orbit as OrbitIcon, Plus, LogIn, HelpCircle } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useOrbitStore } from '../store/orbitStore';
+import { useAuthStore } from '../store/authStore';
+import { useHelpModalStore } from '../store/helpModalStore';
+import OrbitStartModal from './OrbitStartModal';
+import OrbitJoinModal from './OrbitJoinModal';
+import OrbitWordmark from './OrbitWordmark';
+
+/**
+ * Topbar trigger — opens a small launch popover offering three choices:
+ * create a new session, join an existing one via invite link, or open the
+ * Orbit help section. Hidden while a session is already active so we
+ * don't offer entry points while the user's session bar is already live.
+ */
+export default function OrbitStartTrigger() {
+  const { t } = useTranslation();
+  const role = useOrbitStore(s => s.role);
+  const visible = useAuthStore(s => s.showOrbitTrigger);
+
+  const [popoverOpen, setPopoverOpen] = useState(false);
+  const [startOpen, setStartOpen] = useState(false);
+  const [joinOpen, setJoinOpen]   = useState(false);
+  const btnRef = useRef<HTMLButtonElement>(null);
+  const popRef = useRef<HTMLDivElement>(null);
+
+  // Close popover on outside click / Escape.
+  useEffect(() => {
+    if (!popoverOpen) return;
+    const onDown = (e: MouseEvent) => {
+      const target = e.target as Node | null;
+      if (popRef.current?.contains(target)) return;
+      if (btnRef.current?.contains(target)) return;
+      setPopoverOpen(false);
+    };
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') setPopoverOpen(false); };
+    document.addEventListener('mousedown', onDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [popoverOpen]);
+
+  if (role !== null) return null;
+  if (!visible) return null;
+
+  const anchor = btnRef.current?.getBoundingClientRect();
+  const popoverStyle: React.CSSProperties = anchor
+    ? {
+        position: 'fixed',
+        top:  anchor.bottom + 8,
+        left: anchor.left,
+        zIndex: 9999,
+      }
+    : { display: 'none' };
+
+  const pickCreate = () => { setPopoverOpen(false); setStartOpen(true); };
+  const pickJoin   = () => { setPopoverOpen(false); setJoinOpen(true); };
+  const pickHelp   = () => { setPopoverOpen(false); useHelpModalStore.getState().open(); };
+
+  return (
+    <>
+      <button
+        ref={btnRef}
+        type="button"
+        className="btn btn-surface orbit-start-trigger"
+        onClick={() => setPopoverOpen(v => !v)}
+        data-tooltip={t('orbit.triggerTooltip')}
+        data-tooltip-pos="bottom"
+        aria-haspopup="menu"
+        aria-expanded={popoverOpen || undefined}
+        aria-label={t('orbit.triggerLabel')}
+        style={{ position: 'relative', display: 'flex', alignItems: 'center', gap: '0.5rem', padding: '0.5rem 1rem' }}
+      >
+        <OrbitIcon size={18} className="orbit-start-trigger__spin" />
+        <span style={{ display: 'inline-flex', alignItems: 'center', height: '1.5em' }}>
+          <OrbitWordmark height={14} />
+        </span>
+      </button>
+
+      {popoverOpen && createPortal(
+        <div ref={popRef} className="orbit-launch-pop" style={popoverStyle} role="menu">
+          <button type="button" className="orbit-launch-pop__item" onClick={pickCreate}>
+            <Plus size={14} />
+            <span>{t('orbit.launchCreate')}</span>
+          </button>
+          <button type="button" className="orbit-launch-pop__item" onClick={pickJoin}>
+            <LogIn size={14} />
+            <span>{t('orbit.launchJoin')}</span>
+          </button>
+          <button
+            type="button"
+            className="orbit-launch-pop__item"
+            onClick={pickHelp}
+          >
+            <HelpCircle size={14} />
+            <span>{t('orbit.launchHelp')}</span>
+          </button>
+        </div>,
+        document.body,
+      )}
+
+      {startOpen && <OrbitStartModal onClose={() => setStartOpen(false)} />}
+      {joinOpen && <OrbitJoinModal onClose={() => setJoinOpen(false)} />}
+    </>
+  );
+}
@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
 import { useAuthStore } from '../store/authStore';
@@ -6,6 +6,25 @@ import { decodeSharePayloadFromText } from '../utils/shareLink';
 import { decodeServerMagicStringFromText } from '../utils/serverMagicString';
 import { applySharePastePayload } from '../utils/applySharePaste';
 import { showToast } from '../utils/toast';
+import {
+  parseOrbitShareLink,
+  joinOrbitSession,
+  findSessionPlaylistId,
+  readOrbitState,
+  OrbitJoinError,
+} from '../utils/orbit';
+import { switchActiveServer } from '../utils/switchActiveServer';
+import { useOrbitAccountPickerStore } from '../store/orbitAccountPickerStore';
+import ConfirmModal from './ConfirmModal';
+
+const ORBIT_JOIN_ERROR_KEYS: Record<string, string> = {
+  'not-found':    'orbit.joinErrNotFound',
+  'ended':        'orbit.joinErrEnded',
+  'full':         'orbit.joinErrFull',
+  'kicked':       'orbit.joinErrKicked',
+  'no-user':      'orbit.joinErrNoUser',
+  'server-error': 'orbit.joinErrServerError',
+};

 /**
 * Global paste: library share links (`psysonic2-`) and server invites (`psysonic1-`)
@@ -16,6 +35,33 @@ export default function PasteClipboardHandler() {
  const { t } = useTranslation();
  const isLoggedIn = useAuthStore(s => s.isLoggedIn);
  const busy = useRef(false);
+  const [orbitConfirm, setOrbitConfirm] = useState<{ sid: string; host: string; name: string } | null>(null);
+  const [orbitInvalid, setOrbitInvalid] = useState(false);
+
+  // `not-found` and `ended` collapse into a single "link no longer valid"
+  // dialog — from the guest's POV both mean the same thing: the invite
+  // doesn't lead anywhere any more. Other reasons stay as toasts because
+  // they're actionable (full → wait, kicked → talk to host, etc.).
+  const handleJoinError = (reason: string | null, fallback?: string) => {
+    if (reason === 'not-found' || reason === 'ended') {
+      setOrbitInvalid(true);
+      return;
+    }
+    const i18nKey = reason ? ORBIT_JOIN_ERROR_KEYS[reason] : null;
+    showToast(i18nKey ? t(i18nKey) : (fallback ?? t('orbit.toastJoinFail')), 4000, 'error');
+  };
+
+  const runOrbitJoin = (sid: string) => {
+    if (busy.current) return;
+    busy.current = true;
+    joinOrbitSession(sid)
+      .then(() => showToast(t('orbit.toastJoined'), 2500, 'info'))
+      .catch(err => {
+        if (err instanceof OrbitJoinError) handleJoinError(err.reason, err.message);
+        else                               handleJoinError(null);
+      })
+      .finally(() => { busy.current = false; });
+  };

  useEffect(() => {
    const onPaste = (e: ClipboardEvent) => {
@@ -30,6 +76,59 @@ export default function PasteClipboardHandler() {
        return;
      }
      const text = e.clipboardData?.getData('text/plain') ?? '';
+
+      // Orbit share link — handled before library shares.
+      const orbit = parseOrbitShareLink(text.trim());
+      if (orbit) {
+        e.preventDefault();
+        e.stopPropagation();
+        if (!isLoggedIn) { showToast(t('orbit.toastLoginFirst'), 4000, 'info'); return; }
+        if (busy.current) return;
+        busy.current = true;
+
+        (async () => {
+          const active = useAuthStore.getState().getActiveServer();
+          const activeUrl = (active?.url ?? '').replace(/\/+$/, '');
+          const wantUrl   = orbit.serverBase.replace(/\/+$/, '');
+
+          // Auto-switch to the link's target server if the user has an
+          // account registered for it. No account → clear error. Multiple
+          // accounts for the same URL → picker lets the user choose. The
+          // switch itself tears down any lingering orbit session (see
+          // switchActiveServer) so the join below starts clean.
+          if (activeUrl !== wantUrl) {
+            const candidates = useAuthStore.getState().servers
+              .filter(s => s.url.replace(/\/+$/, '') === wantUrl);
+            if (candidates.length === 0) {
+              showToast(t('orbit.toastNoAccountForServer', { url: wantUrl }), 5000, 'warning');
+              return;
+            }
+            const target = candidates.length === 1
+              ? candidates[0]
+              : await useOrbitAccountPickerStore.getState().request(candidates);
+            if (!target) return; // cancelled
+            const switched = await switchActiveServer(target);
+            if (!switched) {
+              showToast(t('orbit.toastSwitchFailed', { url: wantUrl }), 5000, 'error');
+              return;
+            }
+          }
+
+          // Preview the session state so the confirm dialog can show the
+          // host and session name. Failures surface the same error toasts
+          // the join would, without ever showing the confirm.
+          const playlistId = await findSessionPlaylistId(orbit.sid);
+          if (!playlistId) { handleJoinError('not-found'); return; }
+          const state = await readOrbitState(playlistId);
+          if (!state)      { handleJoinError('not-found'); return; }
+          if (state.ended) { handleJoinError('ended');     return; }
+          setOrbitConfirm({ sid: orbit.sid, host: state.host, name: state.name });
+        })()
+          .catch(() => handleJoinError(null))
+          .finally(() => { busy.current = false; });
+        return;
+      }
+
      const share = decodeSharePayloadFromText(text);
      if (share) {
        if (!isLoggedIn) {
@@ -74,5 +173,31 @@ export default function PasteClipboardHandler() {
    return () => document.removeEventListener('paste', onPaste, true);
  }, [navigate, t, isLoggedIn]);

-  return null;
+  return (
+    <>
+      <ConfirmModal
+        open={!!orbitConfirm}
+        title={t('orbit.confirmJoinTitle')}
+        message={t('orbit.confirmJoinBody', {
+          host: orbitConfirm?.host ?? '',
+          name: orbitConfirm?.name ?? '',
+        })}
+        confirmLabel={t('orbit.confirmJoinConfirm')}
+        cancelLabel={t('orbit.confirmCancel')}
+        onConfirm={() => {
+          const sid = orbitConfirm?.sid;
+          setOrbitConfirm(null);
+          if (sid) runOrbitJoin(sid);
+        }}
+        onCancel={() => setOrbitConfirm(null)}
+      />
+      <ConfirmModal
+        open={orbitInvalid}
+        title={t('orbit.invalidLinkTitle')}
+        message={t('orbit.invalidLinkBody')}
+        confirmLabel={t('orbit.exitOk')}
+        onConfirm={() => setOrbitInvalid(false)}
+      />
+    </>
+  );
 }
@@ -1,5 +1,9 @@
 import React, { useState, useRef, useMemo, useEffect } from 'react';
 import { Track, usePlayerStore, songToTrack } from '../store/playerStore';
+import { useOrbitStore } from '../store/orbitStore';
+import OrbitGuestQueue from './OrbitGuestQueue';
+import OrbitQueueHead from './OrbitQueueHead';
+import HostApprovalQueue from './HostApprovalQueue';
 import { Play, Music, Star, X, Trash2, Save, FolderOpen, Shuffle, Infinity, Waves, MicVocal, ListMusic, Check, ListPlus, MoveRight, Radio, HardDrive, ChevronDown, Info, Share2 } from 'lucide-react';
 import { buildCoverArtUrl, coverArtCacheKey, getAlbum, getPlaylists, getPlaylist, updatePlaylist, deletePlaylist, SubsonicPlaylist } from '../api/subsonic';
 import { usePlaylistStore } from '../store/playlistStore';
@@ -231,8 +235,44 @@ function QueueHeader({ queue, queueIndex, showRemainingTime, setShowRemainingTim
 }

 export default function QueuePanel() {
+  const orbitRole = useOrbitStore(s => s.role);
+  if (orbitRole === 'guest') {
+    return (
+      <aside className="queue-panel queue-panel--orbit-guest">
+        <OrbitGuestQueue />
+      </aside>
+    );
+  }
+  return <QueuePanelHostOrSolo />;
+}
+
+function QueuePanelHostOrSolo() {
  const { t } = useTranslation();
  const navigate = useNavigate();
+  const orbitRole = useOrbitStore(s => s.role);
+  const orbitState = useOrbitStore(s => s.state);
+  /** trackId → addedBy (host username or guest username) — only populated while
+   *  hosting an Orbit session, so the queue rows can surface attribution. */
+  const orbitAddedByByTrack = useMemo(() => {
+    const map = new Map<string, string>();
+    if (orbitRole !== 'host' || !orbitState) return map;
+    if (orbitState.currentTrack) {
+      map.set(orbitState.currentTrack.trackId, orbitState.currentTrack.addedBy);
+    }
+    for (const q of orbitState.queue) map.set(q.trackId, q.addedBy);
+    return map;
+  }, [orbitRole, orbitState]);
+  const orbitHostUsername = orbitState?.host ?? '';
+  /** Attribution label for a queue row / current track while hosting. Null when
+   *  not in a hosted session. Bulk-adds (album / playlist enqueue) bypass
+   *  `hostEnqueueToOrbit` and therefore never land in `state.queue`, so we
+   *  default those to "Added by you" rather than showing nothing. */
+  const orbitAttributionLabel = (trackId: string): string | null => {
+    if (orbitRole !== 'host' || !orbitState) return null;
+    const addedBy = orbitAddedByByTrack.get(trackId);
+    if (!addedBy || addedBy === orbitHostUsername) return t('orbit.queueAddedByYou');
+    return t('orbit.queueAddedByUser', { user: addedBy });
+  };
  const queue = usePlayerStore(s => s.queue);
  const queueIndex = usePlayerStore(s => s.queueIndex);
  const currentTrack = usePlayerStore(s => s.currentTrack);
@@ -456,6 +496,12 @@ export default function QueuePanel() {
        borderLeftWidth: isQueueVisible ? 1 : 0,
      }}
    >
+      {orbitRole === 'host' && orbitState && (
+        <>
+          <OrbitQueueHead state={orbitState} />
+          <HostApprovalQueue />
+        </>
+      )}
      <QueueHeader
        queue={queue}
        queueIndex={queueIndex}
@@ -582,6 +628,10 @@ export default function QueuePanel() {
              {currentTrack.year && (
                <div className="queue-current-sub">{currentTrack.year}</div>
              )}
+              {(() => {
+                const label = orbitAttributionLabel(currentTrack.id);
+                return label ? <div className="queue-current-sub queue-current-attribution">{label}</div> : null;
+              })()}
              {renderStars(userRatingOverrides[currentTrack.id] ?? currentTrack.userRating)}
            </div>
          </div>
@@ -759,6 +809,10 @@ export default function QueuePanel() {
                    <span className="truncate">{track.title}</span>
                  </div>
                  <div className="queue-item-artist truncate">{track.artist}</div>
+                  {(() => {
+                    const label = orbitAttributionLabel(track.id);
+                    return label ? <div className="queue-item-attribution truncate">{label}</div> : null;
+                  })()}
                </div>
                <div className="queue-item-duration">
                  {formatTime(track.duration)}
@@ -0,0 +1,126 @@
+import React, { memo } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { Play, ListPlus } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { SubsonicSong, buildCoverArtUrl, coverArtCacheKey } from '../api/subsonic';
+import { usePlayerStore, songToTrack } from '../store/playerStore';
+import CachedImage from './CachedImage';
+import { enqueueAndPlay } from '../utils/playSong';
+import { useDragDrop } from '../contexts/DragDropContext';
+import { useOrbitSongRowBehavior } from '../hooks/useOrbitSongRowBehavior';
+
+interface SongCardProps {
+  song: SubsonicSong;
+}
+
+function SongCard({ song }: SongCardProps) {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const openContextMenu = usePlayerStore(s => s.openContextMenu);
+  const enqueue = usePlayerStore(s => s.enqueue);
+  const coverUrl = song.coverArt ? buildCoverArtUrl(song.coverArt, 200) : '';
+  const psyDrag = useDragDrop();
+  const { orbitActive, addTrackToOrbit } = useOrbitSongRowBehavior();
+
+  const handlePlay = () => {
+    if (orbitActive) { addTrackToOrbit(song.id); return; }
+    enqueueAndPlay(song);
+  };
+
+  const handleEnqueue = () => {
+    if (orbitActive) { addTrackToOrbit(song.id); return; }
+    enqueue([songToTrack(song)]);
+  };
+
+  const handleClick = handlePlay;
+
+  const handleArtistClick = (e: React.MouseEvent) => {
+    if (!song.artistId) return;
+    e.stopPropagation();
+    navigate(`/artist/${song.artistId}`);
+  };
+
+  return (
+    <div
+      className="song-card card"
+      onClick={handleClick}
+      role="button"
+      tabIndex={0}
+      aria-label={`${song.title} – ${song.artist}`}
+      onKeyDown={e => e.key === 'Enter' && handleClick()}
+      onContextMenu={(e) => {
+        e.preventDefault();
+        openContextMenu(e.clientX, e.clientY, song, 'song');
+      }}
+      onMouseDown={e => {
+        if (e.button !== 0) return;
+        const sx = e.clientX, sy = e.clientY;
+        const onMove = (me: MouseEvent) => {
+          if (Math.abs(me.clientX - sx) > 5 || Math.abs(me.clientY - sy) > 5) {
+            document.removeEventListener('mousemove', onMove);
+            document.removeEventListener('mouseup', onUp);
+            psyDrag.startDrag(
+              { data: JSON.stringify({ type: 'song', id: song.id, name: song.title }), label: song.title, coverUrl: coverUrl || undefined },
+              me.clientX, me.clientY,
+            );
+          }
+        };
+        const onUp = () => {
+          document.removeEventListener('mousemove', onMove);
+          document.removeEventListener('mouseup', onUp);
+        };
+        document.addEventListener('mousemove', onMove);
+        document.addEventListener('mouseup', onUp);
+      }}
+    >
+      <div className="song-card-cover">
+        {coverUrl ? (
+          <CachedImage
+            src={coverUrl}
+            cacheKey={coverArtCacheKey(song.coverArt!, 200)}
+            alt={`${song.album} Cover`}
+            loading="lazy"
+          />
+        ) : (
+          <div className="song-card-cover-placeholder">
+            <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+              <circle cx="12" cy="12" r="10" />
+              <circle cx="12" cy="12" r="3" />
+            </svg>
+          </div>
+        )}
+        <div className="song-card-play-overlay">
+          <button
+            className="song-card-action-btn"
+            onClick={e => { e.stopPropagation(); handlePlay(); }}
+            aria-label={t('tracks.playSong')}
+            data-tooltip={t('tracks.playSong')}
+            data-tooltip-pos="top"
+          >
+            <Play size={14} fill="currentColor" />
+          </button>
+          <button
+            className="song-card-action-btn"
+            onClick={e => { e.stopPropagation(); handleEnqueue(); }}
+            aria-label={t('tracks.enqueueSong')}
+            data-tooltip={t('tracks.enqueueSong')}
+            data-tooltip-pos="top"
+          >
+            <ListPlus size={14} />
+          </button>
+        </div>
+      </div>
+      <div className="song-card-info">
+        <p className="song-card-title truncate" title={song.title}>{song.title}</p>
+        <p
+          className={`song-card-artist truncate${song.artistId ? ' track-artist-link' : ''}`}
+          style={{ cursor: song.artistId ? 'pointer' : 'default' }}
+          onClick={handleArtistClick}
+          title={song.artist}
+        >{song.artist}</p>
+      </div>
+    </div>
+  );
+}
+
+export default memo(SongCard);
@@ -0,0 +1,91 @@
+import React, { useRef, useState, useEffect } from 'react';
+import { ChevronLeft, ChevronRight, RefreshCw } from 'lucide-react';
+import { SubsonicSong } from '../api/subsonic';
+import SongCard from './SongCard';
+
+interface Props {
+  title: string;
+  songs: SubsonicSong[];
+  /** Called when user clicks the reroll button (visible only if provided). */
+  onReroll?: () => void | Promise<void>;
+  /** Loading state — disables reroll, optional shimmer */
+  loading?: boolean;
+  /** Empty-state copy when songs is empty AND not loading. */
+  emptyText?: string;
+}
+
+export default function SongRail({ title, songs, onReroll, loading, emptyText }: Props) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [showLeft, setShowLeft] = useState(false);
+  const [showRight, setShowRight] = useState(true);
+
+  const handleScroll = () => {
+    if (!scrollRef.current) return;
+    const { scrollLeft, scrollWidth, clientWidth } = scrollRef.current;
+    setShowLeft(scrollLeft > 0);
+    setShowRight(scrollLeft < scrollWidth - clientWidth - 5);
+  };
+
+  useEffect(() => {
+    handleScroll();
+    window.addEventListener('resize', handleScroll);
+    return () => window.removeEventListener('resize', handleScroll);
+  }, [songs]);
+
+  const scroll = (dir: 'left' | 'right') => {
+    if (!scrollRef.current) return;
+    const amount = scrollRef.current.clientWidth * 0.75;
+    scrollRef.current.scrollBy({ left: dir === 'left' ? -amount : amount, behavior: 'smooth' });
+  };
+
+  // Hide rail entirely if empty and no empty-state copy
+  if (songs.length === 0 && !loading && !emptyText) return null;
+
+  return (
+    <section className="song-row-section">
+      <div className="song-row-header">
+        <h2 className="section-title" style={{ marginBottom: 0 }}>{title}</h2>
+        <div className="song-row-nav">
+          {onReroll && (
+            <button
+              className="nav-btn song-row-reroll"
+              onClick={() => onReroll()}
+              disabled={loading}
+              aria-label="Reroll"
+              data-tooltip="Reroll"
+              data-tooltip-pos="top"
+            >
+              <RefreshCw size={16} className={loading ? 'is-spinning' : ''} />
+            </button>
+          )}
+          <button
+            className={`nav-btn ${!showLeft ? 'disabled' : ''}`}
+            onClick={() => scroll('left')}
+            disabled={!showLeft}
+          >
+            <ChevronLeft size={20} />
+          </button>
+          <button
+            className={`nav-btn ${!showRight ? 'disabled' : ''}`}
+            onClick={() => scroll('right')}
+            disabled={!showRight}
+          >
+            <ChevronRight size={20} />
+          </button>
+        </div>
+      </div>
+
+      <div className="song-grid-wrapper">
+        {songs.length === 0 && emptyText ? (
+          <p className="song-row-empty">{emptyText}</p>
+        ) : (
+          <div className="song-grid" ref={scrollRef} onScroll={handleScroll}>
+            {songs.map(s => (
+              <SongCard key={s.id} song={s} />
+            ))}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}
@@ -0,0 +1,130 @@
+import React, { memo } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { Play, ListPlus } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import type { SubsonicSong } from '../api/subsonic';
+import { usePlayerStore, songToTrack } from '../store/playerStore';
+import { enqueueAndPlay } from '../utils/playSong';
+import { useDragDrop } from '../contexts/DragDropContext';
+import { useOrbitSongRowBehavior } from '../hooks/useOrbitSongRowBehavior';
+
+function fmtDuration(s: number): string {
+  if (!s || !isFinite(s)) return '–';
+  const m = Math.floor(s / 60);
+  const sec = Math.floor(s % 60);
+  return `${m}:${sec.toString().padStart(2, '0')}`;
+}
+
+interface Props {
+  song: SubsonicSong;
+}
+
+function SongRow({ song }: Props) {
+  const navigate = useNavigate();
+  const enqueue = usePlayerStore(s => s.enqueue);
+  const openContextMenu = usePlayerStore(s => s.openContextMenu);
+  const isCurrent = usePlayerStore(s => s.currentTrack?.id === song.id);
+  const psyDrag = useDragDrop();
+  const { orbitActive, addTrackToOrbit } = useOrbitSongRowBehavior();
+
+  // In an orbit session both buttons collapse into the orbit-suggest / host-enqueue
+  // path so we don't ship a queue replacement to every guest.
+  const handlePlay = () => {
+    if (orbitActive) { addTrackToOrbit(song.id); return; }
+    enqueueAndPlay(song);
+  };
+
+  const handleEnqueue = () => {
+    if (orbitActive) { addTrackToOrbit(song.id); return; }
+    enqueue([songToTrack(song)]);
+  };
+
+  return (
+    <div
+      className={`song-list-row${isCurrent ? ' is-current' : ''}`}
+      onDoubleClick={handlePlay}
+      onContextMenu={(e) => {
+        e.preventDefault();
+        openContextMenu(e.clientX, e.clientY, song, 'song');
+      }}
+      onMouseDown={(e) => {
+        if (e.button !== 0) return;
+        const sx = e.clientX, sy = e.clientY;
+        const track = songToTrack(song);
+        const onMove = (me: MouseEvent) => {
+          if (Math.abs(me.clientX - sx) > 5 || Math.abs(me.clientY - sy) > 5) {
+            document.removeEventListener('mousemove', onMove);
+            document.removeEventListener('mouseup', onUp);
+            psyDrag.startDrag(
+              { data: JSON.stringify({ type: 'song', track }), label: song.title },
+              me.clientX, me.clientY,
+            );
+          }
+        };
+        const onUp = () => {
+          document.removeEventListener('mousemove', onMove);
+          document.removeEventListener('mouseup', onUp);
+        };
+        document.addEventListener('mousemove', onMove);
+        document.addEventListener('mouseup', onUp);
+      }}
+    >
+      <div className="song-list-row-cell song-list-row-actions">
+        <button
+          className="song-list-row-btn song-list-row-btn--play"
+          onClick={(e) => { e.stopPropagation(); handlePlay(); }}
+          aria-label="Play"
+        >
+          <Play size={14} fill="currentColor" />
+        </button>
+        <button
+          className="song-list-row-btn"
+          onClick={(e) => { e.stopPropagation(); handleEnqueue(); }}
+          aria-label="Enqueue"
+        >
+          <ListPlus size={14} />
+        </button>
+      </div>
+      <div className="song-list-row-cell song-list-row-title truncate" title={song.title}>{song.title}</div>
+      <div className="song-list-row-cell truncate">
+        <span
+          className={song.artistId ? 'track-artist-link' : ''}
+          style={{ cursor: song.artistId ? 'pointer' : 'default' }}
+          onClick={(e) => { if (song.artistId) { e.stopPropagation(); navigate(`/artist/${song.artistId}`); } }}
+          title={song.artist}
+        >{song.artist}</span>
+      </div>
+      <div className="song-list-row-cell truncate">
+        {song.albumId ? (
+          <span
+            className="track-artist-link"
+            style={{ cursor: 'pointer' }}
+            onClick={(e) => { e.stopPropagation(); navigate(`/album/${song.albumId}`); }}
+            title={song.album}
+          >{song.album}</span>
+        ) : <span title={song.album}>{song.album}</span>}
+      </div>
+      <div className="song-list-row-cell song-list-row-genre truncate" title={song.genre ?? ''}>
+        {song.genre ?? '—'}
+      </div>
+      <div className="song-list-row-cell song-list-row-duration">{fmtDuration(song.duration)}</div>
+    </div>
+  );
+}
+
+/** Column header with the same grid as <SongRow>. Optional — pages can render it above the list. */
+export function SongListHeader() {
+  const { t } = useTranslation();
+  return (
+    <div className="song-list-row song-list-row--header" role="row">
+      <div className="song-list-row-cell song-list-row-actions" />
+      <div className="song-list-row-cell">{t('albumDetail.trackTitle')}</div>
+      <div className="song-list-row-cell">{t('albumDetail.trackArtist')}</div>
+      <div className="song-list-row-cell">{t('albumDetail.trackAlbum')}</div>
+      <div className="song-list-row-cell">{t('randomMix.trackGenre')}</div>
+      <div className="song-list-row-cell song-list-row-duration">{t('albumDetail.trackDuration')}</div>
+    </div>
+  );
+}
+
+export default memo(SongRow);
@@ -0,0 +1,220 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { Search as SearchIcon, X } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { SubsonicSong, searchSongsPaged } from '../api/subsonic';
+import { ndListSongs } from '../api/navidromeBrowse';
+import SongRow, { SongListHeader } from './SongRow';
+
+const PAGE_SIZE = 50;
+const SEARCH_DEBOUNCE_MS = 300;
+const ROW_HEIGHT = 52;
+const PREFETCH_PX = 600;
+
+/**
+ * Empty query → Navidrome /api/song sorted by title (no Subsonic equivalent).
+ * Non-empty → Subsonic search3 (search isn't a browse).
+ * Either way, returns a SubsonicSong[]; on Navidrome failure we fall back to search3.
+ */
+async function fetchSongPage(query: string, offset: number): Promise<SubsonicSong[]> {
+  if (query !== '') {
+    return searchSongsPaged(query, PAGE_SIZE, offset);
+  }
+  try {
+    return await ndListSongs(offset, offset + PAGE_SIZE, 'title', 'ASC');
+  } catch {
+    return searchSongsPaged('', PAGE_SIZE, offset);
+  }
+}
+
+interface Props {
+  title?: string;
+  emptyBrowseText?: string;
+}
+
+export default function VirtualSongList({ title, emptyBrowseText }: Props) {
+  const { t } = useTranslation();
+  const [query, setQuery] = useState('');
+  const [debouncedQuery, setDebouncedQuery] = useState('');
+  const [songs, setSongs] = useState<SubsonicSong[]>([]);
+  const [offset, setOffset] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [hasMore, setHasMore] = useState(true);
+  const [browseUnsupported, setBrowseUnsupported] = useState(false);
+
+  const scrollParentRef = useRef<HTMLDivElement>(null);
+  const requestSeqRef = useRef(0);
+
+  // Debounce query
+  useEffect(() => {
+    const h = setTimeout(() => setDebouncedQuery(query.trim()), SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(h);
+  }, [query]);
+
+  // Reset + first-page fetch on query change. One effect, no dep cascade,
+  // and a `cancelled` flag so a fast typist doesn't see results from stale queries.
+  useEffect(() => {
+    let cancelled = false;
+    setSongs([]);
+    setOffset(0);
+    setHasMore(true);
+    setBrowseUnsupported(false);
+    if (scrollParentRef.current) scrollParentRef.current.scrollTop = 0;
+
+    const seq = ++requestSeqRef.current;
+    setLoading(true);
+    (async () => {
+      try {
+        const page = await fetchSongPage(debouncedQuery, 0);
+        if (cancelled || seq !== requestSeqRef.current) return;
+        if (page.length === 0) {
+          setHasMore(false);
+          if (debouncedQuery === '') setBrowseUnsupported(true);
+        } else {
+          setSongs(page);
+          setOffset(page.length);
+          if (page.length < PAGE_SIZE) setHasMore(false);
+        }
+      } catch {
+        if (!cancelled) setHasMore(false);
+      } finally {
+        if (!cancelled && seq === requestSeqRef.current) setLoading(false);
+      }
+    })();
+
+    return () => { cancelled = true; };
+  }, [debouncedQuery]);
+
+  const loadMore = useCallback(async () => {
+    if (loading || !hasMore) return;
+    setLoading(true);
+    const seq = ++requestSeqRef.current;
+    try {
+      const page = await fetchSongPage(debouncedQuery, offset);
+      if (seq !== requestSeqRef.current) return;
+      if (page.length === 0) {
+        setHasMore(false);
+      } else {
+        setSongs(prev => {
+          const seen = new Set(prev.map(s => s.id));
+          const merged = [...prev];
+          for (const s of page) if (!seen.has(s.id)) merged.push(s);
+          return merged;
+        });
+        setOffset(o => o + page.length);
+        if (page.length < PAGE_SIZE) setHasMore(false);
+      }
+    } catch {
+      setHasMore(false);
+    } finally {
+      if (seq === requestSeqRef.current) setLoading(false);
+    }
+  }, [loading, hasMore, debouncedQuery, offset]);
+
+  // Scroll-based prefetch — uses ref so a stale loadMore can't loop
+  const loadMoreRef = useRef(loadMore);
+  useEffect(() => { loadMoreRef.current = loadMore; }, [loadMore]);
+
+  useEffect(() => {
+    const el = scrollParentRef.current;
+    if (!el) return;
+    let rafId = 0;
+    const onScroll = () => {
+      if (rafId) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = 0;
+        if (el.scrollTop + el.clientHeight >= el.scrollHeight - PREFETCH_PX) {
+          loadMoreRef.current();
+        }
+      });
+    };
+    el.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      el.removeEventListener('scroll', onScroll);
+      if (rafId) cancelAnimationFrame(rafId);
+    };
+  }, []);
+
+  const virtualizer = useVirtualizer({
+    count: songs.length,
+    getScrollElement: () => scrollParentRef.current,
+    estimateSize: () => ROW_HEIGHT,
+    overscan: 8,
+  });
+
+  const totalSize = virtualizer.getTotalSize();
+  const showEmptyBrowse = !loading && songs.length === 0 && debouncedQuery === '' && (browseUnsupported || !hasMore);
+
+  return (
+    <section className="virtual-song-list-section">
+      {title && <h2 className="section-title virtual-song-list-title">{title}</h2>}
+      <div className="virtual-song-list-toolbar">
+        <div className="virtual-song-list-search">
+          <SearchIcon size={16} className="virtual-song-list-search-icon" />
+          <input
+            type="text"
+            className="input virtual-song-list-search-input"
+            placeholder={t('tracks.searchPlaceholder')}
+            value={query}
+            onChange={e => setQuery(e.target.value)}
+          />
+          {query && (
+            <button
+              className="virtual-song-list-search-clear"
+              onClick={() => setQuery('')}
+              aria-label={t('search.clearLabel')}
+            >
+              <X size={14} />
+            </button>
+          )}
+        </div>
+        <div className="virtual-song-list-meta">
+          {songs.length > 0 && (
+            <span>{t('tracks.count', { count: songs.length })}{hasMore ? '+' : ''}</span>
+          )}
+        </div>
+      </div>
+
+      {showEmptyBrowse ? (
+        <div className="virtual-song-list-empty">
+          {emptyBrowseText ?? t('tracks.browseUnsupported')}
+        </div>
+      ) : (
+        <>
+          <SongListHeader />
+          <div ref={scrollParentRef} className="virtual-song-list-scroll">
+            <div style={{ height: totalSize, width: '100%', position: 'relative' }}>
+            {virtualizer.getVirtualItems().map(vi => {
+              const song = songs[vi.index];
+              if (!song) return null;
+              return (
+                <div
+                  key={vi.key}
+                  style={{
+                    position: 'absolute',
+                    top: 0,
+                    left: 0,
+                    width: '100%',
+                    height: ROW_HEIGHT,
+                    transform: `translateY(${vi.start}px)`,
+                  }}
+                >
+                  <SongRow
+                    song={song}
+                  />
+                </div>
+              );
+            })}
+          </div>
+            {loading && (
+              <div className="virtual-song-list-loading">
+                <div className="spinner" style={{ width: 18, height: 18 }} />
+                <span>{t('common.loadingMore')}</span>
+              </div>
+            )}
+          </div>
+        </>
+      )}
+    </section>
+  );
+}