@adcops/autocore-react 3.0.40 → 3.3.2

package/dist/hub/HubWebSocket.d.ts

@@ -1,35 +1,52 @@
-/** @file
+/**
+ * @module hub/HubWebSocket
  *
- * ## broadcast messages
- * The result field of CommandMessages used for broadcast must have
- * success set to true, and must contain the field "topic." The topic field, along
- * with the domain field of the CommandMessage will be combined for the topic used
- * by the websocket client.
+ * Implementation of `HubBase` using standard WebSockets.
  *
- * broadcast topic = `${CommandMessage.domain}/${CommandMessage.result["topic"]}
+ * ## Functionality
  *
- * So, to subscribe to a broadcast topic for GM.fReal that is served by the ADS client, the
- * topic will be: "ADS/GM.fReal"
+ * - **Transport**: Connects to `ws://host:port/ws/` (or `wss://`).
+ * - **Request/Response**: Correlates requests to responses using `transaction_id`.
+ * - **Broadcasts**: Handles unsolicited messages (subscriptions) and routes them via `HubBase.publish`.
+ * - **Binary Data**: Handles `FILE_DOWNLOAD` events by decoding Base64 payloads into Blobs.
+ *
+ * ## Protocol
+ *
+ * Messages are JSON-serialized `CommandMessage` objects.
+ * - **Requests**: Client sends `message_type` (Read/Write/etc) + `transaction_id`.
+ * - **Responses**: Server replies with same `transaction_id` + `success`/`data`.
+ * - **Broadcasts**: Server sends `message_type: Broadcast` + `topic` (FQDN) + `data`.
  */
 import { HubBase } from './HubBase';
-import { CommandMessage, CommandMessageResult } from "./CommandMessage";
+import { MessageType, type CommandMessage } from "./CommandMessage";
+/**
+ * WebSocket implementation of the Hub communication layer.
+ */
 export declare class HubWebSocket extends HubBase {
     private socket;
     private requestId;
+    /**
+     * Map of pending Transaction ID -> Promise Resolvers.
+     * Used to match asynchronous WebSocket responses to their original requests.
+     */
     private pendingRequests;
     /**
-     * Constructor. Creates and attempts to make the Websocket connection.
+     * Initializes the WebSocket connection immediately.
      */
     constructor();
     /**
-     * Invoke a command in the remote webserver.
-     * @param domain The domain of the Servelet supplying the functionality.
-     * @param fname The name of the command to execute.
-     * @param payload The arguments of the command.
-     * @returns Promise<CommandMessageResult>
+     * Sends a command to the server via WebSocket.
+     *
+     * Wraps the operation in a Promise that resolves when the server replies
+     * with a matching `transaction_id`.
+     */
+    invoke: (topic: string, messageType: MessageType, payload?: object) => Promise<CommandMessage>;
+    /**
+     * Processes messages that are not responses to a specific request.
+     * Usually these are subscription updates (Broadcasts).
      */
-    invoke: (domain: string, fname: string, payload?: object) => Promise<CommandMessageResult>;
     handleUnsolicitedMessage: (msg: CommandMessage) => void;
     disconnect: () => void;
     protected emit: (eventName: string, payload?: object) => void;
 }
+//# sourceMappingURL=HubWebSocket.d.ts.map

package/dist/hub/HubWebSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HubWebSocket.d.ts","sourceRoot":"","sources":["../../src/hub/HubWebSocket.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA+DpE;;GAEG;AACH,qBAAa,YAAa,SAAQ,OAAO;IACrC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAoC;IAE3D;;OAEG;;IA4FH;;;;;OAKG;IACH,MAAM,GAAI,OAAO,MAAM,EAAE,aAAa,WAAW,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,cAAc,CAAC,CAqB5F;IAED;;;OAGG;IACH,wBAAwB,GAAI,KAAK,cAAc,UAO9C;IAED,UAAU,QAAO,IAAI,CAEpB;IAED,SAAS,CAAC,IAAI,GAAI,WAAW,MAAM,EAAE,UAAU,MAAM,KAAG,IAAI,CAE3D;CACJ"}

