@visns-studio/visns-components 6.27.0 → 6.30.0

package/README.md

@@ -9,6 +9,82 @@ A comprehensive React component library used by the VISNS Studio team for CRM an
 
 VISNS Components is a React-based UI component library that provides a set of reusable, consistent, and customizable components for building web applications. It includes components for authentication, data grids, forms, navigation, and more, designed to work seamlessly together.
 
+## Recent Updates (v6.30.0)
+
+### `CallQueuePop` no longer loses its channel to the header's phone badge
+
+Two components listen on the same private channel (`call-queue-monitor.{env}`):
+the call pop, mounted at the app root, and `ZoomPhoneBadge` in the header. A
+host that hides its header on some routes (the CRM does, on client and task
+record pages) unmounted the badge, whose cleanup called `echo.leave()` — and
+laravel-echo's `leave()` destroys a channel for every holder, not just the
+caller. The pop kept reporting `subscribed: true` and simply stopped popping
+until the tab was reloaded. Production's webhook ledger showed every ring
+broadcast OK, which is exactly why this took a while to find.
+
+- **`acquirePrivateChannel` / `releasePrivateChannel` / `hasPrivateChannel`**
+  (new, exported): a ref-counted front for `echo.private()` / `echo.leave()`.
+  The channel is opened on the first acquire and only really left when the
+  last holder releases it. Both `CallQueuePop` and `useZoomPhoneLive` go
+  through it. **A host component that listens on a channel one of ours also
+  listens on must use it too** — a direct `echo.leave()` will still take the
+  channel away from everyone.
+- **The pop rechecks its channel** on every socket reconnect and every
+  `resubscribeCheckMs` (new prop, default 60 s, `0` disables) while the tab is
+  visible, and resubscribes when it finds the channel gone — then refetches
+  the live snapshot so anything that rang meanwhile is caught up.
+- **Diagnostics gain a "Channel live" row** beside "Subscribed", fed by the
+  new `channelPresent` status field (`noteCallPopChannelPresent`, exported).
+  The two readings disagreeing is the symptom this release fixes; before,
+  there was no second reading.
+
+## Recent Updates (v6.29.0)
+
+### `TicketConversation` names who a reply reaches
+
+A helpdesk reply goes to everybody on the email chain, not to the one person
+whose message happens to be on screen — and on a forwarded ticket that is
+regularly somebody the agent has never seen. The composer said *"This is
+emailed to the customer."*, which is true and is not enough to check a send
+against.
+
+The server now says who, in two places, and the component draws both:
+
+```jsonc
+// GET {base}/{ticketId}/conversation
+{
+  "reply_audience": {            // or null — not answerable by email, or unknown
+    "to": [{ "name": "Dana Reid", "address": "dana@acme.test" }],
+    "cc": [{ "name": null, "address": "accounts@acme.test" }]
+  },
+  "data": [
+    { "id": 4, "direction": "out", "recipients": { "to": [], "cc": [] } },
+    { "id": 3, "direction": "note", "recipients": null }
+  ]
+}
+```
+
+- **Before sending** — the `.consequence` sentence beside the Internal note
+  switch becomes `Emailed to Dana Reid · Cc accounts@acme.test` (the ` · Cc …`
+  half is omitted when Cc is empty). An internal note is unchanged, and a
+  `reply_audience` of `null` falls back to the old sentence rather than naming
+  nobody.
+- **After sending** — each entry carrying `recipients` draws one quiet
+  `To … · Cc …` line between its head and its body. **Both directions**: on our
+  reply it says who we reached, on the customer's it says who else at their end
+  has already read it, which is what tells an agent whether the answer needs to
+  go anywhere new. Nothing on a note, or on a row imported before the server
+  knew any of this (`recipients: null`).
+- A recipient renders as `name || address`; the **full `Name <address>` list is
+  in the `title`**, because two people called Dana is exactly the case a name
+  alone cannot settle.
+- **Nothing is folded to "+3 more".** The recipient worth noticing is the
+  unexpected one, which is the one a fold would hide — so both lines wrap and
+  take the space they need.
+
+The `POST {base}/{ticketId}/reply` response's `data` carries `recipients` too,
+so a reply prepended by the composer shows its own line immediately.
+
 ## Recent Updates (v6.27.0)
 
 ### A tint on one column: `cellColours`
@@ -2212,6 +2288,7 @@ endpoint nor an Echo instance present it renders nothing and logs nothing.
 | `calendarPath` | `'/calendar'` | |
 | `callWorkspacePath` | `'/call/{number}'` | Template, or `(workspaceId, call) => path`. `{number}` is the `61…` form the workspace route expects. |
 | `syncChannelName` | `'throughlife-call-queue-pop'` | The `BroadcastChannel` that keeps every open tab's stack in step. Falsy switches cross-tab sync off. |
+| `clientDetailFields` | `CLIENT_DETAIL_FIELDS` (adviser / coding / age / city) | `[{ key, label, demo? }]` — the client-block rows, in card order; rows with an empty value are dropped; `demo` seeds the demo card. Pass your CRM's own fields so the card never names a field it does not have. Must be referentially stable (a module-scope constant, not an inline literal) — it sits in the demo effect's dependency list. |
 | `demoEnabled` | `true` | Registers `window.callPopDemo()` / `window.callPopClear()` for reviewing the UI without a backend. |
 
 **Payload contract.** Snake_case and camelCase are both accepted, so a Laravel
@@ -2226,6 +2303,11 @@ Named exports for testing: `toLocalDigits`, `formatAuPhone`, `formatEventDate`,
 `formatDueDate`, `toCallWorkspaceId`, `normaliseCall`, `normalisePickupCodes`,
 `formatElapsed`, `hasMonitorPermission`, `clientDetails`.
 
