@adcops/autocore-react 3.3.9 → 3.3.14

package/src/core/EventEmitterContext.tsx

@@ -1,435 +1,435 @@
-/*
- * Copyright (C) 2024 Automated Design Corp. All Rights Reserved.
- * Created Date: 2024-01-17 11:45:10
- * -----
- * Last Modified: 2026-01-29 09:32:29
- * Modified By: ADC
- * -----
- *
- */
-
-/**
- * @fileoverview EventEmitterContext - Global Event Bus for AutoCore React Applications
- * 
- * The EventEmitterContext provides a comprehensive event-driven communication system for React applications,
- * enabling seamless interaction between components and backend services. It serves as the foundational layer
- * for AutoCore's real-time data flow and component communication architecture.
- * 
- * ## Core Features
- * 
- * - **Global Event Bus**: Publish and subscribe to events across all components.
- * - **Backend Integration**: Direct communication with AutoCore server via Hub abstraction.
- * - **Type-Safe Subscriptions**: Strongly-typed event handling with automatic cleanup.
- * - **Performance Optimized**: Uses stable context values and direct callbacks to avoid global re-renders.
- * - **Connection Management**: Automatic reconnection and state synchronization.
- * 
- * ## Architecture
- * 
- * The system consists of three main components:
- * 1. **EventEmitterProvider**: React context provider that manages global state and event routing.
- * 2. **Hub**: Abstraction layer for backend communication (WebSocket, HTTP, etc.).
- * 3. **Subscription Manager**: Handles event routing and lifecycle management.
- *
- * ## Performance Notes
- * 
- * To ensure high performance with high-frequency data (e.g., 50Hz sensor updates):
- * 1. **No State Updates on Dispatch**: The `dispatch` function does NOT update React state. It calls listeners directly.
- *    This prevents the entire component tree from re-rendering on every message.
- * 2. **Stable Context Value**: The `contextValue` object is memoized and rarely changes.
- * 3. **Direct Subscriptions**: Components subscribe via `useEffect` and receive updates via callbacks, not props.
- * 
- * @module core/EventEmitterContext
- * @version 3.0.42
- * @author Automated Design Corp.
- */
-
-import React, {
-  createContext,
-  useState,
-  useMemo,
-  useCallback,
-  useRef,
-  useEffect,
-} from "react";
-
-import type {ReactNode} from "react";
-import { createHub, Hub } from "../hub";
-import type { CommandMessage } from "../hub";
-import { MessageType } from "../hub/CommandMessage";
-import { enableDebugPanel } from "../hub/DebugPanel";
-
-export { Hub };
-
-/**
- * Represents an active event subscription.
- */
-export interface Subscription {
-  /** Unique ID of the subscription used for unsubscription. */
-  id: number;
-  /** Callback function to execute when the event fires. */
-  callback: React.Dispatch<any>;
-}
-
-/**
- * Represents the internal state of the EventEmitter.
- * Mostly used for debugging and dev tools inspection.
- */
-export interface State {
-  /**
-   * The optional data payload of the last event (DEBUGGING ONLY).
-   * Note: This is no longer updated in production for performance reasons.
-   */
-  eventData?: any;
-  /** Active subscriptions grouped by topic. */
-  subscriptions: Record<string, Subscription[]>;
-
-  /** Tracks the next subscription ID that will be assigned. */
-  nextSubscriptionId: number;
-}
-
-/**
- * An action event published by the EventEmitterContext.
- */
-export interface Action {
-  /** The topic or identifier of the event. */
-  topic: string;
-  /** The optional data payload associated with the event. */
-  payload?: any;
-}
-
-export type EmitterDispatchFunction = (action: Action) => void;
-
-/**
- * Defines the context for the global event emitter.
- * Provides methods for dispatching events, subscribing to topics, and communicating with the backend.
- */
-export interface EventEmitterContextType {
-  /**
-   * The current state of the event emitter (mostly for debugging).
-   */
-  state: State;
-
-  /**
-   * Dispatch an action globally throughout the front-end.
-   * Triggers callbacks for all subscribers of the topic.
-   * 
-   * @param action The action to dispatch.
-   */
-  dispatch: EmitterDispatchFunction;
-
-  /**
-   * Send a message to the backend (Low-level).
-   * 
-   * @param topic The FQDN of the resource (e.g., "ads.plc1.gio.bControlPowerOk")
-   * @param messageType The action to perform (Read, Write, Subscribe, etc.)
-   * @param payload Optional data payload
-   * @returns Promise resolving to the CommandMessage response
-   */
-  invoke(
-    topic: string,
-    messageType: MessageType,
-    payload?: object
-  ): Promise<CommandMessage>;
-
-  /**
-   * Read a value from the backend.
-   *
-   * @param topic The FQDN of the resource to read
-   * @param payload Optional additional parameters
-   * @returns Promise resolving to the CommandMessage response with the value in `data`
-   */
-  read(topic: string, payload?: object): Promise<CommandMessage>;
-
-  /**
-   * Write a value to the backend.
-   *
-   * @param topic The FQDN of the resource to write
-   * @param value The value to write
-   * @returns Promise resolving to the CommandMessage response
-   */
-  write(topic: string, value: any): Promise<CommandMessage>;
-
-  /**
-   * Subscribe to value changes on the backend.
-   *
-   * Tells the server to start broadcasting updates for a specific topic.
-   * Also registers a mapping between the local `tagName` and the remote `topic` (FQDN)
-   * in the Hub, so that incoming broadcasts are routed correctly.
-   *
-   * @param tagName The local tag name to map the topic to
-   * @param topic The FQDN of the resource to watch
-   * @param payload Optional subscription parameters (e.g., update rate)
-   * @returns Promise resolving to the CommandMessage response
-   */
-  serverSubscribe(tagName: string, topic: string, payload?: object): Promise<CommandMessage>;
-
-  /**
-   * Unsubscribe from value changes on the backend.
-   *
-   * @param tagName The local tag name to stop watching
-   * @param payload Optional parameters
-   * @returns Promise resolving to the CommandMessage response
-   */
-  serverUnsubscribe(tagName: string, payload?: object): Promise<CommandMessage>;
-
-  /**
-   * Subscribe to **local** frontend events.
-   * 
-   * This registers a callback to listen for events dispatched on the local event bus.
-   * This includes both locally dispatched events AND broadcast messages received
-   * from the server (which the Hub dispatches to the local bus).
-   *
-   * @param topic The subscription topic (or tagName).
-   * @param callback The callback to signal.
-   * @returns number Subscription ID used to unsubscribe later.
-   */
-  subscribe: (topic: string, callback: React.Dispatch<any>) => number;
-
-  /**
-   * Unsubscribe from **local** frontend events.
-   *
-   * @param subscriptionId The id returned by the subscribe method.
-   */
-  unsubscribe: (subscriptionId: number) => void;
-
-  /**
-   * Global hub instance for backend communication.
-   */
-  hub: Hub | null;
-
-  /**
-   * Retrieves the current subscriptions. Used for debugging purposes.
-   */
-  getSubscriptions: (
-    topic?: string
-  ) => Record<string, Subscription[]> | Subscription[];
-
-  /**
-   * Returns true if the Hub is connected to the backend.
-   */
-  isConnected: () => boolean;
-}
-
-// Default placeholder CommandMessage for context initialization
-const placeholderResponse: CommandMessage = {
-  data: {},
-  success: false,
-  error_message: "Context not initialized",
-  transaction_id: 0,
-  timecode: 0,
-  topic: "",
-  message_type: MessageType.NoOp
-};
-
-export const EventEmitterContext = createContext<EventEmitterContextType>({
-  state: { subscriptions: {}, nextSubscriptionId: 1 },
-  dispatch: () => {},
-  subscribe: () => 0,
-  unsubscribe: () => {},
-  invoke: async () => placeholderResponse,
-  read: async () => placeholderResponse,
-  write: async () => placeholderResponse,
-  serverSubscribe: async (_tagName: string, _topic: string, _payload?: object) => placeholderResponse,
-  serverUnsubscribe: async (_tagName: string, _payload?: object) => placeholderResponse,
-  hub: null,
-  getSubscriptions: () => [],
-  isConnected: () => false,
-});
-
-/**
- * A React component that provides the EventEmitterContext to its children.
- *
- * Wraps child components with the context, enabling them to access and interact
- * with the event emitter.
- *
- * @param children The child components to be wrapped in the context.
- */
-export const EventEmitterProvider: React.FC<{ children: ReactNode; debug?: boolean }> = ({
-  children,
-  debug = false,
-}) => {
-  console.log("[EventEmitterProvider] Rendering...");
-
-  // Enable the debug panel if requested (must run before Hub creation)
-  if (debug) {
-    enableDebugPanel();
-  }
-
-  const [state, setState] = useState<State>({
-    subscriptions: {},
-    nextSubscriptionId: 1,
-  });
-
-  // PERFORMANCE: Memoize the hub instance so it's only created once.
-  // This ensures the WebSocket connection persists across re-renders.
-  const hub = useMemo(() => {
-    console.log("[EventEmitterProvider] Creating Hub instance");
-    return createHub();
-  }, []);
-
-  // Use ref for subscription ID management (avoids global state issues)
-  const nextIdRef = useRef(1);
-
-  // Subscription storage - this is the single source of truth for local listeners
-  const subsRef = useRef<Record<string, Subscription[]>>({});
-
-  // Sync state with ref for debugging/inspection purposes only (on mount)
-  useEffect(() => {
-    setState(prev => ({
-      ...prev,
-      subscriptions: { ...subsRef.current },
-      nextSubscriptionId: nextIdRef.current
-    }));
-  }, []);
-
-  /**
-   * Dispatches an event to all listeners.
-   * 
-   * PERFORMANCE CRITICAL: This function iterates through listeners and calls them directly.
-   * It intentionally does NOT update React state (setState) to avoid triggering a 
-   * full app re-render on every high-frequency event.
-   */
-  const dispatch = useCallback((action: Action) => {
-    const { topic, payload } = action;
-
-    // Read from ref (single source of truth) and create a defensive copy
-    const listeners = subsRef.current[topic]?.slice() ?? [];
-    
-    // Execute callbacks synchronously to avoid timing issues
-    for (const sub of listeners) {
-      try {
-        sub.callback(payload);
-      } catch (e) {
-        console.error("[EventBus] listener error", e);
-      }
-    }
-
-    // NOTE: State update removed for performance. 
-    // Uncommenting this will cause the entire Provider to re-render on every event!
-    // setState((prev) => ({ ...prev, eventData: payload }));
-  }, []);
-
-  const subscribe = useCallback(
-    (topic: string, callback: React.Dispatch<any>): number => {
-      const id = nextIdRef.current++;
-      
-      // Create new subscription entry
-      const newSub: Subscription = { id, callback };
-      
-      // Atomically update the ref with a complete new structure
-      const currentSubs = subsRef.current[topic] ?? [];
-      const newSubs = [...currentSubs, newSub];
-      
-      subsRef.current = {
-        ...subsRef.current,
-        [topic]: newSubs
-      };
-
-      // Update state for debugging/inspection (less frequent than dispatch, so acceptable)
-      setState(prevState => ({
-        ...prevState,
-        subscriptions: { ...subsRef.current },
-        nextSubscriptionId: nextIdRef.current,
-      }));
-
-      return id;
-    },
-    []
-  );
-
-  const unsubscribe = useCallback((subscriptionId: number) => {
-    // Create a completely new structure to avoid mutation issues
-    const newSubscriptions: Record<string, Subscription[]> = {};
-    
-    for (const [topic, subs] of Object.entries(subsRef.current)) {
-      const filteredSubs = subs.filter(s => s.id !== subscriptionId);
-      if (filteredSubs.length > 0) {
-        newSubscriptions[topic] = filteredSubs;
-      }
-    }
-    
-    // Atomically replace the entire structure
-    subsRef.current = newSubscriptions;
-
-    // Update state for debugging/inspection
-    setState(prev => ({ 
-      ...prev, 
-      subscriptions: { ...newSubscriptions }
-    }));
-  }, []);
-
-  // Clean up on unmount
-  useEffect(() => {
-    return () => {
-      subsRef.current = {};
-      nextIdRef.current = 1;
-    };
-  }, []);
-
-  // Handle HMR so listeners don't leak across hot updates
-  if (import.meta && (import.meta as any).hot) {
-    (import.meta as any).hot.dispose(() => {
-      subsRef.current = {};
-      nextIdRef.current = 1;
-    });
-  }
-
-  // Memoize hub methods separately so they don't change when state changes.
-  // This prevents downstream useEffects from re-running due to function reference changes.
-  const invoke = useCallback(
-    (topic: string, messageType: MessageType, payload?: object) => hub.invoke(topic, messageType, payload),
-    [hub]
-  );
-  const read = useCallback(
-    (topic: string, payload?: object) => hub.read(topic, payload),
-    [hub]
-  );
-  const write = useCallback(
-    (topic: string, value: any) => hub.write(topic, value),
-    [hub]
-  );
-  const serverSubscribe = useCallback(
-    (tagName: string, topic: string, payload?: object) => hub.subscribe(tagName, topic, payload),
-    [hub]
-  );
-  const serverUnsubscribe = useCallback(
-    (tagName: string, payload?: object) => hub.unsubscribe(tagName, payload),
-    [hub]
-  );
-  const isConnected = useCallback(() => hub.isConnected(), [hub]);
-
-  // Provide the memoized context value
-  // PERFORMANCE: This object is memoized and its dependencies (dispatch, subscribe, etc.)
-  // are also memoized/stable. This means 'contextValue' reference rarely changes,
-  // preventing consumers (like App) from re-rendering unless necessary.
-  const contextValue = useMemo(
-    () => ({
-      state,
-      dispatch,
-      subscribe,
-      unsubscribe,
-      invoke,
-      read,
-      write,
-      serverSubscribe,
-      serverUnsubscribe,
-      hub,
-      getSubscriptions: (topic?: string) =>
-        topic ? subsRef.current[topic] ?? [] : subsRef.current,
-      isConnected,
-    }),
-    [state, hub, dispatch, subscribe, unsubscribe, invoke, read, write, serverSubscribe, serverUnsubscribe, isConnected]
-  );
-
-  // Set the context on the hub instance so it can dispatch back to us.
-  // Must be in useEffect to avoid side-effects during render phase.
-  useEffect(() => {
-    hub.setContext(contextValue);
-  }, [hub, contextValue]);
-
-  return (
-    <EventEmitterContext.Provider value={contextValue}>
-      {children}
-    </EventEmitterContext.Provider>
-  );
+/*
+ * Copyright (C) 2024 Automated Design Corp. All Rights Reserved.
+ * Created Date: 2024-01-17 11:45:10
+ * -----
+ * Last Modified: 2026-01-29 09:32:29
+ * Modified By: ADC
+ * -----
+ *
+ */
+
+/**
+ * @fileoverview EventEmitterContext - Global Event Bus for AutoCore React Applications
+ * 
+ * The EventEmitterContext provides a comprehensive event-driven communication system for React applications,
+ * enabling seamless interaction between components and backend services. It serves as the foundational layer
+ * for AutoCore's real-time data flow and component communication architecture.
+ * 
+ * ## Core Features
+ * 
+ * - **Global Event Bus**: Publish and subscribe to events across all components.
+ * - **Backend Integration**: Direct communication with AutoCore server via Hub abstraction.
+ * - **Type-Safe Subscriptions**: Strongly-typed event handling with automatic cleanup.
+ * - **Performance Optimized**: Uses stable context values and direct callbacks to avoid global re-renders.
+ * - **Connection Management**: Automatic reconnection and state synchronization.
+ * 
+ * ## Architecture
+ * 
+ * The system consists of three main components:
+ * 1. **EventEmitterProvider**: React context provider that manages global state and event routing.
+ * 2. **Hub**: Abstraction layer for backend communication (WebSocket, HTTP, etc.).
+ * 3. **Subscription Manager**: Handles event routing and lifecycle management.
+ *
+ * ## Performance Notes
+ * 
+ * To ensure high performance with high-frequency data (e.g., 50Hz sensor updates):
+ * 1. **No State Updates on Dispatch**: The `dispatch` function does NOT update React state. It calls listeners directly.
+ *    This prevents the entire component tree from re-rendering on every message.
+ * 2. **Stable Context Value**: The `contextValue` object is memoized and rarely changes.
+ * 3. **Direct Subscriptions**: Components subscribe via `useEffect` and receive updates via callbacks, not props.
+ * 
+ * @module core/EventEmitterContext
+ * @version 3.0.42
+ * @author Automated Design Corp.
+ */
+
+import React, {
+  createContext,
+  useState,
+  useMemo,
+  useCallback,
+  useRef,
+  useEffect,
+} from "react";
+
+import type {ReactNode} from "react";
+import { createHub, Hub } from "../hub";
+import type { CommandMessage } from "../hub";
+import { MessageType } from "../hub/CommandMessage";
+import { enableDebugPanel } from "../hub/DebugPanel";
+
+export { Hub };
+
+/**
+ * Represents an active event subscription.
+ */
+export interface Subscription {
+  /** Unique ID of the subscription used for unsubscription. */
+  id: number;
+  /** Callback function to execute when the event fires. */
+  callback: React.Dispatch<any>;
+}
+
+/**
+ * Represents the internal state of the EventEmitter.
+ * Mostly used for debugging and dev tools inspection.
+ */
+export interface State {
+  /**
+   * The optional data payload of the last event (DEBUGGING ONLY).
+   * Note: This is no longer updated in production for performance reasons.
+   */
+  eventData?: any;
+  /** Active subscriptions grouped by topic. */
+  subscriptions: Record<string, Subscription[]>;
+
+  /** Tracks the next subscription ID that will be assigned. */
+  nextSubscriptionId: number;
+}
+
+/**
+ * An action event published by the EventEmitterContext.
+ */
+export interface Action {
+  /** The topic or identifier of the event. */
+  topic: string;
+  /** The optional data payload associated with the event. */
+  payload?: any;
+}
+
+export type EmitterDispatchFunction = (action: Action) => void;
+
+/**
+ * Defines the context for the global event emitter.
+ * Provides methods for dispatching events, subscribing to topics, and communicating with the backend.
+ */
+export interface EventEmitterContextType {
+  /**
+   * The current state of the event emitter (mostly for debugging).
+   */
+  state: State;
+
+  /**
+   * Dispatch an action globally throughout the front-end.
+   * Triggers callbacks for all subscribers of the topic.
+   * 
+   * @param action The action to dispatch.
+   */
+  dispatch: EmitterDispatchFunction;
+
+  /**
+   * Send a message to the backend (Low-level).
+   * 
+   * @param topic The FQDN of the resource (e.g., "ads.plc1.gio.bControlPowerOk")
+   * @param messageType The action to perform (Read, Write, Subscribe, etc.)
+   * @param payload Optional data payload
+   * @returns Promise resolving to the CommandMessage response
+   */
+  invoke(
+    topic: string,
+    messageType: MessageType,
+    payload?: object
+  ): Promise<CommandMessage>;
+
+  /**
+   * Read a value from the backend.
+   *
+   * @param topic The FQDN of the resource to read
+   * @param payload Optional additional parameters
+   * @returns Promise resolving to the CommandMessage response with the value in `data`
+   */
+  read(topic: string, payload?: object): Promise<CommandMessage>;
+
+  /**
+   * Write a value to the backend.
+   *
+   * @param topic The FQDN of the resource to write
+   * @param value The value to write
+   * @returns Promise resolving to the CommandMessage response
+   */
+  write(topic: string, value: any): Promise<CommandMessage>;
+
+  /**
+   * Subscribe to value changes on the backend.
+   *
+   * Tells the server to start broadcasting updates for a specific topic.
+   * Also registers a mapping between the local `tagName` and the remote `topic` (FQDN)
+   * in the Hub, so that incoming broadcasts are routed correctly.
+   *
+   * @param tagName The local tag name to map the topic to
+   * @param topic The FQDN of the resource to watch
+   * @param payload Optional subscription parameters (e.g., update rate)
+   * @returns Promise resolving to the CommandMessage response
+   */
+  serverSubscribe(tagName: string, topic: string, payload?: object): Promise<CommandMessage>;
+
+  /**
+   * Unsubscribe from value changes on the backend.
+   *
+   * @param tagName The local tag name to stop watching
+   * @param payload Optional parameters
+   * @returns Promise resolving to the CommandMessage response
+   */
+  serverUnsubscribe(tagName: string, payload?: object): Promise<CommandMessage>;
+
+  /**
+   * Subscribe to **local** frontend events.
+   * 
+   * This registers a callback to listen for events dispatched on the local event bus.
+   * This includes both locally dispatched events AND broadcast messages received
+   * from the server (which the Hub dispatches to the local bus).
+   *
+   * @param topic The subscription topic (or tagName).
+   * @param callback The callback to signal.
+   * @returns number Subscription ID used to unsubscribe later.
+   */
+  subscribe: (topic: string, callback: React.Dispatch<any>) => number;
+
+  /**
+   * Unsubscribe from **local** frontend events.
+   *
+   * @param subscriptionId The id returned by the subscribe method.
+   */
+  unsubscribe: (subscriptionId: number) => void;
+
+  /**
+   * Global hub instance for backend communication.
+   */
+  hub: Hub | null;
+
+  /**
+   * Retrieves the current subscriptions. Used for debugging purposes.
+   */
+  getSubscriptions: (
+    topic?: string
+  ) => Record<string, Subscription[]> | Subscription[];
+
+  /**
+   * Returns true if the Hub is connected to the backend.
+   */
+  isConnected: () => boolean;
+}
+
+// Default placeholder CommandMessage for context initialization
+const placeholderResponse: CommandMessage = {
+  data: {},
+  success: false,
+  error_message: "Context not initialized",
+  transaction_id: 0,
+  timecode: 0,
+  topic: "",
+  message_type: MessageType.NoOp
+};
+
+export const EventEmitterContext = createContext<EventEmitterContextType>({
+  state: { subscriptions: {}, nextSubscriptionId: 1 },
+  dispatch: () => {},
+  subscribe: () => 0,
+  unsubscribe: () => {},
+  invoke: async () => placeholderResponse,
+  read: async () => placeholderResponse,
+  write: async () => placeholderResponse,
+  serverSubscribe: async (_tagName: string, _topic: string, _payload?: object) => placeholderResponse,
+  serverUnsubscribe: async (_tagName: string, _payload?: object) => placeholderResponse,
+  hub: null,
+  getSubscriptions: () => [],
+  isConnected: () => false,
+});
+
+/**
+ * A React component that provides the EventEmitterContext to its children.
+ *
+ * Wraps child components with the context, enabling them to access and interact
+ * with the event emitter.
+ *
+ * @param children The child components to be wrapped in the context.
+ */
+export const EventEmitterProvider: React.FC<{ children: ReactNode; debug?: boolean }> = ({
+  children,
+  debug = false,
+}) => {
+  console.log("[EventEmitterProvider] Rendering...");
+
+  // Enable the debug panel if requested (must run before Hub creation)
+  if (debug) {
+    enableDebugPanel();
+  }
+
+  const [state, setState] = useState<State>({
+    subscriptions: {},
+    nextSubscriptionId: 1,
+  });
+
+  // PERFORMANCE: Memoize the hub instance so it's only created once.
+  // This ensures the WebSocket connection persists across re-renders.
+  const hub = useMemo(() => {
+    console.log("[EventEmitterProvider] Creating Hub instance");
+    return createHub();
+  }, []);
+
+  // Use ref for subscription ID management (avoids global state issues)
+  const nextIdRef = useRef(1);
+
+  // Subscription storage - this is the single source of truth for local listeners
+  const subsRef = useRef<Record<string, Subscription[]>>({});
+
+  // Sync state with ref for debugging/inspection purposes only (on mount)
+  useEffect(() => {
+    setState(prev => ({
+      ...prev,
+      subscriptions: { ...subsRef.current },
+      nextSubscriptionId: nextIdRef.current
+    }));
+  }, []);
+
+  /**
+   * Dispatches an event to all listeners.
+   * 
+   * PERFORMANCE CRITICAL: This function iterates through listeners and calls them directly.
+   * It intentionally does NOT update React state (setState) to avoid triggering a 
+   * full app re-render on every high-frequency event.
+   */
+  const dispatch = useCallback((action: Action) => {
+    const { topic, payload } = action;
+
+    // Read from ref (single source of truth) and create a defensive copy
+    const listeners = subsRef.current[topic]?.slice() ?? [];
+    
+    // Execute callbacks synchronously to avoid timing issues
+    for (const sub of listeners) {
+      try {
+        sub.callback(payload);
+      } catch (e) {
+        console.error("[EventBus] listener error", e);
+      }
+    }
+
+    // NOTE: State update removed for performance. 
+    // Uncommenting this will cause the entire Provider to re-render on every event!
+    // setState((prev) => ({ ...prev, eventData: payload }));
+  }, []);
+
+  const subscribe = useCallback(
+    (topic: string, callback: React.Dispatch<any>): number => {
+      const id = nextIdRef.current++;
+      
+      // Create new subscription entry
+      const newSub: Subscription = { id, callback };
+      
+      // Atomically update the ref with a complete new structure
+      const currentSubs = subsRef.current[topic] ?? [];
+      const newSubs = [...currentSubs, newSub];
+      
+      subsRef.current = {
+        ...subsRef.current,
+        [topic]: newSubs
+      };
+
+      // Update state for debugging/inspection (less frequent than dispatch, so acceptable)
+      setState(prevState => ({
+        ...prevState,
+        subscriptions: { ...subsRef.current },
+        nextSubscriptionId: nextIdRef.current,
+      }));
+
+      return id;
+    },
+    []
+  );
+
+  const unsubscribe = useCallback((subscriptionId: number) => {
+    // Create a completely new structure to avoid mutation issues
+    const newSubscriptions: Record<string, Subscription[]> = {};
+    
+    for (const [topic, subs] of Object.entries(subsRef.current)) {
+      const filteredSubs = subs.filter(s => s.id !== subscriptionId);
+      if (filteredSubs.length > 0) {
+        newSubscriptions[topic] = filteredSubs;
+      }
+    }
+    
+    // Atomically replace the entire structure
+    subsRef.current = newSubscriptions;
+
+    // Update state for debugging/inspection
+    setState(prev => ({ 
+      ...prev, 
+      subscriptions: { ...newSubscriptions }
+    }));
+  }, []);
+
+  // Clean up on unmount
+  useEffect(() => {
+    return () => {
+      subsRef.current = {};
+      nextIdRef.current = 1;
+    };
+  }, []);
+
+  // Handle HMR so listeners don't leak across hot updates
+  if (import.meta && (import.meta as any).hot) {
+    (import.meta as any).hot.dispose(() => {
+      subsRef.current = {};
+      nextIdRef.current = 1;
+    });
+  }
+
+  // Memoize hub methods separately so they don't change when state changes.
+  // This prevents downstream useEffects from re-running due to function reference changes.
+  const invoke = useCallback(
+    (topic: string, messageType: MessageType, payload?: object) => hub.invoke(topic, messageType, payload),
+    [hub]
+  );
+  const read = useCallback(
+    (topic: string, payload?: object) => hub.read(topic, payload),
+    [hub]
+  );
+  const write = useCallback(
+    (topic: string, value: any) => hub.write(topic, value),
+    [hub]
+  );
+  const serverSubscribe = useCallback(
+    (tagName: string, topic: string, payload?: object) => hub.subscribe(tagName, topic, payload),
+    [hub]
+  );
+  const serverUnsubscribe = useCallback(
+    (tagName: string, payload?: object) => hub.unsubscribe(tagName, payload),
+    [hub]
+  );
+  const isConnected = useCallback(() => hub.isConnected(), [hub]);
+
+  // Provide the memoized context value
+  // PERFORMANCE: This object is memoized and its dependencies (dispatch, subscribe, etc.)
+  // are also memoized/stable. This means 'contextValue' reference rarely changes,
+  // preventing consumers (like App) from re-rendering unless necessary.
+  const contextValue = useMemo(
+    () => ({
+      state,
+      dispatch,
+      subscribe,
+      unsubscribe,
+      invoke,
+      read,
+      write,
+      serverSubscribe,
+      serverUnsubscribe,
+      hub,
+      getSubscriptions: (topic?: string) =>
+        topic ? subsRef.current[topic] ?? [] : subsRef.current,
+      isConnected,
+    }),
+    [state, hub, dispatch, subscribe, unsubscribe, invoke, read, write, serverSubscribe, serverUnsubscribe, isConnected]
+  );
+
+  // Set the context on the hub instance so it can dispatch back to us.
+  // Must be in useEffect to avoid side-effects during render phase.
+  useEffect(() => {
+    hub.setContext(contextValue);
+  }, [hub, contextValue]);
+
+  return (
+    <EventEmitterContext.Provider value={contextValue}>
+      {children}
+    </EventEmitterContext.Provider>
+  );
 };