package/dist/hub/HubWebSocket.js

@@ -1 +1 @@
-import{HubBase}from"./HubBase";function b64toBlob(e,t="application/octet-stream",s=512){const n=atob(e),o=[];for(let e=0;e<n.length;e+=s){const t=n.slice(e,e+s),r=new Array(t.length);for(let e=0;e<t.length;e++)r[e]=t.charCodeAt(e);const i=new Uint8Array(r);o.push(i)}return new Blob(o,{type:t})}function downloadBlob(e,t){const s=window.URL.createObjectURL(e),n=document.createElement("a");n.href=s,n.download=t,document.body.appendChild(n),n.click(),document.body.removeChild(n),window.URL.revokeObjectURL(s)}export class HubWebSocket extends HubBase{constructor(){super(),Object.defineProperty(this,"socket",{enumerable:!0,configurable:!0,writable:!0,value:void 0}),Object.defineProperty(this,"requestId",{enumerable:!0,configurable:!0,writable:!0,value:0}),Object.defineProperty(this,"pendingRequests",{enumerable:!0,configurable:!0,writable:!0,value:new Map}),Object.defineProperty(this,"invoke",{enumerable:!0,configurable:!0,writable:!0,value:(e,t,s)=>new Promise(((n,o)=>{const r=++this.requestId;this.pendingRequests.set(r,{resolve:n,reject:o});let i={request_id:r,domain:e,fname:t,args:s,result:void 0};this.socket.send(JSON.stringify(i))}))}),Object.defineProperty(this,"handleUnsolicitedMessage",{enumerable:!0,configurable:!0,writable:!0,value:e=>{if("BROADCAST"===e.fname&&e.domain.length>=1&&void 0!==e.result&&null!==e.result&&void 0!==e.result.data&&null!==e.result.data){let t=`${e.domain}/${e.result.data.topic}`;this.publish(t,e.result.data)}}}),Object.defineProperty(this,"disconnect",{enumerable:!0,configurable:!0,writable:!0,value:()=>{this.socket.close()}}),Object.defineProperty(this,"emit",{enumerable:!0,configurable:!0,writable:!0,value:(e,t)=>{this.socket.send(JSON.stringify({eventName:e,payload:t}))}});const e=window.location.hostname;let t;const s=`${"https:"===window.location.protocol?"wss://":"ws://"}${e}${t?":"+t:""}/ws/`;this.socket=new WebSocket(s);let n=this;this.socket.onopen=function(){n.publish("HUB/connected",!0),n.setIsConnected(!0)},this.socket.onmessage=e=>{const t=JSON.parse(e.data);if(t.request_id&&this.pendingRequests.has(t.request_id)){const{resolve:e,reject:s}=this.pendingRequests.get(t.request_id);if("FILE_DOWNLOAD"===t.fname&&void 0!==t.args.file_name&&null!==t.args.file_name&&t.args.file_name.length>0){let n=t.args.file_name.split("/");const o=n[n.length-1];if(t.result&&t.result.success){downloadBlob(b64toBlob(t.result.data),o),t.result.data=o,e(t.result)}else s(new Error(t.result?.error_message))}else t.result?.success?e(t.result):s(new Error(t.result?.error_message));this.pendingRequests.delete(t.request_id)}else this.handleUnsolicitedMessage(t)},this.socket.onerror=e=>{},this.socket.onclose=()=>{n.setIsConnected(!1)}}}
+import{HubBase}from"./HubBase";import{MessageType}from"./CommandMessage";import{getDebugPanel}from"./DebugPanel";function b64toBlob(e,t="application/octet-stream",s=512){const n=atob(e),o=[];for(let e=0;e<n.length;e+=s){const t=n.slice(e,e+s),a=new Array(t.length);for(let e=0;e<t.length;e++)a[e]=t.charCodeAt(e);const i=new Uint8Array(a);o.push(i.buffer)}return new Blob(o,{type:t})}function downloadBlob(e,t){const s=window.URL.createObjectURL(e),n=document.createElement("a");n.href=s,n.download=t,document.body.appendChild(n),n.click(),document.body.removeChild(n),window.URL.revokeObjectURL(s)}export class HubWebSocket extends HubBase{constructor(){super(),Object.defineProperty(this,"socket",{enumerable:!0,configurable:!0,writable:!0,value:void 0}),Object.defineProperty(this,"requestId",{enumerable:!0,configurable:!0,writable:!0,value:0}),Object.defineProperty(this,"pendingRequests",{enumerable:!0,configurable:!0,writable:!0,value:new Map}),Object.defineProperty(this,"invoke",{enumerable:!0,configurable:!0,writable:!0,value:(e,t,s)=>new Promise((n,o)=>{const a=++this.requestId;this.pendingRequests.set(a,{resolve:n,reject:o});const i={transaction_id:a,topic:e,data:s||{},timecode:Date.now(),message_type:t,success:!1,error_message:""};getDebugPanel().messageSent(MessageType[t],e,a),this.socket.send(JSON.stringify(i))})}),Object.defineProperty(this,"handleUnsolicitedMessage",{enumerable:!0,configurable:!0,writable:!0,value:e=>{e.message_type==MessageType.Broadcast&&e.topic.length>1&&this.publish(e.topic,e.data)}}),Object.defineProperty(this,"disconnect",{enumerable:!0,configurable:!0,writable:!0,value:()=>{this.socket.close()}}),Object.defineProperty(this,"emit",{enumerable:!0,configurable:!0,writable:!0,value:(e,t)=>{this.socket.send(JSON.stringify({eventName:e,payload:t}))}}),getDebugPanel().hubCreated();const e=window.location.hostname,t=window.location.port,s=`${"https:"===window.location.protocol?"wss://":"ws://"}${e}${t?":"+t:""}/ws/`;this.socket=new WebSocket(s);let n=this;this.socket.onopen=function(){getDebugPanel().wsOpened(s),n.publish("HUB/connected",!0),n.setIsConnected(!0)},this.socket.onmessage=e=>{const t=JSON.parse(e.data);if(getDebugPanel().messageReceived(MessageType[t.message_type]||String(t.message_type),t.topic,t.transaction_id),t.transaction_id&&this.pendingRequests.has(t.transaction_id)){const{resolve:e,reject:s}=this.pendingRequests.get(t.transaction_id);if("FILE_DOWNLOAD"===t.topic&&void 0!==t.data.file_name&&null!==t.data.file_name&&t.data.file_name.length>0){let n=t.data.file_name.split("/");const o=n[n.length-1];if(t.success){downloadBlob(b64toBlob(t.data),o),t.data=o,e(t)}else s(new Error(t.error_message))}else t.success?e(t):s(new Error(t.error_message));this.pendingRequests.delete(t.transaction_id)}else this.handleUnsolicitedMessage(t)},this.socket.onerror=e=>{getDebugPanel().wsError(String(e))},this.socket.onclose=e=>{n.setIsConnected(!1),getDebugPanel().wsClosed(e.code,e.reason||"No reason")}}}

