@adcops/autocore-react 3.1.1 → 3.1.5

package/src/core/AutoCoreTagContext.tsx

@@ -2,7 +2,7 @@
  * 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-17 10:32:56
  * -----
  *
  */
@@ -123,8 +123,27 @@ import type {
     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: {},
@@ -135,9 +154,24 @@ 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));
 
 
@@ -294,36 +328,81 @@ 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.
+     *
+     * 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
+        // 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 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;
 
-        // 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 +412,26 @@ export const AutoCoreTagProvider: React.FC<{
         return display;
     }, []);
 
-    /** Recompute display values for all tags in this scale from **raw** */
+    /**
+     * 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;
@@ -350,20 +448,80 @@ export const AutoCoreTagProvider: React.FC<{
         });
     }, [tags, toDisplay]);
 
-    /** Subscribe handler for tag updates: buffer raw, compute display. */
+    /**
+     * 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) => {
-        // 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 */
+    /**
+     * 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,
@@ -374,21 +532,28 @@ export const AutoCoreTagProvider: React.FC<{
             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;
+                    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 { /* fall through */ }
+                        } 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 }
@@ -407,39 +572,70 @@ export const AutoCoreTagProvider: React.FC<{
                             }
                         }
                     } catch (outerErr) {
-                        // never throw out of the worker loop
-                        // console.warn(`eager pull worker error for ${domain}/${tag.symbolName}`, 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]
     );
 
-    /** Pull server scale objects first thing (GNV envelope) */
+    /**
+     * 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,
                 });
 
-                // narrow at runtime instead of forcing a direct cast
+                // 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]: {
@@ -448,22 +644,73 @@ export const AutoCoreTagProvider: React.FC<{
                                 label: label ?? prev[scaleName]?.label ?? "---",
                             },
                         }));
+                        // Recompute any existing display values with new scale
                         rescaleFromRaw(scaleName);
                     }
                 }
             } catch {
-                // Ok if not present yet.
+                // Scale not present on server yet - use defaults from props
             }
         }
     }, [invoke, scales, rescaleFromRaw]);
 
-    // Main subscription wiring
+    /**
+     * ==========================================================================
+     * 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 () => {
-            // group tags by domain
+
+            // ──────────────────────────────────────────────────────────────────
+            // 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);
@@ -471,12 +718,27 @@ export const AutoCoreTagProvider: React.FC<{
             }
 
             try {
-                // 0) load scales first so first ADS values get correct factor
+                // ──────────────────────────────────────────────────────────────
+                // 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();
 
-                // 1) ADS register (sequential is fine)
+                // ──────────────────────────────────────────────────────────────
+                // 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
@@ -488,8 +750,29 @@ export const AutoCoreTagProvider: React.FC<{
                             }
                         }
                     }
+                    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});
+                        }
+                    }
 
-                    // 2) subscribe
+                    // ──────────────────────────────────────────────────────────
+                    // 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;
@@ -498,21 +781,35 @@ export const AutoCoreTagProvider: React.FC<{
                         subscriptions.push(id);
                     }
 
-                    // 3) eager reads (non-ADS)
+                    // ──────────────────────────────────────────────────────────
+                    // 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 });
                     }
                 }
 
-                // 4) ADS one-shot refresh (after scales are known)
+                // ──────────────────────────────────────────────────────────────
+                // 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;
@@ -520,16 +817,24 @@ export const AutoCoreTagProvider: React.FC<{
             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);
@@ -537,7 +842,11 @@ export const AutoCoreTagProvider: React.FC<{
         };
     }, [subscribe, unsubscribe, isConnected, invoke, eagerRead, tags, pullServerScales, eagerPullNonADS, handleTagUpdate]);
 
-    /** Subscribe to server-driven scale tags (GNV object), recompute displays from raw. */
+    /**
+     * 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)
@@ -550,16 +859,31 @@ export const AutoCoreTagProvider: React.FC<{
         [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]: {
@@ -568,57 +892,112 @@ export const AutoCoreTagProvider: React.FC<{
                             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]);
 
-    /** Write with inverse scaling and proper domain envelopes. */
+    /**
+     * 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]
     );
 
-    /** Tap (boolean pulse) */
+    /**
+     * 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"
@@ -627,6 +1006,7 @@ export const AutoCoreTagProvider: React.FC<{
                         ? { 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));
@@ -634,7 +1014,39 @@ export const AutoCoreTagProvider: React.FC<{
         [tags, invoke]
     );
 
-    /** Manual scale update (also writes to server if `serverTag` is present) */
+    /**
+     * 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];
@@ -643,7 +1055,7 @@ export const AutoCoreTagProvider: React.FC<{
                 return;
             }
 
-            // If scale has a server tag, write to server first (GNV-style)
+            // 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",
@@ -652,44 +1064,71 @@ export const AutoCoreTagProvider: React.FC<{
                 });
             }
 
-            // Update local scale + recompute displays from raw
+            // 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]
     );
 
-    /** Derive initial display values from any seeded raw values (once scales are known) */
+    /**
+     * ==========================================================================
+     * 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(() => {
-        // On mount or when scales change, recompute every numeric tag from raw
+        // 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,
-            rawValues,
-            isLoading,
-            write,
-            tap,
-            scales: scaleValues,
-            updateScale,
+            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}