poll.js

/**
 * Standalone live polling app.
 *
 * Lives next to quiz.js but never imports from it. Uses the same WebSocket
 * server protocol (create_room / join / start_question / submit_answer /
 * send_results / terminate) so the server stays untouched. Poll-specific
 * metadata that the server's whitelist would otherwise drop (picksPerVoter,
 * revealCount, source) is smuggled as the first element of `options` — a
 * sentinel string `__POLL_META__:{...}` that players strip before display.
 *
 * Two poll variants share one flow:
 *   - source: "players" — options are current room players' names (snapshotted
 *     at vote-start). For Klassensprecher elections, party feedback polls.
 *   - source: "fixed"   — options are host-typed strings. For surveys,
 *     excursion-location votes, etc.
 *
 * Both use ranked Borda aggregation. No points awarded. Top-`revealCount`
 * podium reveal (scales from 3-slot up to a full ranked list).
 */

/* ============================================================================
 * WebSocket URL — same convention as quiz.js (build-time placeholder,
 * runtime override, production fallback).
 * ============================================================================ */
const RAW_URL = '__WS_URL__';
const FALLBACK_WS_URL = RAW_URL === '__WS_URL__' ? 'wss://qlash-server.fly.dev' : RAW_URL;
const HAS_RUNTIME_WS_URL =
    globalThis.window !== undefined && globalThis.WS_URL && globalThis.WS_URL !== '__WS_URL__';
const WS_URL = HAS_RUNTIME_WS_URL ? globalThis.WS_URL : FALLBACK_WS_URL;

/* ============================================================================
 * Constants
 * ============================================================================ */
// First options[] slot carries this prefixed JSON; server's per-option 500-char
// validation gives us plenty of headroom for {picksPerVoter, revealCount, source}.
const POLL_META_PREFIX = '__POLL_META__:';
// Server caps options.length at MAX_OPTIONS_PER_QUESTION (250). Slot 0 is the
// metadata sentinel, leaving 249 real options — comfortably above
// MAX_PLAYERS_PER_ROOM (240) so a full-room Klassensprecher poll fits.
const MAX_REAL_OPTIONS = 240;
const MAX_PICKS_PER_VOTER = 20;
const MIN_DURATION_SEC = 5;
const MAX_DURATION_SEC = 80;
const SESSION_STORAGE_KEY = 'poll_active_session';
const PICKS_STORAGE_KEY = 'poll_last_picks';
// 24 h matches quiz.js. The server-side room expiry (2 h) is the real ceiling;
// this TTL is just for stale-entry cleanup if the user never returns. A poll
// that's been gone longer than this is no longer recoverable anyway.
const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
const MAX_RECONNECT_ATTEMPTS = 30;
// Application-level heartbeat. The server pings every 30 s at the WebSocket
// protocol level and the browser auto-pongs, but (a) some intermediate proxies
// (carrier NAT, corporate firewalls) only see app-layer frames as "activity"
// and drop the TCP socket after ~60 s of silence, and (b) if the server's
// network silently goes dark without closing the TCP connection, the browser
// may keep the socket in OPEN state for many seconds before noticing.
//
// We send a `{type:'heartbeat'}` every 25 s; the server replies with
// `{type:'heartbeat_ack'}`. A watchdog on the client side checks how long ago
// we last heard *anything* from the server (heartbeat ack, game message, etc.)
// — if > HEARTBEAT_TIMEOUT_MS, we force-close the socket and let the unified
// reconnect logic take over.
const HEARTBEAT_INTERVAL_MS = 25_000;
const HEARTBEAT_TIMEOUT_MS = 60_000;
const HEARTBEAT_WATCHDOG_INTERVAL_MS = 10_000;
const HEARTBEAT_PAYLOAD = JSON.stringify({ type: 'heartbeat' });

/* ============================================================================
 * Tiny helpers
 * ============================================================================ */

/**
 * Toast notification. Same visual pattern as quiz.js so the two apps feel
 * kindred; duplicated here per the no-touch-quiz directive.
 * @param {string} message
 * @param {'info'|'error'} [type]
 */
function showMessage(message, type = 'info') {
    const existing = document.querySelector('#toast-notification');
    if (existing) existing.remove();

    const toast = document.createElement('div');
    toast.id = 'toast-notification';
    toast.className = `toast-notification toast-${type}`;
    // Announce to assistive tech: errors assertively, everything else politely.
    toast.setAttribute('role', type === 'error' ? 'alert' : 'status');
    toast.textContent = message;
    document.body.append(toast);

    requestAnimationFrame(() => toast.classList.add('show'));

    setTimeout(() => {
        toast.classList.remove('show');
        setTimeout(() => {
            if (toast.parentNode) toast.remove();
        }, 300);
    }, 4000);
}

/**
 * Accessible modal dialog — a themed, focus-trapped replacement for the native
 * blocking `confirm()`. Resolves to `true` (confirmed) / `false` (cancelled).
 * Esc and backdrop click cancel; Enter on the focused confirm button confirms;
 * focus is trapped while open and restored on close.
 * @param {object} opts
 * @param {string} opts.message
 * @param {string} [opts.confirmText]
 * @param {string} [opts.cancelText]
 * @param {boolean} [opts.danger] - Style the confirm button as destructive.
 * @returns {Promise<boolean>}
 */
function uiDialog(opts) {
    const { message, confirmText = 'OK', cancelText = 'Abbrechen', danger = false } = opts;

    return new Promise((resolve) => {
        const previouslyFocused = document.activeElement;

        const backdrop = document.createElement('div');
        backdrop.className = 'ui-modal-backdrop';

        const modal = document.createElement('div');
        modal.className = 'ui-modal';
        modal.setAttribute('role', 'alertdialog');
        modal.setAttribute('aria-modal', 'true');

        const msgEl = document.createElement('p');
        msgEl.className = 'ui-modal-message';
        msgEl.id = `ui-modal-msg-${Date.now()}`;
        msgEl.textContent = message;
        modal.setAttribute('aria-labelledby', msgEl.id);
        modal.append(msgEl);

        const actions = document.createElement('div');
        actions.className = 'ui-modal-actions';

        const cancelBtn = document.createElement('button');
        cancelBtn.type = 'button';
        cancelBtn.className = 'ui-modal-btn ui-modal-cancel';
        cancelBtn.textContent = cancelText;

        const confirmBtn = document.createElement('button');
        confirmBtn.type = 'button';
        confirmBtn.className = `ui-modal-btn ui-modal-confirm${danger ? ' ui-modal-danger' : ''}`;
        confirmBtn.textContent = confirmText;

        actions.append(cancelBtn, confirmBtn);
        modal.append(actions);
        backdrop.append(modal);
        document.body.append(backdrop);

        const prevBodyOverflow = document.body.style.overflow;
        document.body.style.overflow = 'hidden';

        let settled = false;
        /**
         * @param {boolean} result
         */
        function close(result) {
            if (settled) return;
            settled = true;
            document.removeEventListener('keydown', onKeydown, true);
            document.body.style.overflow = prevBodyOverflow;
            backdrop.remove();
            if (previouslyFocused && typeof previouslyFocused.focus === 'function') {
                previouslyFocused.focus();
            }
            resolve(result);
        }

        /**
         * @param {KeyboardEvent} e
         */
        function onKeydown(e) {
            if (e.key === 'Escape') {
                e.preventDefault();
                close(false);
            } else if (e.key === 'Tab') {
                const first = cancelBtn;
                const last = confirmBtn;
                if (e.shiftKey && document.activeElement === first) {
                    e.preventDefault();
                    last.focus();
                } else if (!e.shiftKey && document.activeElement === last) {
                    e.preventDefault();
                    first.focus();
                }
            }
        }

        cancelBtn.addEventListener('click', () => close(false));
        confirmBtn.addEventListener('click', () => close(true));
        backdrop.addEventListener('mousedown', (e) => {
            if (e.target === backdrop) close(false);
        });
        document.addEventListener('keydown', onKeydown, true);

        confirmBtn.focus();
    });
}

/**
 * Themed confirm dialog. @see uiDialog
 * @param {string} message
 * @param {object} [options]
 * @returns {Promise<boolean>}
 */
function uiConfirm(message, options = {}) {
    return uiDialog({ ...options, message });
}

/**
 * Show a top-level view (role-selection / host-view / player-view) and hide
 * the others. View IDs match the markup in poll.html.
 * @param {string} id
 */
function showTopView(id) {
    for (const v of document.querySelectorAll('.view')) v.classList.remove('active');
    const el = document.querySelector(`#${CSS.escape(id)}`);
    if (el) el.classList.add('active');
}

/**
 * Within host-view or player-view, show one sub-section and hide its siblings.
 * @param {string[]} allIds
 * @param {string} showId
 */
function showOnly(allIds, showId) {
    for (const id of allIds) {
        const el = document.querySelector(`#${CSS.escape(id)}`);
        if (!el) continue;
        el.classList.toggle('hidden', id !== showId);
    }
}

/**
 * WebSocket connect with retry — mirrors quiz.js's connectWithRetry to handle
 * Fly.io cold starts.
 * @param {string} url
 * @param {number} [maxRetries]
 * @returns {Promise<WebSocket>}
 */
function connectWithRetry(url, maxRetries = 3) {
    return new Promise((resolve, reject) => {
        let attempt = 0;
        function tryConnect() {
            attempt++;
            const ws = new WebSocket(url);
            let settled = false;
            // Listener refs so we can detach the unused one on settle.
            let onOpen;
            let onError;
            const detach = () => {
                ws.removeEventListener('open', onOpen);
                ws.removeEventListener('error', onError);
            };
            const timeout = setTimeout(() => {
                if (settled) return;
                settled = true;
                detach();
                ws.close();
                if (attempt < maxRetries) {
                    setTimeout(tryConnect, 2000 * attempt);
                } else {
                    reject(new Error('WebSocket connection failed after retries'));
                }
            }, 10_000);
            onOpen = () => {
                if (settled) return;
                settled = true;
                clearTimeout(timeout);
                detach();
                resolve(ws);
            };
            onError = () => {
                if (settled) return;
                settled = true;
                clearTimeout(timeout);
                detach();
                if (attempt < maxRetries) {
                    setTimeout(tryConnect, 2000 * attempt);
                } else {
                    reject(new Error('WebSocket connection failed after retries'));
                }
            };
            ws.addEventListener('open', onOpen);
            ws.addEventListener('error', onError);
        }
        tryConnect();
    });
}

/**
 * ~1 s → ~2 s → ~4 s → ~10 s steady — same backoff as quiz.js. ±25% jitter is
 * applied so a cascade event (e.g. a brief router restart that drops every
 * client at once) doesn't produce a thundering herd hitting the server on the
 * same backoff schedule.
 * @param {number} attempt
 * @returns {number}
 */
function reconnectBackoffMs(attempt) {
    let base;
    if (attempt <= 1) base = 1000;
    else if (attempt === 2) base = 2000;
    else if (attempt === 3) base = 4000;
    else base = 10_000;
    const jitter = 0.75 + Math.random() * 0.5;
    return Math.round(base * jitter);
}

/**
 * Start the bidirectional heartbeat for a WebSocket. Returns a state object
 * holding the rescheduling timer, the watchdog interval, and the last-seen /
 * last-sent timestamps. Pass the state to `stopHeartbeat` when the socket
 * closes.
 *
 * `ws.send` is wrapped so that *any* outbound frame (submit_answer,
 * start_question, heartbeat itself, ...) reschedules the next heartbeat for
 * exactly `HEARTBEAT_INTERVAL_MS` from now. This guarantees the gap between
 * any two outbound frames is at most `HEARTBEAT_INTERVAL_MS` — important for
 * NATs that drop idle TCP after as little as 30 s. A simple periodic
 * `setInterval` skip-if-recent would have a worst-case gap of ~2× the
 * interval (~50 s) when a real send lands just after a tick fires.
 *
 * `state.lastMsgTime` is updated externally (by the message-handler attached
 * in attachXWsHandlers) on every received frame, so an active stream of
 * server-pushed messages keeps the watchdog quiet without a redundant
 * heartbeat round-trip.
 * @param {WebSocket} ws
 * @returns {{heartbeatTimer:number, watchdog:number, lastMsgTime:number, lastSendTime:number}}
 */
