@byscott-io/where-is-waldo 0.1.0

package/dist/index.esm.js

@@ -0,0 +1,895 @@
+import { createConsumer } from '@rails/actioncable';
+import React, { useState, useRef, useEffect, useCallback, createContext, useMemo, useContext } from 'react';
+
+function _arrayLikeToArray(r, a) {
+  (null == a || a > r.length) && (a = r.length);
+  for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e];
+  return n;
+}
+function _arrayWithHoles(r) {
+  if (Array.isArray(r)) return r;
+}
+function _defineProperty(e, r, t) {
+  return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+    value: t,
+    enumerable: true,
+    configurable: true,
+    writable: true
+  }) : e[r] = t, e;
+}
+function _iterableToArrayLimit(r, l) {
+  var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"];
+  if (null != t) {
+    var e,
+      n,
+      i,
+      u,
+      a = [],
+      f = true,
+      o = false;
+    try {
+      if (i = (t = t.call(r)).next, 0 === l) ; else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0);
+    } catch (r) {
+      o = true, n = r;
+    } finally {
+      try {
+        if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return;
+      } finally {
+        if (o) throw n;
+      }
+    }
+    return a;
+  }
+}
+function _nonIterableRest() {
+  throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function ownKeys(e, r) {
+  var t = Object.keys(e);
+  if (Object.getOwnPropertySymbols) {
+    var o = Object.getOwnPropertySymbols(e);
+    r && (o = o.filter(function (r) {
+      return Object.getOwnPropertyDescriptor(e, r).enumerable;
+    })), t.push.apply(t, o);
+  }
+  return t;
+}
+function _objectSpread2(e) {
+  for (var r = 1; r < arguments.length; r++) {
+    var t = null != arguments[r] ? arguments[r] : {};
+    r % 2 ? ownKeys(Object(t), true).forEach(function (r) {
+      _defineProperty(e, r, t[r]);
+    }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) {
+      Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
+    });
+  }
+  return e;
+}
+function _slicedToArray(r, e) {
+  return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest();
+}
+function _toPrimitive(t, r) {
+  if ("object" != typeof t || !t) return t;
+  var e = t[Symbol.toPrimitive];
+  if (void 0 !== e) {
+    var i = e.call(t, r);
+    if ("object" != typeof i) return i;
+    throw new TypeError("@@toPrimitive must return a primitive value.");
+  }
+  return ("string" === r ? String : Number)(t);
+}
+function _toPropertyKey(t) {
+  var i = _toPrimitive(t, "string");
+  return "symbol" == typeof i ? i : i + "";
+}
+function _unsupportedIterableToArray(r, a) {
+  if (r) {
+    if ("string" == typeof r) return _arrayLikeToArray(r, a);
+    var t = {}.toString.call(r).slice(8, -1);
+    return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0;
+  }
+}
+
+var consumer = null;
+var config = {
+  url: '/cable',
+  getToken: null
+};
+
+// Subscribe-by-event-type registry: message type -> Set of listener fns.
+// Components subscribe to a raw event type (see subscribeToEvent /
+// useWaldoEvent) and decide for themselves whether they care about a given
+// payload. handleMessage dispatches every incoming message to the listeners
+// registered for its type.
+var listeners = new Map();
+
+/**
+ * Subscribe to a raw cable event type. Returns an unsubscribe function.
+ * Multiple subscribers per type are supported; each receives (data, message).
+ * @param {string} type - The message type to listen for
+ * @param {Function} callback - Called with (data, message) on each matching event
+ * @returns {Function} unsubscribe
+ */
+function subscribeToEvent(type, callback) {
+  if (!type || typeof callback !== 'function') return function () {};
+  var set = listeners.get(type);
+  if (!set) {
+    set = new Set();
+    listeners.set(type, set);
+  }
+  set.add(callback);
+  return function unsubscribe() {
+    var current = listeners.get(type);
+    if (!current) return;
+    current["delete"](callback);
+    if (current.size === 0) listeners["delete"](type);
+  };
+}
+
+/**
+ * Configure the ActionCable connection
+ * @param {Object} options
+ * @param {string} options.url - WebSocket URL (default: '/cable')
+ * @param {Function} options.getToken - Function that returns auth token
+ */
+function configureCable() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  config = _objectSpread2(_objectSpread2({}, config), options);
+  // Reset consumer when config changes
+  if (consumer) {
+    consumer.disconnect();
+    consumer = null;
+  }
+}
+
+/**
+ * Get or create the ActionCable consumer
+ * @returns {Consumer}
+ */
+function getConsumer() {
+  if (!consumer) {
+    var url = config.url;
+    if (config.getToken) {
+      var token = config.getToken();
+      if (token) {
+        var separator = url.includes('?') ? '&' : '?';
+        url = "".concat(url).concat(separator, "token=").concat(encodeURIComponent(token));
+      }
+    }
+    consumer = createConsumer(url);
+  }
+  return consumer;
+}
+
+/**
+ * Disconnect and reset the consumer
+ */
+function disconnectCable() {
+  if (consumer) {
+    consumer.disconnect();
+    consumer = null;
+  }
+}
+
+/**
+ * Get current cable configuration
+ * @returns {Object}
+ */
+function getCableConfig() {
+  return _objectSpread2({}, config);
+}
+
+/**
+ * Handle an incoming message by dispatching to every listener subscribed to
+ * its type.
+ * @param {Object} message - The message object with type and data
+ * @returns {boolean} - Whether at least one listener was invoked
+ */
+function handleMessage(message) {
+  var type = message.type,
+    data = message.data;
+  var set = listeners.get(type);
+  if (!set || set.size === 0) return false;
+
+  // Iterate a snapshot so a listener that unsubscribes during dispatch is safe.
+  Array.from(set).forEach(function (cb) {
+    try {
+      cb(data, message);
+    } catch (err) {
+      // One bad listener must not block the others.
+      // eslint-disable-next-line no-console
+      console.error("[where-is-waldo] listener for \"".concat(type, "\" threw:"), err);
+    }
+  });
+  return true;
+}
+
+var DEFAULTS = {
+  channelName: 'WhereIsWaldo::PresenceChannel',
+  heartbeatInterval: 30000,
+  // ms
+  activityTimeout: 30000,
+  // ms of no activity -> subject_active=false
+  metadata: {},
+  debug: false
+};
+function createPresenceReporter() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var config = _objectSpread2(_objectSpread2({}, DEFAULTS), options);
+  var now = config.now || function () {
+    return Date.now();
+  };
+  var resolveConsumer = config.getConsumer || getConsumer;
+  var resolveCableConfig = config.getCableConfig || getCableConfig;
+  var dispatch = config.handleMessage || handleMessage;
+  var log = function log() {
+    var _console;
+    for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+      args[_key] = arguments[_key];
+    }
+    // eslint-disable-next-line no-console
+    if (config.debug) (_console = console).log.apply(_console, ['[PresenceReporter]'].concat(args));
+  };
+  var subscription = null;
+  var heartbeatTimer = null;
+  var activityTimer = null;
+  var lastActivityAt = 0;
+
+  // visible = tab/app is foreground & visible; active = recent user activity.
+  var state = {
+    connected: false,
+    visible: true,
+    active: true,
+    sessionId: null
+  };
+  var emitChange = function emitChange() {
+    if (config.onChange) config.onChange(_objectSpread2({}, state));
+  };
+  var buildPayload = function buildPayload() {
+    var _overrides$tab_visibl, _overrides$subject_ac;
+    var overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    var payload = {
+      tab_visible: (_overrides$tab_visibl = overrides.tab_visible) !== null && _overrides$tab_visibl !== void 0 ? _overrides$tab_visibl : state.visible,
+      subject_active: (_overrides$subject_ac = overrides.subject_active) !== null && _overrides$subject_ac !== void 0 ? _overrides$subject_ac : state.active,
+      metadata: config.metadata || {}
+    };
+    if (lastActivityAt) payload.last_activity_at = lastActivityAt;
+    return payload;
+  };
+  var sendHeartbeat = function sendHeartbeat() {
+    var overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    if (!subscription) return;
+    log('heartbeat', overrides);
+    subscription.perform('heartbeat', buildPayload(overrides));
+  };
+
+  // (Re)arm the inactivity timer: after activityTimeout with no activity, flip
+  // to inactive and send an immediate heartbeat announcing it.
+  var scheduleInactivity = function scheduleInactivity() {
+    if (activityTimer) clearTimeout(activityTimer);
+    activityTimer = setTimeout(function () {
+      if (!state.active) return;
+      state.active = false;
+      emitChange();
+      sendHeartbeat({
+        subject_active: false
+      });
+    }, config.activityTimeout);
+  };
+  var reportActivity = function reportActivity() {
+    lastActivityAt = now();
+    if (!state.active) {
+      state.active = true;
+      emitChange();
+      sendHeartbeat({
+        subject_active: true
+      }); // immediate: inactive -> active
+    }
+    scheduleInactivity();
+  };
+  var setVisible = function setVisible(visible) {
+    if (visible === state.visible) return;
+    state.visible = visible;
+    emitChange();
+    sendHeartbeat(); // immediate: visibility change
+    if (visible) reportActivity();
+  };
+  var startHeartbeatLoop = function startHeartbeatLoop() {
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+    heartbeatTimer = setInterval(function () {
+      return sendHeartbeat();
+    }, config.heartbeatInterval);
+  };
+  var start = function start() {
+    if (subscription) return subscription;
+    subscription = resolveConsumer().subscriptions.create({
+      channel: config.channelName,
+      metadata: config.metadata || {}
+    }, {
+      connected: function connected() {
+        state.connected = true;
+        var cable = resolveCableConfig();
+        if (cable && cable.sessionId) state.sessionId = cable.sessionId;
+        emitChange();
+        if (config.onConnected) config.onConnected();
+        startHeartbeatLoop();
+      },
+      disconnected: function disconnected() {
+        state.connected = false;
+        emitChange();
+        if (config.onDisconnected) config.onDisconnected();
+      },
+      received: function received(message) {
+        // Honor targeted (per-session) messages, then route to the event bus.
+        if (message && message._target_session && message._target_session !== state.sessionId) {
+          return;
+        }
+        dispatch(message);
+      }
+    });
+    scheduleInactivity();
+    return subscription;
+  };
+  var stop = function stop() {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    if (activityTimer) {
+      clearTimeout(activityTimer);
+      activityTimer = null;
+    }
+    if (subscription) {
+      subscription.unsubscribe();
+      subscription = null;
+    }
+    state.connected = false;
+  };
+  return {
+    start: start,
+    stop: stop,
+    setVisible: setVisible,
+    reportActivity: reportActivity,
+    sendHeartbeat: sendHeartbeat,
+    getState: function getState() {
+      return _objectSpread2({}, state);
+    }
+  };
+}
+
+var DEFAULT_OPTIONS = {
+  channelName: 'WhereIsWaldo::PresenceChannel',
+  heartbeatInterval: 30000,
+  activityTimeout: 30000,
+  trackActivity: true,
+  trackVisibility: true,
+  debug: false
+};
+var initialVisible = function initialVisible() {
+  return typeof document === 'undefined' ? true : document.visibilityState !== 'hidden';
+};
+var initialFocused = function initialFocused() {
+  return typeof document === 'undefined' ? true : document.hasFocus();
+};
+
+/**
+ * usePresence - browser presence tracking. This is now a thin DOM-sensor
+ * wrapper around the framework-agnostic core (../core/presenceReporter): it
+ * binds `document`/`window` events to the reporter's `setVisible` /
+ * `reportActivity` inputs and mirrors the reporter's state into React state.
+ * The heartbeat cadence, activity/visibility state machine, and cable
+ * subscription all live in the core, which a React Native reporter reuses.
+ *
+ * @param {Object} options - see DEFAULT_OPTIONS
+ * @returns {{ connected, sessionId, tabVisible, windowFocused, subjectActive, sendHeartbeat }}
+ */
+function usePresence() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var config = _objectSpread2(_objectSpread2({}, DEFAULT_OPTIONS), options);
+  var _useState = useState(false),
+    _useState2 = _slicedToArray(_useState, 2),
+    connected = _useState2[0],
+    setConnected = _useState2[1];
+  var _useState3 = useState(null),
+    _useState4 = _slicedToArray(_useState3, 2),
+    sessionId = _useState4[0],
+    setSessionId = _useState4[1];
+  var _useState5 = useState(true),
+    _useState6 = _slicedToArray(_useState5, 2),
+    subjectActive = _useState6[0],
+    setSubjectActive = _useState6[1];
+  var _useState7 = useState(initialVisible),
+    _useState8 = _slicedToArray(_useState7, 2),
+    tabVisible = _useState8[0],
+    setTabVisible = _useState8[1];
+  var _useState9 = useState(initialFocused),
+    _useState0 = _slicedToArray(_useState9, 2),
+    windowFocused = _useState0[0],
+    setWindowFocused = _useState0[1];
+  var reporterRef = useRef(null);
+  // Latest sensor readings, read by the DOM handlers to compute foreground.
+  var sensorRef = useRef({
+    tab: initialVisible(),
+    focus: initialFocused()
+  });
+
+  // Create + start the reporter once (re-created only if the channel changes).
+  useEffect(function () {
+    var reporter = createPresenceReporter({
+      channelName: config.channelName,
+      heartbeatInterval: config.heartbeatInterval,
+      activityTimeout: config.activityTimeout,
+      metadata: config.metadata,
+      debug: config.debug,
+      onConnected: config.onConnected,
+      onDisconnected: config.onDisconnected,
+      onChange: function onChange(state) {
+        setConnected(state.connected);
+        setSubjectActive(state.active);
+        if (state.sessionId) setSessionId(state.sessionId);
+      }
+    });
+    reporterRef.current = reporter;
+    reporter.start();
+    // Seed foreground state from the current sensors.
+    reporter.setVisible(sensorRef.current.tab && sensorRef.current.focus);
+    return function () {
+      reporter.stop();
+      reporterRef.current = null;
+    };
+  }, [config.channelName]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Activity sensors -> reporter.reportActivity()
+  useEffect(function () {
+    if (!config.trackActivity) return undefined;
+    var onActivity = function onActivity() {
+      var _reporterRef$current;
+      return (_reporterRef$current = reporterRef.current) === null || _reporterRef$current === void 0 ? void 0 : _reporterRef$current.reportActivity();
+    };
+    var events = ['mousemove', 'keydown', 'scroll', 'touchstart', 'click'];
+    events.forEach(function (event) {
+      return window.addEventListener(event, onActivity, {
+        passive: true
+      });
+    });
+    return function () {
+      return events.forEach(function (event) {
+        return window.removeEventListener(event, onActivity);
+      });
+    };
+  }, [config.trackActivity]);
+
+  // Visibility + focus sensors -> reporter.setVisible(foreground)
+  useEffect(function () {
+    if (!config.trackVisibility) return undefined;
+    var pushForeground = function pushForeground() {
+      var _reporterRef$current2;
+      (_reporterRef$current2 = reporterRef.current) === null || _reporterRef$current2 === void 0 || _reporterRef$current2.setVisible(sensorRef.current.tab && sensorRef.current.focus);
+    };
+    var onVisibility = function onVisibility() {
+      var visible = document.visibilityState !== 'hidden';
+      sensorRef.current.tab = visible;
+      setTabVisible(visible);
+      pushForeground();
+    };
+    var onFocus = function onFocus() {
+      sensorRef.current.focus = true;
+      setWindowFocused(true);
+      pushForeground();
+    };
+    var onBlur = function onBlur() {
+      sensorRef.current.focus = false;
+      setWindowFocused(false);
+      pushForeground();
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+    window.addEventListener('focus', onFocus);
+    window.addEventListener('blur', onBlur);
+    return function () {
+      document.removeEventListener('visibilitychange', onVisibility);
+      window.removeEventListener('focus', onFocus);
+      window.removeEventListener('blur', onBlur);
+    };
+  }, [config.trackVisibility]);
+  var sendHeartbeat = useCallback(function (overrides) {
+    var _reporterRef$current3;
+    (_reporterRef$current3 = reporterRef.current) === null || _reporterRef$current3 === void 0 || _reporterRef$current3.sendHeartbeat(overrides);
+  }, []);
+  return {
+    connected: connected,
+    sessionId: sessionId,
+    tabVisible: tabVisible,
+    windowFocused: windowFocused,
+    subjectActive: subjectActive,
+    sendHeartbeat: sendHeartbeat
+  };
+}
+
+var PresenceContext = /*#__PURE__*/createContext(null);
+var DEFAULT_CONFIG = {
+  channelName: 'WhereIsWaldo::PresenceChannel',
+  heartbeatInterval: 30000,
+  activityTimeout: 30000,
+  trackActivity: true,
+  trackVisibility: true,
+  debug: false
+};
+
+/**
+ * Get merged config from defaults, cable config, and overrides
+ */
+function getMergedConfig(configOverrides) {
+  var cableConfig = getCableConfig();
+  var presenceConfig = cableConfig.presence || {};
+  return _objectSpread2(_objectSpread2(_objectSpread2({}, DEFAULT_CONFIG), presenceConfig), configOverrides);
+}
+
+/**
+ * PresenceProvider - Provides real-time presence tracking and message handling
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} props.children
+ * @param {Object} props.metadata - Optional metadata to attach to presence
+ * @param {Object} props.config - Optional configuration overrides
+ * @param {Function} props.onConnected - Callback when connected
+ * @param {Function} props.onDisconnected - Callback when disconnected
+ */
+function PresenceProvider(_ref) {
+  var children = _ref.children,
+    _ref$metadata = _ref.metadata,
+    metadata = _ref$metadata === void 0 ? {} : _ref$metadata,
+    _ref$config = _ref.config,
+    configOverrides = _ref$config === void 0 ? {} : _ref$config,
+    onConnected = _ref.onConnected,
+    onDisconnected = _ref.onDisconnected;
+  var config = useMemo(function () {
+    return getMergedConfig(configOverrides);
+  }, [configOverrides]);
+
+  // Use the shared usePresence hook for all presence tracking
+  var presence = usePresence(_objectSpread2(_objectSpread2({}, config), {}, {
+    metadata: metadata,
+    onConnected: onConnected,
+    onDisconnected: onDisconnected
+  }));
+  return /*#__PURE__*/React.createElement(PresenceContext.Provider, {
+    value: presence
+  }, children);
+}
+
+/**
+ * Hook to access presence context
+ * @returns {Object} Presence context value
+ */
+function usePresenceContext() {
+  var context = useContext(PresenceContext);
+  if (!context) {
+    throw new Error('usePresenceContext must be used within a PresenceProvider');
+  }
+  return context;
+}
+
+/**
+ * useWaldoEvent - subscribe a component to one or more raw real-time event types.
+ *
+ * The component subscribes to a message `type` (or an array of types) and
+ * receives the payload on every matching cable event; it decides for itself
+ * whether it cares about a given record (e.g. `if (data.project_id === myId)
+ * ...`). The subscription is automatically torn down when the component
+ * unmounts ("out of view"), exactly like a useEffect cleanup.
+ *
+ * The handler is held in a ref so it always sees the latest props/state without
+ * re-subscribing on every render — callers do NOT need to memoize it. The
+ * subscription is re-created only when the type(s) / `enabled` change.
+ *
+ * This is a pure subscription primitive — it has no timing/debounce concern.
+ * To coalesce a burst of events, compose with a debounce at the call site, e.g.
+ * corebyscott's `useDebouncedCallback`:
+ *
+ *   const refetch = useDebouncedCallback(loadAll, 250);
+ *   useWaldoEvent(['issue_update', 'project_update'], refetch);
+ *
+ * @param {string|string[]} type - Cable message type(s), e.g. 'issue_update'
+ * @param {Function} handler - Called with (data, message) on each event
+ * @param {Object} [options]
+ * @param {boolean} [options.enabled=true] - When false, no subscription is made
+ *
+ * @example
+ *   useWaldoEvent('issue_update', (data) => {
+ *     if (data.id === issueId) setIssue((prev) => ({ ...prev, ...data }));
+ *   });
+ */
+function useWaldoEvent(type, handler) {
+  var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  var _options$enabled = options.enabled,
+    enabled = _options$enabled === void 0 ? true : _options$enabled;
+  var handlerRef = useRef(handler);
+
+  // Keep the ref pointing at the latest handler every render.
+  useEffect(function () {
+    handlerRef.current = handler;
+  });
+
+  // Stable, order-insensitive key so an inline array literal doesn't
+  // re-subscribe on every render.
+  var types = Array.isArray(type) ? type : [type];
+  var typesKey = types.filter(Boolean).join(' ');
+  useEffect(function () {
+    if (!enabled || !typesKey) return undefined;
+    var typeList = typesKey.split(' ');
+    var onEvent = function onEvent(data, message) {
+      if (handlerRef.current) handlerRef.current(data, message);
+    };
+    var unsubscribes = typeList.map(function (t) {
+      return subscribeToEvent(t, onEvent);
+    });
+    return function () {
+      unsubscribes.forEach(function (unsub) {
+        return unsub();
+      });
+    };
+  }, [typesKey, enabled]);
+}
+
+// Framework-agnostic roster store: pure JS, no DOM and no React Native APIs, so
+// it is safe to import from the web package AND the mobile (React Native)
+// package. It owns the "materialize full state from a snapshot + transition
+// deltas" logic and the derivations over it (per-device roll-up, sorting,
+// labels, colors) — everything except the sensors and the pixels, which are
+// necessarily platform-specific.
+
+// Cable message types exchanged on the roster stream.
+var ROSTER_SNAPSHOT = 'roster_snapshot';
+var ROSTER_DELTA = 'roster_delta';
+// Content-free "re-poll now" trigger (:nudge mode). Carries no data.
+var ROSTER_NUDGE = 'roster_nudge';
+
+// Activity ranking, most-present first. Shared by sorting and by the "highest
+// across devices" roll-up so web and mobile agree.
+var STATUS_RANK = {
+  active: 3,
+  idle: 2,
+  background: 1,
+  offline: 0
+};
+
+// Status -> presence dot color. Platform UIs may theme these, but sharing a
+// default keeps web and mobile visually consistent out of the box.
+var STATUS_COLORS = {
+  active: '#22c55e',
+  // visible + working
+  idle: '#f59e0b',
+  // visible but not actively using
+  background: '#9ca3af',
+  // only backgrounded/hidden sessions
+  offline: '#d1d5db' // no live sessions
+};
+function presenceColor(status) {
+  return STATUS_COLORS[status] || STATUS_COLORS.offline;
+}
+
+/**
+ * Apply an incoming cable message to a members Map (keyed by subject id),
+ * returning a NEW Map (immutable update) so callers can trigger re-renders by
+ * identity. Unknown message types return the same Map unchanged.
+ *
+ * - snapshot: replaces the whole roster.
+ * - delta: upserts one member. Offline members are KEPT (status "offline") so
+ *   the roster stays the full team with live dots rather than vanishing rows.
+ *
+ * @param {Map<any, Object>} map - current members map
+ * @param {Object} message - { type, members? , member? }
+ * @returns {Map<any, Object>}
+ */
+function applyRosterMessage(map, message) {
+  if (!message || !message.type) return map;
+  if (message.type === ROSTER_SNAPSHOT) {
+    var next = new Map();
+    (message.members || []).forEach(function (m) {
+      return next.set(m.id, m);
+    });
+    return next;
+  }
+  if (message.type === ROSTER_DELTA && message.member) {
+    var _next = new Map(map);
+    if (message.member._removed) {
+      // Member left the viewer's visible scope (a visibility change) — drop it.
+      // Distinct from going offline, which arrives as status "offline".
+      _next["delete"](message.member.id);
+    } else {
+      _next.set(message.member.id, message.member);
+    }
+    return _next;
+  }
+  return map;
+}
+
+/**
+ * Modes that require the client to poll the server for deltas (vs. passively
+ * receiving pushed broadcasts). The server declares the mode in the snapshot.
+ */
+function isPollMode(mode) {
+  return mode === 'poll' || mode === 'nudge';
+}
+
+/**
+ * Members Map -> array, sorted most-present first then by display label.
+ */
+function sortedMembers(map) {
+  var list = Array.from(map.values());
+  list.sort(function (a, b) {
+    var _STATUS_RANK$b$status, _STATUS_RANK$a$status;
+    var rank = ((_STATUS_RANK$b$status = STATUS_RANK[b.status]) !== null && _STATUS_RANK$b$status !== void 0 ? _STATUS_RANK$b$status : 0) - ((_STATUS_RANK$a$status = STATUS_RANK[a.status]) !== null && _STATUS_RANK$a$status !== void 0 ? _STATUS_RANK$a$status : 0);
+    if (rank !== 0) return rank;
+    return String(memberLabel(a)).localeCompare(String(memberLabel(b)));
+  });
+  return list;
+}
+
+/**
+ * Only members with a live session (status !== "offline").
+ */
+function onlineMembers(members) {
+  return members.filter(function (m) {
+    return m.status && m.status !== 'offline';
+  });
+}
+
+/**
+ * That member's status on a specific device/platform, e.g.
+ *   deviceStatus(member, 'mobile') // => "idle"
+ * Answers "is the user active on mobile?" vs the overall member.status.
+ */
+function deviceStatus(member, platform) {
+  return member && member.devices && member.devices[platform] || 'offline';
+}
+
+/**
+ * Best-effort display label from a member's subject data.
+ */
+function memberLabel(member) {
+  if (!member) return '';
+  return member.name || [member.first_name, member.last_name].filter(Boolean).join(' ') || member.email || member.username || "#".concat(member.id);
+}
+
+var DEFAULT_CHANNEL = 'WhereIsWaldo::RosterChannel';
+var DEFAULT_POLL_INTERVAL = 15; // seconds; overridden by the server's snapshot
+var DEFAULT_NUDGE_JITTER = 0.5; // seconds; overridden by the server's snapshot
+
+/**
+ * usePresenceRoster - live "who's around" roster as data (bring your own UI).
+ *
+ * The server picks the delivery mode per account and declares it in the initial
+ * snapshot. This hook adapts transparently — no client mode config:
+ *   - broadcast/fanout : passively receive pushed deltas.
+ *   - pull/nudge       : poll the server (`perform('poll')`) on the interval the
+ *                        server specifies; the server replies with a filtered
+ *                        snapshot (resync) or diff.
+ * Either way the shared reducer (../core/rosterStore) keeps `members` as the
+ * full, live set (snapshot seeded, deltas patched, removals dropped).
+ *
+ * Each member: { id, status, devices: { web, mobile, ... }, ...subjectData }.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.channelName] - override the roster channel name
+ * @param {boolean} [options.enabled=true] - when false, no subscription is made
+ * @param {Function} [options.filter] - (member) => boolean. Client-side filter
+ *   applied to the returned members. COSMETIC ONLY — intended for `:broadcast`
+ *   mode, where the full account roster reaches the client and you want to hide
+ *   some rows in the UI. It is NOT an access-control boundary (the unfiltered
+ *   data is already on the client). For enforced visibility use a server-side
+ *   mode (`:poll`/`:nudge`/`:fanout`).
+ * @returns {{ members: Array, online: Array, onlineCount: number,
+ *             byId: Object, connected: boolean, mode: string|null }}
+ */
+function usePresenceRoster() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var _options$channelName = options.channelName,
+    channelName = _options$channelName === void 0 ? DEFAULT_CHANNEL : _options$channelName,
+    _options$enabled = options.enabled,
+    enabled = _options$enabled === void 0 ? true : _options$enabled,
+    filter = options.filter;
+  var _useState = useState([]),
+    _useState2 = _slicedToArray(_useState, 2),
+    members = _useState2[0],
+    setMembers = _useState2[1];
+  var _useState3 = useState(false),
+    _useState4 = _slicedToArray(_useState3, 2),
+    connected = _useState4[0],
+    setConnected = _useState4[1];
+  var _useState5 = useState(null),
+    _useState6 = _slicedToArray(_useState5, 2),
+    mode = _useState6[0],
+    setMode = _useState6[1];
+  var mapRef = useRef(new Map());
+  var pollTimerRef = useRef(null);
+  var nudgeTimerRef = useRef(null);
+  var nudgeJitterRef = useRef(DEFAULT_NUDGE_JITTER);
+  var flush = useCallback(function () {
+    setMembers(sortedMembers(mapRef.current));
+  }, []);
+  useEffect(function () {
+    if (!enabled) return undefined;
+    var consumer = getConsumer();
+    var startPolling = function startPolling(subscription, intervalSeconds) {
+      if (pollTimerRef.current) return; // already polling
+      var ms = (intervalSeconds || DEFAULT_POLL_INTERVAL) * 1000;
+      // Small random offset so clients don't poll in lockstep (herd control).
+      var jitter = function jitter() {
+        return 0.85 + Math.random() * 0.3;
+      };
+      var _tick = function tick() {
+        subscription.perform('poll');
+        pollTimerRef.current = setTimeout(_tick, ms * jitter());
+      };
+      pollTimerRef.current = setTimeout(_tick, ms * jitter());
+    };
+
+    // :nudge — on a content-free trigger, re-poll off-cycle after a random
+    // jitter (herd control), debounced to one pending re-poll at a time.
+    var scheduleNudgePoll = function scheduleNudgePoll(subscription) {
+      if (nudgeTimerRef.current) return;
+      var delay = Math.random() * nudgeJitterRef.current * 1000;
+      nudgeTimerRef.current = setTimeout(function () {
+        nudgeTimerRef.current = null;
+        subscription.perform('poll');
+      }, delay);
+    };
+    var subscription = consumer.subscriptions.create({
+      channel: channelName
+    }, {
+      connected: function connected() {
+        setConnected(true);
+      },
+      disconnected: function disconnected() {
+        setConnected(false);
+      },
+      received: function received(message) {
+        if (message && message.type === ROSTER_SNAPSHOT) {
+          setMode(message.mode || null);
+          if (message.nudge_jitter != null) nudgeJitterRef.current = message.nudge_jitter;
+          if (isPollMode(message.mode)) startPolling(subscription, message.poll_interval);
+        }
+        if (message && message.type === ROSTER_NUDGE) {
+          scheduleNudgePoll(subscription);
+          return; // content-free trigger; nothing to reduce
+        }
+        var next = applyRosterMessage(mapRef.current, message);
+        if (next !== mapRef.current) {
+          mapRef.current = next;
+          flush();
+        }
+      }
+    });
+    return function () {
+      if (pollTimerRef.current) {
+        clearTimeout(pollTimerRef.current);
+        pollTimerRef.current = null;
+      }
+      if (nudgeTimerRef.current) {
+        clearTimeout(nudgeTimerRef.current);
+        nudgeTimerRef.current = null;
+      }
+      subscription.unsubscribe();
+    };
+  }, [channelName, enabled, flush]);
+
+  // Client-side (cosmetic) filter — see options.filter.
+  var visibleMembers = filter ? members.filter(filter) : members;
+  var online = onlineMembers(visibleMembers);
+  var byId = {};
+  visibleMembers.forEach(function (m) {
+    byId[m.id] = m;
+  });
+  return {
+    members: visibleMembers,
+    online: online,
+    onlineCount: online.length,
+    byId: byId,
+    connected: connected,
+    mode: mode
+  };
+}
+
+export { PresenceContext, PresenceProvider, ROSTER_DELTA, ROSTER_SNAPSHOT, STATUS_COLORS, STATUS_RANK, applyRosterMessage, configureCable, createPresenceReporter, deviceStatus, disconnectCable, getCableConfig, getConsumer, handleMessage, memberLabel, onlineMembers, presenceColor, sortedMembers, subscribeToEvent, usePresence, usePresenceContext, usePresenceRoster, useWaldoEvent };
+//# sourceMappingURL=index.esm.js.map