@adcops/autocore-react 3.1.1 → 3.3.2

package/src/core/EventEmitterContext.tsx

@@ -2,7 +2,7 @@
  * Copyright (C) 2024 Automated Design Corp. All Rights Reserved.
  * Created Date: 2024-01-17 11:45:10
  * -----
- * Last Modified: 2025-09-06 14:08:30
+ * Last Modified: 2026-01-29 09:32:29
  * Modified By: ADC
  * -----
  *
@@ -17,287 +17,30 @@
  * 
  * ## 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
- * - **Connection Management**: Automatic reconnection and state synchronization
- * - **Development Tools**: Built-in debugging and subscription introspection
+ * - **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
- * 2. **Hub**: Abstraction layer for backend communication (WebSocket, HTTP, etc.)
- * 3. **Subscription Manager**: Handles event routing and lifecycle management
- * 
- * ## Basic Usage
- * 
- * ### 1. Application Setup
- * 
- * Wrap your entire application with the EventEmitterProvider:
- * 
- * ```tsx
- * // App.tsx
- * import React from 'react';
- * import { EventEmitterProvider } from '@adcops/autocore-react/core/EventEmitterContext';
- * import { PrimeReactProvider } from 'primereact/api';
- * import { MainView } from './MainView';
- * 
- * export default function App() {
- *   return (
- *     <EventEmitterProvider>
- *       <PrimeReactProvider>
- *         <MainView />
- *       </PrimeReactProvider>
- *     </EventEmitterProvider>
- *   );
- * }
- * ```
- * 
- * ### 2. Component Communication
- * 
- * Use the context for inter-component communication:
- * 
- * ```tsx
- * // PublisherComponent.tsx
- * import React, { useContext } from 'react';
- * import { EventEmitterContext } from '@adcops/autocore-react/core/EventEmitterContext';
- * import { Button } from 'primereact/button';
- * 
- * export const PublisherComponent: React.FC = () => {
- *   const { dispatch } = useContext(EventEmitterContext);
- * 
- *   const handleButtonClick = () => {
- *     dispatch({
- *       topic: 'user-action/button-clicked',
- *       payload: { timestamp: Date.now(), buttonId: 'main-action' }
- *     });
- *   };
- * 
- *   return <Button label="Trigger Event" onClick={handleButtonClick} />;
- * };
- * 
- * // SubscriberComponent.tsx
- * import React, { useContext, useEffect, useState } from 'react';
- * import { EventEmitterContext } from '@adcops/autocore-react/core/EventEmitterContext';
- * 
- * export const SubscriberComponent: React.FC = () => {
- *   const { subscribe, unsubscribe } = useContext(EventEmitterContext);
- *   const [lastAction, setLastAction] = useState<any>(null);
- * 
- *   useEffect(() => {
- *     const subscriptionId = subscribe('user-action/button-clicked', (payload) => {
- *       setLastAction(payload);
- *       console.log('Button clicked at:', payload.timestamp);
- *     });
- * 
- *     return () => unsubscribe(subscriptionId);
- *   }, [subscribe, unsubscribe]);
- * 
- *   return (
- *     <div>
- *       {lastAction && (
- *         <p>Last action: {new Date(lastAction.timestamp).toLocaleTimeString()}</p>
- *       )}
- *     </div>
- *   );
- * };
- * ```
- * 
- * ### 3. Backend Integration
- * 
- * Communicate with AutoCore server through the integrated Hub:
- * 
- * ```tsx
- * // ControlPanel.tsx
- * import React, { useContext, useEffect, useState } from 'react';
- * import { EventEmitterContext } from '@adcops/autocore-react/core/EventEmitterContext';
- * import { Button } from 'primereact/button';
- * import { InputNumber } from 'primereact/inputnumber';
- * 
- * export const ControlPanel: React.FC = () => {
- *   const { invoke, subscribe, unsubscribe, isConnected } = useContext(EventEmitterContext);
- *   const [motorSpeed, setMotorSpeed] = useState<number>(0);
- *   const [targetSpeed, setTargetSpeed] = useState<number>(100);
- *   const [connected, setConnected] = useState<boolean>(false);
- * 
- *   // Monitor connection status
- *   useEffect(() => {
- *     setConnected(isConnected());
- *     
- *     const connectionSub = subscribe('HUB/connected', () => setConnected(true));
- *     const disconnectionSub = subscribe('HUB/disconnected', () => setConnected(false));
- * 
- *     return () => {
- *       unsubscribe(connectionSub);
- *       unsubscribe(disconnectionSub);
- *     };
- *   }, [subscribe, unsubscribe, isConnected]);
- * 
- *   // Subscribe to real-time motor speed updates
- *   useEffect(() => {
- *     const speedSub = subscribe('ADS/MAIN.motor.speed', (data) => {
- *       setMotorSpeed(data.value);
- *     });
- * 
- *     return () => unsubscribe(speedSub);
- *   }, [subscribe, unsubscribe]);
- * 
- *   // Send commands to backend
- *   const handleSpeedChange = async () => {
- *     try {
- *       const result = await invoke('ADS', 'write_value', {
- *         symbol_name: 'MAIN.motor.setpoint',
- *         value: targetSpeed
- *       });
- *       
- *       if (!result.success) {
- *         console.error('Failed to set motor speed:', result.error_message);
- *       }
- *     } catch (error) {
- *       console.error('Communication error:', error);
- *     }
- *   };
- * 
- *   const handleEmergencyStop = async () => {
- *     try {
- *       await invoke('ADS', 'emergency_stop', {});
- *     } catch (error) {
- *       console.error('Emergency stop failed:', error);
- *     }
- *   };
- * 
- *   return (
- *     <div className="control-panel">
- *       <div className="status">
- *         Connection: {connected ? '🟢 Connected' : '🔴 Disconnected'}
- *       </div>
- *       
- *       <div className="motor-control">
- *         <p>Current Speed: {motorSpeed} RPM</p>
- *         
- *         <InputNumber
- *           value={targetSpeed}
- *           onValueChange={(e) => setTargetSpeed(e.value || 0)}
- *           min={0}
- *           max={1000}
- *           suffix=" RPM"
- *         />
- *         
- *         <Button
- *           label="Set Speed"
- *           onClick={handleSpeedChange}
- *           disabled={!connected}
- *         />
- *         
- *         <Button
- *           label="Emergency Stop"
- *           onClick={handleEmergencyStop}
- *           severity="danger"
- *           disabled={!connected}
- *         />
- *       </div>
- *     </div>
- *   );
- * };
- * ```
- * 
- * ### 4. Advanced Pattern: State Management Hook
- * 
- * Create reusable hooks for common patterns:
- * 
- * ```tsx
- * // hooks/useRealtimeValue.ts
- * import { useContext, useEffect, useState } from 'react';
- * import { EventEmitterContext } from '@adcops/autocore-react/core/EventEmitterContext';
- * 
- * export function useRealtimeValue<T>(topic: string, initialValue?: T) {
- *   const { subscribe, unsubscribe } = useContext(EventEmitterContext);
- *   const [value, setValue] = useState<T | undefined>(initialValue);
- *   const [lastUpdate, setLastUpdate] = useState<Date | null>(null);
- * 
- *   useEffect(() => {
- *     const subscriptionId = subscribe(topic, (data) => {
- *       setValue(data.value);
- *       setLastUpdate(new Date());
- *     });
- * 
- *     return () => unsubscribe(subscriptionId);
- *   }, [topic, subscribe, unsubscribe]);
- * 
- *   return { value, lastUpdate };
- * }
- * 
- * // Usage in component
- * export const SensorDisplay: React.FC = () => {
- *   const { value: temperature } = useRealtimeValue<number>('ADS/sensors.temperature');
- *   const { value: pressure } = useRealtimeValue<number>('ADS/sensors.pressure');
- * 
- *   return (
- *     <div>
- *       <p>Temperature: {temperature?.toFixed(1)}°C</p>
- *       <p>Pressure: {pressure?.toFixed(2)} bar</p>
- *     </div>
- *   );
- * };
- * ```
- * 
- * ## Integration with AutoCore Systems
- * 
- * The EventEmitterContext is designed to work seamlessly with other AutoCore React components:
- * 
- * ```tsx
- * // Complete AutoCore application setup
- * import React from 'react';
- * import { EventEmitterProvider } from '@adcops/autocore-react/core/EventEmitterContext';
- * import { AutoCoreTagProvider } from '@adcops/autocore-react/core/AutoCoreTagContext';
- * import { PrimeReactProvider } from 'primereact/api';
- * import { tagSpec } from './config/tags';
- * import { MainInterface } from './components/MainInterface';
- * 
- * export default function App() {
- *   return (
- *     <EventEmitterProvider>
- *       <AutoCoreTagProvider tags={tagSpec} eagerRead>
- *         <PrimeReactProvider>
- *           <MainInterface />
- *         </PrimeReactProvider>
- *       </AutoCoreTagProvider>
- *     </EventEmitterProvider>
- *   );
- * }
- * ```
- * 
- * ## Best Practices
- * 
- * 1. **Always Cleanup Subscriptions**: Use the cleanup function returned by useEffect
- * 2. **Use Meaningful Topic Names**: Follow a hierarchical naming convention (e.g., 'domain/category/specific')
- * 3. **Handle Connection States**: Always check connection status before invoking backend functions
- * 4. **Error Handling**: Wrap invoke calls in try-catch blocks
- * 5. **Type Safety**: Use TypeScript interfaces for payload structures
- * 6. **Performance**: Avoid subscribing to high-frequency events in render-heavy components
- * 
- * ## Debugging
- * 
- * Use the built-in debugging features:
- * 
- * ```tsx
- * const { getSubscriptions, state } = useContext(EventEmitterContext);
- * 
- * // View all subscriptions
- * console.log('All subscriptions:', getSubscriptions());
- * 
- * // View subscriptions for specific topic
- * console.log('Motor subscriptions:', getSubscriptions('ADS/MAIN.motor.speed'));
+ * 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
  * 
- * // View current state
- * console.log('EventEmitter state:', state);
- * ```
+ * 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.41
+ * @version 3.0.42
  * @author Automated Design Corp.