+`CLIENT_DETAIL_FIELDS`, `clientDetails` and `demoClientDetails` are exported
+from the package itself (`@visns-studio/visns-components`), so a host can build
+its own field list beside the default or reuse the demo seeding; the helpers
+module is not re-exported wholesale, only those three alongside the component.
+
 #### CallQueueSettings
 
 The admin table behind the pop: one row per Zoom call queue, carrying the

package/package.json

@@ -93,7 +93,7 @@
         "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "6.27.0",
+    "version": "6.30.0",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/callQueue/CallQueueDiagnostics.jsx

@@ -559,6 +559,19 @@ const CallQueueDiagnostics = ({
                             ? 'bad'
                             : 'ok'
                     )}
+                    {/* Deliberately beside "Subscribed", not folded into
+                        it: a channel torn down by somebody else's
+                        `echo.leave()` leaves "Subscribed" stuck on Yes, and
+                        the two readings disagreeing is the symptom. */}
+                    {row(
+                        'Channel live',
+                        yesNo(status.channelPresent, 'not checked'),
+                        status.channelPresent === false
+                            ? 'bad'
+                            : status.channelPresent === true
+                              ? 'ok'
+                              : undefined
+                    )}
                     {row(
                         'Last event',
                         status.lastEventName

package/src/components/callQueue/CallQueuePop.jsx

@@ -20,11 +20,20 @@ import { subscriptionMonitor } from '../sms/smsLiveState';
 import {
     appendCallPopLog,
     installCallPopStatusHook,
+    noteCallPopChannelPresent,
     noteCallPopConnectionState,
     noteCallPopEvent,
     updateCallPopStatus,
 } from './callPopStatus';
 
+// The header's phone badge listens on this SAME channel, and Echo's `leave()`
+// destroys a channel for everyone who holds it — see sharedPrivateChannel.js.
+import {
+    acquirePrivateChannel,
+    hasPrivateChannel,
+    releasePrivateChannel,
+} from '../echo/sharedPrivateChannel';
+
 // 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 {
@@ -40,6 +49,7 @@ import {
     defaultClientTasksUrl,
     defaultClientUrl,
     defaultTaskUrl,
+    demoClientDetails,
     directRingingLine,
     formatAuPhone,
     formatDueDate,
@@ -62,6 +72,7 @@ export {
     callBadgeLabel,
     calleeLabel,
     clientDetails,
+    demoClientDetails,
     directRingingLine,
     formatAuPhone,
     formatDueDate,
@@ -117,6 +128,15 @@ export {
  * 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 channel is SHARED: the header's phone badge listens on the same private
+ * channel, and laravel-echo's `leave()` destroys a channel for everyone rather
+ * than just for its caller — so the badge unmounting (the CRM hides its header
+ * on record pages) used to silently unsubscribe the pop, with `subscribed`
+ * still reading true. Both sides now go through the ref-counted registry in
+ * ../echo/sharedPrivateChannel, and the pop rechecks the channel on every
+ * socket reconnect and every `resubscribeCheckMs` while the tab is visible,
+ * resubscribing when it finds it gone.
+ *
  * The caller -> client match arrives already resolved, as each call's `client`
  * block (computed once by the Zoom webhook, server-side). This component never
  * looks a caller up itself — every watching member of staff sees every pop, and
@@ -207,6 +227,16 @@ const DEFAULT_MISSED_GRACE_MS = 10000;
  */
 const SNAPSHOT_MIN_GAP_MS = 5000;
 
+/**
+ * How often the pop checks that its channel is still there, and resubscribes
+ * if it is not. A dropped socket announces itself; a channel taken away by
+ * another component's `echo.leave()` announces nothing at all, so the only way
+ * to find out is to look. Once a minute is cheap (a property read, and one
+ * throttled snapshot) and bounds the blind window at a minute. Override with
+ * the `resubscribeCheckMs` prop; 0 turns the poll off.
+ */
+const DEFAULT_RESUBSCRIBE_CHECK_MS = 60000;
+
 /** Title shown on alternate ticks while a call rings in a hidden tab. */
 const FLASH_TITLE = '📞 Incoming call…';
 
@@ -286,8 +316,19 @@ const CallQueuePop = ({
     calendarPath = '/calendar',
     callWorkspacePath = '/call/{number}',
     syncChannelName = SYNC_CHANNEL,
+    // The client-block rows, in card order — the host's own fields, so the
+    // card never names one its CRM does not have. The default is this
+    // component's original financial-planning shape (adviser / coding / age /
+    // city) and the demo card seeds itself from the same list, so a host that
+    // passes its own fields also demos its own fields.
+    //
+    // MUST be referentially stable — a module-scope constant, not an inline
+    // literal — because it sits in the demo effect's dependency list, and a
+    // fresh array per render would re-register the demo helpers every time.
+    clientDetailFields = CLIENT_DETAIL_FIELDS,
     demoEnabled = true,
     missedGraceMs = DEFAULT_MISSED_GRACE_MS,
+    resubscribeCheckMs = DEFAULT_RESUBSCRIBE_CHECK_MS,
 }) => {
     const [calls, setCalls] = useState([]);
     const [now, setNow] = useState(() => Date.now());
@@ -680,20 +721,22 @@ const CallQueuePop = ({
                     queueName: 'Test Call Queue',
                     callerNumber: '+61298765432',
                     callerName: 'Margaret Chen',
-                    // Every field the server's client block can carry, so the
-                    // rich card can be reviewed without a real match. id 0
+                    // The rich card reviewed without a real match. The detail
+                    // rows are seeded from `clientDetailFields` itself, so the
+                    // demo shows exactly the host's own fields with the host's
+                    // own sample values rather than another CRM's. id 0
                     // renders the name as plain text, not a link.
                     client: {
                         id: 0,
                         name: 'Chen, Margaret (Mrs)',
                         matched_on: 'home',
-                        adviser: 'Alina Bailey',
-                        coding: 'Early Retirement',
-                        age: 66,
+                        // Before the spread, so a host listing `email` among
+                        // its own fields demos its own sample value while a
+                        // host that does not still gets one.
                         email: 'margaret.chen@example.com',
-                        city: 'Fremantle',
+                        ...demoClientDetails(clientDetailFields),
                         next_event: {
-                            title: 'Client - Annual Review',
+                            title: 'Client review',
                             date: new Date(
                                 Date.now() + 2 * 24 * 60 * 60 * 1000
                             ).toISOString(),
@@ -705,19 +748,19 @@ const CallQueuePop = ({
                     tasks: [
                         {
                             id: 90001,
-                            label: 'Confirm rollover paperwork',
+                            label: 'Confirm the site visit time',
                             due_date: new Date(
                                 Date.now() + 3 * 24 * 60 * 60 * 1000
                             ).toISOString(),
-                            task_type: 'Superannuation',
+                            task_type: 'Ticket',
                         },
                         {
                             id: 90002,
-                            label: 'Send updated risk profile questionnaire',
+                            label: 'Send the updated quote',
                             due_date: new Date(
                                 Date.now() + 9 * 24 * 60 * 60 * 1000
                             ).toISOString(),
-                            task_type: 'Insurance',
+                            task_type: 'Quote',
                         },
                     ],
                     startedAt: new Date().toISOString(),
@@ -745,6 +788,7 @@ const CallQueuePop = ({
         addDemoPickupCode,
         broadcastSync,
         clearCalls,
+        clientDetailFields,
         demoEnabled,
         dropDemoPickupCode,
     ]);
@@ -875,8 +919,9 @@ const CallQueuePop = ({
      * 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.
+     * @param {string} reason 'mount' | 'reconnect' | 'visible' | 'resubscribe'
+     *   | 'poll' — logged, so the diagnostics panel says why each refresh
+     *   happened. Nothing validates the value; it is a label.
      */
     const refreshSnapshot = useCallback(
         (reason) => {
@@ -1133,14 +1178,24 @@ const CallQueuePop = ({
         let subscription = null;
         let stopMonitoring = () => {};
         let unbindState = () => {};
+        let resubscribeTimer = null;
+
+        /**
+         * Bind every `.queue.*` listener plus the subscription monitor.
+         *
+         * Broken out of the effect body because a resubscribe has to do all of
+         * this again against a brand new subscription object — the old one is
+         * a corpse once Echo has dropped the channel.
+         *
+         * @param {object} target The subscription to bind to.
+         * @returns {Function} Stops the monitor again.
+         */
+        const attachListeners = (target) => {
+            if (!target) {
+                return () => {};
+            }
 
-        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) => {
+            target.listen(EVENT_RINGING, (event) => {
                 const call = event?.call ?? event;
 
                 noteCallPopEvent(EVENT_RINGING);
@@ -1148,7 +1203,7 @@ const CallQueuePop = ({
                 ingestCall(call);
             });
 
-            subscription.listen(EVENT_ANSWERED, (event) => {
+            target.listen(EVENT_ANSWERED, (event) => {
                 const callId =
                     event?.callId ?? event?.call_id ?? event?.call?.callId;
 
@@ -1160,7 +1215,7 @@ const CallQueuePop = ({
                 }
             });
 
-            subscription.listen(EVENT_ENDED, (event) => {
+            target.listen(EVENT_ENDED, (event) => {
                 const callId =
                     event?.callId ?? event?.call_id ?? event?.call?.callId;
 
@@ -1175,7 +1230,7 @@ const CallQueuePop = ({
             // 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) => {
+            target.listen(EVENT_MISSED, (event) => {
                 const callId =
                     event?.callId ?? event?.call_id ?? event?.call?.callId;
 
@@ -1189,7 +1244,7 @@ const CallQueuePop = ({
 
             // 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) => {
+            target.listen(EVENT_PING, (event) => {
                 const nonce = event?.nonce ?? event?.id ?? null;
 
                 noteCallPopEvent(EVENT_PING, {
@@ -1201,7 +1256,7 @@ const CallQueuePop = ({
                 trace('event .queue.diagnostic-ping', nonce);
             });
 
-            stopMonitoring = subscriptionMonitor(subscription, {
+            return subscriptionMonitor(target, {
                 onSuccess: () => {
                     appendCallPopLog(`Subscribed to ${activeChannel}`, 'info', {
                         subscribed: true,
@@ -1243,6 +1298,113 @@ const CallQueuePop = ({
                     );
                 },
             });
+        };
+
+        /** Unbind whatever `attachListeners` bound. Never throws. */
+        const detachListeners = (target) => {
+            try {
+                stopMonitoring();
+            } catch (error) {
+                // Already gone.
+            }
+
+            stopMonitoring = () => {};
+
+            try {
+                if (target) {
+                    target.stopListening(EVENT_RINGING);
+                    target.stopListening(EVENT_ANSWERED);
+                    target.stopListening(EVENT_ENDED);
+                    target.stopListening(EVENT_MISSED);
+                    target.stopListening(EVENT_PING);
+                }
+            } catch (error) {
+                // A dead channel has nothing left to unbind.
+            }
+        };
+
+        /**
+         * Confirm the channel is still there, and rebuild it when it is not.
+         *
+         * The failure this exists for is silent by construction: another
+         * component calling `echo.leave()` on the shared channel unsubscribes
+         * us without any event, so `subscribed` stays true and the pop simply
+         * stops popping. Nothing tells us — we have to look.
+         *
+         * @returns {boolean} True when a resubscribe was performed.
+         */
+        const ensureSubscribed = () => {
+            let present = false;
+
+            try {
+                present = hasPrivateChannel(instance, activeChannel);
+            } catch (error) {
+                present = false;
+            }
+
+            noteCallPopChannelPresent(present);
+
+            if (present) {
+                return false;
+            }
+
+            appendCallPopLog('Channel was gone — resubscribing', 'warn', {
+                channel: activeChannel,
+                subscribed: false,
+                subscriptionError: null,
+            });
+            trace(`channel private-${activeChannel} was gone — resubscribing`);
+
+            detachListeners(subscription);
+            // Release before acquiring so the ref count nets out unchanged:
+            // this component held one reference before and holds one after.
+            releasePrivateChannel(instance, activeChannel);
+
+            try {
+                subscription = acquirePrivateChannel(instance, activeChannel);
+                stopMonitoring = attachListeners(subscription);
+                noteCallPopChannelPresent(
+                    hasPrivateChannel(instance, activeChannel)
+                );
+            } catch (error) {
+                subscription = null;
+                appendCallPopLog(
+                    `Could not resubscribe to ${activeChannel}: ${error?.message ?? error}`,
+                    'error',
+                    {
+                        subscribed: false,
+                        channelPresent: false,
+                        subscriptionError: {
+                            status: null,
+                            message: String(error?.message ?? error),
+                        },
+                    }
+                );
+                trace('resubscribe threw', error?.message ?? error);
+
+                return false;
+            }
+
+            // Anything that rang while we were unsubscribed was broadcast to
+            // nobody here, so the snapshot is the only way to learn about it.
+            requestSnapshot('resubscribe');
+
+            return true;
+        };
+
+        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.
+            //
+            // Ref-counted rather than `instance.private()` directly: the
+            // header's phone badge shares this channel and unmounts on record
+            // pages, and its `leave()` used to take our subscription with it.
+            subscription = acquirePrivateChannel(instance, activeChannel);
+            stopMonitoring = attachListeners(subscription);
+            noteCallPopChannelPresent(
+                hasPrivateChannel(instance, activeChannel)
+            );
         } catch (error) {
             subscription = null;
             appendCallPopLog(
@@ -1250,6 +1412,7 @@ const CallQueuePop = ({
                 'error',
                 {
                     subscribed: false,
+                    channelPresent: false,
                     subscriptionError: {
                         status: null,
                         message: String(error?.message ?? error),
@@ -1278,6 +1441,11 @@ const CallQueuePop = ({
                     // only when the socket actually went away, otherwise every
                     // ordinary connecting -> connected on load would refetch.
                     if (current === 'connected') {
+                        // A socket can come back without our channel: pusher-js
+                        // resubscribes what it still holds, and a channel that
+                        // was `leave()`n is no longer among them.
+                        ensureSubscribed();
+
                         if (sawDisconnect.current) {
                             requestSnapshot('reconnect');
                         }
@@ -1312,30 +1480,42 @@ const CallQueuePop = ({
             // says whether this browser is live, which is what it said before.
         }
 
-        return () => {
-            unbindState();
+        // The backstop. `state_change` covers a socket that visibly went away;
+        // this covers the case with no signal at all — the channel removed
+        // underneath a perfectly healthy socket. Only while the tab is being
+        // looked at: a backgrounded tab that nobody can see a pop in has
+        // nothing to catch up for, and the visibilitychange effect above
+        // already refreshes on the way back.
+        if (resubscribeCheckMs > 0) {
+            resubscribeTimer = setInterval(() => {
+                if (
+                    typeof document !== 'undefined' &&
+                    document.visibilityState !== 'visible'
+                ) {
+                    return;
+                }
 
-            try {
-                stopMonitoring();
-            } catch (error) {
-                // Already gone.
+                ensureSubscribed();
+                requestSnapshot('poll');
+            }, resubscribeCheckMs);
+        }
+
+        return () => {
+            if (resubscribeTimer !== null) {
+                clearInterval(resubscribeTimer);
+                resubscribeTimer = null;
             }
 
-            try {
-                if (subscription) {
-                    subscription.stopListening(EVENT_RINGING);
-                    subscription.stopListening(EVENT_ANSWERED);
-                    subscription.stopListening(EVENT_ENDED);
-                    subscription.stopListening(EVENT_MISSED);
-                    subscription.stopListening(EVENT_PING);
-                }
+            unbindState();
+            detachListeners(subscription);
 
-                instance.leave(activeChannel);
-            } catch (error) {
-                // Nothing to clean up.
-            }
+            // Only really leaves the channel when nobody else (the header's
+            // phone badge) is still holding it.
+            releasePrivateChannel(instance, activeChannel);
 
-            updateCallPopStatus({ subscribed: false });
+            // `channelPresent` goes back to unknown rather than false: the pop
+            // is no longer watching, so it has nothing to report either way.
+            updateCallPopStatus({ subscribed: false, channelPresent: null });
         };
     }, [
         activeChannel,
@@ -1344,6 +1524,7 @@ const CallQueuePop = ({
         markMissed,
         removeCall,
         requestSnapshot,
+        resubscribeCheckMs,
     ]);
 
     /**
@@ -1707,7 +1888,7 @@ const CallQueuePop = ({
             {calls.map((call) => {
                 const pickupCode = pickupCodeFor(call);
                 const client = call.client;
-                const details = clientDetails(client);
+                const details = clientDetails(client, clientDetailFields);
                 const nextEvent = client?.next_event ?? null;
                 const nextEventDate = formatEventDate(nextEvent?.date);
                 const openTasks = Number(client?.open_tasks ?? 0);

package/src/components/callQueue/callPopStatus.js

@@ -49,6 +49,15 @@ export const emptyCallPopStatus = () => ({
     /** Has the channel reported pusher:subscription_succeeded? */
     subscribed: false,
     subscribedAt: null,
+    /**
+     * Does Echo still hold the channel? null = not checked yet.
+     *
+     * Separate from `subscribed` on purpose: a channel torn down by somebody
+     * else's `echo.leave()` leaves `subscribed` stuck at true — nothing tells
+     * the pop it has been unsubscribed — so "we think we are subscribed" and
+     * "the channel is actually there" have to be two readings, not one.
+     */
+    channelPresent: null,
     /** `{status, message}` from pusher:subscription_error, else null. */
     subscriptionError: null,
     /** The one-shot `/ajax/call-queue/live` snapshot. */
@@ -207,6 +216,20 @@ export const noteCallPopConnectionState = (state) => {
     });
 };
 
+/**
+ * Record whether Echo still holds the pop's channel.
+ *
+ * Written by the pop's periodic check and whenever it (re)subscribes, so the
+ * diagnostics panel can show the one thing `subscribed` cannot: a subscription
+ * that was confirmed once and has since been thrown away underneath us.
+ *
+ * @param {boolean|null} present
+ */
+export const noteCallPopChannelPresent = (present) =>
+    updateCallPopStatus({
+        channelPresent: typeof present === 'boolean' ? present : null,
+    });
+
 /**
  * Expose the reader on `window` next to the demo hooks, so support can run
  * `callPopStatus()` in a staff member's console without a build of anything.

package/src/components/callQueue/callQueueHelpers.js

@@ -210,32 +210,69 @@ export const defaultTaskUrl = (task) => `/tasks/detail/${task?.id}`;
 /** Default detail route for a matched client. */
 export const defaultClientUrl = (client) => `/clients/${client?.id}`;
 
-/** The client fields shown as label/value rows, in card order. */
+/**
+ * The client fields shown as label/value rows, in card order — the DEFAULT,
+ * inherited from the financial-planning CRM this component was ported from.
+ * Each entry's `demo` is the sample value the demo card shows for it.
+ *
+ * A host whose caller enrichment returns a different shape passes its own list
+ * as `clientDetailFields` rather than living with rows it can never fill.
+ */
 export const CLIENT_DETAIL_FIELDS = [
-    { key: 'adviser', label: 'Adviser' },
-    { key: 'coding', label: 'Coding' },
-    { key: 'age', label: 'Age' },
-    { key: 'city', label: 'City' },
+    { key: 'adviser', label: 'Adviser', demo: 'Alina Bailey' },
+    { key: 'coding', label: 'Coding', demo: 'Early Retirement' },
+    { key: 'age', label: 'Age', demo: 66 },
+    { key: 'city', label: 'City', demo: 'Fremantle' },
 ];
 
 /**
  * Detail rows for a client block, with the empty ones dropped — a card only
  * ever shows what the CRM actually knows, never a row with a blank value.
+ *
+ * `fields` is the host's own list, so the card only ever names fields its CRM
+ * actually has. An entry with no string `key` is malformed and is ignored
+ * rather than drawn as a row with nothing behind it.
  */
-export const clientDetails = (client) => {
+export const clientDetails = (client, fields = CLIENT_DETAIL_FIELDS) => {
     if (!client || typeof client !== 'object') {
         return [];
     }
 
-    return CLIENT_DETAIL_FIELDS.map(({ key, label }) => ({
-        label,
-        value: client[key],
-    })).filter(
-        (row) =>
-            row.value !== null &&
-            row.value !== undefined &&
-            String(row.value).trim() !== ''
-    );
+    const list = Array.isArray(fields) ? fields : CLIENT_DETAIL_FIELDS;
+
+    return list
+        .filter((field) => field && typeof field.key === 'string')
+        .map(({ key, label }) => ({
+            label,
+            value: client[key],
+        }))
+        .filter(
+            (row) =>
+                row.value !== null &&
+                row.value !== undefined &&
+                String(row.value).trim() !== ''
+        );
+};
+
+/**
+ * The demo card's client block, built from the same list the real card draws
+ * from — so a host passing its own fields sees its own fields in the demo
+ * rather than another CRM's. An entry carrying no `demo` contributes nothing.
+ */
+export const demoClientDetails = (fields = CLIENT_DETAIL_FIELDS) => {
+    const list = Array.isArray(fields) ? fields : CLIENT_DETAIL_FIELDS;
+
+    return list.reduce((carry, field) => {
+        if (!field || typeof field.key !== 'string') {
+            return carry;
+        }
+
+        if (field.demo === undefined) {
+            return carry;
+        }
+
+        return { ...carry, [field.key]: field.demo };
+    }, {});
 };
 
 /** Seconds since `startedAt` rendered as m:ss (never negative). */

package/src/components/echo/sharedPrivateChannel.js

@@ -0,0 +1,204 @@
+/**
+ * Shared private channel registry.
+ * -----------------------------------------------------------------------
+ * Ref-counting in front of `echo.private(name)` / `echo.leave(name)`, for the
+ * case where two independent components subscribe to the SAME private channel.
+ *
+ * Why this exists: laravel-echo's `leave(name)` is not "stop listening for me",
+ * it is "destroy this channel" — the connector does
+ *
+ *     this.channels[name].unsubscribe(); delete this.channels[name];
+ *
+ * so the FIRST component to unmount takes the channel away from everyone still
+ * using it. That is exactly what happened with `call-queue-monitor.{env}`: the
+ * CRM header hides itself on client and task record pages, the header's phone
+ * badge unmounted and called `leave()`, and the call pop — mounted at the app
+ * root, with stable effect deps, so it never resubscribed — silently stopped
+ * receiving calls while still reporting `subscribed: true`.
+ *
+ * With this registry a channel is opened on the first acquire and only really
+ * left when the last holder releases it.
+ *
+ * Deliberately plain JS: no React, no DOM, no laravel-echo import. It is
+ * framework-free so `node --test` can import the source directly, and so it
+ * works with whatever the host handed us as an "Echo instance".
+ *
+ * Nothing here throws. A registry that breaks the subscription it is meant to
+ * protect would be worse than the bug it fixes.
+ */
+
+/**
+ * `WeakMap<instance, Map<name, {subscription, refs}>>`.
+ *
+ * Keyed per Echo instance rather than by name alone: an app may hold more than
+ * one broadcaster (and every test file certainly does), and two instances'
+ * `call-queue-monitor.production` are two different channels. Weak so a
+ * discarded Echo instance takes its entries with it.
+ */
+let registries = new WeakMap();
+
+/** The per-instance map, created on demand. */
+const registryFor = (instance) => {
+    let registry = registries.get(instance);
+
+    if (!registry) {
+        registry = new Map();
+        registries.set(instance, registry);
+    }
+
+    return registry;
+};
+
+/**
+ * Echo's own channel cache, when the connector exposes one.
+ *
+ * `PusherConnector`/`SocketIoConnector` both keep `this.channels`, keyed by the
+ * PREFIXED name (`private-<name>` for a private channel), and `leaveChannel()`
+ * deletes from it. Reading it is how we notice that somebody outside this
+ * registry — an older build, another library, a host's own cleanup — has torn
+ * our channel down behind our back. A connector without it (a null broadcaster,
+ * a stub in a test) simply leaves the registry as the only source of truth.
+ */
+const echoChannelCache = (instance) => {
+    try {
+        const channels = instance?.connector?.channels;
+
+        return channels && typeof channels === 'object' ? channels : null;
+    } catch (error) {
+        return null;
+    }
+};
+
+/** Is Echo still holding `private-<name>`? `null` = it cannot tell us. */
+const echoHolds = (instance, name) => {
+    const cache = echoChannelCache(instance);
+
+    if (!cache) {
+        return null;
+    }
+
+    return Object.prototype.hasOwnProperty.call(cache, `private-${name}`);
+};
+
+/**
+ * Subscribe to a private channel, or join the subscription already open.
+ *
+ * `instance.private(name)` is called on the first acquire for this
+ * (instance, name) pair only; later acquires bump the count and hand back the
+ * same subscription object, so every holder listens on one channel.
+ *
+ * One exception: if Echo's own cache no longer holds the channel — somebody
+ * called `leave()` outside this registry — the cached subscription is dead and
+ * handing it back would give the caller an object that will never fire again.
+ * In that case we resubscribe and store the new one.
+ *
+ * @param {object} instance Echo instance.
+ * @param {string} name     Channel name, unprefixed (Echo adds `private-`).
+ *
+ * @returns {object|null} The subscription, or null when there is nothing to
+ *                        subscribe to (no instance, no name, `private` threw).
+ */
+export const acquirePrivateChannel = (instance, name) => {
+    if (!instance || typeof instance.private !== 'function' || !name) {
+        return null;
+    }
+
+    const registry = registryFor(instance);
+    const entry = registry.get(name);
+
+    // A live entry whose channel Echo still has (or cannot report on) is the
+    // ordinary case: share it.
+    if (entry && echoHolds(instance, name) !== false) {
+        entry.refs += 1;
+
+        return entry.subscription;
+    }
+
+    const subscription = instance.private(name);
+
+    if (entry) {
+        // Torn down behind our back: keep the holders we know about, replace
+        // the corpse they are holding.
+        entry.subscription = subscription;
+        entry.refs += 1;
+    } else {
+        registry.set(name, { subscription, refs: 1 });
+    }
+
+    return subscription;
+};
+
+/**
+ * Let go of a private channel. `instance.leave(name)` runs only when the last
+ * holder releases it; releasing a name nobody acquired is a no-op.
+ *
+ * @param {object} instance Echo instance.
+ * @param {string} name     Channel name, unprefixed.
+ *
+ * @returns {number} Holders remaining (0 once the channel has been left).
+ */
+export const releasePrivateChannel = (instance, name) => {
+    if (!instance || !name) {
+        return 0;
+    }
+
+    const registry = registries.get(instance);
+    const entry = registry?.get(name);
+
+    if (!entry) {
+        return 0;
+    }
+
+    entry.refs -= 1;
+
+    if (entry.refs > 0) {
+        return entry.refs;
+    }
+
+    registry.delete(name);
+
+    try {
+        instance.leave?.(name);
+    } catch (error) {
+        // Already gone, or an instance that never had a socket. Either way the
+        // registry is clean, which is the part we control.
+    }
+
+    return 0;
+};
+
+/**
+ * Is this channel actually still subscribed?
+ *
+ * True only when the registry has a live entry AND — when the connector
+ * exposes its cache — Echo still holds `private-<name>`. The second half is
+ * the whole point: an external `leave()` leaves our ref count untouched but
+ * kills the channel, and that mismatch is precisely the failure this module
+ * was written for. Callers use it to notice and resubscribe.
+ *
+ * @param {object} instance Echo instance.
+ * @param {string} name     Channel name, unprefixed.
+ *
+ * @returns {boolean}
+ */
+export const hasPrivateChannel = (instance, name) => {
+    if (!instance || !name) {
+        return false;
+    }
+
+    const entry = registries.get(instance)?.get(name);
+
+    if (!entry) {
+        return false;
+    }
+
+    // `null` = the connector cannot tell us; the registry is then all we have.
+    return echoHolds(instance, name) !== false;
+};
+
+/** Drop every entry. Used by tests; never call this from application code. */
+export const _resetSharedPrivateChannels = () => {
+    registries = new WeakMap();
+};
+
+export default acquirePrivateChannel;

package/src/components/phone/useZoomPhoneLive.js

@@ -6,6 +6,14 @@ import {
     subscriptionMonitor,
 } from '../sms/smsLiveState';
 
+// The call queue pop listens on this SAME channel. Echo's `leave()` destroys a
+// channel for everyone, so neither of us may call it directly — see
+// sharedPrivateChannel.js.
+import {
+    acquirePrivateChannel,
+    releasePrivateChannel,
+} from '../echo/sharedPrivateChannel';
+
 /** The event the backend broadcasts when one extension's state changes. */
 export const EVENT_PRESENCE = '.phone.presence';
 
@@ -80,7 +88,9 @@ const useZoomPhoneLive = ({
         let unbindState = () => {};
 
         try {
-            subscription = instance.private(channel);
+            // Ref-counted: the call pop is very likely already on this
+            // channel, and the two must share one subscription.
+            subscription = acquirePrivateChannel(instance, channel);
 
             subscription.listen(EVENT_PRESENCE, (event) => {
                 presenceRef.current?.(event || {});
@@ -150,7 +160,11 @@ const useZoomPhoneLive = ({
 
             try {
                 subscription?.stopListening(EVENT_PRESENCE);
-                instance.leave(channel);
+                // Our own listener goes, the channel only if nobody else (the
+                // call pop) is still holding it. The header hides itself on
+                // record pages, so this cleanup runs while the pop is very
+                // much still watching.
+                releasePrivateChannel(instance, channel);
             } catch (error) {
                 // Nothing to clean up.
             }

package/src/components/styles/TicketConversation.module.scss

@@ -210,6 +210,19 @@
     white-space: nowrap;
 }
 
+/* Who an email reached, under the head and above the message.
+   Deliberately quiet — it is a qualifier on the entry, not part of it — and
+   deliberately NOT truncated to "+3 more": the recipient worth noticing is the
+   one nobody expected, which is exactly the one a fold would hide. So it wraps
+   and takes as many lines as it needs. */
+.recipients {
+    margin: -0.15rem 0 0.45rem;
+    color: var(--muted-color, #6b7280);
+    font-size: 0.74rem;
+    line-height: 1.4;
+    overflow-wrap: anywhere;
+}
+
 .body {
     margin: 0;
     color: var(--paragraph-color, #2b2b2b);
@@ -518,10 +531,18 @@
     cursor: pointer;
 }
 
-/* The consequence in words, always present. */
+/* The consequence in words, always present — and since it now NAMES the people
+   a reply reaches, it has to survive a Cc of five. `min-width: 0` is the
+   load-bearing half: a flex item's default `min-width: auto` refuses to shrink
+   below its longest unbreakable run, which would push the sentence out of the
+   bar rather than wrapping it. */
 .consequence {
+    flex: 1 1 auto;
+    min-width: 0;
     color: var(--muted-color, #6b7280);
     font-size: 0.76rem;
+    line-height: 1.4;
+    overflow-wrap: anywhere;
 }
 
 .composerInput {

package/src/components/tickets/TicketConversation.jsx

@@ -25,6 +25,44 @@ const CHANNEL_ICON = {
     Web: Globe,
 };
 
+/**
+ * Who an email went to, or is about to go to.
+ *
+ * A reply on a ticket goes to everybody on the chain, not to the one person
+ * whose message is on screen — so the composer has to SAY so before the button
+ * is pressed, and a sent entry has to say who it reached. The same two
+ * readings are used in both places, which is why they live here rather than
+ * once in the Composer and again in Entry:
+ *
+ *   names()     — what is drawn. "Dana Reid, accounts@acme.test" — the name
+ *                 where there is one, the address where there is not.
+ *   addresses() — what is HOVERED. The full `Name <address>` list, because
+ *                 two people called Dana is exactly the case where the name
+ *                 alone is not enough to check a send against.
+ *
+ * Both take a possibly-absent list: `recipients` is null on an internal note
+ * and on every row imported before the server knew any of this.
+ */
+const names = (list) =>
+    (Array.isArray(list) ? list : [])
+        .map((r) => r.name || r.address)
+        .join(', ');
+
+const addresses = (list) =>
+    (Array.isArray(list) ? list : [])
+        .map((r) => (r.name ? `${r.name} <${r.address}>` : r.address))
+        .join(', ');
+
+/** The `title` for a To/Cc line — undefined rather than an empty attribute. */
+const recipientTitle = (to, cc) => {
+    const lines = [];
+
+    if (to.length) lines.push(`To: ${addresses(to)}`);
+    if (cc.length) lines.push(`Cc: ${addresses(cc)}`);
+
+    return lines.length ? lines.join('\n') : undefined;
+};
+
 /**
  * A support ticket's conversation.
  *
@@ -49,6 +87,10 @@ const TicketConversation = ({
 }) => {
     const [entries, setEntries] = useState([]);
     const [ticket, setTicket] = useState(null);
+    // Who a reply would go to. null = the server does not know, or the ticket
+    // cannot be answered by email — the composer falls back to the old
+    // sentence rather than naming nobody.
+    const [audience, setAudience] = useState(null);
     const [loading, setLoading] = useState(true);
     const [failed, setFailed] = useState(false);
     const mountedRef = useRef(true);
@@ -72,6 +114,7 @@ const TicketConversation = ({
 
                 setEntries(Array.isArray(result?.data) ? result.data : []);
                 setTicket(result?.ticket ?? null);
+                setAudience(result?.reply_audience ?? null);
                 setLoading(false);
                 onLoaded?.(result?.ticket ?? null);
             },
@@ -128,6 +171,7 @@ const TicketConversation = ({
                 <Composer
                     base={base}
                     ticketId={ticketId}
+                    audience={audience}
                     onPosted={(entry) => setEntries((prev) => [entry, ...prev])}
                 />
             )}
@@ -155,8 +199,15 @@ const TicketConversation = ({
  * this" / "only staff can see this") every time. An agent sending an internal
  * note to a customer is the expensive mistake here, and a toggle whose state
  * you have to remember is how it happens.
+ *
+ * `audience` is the second half of that argument. A reply goes to everybody on
+ * the email chain — which on a forwarded ticket is regularly somebody the agent
+ * has never seen — so the consequence NAMES them rather than saying "the
+ * customer". Nothing is truncated to "+3 more": the whole point of the line is
+ * to be read before sending, and the name that would be hidden is the one worth
+ * noticing. `null` means the server could not say, and the old sentence stands.
  */
-const Composer = ({ base, ticketId, onPosted }) => {
+const Composer = ({ base, ticketId, audience, onPosted }) => {
     const [body, setBody] = useState('');
     const [internal, setInternal] = useState(false);
     const [sending, setSending] = useState(false);
@@ -189,6 +240,22 @@ const Composer = ({ base, ticketId, onPosted }) => {
         });
     };
 
+    const to = audience?.to ?? [];
+    const cc = audience?.cc ?? [];
+    const named = !internal && to.length > 0;
+
+    let consequence;
+
+    if (internal) {
+        consequence = 'Only staff can see this.';
+    } else if (named) {
+        consequence = `Emailed to ${names(to)}`;
+
+        if (cc.length) consequence += ` · Cc ${names(cc)}`;
+    } else {
+        consequence = 'This is emailed to the customer.';
+    }
+
     return (
         <div className={`${styles.composer} ${internal ? styles.composerNote : ''}`}>
             <div className={styles.composerBar}>
@@ -201,10 +268,11 @@ const Composer = ({ base, ticketId, onPosted }) => {
                     Internal note
                 </label>
 
-                <span className={styles.consequence}>
-                    {internal
-                        ? 'Only staff can see this.'
-                        : 'This is emailed to the customer.'}
+                <span
+                    className={styles.consequence}
+                    title={named ? recipientTitle(to, cc) : undefined}
+                >
+                    {consequence}
                 </span>
             </div>
 
@@ -408,6 +476,20 @@ const Entry = ({ entry }) => {
           ? styles.entryIn
           : styles.entryOut;
 
+    /* Who else was on this message. Drawn for BOTH directions, and they answer
+       different questions: on our reply it is who we sent to, on the
+       customer's it is who else at their end has already read it — which is
+       what tells an agent whether the answer needs to reach anybody new.
+       Absent on notes, and on every row that predates the server sending it. */
+    const to = entry.recipients?.to ?? [];
+    const cc = entry.recipients?.cc ?? [];
+    const parts = [];
+
+    if (to.length) parts.push(`To ${names(to)}`);
+    if (cc.length) parts.push(`Cc ${names(cc)}`);
+
+    const showRecipients = !isNote && parts.length > 0;
+
     return (
         <li className={`${styles.entry} ${cls}`}>
             <div className={styles.entryHead}>
@@ -452,6 +534,15 @@ const Entry = ({ entry }) => {
                 )}
             </div>
 
+            {showRecipients && (
+                <p
+                    className={styles.recipients}
+                    title={recipientTitle(to, cc)}
+                >
+                    {parts.join(' · ')}
+                </p>
+            )}
+
             <EntryBody entry={entry} />
         </li>
     );

package/src/index.js

@@ -141,12 +141,30 @@ import {
 import CallQueuePop from './components/callQueue/CallQueuePop';
 import CallQueueSettings from './components/callQueue/CallQueueSettings';
 import CallQueueDiagnostics from './components/callQueue/CallQueueDiagnostics';
+// The client-block field list and its two readers, so a host can build its own
+// `clientDetailFields` beside the default rather than restating the shape.
+import {
+    CLIENT_DETAIL_FIELDS,
+    clientDetails,
+    demoClientDetails,
+} from './components/callQueue/callQueueHelpers';
 import {
     CALL_POP_STATUS_EVENT,
     getCallPopStatus,
+    noteCallPopChannelPresent,
     updateCallPopStatus,
 } from './components/callQueue/callPopStatus';
 
+// Ref-counted `echo.private()`. Exported because any host component that
+// listens on a channel one of ours also listens on must go through it —
+// laravel-echo's `leave()` destroys a channel for every holder, not just the
+// caller, which is how the call pop lost its subscription to the header badge.
+import {
+    acquirePrivateChannel,
+    hasPrivateChannel,
+    releasePrivateChannel,
+} from './components/echo/sharedPrivateChannel';
+
 // Vault — the staff password manager. VaultQuickSearch mounts through
 // Navigation's `renderers` slot; VaultManager is the page behind it.
 import OtpChip from './components/vault/OtpChip';
@@ -365,8 +383,15 @@ export {
     CallQueueDiagnostics,
     CallQueuePop,
     CallQueueSettings,
+    CLIENT_DETAIL_FIELDS,
+    clientDetails,
+    demoClientDetails,
     getCallPopStatus,
+    noteCallPopChannelPresent,
     updateCallPopStatus,
+    acquirePrivateChannel,
+    hasPrivateChannel,
+    releasePrivateChannel,
     cleanBase32,
     decodeFromBlob,
     decodeFromSource,