function startHeartbeat(ws) {
    const now = Date.now();
    const state = { lastMsgTime: now, lastSendTime: now, heartbeatTimer: null };

    function scheduleNextHeartbeat() {
        if (state.heartbeatTimer !== null) clearTimeout(state.heartbeatTimer);
        state.heartbeatTimer = setTimeout(() => {
            if (!ws || ws.readyState !== WebSocket.OPEN) return;
            try {
                // Goes through the wrapped send, which itself reschedules.
                ws.send(HEARTBEAT_PAYLOAD);
            } catch (error) {
                logger.error('Heartbeat send failed:', error);
            }
        }, HEARTBEAT_INTERVAL_MS);
    }

    // Wrap ws.send so every outbound frame bumps lastSendTime *and* resets
    // the heartbeat timer. Stash the native bound send on the socket itself
    // so a second startHeartbeat call on the same socket doesn't capture
    // the previous wrapper as "original" and stack wrappers (which would
    // self-reschedule recursively on each outbound frame).
    if (!ws.__heartbeatNativeSend) {
        ws.__heartbeatNativeSend = ws.send.bind(ws);
    }
    const originalSend = ws.__heartbeatNativeSend;
    ws.send = (...args) => {
        state.lastSendTime = Date.now();
        scheduleNextHeartbeat();
        return originalSend(...args);
    };

    // Kick off the first heartbeat 25 s from now (initial state).
    scheduleNextHeartbeat();

    state.watchdog = setInterval(() => {
        if (!ws || ws.readyState !== WebSocket.OPEN) return;
        const silentMs = Date.now() - state.lastMsgTime;
        if (silentMs > HEARTBEAT_TIMEOUT_MS) {
            logger.warn(
                `No server activity for ${Math.round(silentMs / 1000)}s — forcing reconnect.`
            );
            try {
                ws.close();
            } catch {
                /* close already in progress */
            }
        }
    }, HEARTBEAT_WATCHDOG_INTERVAL_MS);

    return state;
}

/**
 * @param {{heartbeatTimer:number|null, watchdog:number}|null} state
 * @returns {null}
 */
function stopHeartbeat(state) {
    if (state) {
        if (state.heartbeatTimer !== null) clearTimeout(state.heartbeatTimer);
        clearInterval(state.watchdog);
    }
    return null;
}

/**
 * Session save/load/clear so a page reload mid-poll can re-attach without
 * re-entering a code.
 * @param role
 * @param roomId
 * @param sessionId
 * @param extra
 */
function saveActiveSession(role, roomId, sessionId, extra = {}) {
    try {
        localStorage.setItem(
            SESSION_STORAGE_KEY,
            JSON.stringify({ role, roomId, sessionId, ts: Date.now(), ...extra })
        );
    } catch {
        /* private mode */
    }
}
function loadActiveSession() {
    try {
        const raw = localStorage.getItem(SESSION_STORAGE_KEY);
        if (!raw) return null;
        const parsed = JSON.parse(raw);
        if (!parsed || !parsed.role || !parsed.roomId || !parsed.sessionId) return null;
        if (parsed.ts && Date.now() - parsed.ts > SESSION_TTL_MS) {
            localStorage.removeItem(SESSION_STORAGE_KEY);
            return null;
        }
        return parsed;
    } catch {
        return null;
    }
}
function clearActiveSession() {
    try {
        localStorage.removeItem(SESSION_STORAGE_KEY);
    } catch {
        /* private mode */
    }
}

/**
 * Last-submitted picks: keep them across reconnect so the player can still
 * see their own ballot on the reveal even if they were disconnected when the
 * server replayed `alreadySubmitted: true`.
 * @param roomId
 * @param questionKey
 * @param picks
 */
function saveLastPicks(roomId, questionKey, picks) {
    try {
        sessionStorage.setItem(PICKS_STORAGE_KEY, JSON.stringify({ roomId, questionKey, picks }));
    } catch {
        /* private mode */
    }
}
function loadLastPicks(roomId, questionKey) {
    try {
        const raw = sessionStorage.getItem(PICKS_STORAGE_KEY);
        if (!raw) return null;
        const p = JSON.parse(raw);
        if (p && p.roomId === roomId && p.questionKey === questionKey) return p.picks;
        return null;
    } catch {
        return null;
    }
}
function clearLastPicks() {
    try {
        sessionStorage.removeItem(PICKS_STORAGE_KEY);
    } catch {
        /* private mode */
    }
}

/* ============================================================================
 * Metadata encoding
 *
 * options[0] = '__POLL_META__:' + JSON.stringify({picksPerVoter, revealCount,
 * source}); options[1..N] are the displayable choices. Players strip slot 0
 * before rendering; their submitted indices refer to slot positions in the
 * full options array (so a "first real option" submission is index 1, not 0).
 * The host computes Borda over those same indices.
 * ============================================================================ */

/**
 * @param {{picksPerVoter:number, revealCount:number|'all', source:'players'|'fixed'}} meta
 * @returns {string}
 */
function encodeMeta(meta) {
    return POLL_META_PREFIX + JSON.stringify(meta);
}

/**
 * @param {string} optionZero
 * @returns {{picksPerVoter:number, revealCount:number|'all', source:string}|null}
 */
function decodeMeta(optionZero) {
    if (typeof optionZero !== 'string' || !optionZero.startsWith(POLL_META_PREFIX)) {
        return null;
    }
    try {
        const obj = JSON.parse(optionZero.slice(POLL_META_PREFIX.length));
        if (!obj || typeof obj !== 'object') return null;
        const picks = Number(obj.picksPerVoter);
        const reveal = obj.revealCount === 'all' ? 'all' : Number(obj.revealCount);
        const source = obj.source === 'fixed' ? 'fixed' : 'players';
        if (!Number.isFinite(picks) || picks < 1) return null;
        if (reveal !== 'all' && (!Number.isFinite(reveal) || reveal < 1)) return null;
        return { picksPerVoter: picks, revealCount: reveal, source };
    } catch {
        return null;
    }
}

/* ============================================================================
 * Shared module state
 * ============================================================================ */

// Host state
let hostWs = null;
let hostRoomId = null;
let hostSessionId = null;
let hostWsReconnectAttempts = 0;
let hostSuppressReconnect = false;
// True while a reconnect attempt is in flight (awaiting connectWithRetry).
// Prevents the close handler, the `online` event, and a manual button click
// from racing into multiple parallel WebSocket connections.
let hostReconnecting = false;
let hostHeartbeat = null;
// players keyed by sessionId; value: { name, isConnected }
const hostPlayers = new Map();
// During an active poll: snapshot of the broadcast question payload + answers.
let hostActivePoll = null; // {question, options, picksPerVoter, revealCount, source, duration}
// Guard so endVote() can be triggered from multiple sources (timer, auto-end,
// host click) without re-sending results.
let hostPollEnding = false;
const hostAnswers = new Map(); // sessionId -> {ranks: number[], name}
let hostTimerInterval = null;
// Pending question to send once a fresh hostWs is open after a transient drop.
let hostPendingQuestion = null;
// Pending results frame to send once a fresh hostWs is open after a transient
// drop. Without this, an endVote() that ran while the host WS was closed
// would compute the podium locally but never notify the players — they'd be
// stuck on the voting screen until reconnect or manual session end.
let hostPendingResults = null;
// Grace timer that defers maybeAutoEndVote when a disconnect makes the
// remaining connected players look all-voted. Lets a reloading voter rejoin
// before the vote closes around them.
let hostDisconnectGraceTimeout = null;
const DISCONNECT_GRACE_MS = 10_000;

// Player state
let playerWs = null;
let playerRoomCode = null;
let playerSessionId = null;
let playerName = null;
let playerWsReconnectAttempts = 0;
let playerSuppressReconnect = false;
// See hostReconnecting — same purpose.
let playerReconnecting = false;
let playerHeartbeat = null;
let playerCurrentMeta = null;
let playerDisplayOptions = []; // options[1..N] (sliced)
let playerOptionIndexBase = 1; // index of the first displayable option in raw options
let playerCurrentQuestion = ''; // raw question text
let playerSelectedRanks = []; // indices into raw options
let playerHasSubmitted = false;
let playerTimerInterval = null;
let playerCurrentQuestionKey = ''; // stable identifier for "this question"

// Composer state for fixed source
const composerFixedOptions = ['', ''];

// Built-in question suggestions for the host — class-rep-style "Wer …" awards.
// All are source: "players" polls (voting for someone in the room). The host
// can always type their own question instead; suggestions are unobtrusive.
const POLL_SUGGESTIONS = [
    {
        title: 'Mebis-Sherpa',
        question:
            'Mebis-Sherpa: Wer hat die eigene Gruppe durch die tiefsten Mebis-Kapitel gecarried und alle mit Lösungen versorgt?',
    },
    {
        title: 'Koffein-Reaktor',
        question:
            'Koffein-Reaktor: Wer besteht nach drei Jahren eigentlich zu 80 % aus Energydrinks und Mate statt aus Wasser?',
    },
    {
        title: 'Linux-Prediger*in',
        question:
            'Linux-Prediger*in: Wer lässt keine Gelegenheit aus zu betonen, dass Windows Müll ist und Arch das einzig Wahre ist? (I use Arch, btw)',
    },
    {
        title: 'Git-Poet*in',
        question:
            'Git-Poet*in: Wer schreibt die wildesten Commit-Messages? (z. B. "update", "fix", "asdasd", "jetzt gehts")',
    },
    {
        title: 'Stealth-Gamer*in',
        question:
            'Stealth-Gamer*in: Wer hat im Unterricht völlig unbemerkt hunderte Stunden in Games versenkt?',
    },
    {
        title: 'Zukünftige*r Start-up-Milliardär*in',
        question:
            'Zukünftige*r Start-up-Milliardär*in: Wer gründet als Erstes ein Start-up für ein überkomplexes Gadget, das absolut niemand braucht?',
    },
    {
        title: 'Chief Hydration Officer (CHO)',
        question:
            'Chief Hydration Officer (CHO): Wer hat heldenhaft die Klasse am Wasserspender versorgt und vor dem Dehydrieren bewahrt?',
    },
    {
        title: 'ChatGPT-Magier*in',
        question:
            'ChatGPT-Magier*in: Wer hat die gesamte schulische Existenz aus perfekten Prompts zusammengeklebt – und es hat funktioniert?',
    },
    {
        title: 'Bullshit-Bingo-Legende',
        question:
            'Bullshit-Bingo-Legende: Schlecht gelernt, perfekt verkauft: Wer referiert souverän über Themen, die erst 5 Minuten vorher gegoogelt wurden?',
    },
    {
        title: 'Heimliche*r 1st-Level-Support',
        question:
            'Heimliche*r 1st-Level-Support: Wer ist die unfreiwillige Dauer-Hotline für die ByCS- und WLAN-Probleme der kompletten Klasse?',
    },
    {
        title: 'Berichtsheft-Pedant*in',
        question:
            'Berichtsheft-Pedant*in: Wer führt das Berichtsheft wie ein Git-Repo – mit fix:-Einträgen und einem Branch pro Quartal?',
    },
    {
        title: 'IHK-Stoiker*in',
        question:
            'IHK-Stoiker*in: Wer hat in der Abschlussprüfung eiskalt vier Sekunden vor Abgabe das letzte Kreuz gesetzt?',
    },
    {
        title: 'Hardware-Jünger*in',
        question:
            'Hardware-Jünger*in: Wer investiert das allererste richtige Gehalt sofort in eine RTX 5090?',
    },
    {
        title: 'Meme-Beauftragte*r',
        question:
            'Meme-Beauftragte*r: Wer postet im Klassenchat deutlich mehr Memes und :wq-Jokes als ernsthafte Nachrichten?',
    },
    {
        title: 'Open-Source-Philanthrop*in',
        question:
            'Open-Source-Philanthrop*in: Wer hat während des Unterrichts heimlich Bug-Bounties gesammelt oder Pull Requests eingereicht?',
    },
];

