@adcops/autocore-react 3.0.40 → 3.1.5

package/src/core/AutoCoreTagContext.tsx

@@ -0,0 +1,1137 @@
+/*
+ * Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2025-09-05 07:35:46
+ * -----
+ * Last Modified: 2026-01-17 10:32:56
+ * -----
+ *
+ */
+
+/**
+ * @module core/AutoCoreTagContext
+ * 
+ * @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
+ *
+ * @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
+ *
+ * ❖ **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
+ *
+ * @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}
+ *   },
+ * };
+ *
+ * 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>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+
+
+import React, {
+    useRef,
+    createContext,
+    useCallback,
+    useContext,
+    useEffect,
+    useMemo,
+    useState,
+    type ReactNode,
+} from "react";
+import { EventEmitterContext } from "./EventEmitterContext";
+import type {
+    BaseContextValue,
+    TagConfig,
+    ScaleConfig,
+} from "./AutoCoreTagTypes";
+
+/**
+ * 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: {},
+    isLoading: true,
+    write: async () => { },
+    tap: async () => { },
+    scales: {},
+    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 };
+
+/**
+ * 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));
+
+
+/**
+ * AutoCoreTagProvider
+ *
+ * @description
+ * React Provider that wires up AutoCore tags to live server updates, buffers **raw**
+ * controller values, exposes **display** values (scales/codec applied), and handles
+ * 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>
+ * ```
+ */
+export const AutoCoreTagProvider: React.FC<{
+    children: ReactNode;
+    tags: readonly TagConfig[];
+    scales?: Record<string, ScaleConfig>;
+    eagerRead?: boolean;
+}> = ({ children, tags, scales = {}, eagerRead = true }) => {
+    const startedRef = useRef(false);
+
+    const { invoke, isConnected, subscribe, unsubscribe } =
+        useContext(EventEmitterContext);
+
+    /** Raw (controller) values as received from the server (pre-scale, pre-codec). */
+    const [rawValues, setRawValues] = useState<Record<string, unknown>>(() => {
+        const seed: Record<string, unknown> = {};
+        for (const t of tags) {
+            if (t.initialValue !== undefined) {
+                // Interpret initialValue as **raw**.
+                seed[t.tagName] = t.initialValue;
+            }
+        }
+        return seed;
+    });
+
+    /** App-visible display values, computed from raw using scales/codecs. */
+    const [values, setValues] = useState<Record<string, unknown>>({});
+
+    /** Scales (current factor/label) */
+    const [scaleValues, setScaleValues] =
+        useState<Record<string, ScaleConfig>>(scales);
+
+    /** Keep refs for subscription callbacks without re-subscribing */
+    const scaleRef = useRef(scaleValues);
+    const rawRef = useRef(rawValues);
+    useEffect(() => { scaleRef.current = scaleValues; }, [scaleValues]);
+    useEffect(() => { rawRef.current = rawValues; }, [rawValues]);
+
+    const [isLoading, setIsLoading] = useState(true);
+
+    /**
+     * Converts a raw controller value to a display value.
+     *
+     * This function applies transformations in the following order:
+     * 1. **Numeric scaling**: If the tag has a scale group and the value is a number,
+     *    multiply by the scale factor (e.g., mm → inches)
+     * 2. **JSON codec**: If the tag has a codec with `fromServer`, apply it to decode
+     *    the server representation (e.g., JSON string → object)
+     * 3. **Pass-through**: If no transformations apply, return the raw value as-is
+     *
+     * @param tag - The tag configuration containing valueType, scale group, and optional codec
+     * @param raw - The raw value received from the controller/server
+     * @returns The display value suitable for showing in the UI
+     *
+     * @example
+     * // For a position tag with scale factor 0.03937 (mm to inches)
+     * toDisplay(positionTag, 254) // returns 10.0 (inches)
+     *
+     * @example
+     * // For a JSON tag with codec
+     * toDisplay(jsonTag, '{"name":"test"}') // returns { name: "test" }
+     */
+    const toDisplay = useCallback((tag: TagConfig, raw: unknown): unknown => {
+        const { valueType, scale, codec } = tag;
+
+        // 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): decode server representation
+        if (valueType === "json" && codec?.fromServer) {
+            try { return codec.fromServer(raw); } catch { /* fall through */ }
+        }
+
+        // 3) pass-through: no transformation needed
+        return raw;
+    }, []);
+
+    /**
+     * Converts a display value back to a raw controller value for writing.
+     *
+     * This is the inverse of `toDisplay`. It reverses transformations so that
+     * writes from the UI are sent to the server in controller units.
+     *
+     * Transformations are applied in reverse order:
+     * 1. **JSON codec**: If the tag has a codec with `toServer`, apply it to encode
+     *    the value for the server (e.g., object → JSON string)
+     * 2. **Inverse scaling**: If the tag has a scale group and the value is a number,
+     *    divide by the scale factor to convert back to controller units
+     *
+     * @param tag - The tag configuration containing valueType, scale group, and optional codec
+     * @param display - The display value from the UI (in user-facing units)
+     * @returns The raw value to send to the controller/server
+     *
+     * @example
+     * // For a position tag with scale factor 0.03937 (mm to inches)
+     * // User enters 10 inches, need to send 254 mm to controller
+     * toServer(positionTag, 10.0) // returns 254.0 (mm)
+     *
+     * @example
+     * // For a JSON tag with codec
+     * toServer(jsonTag, { name: "test" }) // returns '{"name":"test"}'
+     */
+    const toServer = useCallback((tag: TagConfig, display: unknown): unknown => {
+        const { valueType, scale, codec } = tag;
+
+        // 1) invert codec first (json): encode for server
+        if (valueType === "json" && codec?.toServer) {
+            try { display = codec.toServer(display as any); } catch { /* fall through */ }
+        }
+
+        // 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;
+            return display / factor;
+        }
+
+        return display;
+    }, []);
+
+    /**
+     * Recomputes display values for all tags that use a specific scale group.
+     *
+     * This function is called when a scale factor changes. It:
+     * 1. Finds all tags that belong to the specified scale group
+     * 2. For each tag, retrieves the current RAW value (not the old display value)
+     * 3. Applies the NEW scale factor to compute updated display values
+     *
+     * **Important**: This always recomputes from RAW values to avoid cumulative
+     * precision errors. If we scaled from display values, repeated scale changes
+     * would accumulate floating-point errors.
+     *
+     * @param scaleName - The name of the scale group to recompute (e.g., "position", "load")
+     *
+     * @example
+     * // When user switches from mm to inches:
+     * // 1. Scale factor changes from 1.0 to 0.03937
+     * // 2. rescaleFromRaw("position") is called
+     * // 3. All position tags are recomputed: raw_mm * 0.03937 = display_inches
+     */
+    const rescaleFromRaw = useCallback((scaleName: string) => {
+        const affected = tags.filter(t => t.scale === scaleName);
+        if (!affected.length) return;
+
+        setValues(prev => {
+            const next = { ...prev };
+            for (const tag of affected) {
+                const raw = rawRef.current[tag.tagName];
+                if (typeof raw !== "number") continue;
+                const disp = toDisplay(tag, raw);
+                if (next[tag.tagName] !== disp) next[tag.tagName] = disp;
+            }
+            return next;
+        });
+    }, [tags, toDisplay]);
+
+    /**
+     * Handles incoming value updates from the server.
+     *
+     * This is the callback invoked when the server broadcasts a new value for a tag.
+     * It performs two operations:
+     *
+     * 1. **Store raw value**: Saves the unmodified controller value in `rawValues`.
+     *    This is the source of truth that scaling is computed from.
+     *
+     * 2. **Compute display value**: Applies scaling/codecs via `toDisplay()` and
+     *    stores the result in `values` for UI consumption.
+     *
+     * Both updates are done immutably - if the value hasn't changed, React state
+     * is not updated (preventing unnecessary re-renders).
+     *
+     * @param tag - The tag configuration for the updated value
+     * @param raw - The raw value received from the server (in controller units)
+     *
+     * @example
+     * // Server broadcasts: MODBUS/simulator.holding_0 with value 42
+     * // EventEmitter callback receives data: { value: 42 }
+     * handleTagUpdate(holdingTag, 42);
+     * // rawValues["holdingReg0"] = 42
+     * // values["holdingReg0"] = 42 (or scaled if scale configured)
+     */
+    const handleTagUpdate = useCallback((tag: TagConfig, raw: unknown) => {
+        // Store the raw controller value (source of truth for scaling)
+        setRawValues(prev =>
+            prev[tag.tagName] === raw ? prev : { ...prev, [tag.tagName]: 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]);
+
+    /**
+     * Performs eager (one-time) reads for non-ADS domain tags.
+     *
+     * This function fetches initial values for tags that don't use the ADS protocol.
+     * It uses a worker pool pattern to read multiple tags concurrently while
+     * respecting rate limits.
+     *
+     * **Strategy for each tag:**
+     * 1. First, try `refresh` command - this asks the server to broadcast the current
+     *    value (if the domain supports it). This is preferred because it uses the
+     *    normal broadcast path.
+     * 2. If `refresh` fails, fall back to `read_value` - a direct request/response
+     *    read of the tag value.
+     *
+     * **Rate limiting:**
+     * - Uses configurable concurrency (default 4 parallel workers)
+     * - Adds delay + random jitter between requests to avoid overwhelming the server
+     *
+     * **Error handling:**
+     * - Missing keys are common on fresh systems and are silently ignored
+     * - Other errors are caught but don't stop the worker pool
+     *
+     * @param domain - The domain to read from (e.g., "GNV", "MODBUS", "DATASTORE")
+     * @param tagList - List of tags to read values for
+     * @param opts - Optional configuration for rate limiting
+     * @param opts.concurrency - Number of parallel workers (default: 4)
+     * @param opts.minDelayMs - Minimum delay between requests per worker (default: 20ms)
+     * @param opts.jitterMs - Random additional delay range (default: 0-40ms)
+     *
+     * @example
+     * // Read all GNV tags with default rate limiting
+     * await eagerPullNonADS("GNV", gnvTags);
+     *
+     * @example
+     * // Read MODBUS tags with custom concurrency
+     * await eagerPullNonADS("MODBUS", modbusTags, { concurrency: 2, minDelayMs: 50 });
+     */
+    const eagerPullNonADS = useCallback(
+        async (
+            domain: string,
+            tagList: readonly TagConfig[],
+            opts?: { concurrency?: number; minDelayMs?: number; jitterMs?: number }
+        ) => {
+            const concurrency = opts?.concurrency ?? 4;
+            const minDelayMs = opts?.minDelayMs ?? 20;
+            const jitterMs = opts?.jitterMs ?? 40;
+
+            // Shared index counter for work-stealing pattern
+            let index = 0;
+
+            // Create worker pool - each worker pulls tags from shared queue
+            const workers = Array.from({ length: concurrency }, () => (async () => {
+                while (true) {
+                    // Atomically grab next tag index
+                    const i = index++;
+                    if (i >= tagList.length) return; // No more work
+                    const tag = tagList[i];
+
+                    try {
+                        // Strategy 1: Try refresh (asks server to broadcast current value)
+                        let usedPublishPath = false;
+                        try {
+                            await invoke(domain, "refresh", { topic: tag.symbolName });
+                            usedPublishPath = true;
+                        } catch { /* refresh not supported, fall through to read_value */ }
+
+                        // Strategy 2: Fall back to direct read_value
+                        if (!usedPublishPath) {
+                            // Build domain-specific payload (GNV uses group:"ux")
+                            const payload =
+                                domain.toUpperCase() === "GNV"
+                                    ? { group: "ux", key: tag.symbolName }
+                                    : { key: tag.symbolName };
+
+                            if (tag.options) (payload as any).options = tag.options;
+
+                            try {
+                                const resp: any = await invoke(domain, "read_value", payload);
+                                // Server always returns { success, valid, data }
+                                if (resp?.success && resp?.valid) {
+                                    handleTagUpdate(tag, resp.data);
+                                }
+                            } catch (err) {
+                                // Missing key on fresh systems is normal; keep going.
+                            }
+                        }
+                    } catch (outerErr) {
+                        // Never throw out of the worker loop - one failure shouldn't stop others
+                    } finally {
+                        // Rate limiting: delay + jitter before next request
+                        const extra = Math.floor(Math.random() * jitterMs);
+                        await sleep(minDelayMs + extra);
+                    }
+                }
+            })());
+
+            // Wait for all workers to complete
+            await Promise.all(workers);
+        },
+        [invoke, handleTagUpdate]
+    );
+
+    /**
+     * Fetches server-stored scale configurations before loading tag values.
+     *
+     * Scales may be stored on the server (typically in the GNV domain) so that
+     * unit preferences persist across sessions. This function reads those stored
+     * scale values before any tag values are loaded.
+     *
+     * **Why this runs first:**
+     * If we loaded tag values before knowing the correct scale factor, the initial
+     * display would show wrong units, then "jump" when the scale arrived. By loading
+     * scales first, the first display of tag values is already in correct units.
+     *
+     * **Server format:**
+     * The server stores scales as JSON objects: `{ name, scale, label }`
+     * For example: `{ name: "position", scale: 0.03937, label: "in" }`
+     *
+     * @example Scale configuration with serverTag
+     * ```typescript
+     * const scales = {
+     *   position: {
+     *     name: "position",
+     *     scale: 1.0,        // default until server value loaded
+     *     label: "mm",       // default until server value loaded
+     *     serverTag: { domain: "GNV", symbolName: "position_units" }
+     *   }
+     * };
+     * ```
+     */
+    const pullServerScales = useCallback(async () => {
+        for (const [scaleName, cfg] of Object.entries(scales)) {
+            // Skip scales that don't have server storage configured
+            if (!cfg.serverTag) continue;
+            const { domain, symbolName } = cfg.serverTag;
+
+            try {
+                // Read the scale configuration from server (GNV-style payload)
+                const respUnknown = await invoke(domain, "read_value", {
+                    group: "ux",
+                    key: symbolName,
+                });
+
+                // Parse response envelope
+                const env = respUnknown as HubEnvelope<string>;
+                if (env.data && (env.success ?? true) && (env.valid ?? true)) {
+                    // Server stores as JSON string, parse it
+                    const env_data = JSON.parse(env.data) as ScaleConfig;
+                    if (env_data && typeof env_data.scale === "number" ) {
+                        const { scale, label } = env_data;
+                        // Update local scale state
+                        setScaleValues(prev => ({
+                            ...prev,
+                            [scaleName]: {
+                                ...prev[scaleName],
+                                scale,
+                                label: label ?? prev[scaleName]?.label ?? "---",
+                            },
+                        }));
+                        // Recompute any existing display values with new scale
+                        rescaleFromRaw(scaleName);
+                    }
+                }
+            } catch {
+                // Scale not present on server yet - use defaults from props
+            }
+        }
+    }, [invoke, scales, rescaleFromRaw]);
+
+    /**
+     * ==========================================================================
+     * MAIN SUBSCRIPTION WIRING EFFECT
+     * ==========================================================================
+     *
+     * This useEffect is the heart of the AutoCoreTagProvider. It sets up all
+     * the plumbing to receive live tag updates from the server.
+     *
+     * IMPORTANT CONCEPTS:
+     *
+     * 1. **Local EventEmitter subscriptions** (subscribe() function):
+     *    - These register callbacks in the browser to receive broadcast messages
+     *    - When the server sends a broadcast, the WebSocket layer receives it and
+     *      the EventEmitter dispatches it to matching subscribers
+     *    - This is CLIENT-SIDE ONLY - it does NOT tell the server anything
+     *
+     * 2. **Server-side subscriptions** (invoke with "subscribe" or "register_symbol"):
+     *    - These tell the server "please start sending me updates for X"
+     *    - Without this, the server doesn't know to broadcast anything
+     *    - ADS: Uses "register_symbol" which implicitly subscribes
+     *    - Other domains (MODBUS, etc.): Need explicit "subscribe" command
+     *
+     * DATA FLOW:
+     *
+     *   [Server changes value]
+     *          ↓
+     *   [Server broadcasts if client is subscribed]  ← requires server-side subscription
+     *          ↓
+     *   [WebSocket receives broadcast]
+     *          ↓
+     *   [EventEmitter dispatches to local subscribers]  ← requires local subscription
+     *          ↓
+     *   [handleTagUpdate callback fires]
+     *          ↓
+     *   [rawValues and values state updated]
+     *          ↓
+     *   [React re-renders with new values]
+     */
+    useEffect(() => {
+        // Track if component is still mounted (for async safety)
+        let mounted = true;
+        // Collect subscription IDs for cleanup on unmount
+        const subscriptions: number[] = [];
+
+        /**
+         * Main registration and subscription function.
+         *
+         * This orchestrates the entire setup process in a specific order to ensure
+         * values display correctly from the first render.
+         */
+        const registerAndSubscribe = async () => {
+
+            // ──────────────────────────────────────────────────────────────────
+            // STEP 0: Group tags by domain
+            // ──────────────────────────────────────────────────────────────────
+            // We process tags domain-by-domain because each domain has different
+            // registration and subscription requirements.
+            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 {
+                // ──────────────────────────────────────────────────────────────
+                // STEP 1: Load server-stored scale factors FIRST
+                // ──────────────────────────────────────────────────────────────
+                // Why first? So when tag values arrive, they're already displayed
+                // in the correct units. Otherwise values would "jump" when scales load.
+                await pullServerScales();
+
+                // ──────────────────────────────────────────────────────────────
+                // STEP 2: Process each domain
+                // ──────────────────────────────────────────────────────────────
+                for (const [domain, tagList] of tagsByDomain.entries()) {
+
+                    // ──────────────────────────────────────────────────────────
+                    // STEP 2a: Subscribe to onchange notification
+                    // ──────────────────────────────────────────────────────────
+                    if (domain.toUpperCase() === "ADS") {
+                        // ADS (Beckhoff TwinCAT) requires explicit symbol registration.
+                        // This tells the ADS server "I want to access this PLC variable."
+                        // The registration also sets up server-side subscriptions for
+                        // the ADS notification system.
+
+                        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}`);
+                            }
+                        }
+                    }
+                    else {
+                        // For all other modules, use autocore-server standard subscription logic.
+                        // This will be standardized in future versions of autocore-server, but for
+                        // now we use the original autocore-server protocol system.
+                        for ( const tag of tagList ) {
+                            await invoke (domain, "subscribe", {data_filter: tag.symbolName});
+                        }
+                    }
+
+                    // ──────────────────────────────────────────────────────────
+                    // STEP 2b: Set up LOCAL EventEmitter subscriptions
+                    // ──────────────────────────────────────────────────────────
+                    // This registers callbacks in the browser's EventEmitter.
+                    // When a broadcast arrives via WebSocket, it will be dispatched
+                    // to these callbacks.
+                    //
+                    // IMPORTANT: This is CLIENT-SIDE ONLY!
+                    // It does NOT tell the server to start sending updates.
+                    // For ADS, register_symbol (above) handles that.
+                    // For other domains, we need to send a "subscribe" command.
+                    //
+                    // Topic format: "DOMAIN/symbolName"
+                    // Example: "MODBUS/simulator.holding_0"
+                    for (const tag of tagList) {
+                        const id = subscribe(`${domain}/${tag.symbolName}`, (data) => {
+                            if (!mounted) return;
+                            handleTagUpdate(tag, data?.value);
+                        });
+                        subscriptions.push(id);
+                    }
+
+                    // ──────────────────────────────────────────────────────────
+                    // STEP 2c: Eager reads for non-ADS domains
+                    // ──────────────────────────────────────────────────────────
+                    // For domains other than ADS, we do a one-time read to get
+                    // initial values. ADS has its own "refresh" mechanism.
+                    if (eagerRead && domain.toUpperCase() !== "ADS") {
+                        await eagerPullNonADS(domain, tagList, { concurrency: 4, minDelayMs: 20, jitterMs: 40 });
+                    }
+                }
+
+                // ──────────────────────────────────────────────────────────────
+                // STEP 3: ADS one-shot refresh
+                // ──────────────────────────────────────────────────────────────
+                // Tells the ADS server to immediately publish current values for
+                // all registered symbols. This gives us initial values quickly.
+                if (eagerRead) {
+                    await invoke("ADS", "refresh", {});
+                }
+            } finally {
+                // Mark loading complete (with small delay for UI smoothness)
+                if (mounted) setTimeout(() => mounted && setIsLoading(false), 100);
+            }
+        };
+
+        /**
+         * Wrapper to ensure registerAndSubscribe only runs once.
+         * Uses startedRef to prevent duplicate initialization from React strict mode
+         * or rapid re-renders.
+         */
+        const safeRegister = async () => {
+            if (!mounted || startedRef.current) return;
+            startedRef.current = true;
+            try { await registerAndSubscribe(); }
+            finally { if (mounted) setTimeout(() => mounted && setIsLoading(false), 100); }
+        };
+
+        // ──────────────────────────────────────────────────────────────────────
+        // INITIALIZATION: Wait for WebSocket connection before registering
+        // ──────────────────────────────────────────────────────────────────────
+        if (!isConnected()) {
+            // Not connected yet - wait for connection event
+            const id = subscribe("HUB/connected", () => {
+                unsubscribe(id);
+                void safeRegister();
+            });
+            subscriptions.push(id);
+        } else {
+            // Already connected - register immediately
+            void safeRegister();
+        }
+
+        // ──────────────────────────────────────────────────────────────────────
+        // CLEANUP: Unsubscribe from all local subscriptions on unmount
+        // ──────────────────────────────────────────────────────────────────────
+        return () => {
+            mounted = false;
+            subscriptions.forEach(unsubscribe);
+            startedRef.current = false;
+        };
+    }, [subscribe, unsubscribe, isConnected, invoke, eagerRead, tags, pullServerScales, eagerPullNonADS, handleTagUpdate]);
+
+    /**
+     * Memoized list of scale configurations that have server-side storage.
+     * Used to set up live subscriptions for scale changes (e.g., when another
+     * user changes unit preferences).
+     */
+    const scaleServerSubs = useMemo(
+        () =>
+            Object.entries(scales)
+                .filter(([, cfg]) => cfg.serverTag)
+                .map(([scaleName, cfg]) => ({
+                    scaleName,
+                    domain: cfg.serverTag!.domain,
+                    symbolName: cfg.serverTag!.symbolName,
+                })),
+        [scales]
+    );
+
+    /**
+     * ==========================================================================
+     * SCALE BROADCAST SUBSCRIPTIONS
+     * ==========================================================================
+     *
+     * This effect sets up live subscriptions to server-stored scale values.
+     * When a scale changes on the server (e.g., another user switches from mm to inches),
+     * this subscription receives the update and recomputes all affected display values.
+     *
+     * Note: This is separate from pullServerScales() which does a one-time read.
+     * This effect keeps the UI in sync with server changes in real-time.
+     */
+    useEffect(() => {
+        let mounted = true;
+        const subs: number[] = [];
+
+        for (const { scaleName, domain, symbolName } of scaleServerSubs) {
+            // Subscribe to broadcasts for this scale's server tag
+            const id = subscribe(`${domain}/${symbolName}`, (data) => {
+                if (!mounted) return;
+                const v = data?.value;
+                // Validate the received data has the expected shape
+                if (v && typeof v === "object" && typeof (v as any).scale === "number") {
+                    const { scale, label } = v as { scale: number; label?: string };
+                    // Update local scale state
+                    setScaleValues(prev => ({
+                        ...prev,
+                        [scaleName]: {
+                            ...prev[scaleName],
+                            scale,
+                            label: label ?? prev[scaleName]?.label ?? "---",
+                        },
+                    }));
+                    // Recompute all display values that use this scale
+                    rescaleFromRaw(scaleName);
+                }
+            });
+            subs.push(id);
+        }
+
+        // Cleanup subscriptions on unmount
+        return () => {
+            mounted = false;
+            subs.forEach(unsubscribe);
+        };
+    }, [subscribe, unsubscribe, scaleServerSubs, rescaleFromRaw]);
+
+    /**
+     * Writes a value to a tag on the server.
+     *
+     * This function:
+     * 1. Looks up the tag configuration by name
+     * 2. Converts display value → server value (inverse scaling, codec encoding)
+     * 3. Builds the appropriate payload for the tag's domain
+     * 4. Sends the write command to the server
+     *
+     * **Domain-specific payloads:**
+     * - ADS: `{ symbol_name: "...", value: ... }`
+     * - GNV: `{ group: "ux", key: "...", value: ... }`
+     * - Other: `{ key: "...", value: ... }`
+     *
+     * @param tagName - The tag name (as defined in TagConfig, not symbolName)
+     * @param displayValue - The value in display units (will be inverse-scaled)
+     *
+     * @example
+     * // Write 10 inches to a position tag (scale converts to 254mm for server)
+     * await write("pressPosition", 10.0);
+     *
+     * @example
+     * // Write a boolean
+     * await write("isMotorsOn", true);
+     */
+    const write = useCallback(
+        async (tagName: string, displayValue: unknown) => {
+            // Find the tag configuration
+            const cfg = tags.find((t) => t.tagName === tagName);
+            if (!cfg) {
+                console.error(`write(): unknown tag '${tagName}'`);
+                return;
+            }
+
+            // Convert display value to server value (inverse scaling/codec)
+            const serverValue = toServer(cfg, displayValue);
+
+            // Build domain-specific payload
+            let payload: any;
+            const dom = cfg.domain.toUpperCase();
+            if (dom === "ADS") {
+                // ADS uses symbol_name
+                payload = { symbol_name: cfg.symbolName, value: serverValue };
+            } else if (dom === "GNV") {
+                // GNV uses group + key
+                payload = { group: "ux", key: cfg.symbolName, value: serverValue };
+            } else {
+                // Other domains (MODBUS, DATASTORE, etc.) use key
+                payload = { key: cfg.symbolName, value: serverValue };
+            }
+
+            // Send to server
+            await invoke(cfg.domain, "write_value", payload);
+        },
+        [tags, invoke, toServer]
+    );
+
+    /**
+     * Pulses a boolean tag: writes true, waits 300ms, then writes false.
+     *
+     * This is commonly used for "momentary" buttons or triggers in automation
+     * systems where you need to send a rising edge rather than toggle state.
+     *
+     * **Only works with boolean tags** - logs a warning if called on other types.
+     *
+     * @param tagName - The tag name (must be a boolean type tag)
+     *
+     * @example
+     * // Pulse a "start cycle" button
+     * await tap("cycleStart");
+     * // Server receives: true at t=0, false at t=300ms
+     *
+     * @example
+     * // In a React component
+     * const { tap } = useAutoCoreTag("motorsEnable");
+     * return <button onClick={() => tap()}>Enable Motors</button>;
+     */
+    const tap = useCallback(
+        async (tagName: string) => {
+            // Find the tag configuration
+            const cfg = tags.find((t) => t.tagName === tagName);
+            if (!cfg) {
+                console.error(`tap(): unknown tag '${tagName}'`);
+                return;
+            }
+            // Only boolean tags can be tapped
+            if (cfg.valueType !== "boolean") {
+                console.warn(`tap(): tag '${tagName}' is not a boolean type`);
+                return;
+            }
+
+            // Helper to build domain-specific payload
+            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 };
+
+            // Pulse: true → wait → false
+            await invoke(cfg.domain, "write_value", mkPayload(true));
+            await sleep(300);
+            await invoke(cfg.domain, "write_value", mkPayload(false));
+        },
+        [tags, invoke]
+    );
+
+    /**
+     * Updates a scale factor and label, optionally persisting to the server.
+     *
+     * This function:
+     * 1. Validates the scale name exists
+     * 2. If the scale has a serverTag, writes the new configuration to the server
+     *    (so other clients and future sessions use the same units)
+     * 3. Updates local scale state
+     * 4. Recomputes all affected display values from raw
+     *
+     * **Server format:** `{ name: "position", scale: 0.03937, label: "in" }`
+     *
+     * @param scaleName - The scale group name (e.g., "position", "load")
+     * @param newScale - The new scale factor to apply (raw * scale = display)
+     * @param newLabel - The new unit label to display (e.g., "in", "mm", "lbs")
+     *
+     * @example
+     * // Switch position display from mm to inches
+     * await updateScale("position", 0.03937, "in");
+     *
+     * @example
+     * // In a React component with unit selector
+     * const { scales, updateScale } = useScales();
+     * return (
+     *   <select onChange={(e) => {
+     *     if (e.target.value === "mm") updateScale("position", 1.0, "mm");
+     *     if (e.target.value === "in") updateScale("position", 0.03937, "in");
+     *   }}>
+     *     <option value="mm">Millimeters</option>
+     *     <option value="in">Inches</option>
+     *   </select>
+     * );
+     */
+    const updateScale = useCallback(
+        async (scaleName: string, newScale: number, newLabel: string) => {
+            const cfg = scaleValues[scaleName];
+            if (!cfg) {
+                console.error(`Scale '${scaleName}' not found`);
+                return;
+            }
+
+            // If scale has a server tag, persist to server for other clients/sessions
+            if (cfg.serverTag) {
+                await invoke(cfg.serverTag.domain, "write_value", {
+                    group: "ux",
+                    key: cfg.serverTag.symbolName,
+                    value: { name: scaleName, scale: newScale, label: newLabel },
+                });
+            }
+
+            // Update local scale state
+            setScaleValues(prev => ({
+                ...prev,
+                [scaleName]: { ...prev[scaleName], scale: newScale, label: newLabel },
+            }));
+
+            // Recompute all display values that use this scale (from raw values)
+            rescaleFromRaw(scaleName);
+        },
+        [scaleValues, invoke, rescaleFromRaw]
+    );
+
+    /**
+     * ==========================================================================
+     * DISPLAY VALUES RECOMPUTATION EFFECT
+     * ==========================================================================
+     *
+     * This effect ensures display values stay in sync when:
+     * 1. Component mounts with initial/seeded raw values
+     * 2. Scale factors change (scaleValues dependency)
+     * 3. Tag configuration changes (tags dependency)
+     *
+     * It iterates all tags and recomputes display values from raw using the
+     * current scale factors. This is a safety net that catches edge cases
+     * where individual updates might have been missed.
+     *
+     * Note: Individual updates via handleTagUpdate are more efficient for
+     * normal operation. This effect handles bulk recomputation scenarios.
+     */
+    useEffect(() => {
+        // Recompute every tag's display value from its raw value
+        setValues(prev => {
+            const next = { ...prev };
+            for (const tag of tags) {
+                const raw = rawRef.current[tag.tagName];
+                if (raw === undefined) continue;
+                const disp = toDisplay(tag, raw);
+                // Only update if value actually changed (avoid unnecessary re-renders)
+                if (next[tag.tagName] !== disp) next[tag.tagName] = disp;
+            }
+            return next;
+        });
+    }, [tags, toDisplay, scaleValues]);
+
+    /**
+     * Memoized context value to prevent unnecessary re-renders.
+     * Only recreates when one of the dependencies actually changes.
+     */
+    const ctxValue = useMemo<BaseContextValue<VMapRuntime>>(
+        () => ({
+            values,       // Display values (scaled/decoded) - what the UI shows
+            rawValues,    // Raw controller values - source of truth for scaling
+            isLoading,    // True until initial setup completes
+            write,        // Function to write a value to a tag
+            tap,          // Function to pulse a boolean tag
+            scales: scaleValues,  // Current scale configurations
+            updateScale,  // Function to change scale factor/label
+        }),
+        [values, rawValues, isLoading, write, tap, scaleValues, updateScale]
+    );
+
+    /**
+     * Render the context provider with all state and functions available
+     * to child components via useContext(AutoCoreTagContext) or the typed hooks.
+     */
+    return (
+        <AutoCoreTagContext.Provider value={ctxValue}>
+            {children}
+        </AutoCoreTagContext.Provider>
+    );
+};