package/dist/hub/debug.d.ts

@@ -0,0 +1,23 @@
+export interface DebugLogEntry {
+    timestamp: number;
+    source: string;
+    level: "info" | "warn" | "error" | "send" | "recv";
+    message: string;
+    data?: unknown;
+}
+export declare const debug: {
+    /** Log an info message */
+    info(source: string, message: string, data?: unknown): void;
+    /** Log a warning message */
+    warn(source: string, message: string, data?: unknown): void;
+    /** Log an error message */
+    error(source: string, message: string, data?: unknown): void;
+    /** Log an outgoing message (to server) */
+    send(source: string, message: string, data?: unknown): void;
+    /** Log an incoming message (from server) */
+    recv(source: string, message: string, data?: unknown): void;
+    /** Check if debug is enabled */
+    isEnabled(): boolean;
+};
+export default debug;
+//# sourceMappingURL=debug.d.ts.map

package/dist/hub/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/hub/debug.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAwFD,eAAO,MAAM,KAAK;IAChB,0BAA0B;iBACb,MAAM,WAAW,MAAM,SAAS,OAAO,GAAG,IAAI;IAI3D,4BAA4B;iBACf,MAAM,WAAW,MAAM,SAAS,OAAO,GAAG,IAAI;IAI3D,2BAA2B;kBACb,MAAM,WAAW,MAAM,SAAS,OAAO,GAAG,IAAI;IAI5D,0CAA0C;iBAC7B,MAAM,WAAW,MAAM,SAAS,OAAO,GAAG,IAAI;IAI3D,4CAA4C;iBAC/B,MAAM,WAAW,MAAM,SAAS,OAAO,GAAG,IAAI;IAI3D,gCAAgC;iBACnB,OAAO;CAGrB,CAAC;AAqEF,eAAe,KAAK,CAAC"}