// Cycle state: the host walks a single shuffled order of all suggestions
// (randomized once per session, then deterministic). A substring filter from
// the question textarea is applied on top — cycling and auto-pick stay within
// matching suggestions. When the typed text matches nothing, the filter is
// ignored so a suggestion still shows (same as an empty input).
let suggestionOrder = [];
let suggestionCursor = 0;
let currentSuggestionIdx = null;

/* ============================================================================
 * DOM references — populated on DOMContentLoaded.
 * ============================================================================ */

let dom = {};

/**
 *
 */
function collectDom() {
    dom = {
        roleSelection: document.querySelector('#role-selection'),
        hostBtn: document.querySelector('#host-btn'),
        playerBtn: document.querySelector('#player-btn'),
        reconnectHostBtn: document.querySelector('#reconnect-host-btn'),
        reconnectPlayerBtn: document.querySelector('#reconnect-player-btn'),

        hostView: document.querySelector('#host-view'),
        hostLobby: document.querySelector('#host-lobby'),
        hostComposer: document.querySelector('#host-composer'),
        hostVoting: document.querySelector('#host-voting'),
        hostReveal: document.querySelector('#host-reveal'),

        playerView: document.querySelector('#player-view'),
        joinForm: document.querySelector('#join-form'),
        playerWaiting: document.querySelector('#player-waiting'),
        playerVote: document.querySelector('#player-vote'),
        playerSubmitted: document.querySelector('#player-submitted'),
        playerReveal: document.querySelector('#player-reveal'),

        // Lobby
        qrcodeEl: document.querySelector('#qrcode'),
        joinLink: document.querySelector('#join-link'),
        roomIdEl: document.querySelector('#room-id'),
        playerCountEl: document.querySelector('#player-count'),
        playersListEl: document.querySelector('#players-list'),
        showComposerBtn: document.querySelector('#show-composer-btn'),

        // Composer
        composerQuestion: document.querySelector('#composer-question'),
        suggestionBox: document.querySelector('#suggestion-box'),
        suggestionTitle: document.querySelector('#suggestion-title'),
        suggestionText: document.querySelector('#suggestion-text'),
        applySuggestionBtn: document.querySelector('#apply-suggestion-btn'),
        cycleSuggestionBtn: document.querySelector('#cycle-suggestion-btn'),
        sourceRadios: document.querySelectorAll('input[name="poll-source"]'),
        fixedOptionsSection: document.querySelector('#fixed-options-section'),
        composerOptionsList: document.querySelector('#composer-options'),
        addOptionBtn: document.querySelector('#add-option-btn'),
        composerPicks: document.querySelector('#composer-picks'),
        composerReveal: document.querySelector('#composer-reveal'),
        composerRevealAll: document.querySelector('#composer-reveal-all'),
        composerDuration: document.querySelector('#composer-duration'),
        startVoteBtn: document.querySelector('#start-vote-btn'),
        backToLobbyBtn: document.querySelector('#back-to-lobby-btn'),

        // Voting (host)
        hostQuestionDisplay: document.querySelector('#host-question-display'),
        hostTimerBar: document.querySelector('#host-timer-bar'),
        hostAnswersCount: document.querySelector('#host-answers-count'),
        hostTotalPlayers: document.querySelector('#host-total-players'),
        hostLiveOptions: document.querySelector('#host-live-options'),
        endVoteBtn: document.querySelector('#end-vote-btn'),

        // Reveal (host)
        hostRevealQuestion: document.querySelector('#host-reveal-question'),
        hostPodiumList: document.querySelector('#host-podium-list'),
        hostRevealMeta: document.querySelector('#host-reveal-meta'),
        nextQuestionBtn: document.querySelector('#next-question-btn'),
        endSessionBtn: document.querySelector('#end-session-btn'),

        // Player
        roomCodeInput: document.querySelector('#room-code-input'),
        playerNameInput: document.querySelector('#player-name-input'),
        joinBtn: document.querySelector('#join-btn'),
        playerWaitingStatus: document.querySelector('#player-waiting-status'),
        playerNameDisplay: document.querySelector('#player-name-display'),
        playerQuestionText: document.querySelector('#player-question-text'),
        playerTimerBar: document.querySelector('#player-timer-bar'),
        playerVoteHint: document.querySelector('#player-vote-hint'),
        rankList: document.querySelector('#rank-list'),
        rankListEmpty: document.querySelector('#rank-list-empty'),
        rankOptions: document.querySelector('#rank-options'),
        submitVoteBtn: document.querySelector('#submit-vote-btn'),
        submittedPicksEcho: document.querySelector('#submitted-picks-echo'),
        playerRevealQuestion: document.querySelector('#player-reveal-question'),
        playerPodiumList: document.querySelector('#player-podium-list'),
        playerPicksEcho: document.querySelector('#player-picks-echo'),
        playerRevealStatus: document.querySelector('#player-reveal-status'),

        // QR modal
        qrModalOverlay: document.querySelector('#qr-modal-overlay'),
        qrModalClose: document.querySelector('#qr-modal-close'),
        largeQrcode: document.querySelector('#large-qrcode'),
        joinLinkModal: document.querySelector('#join-link-modal'),
        modalRoomIdSpan: document.querySelector('#modal-room-id'),
    };
}

/* ============================================================================
 * QR code rendering
 * ============================================================================ */

/**
 * @param {string} roomId
 * @returns {string}
 */
function buildJoinUrl(roomId) {
    const loc = globalThis.location;
    const base = `${loc.protocol}//${loc.host}${loc.pathname}`;
    return `${base}?room=${encodeURIComponent(roomId)}`;
}

/**
 * @param {string} url
 */
function renderQrCode(url) {
    if (!dom.qrcodeEl) return;
    dom.qrcodeEl.innerHTML = '';
    if (typeof QRCode === 'undefined') return;
    try {
        new QRCode(dom.qrcodeEl, {
            text: url,
            width: 180,
            height: 180,
            correctLevel: QRCode.CorrectLevel.H,
        });
    } catch (error) {
        logger.error('QR generation failed:', error);
    }
}

/**
 * @param {string} url
 */
function renderLargeQrCode(url) {
    if (!dom.largeQrcode) return;
    dom.largeQrcode.innerHTML = '';
    if (typeof QRCode === 'undefined') return;
    try {
        new QRCode(dom.largeQrcode, {
            text: url,
            width: 360,
            height: 360,
            correctLevel: QRCode.CorrectLevel.H,
        });
    } catch (error) {
        logger.error('QR generation failed:', error);
    }
}

/* ============================================================================
 * Host: lifecycle
 * ============================================================================ */

/**
 * Open a fresh room. Called when user clicks "Umfrage hosten".
 */
async function initHost() {
    showTopView('host-view');
    showOnly(['host-lobby', 'host-composer', 'host-voting', 'host-reveal'], 'host-lobby');

    hostWsReconnectAttempts = 0;
    hostSuppressReconnect = false;

    try {
        hostWs = await connectWithRetry(WS_URL);
    } catch {
        showMessage('Server nicht erreichbar. Bitte versuche es später erneut.', 'error');
        return;
    }

    attachHostWsHandlers(hostWs);
    hostWs.send(JSON.stringify({ type: 'create_room' }));
}

/**
 * Re-attach a previous host session after a page reload. Routes through the
 * unified reconnect logic so transient network failures keep retrying
 * instead of stranding the user. The active session is preserved on
 * failure so the reconnect button stays available for another try.
 * @param {{roomId:string, sessionId:string}} info
 */
function initHostReconnect(info) {
    hostRoomId = info.roomId;
    hostSessionId = info.sessionId;
    showTopView('host-view');
    showOnly(['host-lobby', 'host-composer', 'host-voting', 'host-reveal'], 'host-lobby');
    hostWsReconnectAttempts = 0;
    hostSuppressReconnect = false;
    reconnectHostWs();
}

/**
 * @param {WebSocket} ws
 */
function attachHostWsHandlers(ws) {
    ws.addEventListener('message', (ev) => {
        // Any incoming frame (heartbeat_ack or real game message) counts as
        // server liveness — keeps the watchdog quiet.
        if (hostHeartbeat) hostHeartbeat.lastMsgTime = Date.now();
        let msg;
        try {
            msg = JSON.parse(ev.data);
        } catch {
            return;
        }
        handleHostMessage(msg);
    });

    hostHeartbeat = stopHeartbeat(hostHeartbeat);
    hostHeartbeat = startHeartbeat(ws);

    ws.addEventListener('close', () => {
        // Ignore stale close events from a previous WS instance we've
        // already replaced — otherwise an old socket's close (which can
        // fire seconds after we attached a new one) would tear down the
        // healthy current connection's keepalive and schedule a redundant
        // reconnect on top.
        if (ws !== hostWs) return;
        logger.log('Host WS closed');
        hostHeartbeat = stopHeartbeat(hostHeartbeat);
        reconnectHostWs();
    });

    ws.addEventListener('error', (err) => {
        logger.error('Host WS error:', err);
    });
}

/**
 * Single source of truth for reconnect attempts. Called from the close
 * handler, the `online` event, and the manual reconnect button — guards
 * keep concurrent invocations from racing into multiple sockets, and a
 * failed connect schedules another attempt instead of giving up (which
 * previously stranded users when a transient network blip exhausted
 * connectWithRetry's inner budget on a single outer attempt).
 */
async function reconnectHostWs() {
    if (hostReconnecting) return;
    if (hostSuppressReconnect) return;
    if (!hostRoomId || !hostSessionId) return;
    if (hostWs && hostWs.readyState === WebSocket.OPEN) return;
    if (hostWsReconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
        showMessage('Verbindung zum Server verloren. Bitte lade die Seite neu.', 'error');
        return;
    }
    hostReconnecting = true;
    hostWsReconnectAttempts++;
    showMessage(
        `Verbindung unterbrochen. Reconnect ${hostWsReconnectAttempts}/${MAX_RECONNECT_ATTEMPTS}…`,
        'info'
    );
    let connectedWs;
    try {
        connectedWs = await connectWithRetry(WS_URL);
    } catch {
        hostReconnecting = false;
        if (hostSuppressReconnect) return;
        // Schedule another attempt instead of giving up — this is the
        // fix for "reconnect didn't work". A flaky mobile uplink can
        // exhaust connectWithRetry's inner ~30 s budget on a single outer
        // attempt, but we have plenty of outer budget left.
        const delay = reconnectBackoffMs(hostWsReconnectAttempts);
        setTimeout(reconnectHostWs, delay);
        return;
    }
    hostWs = connectedWs;
    // Clear the in-flight guard before attaching handlers and sending. If
    // `ws.send` throws or a synchronous close event fires mid-setup, the
    // close handler's reconnectHostWs() call would otherwise early-return
    // on the still-true guard and we'd stall.
    hostReconnecting = false;
    attachHostWsHandlers(hostWs);
    hostWs.send(
        JSON.stringify({ type: 'reconnect_host', roomId: hostRoomId, sessionId: hostSessionId })
    );
    // Resend any pending question that wasn't acknowledged across the gap.
    if (hostPendingQuestion) {
        hostWs.send(JSON.stringify(hostPendingQuestion));
        hostPendingQuestion = null;
    }
    // Same for results — an endVote() that fired during the outage left the
    // poll resolved on the host side but never reached players.
    if (hostPendingResults) {
        hostWs.send(JSON.stringify(hostPendingResults));
        hostPendingResults = null;
    }
    // Counter resets to 0 in the 'host_reconnected' message handler.
}

/**
 * @param {object} msg
 */
