@adcops/autocore-react 3.3.9 → 3.3.14

package/additional-docs/AutoCoreTagContext.md

@@ -1,441 +1,441 @@
-# AutoCoreTagContext Manual
-
-This manual explains how to configure, provide, and consume the **AutoCoreTagContext** system.  
-The goal is to create a **typed, global context** of tags (values from `autocore-server`), so your React components can read and update them easily.
-
----
-
-## Overview
-
-The AutoCoreTagContext is built around three parts:
-
-1. **Context** – created with `makeAutoCoreTagContext` to hold live tag values.  
-2. **Hooks** – created with `makeAutoCoreTagHooks` to read, write, tap, and derive values.  
-3. **Dev Panel** – created with `makeAutoCoreDevPanel` to inspect and manually interact with tags during development.
-
-Tags are defined in a `spec` object: an array of `TagConfig` entries that tell the system what to subscribe to.
-
----
-
-## Summary
-
-- Define tags once in a spec.
-- Create context, hooks, and optionally a Dev Panel.
-- Provide the context at the root of your app.
-- Consume via:
-    - useAutoCoreTag → single value + actions.
-    - useAutoCoreTags → bulk values.
-    - useAutoCoreSelect → computed state.
-
-This makes your React UI a strongly-typed, declarative layer over the live tag system from autocore-server.
-
-
-## Defining Your Tags and AutoCoreHooks
-
-In this initial step, we make two files:
-1. AutoCoreTags.ts
-2. AutoCore.ts
-
-Note that ADC is working to create a VS Code extension for help auto-generating these files.
-
-### AutoCoreTags.ts
-
-To maintain type safety, tags are defined and exported from a TypeScript file. Tags are defined as an array of TagConfig objects.
-
-Each tag has:
-- `tagName` – your local name for the tag.
-- `domain` – the domain for the symbol (e.g., `"ADS"`, `"MEMORYSTORE"`).
-- `symbolName` – the backend symbol name.
-- `valueType` – `"boolean"`, `"number"`, `"string"`, or `"json"`.
-- `initialValue` (optional) – value before first update.
-- `options` (optional) – advanced subscription options.
-
-By convention, the TypeScript file is located in the same directory as App.tsx and named AutoCoreTags.ts. The exported object is named acTagSpec.
-
-Example:
-
-```ts
-import type { TagConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
-
-export const acTagSpec = [
-  { "tagName": "isControlPowerOk", "domain": "ADS", "symbolName": "GIO.xbControlPowerOk", "valueType": "boolean" },
-  { "tagName": "positionScalar",   "domain": "MEMORYSTORE", "symbolName": "position_scalar", "valueType": "number",  "initialValue": 1.0 },
-  { "tagName": "isAutoCycleRunning",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAutoCycleRunning", "valueType": "boolean" },
-  { "tagName": "isAutoCycleRunning",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAutoCycleRunning", "valueType": "boolean" },
-  { "tagName": "shuttlePosition",   "domain": "ADS", "symbolName": "MAIN.ctx.gio.axisShuttle.fPosition", "valueType": "number" },
-  { "tagName": "pressLoad",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressLoad", "valueType": "number" },
-  { "tagName": "pressPosition",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPosition", "valueType": "number" },
-  { "tagName": "pressPeakLoad",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPeakLoad", "valueType": "number" },
-  { "tagName": "isReadyForCycle",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bReadyForCycle", "valueType": "boolean" },  
-  { "tagName": "reqStartAuto",   "domain": "ADS", "symbolName": "MAIN.ctx.gsig.bSigStartAuto", "valueType": "boolean" },  
-  { "tagName": "useSecondaryLoadChannel",   "domain": "ADS", "symbolName": "MAIN.ctx.gnv.bEnableSecondaryLoadInput", "valueType": "boolean" },  
-  { "tagName": "isLoadCellOverrange",   "domain": "ADS", "symbolName": "MAIN.ctx.gio.xstLoadInputStatus.IsOverrange", "valueType": "boolean" },  
-  { "tagName": "isLoadCellUnderrange",   "domain": "ADS", "symbolName": "MAIN.ctx.gio.xstLoadInputStatus.IsUnderrange", "valueType": "boolean" },  
-  { "tagName": "isMotorsOn",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAllMotorsOn", "valueType": "boolean" },  
-  { "tagName": "isAxisErrorPresent",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAxisErrorPresent", "valueType": "boolean" },  
-  { "tagName": "isAllAxesHomed",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAllAxesHomed", "valueType": "boolean" },  
-  { "tagName": "isReadyForOperation",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bReadyForOperation", "valueType": "boolean" }
-] as const satisfies readonly TagConfig[];
-
-export default acTagSpec;
-```
-
-### AutoCore.ts
-
-Once the tags are created, we create a simple TypeScript file to make and provide the hooks throughout the application. By producing typed hooks, Intellisense is able to provide support for tag names and value types.
-
-Create AutoCore.ts in the same directory as App.tsx and AutoCoreTags.ts. The template below should work for any project. 
-
-```ts
-/**
- * @module src/AutoCore
- * @preferred
- *
- * Strongly-typed hooks for AutoCore tags.
- * Could be automatically generated by autocore-react plugin.
- *
- * This module binds your app’s tag spec (from `tags.json` or `tags-spec.ts`) to the
- * global `AutoCoreTagContext`, producing **typed hooks** that provide perfect
- * IntelliSense for tag names and value types.
- *
- * @remarks
- * - Pair this with the runtime provider in your app root:
- *   `AutoCoreTagProvider` wraps `<App/>` and receives the same `spec`.
- * - These hooks expose:
- *   - `useAutoCoreTag(tagName)` → `{ value, write, tap, isLoading, ... }`
- *   - `useAutoCoreTags(tagNames[])` → `{ values, set, isLoading }`
- *   - `useAutoCoreSelect(selector)` → `{ selected, isLoading }`
- * - Keep `tags.json` (or `tags.ts`) as the single source of truth. If using JSON,
- *   validate and narrow it before export so `valueType` is the literal union
- *   `"boolean" | "number" | "string" | "json"`.
- *
- * @example
- * ```ts
- * // src/AutoCore.ts
- * import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
- * import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
- * import { spec } from "./tags-spec"; // wraps ./tags.json and exports a narrowed, validated spec
- *
- * export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, spec);
- * ```
- *
- * @example
- * ```tsx
- * // App.tsx (runtime provider)
- * import rawSpec from "./tags.json" assert { type: "json" };
- * import { AutoCoreTagProvider } from "@adcops/autocore-react/core/AutoCoreTagContext";
- *
- * <EventEmitterProvider>
- *   <AutoCoreTagProvider tags={rawSpec} eagerRead>
- *     <App/>
- *   </AutoCoreTagProvider>
- * </EventEmitterProvider>
- * ```
- *
- * @example
- * ```tsx
- * // Any component
- * import { AutoCoreHooks } from "./AutoCore";
- *
- * const { value: solForward, tap } = AutoCoreHooks.useAutoCoreTag("gio.solForward");
- * const { value: preset, write }   = AutoCoreHooks.useAutoCoreTag("gm.ton.tPreset");
- *
- * const { values } = AutoCoreHooks.useAutoCoreTags(["isDoorClosed", "isControlPowerOk"]);
- *
- * const { selected: ready } = AutoCoreHooks.useAutoCoreSelect(v =>
- *   !!v["isDoorClosed"] && !!v["isControlPowerOk"]
- * );
- * ```
- *
- * @see {@link @adcops/autocore-react/core/AutoCoreTagContext.AutoCoreTagProvider | AutoCoreTagProvider}
- * @see {@link @adcops/autocore-react/hooks/useAutoCoreTag.makeAutoCoreTagHooks | makeAutoCoreTagHooks}
- */
-
-import {acTagSpec} from "./AutoCoreTags";
-import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
-import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
-
-export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, acTagSpec);
-```
-
-
-# Providing Context to the App
-
-With our autocore tags and hooks defined, we now wrap our app in the provided context. Make sure to wrap the application in both the EventEmitterProvider and AutoCoreTagProvider. The example shown also uses primereact.
-
-
-```ts
-import { PrimeReactProvider} from 'primereact/api';
-import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext.js";
-import {AutoCoreTagProvider} from "@adcops/autocore-react/core/AutoCoreTagContext";
-import {acTagSpec} from "./AutoCoreTags";
-
-
-// 3. Developer panel
-export const AutoCorePanel = makeAutoCoreDevPanel(AutoCore.Context, spec);
-```
-
-
-# Providing Context to Your App
-
-Wrap your application with the provider:
-
-```tsx
-function App() {
-    return(
-        <EventEmitterProvider>
-            <PrimeReactProvider>
-                <AutoCoreTagProvider tags={acTagSpec} eagerRead>
-                    <div className="app-wrapper">
-
-                        <main className="main-wrapper">
-
-                            <section className="content-wrapper">
-                                <ContentView />
-                            </section>
-
-                        </main>
-
-                        <footer className="footer-wrapper">
-                            <FooterView />
-                        </footer>
-
-                    </div>
-                </AutoCoreTagProvider>
-            </PrimeReactProvider>
-        </EventEmitterProvider>     
-    )       
-}
-```
-
-- `eagerRead` (default: true) triggers initial reads so values are populated immediately.
-
-# Using the Hooks
-
-1. useAutoCoreTag(tagName)
-
-Access a single tag. Provides:
-- `value` – current value.
-- `setValue` / write – optimistic setter (updates context + backend).
-- `writeRaw` – direct backend write, no optimistic update.
-- `tap` – momentary true → false action (for booleans).
-- `isLoading` – whether the initial read is pending.
-
-
-2. useAutoCoreTags([tagNames])
-
-Access multiple tags at once. Provides:
-
-- `values` – object with each tag’s current value.
-- `set(tagName, value)` – update any tag in the set.
-- `isLoading` – whether the initial read is pending.
-
-3. useAutoCoreSelect(selector)
-
-Derive a computed value from the full tag state.
-
-```tsx
-const { selected: ready } = AutoCoreHooks.useAutoCoreSelect(v =>
-  !!v["gio.solForward"] && (v["gm.ton.tPreset"] ?? 0) > 0
-);
-
-return <Button disabled={!ready}>Start</Button>;
-```
-- `ready` is recomputed any time gio.solForward or gm.ton.tPreset changes.
-- Great for business logic conditions.
-
-
-# Automatic Scaling
-
-AutoCoreTagContext supports automatic unit conversion through named scales with server synchronization. Scale factors are automatically kept in sync with autocore-server values, enabling user-configurable units that persist across sessions.
-
-### How Scaling Works
-
-- Incoming values: Server values are multiplied by the scale factor before being stored
-- Outgoing values: Display values are divided by the scale factor before being sent to server
-- Components see scaled values: All hook operations work with display-friendly values
-- Automatic sync: Scale factors with serverTag properties are automatically synchronized with their server values.
-- Real-time updates: Scale changes take effect immediately across the application.
-- Consistent display: All components automatically show the same units.
-- Dual subscriptions: The system maintains separate subscriptions for data tags and scale tags.
-- No manual scaling needed: Eliminates the need for `useScaledValue` hooks
-    - Prevents value flicker. Values are scaled before being displayed.
-    - Type-safe. Scale names are validated at compile time.
-
-
-Server-Driven Scales are preferred. 
-- Scale factors can come from autocore-server tags for user-configurable units. 
-- The autocore-server GNV domain will store changes in non-volatile memory.
-- Automatic synchronization: Multiple clients stay in sync
-
-
-## Defining Server-Driven Scales
-
-Create AutoCoreScales.ts with server tag references:
-
-```tsx
-import { ScaleConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
-
-export const acScales = {
-  position: { 
-    name: "position", 
-    scale: 1.0, 
-    label: "mm",
-    serverTag: { domain: "MEMORYSTORE", symbolName: "position_scalar" }
-  },
-  load: { 
-    name: "load", 
-    scale: 1.0, 
-    label: "N",
-    serverTag: { domain: "MEMORYSTORE", symbolName: "load_scalar" }
-  },
-  temperature: { 
-    name: "temperature", 
-    scale: 1.0, 
-    label: "°C"
-    // No serverTag - static scale only
-  }
-} as const satisfies Record<string, ScaleConfig>;
-```
-
-Then reference scales in the tag definitions:
-```tsx
-// In AutoCoreTags.ts - add scale property to numeric tags
-{ "tagName": "pressPosition", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPosition", "valueType": "number", "scale": "position" },
-{ "tagName": "pressLoad", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressLoad", "valueType": "number", "scale": "load" }
-```
-
-
-## Provider Configuration
-
-Pass scales to the provider:
-
-```tsx
-import { acScales } from "./AutoCoreScales";
-
-<AutoCoreTagProvider tags={acTagSpec} scales={acScales} eagerRead>
-  <App/>
-</AutoCoreTagProvider>
-```
-
-
-## Updating Scale Factors
-
-Use the updateScale function to change units at runtime.
-
-`updateScale(scaleName, newScale, newLabel)`
-
-Always provide both scale factor and label when calling `updateScale`.
-
-
-Example:
-```tsx
-import { AutoCoreHooks } from "./AutoCore";
-
-const UnitControls: React.FC = () => {
-  const { updateScale, getScale } = AutoCoreHooks.useScales();
-
-  const switchToMetric = async () => {
-    await updateScale("position", 1.0, "mm");
-    await updateScale("load", 1.0, "N");
-  };
-
-  const switchToImperial = async () => {
-    await updateScale("position", 1/25.4, "in");
-    await updateScale("load", 0.224809, "lbs");
-  };
-
-  return (
-    <div>
-      <button onClick={switchToMetric}>Metric Units</button>
-      <button onClick={switchToImperial}>Imperial Units</button>
-    </div>
-  );
-};
-```
-
-### Backward Compatibility
-The system handles legacy installations where only numeric scale factors were stored. When legacy numeric data is received from the server, the label is set to "---" to indicate that proper units should be configured.
-
-```tsx
-const positionScale = getScale("position");
-if (positionScale?.label === "---") {
-  // Legacy data detected - prompt user to set proper units
-  return <div>Please configure display units in settings</div>;
-}
-```
-
-## Server Data Format
-Scale data is stored on the server as JSON objects containing both scale factor and display label.
-
-```json
-{
-  "scale": 1.0,
-  "label": "mm"
-}
-```
-
-# Passing Tag Hooks as Component Props
-When building reusable components that work with AutoCore tags, you can pass entire tag hook results as props. This provides the component with both the current value and the ability to write/tap the tag.
-
-Use ReturnType<typeof AutoCoreHooks.useAutoCoreTag> to properly type tag hook props.
-
-```tsx
-interface LoadChannelSettingsProps {
-  capacitySetTag: ReturnType<typeof AutoCoreHooks.useAutoCoreTag>;
-  enabledTag: ReturnType<typeof AutoCoreHooks.useAutoCoreTag>;
-}
-
-const LoadChannelSettings: React.FC<LoadChannelSettingsProps> = ({ 
-  capacitySetTag, 
-  enabledTag 
-}) => {
-  const { value: capacity, write: setCapacity } = capacitySetTag;
-  const { value: enabled, tap: toggleEnabled } = enabledTag;
-
-  return (
-    <div>
-      <input 
-        type="number" 
-        value={capacity ?? 0} 
-        onChange={e => setCapacity(Number(e.target.value))} 
-      />
-      <button onClick={toggleEnabled}>
-        {enabled ? "Disable" : "Enable"}
-      </button>
-    </div>
-  );
-};
-```
-
-### Usage
-
-Pass the complete hook result to the component.
-
-```tsx
-<LoadChannelSettings 
-  capacitySetTag={AutoCoreHooks.useAutoCoreTag("loadCellCapacitySet")}
-  enabledTag={AutoCoreHooks.useAutoCoreTag("loadChannelEnabled")}
-/>
-```
-
-# DevPanel
-For debugging, include the Dev Panel in your app:
-
-```tsx
-<AutoCorePanel className="fixed bottom-4 right-4 bg-black/60 text-white" />
-```
-
-It shows:
-- Each tag’s name, type, current value.
-- Editable input fields for live writes/taps.
-- Loading/live status indicator.
-
-# Best Practices
-
-- Always define your tags in one spec to keep types consistent across your app.
-- Prefer write (optimistic) for user-driven updates; use writeRaw only if you need backend confirmation before updating UI.
-- Use tap only for boolean momentary actions (reset, trigger, etc.).
-- Use useAutoCoreSelect to express high-level conditions (isSafeToStart, readyToCycle) instead of scattering logic through components.
-- Keep the Dev Panel available in development to quickly test and validate your tag interactions.
-
+# AutoCoreTagContext Manual
+
+This manual explains how to configure, provide, and consume the **AutoCoreTagContext** system.  
+The goal is to create a **typed, global context** of tags (values from `autocore-server`), so your React components can read and update them easily.
+
+---
+
+## Overview
+
+The AutoCoreTagContext is built around three parts:
+
+1. **Context** – created with `makeAutoCoreTagContext` to hold live tag values.  
+2. **Hooks** – created with `makeAutoCoreTagHooks` to read, write, tap, and derive values.  
+3. **Dev Panel** – created with `makeAutoCoreDevPanel` to inspect and manually interact with tags during development.
+
+Tags are defined in a `spec` object: an array of `TagConfig` entries that tell the system what to subscribe to.
+
+---
+
+## Summary
+
+- Define tags once in a spec.
+- Create context, hooks, and optionally a Dev Panel.
+- Provide the context at the root of your app.
+- Consume via:
+    - useAutoCoreTag → single value + actions.
+    - useAutoCoreTags → bulk values.
+    - useAutoCoreSelect → computed state.
+
+This makes your React UI a strongly-typed, declarative layer over the live tag system from autocore-server.
+
+
+## Defining Your Tags and AutoCoreHooks
+
+In this initial step, we make two files:
+1. AutoCoreTags.ts
+2. AutoCore.ts
+
+Note that ADC is working to create a VS Code extension for help auto-generating these files.
+
+### AutoCoreTags.ts
+
+To maintain type safety, tags are defined and exported from a TypeScript file. Tags are defined as an array of TagConfig objects.
+
+Each tag has:
+- `tagName` – your local name for the tag.
+- `domain` – the domain for the symbol (e.g., `"ADS"`, `"MEMORYSTORE"`).
+- `symbolName` – the backend symbol name.
+- `valueType` – `"boolean"`, `"number"`, `"string"`, or `"json"`.
+- `initialValue` (optional) – value before first update.
+- `options` (optional) – advanced subscription options.
+
+By convention, the TypeScript file is located in the same directory as App.tsx and named AutoCoreTags.ts. The exported object is named acTagSpec.
+
+Example:
+
+```ts
+import type { TagConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+
+export const acTagSpec = [
+  { "tagName": "isControlPowerOk", "domain": "ADS", "symbolName": "GIO.xbControlPowerOk", "valueType": "boolean" },
+  { "tagName": "positionScalar",   "domain": "MEMORYSTORE", "symbolName": "position_scalar", "valueType": "number",  "initialValue": 1.0 },
+  { "tagName": "isAutoCycleRunning",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAutoCycleRunning", "valueType": "boolean" },
+  { "tagName": "isAutoCycleRunning",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAutoCycleRunning", "valueType": "boolean" },
+  { "tagName": "shuttlePosition",   "domain": "ADS", "symbolName": "MAIN.ctx.gio.axisShuttle.fPosition", "valueType": "number" },
+  { "tagName": "pressLoad",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressLoad", "valueType": "number" },
+  { "tagName": "pressPosition",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPosition", "valueType": "number" },
+  { "tagName": "pressPeakLoad",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPeakLoad", "valueType": "number" },
+  { "tagName": "isReadyForCycle",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bReadyForCycle", "valueType": "boolean" },  
+  { "tagName": "reqStartAuto",   "domain": "ADS", "symbolName": "MAIN.ctx.gsig.bSigStartAuto", "valueType": "boolean" },  
+  { "tagName": "useSecondaryLoadChannel",   "domain": "ADS", "symbolName": "MAIN.ctx.gnv.bEnableSecondaryLoadInput", "valueType": "boolean" },  
+  { "tagName": "isLoadCellOverrange",   "domain": "ADS", "symbolName": "MAIN.ctx.gio.xstLoadInputStatus.IsOverrange", "valueType": "boolean" },  
+  { "tagName": "isLoadCellUnderrange",   "domain": "ADS", "symbolName": "MAIN.ctx.gio.xstLoadInputStatus.IsUnderrange", "valueType": "boolean" },  
+  { "tagName": "isMotorsOn",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAllMotorsOn", "valueType": "boolean" },  
+  { "tagName": "isAxisErrorPresent",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAxisErrorPresent", "valueType": "boolean" },  
+  { "tagName": "isAllAxesHomed",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAllAxesHomed", "valueType": "boolean" },  
+  { "tagName": "isReadyForOperation",   "domain": "ADS", "symbolName": "MAIN.ctx.gm.bReadyForOperation", "valueType": "boolean" }
+] as const satisfies readonly TagConfig[];
+
+export default acTagSpec;
+```
+
+### AutoCore.ts
+
+Once the tags are created, we create a simple TypeScript file to make and provide the hooks throughout the application. By producing typed hooks, Intellisense is able to provide support for tag names and value types.
+
+Create AutoCore.ts in the same directory as App.tsx and AutoCoreTags.ts. The template below should work for any project. 
+
+```ts
+/**
+ * @module src/AutoCore
+ * @preferred
+ *
+ * Strongly-typed hooks for AutoCore tags.
+ * Could be automatically generated by autocore-react plugin.
+ *
+ * This module binds your app’s tag spec (from `tags.json` or `tags-spec.ts`) to the
+ * global `AutoCoreTagContext`, producing **typed hooks** that provide perfect
+ * IntelliSense for tag names and value types.
+ *
+ * @remarks
+ * - Pair this with the runtime provider in your app root:
+ *   `AutoCoreTagProvider` wraps `<App/>` and receives the same `spec`.
+ * - These hooks expose:
+ *   - `useAutoCoreTag(tagName)` → `{ value, write, tap, isLoading, ... }`
+ *   - `useAutoCoreTags(tagNames[])` → `{ values, set, isLoading }`
+ *   - `useAutoCoreSelect(selector)` → `{ selected, isLoading }`
+ * - Keep `tags.json` (or `tags.ts`) as the single source of truth. If using JSON,
+ *   validate and narrow it before export so `valueType` is the literal union
+ *   `"boolean" | "number" | "string" | "json"`.
+ *
+ * @example
+ * ```ts
+ * // src/AutoCore.ts
+ * import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
+ * import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
+ * import { spec } from "./tags-spec"; // wraps ./tags.json and exports a narrowed, validated spec
+ *
+ * export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, spec);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // App.tsx (runtime provider)
+ * import rawSpec from "./tags.json" assert { type: "json" };
+ * import { AutoCoreTagProvider } from "@adcops/autocore-react/core/AutoCoreTagContext";
+ *
+ * <EventEmitterProvider>
+ *   <AutoCoreTagProvider tags={rawSpec} eagerRead>
+ *     <App/>
+ *   </AutoCoreTagProvider>
+ * </EventEmitterProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Any component
+ * import { AutoCoreHooks } from "./AutoCore";
+ *
+ * const { value: solForward, tap } = AutoCoreHooks.useAutoCoreTag("gio.solForward");
+ * const { value: preset, write }   = AutoCoreHooks.useAutoCoreTag("gm.ton.tPreset");
+ *
+ * const { values } = AutoCoreHooks.useAutoCoreTags(["isDoorClosed", "isControlPowerOk"]);
+ *
+ * const { selected: ready } = AutoCoreHooks.useAutoCoreSelect(v =>
+ *   !!v["isDoorClosed"] && !!v["isControlPowerOk"]
+ * );
+ * ```
+ *
+ * @see {@link @adcops/autocore-react/core/AutoCoreTagContext.AutoCoreTagProvider | AutoCoreTagProvider}
+ * @see {@link @adcops/autocore-react/hooks/useAutoCoreTag.makeAutoCoreTagHooks | makeAutoCoreTagHooks}
+ */
+
+import {acTagSpec} from "./AutoCoreTags";
+import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
+import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
+
+export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, acTagSpec);
+```
+
+
+# Providing Context to the App
+
+With our autocore tags and hooks defined, we now wrap our app in the provided context. Make sure to wrap the application in both the EventEmitterProvider and AutoCoreTagProvider. The example shown also uses primereact.
+
+
+```ts
+import { PrimeReactProvider} from 'primereact/api';
+import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext.js";
+import {AutoCoreTagProvider} from "@adcops/autocore-react/core/AutoCoreTagContext";
+import {acTagSpec} from "./AutoCoreTags";
+
+
+// 3. Developer panel
+export const AutoCorePanel = makeAutoCoreDevPanel(AutoCore.Context, spec);
+```
+
+
+# Providing Context to Your App
+
+Wrap your application with the provider:
+
+```tsx
+function App() {
+    return(
+        <EventEmitterProvider>
+            <PrimeReactProvider>
+                <AutoCoreTagProvider tags={acTagSpec} eagerRead>
+                    <div className="app-wrapper">
+
+                        <main className="main-wrapper">
+
+                            <section className="content-wrapper">
+                                <ContentView />
+                            </section>
+
+                        </main>
+
+                        <footer className="footer-wrapper">
+                            <FooterView />
+                        </footer>
+
+                    </div>
+                </AutoCoreTagProvider>
+            </PrimeReactProvider>
+        </EventEmitterProvider>     
+    )       
+}
+```
+
+- `eagerRead` (default: true) triggers initial reads so values are populated immediately.
+
+# Using the Hooks
+
+1. useAutoCoreTag(tagName)
+
+Access a single tag. Provides:
+- `value` – current value.
+- `setValue` / write – optimistic setter (updates context + backend).
+- `writeRaw` – direct backend write, no optimistic update.
+- `tap` – momentary true → false action (for booleans).
+- `isLoading` – whether the initial read is pending.
+
+
+2. useAutoCoreTags([tagNames])
+
+Access multiple tags at once. Provides:
+
+- `values` – object with each tag’s current value.
+- `set(tagName, value)` – update any tag in the set.
+- `isLoading` – whether the initial read is pending.
+
+3. useAutoCoreSelect(selector)
+
+Derive a computed value from the full tag state.
+
+```tsx
+const { selected: ready } = AutoCoreHooks.useAutoCoreSelect(v =>
+  !!v["gio.solForward"] && (v["gm.ton.tPreset"] ?? 0) > 0
+);
+
+return <Button disabled={!ready}>Start</Button>;
+```
+- `ready` is recomputed any time gio.solForward or gm.ton.tPreset changes.
+- Great for business logic conditions.
+
+
+# Automatic Scaling
+
+AutoCoreTagContext supports automatic unit conversion through named scales with server synchronization. Scale factors are automatically kept in sync with autocore-server values, enabling user-configurable units that persist across sessions.
+
+### How Scaling Works
+
+- Incoming values: Server values are multiplied by the scale factor before being stored
+- Outgoing values: Display values are divided by the scale factor before being sent to server
+- Components see scaled values: All hook operations work with display-friendly values
+- Automatic sync: Scale factors with serverTag properties are automatically synchronized with their server values.
+- Real-time updates: Scale changes take effect immediately across the application.
+- Consistent display: All components automatically show the same units.
+- Dual subscriptions: The system maintains separate subscriptions for data tags and scale tags.
+- No manual scaling needed: Eliminates the need for `useScaledValue` hooks
+    - Prevents value flicker. Values are scaled before being displayed.
+    - Type-safe. Scale names are validated at compile time.
+
+
+Server-Driven Scales are preferred. 
+- Scale factors can come from autocore-server tags for user-configurable units. 
+- The autocore-server GNV domain will store changes in non-volatile memory.
+- Automatic synchronization: Multiple clients stay in sync
+
+
+## Defining Server-Driven Scales
+
+Create AutoCoreScales.ts with server tag references:
+
+```tsx
+import { ScaleConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+
+export const acScales = {
+  position: { 
+    name: "position", 
+    scale: 1.0, 
+    label: "mm",
+    serverTag: { domain: "MEMORYSTORE", symbolName: "position_scalar" }
+  },
+  load: { 
+    name: "load", 
+    scale: 1.0, 
+    label: "N",
+    serverTag: { domain: "MEMORYSTORE", symbolName: "load_scalar" }
+  },
+  temperature: { 
+    name: "temperature", 
+    scale: 1.0, 
+    label: "°C"
+    // No serverTag - static scale only
+  }
+} as const satisfies Record<string, ScaleConfig>;
+```
+
+Then reference scales in the tag definitions:
+```tsx
+// In AutoCoreTags.ts - add scale property to numeric tags
+{ "tagName": "pressPosition", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPosition", "valueType": "number", "scale": "position" },
+{ "tagName": "pressLoad", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressLoad", "valueType": "number", "scale": "load" }
+```
+
+
+## Provider Configuration
+
+Pass scales to the provider:
+
+```tsx
+import { acScales } from "./AutoCoreScales";
+
+<AutoCoreTagProvider tags={acTagSpec} scales={acScales} eagerRead>
+  <App/>
+</AutoCoreTagProvider>
+```
+
+
+## Updating Scale Factors
+
+Use the updateScale function to change units at runtime.
+
+`updateScale(scaleName, newScale, newLabel)`
+
+Always provide both scale factor and label when calling `updateScale`.
+
+
+Example:
+```tsx
+import { AutoCoreHooks } from "./AutoCore";
+
+const UnitControls: React.FC = () => {
+  const { updateScale, getScale } = AutoCoreHooks.useScales();
+
+  const switchToMetric = async () => {
+    await updateScale("position", 1.0, "mm");
+    await updateScale("load", 1.0, "N");
+  };
+
+  const switchToImperial = async () => {
+    await updateScale("position", 1/25.4, "in");
+    await updateScale("load", 0.224809, "lbs");
+  };
+
+  return (
+    <div>
+      <button onClick={switchToMetric}>Metric Units</button>
+      <button onClick={switchToImperial}>Imperial Units</button>
+    </div>
+  );
+};
+```
+
+### Backward Compatibility
+The system handles legacy installations where only numeric scale factors were stored. When legacy numeric data is received from the server, the label is set to "---" to indicate that proper units should be configured.
+
+```tsx
+const positionScale = getScale("position");
+if (positionScale?.label === "---") {
+  // Legacy data detected - prompt user to set proper units
+  return <div>Please configure display units in settings</div>;
+}
+```
+
+## Server Data Format
+Scale data is stored on the server as JSON objects containing both scale factor and display label.
+
+```json
+{
+  "scale": 1.0,
+  "label": "mm"
+}
+```
+
+# Passing Tag Hooks as Component Props
+When building reusable components that work with AutoCore tags, you can pass entire tag hook results as props. This provides the component with both the current value and the ability to write/tap the tag.
+
+Use ReturnType<typeof AutoCoreHooks.useAutoCoreTag> to properly type tag hook props.
+
+```tsx
+interface LoadChannelSettingsProps {
+  capacitySetTag: ReturnType<typeof AutoCoreHooks.useAutoCoreTag>;
+  enabledTag: ReturnType<typeof AutoCoreHooks.useAutoCoreTag>;
+}
+
+const LoadChannelSettings: React.FC<LoadChannelSettingsProps> = ({ 
+  capacitySetTag, 
+  enabledTag 
+}) => {
+  const { value: capacity, write: setCapacity } = capacitySetTag;
+  const { value: enabled, tap: toggleEnabled } = enabledTag;
+
+  return (
+    <div>
+      <input 
+        type="number" 
+        value={capacity ?? 0} 
+        onChange={e => setCapacity(Number(e.target.value))} 
+      />
+      <button onClick={toggleEnabled}>
+        {enabled ? "Disable" : "Enable"}
+      </button>
+    </div>
+  );
+};
+```
+
+### Usage
+
+Pass the complete hook result to the component.
+
+```tsx
+<LoadChannelSettings 
+  capacitySetTag={AutoCoreHooks.useAutoCoreTag("loadCellCapacitySet")}
+  enabledTag={AutoCoreHooks.useAutoCoreTag("loadChannelEnabled")}
+/>
+```
+
+# DevPanel
+For debugging, include the Dev Panel in your app:
+
+```tsx
+<AutoCorePanel className="fixed bottom-4 right-4 bg-black/60 text-white" />
+```
+
+It shows:
+- Each tag’s name, type, current value.
+- Editable input fields for live writes/taps.
+- Loading/live status indicator.
+
+# Best Practices
+
+- Always define your tags in one spec to keep types consistent across your app.
+- Prefer write (optimistic) for user-driven updates; use writeRaw only if you need backend confirmation before updating UI.
+- Use tap only for boolean momentary actions (reset, trigger, etc.).
+- Use useAutoCoreSelect to express high-level conditions (isSafeToStart, readyToCycle) instead of scattering logic through components.
+- Keep the Dev Panel available in development to quickly test and validate your tag interactions.
+