@adcops/autocore-react 3.1.1 → 3.3.5

package/src/core/AutoCoreTagContext.tsx

@@ -2,7 +2,8 @@
  * Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
  * Created Date: 2025-09-05 07:35:46
  * -----
- * Last Modified: 2025-09-10 11:28:01
+ * Last Modified: 2026-01-29 09:31:42
+ * Modified By: ADC
  * -----
  *
  */
@@ -13,99 +14,50 @@
  * @document ../../additional-docs/AutCoreTagContext.md
  *
  * @summary
- * A React Context + Provider that:
- * - Buffers **raw** controller values for every tag (exactly as received)
- * - Derives **display** values from raw using current `scales` and optional tag `codec`
- * - Recomputes display values **from raw** whenever a scale changes (no lossy re-scaling)
- * - Inverse-scales on `write()` so the server always receives controller units
- * - Supports ADS one-shot refresh, GNV-style scale objects, and resilient eager reads
+ * A React Context + Provider that manages the state and synchronization of "Tags" (data points)
+ * between the React frontend and the AutoCore backend.
+ * 
+ * It acts as the central data store for real-time values, handling:
+ * - **Buffering**: Stores raw controller values exactly as received.
+ * - **Scaling**: Converts raw values to display values (e.g., mm -> inches) based on configuration.
+ * - **Synchronization**: Subscribes to live updates from the server.
+ * - **Writing**: Converts display values back to raw controller units before sending.
  *
  * @remarks
- * ❖ **Two representations per tag**
- * - `rawValues[tagName]`: last controller value as-is (pre-scale, pre-codec)
- * - `values[tagName]`: app-visible value derived from raw (scales/codec applied)
- *
- * ❖ **Scaling**
- * - Provide `scales` keyed by scale group (e.g., `"position"`, `"load"`).
- * - Each scale may point at a server tag (`serverTag`) that publishes an object
- *   `{ name, scale, label }` (GNV-style). When received, the Provider recomputes
- *   *only* affected display values **from raw**.
- * - Manual `updateScale(name, scale, label)` writes the object back to the server
- *   (if `serverTag` is configured) and recomputes from raw locally.
- *
- * ❖ **Lifecycle order (eagerRead = true)**
- * 1. Pull server scales first (so first ADS burst displays in correct units)
- * 2. Register ADS symbols and subscribe all domains
- * 3. Eager-pull non-ADS (refresh if available, else read_value)
- * 4. ADS `refresh` one-shot publish
- *
- * ❖ **Writes**
- * - `write(tagName, displayValue)` → (codec?) → inverse-scale → `write_value`
- * - `tap(tagName)` pulses booleans `true → (300ms) → false` with proper domain envelopes
+ * ❖ **Dual-State Representation**
+ * To prevent rounding errors and race conditions, we maintain two parallel states:
+ * 1. `rawValues[tagName]`: The exact value received from the controller (Source of Truth).
+ * 2. `values[tagName]`: The derived value shown in the UI (calculated from raw + scale).
+ * 
+ * When a scale changes (e.g., user switches units), we recompute `values` from `rawValues`.
+ * We *never* rescale a previously scaled value.
  *