function handleHostPlayerUpdate(msg) {
    switch (msg.type) {
        case 'player_joined': {
            hostPlayers.set(msg.sessionId, { name: msg.name, isConnected: true });
            // If a poll is in progress and it's voting on people in the room,
            // append the new joiner's name to the options so others can rank
            // them too. Appending (never inserting) keeps previously-submitted
            // indices valid.
            if (hostActivePoll && hostActivePoll.source === 'players' && !hostPollEnding) {
                appendPlayerToActivePoll(msg.name, msg.sessionId);
            }

            break;
        }
        case 'player_reconnected': {
            // Cancel any pending grace-period auto-end: a reconnect could mean
            // the player is back at the voting screen and about to submit.
            if (hostDisconnectGraceTimeout) {
                clearTimeout(hostDisconnectGraceTimeout);
                hostDisconnectGraceTimeout = null;
            }
            const existing = hostPlayers.get(msg.sessionId);
            if (existing) {
                existing.isConnected = true;
                existing.name = msg.name || existing.name;
            } else {
                hostPlayers.set(msg.sessionId, { name: msg.name, isConnected: true });
            }
            // The reconnecting player may not be in the poll's options yet —
            // they could have been disconnected at vote-start, or originally
            // joined during a host outage and thus never propagated to our
            // local poll state. appendPlayerToActivePoll's optionPlayerIds
            // check makes this idempotent if they're already represented.
            if (hostActivePoll && hostActivePoll.source === 'players' && !hostPollEnding) {
                appendPlayerToActivePoll(msg.name, msg.sessionId);
            }

            break;
        }
        case 'player_left': {
            const existing = hostPlayers.get(msg.sessionId);
            if (existing) existing.isConnected = false;

            break;
        }
        // No default
    }
    refreshPlayersUI();
    // Voting view: the count denominator changes too; refresh and check if
    // the disconnect left the remaining connected players all-voted. For
    // `player_left` we defer the auto-end through a grace timer so a
    // reloading voter can rejoin before the vote closes around them.
    if (hostActivePoll) {
        refreshHostVotingProgress();
        if (msg.type === 'player_left') {
            scheduleDisconnectGraceEnd();
        } else {
            maybeAutoEndVote();
        }
    }
}

/**
 * Defer maybeAutoEndVote by DISCONNECT_GRACE_MS so a page-reloading voter
 * isn't kicked out of the vote between their `player_left` and
 * `player_reconnected` events. Idempotent: re-entry while a timer is
 * already pending is a no-op.
 */
function scheduleDisconnectGraceEnd() {
    if (hostDisconnectGraceTimeout) return;
    hostDisconnectGraceTimeout = setTimeout(() => {
        hostDisconnectGraceTimeout = null;
        maybeAutoEndVote();
    }, DISCONNECT_GRACE_MS);
}

/**
 * Append a name to the active `source: 'players'` poll's option list, both
 * locally (so the host's voting view shows it) and via `append_option` to the
 * server (which broadcasts to all connected players so they can rank the new
 * person too). De-duplicates against existing options with a "(2)", "(3)" …
 * suffix the same way the initial snapshot does.
 *
 * Idempotent by sessionId: if the session already has an entry in
 * `hostActivePoll.optionPlayerIds`, this is a no-op. That lets us call it
 * safely from `player_joined`, `player_reconnected` (which can fire
 * repeatedly across a flaky session), and the `host_reconnected` reconcile
 * path — they're all "make sure this player has an option" callers.
 * @param {string} rawName
 * @param {string|null} sessionId — null only for non-player sources, where
 *   this function shouldn't be called anyway.
 */
function appendPlayerToActivePoll(rawName, sessionId) {
    if (!hostActivePoll) return;
    if (
        sessionId &&
        hostActivePoll.optionPlayerIds &&
        hostActivePoll.optionPlayerIds.has(sessionId)
    ) {
        return;
    }
    if (!hostWs || hostWs.readyState !== WebSocket.OPEN) return;

    const taken = new Set(hostActivePoll.realOptions);
    const baseName = (rawName || 'Spieler').trim() || 'Spieler';
    let label = baseName;
    let suffix = 2;
    while (taken.has(label)) {
        label = `${baseName} (${suffix++})`;
    }

    // Mirror the server-side ceiling (MAX_OPTIONS_PER_QUESTION = 250 incl.
    // the meta sentinel at slot 0). Beyond this the server would reject the
    // append_option and the host UI would diverge from reality.
    if (hostActivePoll.options.length >= MAX_REAL_OPTIONS + 1) {
        showMessage(
            `Maximale Anzahl Optionen erreicht — ${label} wird in diesem Durchgang nicht zur Wahl gestellt.`,
            'info'
        );
        return;
    }

    hostActivePoll.realOptions.push(label);
    hostActivePoll.options.push(label);
    if (sessionId && hostActivePoll.optionPlayerIds) {
        hostActivePoll.optionPlayerIds.add(sessionId);
    }
    hostWs.send(JSON.stringify({ type: 'append_option', option: label }));
    renderHostVotingView();
}

/**
 * @param {object} msg
 */
function handleHostAnswer(msg) {
    if (!hostActivePoll) return;
    if (!Array.isArray(msg.answerData)) return;
    hostAnswers.set(msg.sessionId, {
        ranks: [...msg.answerData],
        name: msg.name || (hostPlayers.get(msg.sessionId) || {}).name || 'Spieler',
    });
    refreshHostVotingProgress();
    // If a recent disconnect set a grace timer, let it decide when to end —
    // closing the vote the moment the remaining voters finish would lock a
    // reloading voter out of the poll.
    if (hostDisconnectGraceTimeout) return;
    maybeAutoEndVote();
}

/**
 * Auto-end the vote when every currently-connected player has submitted —
 * there's nothing more to wait for. Idempotent: the hostPollEnding guard
 * prevents double-firing across this, the timer setTimeout, and a manual
 * "Umfrage jetzt beenden" click.
 */
function maybeAutoEndVote() {
    if (!hostActivePoll || hostPollEnding) return;
    const connectedIds = [];
    for (const [sid, p] of hostPlayers.entries()) {
        if (p.isConnected) connectedIds.push(sid);
    }
    if (connectedIds.length === 0) return;
    const allVoted = connectedIds.every((sid) => hostAnswers.has(sid));
    if (!allVoted) return;
    endVote();
}

const HOST_PLAYER_UPDATE_TYPES = new Set(['player_joined', 'player_reconnected', 'player_left']);

/**
 * Host-side message dispatcher.
 * @param {object} msg
 */
function handleHostMessage(msg) {
    if (HOST_PLAYER_UPDATE_TYPES.has(msg.type)) {
        handleHostPlayerUpdate(msg);
        return;
    }
    switch (msg.type) {
        case 'room_created': {
            hostRoomId = msg.roomId;
            hostSessionId = msg.sessionId;
            hostWsReconnectAttempts = 0;
            saveActiveSession('host', hostRoomId, hostSessionId);
            renderHostLobby();
            break;
        }
        case 'host_reconnected': {
            // Reset the budget — a flaky connection that reconnects many
            // times across a long session would otherwise run dry.
            hostWsReconnectAttempts = 0;
            // Reconcile local maps with the server's authoritative state. Any
            // joins, leaves, or submissions that happened during the brief
            // WS gap were never delivered to the host (the server's
            // send-to-host call short-circuits on a closed socket), so the
            // local maps may have stale isConnected flags or missing answers.
            // Without this, the auto-end-when-all-voted check could stall.
            if (Array.isArray(msg.players)) {
                const serverIds = new Set();
                for (const p of msg.players) {
                    if (!p || typeof p.sessionId !== 'string') continue;
                    serverIds.add(p.sessionId);
                    const existing = hostPlayers.get(p.sessionId);
                    hostPlayers.set(p.sessionId, {
                        name: p.name || (existing && existing.name) || 'Spieler',
                        isConnected: !!p.isConnected,
                    });
                    // Restore answers submitted during the host's outage.
                    if (
                        hostActivePoll &&
                        p.hasAnswered &&
                        Array.isArray(p.currentAnswer) &&
                        !hostAnswers.has(p.sessionId)
                    ) {
                        hostAnswers.set(p.sessionId, {
                            ranks: [...p.currentAnswer],
                            name: p.name || 'Spieler',
                        });
                    }
                    // A player who joined during the host's outage was
                    // never appended to the active poll's options.
                    // appendPlayerToActivePoll's optionPlayerIds check
                    // makes this idempotent for sessions we already knew.
                    if (
                        p.isConnected &&
                        hostActivePoll &&
                        hostActivePoll.source === 'players' &&
                        !hostPollEnding
                    ) {
                        appendPlayerToActivePoll(p.name, p.sessionId);
                    }
                }
                // Drop any local entries the server no longer knows about
                // (e.g. a player left while we were briefly disconnected and
                // the room expired their session). Collect first, then delete,
                // so we don't mutate the Map during its own iteration.
                const ghostIds = [];
                for (const sid of hostPlayers.keys()) {
                    if (!serverIds.has(sid)) ghostIds.push(sid);
                }
                for (const sid of ghostIds) hostPlayers.delete(sid);
            }
            renderHostLobby();
            if (hostActivePoll) {
                refreshHostVotingProgress();
                maybeAutoEndVote();
            }
            break;
        }
        case 'room_not_found_try_restore': {
            // Poll sessions are short-lived; we don't attempt full restoration.
            showMessage('Der Raum ist abgelaufen. Bitte starte eine neue Umfrage.', 'error');
            clearActiveSession();
            hostRoomId = null;
            hostSessionId = null;
            showTopView('role-selection');
            break;
        }
        case 'player_answered': {
            handleHostAnswer(msg);
            break;
        }
        case 'quiz_terminated': {
            showMessage('Sitzung wurde beendet.', 'info');
            hardResetHost();
            break;
        }
        case 'error': {
            showMessage(msg.message || 'Unbekannter Fehler', 'error');
            // If the server rejected the start_question we just sent, the
            // host UI has already transitioned into "host-voting" with a
            // running timer — but no players will ever see the question.
            // Roll back to the composer so the host can fix the input.
            if (hostActivePoll && !hostPollEnding) {
                if (hostTimerInterval) {
                    clearInterval(hostTimerInterval);
                    hostTimerInterval = null;
                }
                hostActivePoll = null;
                hostAnswers.clear();
                showOnly(
                    ['host-lobby', 'host-composer', 'host-voting', 'host-reveal'],
                    'host-composer'
                );
            }
            break;
        }
        // player_avatar / music / categories — irrelevant for poll, ignored.
        default: {
            break;
        }
    }
}

/**
 *
 */
function renderHostLobby() {
    // Guard against a stray render before `room_created` lands — a spurious
    // host_reconnected (or any caller that races ahead of room creation)
    // would otherwise throw on the slice.
    if (!hostRoomId) return;
    const displayCode = hostRoomId.slice(0, 2) + ' ' + hostRoomId.slice(2, 4);
    dom.roomIdEl.textContent = displayCode;
    if (dom.modalRoomIdSpan) dom.modalRoomIdSpan.textContent = displayCode;
    const url = buildJoinUrl(hostRoomId);
    const shortUrl = 'bycs.link/wer-hat';
    dom.joinLink.textContent = shortUrl;
    dom.joinLink.href = url;
    if (dom.joinLinkModal) {
        dom.joinLinkModal.textContent = shortUrl;
        dom.joinLinkModal.href = url;
    }
    renderQrCode(url);
    renderLargeQrCode(url);
    refreshPlayersUI();
}

/**
 *
 */
function refreshPlayersUI() {
    const connected = [...hostPlayers.values()].filter((p) => p.isConnected);
    dom.playerCountEl.textContent = String(connected.length);

    dom.playersListEl.innerHTML = '';
    for (const [, p] of hostPlayers) {
        const chip = document.createElement('span');
        chip.className = 'player-chip' + (p.isConnected ? '' : ' disconnected');
        chip.textContent = p.name;
        dom.playersListEl.append(chip);
    }
}