- * @since 1.0.0
  */
 
 import React, {
@@ -311,29 +54,32 @@ import React, {
 
 import type {ReactNode} from "react";
 import { createHub, Hub } from "../hub";
-import type { CommandMessageResult } from "../hub/CommandMessage";
+import type { CommandMessage } from "../hub";
+import { MessageType } from "../hub/CommandMessage";
 
 export { Hub };
 
 /**
- * Represents an event subsription.
+ * Represents an active event subscription.
  */
 export interface Subscription {
-  /** ID of the subscription used for unsubscription. */
+  /** Unique ID of the subscription used for unsubscription. */
   id: number;
-  /** Callback function. */
+  /** Callback function to execute when the event fires. */
   callback: React.Dispatch<any>;
 }
 
 /**
- * Represents the payload data associated with an event.
+ * Represents the internal state of the EventEmitter.
+ * Mostly used for debugging and dev tools inspection.
  */
 export interface State {
   /**
-   * The optional data payload of the event.
+   * The optional data payload of the last event (DEBUGGING ONLY).
+   * Note: This is no longer updated in production for performance reasons.
    */
   eventData?: any;
-  /** Callback subscription. A list of callback subscriptions matched to a topic. */
+  /** Active subscriptions grouped by topic. */
   subscriptions: Record<string, Subscription[]>;
 
   /** Tracks the next subscription ID that will be assigned. */
@@ -341,259 +87,152 @@ export interface State {
 }
 
 /**
- * An action event published by the EventEmitterContext. Contains
- * the topic identifying the event and the optional payload, which is
- * a value of any type.
+ * An action event published by the EventEmitterContext.
  */
 export interface Action {
-  /**
-   * The topic or identifier of the event.
-   */
+  /** The topic or identifier of the event. */
   topic: string;
-
-  /**
-   * The optional data payload associated with the event.
-   */
+  /** The optional data payload associated with the event. */
   payload?: any;
 }
 
-/**
- * Type declaration for the EventEmitter dispatch function, which
- * publishes an Action globally throughout the EventEmitterContext.
- */
 export type EmitterDispatchFunction = (action: Action) => void;
 
 /**
- * Type declaration for the EventEmitter dispatch function, which
- * receives an Action on a specific topic broadcast through the EventEmitterContext.
- */
-export type EmitterSubscribeFunction = (action: Action) => void;
-
-/**
- * Type declaration for the EventEmitter unsubscribe function, which
- * receives an Action on a specific topic broadcast through the EventEmitterContext.
- */
-export type EmitterUnsubscribeFunction = (action: Action) => void;
-
-/**
- * Defines the context for an event emitter used throughout a front-end application to manage and dispatch events.
- * This interface includes methods for managing the application's state, handling global actions, communicating with the back end,
- * subscribing to and unsubscribing from events, and accessing a global hub for event publishing and subscription management.
- * It serves as a central point for event-driven interactions within the application, facilitating communication between
- * components and the back end, as well as among components themselves.
+ * 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, containing the latest event data.
+   * The current state of the event emitter (mostly for debugging).
    */
   state: State;
 
   /**
-   * A function to dispatch actions globally throughout the front-end,
-   * triggering state updates and events.
-   *
-   * @param action The action to dispatch, containing topic and optional payload.
+   * Dispatch an action globally throughout the front-end.
+   * Triggers callbacks for all subscribers of the topic.
+   * 
+   * @param action The action to dispatch.
    */
-  dispatch: (action: Action) => void;
+  dispatch: EmitterDispatchFunction;
 
   /**
-   * Invoke/send a message to the back end.
-   * This does NOT get published to the front end.
+   * 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(
-    domain: string,
-    fname: string,
+    topic: string,
+    messageType: MessageType,
     payload?: object
-  ): Promise<CommandMessageResult>;
+  ): 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 events identified by the topic.
-   * @param topic The subscription topic.
+   * 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 to events.
-   * @param subscriptionId The id of the subscription returned by the subscribe method.
-   * @returns
+   * Unsubscribe from **local** frontend events.
+   *
+   * @param subscriptionId The id returned by the subscribe method.
    */
   unsubscribe: (subscriptionId: number) => void;
 
   /**
-   * Global hub for publishing and receiving events throughout the interface, and for exchanging
-   * data with the backend.
+   * Global hub instance for backend communication.
    */
   hub: Hub | null;
 
   /**
    * Retrieves the current subscriptions. Used for debugging purposes.
-   * @param topic Optional. The topic to retrieve subscriptions for. If omitted, returns all subscriptions.
-   * @returns An object containing the current subscriptions, optionally filtered by topic.
    */
   getSubscriptions: (
     topic?: string
   ) => Record<string, Subscription[]> | Subscription[];
 
   /**
-   * Returns true if the Hub in use is connected to its source.
-   * @returns boolean
+   * Returns true if the Hub is connected to the backend.
    */
   isConnected: () => boolean;
 }
 
-/**
- * A global context for managing event emission and subscription.
- *
- * Creates a React context for the EventEmitter system, providing a structured way to manage events and data flow
- * in a React application. It serves as a global event bus that components can subscribe to or emit events, allowing for
- * a loosely coupled architecture. Additionally, it provides a mechanism for invoking backend functions and managing
- * subscriptions, making it easier to integrate React components with backend services.
- *
- * The context includes several key functionalities:
- * - `state`: Maintains the current state of subscriptions and their identifiers.
- * - `dispatch`: Allows components to emit events with specific topics and payloads, which can be listened to by other components.
- * - `subscribe`: Enables components to listen to specific topics and react to those events by providing a callback function.
- * - `unsubscribe`: Provides a way for components to stop listening to events, helping prevent memory leaks and unnecessary updates.
- * - `invoke`: Facilitates calling backend functions with specific arguments and handling their responses asynchronously.
- * - `getSubscriptions`: Offers insight into current active subscriptions, useful for debugging purposes.
- *
- * This context is essential for applications that require a high degree of inter-component communication or need to
- * interact with a backend efficiently.
- *
- * For more information, see [Additional Documentation](../additional-docs/GlobalEventEmitter.md).
- *
- * ## Usage
- *
- * The entire application should be wrapped in the EventEmitterProvider.
- *
- * App.tsx
- * ```
- * import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext.js";
- * function App() {
- *
- *      return(
- *          <EventEmitterProvider>
- *              <PrimeReactProvider>
- *                  <main>
- *                      <section>
- *                          <ContentView />
- *                      </section>
- *                  </main>
- *              </PrimeReactProvider>
- *          </EventEmitterProvider>
- *      );
- *
- * }
- *
- * ```
- *
- * ### Catching and receiving events
- * The EventEmitterContext creates an appropriate instance of the hub, which is derived from HubBase.
- * That hub can be used to publish and subscribe to
- * topics globally in the front-end, regardless of being connected to any backend.
- * Usage within a component is simple.
- *
- * ```
- * const {dispatch, subscribe, unsubscribe} = useContext(EventEmitterContext);
- * const [controlPower, setControlPower] = useState(false);
- * useEffect(() => {
- *      const unsubscribeControlPower = subscribe('value-simulator-bBit1', (value) => {
- *          setControlPower(value);
- *      });
- *
- *
- *      return () => {
- *           unsubscribe(unsubscribeControlPower);
- *      }
- * }, [] );
- *
- * const onPbPressed = () => {
- *      let count = 1;
- *      dispatch({
- *          topic: "my-awesome-topic",
- *          payload: count
- *      });
- * }
- *
- * ```
- * The hub should also be used for invoking events in the backend.
- * This example will call the function "update_count" in the backend, passing
- * the expected argument "count". Details of the interaction between the Hub and
- * the backend will be handled by the appropriate HubBase sub-class, and should
- * be transparent to the front end.
- *
- * ```
- * const {invoke} = useContext(EventEmitterContext);
- * const incrementCount = () => {
- *    count += 1;
- *    invoke('update_count', {"count": count});
- * };
- *
- * Subscribing to a topic is simple. The type of value received is specific
- * to the topic.
- *
- * Example: Listen to an event 'xarm-position':
- * ```
- * const {subscribe, unsubscribe} = useContext(EventEmitterContext);
- * useEffect(() => {
- *         const unsubscripeMp = subscribe('xarm-position', (value) => {
- *            // The publisher sent a JSON object of 3D position values.
- *            setX(value.x);
- *            setY(value.y);
- *            setZ(value.z);
- *            setA(value.roll);
- *            setB(value.yaw);
- *            setC(value.pitch);
- *        });
- *
- *    return () => {
- *        unsubscribe(unsubscripeMp);
- *    }
- *
- * }, [] );
- *
- * ```
- *
- * For applications that need to access the instance of the hub, get the current instance
- * from the EventEmitterContext:
- *
- * ```
- * const {hub} = useContext(EventEmitterContext);
- *  * ```
- *
- *
- */
+// 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: () => {
-    return 0;
-  }, // Placeholder for subscription logic
-  invoke: async (domain: string, fname: string, payload?: object) => {
-    domain;
-    fname;
-    payload;
-    let ret: CommandMessageResult = {
-      data: {},
-      success: false,
-      error_message: "",
-    };
-    // Placeholder for invoke logic
-    // Implement the logic to send a message to the backend and return a promise
-    return Promise.resolve(ret); // Example placeholder, replace with actual implementation
-  },
-  unsubscribe: (subscriptionId: number) => {
-    subscriptionId;
-  }, // Placeholder for unsubscription logic
+  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: () => {
-    return [];
-  },
-  isConnected: () => {
-    return false;
-  },
+  getSubscriptions: () => [],
+  isConnected: () => false,
 });
 
 /**
@@ -603,50 +242,31 @@ export const EventEmitterContext = createContext<EventEmitterContextType>({
  * with the event emitter.
  *
  * @param children The child components to be wrapped in the context.
- *
- * ## Usage
- *
- * The entire application should be wrapped in the EventEmitterProvider.
- *
- * App.tsx
- * ```
- * import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext.js";
- * function App() {
- *
- *      return(
- *          <EventEmitterProvider>
- *              <PrimeReactProvider>
- *                  <main>
- *                      <section>
- *                          <ContentView />
- *                      </section>
- *                  </main>
- *              </PrimeReactProvider>
- *          </EventEmitterProvider>
- *      );
- *
- * }
- *
- * ```
  */
 export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
   children,
 }) => {
+  console.log("[EventEmitterProvider] Rendering...");
+
   const [state, setState] = useState<State>({
     subscriptions: {},
     nextSubscriptionId: 1,
   });
 
-  // Memoize the hub instance so it's only created once
-  const hub = useMemo(() => createHub(), []);
+  // 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
+  // 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
+  // Sync state with ref for debugging/inspection purposes only (on mount)
   useEffect(() => {
     setState(prev => ({
       ...prev,
@@ -655,6 +275,13 @@ export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
     }));
   }, []);
 
+  /**
+   * 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;
 
@@ -670,8 +297,9 @@ export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
       }
     }
 
-    // Update state for debugging/inspection (optional)
-    setState((prev) => ({ ...prev, eventData: payload }));
+    // 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(
@@ -690,7 +318,7 @@ export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
         [topic]: newSubs
       };
 
-      // Update state for debugging/inspection
+      // Update state for debugging/inspection (less frequent than dispatch, so acceptable)
       setState(prevState => ({
         ...prevState,
         subscriptions: { ...subsRef.current },
@@ -711,7 +339,6 @@ export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
       if (filteredSubs.length > 0) {
         newSubscriptions[topic] = filteredSubs;
       }
-      // If no subscriptions left for this topic, don't include it
     }
     
     // Atomically replace the entire structure
@@ -724,7 +351,7 @@ export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
     }));
   }, []);
 
-  // Clean up on unmount and handle HMR
+  // Clean up on unmount
   useEffect(() => {
     return () => {
       subsRef.current = {};
@@ -740,23 +367,58 @@ export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
     });
   }
 
-  // Provide the memoized hub instance in the context value
+  // 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: hub.invoke,
+      invoke,
+      read,
+      write,
+      serverSubscribe,
+      serverUnsubscribe,
       hub,
       getSubscriptions: (topic?: string) =>
         topic ? subsRef.current[topic] ?? [] : subsRef.current,
-      isConnected: hub.isConnected,
+      isConnected,
     }),
-    [state, hub, dispatch, subscribe, unsubscribe]
+    [state, hub, dispatch, subscribe, unsubscribe, invoke, read, write, serverSubscribe, serverUnsubscribe, isConnected]
   );
 
-  hub.setContext(contextValue);
+  // 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}>