- * ❖ **Resilience**
- * - Eager reads tolerate “missing key” errors on fresh systems and keep going
- * - All re-scaling recomputes from **raw** to avoid cumulative precision/race issues
+ * ❖ **Key Features**
+ * - **Resilient Initialization**: Eagerly fetches initial values (via ADS refresh or read fallback).
+ * - **Server-Stored Scales**: Can load unit preferences from the server (GNV domain).
+ * - **Optimized Updates**: Uses stable references and memoization to minimize React re-renders.
+ * - **Type Safety**: Strongly typed context via generic `VMapRuntime`.
  *
  * @example Minimal wiring
  * ```tsx
- * import { AutoCoreTagProvider } from "@adcops/autocore-react/core/AutoCoreTagContext";
- * import type { TagConfig, ScaleConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
- *
- * const acTagSpec = [
- *   { tagName: "pressPosition", domain: "ADS", valueType: "number", symbolName: "AX.Press.Position", scale: "position" },
- *   { tagName: "pressLoad",     domain: "ADS", valueType: "number", symbolName: "AX.Press.Load",     scale: "load" },
- *   { tagName: "isMotorsOn",    domain: "ADS", valueType: "boolean", symbolName: "GIO.isMotorsOn" },
- * ] as const satisfies readonly TagConfig[];
- *
- * const scales: Record<string, ScaleConfig> = {
- *   position: {
- *     name: "position",
- *     scale: 1.0,
- *     label: "mm",
- *     serverTag: { domain: "GNV", symbolName: "position_units" }, // expects {name, scale, label}
- *   },
- *   load: {
- *     name: "load",
- *     scale: 1.0,
- *     label: "N",
- *     serverTag: { domain: "GNV", symbolName: "load_units" },     // expects {name, scale, label}
- *   },
+ * // 1. Define your tags
+ * const tags = [
+ *   { tagName: "position", fqdn: "ADS.Axis.Pos", valueType: "number", scale: "dist" },
+ *   { tagName: "speed",    fqdn: "ADS.Axis.Vel", valueType: "number", scale: "dist" }
+ * ];
+ * 
+ * // 2. Define scales
+ * const scales = {
+ *   dist: { name: "dist", scale: 1.0, label: "mm" }
  * };
- *
- * export function AppRoot() {
- *   return (
- *     <AutoCoreTagProvider tags={acTagSpec} scales={scales} eagerRead>
- *       <App />
- *     </AutoCoreTagProvider>
- *   );
- * }
- * ```
- *
- * @example Consuming values with hooks
- * ```tsx
- * import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
- * import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
- *
- * export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, acTagSpec);
- *
- * function Dashboard() {
- *   const { value: pos } = AutoCoreHooks.useAutoCoreTag("pressPosition"); // display units
- *   const { value: load } = AutoCoreHooks.useAutoCoreTag("pressLoad");
- *   const { scales, updateScale } = AutoCoreHooks.useScales();
- *
- *   return (
- *     <>
- *       <div>Position: {pos} {scales.position.label}</div>
- *       <div>Load: {load} {scales.load.label}</div>
- *       <button onClick={() => updateScale("position", 1/25.4, "in")}>inches</button>
- *     </>
- *   );
- * }
+ * 
+ * // 3. Wrap application
+ * <AutoCoreTagProvider tags={tags} scales={scales}>
+ *   <App />
+ * </AutoCoreTagProvider>
  * ```
  */
 