/* ============================================================================
 * Host: composer (live-typed questions)
 * ============================================================================ */

/**
 * Switch from the lobby into the question composer.
 */
function openComposer() {
    showOnly(['host-lobby', 'host-composer', 'host-voting', 'host-reveal'], 'host-composer');
    // Default to player-source on a fresh composer (typical use case is voting
    // on people in the room); preserve choice on subsequent openings.
    renderComposerOptionsList();
    updateFixedSectionVisibility();
    refreshSuggestionForInput();
    dom.composerQuestion.focus();
}

/**
 * Lazily shuffle the suggestion order once per session (Fisher-Yates) and
 * seed the cursor at position 0.
 */
function ensureSuggestionOrder() {
    if (suggestionOrder.length === POLL_SUGGESTIONS.length) return;
    suggestionOrder = POLL_SUGGESTIONS.map((_, i) => i);
    for (let i = suggestionOrder.length - 1; i > 0; i--) {
        const j = Math.floor(Math.random() * (i + 1));
        [suggestionOrder[i], suggestionOrder[j]] = [suggestionOrder[j], suggestionOrder[i]];
    }
    suggestionCursor = 0;
    currentSuggestionIdx = suggestionOrder[0];
}

/**
 * Case-insensitive substring match against title OR question.
 * @param {number|null} idx
 * @param {string} q lowercased filter (empty string = match any)
 * @returns {boolean}
 */
function suggestionMatches(idx, q) {
    if (!q) return true;
    if (idx === null) return false;
    const s = POLL_SUGGESTIONS[idx];
    return s.title.toLowerCase().includes(q) || s.question.toLowerCase().includes(q);
}

/**
 * Returns the filter to apply: the lowercased trimmed input, or '' if no
 * suggestion would match it (in which case the cycle behaves as if the input
 * were empty — any suggestion is fair game).
 * @returns {string}
 */
function effectiveSuggestionFilter() {
    const raw = dom.composerQuestion ? dom.composerQuestion.value : '';
    const q = raw.trim().toLowerCase();
    if (!q) return '';
    const anyMatch = POLL_SUGGESTIONS.some((_, i) => suggestionMatches(i, q));
    return anyMatch ? q : '';
}

/**
 * Walk the shuffled order forward until landing on a suggestion that matches
 * the active filter. When `forceAdvance` is true, the currently-shown
 * suggestion is skipped so the "Anderer Vorschlag" button actually moves.
 * @param {boolean} forceAdvance
 */
function advanceSuggestion(forceAdvance) {
    ensureSuggestionOrder();
    const q = effectiveSuggestionFilter();
    const n = suggestionOrder.length;
    const start = forceAdvance ? suggestionCursor + 1 : suggestionCursor;
    for (let step = 0; step < n; step++) {
        const pos = (start + step) % n;
        const idx = suggestionOrder[pos];
        if (forceAdvance && idx === currentSuggestionIdx) continue;
        if (suggestionMatches(idx, q)) {
            suggestionCursor = pos;
            currentSuggestionIdx = idx;
            return;
        }
    }
}

/**
 * Called on every textarea content change. Keeps the displayed suggestion
 * if it still matches the new filter, otherwise jumps to the next one that
 * does.
 */
function refreshSuggestionForInput() {
    ensureSuggestionOrder();
    const q = effectiveSuggestionFilter();
    if (!suggestionMatches(currentSuggestionIdx, q)) {
        advanceSuggestion(false);
    }
    renderSuggestionBox();
}

/**
 * Render the suggestion box. Hidden only before the shuffled order has been
 * seeded (i.e. before the composer has opened); once seeded the cycle always
 * has a current entry to show.
 */
function renderSuggestionBox() {
    if (!dom.suggestionBox) return;
    if (currentSuggestionIdx === null) {
        dom.suggestionBox.classList.add('hidden');
        return;
    }
    const s = POLL_SUGGESTIONS[currentSuggestionIdx];
    dom.suggestionBox.classList.remove('hidden');
    dom.suggestionTitle.textContent = s.title;
    dom.suggestionText.textContent = s.question;
}

/**
 * Fill the composer with the currently-shown suggestion. Always sets
 * source=players because every built-in suggestion is a "Wer …" question.
 */
function applyCurrentSuggestion() {
    if (currentSuggestionIdx === null) return;
    const s = POLL_SUGGESTIONS[currentSuggestionIdx];
    dom.composerQuestion.value = s.question;
    for (const r of dom.sourceRadios) {
        r.checked = r.value === 'players';
    }
    updateFixedSectionVisibility();
    dom.composerQuestion.focus();
}

/**
 * Walk to the next matching suggestion in the shuffled order. No-op when
 * only one suggestion matches the active filter.
 */
function cycleSuggestion() {
    advanceSuggestion(true);
    renderSuggestionBox();
}

/**
 *
 */
function updateFixedSectionVisibility() {
    const sourceVal = currentSourceValue();
    dom.fixedOptionsSection.classList.toggle('hidden', sourceVal !== 'fixed');
}

/**
 * @returns {'players'|'fixed'}
 */
function currentSourceValue() {
    for (const r of dom.sourceRadios) {
        if (r.checked) return r.value === 'fixed' ? 'fixed' : 'players';
    }
    return 'players';
}

/**
 *
 */
function renderComposerOptionsList() {
    dom.composerOptionsList.innerHTML = '';
    for (const [idx, val] of composerFixedOptions.entries()) {
        const row = document.createElement('div');
        row.className = 'composer-option-row';
        const input = document.createElement('input');
        input.type = 'text';
        input.placeholder = `Option ${idx + 1}`;
        input.value = val;
        input.maxLength = 400;
        input.addEventListener('input', () => {
            composerFixedOptions[idx] = input.value;
        });
        row.append(input);
        const rm = document.createElement('button');
        rm.type = 'button';
        rm.className = 'composer-option-remove';
        rm.textContent = '×';
        rm.title = 'Option entfernen';
        rm.addEventListener('click', () => {
            composerFixedOptions.splice(idx, 1);
            if (composerFixedOptions.length < 2) {
                while (composerFixedOptions.length < 2) composerFixedOptions.push('');
            }
            renderComposerOptionsList();
        });
        row.append(rm);
        dom.composerOptionsList.append(row);
    }
}

/**
 *
 */
function addComposerOption() {
    if (composerFixedOptions.length >= MAX_REAL_OPTIONS) {
        showMessage(`Maximal ${MAX_REAL_OPTIONS} Optionen.`, 'info');
        return;
    }
    composerFixedOptions.push('');
    renderComposerOptionsList();
}

/**
 * Build a unique, display-friendly snapshot of currently-connected players for
 * source: "players". Duplicate names get " (2)" / " (3)" suffixes so the host
 * can disambiguate when computing Borda. Each entry also carries its
 * sessionId so the caller can track which sessions are already represented
 * in the poll's option list (used to keep `appendPlayerToActivePoll`
 * idempotent across player_joined / player_reconnected / host_reconnected
 * reconcile).
 * @returns {Array<{label:string, sessionId:string}>}
 */
function snapshotPlayerOptions() {
    const taken = new Map();
    const result = [];
    for (const [sid, p] of hostPlayers.entries()) {
        if (!p.isConnected) continue;
        const baseName = (p.name || 'Spieler').trim() || 'Spieler';
        const seen = taken.get(baseName) || 0;
        const label = seen === 0 ? baseName : `${baseName} (${seen + 1})`;
        taken.set(baseName, seen + 1);
        result.push({ label, sessionId: sid });
        if (result.length >= MAX_REAL_OPTIONS) break;
    }
    return result;
}

/**
 * @param {'players'|'fixed'} source
 * @returns {Array<{label:string, sessionId:string|null}>|null} entries, or
 *   null on validation failure. Fixed-source entries carry a null sessionId.
 */
function collectRealOptions(source) {
    if (source === 'players') {
        const entries = snapshotPlayerOptions();
        if (entries.length < 2) {
            showMessage('Mindestens 2 verbundene Spieler nötig, um über sie abzustimmen.', 'error');
            return null;
        }
        return entries;
    }
    const labels = composerFixedOptions
        .map((s) => (s || '').trim())
        .filter((s) => s.length > 0)
        .slice(0, MAX_REAL_OPTIONS);
    if (labels.length < 2) {
        showMessage('Mindestens 2 Optionen sind nötig.', 'error');
        return null;
    }
    return labels.map((label) => ({ label, sessionId: null }));
}

/**
 * Pull and clamp picksPerVoter / revealCount / duration from the composer.
 * @param {number} optionCount
 * @returns {{picks:number, revealCount:number|'all', duration:number}}
 */
function readComposerNumericInputs(optionCount) {
    let picks = Number.parseInt(dom.composerPicks.value, 10);
    if (!Number.isFinite(picks) || picks < 1) picks = 1;
    picks = Math.min(picks, MAX_PICKS_PER_VOTER, optionCount);

    let revealCount;
    if (dom.composerRevealAll.checked) {
        revealCount = 'all';
    } else {
        revealCount = Number.parseInt(dom.composerReveal.value, 10);
        if (!Number.isFinite(revealCount) || revealCount < 1) revealCount = 3;
        revealCount = Math.min(revealCount, optionCount);
    }

    let duration = Number.parseInt(dom.composerDuration.value, 10);
    if (!Number.isFinite(duration)) duration = 45;
    duration = Math.max(MIN_DURATION_SEC, Math.min(MAX_DURATION_SEC, duration));

    return { picks, revealCount, duration };
}

/**
 * Validate composer inputs, build start_question payload, send it, and
 * transition the host into the live-voting view.
 */
function startVote() {
    const question = (dom.composerQuestion.value || '').trim();
    if (!question) {
        showMessage('Bitte gib eine Frage ein.', 'error');
        dom.composerQuestion.focus();
        return;
    }
    if (question.length > 3000) {
        showMessage('Frage ist zu lang (max. 3000 Zeichen).', 'error');
        return;
    }

    const source = currentSourceValue();
    const entries = collectRealOptions(source);
    if (!entries) return;
    const realOptions = entries.map((e) => e.label);

    const { picks, revealCount, duration } = readComposerNumericInputs(realOptions.length);

    const meta = { picksPerVoter: picks, revealCount, source };
    const options = [encodeMeta(meta), ...realOptions];

    // Per-option validation matches what the server will enforce — fail fast
    // here so the user gets a useful message instead of a silent drop.
    if (options.some((opt) => opt.length > 500)) {
        showMessage('Eine Option ist zu lang (max. 500 Zeichen).', 'error');
        return;
    }
    // Mirror the server's options ceiling so an oversized snapshot (e.g. a
    // very large class voting on themselves) is caught here with a clear
    // message instead of getting silently rejected upstream.
    if (options.length > MAX_REAL_OPTIONS + 1) {
        showMessage(
            `Zu viele Optionen (${options.length - 1}). Maximum: ${MAX_REAL_OPTIONS}.`,
            'error'
        );
        return;
    }

    const payload = {
        type: 'start_question',
        question,
        options,
        index: 0,
        total: 1,
        duration,
    };

    if (!hostWs || hostWs.readyState !== WebSocket.OPEN) {
        showMessage('Keine Verbindung. Versuche erneut zu verbinden…', 'error');
        hostPendingQuestion = payload;
        return;
    }

    // For source='players', track which sessions are represented in the
    // option list. Used by `appendPlayerToActivePoll` to stay idempotent
    // across player_joined / player_reconnected / host_reconnected reconcile,
    // and to detect reconnecting players who weren't in the original
    // snapshot (e.g. they were disconnected when the poll started, or
    // joined while the host's WS was briefly offline).
    const optionPlayerIds = new Set();
    for (const e of entries) {
        if (e.sessionId) optionPlayerIds.add(e.sessionId);
    }

    hostActivePoll = {
        question,
        options, // full array including meta sentinel at [0]
        realOptions,
        optionPlayerIds,
        picksPerVoter: picks,
        revealCount,
        source,
        duration,
    };
    hostPollEnding = false;
    hostAnswers.clear();
    // A grace timer from a prior round must not bleed into this one.
    if (hostDisconnectGraceTimeout) {
        clearTimeout(hostDisconnectGraceTimeout);
        hostDisconnectGraceTimeout = null;
    }

    hostWs.send(JSON.stringify(payload));

    showOnly(['host-lobby', 'host-composer', 'host-voting', 'host-reveal'], 'host-voting');
    renderHostVotingView();
    startHostTimer(duration);
}