package/dist/hub/debug.js

@@ -0,0 +1 @@
+const state={enabled:!0,logs:[],maxLogs:1e3};function formatTime(e){const t=new Date(e);return t.toTimeString().slice(0,8)+"."+String(t.getMilliseconds()).padStart(3,"0")}function formatEntry(e){return`[${formatTime(e.timestamp)}] [${e.source}] ${e.message}`}function addLog(e,t,o,s){const r={timestamp:Date.now(),source:e,level:t,message:o,data:s};if(state.logs.push(r),state.logs.length>state.maxLogs&&state.logs.shift(),state.enabled){formatEntry(r),getLogStyle(t);t}}function getLogStyle(e){switch(e){case"error":return"color: #ff4444; font-weight: bold;";case"warn":return"color: #ffaa00;";case"send":return"color: #44ff44;";case"recv":return"color: #4444ff;";default:return"color: #888888;"}}export const debug={info(e,t,o){addLog(e,"info",t,o)},warn(e,t,o){addLog(e,"warn",t,o)},error(e,t,o){addLog(e,"error",t,o)},send(e,t,o){addLog(e,"send",t,o)},recv(e,t,o){addLog(e,"recv",t,o)},isEnabled:()=>state.enabled};const consoleAPI={enable(){state.enabled=!0},disable(){state.enabled=!1},get logs(){return[...state.logs]},clear(){state.logs=[]},dump(){for(const e of state.logs){formatEntry(e);e.level}},filterBySource:e=>state.logs.filter(t=>t.source.includes(e)),filterByLevel:e=>state.logs.filter(t=>t.level===e),getMessages:()=>state.logs.filter(e=>"send"===e.level||"recv"===e.level)};"undefined"!=typeof window&&(window.__AUTOCORE_DEBUG__=consoleAPI);export default debug;

package/dist/hub/index.d.ts

@@ -2,14 +2,30 @@ import { HubBase as Hub } from './HubBase';
 import { HubTauri } from './HubTauri';
 import { HubWebSocket } from "./HubWebSocket";
 import { HubSimulate } from "./HubSimulate";
-import { CommandMessage, CommandMessageResult } from './CommandMessage';
 /**
- * Creates a connection to the backend.
- * @returns Hub
+ * Creates or returns the singleton Hub connection to the backend.
+ *
+ * The hub type is determined automatically:
+ * - If running in Tauri: HubTauri (direct Rust IPC)
+ * - Otherwise: HubWebSocket (WebSocket to autocore-server)
+ *
+ * @returns Hub The singleton hub instance
  */
 export declare function createHub(): Hub;
