slopfixing / issue 004

2026-09-16 09:31:20 -04:00 · 2026-06-12 12:33:00 -04:00
parent dc193d09db
commit cc06709674
29 changed files with 855 additions and 338 deletions
@@ -2,19 +2,72 @@
 // Purpose: Maintains shared telemetry snapshots and rover status streams for UI consumers. Scope: Subscribes to telemetry events and exposes normalized read APIs to components.
 /* eslint-disable react-refresh/only-export-components */

-import { createContext, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { useSocket } from './SocketContext.jsx';
+import { useSessionSelector } from './SessionContext.jsx';

 const EMPTY_FRAMES = Object.freeze({});
 const EMPTY_FRAME = null;
+const DEFAULT_VISUAL_THROTTLE_MS = 250;

 const TelemetryContext = createContext(null);

+export function shallowArrayEqual(left, right) {
+  if (Object.is(left, right)) return true;
+  if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+  for (let idx = 0; idx < left.length; idx += 1) {
+    if (!Object.is(left[idx], right[idx])) return false;
+  }
+  return true;
+}
+
+export function shallowObjectEqual(left, right) {
+  if (Object.is(left, right)) return true;
+  if (!left || !right || typeof left !== 'object' || typeof right !== 'object') return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+  for (const key of leftKeys) {
+    if (!Object.prototype.hasOwnProperty.call(right, key) || !Object.is(left[key], right[key])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function selectFrameIdentity(frame) {
+  return frame;
+}
+
 export function TelemetryProvider({ children }) {
  const socket = useSocket();
+  const sessionRole = useSessionSelector((state) => state.session?.role || null);
  const framesRef = useRef({});
  const roverSubscribersRef = useRef(new Map());
  const allSubscribersRef = useRef(new Set());
+  const visualAllSubscribersRef = useRef(new Set());
+  const selectorSubscribersRef = useRef(new Map());
+  const pendingVisualRoversRef = useRef(new Set());
+  const visualAllPendingRef = useRef(false);
+  const sessionRoleRef = useRef(sessionRole);
+  const visualPolicyRef = useRef({ mobile: false });
+  const visualTimerRef = useRef(null);
+  sessionRoleRef.current = sessionRole;
+
+  const defaultVisualThrottleMs = () => {
+    // The throttle policy is intentionally sourced from existing app state:
+    // session role identifies spectator-style pages, and App publishes its
+    // already-computed layout mode. Telemetry should not independently inspect
+    // paths or viewport dimensions because that would duplicate page policy and
+    // drift from the rest of the UI.
+    const spectator = sessionRoleRef.current === 'spectator';
+    const mobile = Boolean(visualPolicyRef.current.mobile);
+    return spectator || mobile ? DEFAULT_VISUAL_THROTTLE_MS : 0;
+  };
+
+  const throttleMsForEntry = (entry) => (
+    Number.isFinite(entry.throttleMs) ? entry.throttleMs : defaultVisualThrottleMs()
+  );

  const notifyRover = (roverId) => {
    const listeners = roverSubscribersRef.current.get(roverId);
@@ -24,6 +77,79 @@ export function TelemetryProvider({ children }) {
    allSubscribersRef.current.forEach((listener) => listener());
  };

+  const evaluateSelectorEntries = (roverId, entries) => {
+    const frame = framesRef.current[roverId] ?? EMPTY_FRAME;
+    entries.forEach((entry) => {
+      const nextValue = entry.selector(frame);
+      if (entry.equalityFn(entry.currentValue, nextValue)) return;
+      entry.currentValue = nextValue;
+      entry.listener(nextValue);
+    });
+  };
+
+  const notifyRawSelectors = (roverId) => {
+    const entries = selectorSubscribersRef.current.get(roverId);
+    if (!entries) return;
+    evaluateSelectorEntries(
+      roverId,
+      [...entries].filter((entry) => entry.mode !== 'visual'),
+    );
+  };
+
+  const flushVisualSelectors = () => {
+    visualTimerRef.current = null;
+    const roverIds = [...pendingVisualRoversRef.current];
+    pendingVisualRoversRef.current.clear();
+    roverIds.forEach((roverId) => {
+      const entries = selectorSubscribersRef.current.get(roverId);
+      if (!entries) return;
+      evaluateSelectorEntries(
+        roverId,
+        [...entries].filter((entry) => entry.mode === 'visual' && entry.throttleMs > 0),
+      );
+    });
+    if (visualAllPendingRef.current) {
+      visualAllPendingRef.current = false;
+      visualAllSubscribersRef.current.forEach((listener) => listener());
+    }
+  };
+
+  const notifyVisualSelectors = (roverId) => {
+    const entries = selectorSubscribersRef.current.get(roverId);
+    if (!entries) return;
+    const visualEntries = [...entries].filter((entry) => entry.mode === 'visual');
+    const immediateEntries = visualEntries.filter((entry) => throttleMsForEntry(entry) <= 0);
+    const throttledEntries = visualEntries.filter((entry) => throttleMsForEntry(entry) > 0);
+
+    // Desktop visual subscriptions still benefit from field-level selectors, but
+    // they do not need cadence throttling. Evaluate those entries immediately so
+    // desktop dashboards keep the same responsiveness they had before this change.
+    if (immediateEntries.length) {
+      evaluateSelectorEntries(roverId, immediateEntries);
+    }
+    if (!throttledEntries.length) return;
+
+    pendingVisualRoversRef.current.add(roverId);
+    if (visualTimerRef.current) return;
+
+    const delay = throttledEntries.reduce(
+      (lowest, entry) => Math.min(lowest, throttleMsForEntry(entry)),
+      DEFAULT_VISUAL_THROTTLE_MS,
+    );
+    visualTimerRef.current = setTimeout(flushVisualSelectors, delay);
+  };
+
+  const notifyVisualAll = () => {
+    const throttleMs = defaultVisualThrottleMs();
+    if (throttleMs <= 0) {
+      visualAllSubscribersRef.current.forEach((listener) => listener());
+      return;
+    }
+    visualAllPendingRef.current = true;
+    if (visualTimerRef.current) return;
+    visualTimerRef.current = setTimeout(flushVisualSelectors, throttleMs);
+  };
+
  const store = useMemo(
    () => ({
      getFrames: () => framesRef.current,
@@ -37,6 +163,18 @@ export function TelemetryProvider({ children }) {
          allSubscribersRef.current.delete(listener);
        };
      },
+      subscribeAllVisual: (listener) => {
+        visualAllSubscribersRef.current.add(listener);
+        return () => {
+          visualAllSubscribersRef.current.delete(listener);
+        };
+      },
+      setVisualPolicy: (policy = {}) => {
+        visualPolicyRef.current = {
+          ...visualPolicyRef.current,
+          ...policy,
+        };
+      },
      subscribeRover: (roverId, listener) => {
        if (!roverId) return () => {};
        let listeners = roverSubscribersRef.current.get(roverId);
@@ -54,6 +192,40 @@ export function TelemetryProvider({ children }) {
          }
        };
      },
+      subscribeSelector: (roverId, selector, listener, equalityFn = Object.is, options = {}) => {
+        if (!roverId || typeof selector !== 'function') return () => {};
+        let listeners = selectorSubscribersRef.current.get(roverId);
+        if (!listeners) {
+          listeners = new Set();
+          selectorSubscribersRef.current.set(roverId, listeners);
+        }
+
+        const mode = options.mode === 'visual' ? 'visual' : 'raw';
+        const throttleMs =
+          mode === 'visual' && Number.isFinite(options.throttleMs)
+            ? Math.max(0, options.throttleMs)
+            : null;
+        const entry = {
+          selector,
+          listener,
+          equalityFn,
+          mode,
+          throttleMs,
+          // The current value is stored with the subscription so selector
+          // equality is checked before React is notified. This keeps unrelated
+          // sensor fields from invalidating components that do not read them.
+          currentValue: selector(framesRef.current[roverId] ?? EMPTY_FRAME),
+        };
+        listeners.add(entry);
+        return () => {
+          const current = selectorSubscribersRef.current.get(roverId);
+          if (!current) return;
+          current.delete(entry);
+          if (!current.size) {
+            selectorSubscribersRef.current.delete(roverId);
+          }
+        };
+      },
    }),
    [],
  );
@@ -73,6 +245,9 @@ export function TelemetryProvider({ children }) {
        },
      };
      notifyRover(roverId);
+      notifyRawSelectors(roverId);
+      notifyVisualSelectors(roverId);
+      notifyVisualAll();
    }

    function handleRoverHostStats({ roverId, stats = {}, receivedAt = null }) {
@@ -92,6 +267,9 @@ export function TelemetryProvider({ children }) {
        },
      };
      notifyRover(roverId);
+      notifyRawSelectors(roverId);
+      notifyVisualSelectors(roverId);
+      notifyVisualAll();
    }

    socket.on('sensorFrame', handleSensorFrame);
@@ -99,7 +277,16 @@ export function TelemetryProvider({ children }) {
    return () => {
      socket.off('sensorFrame', handleSensorFrame);
      socket.off('roverHostStats', handleRoverHostStats);
+      if (visualTimerRef.current) {
+        clearTimeout(visualTimerRef.current);
+        visualTimerRef.current = null;
+      }
    };
+    // The notification helpers above read only refs and constants; tying this
+    // socket subscription to their render-time identities would churn socket
+    // listeners without changing what data they read. The socket object is the
+    // actual external dependency that should resubscribe this effect.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [socket]);

  return <TelemetryContext.Provider value={store}>{children}</TelemetryContext.Provider>;
@@ -113,6 +300,29 @@ export function useTelemetryFrames() {
  return useSyncExternalStore(store.subscribeAll, store.getFrames, () => EMPTY_FRAMES);
 }

+export function useVisualTelemetryFrames() {
+  const store = useContext(TelemetryContext);
+  if (!store) {
+    throw new Error('useVisualTelemetryFrames must be used within TelemetryProvider');
+  }
+  return useSyncExternalStore(store.subscribeAllVisual, store.getFrames, () => EMPTY_FRAMES);
+}
+
+export function useTelemetryVisualPolicy(policy) {
+  const store = useContext(TelemetryContext);
+  if (!store) {
+    throw new Error('useTelemetryVisualPolicy must be used within TelemetryProvider');
+  }
+
+  const mobile = Boolean(policy?.mobile);
+  useEffect(() => {
+    store.setVisualPolicy({ mobile });
+    return () => {
+      store.setVisualPolicy({ mobile: false });
+    };
+  }, [mobile, store]);
+}
+
 export function useTelemetryFrame(roverId) {
  const store = useContext(TelemetryContext);
  if (!store) {
@@ -124,3 +334,34 @@ export function useTelemetryFrame(roverId) {
    () => EMPTY_FRAME,
  );
 }
+
+export function useTelemetrySelector(roverId, selector = selectFrameIdentity, equalityFn = Object.is, options = {}) {
+  const store = useContext(TelemetryContext);
+  if (!store) {
+    throw new Error('useTelemetrySelector must be used within TelemetryProvider');
+  }
+  const mode = options.mode === 'visual' ? 'visual' : 'raw';
+  const throttleMs = Number.isFinite(options.throttleMs) ? Math.max(0, options.throttleMs) : undefined;
+  const [selectionState, setSelectionState] = useState(() => ({
+    roverId,
+    selector,
+    value: selector(store.getFrame(roverId)),
+  }));
+  const renderedSelected =
+    selectionState.roverId === roverId && selectionState.selector === selector
+      ? selectionState.value
+      : selector(store.getFrame(roverId));
+
+  useEffect(() => {
+    const publishSelected = (value) => {
+      setSelectionState({ roverId, selector, value });
+    };
+    return store.subscribeSelector(roverId, selector, publishSelected, equalityFn, { mode, throttleMs });
+  }, [equalityFn, mode, roverId, selector, store, throttleMs]);
+
+  return renderedSelected;
+}
+
+export function useVisualTelemetrySelector(roverId, selector, equalityFn = Object.is, options = {}) {
+  return useTelemetrySelector(roverId, selector, equalityFn, { ...options, mode: 'visual' });
+}