@visns-studio/visns-components 6.25.0 → 6.26.0

package/src/components/callQueue/CallQueuePop.jsx

@@ -13,17 +13,34 @@ import { toast } from 'react-toastify';
 
 import CustomFetch from '../Fetch';
 import styles from '../styles/CallQueuePop.module.scss';
+import { subscriptionMonitor } from '../sms/smsLiveState';
+
+// Instrumentation only: every write below records what the plumbing did, and
+// nothing the pop renders or decides ever reads back out of this store.
+import {
+    appendCallPopLog,
+    installCallPopStatusHook,
+    noteCallPopConnectionState,
+    noteCallPopEvent,
+    updateCallPopStatus,
+} from './callPopStatus';
 
 // Pure helpers live in a plain .js sibling so `node --test` can import them;
 // re-exported below so this file's public surface is unchanged.
 import {
     CLIENT_DETAIL_FIELDS,
     FALLBACK_QUEUE_NAME,
+    KIND_DIRECT,
     MONITOR_PERMISSION,
+    applyMissed,
+    applyRinging,
+    callBadgeLabel,
+    calleeLabel,
     clientDetails,
     defaultClientTasksUrl,
     defaultClientUrl,
     defaultTaskUrl,
+    directRingingLine,
     formatAuPhone,
     formatDueDate,
     formatElapsed,
@@ -31,13 +48,21 @@ import {
     hasMonitorPermission,
     normaliseCall,
     normalisePickupCodes,
+    pickupKeyFor,
+    reconcileSnapshot,
+    resolvePickupCode,
     toCallWorkspaceId,
     toLocalDigits,
 } from './callQueueHelpers';
 
 export {
     CLIENT_DETAIL_FIELDS,
+    applyMissed,
+    applyRinging,
+    callBadgeLabel,
+    calleeLabel,
     clientDetails,
+    directRingingLine,
     formatAuPhone,
     formatDueDate,
     formatElapsed,
@@ -45,6 +70,9 @@ export {
     hasMonitorPermission,
     normaliseCall,
     normalisePickupCodes,
+    pickupKeyFor,
+    reconcileSnapshot,
+    resolvePickupCode,
     toCallWorkspaceId,
     toLocalDigits,
 };
@@ -66,9 +94,28 @@ export {
  *     the host app has a broadcaster configured)
  * With neither present the component renders nothing and logs nothing.
  *
- * Pickup codes arrive as the snapshot's `pickup_codes` map, keyed by Zoom call
- * queue id. A queue with no code still pops — its card just has no Pick up
- * button, because there is no dial string to offer.
+ * Direct calls pop too: a call ringing one staff member's own extension (or
+ * transferred to it) arrives with `kind: 'direct'`, no queue at all, and the
+ * name of whoever it is ringing. Everyone watching sees it, which is the whole
+ * point — a colleague's phone ringing out is exactly the call somebody else
+ * should be picking up.
+ *
+ * Pickup codes arrive as the snapshot's `pickup_codes` map, keyed by each
+ * call's `pickup_key` — the Zoom call queue id for a queue call, the literal
+ * 'direct' for a direct one (whose interception goes through a call pickup
+ * GROUP, one code for the lot). A call with no code still pops; its card just
+ * has no Pick up button, because there is no dial string to offer.
+ *
+ * A call rings several devices at once, so one leg being declined settles
+ * nothing: `.queue.missed` marks the card and starts a `missedGraceMs` timer
+ * instead of removing it, and a further `.queue.ringing` for the same call
+ * cancels that timer. Only `.queue.answered`/`.queue.ended` take a card away
+ * outright.
+ *
+ * The snapshot is a catch-up mechanism, not just a first paint: it runs again
+ * whenever the socket reconnects and whenever a hidden tab is looked at again,
+ * and reconciles both ways, so a call that started or ended while this browser
+ * was deaf is not stuck on (or missing from) the screen.
  *
  * The caller -> client match arrives already resolved, as each call's `client`
  * block (computed once by the Zoom webhook, server-side). This component never
@@ -88,6 +135,11 @@ export {
  *   window.callPopClear()  -> clear the stack (in all tabs)
  * Demo calls bypass the permission gate and never hit a real endpoint.
  *
+ * The permission gate is optional: `monitorPermission={null}` pops for every
+ * signed-in user instead of only those holding a named permission. A host that
+ * does that must open its broadcast channel authorisation the same way — the
+ * pop cannot show what the socket refuses to deliver.
+ *
  * Library note: this is the portable version of the CRM's original component.
  * Every host-specific decision it hard-coded — the Echo instance, the channel
  * name, the endpoints, the routes it links to, whether Pick up is live — is now
@@ -104,6 +156,33 @@ const EVENT_RINGING = '.queue.ringing';
 const EVENT_ANSWERED = '.queue.answered';
 const EVENT_ENDED = '.queue.ended';
 
+/**
+ * One ringing leg was declined or timed out. NOT the same as `.queue.ended`:
+ * a call rings several devices at once, so a declined leg says nothing about
+ * the others — the card is only marked, and a grace timer decides.
+ */
+const EVENT_MISSED = '.queue.missed';
+
+/**
+ * The diagnostics panel's round-trip probe. It carries no call and pops
+ * nothing — it is broadcast on the same channel purely so a browser can prove
+ * the socket is delivering (see CallQueueDiagnostics).
+ */
+const EVENT_PING = '.queue.diagnostic-ping';
+
+/** Terse console breadcrumbs, so a support call can read them out. */
+const trace = (message, detail) => {
+    try {
+        if (detail === undefined) {
+            console.info(`[call-pop] ${message}`);
+        } else {
+            console.info(`[call-pop] ${message}`, detail);
+        }
+    } catch (error) {
+        // A console that refuses to log is not worth failing over.
+    }
+};
+
 /** Default BroadcastChannel used to keep every open tab's stack in step. */
 const SYNC_CHANNEL = 'throughlife-call-queue-pop';
 
@@ -113,6 +192,21 @@ const DEFAULT_CHANNEL = 'call-queue-monitor';
 /** How long the exit animation runs before the card is dropped from state. */
 const EXIT_MS = 220;
 
+/**
+ * How long a card survives a `.queue.missed` before it is taken as gone. Long
+ * enough for the next leg's `.queue.ringing` to arrive and cancel it, short
+ * enough that a call nobody took stops sitting on screen. Override with the
+ * `missedGraceMs` prop.
+ */
+const DEFAULT_MISSED_GRACE_MS = 10000;
+
+/**
+ * Minimum gap between snapshot refreshes, for every reason except mount. A
+ * flapping socket and a user cycling between tabs both ask repeatedly; one
+ * request per five seconds is plenty to catch up with.
+ */
+const SNAPSHOT_MIN_GAP_MS = 5000;
+
 /** Title shown on alternate ticks while a call rings in a hidden tab. */
 const FLASH_TITLE = '📞 Incoming call…';
 
@@ -193,6 +287,7 @@ const CallQueuePop = ({
     callWorkspacePath = '/call/{number}',
     syncChannelName = SYNC_CHANNEL,
     demoEnabled = true,
+    missedGraceMs = DEFAULT_MISSED_GRACE_MS,
 }) => {
     const [calls, setCalls] = useState([]);
     const [now, setNow] = useState(() => Date.now());
@@ -212,6 +307,32 @@ const CallQueuePop = ({
     // against an unmounted tree.
     const exitTimers = useRef([]);
 
+    // Grace timers started by `.queue.missed`, keyed by callId, so a later
+    // `.queue.ringing` for the same call can cancel exactly one of them.
+    const missedTimers = useRef(new Map());
+
+    // The stack, readable from a callback that must not be re-created every
+    // time it changes (the snapshot refresh, which reconciles against it).
+    const callsRef = useRef(calls);
+    callsRef.current = calls;
+
+    // callIds this browser has settled by hand (Dismiss, Pick up, or a
+    // cross-tab remove). The server still lists them as ringing, so without
+    // this a refresh would put the card straight back.
+    const dismissedIds = useRef(new Set());
+
+    // Snapshot refresh bookkeeping: when the last one went out, and the single
+    // trailing request parked behind the minimum gap.
+    const lastSnapshotAt = useRef(0);
+    const pendingSnapshot = useRef(null);
+
+    // Has the socket left `connected` since the last snapshot? Only then is
+    // coming back a reconnect worth catching up from.
+    const sawDisconnect = useRef(false);
+
+    // Cleared on unmount, so an in-flight request's callback knows to stop.
+    const mounted = useRef(true);
+
     // callIds whose drill-down request has already gone out — the endpoint is
     // hit once per call however often the chip is toggled.
     const taskFetched = useRef(new Set());
@@ -250,6 +371,10 @@ const CallQueuePop = ({
         [endpoints]
     );
 
+    // `monitorPermission={null}` means the deployment gates on being signed in
+    // and nothing else — every member of staff sees every call. The prop is
+    // passed straight through, because only `undefined` picks up the default.
+    const gateIsOpen = monitorPermission === null || monitorPermission === '';
     const canMonitor = hasMonitorPermission(userProfile, monitorPermission);
     const hasDemoCalls = calls.some((call) => call.isDemo);
     const hasRinging = calls.some((call) => !call.leaving);
@@ -264,42 +389,105 @@ const CallQueuePop = ({
         return trialBadge ? TRIAL_BADGE_TEXT : '';
     }, [trialBadge]);
 
-    /** Add a call, ignoring duplicates of a callId already on screen. */
-    const addCall = useCallback((call) => {
-        if (!call) {
-            return;
+    /** Cancel one call's grace timer, if it has one. Always safe to call. */
+    const clearMissedTimer = useCallback((callId) => {
+        const id = String(callId);
+        const timer = missedTimers.current.get(id);
+
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            missedTimers.current.delete(id);
         }
+    }, []);
 
-        setCalls((previous) => {
-            if (previous.some((item) => item.callId === call.callId)) {
-                return previous;
+    /**
+     * Add a call, or clear the missed mark of one already on screen — a second
+     * `.queue.ringing` for a call whose first leg was declined proves it is
+     * still live (see applyRinging).
+     */
+    const addCall = useCallback(
+        (call) => {
+            if (!call) {
+                return;
             }
 
-            return [...previous, call];
-        });
-    }, []);
+            clearMissedTimer(call.callId);
+            setCalls((previous) => applyRinging(previous, call));
+        },
+        [clearMissedTimer]
+    );
 
     /** Animate a card out, then drop it from state. */
-    const removeCall = useCallback((callId) => {
-        setCalls((previous) =>
-            previous.map((call) =>
-                call.callId === String(callId)
-                    ? { ...call, leaving: true }
-                    : call
-            )
-        );
+    const removeCall = useCallback(
+        (callId) => {
+            // Whatever settles the call settles its grace timer too, so a
+            // dismissed or answered card can never be removed twice.
+            clearMissedTimer(callId);
 
-        const timer = setTimeout(() => {
             setCalls((previous) =>
-                previous.filter((call) => call.callId !== String(callId))
+                previous.map((call) =>
+                    call.callId === String(callId)
+                        ? { ...call, leaving: true }
+                        : call
+                )
             );
-        }, EXIT_MS);
 
-        exitTimers.current.push(timer);
-    }, []);
+            const timer = setTimeout(() => {
+                setCalls((previous) =>
+                    previous.filter((call) => call.callId !== String(callId))
+                );
+            }, EXIT_MS);
+
+            exitTimers.current.push(timer);
+        },
+        [clearMissedTimer]
+    );
+
+    /**
+     * A ringing leg was declined or timed out. The call may still be ringing on
+     * someone else's device, so the card is marked and given `missedGraceMs` to
+     * prove it: a `.queue.ringing` inside that window cancels the timer, and
+     * nothing arriving lets it remove the card the same way `.queue.ended`
+     * would.
+     */
+    const markMissed = useCallback(
+        (callId) => {
+            const id = String(callId ?? '');
+
+            if (id === '') {
+                return;
+            }
+
+            // Already counting down, or never on screen here in the first
+            // place: either way there is nothing to start.
+            if (missedTimers.current.has(id)) {
+                return;
+            }
+
+            if (
+                !callsRef.current.some(
+                    (call) => call.callId === id && !call.leaving
+                )
+            ) {
+                return;
+            }
+
+            setCalls((previous) => applyMissed(previous, id, Date.now()));
+
+            const timer = setTimeout(() => {
+                missedTimers.current.delete(id);
+                removeCall(id);
+            }, missedGraceMs);
+
+            missedTimers.current.set(id, timer);
+        },
+        [missedGraceMs, removeCall]
+    );
 
     /** Drop the whole stack (no exit animation — used by clear). */
     const clearCalls = useCallback(() => {
+        missedTimers.current.forEach((timer) => clearTimeout(timer));
+        missedTimers.current.clear();
         setCalls([]);
     }, []);
 
@@ -359,6 +547,9 @@ const CallQueuePop = ({
      */
     const dismissCall = useCallback(
         (callId) => {
+            // Remembered so a later snapshot refresh does not re-add the card:
+            // the server has no idea this browser settled the call.
+            dismissedIds.current.add(String(callId));
             removeCall(callId);
             broadcastSync({ type: 'remove', callId: String(callId) });
         },
@@ -450,7 +641,11 @@ const CallQueuePop = ({
         }
 
         /** Add a demo call here and mirror it into every other open tab. */
-        const pushDemo = (call) => {
+        const pushDemo = (payload) => {
+            // Through the same normaliser as a real call, so a demo card has
+            // every field the reconcile and grace logic reads.
+            const call = normaliseCall(payload);
+
             addDemoPickupCode(call);
             addCall(call);
             broadcastSync({ type: 'add', call });
@@ -593,6 +788,9 @@ const CallQueuePop = ({
 
                 if (message.type === 'remove') {
                     if (message.callId) {
+                        // Another tab settled it by hand, so this tab must not
+                        // let a refresh bring it back either.
+                        dismissedIds.current.add(String(message.callId));
                         removeCall(message.callId);
                     }
 
@@ -640,74 +838,265 @@ const CallQueuePop = ({
         syncChannelName,
     ]);
 
-    /** Snapshot of what is already ringing when the page loads. */
+    /**
+     * Diagnostics wiring. Three passive observers of state the pop already
+     * keeps: the permission verdict, how many cards are on screen, and the
+     * `window.callPopStatus()` console hook that sits beside the demo hooks.
+     */
     useEffect(() => {
-        if (!canMonitor) {
-            return undefined;
+        updateCallPopStatus({ canMonitor });
+
+        // Only worth saying when a permission was actually asked for: with the
+        // gate open a signed-out user is the only way to fail, and "no
+        // permission" would be a misleading thing to read in the log.
+        if (!canMonitor && !gateIsOpen) {
+            appendCallPopLog(
+                'User does not hold the call queue monitor permission.',
+                'warn'
+            );
         }
+    }, [canMonitor, gateIsOpen]);
 
-        let cancelled = false;
-
-        try {
-            const request = CustomFetch(
-                liveUrl,
-                'GET',
-                {},
-                function (result) {
-                    if (cancelled) {
-                        return;
-                    }
+    useEffect(() => {
+        updateCallPopStatus({
+            visibleCalls: calls.filter((call) => !call.leaving).length,
+        });
+    }, [calls]);
 
-                    if (
-                        typeof result?.channel === 'string' &&
-                        result.channel !== ''
-                    ) {
-                        setEchoChannel(result.channel);
-                    }
+    useEffect(() => installCallPopStatusHook(), []);
 
-                    if (result?.pickup_codes ?? result?.pickupCodes) {
-                        const codes = normalisePickupCodes(
-                            result.pickup_codes ?? result.pickupCodes
+    /**
+     * Fetch `/ajax/call-queue/live` and reconcile the stack against it.
+     *
+     * This is the pop's catch-up path, not just its first paint: the same
+     * request runs on mount, after the socket comes back, and when a hidden tab
+     * is looked at again — every moment a `.queue.*` event could have been
+     * missed. What comes back is authoritative in both directions (see
+     * reconcileSnapshot for the two exceptions), so a call that started while
+     * the socket was down appears, and one that ended while it was down goes.
+     *
+     * @param {string} reason 'mount' | 'reconnect' | 'visible' — logged, so the
+     *   diagnostics panel says why each refresh happened.
+     */
+    const refreshSnapshot = useCallback(
+        (reason) => {
+            try {
+                const request = CustomFetch(
+                    liveUrl,
+                    'GET',
+                    {},
+                    function (result) {
+                        if (!mounted.current) {
+                            return;
+                        }
+
+                        if (
+                            typeof result?.channel === 'string' &&
+                            result.channel !== ''
+                        ) {
+                            setEchoChannel(result.channel);
+                        }
+
+                        if (result?.pickup_codes ?? result?.pickupCodes) {
+                            const codes = normalisePickupCodes(
+                                result.pickup_codes ?? result.pickupCodes
+                            );
+
+                            // Merged, not replaced: an injected demo code
+                            // already in the map must survive the snapshot
+                            // landing.
+                            setPickupCodes((previous) => ({
+                                ...previous,
+                                ...codes,
+                            }));
+                        }
+
+                        const payload = Array.isArray(result)
+                            ? result
+                            : result?.calls;
+
+                        if (!Array.isArray(payload)) {
+                            // A response with no `calls` array says nothing
+                            // about what is ringing, so nothing is reconciled
+                            // away on the strength of it.
+                            updateCallPopStatus({
+                                snapshotAt: new Date().toISOString(),
+                                snapshotError: null,
+                                snapshotCalls: 0,
+                            });
+                            trace(`snapshot (${reason}) ok — no calls block`);
+
+                            return;
+                        }
+
+                        const incoming = payload
+                            .map((item) => normaliseCall(item))
+                            .filter(Boolean);
+
+                        const { add, remove } = reconcileSnapshot(
+                            callsRef.current,
+                            incoming,
+                            Date.now(),
+                            { skipIds: dismissedIds.current }
                         );
 
-                        // Merged, not replaced: an injected demo code already
-                        // in the map must survive the snapshot landing.
-                        setPickupCodes((previous) => ({
-                            ...previous,
-                            ...codes,
-                        }));
+                        add.forEach((call) => addCall(call));
+                        remove.forEach((callId) => removeCall(callId));
+
+                        // A dismissal only has to outlive the call it
+                        // silenced: once the server stops listing it, forget
+                        // it, so the set cannot grow all day.
+                        if (dismissedIds.current.size > 0) {
+                            const listed = new Set(
+                                incoming.map((call) => call.callId)
+                            );
+
+                            dismissedIds.current.forEach((callId) => {
+                                if (!listed.has(callId)) {
+                                    dismissedIds.current.delete(callId);
+                                }
+                            });
+                        }
+
+                        appendCallPopLog(
+                            `Snapshot (${reason}) — ${incoming.length} ringing, ` +
+                                `${add.length} added, ${remove.length} removed`,
+                            'info',
+                            {
+                                snapshotAt: new Date().toISOString(),
+                                snapshotError: null,
+                                snapshotCalls: incoming.length,
+                            }
+                        );
+                        trace(
+                            `snapshot (${reason}) ok — ${incoming.length} call(s) ringing`
+                        );
+                    },
+                    function (message) {
+                        // Absence of the endpoint is expected pre-backend.
+                        if (!mounted.current) {
+                            return;
+                        }
+
+                        const failure =
+                            typeof message === 'string' && message !== ''
+                                ? message
+                                : 'request failed';
+
+                        appendCallPopLog(
+                            `Snapshot (${reason}) failed: ${failure}`,
+                            'error',
+                            {
+                                snapshotAt: new Date().toISOString(),
+                                snapshotError: failure,
+                            }
+                        );
+                        trace(`snapshot (${reason}) failed — ${failure}`);
                     }
+                );
+
+                if (request && typeof request.catch === 'function') {
+                    request.catch(() => {});
+                }
+            } catch (error) {
+                // Silent by design — but no longer invisible.
+                appendCallPopLog(
+                    `Snapshot request could not be sent: ${error?.message ?? error}`,
+                    'error',
+                    { snapshotError: String(error?.message ?? error) }
+                );
+            }
+        },
+        [addCall, liveUrl, removeCall]
+    );
 
-                    const payload = Array.isArray(result)
-                        ? result
-                        : result?.calls;
+    /**
+     * Ask for a refresh, at most one per `SNAPSHOT_MIN_GAP_MS` — a socket that
+     * flaps and a user cycling through tabs both ask far more often than the
+     * server needs to be asked. A throttled request is not dropped: one
+     * trailing refresh is parked until the gap expires, so the last reason to
+     * catch up always does.
+     *
+     * 'mount' bypasses the gap: it is the first paint, and there is nothing to
+     * have throttled it.
+     */
+    const requestSnapshot = useCallback(
+        (reason) => {
+            const send = () => {
+                lastSnapshotAt.current = Date.now();
+                sawDisconnect.current = false;
+                refreshSnapshot(reason);
+            };
 
-                    if (!Array.isArray(payload)) {
-                        return;
-                    }
+            if (reason === 'mount') {
+                send();
 
-                    payload.forEach((item) => ingestCall(item));
-                },
-                function () {
-                    // Absence of the endpoint is expected pre-backend.
-                }
-            );
+                return;
+            }
+
+            const wait =
+                SNAPSHOT_MIN_GAP_MS - (Date.now() - lastSnapshotAt.current);
+
+            if (wait <= 0) {
+                send();
 
-            if (request && typeof request.catch === 'function') {
-                request.catch(() => {});
+                return;
             }
-        } catch (error) {
-            // Silent by design.
+
+            if (pendingSnapshot.current !== null) {
+                return;
+            }
+
+            pendingSnapshot.current = setTimeout(() => {
+                pendingSnapshot.current = null;
+                send();
+            }, wait);
+        },
+        [refreshSnapshot]
+    );
+
+    /** Snapshot of what is already ringing when the page loads. */
+    useEffect(() => {
+        if (!canMonitor) {
+            return undefined;
         }
 
-        return () => {
-            cancelled = true;
+        requestSnapshot('mount');
+
+        return undefined;
+    }, [canMonitor, requestSnapshot]);
+
+    /**
+     * Catch up when a backgrounded tab is looked at again. A tab that has been
+     * hidden for an hour may have had its socket quietly reaped; this is the
+     * cheap way to find out, and it costs one request at most every five
+     * seconds however often the user switches back and forth.
+     */
+    useEffect(() => {
+        if (!canMonitor || typeof document === 'undefined') {
+            return undefined;
+        }
+
+        const onVisibilityChange = () => {
+            if (document.visibilityState === 'visible') {
+                requestSnapshot('visible');
+            }
         };
-    }, [canMonitor, ingestCall, liveUrl]);
+
+        document.addEventListener('visibilitychange', onVisibilityChange);
+
+        return () =>
+            document.removeEventListener(
+                'visibilitychange',
+                onVisibilityChange
+            );
+    }, [canMonitor, requestSnapshot]);
 
     /** Live updates over Laravel Echo, when the broadcaster is wired up. */
     useEffect(() => {
         if (!canMonitor || !activeChannel || typeof window === 'undefined') {
+            updateCallPopStatus({ channel: activeChannel ?? null });
+
             return undefined;
         }
 
@@ -718,24 +1107,54 @@ const CallQueuePop = ({
         const instance = typeof source === 'function' ? source() : source;
 
         if (!instance) {
+            appendCallPopLog(
+                'No Echo instance: the app has no broadcaster configured, ' +
+                    'so nothing will ever arrive live.',
+                'error',
+                {
+                    channel: activeChannel,
+                    echoAvailable: false,
+                    subscribed: false,
+                }
+            );
+            trace('no Echo instance — live updates are off');
+
             return undefined;
         }
 
+        appendCallPopLog(`Subscribing to ${activeChannel}`, 'info', {
+            channel: activeChannel,
+            echoAvailable: true,
+            subscribed: false,
+            subscriptionError: null,
+        });
+        trace(`subscribing to private-${activeChannel}`);
+
         let subscription = null;
+        let stopMonitoring = () => {};
+        let unbindState = () => {};
 
         try {
             // Until /broadcasting/auth knows this channel the subscription just
             // fails auth — pusher-js logs a warning, nothing of ours throws.
+            // That silence is exactly what the monitor below breaks.
             subscription = instance.private(activeChannel);
 
             subscription.listen(EVENT_RINGING, (event) => {
-                ingestCall(event?.call ?? event);
+                const call = event?.call ?? event;
+
+                noteCallPopEvent(EVENT_RINGING);
+                trace('event .queue.ringing', call?.callId ?? call?.call_id);
+                ingestCall(call);
             });
 
             subscription.listen(EVENT_ANSWERED, (event) => {
                 const callId =
                     event?.callId ?? event?.call_id ?? event?.call?.callId;
 
+                noteCallPopEvent(EVENT_ANSWERED);
+                trace('event .queue.answered', callId);
+
                 if (callId) {
                     removeCall(callId);
                 }
@@ -745,28 +1164,187 @@ const CallQueuePop = ({
                 const callId =
                     event?.callId ?? event?.call_id ?? event?.call?.callId;
 
+                noteCallPopEvent(EVENT_ENDED);
+                trace('event .queue.ended', callId);
+
                 if (callId) {
                     removeCall(callId);
                 }
             });
+
+            // One leg said no. The call is not over — it may be ringing on
+            // three other devices — so this starts a grace period rather than
+            // removing anything.
+            subscription.listen(EVENT_MISSED, (event) => {
+                const callId =
+                    event?.callId ?? event?.call_id ?? event?.call?.callId;
+
+                noteCallPopEvent(EVENT_MISSED);
+                trace('event .queue.missed', callId);
+
+                if (callId) {
+                    markMissed(callId);
+                }
+            });
+
+            // The diagnostics panel's round-trip probe. It settles nothing and
+            // pops nothing — it only proves this browser is being delivered to.
+            subscription.listen(EVENT_PING, (event) => {
+                const nonce = event?.nonce ?? event?.id ?? null;
+
+                noteCallPopEvent(EVENT_PING, {
+                    lastPing: {
+                        nonce: nonce === null ? null : String(nonce),
+                        receivedAt: new Date().toISOString(),
+                    },
+                });
+                trace('event .queue.diagnostic-ping', nonce);
+            });
+
+            stopMonitoring = subscriptionMonitor(subscription, {
+                onSuccess: () => {
+                    appendCallPopLog(`Subscribed to ${activeChannel}`, 'info', {
+                        subscribed: true,
+                        subscribedAt: new Date().toISOString(),
+                        subscriptionError: null,
+                    });
+                    trace(`subscribed to private-${activeChannel}`);
+                },
+                onError: (payload) => {
+                    // pusher-js hands over `{type, error, status}`; Reverb and
+                    // Laravel's auth endpoint both put the HTTP code on
+                    // `status`, which is the number that says WHY (403 = the
+                    // channel authorisation said no, 404 = no auth route).
+                    const httpStatus =
+                        payload?.status ??
+                        payload?.error?.status ??
+                        payload?.data?.code ??
+                        null;
+                    const message =
+                        payload?.error?.message ??
+                        payload?.error?.data?.message ??
+                        payload?.message ??
+                        'channel authorisation failed';
+
+                    appendCallPopLog(
+                        `Subscription refused (${httpStatus ?? 'no status'}): ${message}`,
+                        'error',
+                        {
+                            subscribed: false,
+                            subscriptionError: {
+                                status: httpStatus,
+                                message: String(message),
+                            },
+                        }
+                    );
+                    trace(
+                        `subscription error on private-${activeChannel}`,
+                        httpStatus ?? message
+                    );
+                },
+            });
         } catch (error) {
             subscription = null;
+            appendCallPopLog(
+                `Could not subscribe to ${activeChannel}: ${error?.message ?? error}`,
+                'error',
+                {
+                    subscribed: false,
+                    subscriptionError: {
+                        status: null,
+                        message: String(error?.message ?? error),
+                    },
+                }
+            );
+            trace('subscribe threw', error?.message ?? error);
+        }
+
+        // The socket underneath the channel. Every property access is guarded:
+        // the Echo instance need not be pusher-backed at all, and a diagnostics
+        // read must never be what breaks the pop.
+        try {
+            const connection = instance.connector?.pusher?.connection;
+
+            if (connection && typeof connection.bind === 'function') {
+                const onStateChange = (states) => {
+                    const current = states?.current ?? states;
+
+                    noteCallPopConnectionState(current ?? null);
+                    trace(`socket ${current}`);
+
+                    // Coming back is the interesting half. Everything that
+                    // rang while the socket was away was broadcast to nobody,
+                    // so the snapshot is the only way to learn about it — but
+                    // only when the socket actually went away, otherwise every
+                    // ordinary connecting -> connected on load would refetch.
+                    if (current === 'connected') {
+                        if (sawDisconnect.current) {
+                            requestSnapshot('reconnect');
+                        }
+
+                        return;
+                    }
+
+                    if (current) {
+                        sawDisconnect.current = true;
+                    }
+                };
+
+                connection.bind('state_change', onStateChange);
+                noteCallPopConnectionState(connection.state ?? null);
+
+                // A socket that is already down at subscribe time counts as a
+                // departure, so its eventual `connected` catches up too.
+                if (connection.state && connection.state !== 'connected') {
+                    sawDisconnect.current = true;
+                }
+
+                unbindState = () => {
+                    try {
+                        connection.unbind?.('state_change', onStateChange);
+                    } catch (error) {
+                        // Already gone.
+                    }
+                };
+            }
+        } catch (error) {
+            // No reachable connection object: the channel confirmation alone
+            // says whether this browser is live, which is what it said before.
         }
 
         return () => {
+            unbindState();
+
+            try {
+                stopMonitoring();
+            } catch (error) {
+                // Already gone.
+            }
+
             try {
                 if (subscription) {
                     subscription.stopListening(EVENT_RINGING);
                     subscription.stopListening(EVENT_ANSWERED);
                     subscription.stopListening(EVENT_ENDED);
+                    subscription.stopListening(EVENT_MISSED);
+                    subscription.stopListening(EVENT_PING);
                 }
 
                 instance.leave(activeChannel);
             } catch (error) {
                 // Nothing to clean up.
             }
+
+            updateCallPopStatus({ subscribed: false });
         };
-    }, [activeChannel, canMonitor, ingestCall, removeCall]);
+    }, [
+        activeChannel,
+        canMonitor,
+        ingestCall,
+        markMissed,
+        removeCall,
+        requestSnapshot,
+    ]);
 
     /**
      * One interval for the whole stack, started only while cards are on screen
@@ -1023,12 +1601,28 @@ const CallQueuePop = ({
         };
     }, [hasRinging]);
 
-    /** Drop any pending exit timers, notifications and titles on unmount. */
-    useEffect(
-        () => () => {
+    /** Drop any pending timers, requests and notifications on unmount. */
+    useEffect(() => {
+        // Set here rather than only at declaration: React can unmount and
+        // remount the same instance (StrictMode does exactly that in
+        // development), and a `mounted` flag that never comes back would
+        // silently swallow every snapshot response after it.
+        mounted.current = true;
+
+        return () => {
+            mounted.current = false;
+
             exitTimers.current.forEach((timer) => clearTimeout(timer));
             exitTimers.current = [];
 
+            missedTimers.current.forEach((timer) => clearTimeout(timer));
+            missedTimers.current.clear();
+
+            if (pendingSnapshot.current !== null) {
+                clearTimeout(pendingSnapshot.current);
+                pendingSnapshot.current = null;
+            }
+
             notifications.current.forEach((notification) => {
                 try {
                     notification.close();
@@ -1039,13 +1633,16 @@ const CallQueuePop = ({
 
             notifications.current.clear();
             notified.current.clear();
-        },
-        []
-    );
+        };
+    }, []);
 
-    /** The dial string for a call's queue, or '' when that queue has none. */
-    const pickupCodeFor = (call) =>
-        (call.queueId !== null && pickupCodes[call.queueId]) || '';
+    /**
+     * The dial string for a call, or '' when nothing is configured for it.
+     * Keyed on `pickupKey`, not the queue id: a direct call is intercepted
+     * through a Zoom call pickup GROUP, whose code the snapshot files under
+     * 'direct'.
+     */
+    const pickupCodeFor = (call) => resolvePickupCode(call, pickupCodes);
 
     /** A task's popup target, from the `taskUrl` builder or `{id}` template. */
     const hrefForTask = (task) =>
@@ -1126,6 +1723,11 @@ const CallQueuePop = ({
                 const tasksPanelId = `cqpop-tasks-${call.callId}`;
                 const tasksOpen = expandedTasks[call.callId] === true;
 
+                // A direct call rang a person, not a queue: the badge says so,
+                // and the card names who it is ringing (and who passed it on).
+                const isDirect = call.kind === KIND_DIRECT;
+                const ringingLine = directRingingLine(call);
+
                 // Demo cards ship a ready-made list; everything else waits on
                 // (or has already had) the drill-down fetch.
                 const tasksPanel = Array.isArray(call.tasks)
@@ -1135,14 +1737,20 @@ const CallQueuePop = ({
                 return (
                     <div
                         className={`${styles.cqpopCard}${
-                            call.leaving ? ` ${styles.cqpopCardLeaving}` : ''
-                        }`}
+                            isDirect ? ` ${styles.cqpopCardDirect}` : ''
+                        }${call.leaving ? ` ${styles.cqpopCardLeaving}` : ''}`}
                         key={`cqpop-${call.callId}`}
                     >
                         <div className={styles.cqpopCardHead}>
-                            <span className={styles.cqpopBadge}>
+                            <span
+                                className={`${styles.cqpopBadge}${
+                                    isDirect
+                                        ? ` ${styles.cqpopBadgeDirect}`
+                                        : ''
+                                }`}
+                            >
                                 <span className={styles.cqpopDot} />
-                                {call.queueName}
+                                {callBadgeLabel(call)}
                             </span>
                             <span className={styles.cqpopTimer}>
                                 Ringing · {formatElapsed(call.startedAt, now)}
@@ -1168,6 +1776,21 @@ const CallQueuePop = ({
                                 </div>
                             ) : null}
 
+                            {ringingLine ? (
+                                <div className={styles.cqpopCallee}>
+                                    {ringingLine}
+                                </div>
+                            ) : null}
+
+                            {/* One leg said no, but the call may still be
+                                ringing elsewhere — say so rather than let the
+                                card sit there looking untouched. */}
+                            {call.missedAt ? (
+                                <div className={styles.cqpopMissed}>
+                                    One line declined
+                                </div>
+                            ) : null}
+
                             {client ? (
                                 <div className={styles.cqpopClient}>
                                     <div className={styles.cqpopClientHead}>