/**
 *
 */
function renderHostVotingView() {
    if (!hostActivePoll) return;
    dom.hostQuestionDisplay.textContent = hostActivePoll.question;
    // No live tally during voting — would bias late voters and undermine
    // anonymity. The host sees only the submission count and the options
    // (without counts), and gets the full Borda ranking on reveal.
    dom.hostLiveOptions.innerHTML = '';
    for (const opt of hostActivePoll.realOptions) {
        const li = document.createElement('li');
        const name = document.createElement('span');
        name.textContent = opt;
        li.append(name);
        dom.hostLiveOptions.append(li);
    }
    refreshHostVotingProgress();
}

/**
 *
 */
function refreshHostVotingProgress() {
    if (!hostActivePoll) return;
    const connected = [...hostPlayers.values()].filter((p) => p.isConnected).length;
    const submitted = hostAnswers.size;
    dom.hostAnswersCount.textContent = String(submitted);
    dom.hostTotalPlayers.textContent = String(connected);
}

/**
 * @param {number} seconds
 */
function startHostTimer(seconds) {
    if (hostTimerInterval) clearInterval(hostTimerInterval);
    dom.hostTimerBar.style.width = '100%';
    const totalMs = seconds * 1000;
    const start = Date.now();
    hostTimerInterval = setInterval(() => {
        const remaining = Math.max(0, totalMs - (Date.now() - start));
        dom.hostTimerBar.style.width = `${(remaining / totalMs) * 100}%`;
        if (remaining <= 0) {
            clearInterval(hostTimerInterval);
            hostTimerInterval = null;
            // Grace period for last-second submissions to arrive. Bumped to
            // 5 s because the question broadcast can be delayed several
            // seconds on slow mobile networks — a 2 s grace was dropping
            // votes from players whose phones got the question late and
            // submitted right at the edge of the host's countdown.
            // endVote()'s own guard makes this a no-op if the vote was
            // already auto-ended by the last submission landing.
            setTimeout(endVote, 5000);
        }
    }, 100);
}

/**
 * Stop the vote, compute Borda results, send `send_results` so players see
 * the same podium, then move the host into the reveal view.
 */
function endVote() {
    if (!hostActivePoll || hostPollEnding) return;
    hostPollEnding = true;
    if (hostTimerInterval) {
        clearInterval(hostTimerInterval);
        hostTimerInterval = null;
    }
    if (hostDisconnectGraceTimeout) {
        clearTimeout(hostDisconnectGraceTimeout);
        hostDisconnectGraceTimeout = null;
    }

    const podium = computeBordaPodium(hostActivePoll);

    // Pack the podium into the `leaderboard` field — it's the only whitelisted
    // slot in send_results that can carry [{name, score}] pairs through the
    // server's relay. The server will replay this to reconnecting players via
    // its `final` snapshot, so we set isFinal: true on every poll result.
    const leaderboard = podium.map((p) => ({ name: p.label, score: p.points }));

    const resultsPayload = {
        type: 'send_results',
        correct: [],
        isFinal: true,
        leaderboard,
    };
    if (hostWs && hostWs.readyState === WebSocket.OPEN) {
        try {
            hostWs.send(JSON.stringify(resultsPayload));
        } catch {
            hostPendingResults = resultsPayload;
            showMessage('Keine Verbindung — Ergebnisse werden nach Reconnect gesendet.', 'info');
        }
    } else {
        hostPendingResults = resultsPayload;
        showMessage('Keine Verbindung — Ergebnisse werden nach Reconnect gesendet.', 'info');
    }

    renderHostReveal(podium);
    showOnly(['host-lobby', 'host-composer', 'host-voting', 'host-reveal'], 'host-reveal');
}

/**
 * Borda count over the active poll's submitted ballots. Each ballot is a
 * ranked list of raw option indices; we map back to real options (index-1)
 * and award `picksPerVoter - rank` points to each pick from rank 0 to
 * min(ballotLength, picksPerVoter) - 1. Duplicates within a single ballot
 * (rare; player UI prevents them) are de-duped — only the first occurrence
 * of a given pick scores.
 * @param {object} poll
 * @returns {Array<{label:string, points:number, mentions:number, rank:number}>}
 */
function computeBordaPodium(poll) {
    const realOpts = poll.realOptions;
    const N = poll.picksPerVoter;
    const scores = Array.from({ length: realOpts.length }).fill(0);
    const mentions = Array.from({ length: realOpts.length }).fill(0);

    for (const ans of hostAnswers.values()) {
        const seen = new Set();
        const ranks = ans.ranks.slice(0, N);
        for (const [rank, rawIdx] of ranks.entries()) {
            const realIdx = rawIdx - 1;
            if (realIdx < 0 || realIdx >= realOpts.length) continue;
            if (seen.has(realIdx)) continue;
            seen.add(realIdx);
            // Borda weight: rank-1 = N points, rank-N = 1 point.
            scores[realIdx] += N - rank;
            mentions[realIdx]++;
        }
    }

    const ranked = realOpts.map((label, i) => ({
        label,
        points: scores[i],
        mentions: mentions[i],
    }));
    // Sort by points desc, breaking remaining order ties alphabetically. Mentions
    // alone aren't a tiebreaker for the *rank* — entries with the same Borda
    // points share a rank even if mention counts differ.
    ranked.sort((a, b) => {
        if (b.points !== a.points) return b.points - a.points;
        return a.label.localeCompare(b.label, 'de');
    });
    assignCompetitionRanks(ranked);

    // Tie-respecting cutoff: include every entry whose competition rank is
    // <= revealCount. For revealCount=3 with [10,10,8] the result is [1,1,3]
    // (3 entries); with [10,8,8,8] it's [1,2,2,2] (all 4 entries, since the
    // tied trio all carry rank 2 ≤ 3).
    if (poll.revealCount === 'all') return ranked;
    return ranked.filter((e) => e.rank <= poll.revealCount);
}

/**
 * Walk a points-sorted array and assign competition-style ranks (1, 1, 3, 4, 4, 6).
 * Mutates each entry to add a `rank` field.
 * @param {Array<{points:number, rank?:number}>} sorted
 */
function assignCompetitionRanks(sorted) {
    let currentRank = 0;
    let lastPoints = null;
    for (const [i, entry] of sorted.entries()) {
        if (lastPoints === null || entry.points !== lastPoints) {
            currentRank = i + 1;
            lastPoints = entry.points;
        }
        entry.rank = currentRank;
    }
}

/**
 * @param {Array<{label:string, points:number, mentions:number, rank:number}>} podium
 */
function renderHostReveal(podium) {
    if (!hostActivePoll) return;
    dom.hostRevealQuestion.textContent = hostActivePoll.question;
    dom.hostPodiumList.innerHTML = '';
    // When the config asks for a single result, hide the redundant "1." prefix —
    // there's no second place to number against. Ties still show all winners,
    // just without a leading number on any of them.
    dom.hostPodiumList.classList.toggle('single-result', hostActivePoll.revealCount === 1);
    for (const entry of podium) {
        dom.hostPodiumList.append(
            buildPodiumItem(
                entry.rank,
                entry.label,
                `${entry.points} Pkt · ${entry.mentions}× genannt`
            )
        );
    }

    const totalBallots = hostAnswers.size;
    const connected = [...hostPlayers.values()].filter((p) => p.isConnected).length;
    const revealTxt = hostActivePoll.revealCount === 'all' ? 'alle' : hostActivePoll.revealCount;
    const metaTxt =
        `${totalBallots} von ${connected} Stimmen · ` +
        `Auswahlen pro Person: ${hostActivePoll.picksPerVoter} · ` +
        `Ergebnisse: ${revealTxt} · ` +
        `Quelle: ${hostActivePoll.source === 'players' ? 'Spielernamen' : 'eigene Optionen'}`;
    dom.hostRevealMeta.textContent = metaTxt;
}

/**
 * From reveal → back to composer for the next question.
 */
function nextQuestion() {
    hostActivePoll = null;
    hostPollEnding = false;
    hostAnswers.clear();
    // Clear the just-used question text so the next suggestion can shine
    // through cleanly. picksPerVoter / revealCount / duration stay so the
    // host can iterate quickly with the same parameters.
    dom.composerQuestion.value = '';
    openComposer();
}

/**
 * Host terminates the session entirely.
 */
async function endSession() {
    const ok = await uiConfirm('Sitzung wirklich beenden?', {
        confirmText: 'Beenden',
        danger: true,
    });
    if (!ok) return;
    hostSuppressReconnect = true;
    if (hostWs && hostWs.readyState === WebSocket.OPEN) {
        hostWs.send(JSON.stringify({ type: 'terminate' }));
    }
    hardResetHost();
}

/**
 *
 */
function hardResetHost() {
    hostSuppressReconnect = true;
    if (hostTimerInterval) {
        clearInterval(hostTimerInterval);
        hostTimerInterval = null;
    }
    hostHeartbeat = stopHeartbeat(hostHeartbeat);
    if (hostWs) {
        try {
            hostWs.close();
        } catch {
            /* ignore */
        }
    }
    hostWs = null;
    hostRoomId = null;
    hostSessionId = null;
    hostActivePoll = null;
    hostPollEnding = false;
    hostPendingQuestion = null;
    hostPendingResults = null;
    hostPlayers.clear();
    hostAnswers.clear();
    suggestionOrder = [];
    suggestionCursor = 0;
    currentSuggestionIdx = null;
    clearActiveSession();
    showTopView('role-selection');
    refreshReconnectButtons();
}

/* ============================================================================
 * Player: lifecycle
 * ============================================================================ */

/**
 * Open the join view (used when the user clicks "Umfrage beitreten").
 */
function openPlayerJoin() {
    showTopView('player-view');
    showOnly(
        ['join-form', 'player-waiting', 'player-vote', 'player-submitted', 'player-reveal'],
        'join-form'
    );
    // Auto-fill room code from ?room= if present.
    const params = new URLSearchParams(globalThis.location.search);
    const roomParam = (params.get('room') || '').toUpperCase();
    if (roomParam && dom.roomCodeInput) {
        dom.roomCodeInput.value = roomParam;
    }
    dom.playerNameInput.focus();
}

/**
 * Player submits the join form.
 */
async function submitJoin() {
    const code = (dom.roomCodeInput.value || '').replaceAll(/\s/g, '').toUpperCase();
    const name = sanitizePlayerName(dom.playerNameInput.value || '');
    if (code.length < 3) {
        showMessage('Bitte gib einen gültigen Raum-Code ein.', 'error');
        return;
    }
    if (!name) {
        showMessage('Bitte gib einen Namen ein.', 'error');
        return;
    }
    playerRoomCode = code;
    playerName = name;
    playerWsReconnectAttempts = 0;
    playerSuppressReconnect = false;

    try {
        playerWs = await connectWithRetry(WS_URL);
    } catch {
        showMessage('Server nicht erreichbar.', 'error');
        return;
    }
    attachPlayerWsHandlers(playerWs);
    playerWs.send(
        JSON.stringify({
            type: 'join',
            roomCode: playerRoomCode,
            playerName: playerName,
        })
    );
}

/**
 * Reconnect a player after a page reload using saved session. Routes through
 * the unified reconnect logic so brief outages don't strand the user.
 * @param {{roomId:string, sessionId:string, name?:string}} info
 */