-
 import React, {
     useRef,
     createContext,
@@ -120,11 +72,32 @@ import { EventEmitterContext } from "./EventEmitterContext";
 import type {
     BaseContextValue,
     TagConfig,
-    ScaleConfig,
+    ScaleConfig
 } from "./AutoCoreTagTypes";
 
+import { MessageType } from "../hub/CommandMessage";
+
+/**
+ * Runtime type for the values map - allows any tag name to map to any value type.
+ * This is the generic type used when the specific tag configuration is not known at compile time.
+ */
 type VMapRuntime = Record<string, unknown>;
 
+/**
+ * The React Context that holds all AutoCore tag state and operations.
+ *
+ * This context provides:
+ * - `values`: Display values (with scaling/codecs applied)
+ * - `rawValues`: Raw controller values as received from server
+ * - `isLoading`: Whether initial data loading is complete
+ * - `write`: Function to write a value to a tag
+ * - `tap`: Function to pulse a boolean tag (true → delay → false)
+ * - `scales`: Current scale configurations
+ * - `updateScale`: Function to change a scale factor/label
+ *
+ * @see AutoCoreTagProvider for the provider implementation
+ * @see makeAutoCoreTagHooks for creating typed hooks from this context
+ */
 export const AutoCoreTagContext = createContext<BaseContextValue<VMapRuntime>>({
     values: {},
     rawValues: {},
@@ -135,11 +108,33 @@ export const AutoCoreTagContext = createContext<BaseContextValue<VMapRuntime>>({
     updateScale: async () => { },
 });
 
+/**
+ * Standard response envelope from the AutoCore server.
+ * All server responses follow this structure.
+ *
+ * @template T - The type of data contained in the response
+ * @property success - Whether the operation succeeded
+ * @property valid - Whether the response data is valid
+ * @property data - The actual response payload
+ */
 type HubEnvelope<T> = { success?: boolean; valid?: boolean; data?: T };
 
-/** Small sleep helper */
+/**
+ * Utility function to create a promise that resolves after a specified delay.
+ * Used for tap() pulse timing and retry delays.
+ *
+ * @param ms - Number of milliseconds to sleep
+ * @returns Promise that resolves after the delay
+ */
 const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
+/**
+ * Extracts the domain (first segment) from a Fully-Qualified Domain Name.
+ * @param fqdn - The full topic path (e.g., "ads.plc1.gio.bControlPowerOk")
+ * @returns The domain segment (e.g., "ads")
+ */
+
+
 
 /**
  * AutoCoreTagProvider
@@ -150,124 +145,33 @@ const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
  * writes/taps with proper domain envelopes. Scaling is **always** applied to display
  * values only; raw values remain untouched and are the single source of truth.
  *
- * @props
- * - `tags: readonly TagConfig[]`
- *    The full tag spec. Each tag declares `tagName`, `domain`, `symbolName`,
- *    `valueType` ("boolean"|"number"|"string"|"json"), optional `scale` name, and
- *    optional `codec` for JSON.
- *
- * - `scales?: Record<string, ScaleConfig>`
- *    Map of scale groups (`position`, `load`, …). Each scale may include an optional
- *    `serverTag` `{ domain, symbolName }`. When present, the provider reads that key
- *    first and subscribes to updates. The server must publish a GNV-style object
- *    `{ name, scale, label }` (stringified or object). When a new scale arrives,
- *    the provider recomputes affected display values **from raw**.
- *
- * - `eagerRead?: boolean = true`
- *    If true, the provider performs a non-ADS eager fetch pass (refresh if available,
- *    otherwise read_value with backoff) and then performs a single ADS `refresh`.
- *    Missing keys are common on clean systems—these are logged and skipped.
- *
- * - `children: ReactNode`
- *    Your app subtree that consumes `AutoCoreTagContext`.
- *
- * @context value
- * - `values`: Partial<Record<tagName, unknown>> — app-visible (scaled/decoded)
- * - `rawValues`: Record<tagName, unknown>       — last controller values as received
- * - `isLoading`: boolean                        — true until initial wiring completes
- * - `write(tagName, displayValue)`: Promise<void>
- *      Serializes/encodes JSON if needed and inverse-scales numbers back to raw units.
- *      Dispatches `write_value` with appropriate domain envelope:
- *      - ADS: `{ symbol_name, value }`
- *      - GNV: `{ group:"ux", key, value }`
- *      - Other: `{ key, value }`
- * - `tap(tagName)`: Promise<void>
- *      For boolean tags only. Pulses true → 300ms → false with the proper envelope.
- * - `scales`: Record<string, ScaleConfig>       — current factors/labels
- * - `updateScale(name, scale, label)`: Promise<void>
- *      Writes `{ name, scale, label }` to the configured `serverTag` (if present) and
- *      recomputes display values **from raw** locally.
- *
- * @example With server-driven scales (GNV) and ADS data
- * ```tsx
- * const tags: readonly TagConfig[] = [
- *   { tagName: "pressPosition", domain: "ADS", valueType: "number", symbolName: "AX.Press.Pos",   scale: "position" },
- *   { tagName: "pressLoad",     domain: "ADS", valueType: "number", symbolName: "AX.Press.Load",  scale: "load" },
- *   { tagName: "isMotorsOn",    domain: "ADS", valueType: "boolean", symbolName: "GIO.isMotorsOn" },
- *   // JSON with codec example
- *   { tagName: "jobMeta",       domain: "GNV", valueType: "json",   symbolName: "job_meta",
- *     codec: {
- *       fromServer: (raw) => (typeof raw === "string" ? JSON.parse(raw) : raw),
- *       toServer:   (val) => JSON.stringify(val),
- *     }
- *   },
- * ] as const;
- *
- * const scales: Record<string, ScaleConfig> = {
- *   position: {
- *     name: "position",
- *     scale: 1, label: "mm",
- *     serverTag: { domain: "GNV", symbolName: "position_units" } // expects {name, scale, label}
- *   },
- *   load: {
- *     name: "load",
- *     scale: 1, label: "N",
- *     serverTag: { domain: "GNV", symbolName: "load_units" }     // expects {name, scale, label}
- *   }
- * };
- *
- * <AutoCoreTagProvider tags={tags} scales={scales} eagerRead>
- *   <YourApp/>
- * </AutoCoreTagProvider>
- * ```
- *
- * @example Reading values, raw vs display, and writing
- * ```tsx
- * import { makeAutoCoreTagHooks } from "../hooks/useAutoCoreTag";
- * import { AutoCoreTagContext } from "../core/AutoCoreTagContext";
- *
- * const Hooks = makeAutoCoreTagHooks(AutoCoreTagContext, tags);
- *
- * function Status() {
- *   const { value: pos, isLoading } = Hooks.useAutoCoreTag("pressPosition"); // scaled
- *   const { value: rawPos } = (() => {
- *     // access raw via context when needed for debugging
- *     const ctx = React.useContext(AutoCoreTagContext);
- *     return { value: ctx.rawValues["pressPosition"] };
- *   })();
- *
- *   const { scales, updateScale } = Hooks.useScales();
- *
- *   return (
- *     <>
- *       <div>Pos: {pos} {scales.position.label} (raw: {String(rawPos)})</div>
- *       <button onClick={() => updateScale("position", 1/25.4, "in")}>inches</button>
- *     </>
- *   );
- * }
- * ```
- *
- * @example Tapping booleans and writing numbers in display units
- * ```tsx
- * const { tap } = Hooks.useAutoCoreTag("isMotorsOn");
- * const { write } = Hooks.useAutoCoreTag("pressPosition");
- *
- * <button onClick={() => tap()}>Motors TAP</button>
- * <button onClick={() => write(10.0)}>Jog to 10 (display units)</button>
- * ```
+ * @param props.tags - List of tag configurations (tagName, fqdn, etc.)
+ * @param props.scales - Map of scale definitions (name, factor, label)
+ * @param props.eagerRead - If true, automatically fetches initial values on mount
  */
 export const AutoCoreTagProvider: React.FC<{
     children: ReactNode;
     tags: readonly TagConfig[];
     scales?: Record<string, ScaleConfig>;
     eagerRead?: boolean;
-}> = ({ children, tags, scales = {}, eagerRead = true }) => {
+}> = ({ children, tags, scales, eagerRead = true }) => {
     const startedRef = useRef(false);
 
-    const { invoke, isConnected, subscribe, unsubscribe } =
+    // PERFORMANCE: Memoize default scales to ensure reference stability.
+    // If 'scales' prop is undefined, we use this stable empty object.
+    // This prevents infinite re-render loops caused by creating a new object on every render.
+    const defaultScales = useMemo<Record<string, ScaleConfig>>(() => ({}), []);
+    const actualScales: Record<string, ScaleConfig> = scales ?? defaultScales;
+
+    const { invoke, read, write: hubWrite, serverSubscribe, isConnected, subscribe, unsubscribe } =
         useContext(EventEmitterContext);
 
-    /** Raw (controller) values as received from the server (pre-scale, pre-codec). */
+    /** 
+     * Raw (controller) values as received from the server (pre-scale, pre-codec). 
+     * This is the single source of truth for value data.
+     * Seeded with `initialValue` from tag config if available.
+     * Keyed by `tagName`.
+     */
     const [rawValues, setRawValues] = useState<Record<string, unknown>>(() => {
         const seed: Record<string, unknown> = {};
         for (const t of tags) {
@@ -279,14 +183,24 @@ export const AutoCoreTagProvider: React.FC<{
         return seed;
     });
 
-    /** App-visible display values, computed from raw using scales/codecs. */
+    /** 
+     * App-visible display values, computed from raw using scales/codecs.
+     * This is what the UI consumes.
+     * Keyed by `tagName`.
+     */
     const [values, setValues] = useState<Record<string, unknown>>({});
 
-    /** Scales (current factor/label) */
+    /** 
+     * Current state of scales (factor/label).
+     * Can be updated by the server or user interaction.
+     */
     const [scaleValues, setScaleValues] =
-        useState<Record<string, ScaleConfig>>(scales);
+        useState<Record<string, ScaleConfig>>(actualScales);
 
-    /** Keep refs for subscription callbacks without re-subscribing */
+    /** 
+     * Refs to access latest state inside callbacks without adding them to dependency arrays.
+     * This helps prevent re-subscribing when state changes.
+     */
     const scaleRef = useRef(scaleValues);
     const rawRef = useRef(rawValues);
     useEffect(() => { scaleRef.current = scaleValues; }, [scaleValues]);
@@ -294,36 +208,44 @@ export const AutoCoreTagProvider: React.FC<{
 
     const [isLoading, setIsLoading] = useState(true);
 
-    /** Produce a display value from a raw value given the tag config + current scales. */
+    /**
+     * Converts a raw controller value to a display value.
+     *
+     * Pipeline: Raw -> [Codec Decode] -> [Scale Multiply] -> Display
+     */
     const toDisplay = useCallback((tag: TagConfig, raw: unknown): unknown => {
         const { valueType, scale, codec } = tag;
 
-        // 1) numeric scaling
+        // 1) numeric scaling: multiply raw by scale factor
         if (valueType === "number" && typeof raw === "number" && scale) {
             const s = scaleRef.current[scale];
             const factor = s?.scale ?? 1;
             return raw * factor;
         }
 
-        // 2) codec for json (optional)
+        // 2) codec for json (optional): decode server representation
         if (valueType === "json" && codec?.fromServer) {
             try { return codec.fromServer(raw); } catch { /* fall through */ }
         }
 
-        // 3) pass-through
+        // 3) pass-through: no transformation needed
         return raw;
     }, []);
 
-    /** Inverse of toDisplay for writes (display -> raw server value) */
+    /**
+     * Converts a display value back to a raw controller value.
+     *
+     * Pipeline: Display -> [Scale Divide] -> [Codec Encode] -> Raw
+     */
     const toServer = useCallback((tag: TagConfig, display: unknown): unknown => {
         const { valueType, scale, codec } = tag;
 
-        // invert codec first (json)
+        // 1) invert codec first (json): encode for server
         if (valueType === "json" && codec?.toServer) {
             try { display = codec.toServer(display as any); } catch { /* fall through */ }
         }
 
-        // inverse numeric scaling
+        // 2) inverse numeric scaling: divide by scale factor
         if (valueType === "number" && typeof display === "number" && scale) {
             const s = scaleRef.current[scale];
             const factor = s?.scale ?? 1;
@@ -333,7 +255,13 @@ export const AutoCoreTagProvider: React.FC<{
         return display;
     }, []);
 
-    /** Recompute display values for all tags in this scale from **raw** */
+    /**
+     * Recomputes display values for all tags in a specific scale group.
+     * Called when a scale factor changes.
+     * 
+     * CRITICAL: Computes from `rawValues` (Source of Truth), not existing `values`.
+     * This prevents floating point error accumulation from repeated scaling.
+     */
     const rescaleFromRaw = useCallback((scaleName: string) => {
         const affected = tags.filter(t => t.scale === scaleName);
         if (!affected.length) return;
@@ -350,20 +278,30 @@ export const AutoCoreTagProvider: React.FC<{
         });
     }, [tags, toDisplay]);
 
-    /** Subscribe handler for tag updates: buffer raw, compute display. */
+    /**
+     * Handles incoming value updates from the server.
+     * 
+     * 1. Updates `rawValues` (Source of Truth).
+     * 2. Computes and updates `values` (Display).
+     * 3. Uses functional state updates to ensure atomicity.
+     * 4. Keys by `tagName` for consistent access by hooks.
+     */
     const handleTagUpdate = useCallback((tag: TagConfig, raw: unknown) => {
-        // write raw (immutably)
+        // Store the raw controller value (source of truth for scaling)
         setRawValues(prev =>
             prev[tag.tagName] === raw ? prev : { ...prev, [tag.tagName]: raw }
         );
-        // compute display from raw
+        // Compute and store the display value (with scaling/codecs applied)
         const display = toDisplay(tag, raw);
         setValues(prev =>
             prev[tag.tagName] === display ? prev : { ...prev, [tag.tagName]: display }
         );
     }, [toDisplay]);
 
-    /** Eager pulls (non-ADS): read raw and run handleTagUpdate */
+    /**
+     * Eagerly fetches initial values for non-ADS domains (e.g., MODBUS).
+     * Uses a worker pool to fetch in parallel while respecting rate limits.
+     */
     const eagerPullNonADS = useCallback(
         async (
             domain: string,
@@ -375,6 +313,7 @@ export const AutoCoreTagProvider: React.FC<{
             const jitterMs = opts?.jitterMs ?? 40;
 
             let index = 0;
+
             const workers = Array.from({ length: concurrency }, () => (async () => {
                 while (true) {
                     const i = index++;
@@ -382,34 +321,24 @@ export const AutoCoreTagProvider: React.FC<{
                     const tag = tagList[i];
 
                     try {
+                        // Try 'refresh' first (server broadcast), else 'read_value'
                         let usedPublishPath = false;
                         try {
-                            await invoke(domain, "refresh", { topic: tag.symbolName });
+                            await invoke(tag.fqdn, MessageType.Request, { action: "refresh" });
                             usedPublishPath = true;
                         } catch { /* fall through */ }
 
                         if (!usedPublishPath) {
-                            const payload =
-                                domain.toUpperCase() === "GNV"
-                                    ? { group: "ux", key: tag.symbolName }
-                                    : { key: tag.symbolName };
-
-                            if (tag.options) (payload as any).options = tag.options;
-
+                            const payload = domain.toUpperCase() === "GNV" ? { group: "ux" } : {};
                             try {
-                                const resp: any = await invoke(domain, "read_value", payload);
-                                // Server always returns { success, valid, data }
-                                if (resp?.success && resp?.valid) {
+                                const resp: any = await read(tag.fqdn, payload);
+                                if (resp?.success) {
                                     handleTagUpdate(tag, resp.data);
                                 }
-                            } catch (err) {
-                                // Missing key on fresh systems is normal; keep going.
-                            }
+                            } catch (err) { /* ignore missing keys on init */ }
                         }
-                    } catch (outerErr) {
-                        // never throw out of the worker loop
-                        // console.warn(`eager pull worker error for ${domain}/${tag.symbolName}`, outerErr);
-                    } finally {
+                    } catch (outerErr) { /* ignore */ } 
+                    finally {
                         const extra = Math.floor(Math.random() * jitterMs);
                         await sleep(minDelayMs + extra);
                     }
@@ -418,25 +347,24 @@ export const AutoCoreTagProvider: React.FC<{
 
             await Promise.all(workers);
         },
-        [invoke, handleTagUpdate]
+        [invoke, read, handleTagUpdate]
     );
 
-    /** Pull server scale objects first thing (GNV envelope) */
+    /**
+     * Reads scale configurations from the server (if configured).
+     * Ensures display units match the server's persisted configuration.
+     */
     const pullServerScales = useCallback(async () => {
-        for (const [scaleName, cfg] of Object.entries(scales)) {
+        // Use actualScales to ensure we iterate over a stable object
+        for (const [scaleName, cfg] of Object.entries(actualScales)) {
             if (!cfg.serverTag) continue;
             const { domain, symbolName } = cfg.serverTag;
 
             try {
-                const respUnknown = await invoke(domain, "read_value", {
-                    group: "ux",
-                    key: symbolName,
-                });
-
-                // narrow at runtime instead of forcing a direct cast
+                const respUnknown = await read(`${domain}.${symbolName}`, { group: "ux" });
                 const env = respUnknown as HubEnvelope<string>;
+                
                 if (env.data && (env.success ?? true) && (env.valid ?? true)) {
-
                     const env_data = JSON.parse(env.data) as ScaleConfig;
                     if (env_data && typeof env_data.scale === "number" ) {
                         const { scale, label } = env_data;
@@ -451,68 +379,57 @@ export const AutoCoreTagProvider: React.FC<{
                         rescaleFromRaw(scaleName);
                     }
                 }
-            } catch {
-                // Ok if not present yet.
-            }
+            } catch { /* Scale not present, use default */ }
         }
-    }, [invoke, scales, rescaleFromRaw]);
-
-    // Main subscription wiring
+    }, [read, actualScales, rescaleFromRaw]);
+
+    /**
+     * ==========================================================================
+     * MAIN SUBSCRIPTION WIRING EFFECT
+     * ==========================================================================
+     * Orchestrates the initialization sequence:
+     * 1. Load server scales.
+     * 2. Subscribe to tags (Server & Local).
+     * 3. Perform one-shot reads (ADS refresh).
+     */
     useEffect(() => {
         let mounted = true;
         const subscriptions: number[] = [];
 
         const registerAndSubscribe = async () => {
-            // group tags by domain
-            const tagsByDomain = new Map<string, TagConfig[]>();
-            for (const tag of tags) {
-                const list = tagsByDomain.get(tag.domain);
-                if (list) list.push(tag); else tagsByDomain.set(tag.domain, [tag]);
-            }
-
             try {
-                // 0) load scales first so first ADS values get correct factor
+                // 1. Load scales first so initial values are correct
                 await pullServerScales();
 
-                // 1) ADS register (sequential is fine)
-                for (const [domain, tagList] of tagsByDomain.entries()) {
-                    if (domain.toUpperCase() === "ADS") {
-                        for (const tag of tagList) {
-                            try {
-                                const invokeOptions = tag.options
-                                    ? { symbol_name: tag.symbolName, options: tag.options }
-                                    : { symbol_name: tag.symbolName };
-                                await invoke("ADS", "register_symbol", invokeOptions);
-                            } catch (ex) {
-                                console.error(`Failed to register symbol ${tag.symbolName}: ${ex}`);
-                            }
-                        }
-                    }
-
-                    // 2) subscribe
-                    for (const tag of tagList) {
-                        const id = subscribe(`${domain}/${tag.symbolName}`, (data) => {
-                            if (!mounted) return;
-                            handleTagUpdate(tag, data?.value);
-                        });
-                        subscriptions.push(id);
-                    }
-
-                    // 3) eager reads (non-ADS)
-                    if (eagerRead && domain.toUpperCase() !== "ADS") {
-                        await eagerPullNonADS(domain, tagList, { concurrency: 4, minDelayMs: 20, jitterMs: 40 });
-                    }
+                // 2. Subscribe to all tags
+                for (const tag of tags) {
+                    console.log(`Subscribe on [${tag.tagName}]  ${tag.fqdn}  ...`);
+                    
+                    // A. Server Subscription: Tell backend to start sending updates.
+                    //    We pass tagName so the Hub can map the FQDN back to the local name.
+                    await serverSubscribe(tag.tagName, tag.fqdn, tag.subscriptionOptions);
+
+                    // B. Local Subscription: Listen for updates on the Event Bus.
+                    //    The Hub will receive FQDN messages, map them to tagName, and dispatch.
+                    const id = subscribe(tag.tagName, (data) => {
+                        if (!mounted) return;
+                        // data is the raw value payload directly
+                        handleTagUpdate(tag, data);
+                    });
+                    subscriptions.push(id);
                 }
 
-                // 4) ADS one-shot refresh (after scales are known)
-                if (eagerRead) {
-                    await invoke("ADS", "refresh", {});
-                }
+                // // 3. ADS Refresh: Ask ADS to broadcast current values immediately.
+                // if (eagerRead) {
+                //     await invoke("ADS.refresh", MessageType.Request, {});
+                // }
+                
             } finally {
                 if (mounted) setTimeout(() => mounted && setIsLoading(false), 100);
             }
         };
 
+        // Prevents double-execution in React Strict Mode
         const safeRegister = async () => {
             if (!mounted || startedRef.current) return;
             startedRef.current = true;
@@ -520,6 +437,7 @@ export const AutoCoreTagProvider: React.FC<{
             finally { if (mounted) setTimeout(() => mounted && setIsLoading(false), 100); }
         };
 
+        // Wait for connection before registering
         if (!isConnected()) {
             const id = subscribe("HUB/connected", () => {
                 unsubscribe(id);
@@ -535,29 +453,36 @@ export const AutoCoreTagProvider: React.FC<{
             subscriptions.forEach(unsubscribe);
             startedRef.current = false;
         };
-    }, [subscribe, unsubscribe, isConnected, invoke, eagerRead, tags, pullServerScales, eagerPullNonADS, handleTagUpdate]);
+    }, [subscribe, unsubscribe, isConnected, invoke, serverSubscribe, eagerRead, tags, pullServerScales, eagerPullNonADS, handleTagUpdate]);
 
-    /** Subscribe to server-driven scale tags (GNV object), recompute displays from raw. */
+    /**
+     * Memoized list of scales that need server subscriptions.
+     * Used for the separate effect that listens for live scale changes.
+     */
     const scaleServerSubs = useMemo(
         () =>
-            Object.entries(scales)
+            Object.entries(actualScales)
                 .filter(([, cfg]) => cfg.serverTag)
                 .map(([scaleName, cfg]) => ({
                     scaleName,
                     domain: cfg.serverTag!.domain,
                     symbolName: cfg.serverTag!.symbolName,
                 })),
-        [scales]
+        [actualScales]
     );
 
+    /**
+     * Effect to listen for live scale changes from the server.
+     * If another user changes units, this updates our local state immediately.
+     */
     useEffect(() => {
         let mounted = true;
         const subs: number[] = [];
 
         for (const { scaleName, domain, symbolName } of scaleServerSubs) {
-            const id = subscribe(`${domain}/${symbolName}`, (data) => {
+            const id = subscribe(`${domain}.${symbolName}`, (data) => {
                 if (!mounted) return;
-                const v = data?.value;
+                const v = data?.value; // Scales come as { value: { scale, label } } usually
                 if (v && typeof v === "object" && typeof (v as any).scale === "number") {
                     const { scale, label } = v as { scale: number; label?: string };
                     setScaleValues(prev => ({
@@ -580,7 +505,12 @@ export const AutoCoreTagProvider: React.FC<{
         };
     }, [subscribe, unsubscribe, scaleServerSubs, rescaleFromRaw]);
 
-    /** Write with inverse scaling and proper domain envelopes. */
+    /**
+     * Writes a value to the server.
+     * 1. Finds tag config by `tagName`.
+     * 2. Inverse-scales the value (Display -> Raw).
+     * 3. Sends update to server using `fqdn`.
+     */
     const write = useCallback(
         async (tagName: string, displayValue: unknown) => {
             const cfg = tags.find((t) => t.tagName === tagName);
@@ -590,23 +520,14 @@ export const AutoCoreTagProvider: React.FC<{
             }
 
             const serverValue = toServer(cfg, displayValue);
-
-            let payload: any;
-            const dom = cfg.domain.toUpperCase();
-            if (dom === "ADS") {
-                payload = { symbol_name: cfg.symbolName, value: serverValue };
-            } else if (dom === "GNV") {
-                payload = { group: "ux", key: cfg.symbolName, value: serverValue };
-            } else {
-                payload = { key: cfg.symbolName, value: serverValue };
-            }
-
-            await invoke(cfg.domain, "write_value", payload);
+            await hubWrite(cfg.fqdn, serverValue);
         },
-        [tags, invoke, toServer]
+        [tags, hubWrite, toServer]
     );
 
-    /** Tap (boolean pulse) */
+    /**
+     * Momentary pulse for boolean tags (True -> Wait 300ms -> False).
+     */
     const tap = useCallback(
         async (tagName: string) => {
             const cfg = tags.find((t) => t.tagName === tagName);
@@ -619,22 +540,16 @@ export const AutoCoreTagProvider: React.FC<{
                 return;
             }
 
-            const dom = cfg.domain.toUpperCase();
-            const mkPayload = (val: boolean) =>
-                dom === "ADS"
-                    ? { symbol_name: cfg.symbolName, value: val }
-                    : dom === "GNV"
-                        ? { group: "ux", key: cfg.symbolName, value: val }
-                        : { key: cfg.symbolName, value: val };
-
-            await invoke(cfg.domain, "write_value", mkPayload(true));
+            await hubWrite(cfg.fqdn, true);
             await sleep(300);
-            await invoke(cfg.domain, "write_value", mkPayload(false));
+            await hubWrite(cfg.fqdn, false);
         },
-        [tags, invoke]
+        [tags, hubWrite]
     );
 
-    /** Manual scale update (also writes to server if `serverTag` is present) */
+    /**
+     * Updates a scale factor locally and optionally persists to server.
+     */
     const updateScale = useCallback(
         async (scaleName: string, newScale: number, newLabel: string) => {
             const cfg = scaleValues[scaleName];
@@ -643,28 +558,26 @@ export const AutoCoreTagProvider: React.FC<{
                 return;
             }
 
-            // If scale has a server tag, write to server first (GNV-style)
             if (cfg.serverTag) {
-                await invoke(cfg.serverTag.domain, "write_value", {
-                    group: "ux",
-                    key: cfg.serverTag.symbolName,
-                    value: { name: scaleName, scale: newScale, label: newLabel },
-                });
+                const topic = `${cfg.serverTag.domain}.${cfg.serverTag.symbolName}`;
+                await hubWrite(topic, { name: scaleName, scale: newScale, label: newLabel });
             }
 
-            // Update local scale + recompute displays from raw
             setScaleValues(prev => ({
                 ...prev,
                 [scaleName]: { ...prev[scaleName], scale: newScale, label: newLabel },
             }));
+
             rescaleFromRaw(scaleName);
         },
-        [scaleValues, invoke, rescaleFromRaw]
+        [scaleValues, hubWrite, rescaleFromRaw]
     );
 
-    /** Derive initial display values from any seeded raw values (once scales are known) */
+    /**
+     * Safety net: Recomputes all display values whenever scales or tags change.
+     * Ensures UI consistency even if individual updates were missed.
+     */
     useEffect(() => {
-        // On mount or when scales change, recompute every numeric tag from raw
         setValues(prev => {
             const next = { ...prev };
             for (const tag of tags) {
@@ -677,10 +590,14 @@ export const AutoCoreTagProvider: React.FC<{
         });
     }, [tags, toDisplay, scaleValues]);
 
+    /**
+     * Construct context value. Memoized to prevent consumers from re-rendering
+     * unless actual data changes.
+     */
     const ctxValue = useMemo<BaseContextValue<VMapRuntime>>(
         () => ({
-            values,
-            rawValues,
+            values,       // Display values (scaled)
+            rawValues,    // Raw values (unscaled)
             isLoading,
             write,
             tap,
@@ -695,4 +612,4 @@ export const AutoCoreTagProvider: React.FC<{
             {children}
         </AutoCoreTagContext.Provider>
     );
-};
+};