+/**
+ * Returns the current hub instance, or null if not yet created.
+ * Useful for checking if a hub exists without creating one.
+ */
+export declare function getHubInstance(): Hub | null;
+/**
+ * Resets the singleton hub instance.
+ * This should only be used for testing or when intentionally reconnecting.
+ */
+export declare function resetHub(): void;
 export { HubBase as Hub } from './HubBase';
 export { HubTauri };
 export { HubWebSocket };
 export { HubSimulate };
-export type { CommandMessage, CommandMessageResult };
+export type { CommandMessage } from './CommandMessage';
+export { MessageType } from './CommandMessage';
+//# sourceMappingURL=index.d.ts.map

package/dist/hub/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hub/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAW5C;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,GAAG,CAiB/B;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,GAAG,GAAG,IAAI,CAE3C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,IAAI,CAE/B;AAGD,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,CAAC;AAGvB,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/hub/index.js

@@ -1 +1 @@
-import{HubTauri}from"./HubTauri";import{HubWebSocket}from"./HubWebSocket";import{HubSimulate}from"./HubSimulate";let hubInstance=null;export function createHub(){return hubInstance||(hubInstance=void 0!==window.__TAURI__&&null!==window.__TAURI__?new HubTauri:new HubWebSocket),hubInstance}export{HubBase as Hub}from"./HubBase";export{HubTauri};export{HubWebSocket};export{HubSimulate};
+import{HubBase as Hub}from"./HubBase";import{HubTauri}from"./HubTauri";import{HubWebSocket}from"./HubWebSocket";import{HubSimulate}from"./HubSimulate";import{getDebugPanel}from"./DebugPanel";let hubInstance=null;export function createHub(){const e=getDebugPanel();return e.log("info","createHub",`called (hasInstance: ${!!hubInstance})`),hubInstance?e.log("info","createHub","Returning existing hub instance"):"undefined"!=typeof window&&void 0!==window.__TAURI__&&null!==window.__TAURI__?(e.log("info","createHub","Creating HubTauri instance"),hubInstance=new HubTauri):(e.log("info","createHub","Creating HubWebSocket instance"),hubInstance=new HubWebSocket),hubInstance}export function getHubInstance(){return hubInstance}export function resetHub(){hubInstance=null}export{HubBase as Hub}from"./HubBase";export{HubTauri};export{HubWebSocket};export{HubSimulate};export{MessageType}from"./CommandMessage";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@adcops/autocore-react",
-    "version": "3.0.40",
+    "version": "3.3.2",
     "description": "A React component library for industrial user interfaces.",
     "private": false,
     "type": "module",
@@ -14,6 +14,7 @@
         "dev": "npm run clean && tsc && node ./tools/copy-distribution-files.cjs",
         "prestart": "tsc",
         "publish-package": "npm run build && npm version patch && npm publish",
+        "prepublishOnly": "npm run build",
         "release:patch": "npm version patch && npm publish",
         "release:minor": "npm version minor && npm publish",
         "release:major": "npm version major && npm publish",
@@ -26,8 +27,10 @@
     "keywords": [
         "react",
         "autocore",
-        "component",
-        "dispatcher"
+        "component-library",
+        "industrial-ui",
+        "typescript",
+        "primereact"
     ],
     "author": "Automated Design Corp.",
     "license": "ISC",