function initPlayerReconnect(info) {
    playerRoomCode = info.roomId;
    playerSessionId = info.sessionId;
    playerName = info.name || 'Spieler';
    showTopView('player-view');
    showOnly(
        ['join-form', 'player-waiting', 'player-vote', 'player-submitted', 'player-reveal'],
        'player-waiting'
    );
    dom.playerWaitingStatus.textContent = 'Wiederverbindung läuft…';
    // Suppress page-level back arrow during the brief reconnect window so
    // an accidental tap doesn't pull the player out before the WS lands.
    document.body.classList.add('player-in-game');
    playerWsReconnectAttempts = 0;
    playerSuppressReconnect = false;
    reconnectPlayerWs();
}

/**
 * @param {WebSocket} ws
 */
function attachPlayerWsHandlers(ws) {
    ws.addEventListener('message', (ev) => {
        if (playerHeartbeat) playerHeartbeat.lastMsgTime = Date.now();
        let msg;
        try {
            msg = JSON.parse(ev.data);
        } catch {
            return;
        }
        handlePlayerMessage(msg);
    });

    playerHeartbeat = stopHeartbeat(playerHeartbeat);
    playerHeartbeat = startHeartbeat(ws);

    ws.addEventListener('close', () => {
        // Ignore stale close events from a previous WS instance we've
        // already replaced — see the matching comment on the host side.
        if (ws !== playerWs) return;
        logger.log('Player WS closed');
        playerHeartbeat = stopHeartbeat(playerHeartbeat);
        reconnectPlayerWs();
    });

    ws.addEventListener('error', (err) => {
        logger.error('Player WS error:', err);
    });
}

/**
 * Single source of truth for player reconnect attempts. Called from the
 * close handler, the `online` event, and the manual reconnect button.
 * Guards keep concurrent invocations from racing; a failed connect
 * schedules another attempt instead of giving up.
 */
async function reconnectPlayerWs() {
    if (playerReconnecting) return;
    if (playerSuppressReconnect) return;
    if (!playerRoomCode || !playerSessionId) return;
    if (playerWs && playerWs.readyState === WebSocket.OPEN) return;
    if (playerWsReconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
        showMessage('Verbindung zur Umfrage verloren. Bitte lade die Seite neu.', 'error');
        return;
    }
    playerReconnecting = true;
    playerWsReconnectAttempts++;
    showMessage(
        `Verbindung unterbrochen. Reconnect ${playerWsReconnectAttempts}/${MAX_RECONNECT_ATTEMPTS}…`,
        'info'
    );
    let connectedWs;
    try {
        connectedWs = await connectWithRetry(WS_URL);
    } catch {
        playerReconnecting = false;
        if (playerSuppressReconnect) return;
        // Schedule another attempt instead of giving up.
        const delay = reconnectBackoffMs(playerWsReconnectAttempts);
        setTimeout(reconnectPlayerWs, delay);
        return;
    }
    playerWs = connectedWs;
    attachPlayerWsHandlers(playerWs);
    playerReconnecting = false;
    playerWs.send(
        JSON.stringify({
            type: 'join',
            roomCode: playerRoomCode,
            playerName: playerName,
            sessionId: playerSessionId,
        })
    );
    // Counter resets to 0 in the 'joined' message handler.
}

/**
 * Player-side message dispatcher.
 * @param {object} msg
 */
function handlePlayerMessage(msg) {
    switch (msg.type) {
        case 'joined': {
            playerSessionId = msg.sessionId;
            // Reset the reconnect budget — a flaky mobile connection that
            // reconnects many times across a long poll would otherwise burn
            // through MAX_RECONNECT_ATTEMPTS and stop trying.
            playerWsReconnectAttempts = 0;
            if (typeof msg.playerName === 'string') playerName = msg.playerName;
            saveActiveSession('player', playerRoomCode, playerSessionId, { name: playerName });

            // If the server replayed an active question via the join response,
            // the next message will be the question payload itself; we just
            // need to land on the waiting view in the meantime.
            showOnly(
                ['join-form', 'player-waiting', 'player-vote', 'player-submitted', 'player-reveal'],
                'player-waiting'
            );
            dom.playerWaitingStatus.textContent = msg.isReconnect
                ? 'Wiederverbunden — warte auf nächste Umfrage.'
                : 'Du bist drin — wir warten auf die nächste Umfrage.';
            dom.playerNameDisplay.textContent = `Eingeloggt als ${playerName}`;
            // Suppress page-level navigation while the player is in the room.
            document.body.classList.add('player-in-game');
            break;
        }
        case 'question': {
            onQuestionReceived(msg);
            break;
        }
        case 'option_appended': {
            onOptionAppended(msg);
            break;
        }
        case 'result': {
            onResultReceived(msg);
            break;
        }
        case 'quiz_terminated': {
            showMessage('Der Host hat die Sitzung beendet.', 'info');
            hardResetPlayer();
            break;
        }
        case 'error': {
            showMessage(msg.message || 'Unbekannter Fehler', 'error');
            // Join failure → kick back to role selection.
            if (
                msg.message === 'Raum nicht gefunden.' ||
                msg.message === 'Raum ist voll (max. 240 Spieler).' ||
                msg.message === 'Raum nicht mehr aktiv.'
            ) {
                hardResetPlayer();
            }
            break;
        }
        // Lobby music / categories / etc. — ignored.
        default: {
            break;
        }
    }
}

/**
 * @param {object} msg
 */
function onQuestionReceived(msg) {
    const options = Array.isArray(msg.options) ? msg.options : [];
    if (options.length < 2) {
        showMessage('Ungültige Umfrage-Daten empfangen.', 'error');
        return;
    }
    const meta = decodeMeta(options[0]);
    if (!meta) {
        // This room is running a quiz, not a poll. Refuse loudly rather than
        // silently render a malformed picker.
        showMessage('Dieser Raum ist keine Umfrage. Bitte tritt über quiz.html bei.', 'error');
        return;
    }
    playerCurrentMeta = meta;
    playerOptionIndexBase = 1;
    playerDisplayOptions = options.slice(1);
    playerCurrentQuestion = msg.question || '';
    playerCurrentQuestionKey = `${playerRoomCode}|${msg.index || 0}|${playerCurrentQuestion.slice(0, 64)}`;

    if (msg.alreadySubmitted) {
        playerHasSubmitted = true;
        playerSelectedRanks = loadLastPicks(playerRoomCode, playerCurrentQuestionKey) || [];
        renderSubmittedView();
        return;
    }

    playerHasSubmitted = false;
    playerSelectedRanks = [];
    renderVoteView();
    const remaining =
        typeof msg.remaining === 'number' ? Math.max(0, msg.remaining) : Number(msg.duration) || 45;
    startPlayerTimer(remaining);
}

/**
 * Server broadcast that the host added a new option to the active poll
 * (typically: a late-joiner's name in a `source: 'players'` poll). Append
 * to our local display list and re-render the rank picker if we're still
 * voting. Previously-submitted ballots aren't affected — their indices
 * point at the same options as before since we only append, never insert.
 * @param {object} msg
 */
function onOptionAppended(msg) {
    if (typeof msg.option !== 'string' || !msg.option) return;
    if (!Array.isArray(playerDisplayOptions)) return;
    playerDisplayOptions.push(msg.option);
    // Re-render only if the player is currently in the voting view.
    // Submitted view: their picks are already in; new option is irrelevant.
    // Reveal view: too late, results are computed.
    if (dom.playerVote && !dom.playerVote.classList.contains('hidden')) {
        renderRankPicker();
    }
}

/**
 *
 */
function renderVoteView() {
    showOnly(
        ['join-form', 'player-waiting', 'player-vote', 'player-submitted', 'player-reveal'],
        'player-vote'
    );
    dom.playerQuestionText.textContent = playerCurrentQuestion;
    const picks = playerCurrentMeta.picksPerVoter;
    const cap = Math.min(picks, playerDisplayOptions.length);
    dom.playerVoteHint.textContent =
        cap === 1
            ? 'Wähle deinen Favoriten.'
            : `Wähle bis zu ${cap} in Reihenfolge deiner Präferenz (1 = höchste).`;
    renderRankPicker();
}

/**
 *
 */
function renderRankPicker() {
    // Ranked picks list (top): shows current 1., 2., 3., ... selection. Tap to
    // remove from the ranking. When the host configured a single pick, the
    // "1." prefix is redundant — `single-pick` hides it via CSS.
    dom.rankList.innerHTML = '';
    dom.rankList.classList.toggle(
        'single-pick',
        playerCurrentMeta && playerCurrentMeta.picksPerVoter === 1
    );
    if (playerSelectedRanks.length === 0) {
        if (dom.rankListEmpty) dom.rankListEmpty.hidden = false;
    } else {
        if (dom.rankListEmpty) dom.rankListEmpty.hidden = true;
        for (const [rank, rawIdx] of playerSelectedRanks.entries()) {
            const li = document.createElement('li');
            const realIdx = rawIdx - playerOptionIndexBase;
            li.textContent = playerDisplayOptions[realIdx] || '?';
            li.title = 'Tippen, um aus der Rangfolge zu entfernen';
            li.addEventListener('click', () => {
                playerSelectedRanks.splice(rank, 1);
                renderRankPicker();
            });
            dom.rankList.append(li);
        }
    }

    // Option chips (bottom): tap to append to the ranking. Disabled when
    // already picked or when picksPerVoter cap is reached.
    dom.rankOptions.innerHTML = '';
    const cap = Math.min(playerCurrentMeta.picksPerVoter, playerDisplayOptions.length);
    const picked = new Set(playerSelectedRanks);
    for (const [i, label] of playerDisplayOptions.entries()) {
        const rawIdx = i + playerOptionIndexBase;
        const btn = document.createElement('button');
        btn.type = 'button';
        btn.textContent = label;
        if (picked.has(rawIdx)) {
            btn.classList.add('picked');
            btn.disabled = true;
        } else if (playerSelectedRanks.length >= cap) {
            btn.disabled = true;
            btn.title = `Du hast bereits ${cap} ausgewählt — entferne erst eine Wahl.`;
        }
        btn.addEventListener('click', () => {
            if (playerSelectedRanks.length >= cap) return;
            if (picked.has(rawIdx)) return;
            playerSelectedRanks.push(rawIdx);
            renderRankPicker();
        });
        dom.rankOptions.append(btn);
    }

    dom.submitVoteBtn.disabled = playerSelectedRanks.length === 0;
}

/**
 *
 */
function submitVote() {
    if (playerHasSubmitted) return;
    if (!playerWs || playerWs.readyState !== WebSocket.OPEN) {
        showMessage('Keine Verbindung. Versuche es erneut.', 'error');
        return;
    }
    if (playerSelectedRanks.length === 0) {
        showMessage('Wähle mindestens eine Option.', 'error');
        return;
    }
    playerWs.send(
        JSON.stringify({
            type: 'submit_answer',
            answerData: [...playerSelectedRanks],
        })
    );
    playerHasSubmitted = true;
    saveLastPicks(playerRoomCode, playerCurrentQuestionKey, [...playerSelectedRanks]);
    renderSubmittedView();
    stopPlayerTimer();
}

/**
 *
 */
function renderSubmittedView() {
    showOnly(
        ['join-form', 'player-waiting', 'player-vote', 'player-submitted', 'player-reveal'],
        'player-submitted'
    );
    renderPicksEcho(dom.submittedPicksEcho, playerSelectedRanks);
}

/**
 * @param {object} msg
 */
