@byscott-io/where-is-waldo 0.1.0

package/src/core/rosterStore.js

@@ -0,0 +1,117 @@
+// 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.
+export const ROSTER_SNAPSHOT = 'roster_snapshot';
+export const ROSTER_DELTA = 'roster_delta';
+// Content-free "re-poll now" trigger (:nudge mode). Carries no data.
+export const 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.
+export const 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.
+export const STATUS_COLORS = {
+  active: '#22c55e', // visible + working
+  idle: '#f59e0b', // visible but not actively using
+  background: '#9ca3af', // only backgrounded/hidden sessions
+  offline: '#d1d5db', // no live sessions
+};
+
+export 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>}
+ */
+export function applyRosterMessage(map, message) {
+  if (!message || !message.type) return map;
+
+  if (message.type === ROSTER_SNAPSHOT) {
+    const next = new Map();
+    (message.members || []).forEach((m) => next.set(m.id, m));
+    return next;
+  }
+
+  if (message.type === ROSTER_DELTA && message.member) {
+    const 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.
+ */
+export function isPollMode(mode) {
+  return mode === 'poll' || mode === 'nudge';
+}
+
+/**
+ * Members Map -> array, sorted most-present first then by display label.
+ */
+export function sortedMembers(map) {
+  const list = Array.from(map.values());
+  list.sort((a, b) => {
+    const rank = (STATUS_RANK[b.status] ?? 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").
+ */
+export function onlineMembers(members) {
+  return members.filter((m) => 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.
+ */
+export function deviceStatus(member, platform) {
+  return (member && member.devices && member.devices[platform]) || 'offline';
+}
+
+/**
+ * Best-effort display label from a member's subject data.
+ */
+export function memberLabel(member) {
+  if (!member) return '';
+  return (
+    member.name ||
+    [member.first_name, member.last_name].filter(Boolean).join(' ') ||
+    member.email ||
+    member.username ||
+    `#${member.id}`
+  );
+}

package/src/hooks/usePresence.js

@@ -0,0 +1,122 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { createPresenceReporter } from '../core/presenceReporter';
+
+const DEFAULT_OPTIONS = {
+  channelName: 'WhereIsWaldo::PresenceChannel',
+  heartbeatInterval: 30000,
+  activityTimeout: 30000,
+  trackActivity: true,
+  trackVisibility: true,
+  debug: false,
+};
+
+const initialVisible = () =>
+  typeof document === 'undefined' ? true : document.visibilityState !== 'hidden';
+const initialFocused = () =>
+  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 }}
+ */
+export function usePresence(options = {}) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+
+  const [connected, setConnected] = useState(false);
+  const [sessionId, setSessionId] = useState(null);
+  const [subjectActive, setSubjectActive] = useState(true);
+  const [tabVisible, setTabVisible] = useState(initialVisible);
+  const [windowFocused, setWindowFocused] = useState(initialFocused);
+
+  const reporterRef = useRef(null);
+  // Latest sensor readings, read by the DOM handlers to compute foreground.
+  const sensorRef = useRef({ tab: initialVisible(), focus: initialFocused() });
+
+  // Create + start the reporter once (re-created only if the channel changes).
+  useEffect(() => {
+    const reporter = createPresenceReporter({
+      channelName: config.channelName,
+      heartbeatInterval: config.heartbeatInterval,
+      activityTimeout: config.activityTimeout,
+      metadata: config.metadata,
+      debug: config.debug,
+      onConnected: config.onConnected,
+      onDisconnected: config.onDisconnected,
+      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 () => {
+      reporter.stop();
+      reporterRef.current = null;
+    };
+  }, [config.channelName]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Activity sensors -> reporter.reportActivity()
+  useEffect(() => {
+    if (!config.trackActivity) return undefined;
+
+    const onActivity = () => reporterRef.current?.reportActivity();
+    const events = ['mousemove', 'keydown', 'scroll', 'touchstart', 'click'];
+    events.forEach((event) => window.addEventListener(event, onActivity, { passive: true }));
+
+    return () => events.forEach((event) => window.removeEventListener(event, onActivity));
+  }, [config.trackActivity]);
+
+  // Visibility + focus sensors -> reporter.setVisible(foreground)
+  useEffect(() => {
+    if (!config.trackVisibility) return undefined;
+
+    const pushForeground = () => {
+      reporterRef.current?.setVisible(sensorRef.current.tab && sensorRef.current.focus);
+    };
+    const onVisibility = () => {
+      const visible = document.visibilityState !== 'hidden';
+      sensorRef.current.tab = visible;
+      setTabVisible(visible);
+      pushForeground();
+    };
+    const onFocus = () => {
+      sensorRef.current.focus = true;
+      setWindowFocused(true);
+      pushForeground();
+    };
+    const onBlur = () => {
+      sensorRef.current.focus = false;
+      setWindowFocused(false);
+      pushForeground();
+    };
+
+    document.addEventListener('visibilitychange', onVisibility);
+    window.addEventListener('focus', onFocus);
+    window.addEventListener('blur', onBlur);
+
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibility);
+      window.removeEventListener('focus', onFocus);
+      window.removeEventListener('blur', onBlur);
+    };
+  }, [config.trackVisibility]);
+
+  const sendHeartbeat = useCallback((overrides) => {
+    reporterRef.current?.sendHeartbeat(overrides);
+  }, []);
+
+  return { connected, sessionId, tabVisible, windowFocused, subjectActive, sendHeartbeat };
+}
+
+export default usePresence;

package/src/hooks/useRoster.js

@@ -0,0 +1,138 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { getConsumer } from '../cable';
+import {
+  applyRosterMessage,
+  sortedMembers,
+  onlineMembers,
+  isPollMode,
+  ROSTER_SNAPSHOT,
+  ROSTER_NUDGE,
+} from '../core/rosterStore';
+
+const DEFAULT_CHANNEL = 'WhereIsWaldo::RosterChannel';
+const DEFAULT_POLL_INTERVAL = 15; // seconds; overridden by the server's snapshot
+const 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 }}
+ */
+export function usePresenceRoster(options = {}) {
+  const { channelName = DEFAULT_CHANNEL, enabled = true, filter } = options;
+
+  const [members, setMembers] = useState([]);
+  const [connected, setConnected] = useState(false);
+  const [mode, setMode] = useState(null);
+
+  const mapRef = useRef(new Map());
+  const pollTimerRef = useRef(null);
+  const nudgeTimerRef = useRef(null);
+  const nudgeJitterRef = useRef(DEFAULT_NUDGE_JITTER);
+
+  const flush = useCallback(() => {
+    setMembers(sortedMembers(mapRef.current));
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) return undefined;
+
+    const consumer = getConsumer();
+
+    const startPolling = (subscription, intervalSeconds) => {
+      if (pollTimerRef.current) return; // already polling
+      const ms = (intervalSeconds || DEFAULT_POLL_INTERVAL) * 1000;
+      // Small random offset so clients don't poll in lockstep (herd control).
+      const jitter = () => 0.85 + Math.random() * 0.3;
+      const 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.
+    const scheduleNudgePoll = (subscription) => {
+      if (nudgeTimerRef.current) return;
+      const delay = Math.random() * nudgeJitterRef.current * 1000;
+      nudgeTimerRef.current = setTimeout(() => {
+        nudgeTimerRef.current = null;
+        subscription.perform('poll');
+      }, delay);
+    };
+
+    const subscription = consumer.subscriptions.create(
+      { channel: channelName },
+      {
+        connected() {
+          setConnected(true);
+        },
+        disconnected() {
+          setConnected(false);
+        },
+        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
+          }
+          const next = applyRosterMessage(mapRef.current, message);
+          if (next !== mapRef.current) {
+            mapRef.current = next;
+            flush();
+          }
+        },
+      }
+    );
+
+    return () => {
+      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.
+  const visibleMembers = filter ? members.filter(filter) : members;
+  const online = onlineMembers(visibleMembers);
+  const byId = {};
+  visibleMembers.forEach((m) => {
+    byId[m.id] = m;
+  });
+
+  return { members: visibleMembers, online, onlineCount: online.length, byId, connected, mode };
+}
+
+export default usePresenceRoster;

package/src/hooks/useWaldoEvent.js

@@ -0,0 +1,63 @@
+import { useEffect, useRef } from 'react';
+import { subscribeToEvent } from '../cable';
+
+/**
+ * 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 }));
+ *   });
+ */
+export function useWaldoEvent(type, handler, options = {}) {
+  const { enabled = true } = options;
+  const handlerRef = useRef(handler);
+
+  // Keep the ref pointing at the latest handler every render.
+  useEffect(() => {
+    handlerRef.current = handler;
+  });
+
+  // Stable, order-insensitive key so an inline array literal doesn't
+  // re-subscribe on every render.
+  const types = Array.isArray(type) ? type : [type];
+  const typesKey = types.filter(Boolean).join(' ');
+
+  useEffect(() => {
+    if (!enabled || !typesKey) return undefined;
+    const typeList = typesKey.split(' ');
+
+    const onEvent = (data, message) => {
+      if (handlerRef.current) handlerRef.current(data, message);
+    };
+
+    const unsubscribes = typeList.map((t) => subscribeToEvent(t, onEvent));
+    return () => {
+      unsubscribes.forEach((unsub) => unsub());
+    };
+  }, [typesKey, enabled]);
+}
+
+export default useWaldoEvent;

package/src/index.js

@@ -0,0 +1,41 @@
+// Cable management
+export {
+  configureCable,
+  getConsumer,
+  disconnectCable,
+  getCableConfig,
+  handleMessage,
+  subscribeToEvent,
+} from './cable';
+
+// Context and Provider
+export {
+  PresenceProvider,
+  usePresenceContext,
+  default as PresenceContext,
+} from './context/PresenceContext';
+
+// Hooks
+export { usePresence } from './hooks/usePresence';
+export { useWaldoEvent } from './hooks/useWaldoEvent';
+export { usePresenceRoster } from './hooks/useRoster';
+
+// Framework-agnostic presence reporter core (no DOM) — the shared session-state
+// -> heartbeat state machine that usePresence wraps and a React Native reporter
+// reuses. See docs for mobile wiring.
+export { createPresenceReporter } from './core/presenceReporter';
+
+// Roster core helpers (pure JS, no DOM — shared with the mobile package). Build
+// your own UI with these; nothing here renders.
+export {
+  applyRosterMessage,
+  sortedMembers,
+  onlineMembers,
+  deviceStatus,
+  memberLabel,
+  presenceColor,
+  STATUS_COLORS,
+  STATUS_RANK,
+  ROSTER_SNAPSHOT,
+  ROSTER_DELTA,
+} from './core/rosterStore';