chore(orbit): launch popover with create / join / help entries

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/OrbitJoinModal.tsx

@@ -0,0 +1,139 @@
+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 { 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(/\/+$/, '');
+    if (activeUrl !== wantUrl) {
+      setError(t('orbit.toastSwitchServer', { url: wantUrl }));
+      return;
+    }
+
+    setBusy(true);
+    try {
+      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,
+  );
+}

src/components/OrbitStartTrigger.tsx

@@ -1,34 +1,103 @@
-import { useState } from 'react';
-import { Orbit as OrbitIcon } from 'lucide-react';
+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 OrbitStartModal from './OrbitStartModal';
+import OrbitJoinModal from './OrbitJoinModal';
 
 /**
- * Topbar trigger — opens the start-session modal. Hidden while a session
- * is already active (role !== null) to avoid double-entry.
+ * 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 [open, setOpen] = useState(false);
+
+  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;
 
+  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); };
+
   return (
     <>
       <button
+        ref={btnRef}
         type="button"
         className="btn btn-surface orbit-start-trigger"
-        onClick={() => setOpen(true)}
+        onClick={() => setPopoverOpen(v => !v)}
         data-tooltip={t('orbit.triggerTooltip')}
         data-tooltip-pos="bottom"
+        aria-haspopup="menu"
+        aria-expanded={popoverOpen || undefined}
         style={{ position: 'relative', display: 'flex', alignItems: 'center', gap: '0.5rem', padding: '0.5rem 1rem' }}
       >
         <OrbitIcon size={18} />
         <span>{t('orbit.triggerLabel')}</span>
       </button>
-      {open && <OrbitStartModal onClose={() => setOpen(false)} />}
+
+      {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"
+            disabled
+            data-tooltip={t('orbit.launchHelpSoon')}
+            data-tooltip-pos="bottom"
+          >
+            <HelpCircle size={14} />
+            <span>{t('orbit.launchHelp')}</span>
+          </button>
+        </div>,
+        document.body,
+      )}
+
+      {startOpen && <OrbitStartModal onClose={() => setStartOpen(false)} />}
+      {joinOpen && <OrbitJoinModal onClose={() => setJoinOpen(false)} />}
     </>
   );
 }

src/locales/de.ts

@@ -1449,7 +1449,21 @@ export const deTranslation = {
   },
   orbit: {
     triggerLabel: 'Psy Orbit',
-    triggerTooltip: 'Gemeinsame Hör-Session starten',
+    triggerTooltip: 'Gemeinsame Hör-Session starten oder beitreten',
+    launchCreate: 'Session erstellen',
+    launchJoin: 'Session beitreten',
+    launchHelp: 'Wie funktioniert das?',
+    launchHelpSoon: 'Kommt bald',
+    joinModalTitle: 'Einer Orbit-Session beitreten',
+    joinModalSub: 'Füge den Einladungslink ein, den dir der Host geschickt hat.',
+    joinModalLinkLabel: 'Einladungslink',
+    joinModalLinkPlaceholder: 'psysonic2://orbit/…',
+    joinModalLinkHelper: 'Akzeptiert jeden gültigen Orbit-Link. Der Link muss zu dem Server gehören, auf dem du gerade angemeldet bist.',
+    joinModalPasteTooltip: 'Aus Zwischenablage einfügen',
+    joinModalSubmit: 'Beitreten',
+    joinModalBusy: 'Beitreten…',
+    joinErrEmpty: 'Bitte Einladungslink einfügen.',
+    joinErrInvalid: 'Das sieht nicht nach einem Orbit-Einladungslink aus.',
     closeAria: 'Schließen',
     heroTitlePrefix: 'Gemeinsam hören mit',
     heroTitleBrand: 'Psy Orbit',

src/locales/en.ts

@@ -1452,7 +1452,21 @@ export const enTranslation = {
   },
   orbit: {
     triggerLabel: 'Psy Orbit',
-    triggerTooltip: 'Start a shared listening session',
+    triggerTooltip: 'Start or join a shared listening session',
+    launchCreate: 'Create a session',
+    launchJoin: 'Join a session',
+    launchHelp: 'How does this work?',
+    launchHelpSoon: 'Coming soon',
+    joinModalTitle: 'Join an Orbit session',
+    joinModalSub: 'Paste the invite link your host sent you.',
+    joinModalLinkLabel: 'Invite link',
+    joinModalLinkPlaceholder: 'psysonic2://orbit/…',
+    joinModalLinkHelper: 'Works with any valid Orbit link. Must point to the server you\'re currently signed into.',
+    joinModalPasteTooltip: 'Paste from clipboard',
+    joinModalSubmit: 'Join',
+    joinModalBusy: 'Joining…',
+    joinErrEmpty: 'Please paste an invite link.',
+    joinErrInvalid: 'That doesn\'t look like an Orbit invite link.',
     closeAria: 'Close',
     heroTitlePrefix: 'Listen together with',
     heroTitleBrand: 'Psy Orbit',

src/styles/components.css

@@ -11878,6 +11878,46 @@ html[data-psy-native-hidden="true"] *::after {
 }
 .orbit-start-trigger:hover svg { transform: rotate(45deg); }
 
+/* Launch popover — three-option menu anchored below the topbar trigger. */
+.orbit-launch-pop {
+  min-width: 220px;
+  padding: 6px;
+  background: var(--ctp-base, #1e1e2e);
+  border: 1px solid color-mix(in srgb, var(--accent) 22%, rgba(255,255,255,0.1));
+  border-radius: var(--radius-md);
+  box-shadow: 0 10px 30px rgba(0,0,0,0.5);
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.orbit-launch-pop__item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 9px 10px;
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  color: var(--text-primary);
+  font-size: 13px;
+  font-weight: 500;
+  text-align: left;
+  cursor: pointer;
+  transition: background 120ms ease, color 120ms ease;
+}
+.orbit-launch-pop__item svg {
+  color: var(--accent);
+  flex-shrink: 0;
+}
+.orbit-launch-pop__item:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+}
+.orbit-launch-pop__item:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
 /* ── Start-session modal ────────────────────────────────────────── */
 .orbit-start-overlay {
   align-items: center;