function onResultReceived(msg) {
    stopPlayerTimer();
    showOnly(
        ['join-form', 'player-waiting', 'player-vote', 'player-submitted', 'player-reveal'],
        'player-reveal'
    );
    dom.playerRevealQuestion.textContent = playerCurrentQuestion;
    dom.playerPodiumList.innerHTML = '';
    const leaderboard = Array.isArray(msg.leaderboard) ? msg.leaderboard : [];
    // The server's whitelist drops anything beyond {name, score} on each entry,
    // so the host can't ship pre-computed ranks. Recompute them client-side
    // from the score values — the leaderboard arrives already sorted desc.
    const withPoints = leaderboard.map((entry) => ({
        label: entry.name || '?',
        points: Number.isFinite(Number(entry.score)) ? Number(entry.score) : 0,
    }));
    assignCompetitionRanks(withPoints);
    const singleResult = playerCurrentMeta && playerCurrentMeta.revealCount === 1;
    dom.playerPodiumList.classList.toggle('single-result', !!singleResult);
    for (const entry of withPoints) {
        const scoreTxt = `${entry.points} Pkt`;
        dom.playerPodiumList.append(buildPodiumItem(entry.rank, entry.label, scoreTxt));
    }
    renderPicksEcho(dom.playerPicksEcho, playerSelectedRanks);
    dom.playerRevealStatus.textContent = 'Warten auf nächste Umfrage…';
}

/**
 * Build a single <li> for a podium list. Used by both the host's full reveal
 * and the player's reveal so the visual treatment stays in lockstep.
 * @param {number} rank — 1-based competition rank.
 * @param {string} label
 * @param {string} scoreText
 * @returns {HTMLLIElement}
 */
function buildPodiumItem(rank, label, scoreText) {
    const li = document.createElement('li');
    li.className = `rank-${rank}`;
    const rankEl = document.createElement('span');
    rankEl.className = 'podium-rank';
    rankEl.textContent = `${rank}.`;
    const name = document.createElement('span');
    name.className = 'podium-name';
    name.textContent = label;
    const score = document.createElement('span');
    score.className = 'podium-score';
    score.textContent = scoreText;
    li.append(rankEl, name, score);
    return li;
}

/**
 * @param {HTMLElement} target
 * @param {number[]} picks
 */
function renderPicksEcho(target, picks) {
    if (!target) return;
    target.innerHTML = '';
    if (!picks || picks.length === 0) {
        const p = document.createElement('p');
        p.className = 'player-hint';
        p.textContent = 'Du hast keine Stimme abgegeben.';
        target.append(p);
        return;
    }
    const heading = document.createElement('h4');
    heading.textContent = 'Deine Wahl:';
    target.append(heading);
    const ol = document.createElement('ol');
    for (const rawIdx of picks) {
        const realIdx = rawIdx - playerOptionIndexBase;
        const label = playerDisplayOptions[realIdx] || '?';
        const li = document.createElement('li');
        li.textContent = label;
        ol.append(li);
    }
    target.append(ol);
}

/**
 * @param {number} seconds
 */
function startPlayerTimer(seconds) {
    if (playerTimerInterval) clearInterval(playerTimerInterval);
    if (!dom.playerTimerBar) return;
    dom.playerTimerBar.style.width = '100%';
    const totalMs = Math.max(1, seconds * 1000);
    const start = Date.now();
    playerTimerInterval = setInterval(() => {
        const remaining = Math.max(0, totalMs - (Date.now() - start));
        dom.playerTimerBar.style.width = `${(remaining / totalMs) * 100}%`;
        if (remaining <= 0) {
            clearInterval(playerTimerInterval);
            playerTimerInterval = null;
            // Auto-submit whatever the player has ranked (could be empty). The
            // host's grace period gives this a couple of seconds to arrive.
            if (!playerHasSubmitted && playerSelectedRanks.length > 0) {
                submitVote();
            }
        }
    }, 100);
}

/**
 *
 */
function stopPlayerTimer() {
    if (playerTimerInterval) {
        clearInterval(playerTimerInterval);
        playerTimerInterval = null;
    }
    if (dom.playerTimerBar) dom.playerTimerBar.style.width = '0%';
}

/**
 *
 */
function hardResetPlayer() {
    playerSuppressReconnect = true;
    stopPlayerTimer();
    playerHeartbeat = stopHeartbeat(playerHeartbeat);
    if (playerWs) {
        try {
            playerWs.close();
        } catch {
            /* ignore */
        }
    }
    playerWs = null;
    playerRoomCode = null;
    playerSessionId = null;
    playerName = null;
    playerCurrentMeta = null;
    playerDisplayOptions = [];
    playerSelectedRanks = [];
    playerHasSubmitted = false;
    // Restore page-level navigation (back arrow) now that the player has
    // explicitly left the room.
    document.body.classList.remove('player-in-game');
    clearActiveSession();
    clearLastPicks();
    showTopView('role-selection');
    refreshReconnectButtons();
}

/* ============================================================================
 * Reconnect-button visibility
 * ============================================================================ */

/**
 * Show "Reconnect" CTAs in role-selection when an unfinished session exists.
 */
function refreshReconnectButtons() {
    const sess = loadActiveSession();
    if (!sess) {
        dom.reconnectHostBtn.classList.add('hidden');
        dom.reconnectPlayerBtn.classList.add('hidden');
        return;
    }
    if (sess.role === 'host') {
        dom.reconnectHostBtn.classList.remove('hidden');
        dom.reconnectPlayerBtn.classList.add('hidden');
    } else if (sess.role === 'player') {
        dom.reconnectPlayerBtn.classList.remove('hidden');
        dom.reconnectHostBtn.classList.add('hidden');
    }
}

/* ============================================================================
 * Boot
 * ============================================================================ */

document.addEventListener('DOMContentLoaded', () => {
    collectDom();

    dom.hostBtn.addEventListener('click', initHost);
    dom.playerBtn.addEventListener('click', openPlayerJoin);
    dom.reconnectHostBtn.addEventListener('click', () => {
        const sess = loadActiveSession();
        if (sess && sess.role === 'host') initHostReconnect(sess);
    });
    dom.reconnectPlayerBtn.addEventListener('click', () => {
        const sess = loadActiveSession();
        if (sess && sess.role === 'player') initPlayerReconnect(sess);
    });

    dom.showComposerBtn.addEventListener('click', openComposer);
    for (const r of dom.sourceRadios) {
        r.addEventListener('change', updateFixedSectionVisibility);
    }
    dom.addOptionBtn.addEventListener('click', addComposerOption);
    if (dom.applySuggestionBtn) {
        dom.applySuggestionBtn.addEventListener('click', applyCurrentSuggestion);
    }
    if (dom.cycleSuggestionBtn) {
        dom.cycleSuggestionBtn.addEventListener('click', cycleSuggestion);
    }
    if (dom.composerQuestion) {
        dom.composerQuestion.addEventListener('input', refreshSuggestionForInput);
    }
    dom.composerRevealAll.addEventListener('change', () => {
        dom.composerReveal.disabled = dom.composerRevealAll.checked;
    });
    dom.startVoteBtn.addEventListener('click', startVote);
    dom.backToLobbyBtn.addEventListener('click', () => {
        showOnly(['host-lobby', 'host-composer', 'host-voting', 'host-reveal'], 'host-lobby');
    });
    dom.endVoteBtn.addEventListener('click', endVote);
    dom.nextQuestionBtn.addEventListener('click', nextQuestion);
    dom.endSessionBtn.addEventListener('click', endSession);

    dom.joinBtn.addEventListener('click', submitJoin);
    dom.roomCodeInput.addEventListener('keydown', (e) => {
        if (e.key === 'Enter') submitJoin();
    });
    dom.playerNameInput.addEventListener('keydown', (e) => {
        if (e.key === 'Enter') submitJoin();
    });
    dom.submitVoteBtn.addEventListener('click', submitVote);

    // QR modal: clicking the small QR enlarges it for the room.
    if (dom.qrcodeEl) {
        dom.qrcodeEl.addEventListener('click', () => {
            if (!hostRoomId) return;
            dom.qrModalOverlay.classList.remove('hidden');
        });
    }
    if (dom.qrModalClose) {
        dom.qrModalClose.addEventListener('click', () => {
            dom.qrModalOverlay.classList.add('hidden');
        });
    }
    if (dom.qrModalOverlay) {
        dom.qrModalOverlay.addEventListener('click', (e) => {
            if (e.target === dom.qrModalOverlay) {
                dom.qrModalOverlay.classList.add('hidden');
            }
        });
    }

    renderComposerOptionsList();
    refreshReconnectButtons();

    // Auto-reconnect on page reload. Priority:
    //   1. ?room=XXXX pointing at a *different* room than the saved player
    //      session → respect the URL. A shared invite is an explicit
    //      "join this room" intent; silently reconnecting to the old one
    //      would override the user's choice.
    //   2. Saved player session → silent reconnect. Players reload mid-game
    //      and just need to be back where they were.
    //   3. Saved host session → stay on role-selection with the reconnect
    //      CTA highlighted. The host has to make an explicit choice between
    //      resuming the existing poll and starting a new one, so we don't
    //      auto-reconnect them — refreshReconnectButtons() above already
    //      surfaced the button.
    //   4. ?room=XXXX URL param (no conflicting session) → player join form.
    //   5. Fall through to role-selection.
    const initialParams = new URLSearchParams(globalThis.location.search);
    const bootSession = loadActiveSession();
    const roomFromUrl = (initialParams.get('room') || '').toUpperCase();
    const bootRoomId = bootSession ? (bootSession.roomId || '').toUpperCase() : '';
    const urlOverridesSession =
        roomFromUrl && bootSession && bootSession.role === 'player' && roomFromUrl !== bootRoomId;

    if (urlOverridesSession) {
        clearActiveSession();
        refreshReconnectButtons();
        openPlayerJoin();
    } else if (bootSession && bootSession.role === 'player') {
        initPlayerReconnect(bootSession);
    } else if (!bootSession && roomFromUrl) {
        openPlayerJoin();
    }

    // When a backgrounded tab comes back to foreground, setInterval-based
    // keepalives may have been throttled (browsers commonly clamp to 1/min
    // in hidden tabs) — long enough for a proxy idle timeout to bite.
    // Two things to do on each foreground transition:
    //  1. Fire an immediate keepalive on still-open sockets to refresh the
    //     path before the 25 s tick.
    //  2. Actively probe any non-OPEN socket: mobile networks sometimes drop
    //     the TCP connection without ever firing a `close` event, so the
    //     auto-reconnect chain may not have kicked in. Trigger it ourselves.
    document.addEventListener('visibilitychange', () => {
        if (document.visibilityState !== 'visible') return;
        for (const ws of [hostWs, playerWs]) {
            if (ws && ws.readyState === WebSocket.OPEN) {
                try {
                    ws.send(HEARTBEAT_PAYLOAD);
                } catch {
                    /* swallow — close handler will reconnect if the path is dead */
                }
            }
        }
        if (
            playerRoomCode &&
            playerSessionId &&
            !playerSuppressReconnect &&
            !playerReconnecting &&
            (!playerWs || playerWs.readyState !== WebSocket.OPEN)
        ) {
            reconnectPlayerWs();
        }
        if (
            hostRoomId &&
            hostSessionId &&
            !hostSuppressReconnect &&
            !hostReconnecting &&
            (!hostWs || hostWs.readyState !== WebSocket.OPEN)
        ) {
            reconnectHostWs();
        }
    });

    // Mobile networks frequently drop the WebSocket without the browser
    // noticing; the close event can take a full heartbeat cycle to fire.
    // When the OS reports the network coming back, kick off a reconnect
    // immediately instead of waiting for the next backoff tick. The
    // in-flight guards inside reconnectPlayerWs/reconnectHostWs make this
    // safe to call even if a reconnect is already running.
    globalThis.addEventListener('online', () => {
        if (
            playerRoomCode &&
            playerSessionId &&
            !playerSuppressReconnect &&
            !playerReconnecting &&
            (!playerWs || playerWs.readyState !== WebSocket.OPEN)
        ) {
            // Restored network gets a fresh attempt budget.
            playerWsReconnectAttempts = 0;
            reconnectPlayerWs();
        }
        if (
            hostRoomId &&
            hostSessionId &&
            !hostSuppressReconnect &&
            !hostReconnecting &&
            (!hostWs || hostWs.readyState !== WebSocket.OPEN)
        ) {
            hostWsReconnectAttempts = 0;
            reconnectHostWs();
        }
    });
});