@@ -36,10 +39,10 @@
     },
     "homepage": "https://automateddesign.com",
     "peerDependencies": {
-        "@types/react": ">=18.0.0",
-        "react": ">=18.2.0",
-        "react-dom": ">=18.2.0",
-        "primereact": ">=10.6.3"
+        "@types/react": "^18",
+        "primereact": ">=10.6.3",
+        "react": "^18",
+        "react-dom": "^18"
     },
     "peerDependenciesMeta": {
         "@types/react": {
@@ -47,49 +50,51 @@
         }
     },
     "dependencies": {
-        "@monaco-editor/react": "^4.6.0",
-        "@tauri-apps/api": "^1.5.3",
-        "@types/react-dom": "^18.2.18",
-        "@types/react-transition-group": "^4.4.1",
-        "clsx": "^2.1.0",
+        "@monaco-editor/react": "^4.7.0",
+        "@tauri-apps/api": "^2.9.1",
+        "clsx": "^2.1.1",
         "numerable": "^0.3.15",
-        "react-blockly": "^8.1.1",
-        "react-simple-keyboard": "^3.7.65",
-        "react-transition-group": "^4.4.1",
-        "sass": "^1.89.2",
-        "socket.io-client": "^4.7.2",
+        "react-blockly": "^8.1.2",
+        "react-simple-keyboard": "^3.8.120",
+        "react-transition-group": "^4.4.5",
+        "sass": "^1.92.1",
+        "socket.io-client": "^4.8.1",
         "use-fit-text": "^2.4.0"
     },
     "sideEffects": [
-        "**/*.css"
+        "**/*.css",
+        "**/*.scss"
     ],
     "engines": {
         "node": ">=20.0.0"
     },
     "devDependencies": {
         "@svgr/cli": "^8.1.0",
-        "rimraf": "^5.0.5",
-        "terser": "^5.26.0",
-        "typedoc": "^0.25.11",
-        "typescript": "^5.0.2",
-        "primereact": ">=10.6.3"
+        "@types/react": "^18.2.15",
+        "@types/react-dom": "^18.2.7",
+        "@types/react-transition-group": "^4.4.12",
+        "primereact": "^10.9.7",
+        "rimraf": "^6.0.1",
+        "terser": "^5.44.0",
+        "typedoc": "^0.28.12",
+        "typescript": "^5.9.2"
     },
     "exports": {
         "./core/*": {
             "import": "./dist/core/*",
-            "types": "./dist/core/*.d.js"
+            "types": "./dist/core/*.d.ts"
         },
         "./components/*": {
             "import": "./dist/components/*",
-            "types": "./dist/components/*.d.js"
+            "types": "./dist/components/*.d.ts"
         },
         "./hooks/*": {
             "import": "./dist/hooks/*",
-            "types": "./dist/hooks/*.d.js"
+            "types": "./dist/hooks/*.d.ts"
         },
         "./themes/*": {
             "import": "./dist/themes/*",
-            "types": "./dist/themes/*.d.js"
+            "types": "./dist/themes/*.d.ts"
         }
     }
 }

package/readme.md

@@ -15,26 +15,202 @@ PrimeReact to supply almost all but the most obscure controls, and adds a wrappe
 signals from the backend to the common controls. This allows autocore-react to focus on the additional
 features needed for machine-control user interfaces, while PrimeReact excels at development of components.
 
-## Hub
+## Installation
 
-Whether running in a browser or within a Tauri application, the user interface of a web app needs to 
-communicate with a backed. The Hub abstracts this by defining a common base class, then automatically
-selecting the proper pipeline based upon the environment. If the Tauri environment is detected, HubTauri 
-is loaded. For a browser instance, a socket.io connection is used. When running in a development environment,
-a simulated backend that simply echoes responses is used.
+Install from NPM.
 
-When writing the main application or developing components, you only need to focus on the Hub class. Because the
-backend is selected automatically, the web application does not need to be modified for each individual environment.
+```
+npm install --save @adcops/autocore-react
+```
 
+## Quick Start
 
-## Installation
+### 1. Define Your Tags
 
-Install from NPM.
+Create `AutoCoreTags.ts` to define all the tags your application will use:
 
+```typescript
+import type { TagConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+
+export const acTagSpec = [
+  { "tagName": "isControlPowerOk", "domain": "ADS", "symbolName": "GIO.xbControlPowerOk", "valueType": "boolean" },
+  { "tagName": "motorSpeed", "domain": "ADS", "symbolName": "MAIN.ctx.motor.fSpeed", "valueType": "number" },
+  { "tagName": "isAutoCycleRunning", "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAutoCycleRunning", "valueType": "boolean" },
+  { "tagName": "positionScalar", "domain": "MEMORYSTORE", "symbolName": "position_scalar", "valueType": "number", "initialValue": 1.0 }
+] as const satisfies readonly TagConfig[];
+
+export default acTagSpec;
 ```
-npm install --save @adcops/autocore-react
+
+### 2. Create Typed Hooks
+
+Create `AutoCore.ts` to generate strongly-typed hooks:
+
+```typescript
+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);
+```
+
+
+#### Define Scales (Optional)
+For applications that need unit conversion, create `AutoCoreScales.ts` with server-driven scaling:
+
+
+```tsx
+import { ScaleConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+
+export const acScales = {
+  position: { 
+    name: "position", 
+    scale: 1.0, 
+    label: "mm",
+    serverTag: { domain: "GNV", symbolName: "position_scalar" }
+  },
+  load: { 
+    name: "load", 
+    scale: 1.0, 
+    label: "N",
+    serverTag: { domain: "GNV", symbolName: "load_scalar" }
+  }
+} as const satisfies Record<string, ScaleConfig>;
+```
+
+Note: Server tags now store both scale factor and label as a JSON object: `{ scale: 1.0, label: "mm" }`. Legacy numeric-only values are supported for backward compatibility.
+
+Next, reference scales in your 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" }
+```
+
+### 3. Wrap Your App
+
+Update your `App.tsx` to provide the contexts:
+
+```typescript
+import React from 'react';
+import { PrimeReactProvider } from 'primereact/api';
+import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext";
+import { AutoCoreTagProvider } from "@adcops/autocore-react/core/AutoCoreTagContext";
+import { acTagSpec } from "./AutoCoreTags";
+import { acScales } from "./AutoCoreScales";
+
+function App() {
+  return (
+    <EventEmitterProvider>
+      <PrimeReactProvider>
+        <AutoCoreTagProvider tags={acTagSpec} scales={acScales} eagerRead>
+          <div className="app-wrapper">
+            <main className="main-wrapper">
+              <YourMainContent />
+            </main>
+          </div>
+        </AutoCoreTagProvider>
+      </PrimeReactProvider>
+    </EventEmitterProvider>
+  );
+}
+
+export default App;
 ```
 
+### 4. Use Tags in Components
+
+Import your typed hooks and use them in any component:
+
+```typescript
+import React from 'react';
+import { Button } from 'primereact/button';
+import { AutoCoreHooks } from './AutoCore';
+
+export const ControlPanel: React.FC = () => {
+  // Single tag access
+  const { value: powerOk, write: setPowerOk } = AutoCoreHooks.useAutoCoreTag("isControlPowerOk");
+  const { value: motorSpeed, write: setMotorSpeed } = AutoCoreHooks.useAutoCoreTag("motorSpeed");
+  
+  // Multiple tag access
+  const { values } = AutoCoreHooks.useAutoCoreTags(["isControlPowerOk", "isAutoCycleRunning"]);
+  
+  // Computed state
+  const { selected: canStart } = AutoCoreHooks.useAutoCoreSelect(v =>
+    !!v["isControlPowerOk"] && !v["isAutoCycleRunning"]
+  );
+
+  return (
+    <div>
+      <div>Power OK: {powerOk ? "Yes" : "No"}</div>
+      <div>Motor Speed: {motorSpeed} RPM</div>
+      
+      <Button 
+        label="Start Motor" 
+        disabled={!canStart}
+        onClick={() => setMotorSpeed(1000)}
+      />
+      
+      <Button 
+        label="Emergency Stop" 
+        severity="danger"
+        onClick={() => setPowerOk(false)}
+      />
+    </div>
+  );
+};
+```
+
+### 5. Development Panel (Optional)
+
+Add a debugging panel for development:
+
+```typescript
+import { AutoCoreDevPanel } from "@adcops/autocore-react/components/AutoCoreDevPanel";
+import { acTagSpec } from "./AutoCoreTags";
+
+// In your App component:
+{process.env.NODE_ENV === 'development' && (
+  <AutoCoreDevPanel 
+    tags={acTagSpec} 
+    className="fixed bottom-4 right-4 bg-white shadow-lg" 
+  />
+)}
+```
+
+## AutoCoreTagContext Features
+
+- **Strongly-typed**: Full TypeScript support with IntelliSense for tag names and value types
+- **Global state**: Share tag values across your entire application
+- **Real-time updates**: Automatic subscription to server data changes
+- **No optimistic updates**: UI always reflects true server state
+- **Error handling**: Proper async/await patterns with error feedback
+- **Development tools**: Built-in debugging panel for testing
+
+## Architecture
+
+### Hub (Internal)
+
+The Hub is an internal abstraction that handles communication with the backend. It automatically
+selects the proper pipeline based on the environment: HubTauri for Tauri applications, socket.io 
+for browser instances, and a simulated backend for development environments.
+
+**Important**: Applications should not interact with the Hub directly. Instead, use the higher-level 
+abstractions described below.
+
+### EventEmitterContext
+
+The EventEmitterContext provides a global event system for component communication and backend 
+interaction through `invoke()`, `subscribe()`, and `dispatch()` methods. This is automatically 
+available when you wrap your app with `<EventEmitterProvider>`.
+
+### AutoCoreTagContext (Recommended)
+
+For most backend data interactions, use the AutoCoreTagContext system with strongly-typed hooks.
+This provides the cleanest, most maintainable approach for managing server state in your components.
+See the Quick Start section above for setup and usage.
+
 ## Development
 
 We typically have an external Tauri project designed to import and test the autocore-react library. We find that
@@ -56,14 +232,12 @@ npm publish --tag staging --access=public
 
 Note that we have to specify that the access is public because the tag makes this "scoped," which are private by default.
 
-
 In the test project, simply install the 'staging' tag version.
 
 ```
 npm install @adcops/autocore-react@staging
 ```
 
-
 ### npm link
 
 In the root of the autocore-react project, initiate npm link:
@@ -131,10 +305,6 @@ overwrite existing .tsx files. If you need to update a pre-existing .tsx file, d
 Possible options for SVGR:
 https://react-svgr.com/docs/options/
 
-
-
-
-
 ## Documentation
 
 To generate documentation:
@@ -144,29 +314,30 @@ npm run generate-docs
 
 Publishing the package will also regenerate the documentation.
 
-
-
 ## Additional Documentation
 
 Beyond doc-comments in the code, we provide additional documentation in the additional-docs folder.
 
+- AutoCoreTagContext Manual: [AutoCoreTagContext Manual](../additional-docs/AutoCoreTagContext.md).
 - Button API Specs: [Button API Specs](../additional-docs/ButtonApiSpecs.md).
 - Global Event Emitter: [Global Event Emitter](../additional-docs/GlobalEventEmitter.md).
 
-
 ## Acknowledgements
 
-Beyond the obvious, inherent React libraries, autocore-react greatly appreciates the works of
+Beyond the obvious, inherent React and TypeScript libraries, autocore-react greatly appreciates the works of
 these additional libraries.
 
 - PrimeReact and PrimeIcons
 - numerable
 - Simple Keyboard (https://github.com/hodgef/simple-keyboard)
 - - We customize Simple Keyboard for cleaner physical keyboard integration.
+- Monaco editor
+- socket-io
+- Tauri
 
 ## Copyright
 
-(C) Copyright 2021-2024 Automated Design Corp. All Rights Reserved.
+(C) Copyright 2021-2025 Automated Design Corp. All Rights Reserved.
 
 ## License