@adcops/autocore-react 3.0.39 → 3.1.1

package/dist/core/AutoCoreTagContext.d.ts

@@ -0,0 +1,224 @@
+/**
+ * @module core/AutoCoreTagContext
+ *
+ * @document ../../additional-docs/AutCoreTagContext.md
+ *
+ * @summary
+ * A React Context + Provider that:
+ * - Buffers **raw** controller values for every tag (exactly as received)
+ * - Derives **display** values from raw using current `scales` and optional tag `codec`
+ * - Recomputes display values **from raw** whenever a scale changes (no lossy re-scaling)
+ * - Inverse-scales on `write()` so the server always receives controller units
+ * - Supports ADS one-shot refresh, GNV-style scale objects, and resilient eager reads
+ *
+ * @remarks
+ * ❖ **Two representations per tag**
+ * - `rawValues[tagName]`: last controller value as-is (pre-scale, pre-codec)
+ * - `values[tagName]`: app-visible value derived from raw (scales/codec applied)
+ *
+ * ❖ **Scaling**
+ * - Provide `scales` keyed by scale group (e.g., `"position"`, `"load"`).
+ * - Each scale may point at a server tag (`serverTag`) that publishes an object
+ *   `{ name, scale, label }` (GNV-style). When received, the Provider recomputes
+ *   *only* affected display values **from raw**.
+ * - Manual `updateScale(name, scale, label)` writes the object back to the server
+ *   (if `serverTag` is configured) and recomputes from raw locally.
+ *
+ * ❖ **Lifecycle order (eagerRead = true)**
+ * 1. Pull server scales first (so first ADS burst displays in correct units)
+ * 2. Register ADS symbols and subscribe all domains
+ * 3. Eager-pull non-ADS (refresh if available, else read_value)
+ * 4. ADS `refresh` one-shot publish
+ *
+ * ❖ **Writes**
+ * - `write(tagName, displayValue)` → (codec?) → inverse-scale → `write_value`
+ * - `tap(tagName)` pulses booleans `true → (300ms) → false` with proper domain envelopes
+ *
+ * ❖ **Resilience**
+ * - Eager reads tolerate “missing key” errors on fresh systems and keep going
+ * - All re-scaling recomputes from **raw** to avoid cumulative precision/race issues
+ *
+ * @example Minimal wiring
+ * ```tsx
+ * import { AutoCoreTagProvider } from "@adcops/autocore-react/core/AutoCoreTagContext";
+ * import type { TagConfig, ScaleConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+ *
+ * const acTagSpec = [
+ *   { tagName: "pressPosition", domain: "ADS", valueType: "number", symbolName: "AX.Press.Position", scale: "position" },
+ *   { tagName: "pressLoad",     domain: "ADS", valueType: "number", symbolName: "AX.Press.Load",     scale: "load" },
+ *   { tagName: "isMotorsOn",    domain: "ADS", valueType: "boolean", symbolName: "GIO.isMotorsOn" },
+ * ] as const satisfies readonly TagConfig[];
+ *
+ * const scales: Record<string, ScaleConfig> = {
+ *   position: {
+ *     name: "position",
+ *     scale: 1.0,
+ *     label: "mm",
+ *     serverTag: { domain: "GNV", symbolName: "position_units" }, // expects {name, scale, label}
+ *   },
+ *   load: {
+ *     name: "load",
+ *     scale: 1.0,
+ *     label: "N",
+ *     serverTag: { domain: "GNV", symbolName: "load_units" },     // expects {name, scale, label}
+ *   },
+ * };
+ *
+ * export function AppRoot() {
+ *   return (
+ *     <AutoCoreTagProvider tags={acTagSpec} scales={scales} eagerRead>
+ *       <App />
+ *     </AutoCoreTagProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Consuming values with hooks
+ * ```tsx
+ * import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
+ * import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
+ *
+ * export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, acTagSpec);
+ *
+ * function Dashboard() {
+ *   const { value: pos } = AutoCoreHooks.useAutoCoreTag("pressPosition"); // display units
+ *   const { value: load } = AutoCoreHooks.useAutoCoreTag("pressLoad");
+ *   const { scales, updateScale } = AutoCoreHooks.useScales();
+ *
+ *   return (
+ *     <>
+ *       <div>Position: {pos} {scales.position.label}</div>
+ *       <div>Load: {load} {scales.load.label}</div>
+ *       <button onClick={() => updateScale("position", 1/25.4, "in")}>inches</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+import React, { type ReactNode } from "react";
+import type { BaseContextValue, TagConfig, ScaleConfig } from "./AutoCoreTagTypes";
+type VMapRuntime = Record<string, unknown>;
+export declare const AutoCoreTagContext: React.Context<BaseContextValue<VMapRuntime>>;
+/**
+ * AutoCoreTagProvider
+ *
+ * @description
+ * React Provider that wires up AutoCore tags to live server updates, buffers **raw**
+ * controller values, exposes **display** values (scales/codec applied), and handles
+ * writes/taps with proper domain envelopes. Scaling is **always** applied to display
+ * values only; raw values remain untouched and are the single source of truth.
+ *
+ * @props
+ * - `tags: readonly TagConfig[]`
+ *    The full tag spec. Each tag declares `tagName`, `domain`, `symbolName`,
+ *    `valueType` ("boolean"|"number"|"string"|"json"), optional `scale` name, and
+ *    optional `codec` for JSON.
+ *
+ * - `scales?: Record<string, ScaleConfig>`
+ *    Map of scale groups (`position`, `load`, …). Each scale may include an optional
+ *    `serverTag` `{ domain, symbolName }`. When present, the provider reads that key
+ *    first and subscribes to updates. The server must publish a GNV-style object
+ *    `{ name, scale, label }` (stringified or object). When a new scale arrives,
+ *    the provider recomputes affected display values **from raw**.
+ *
+ * - `eagerRead?: boolean = true`
+ *    If true, the provider performs a non-ADS eager fetch pass (refresh if available,
+ *    otherwise read_value with backoff) and then performs a single ADS `refresh`.
+ *    Missing keys are common on clean systems—these are logged and skipped.
+ *
+ * - `children: ReactNode`
+ *    Your app subtree that consumes `AutoCoreTagContext`.
+ *
+ * @context value
+ * - `values`: Partial<Record<tagName, unknown>> — app-visible (scaled/decoded)
+ * - `rawValues`: Record<tagName, unknown>       — last controller values as received
+ * - `isLoading`: boolean                        — true until initial wiring completes
+ * - `write(tagName, displayValue)`: Promise<void>
+ *      Serializes/encodes JSON if needed and inverse-scales numbers back to raw units.
+ *      Dispatches `write_value` with appropriate domain envelope:
+ *      - ADS: `{ symbol_name, value }`
+ *      - GNV: `{ group:"ux", key, value }`
+ *      - Other: `{ key, value }`
+ * - `tap(tagName)`: Promise<void>
+ *      For boolean tags only. Pulses true → 300ms → false with the proper envelope.
+ * - `scales`: Record<string, ScaleConfig>       — current factors/labels
+ * - `updateScale(name, scale, label)`: Promise<void>
+ *      Writes `{ name, scale, label }` to the configured `serverTag` (if present) and
+ *      recomputes display values **from raw** locally.
+ *
+ * @example With server-driven scales (GNV) and ADS data
+ * ```tsx
+ * const tags: readonly TagConfig[] = [
+ *   { tagName: "pressPosition", domain: "ADS", valueType: "number", symbolName: "AX.Press.Pos",   scale: "position" },
+ *   { tagName: "pressLoad",     domain: "ADS", valueType: "number", symbolName: "AX.Press.Load",  scale: "load" },
+ *   { tagName: "isMotorsOn",    domain: "ADS", valueType: "boolean", symbolName: "GIO.isMotorsOn" },
+ *   // JSON with codec example
+ *   { tagName: "jobMeta",       domain: "GNV", valueType: "json",   symbolName: "job_meta",
+ *     codec: {
+ *       fromServer: (raw) => (typeof raw === "string" ? JSON.parse(raw) : raw),
+ *       toServer:   (val) => JSON.stringify(val),
+ *     }
+ *   },
+ * ] as const;
+ *
+ * const scales: Record<string, ScaleConfig> = {
+ *   position: {
+ *     name: "position",
+ *     scale: 1, label: "mm",
+ *     serverTag: { domain: "GNV", symbolName: "position_units" } // expects {name, scale, label}
+ *   },
+ *   load: {
+ *     name: "load",
+ *     scale: 1, label: "N",
+ *     serverTag: { domain: "GNV", symbolName: "load_units" }     // expects {name, scale, label}
+ *   }
+ * };
+ *
+ * <AutoCoreTagProvider tags={tags} scales={scales} eagerRead>
+ *   <YourApp/>
+ * </AutoCoreTagProvider>
+ * ```
+ *
+ * @example Reading values, raw vs display, and writing
+ * ```tsx
+ * import { makeAutoCoreTagHooks } from "../hooks/useAutoCoreTag";
+ * import { AutoCoreTagContext } from "../core/AutoCoreTagContext";
+ *
+ * const Hooks = makeAutoCoreTagHooks(AutoCoreTagContext, tags);
+ *
+ * function Status() {
+ *   const { value: pos, isLoading } = Hooks.useAutoCoreTag("pressPosition"); // scaled
+ *   const { value: rawPos } = (() => {
+ *     // access raw via context when needed for debugging
+ *     const ctx = React.useContext(AutoCoreTagContext);
+ *     return { value: ctx.rawValues["pressPosition"] };
+ *   })();
+ *
+ *   const { scales, updateScale } = Hooks.useScales();
+ *
+ *   return (
+ *     <>
+ *       <div>Pos: {pos} {scales.position.label} (raw: {String(rawPos)})</div>
+ *       <button onClick={() => updateScale("position", 1/25.4, "in")}>inches</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example Tapping booleans and writing numbers in display units
+ * ```tsx
+ * const { tap } = Hooks.useAutoCoreTag("isMotorsOn");
+ * const { write } = Hooks.useAutoCoreTag("pressPosition");
+ *
+ * <button onClick={() => tap()}>Motors TAP</button>
+ * <button onClick={() => write(10.0)}>Jog to 10 (display units)</button>
+ * ```
+ */
+export declare const AutoCoreTagProvider: React.FC<{
+    children: ReactNode;
+    tags: readonly TagConfig[];
+    scales?: Record<string, ScaleConfig>;
+    eagerRead?: boolean;
+}>;
+export {};
+//# sourceMappingURL=AutoCoreTagContext.d.ts.map

package/dist/core/AutoCoreTagContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutoCoreTagContext.d.ts","sourceRoot":"","sources":["../../src/core/AutoCoreTagContext.tsx"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAGH,OAAO,KAAK,EAAE,EAQV,KAAK,SAAS,EACjB,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EACR,gBAAgB,EAChB,SAAS,EACT,WAAW,EACd,MAAM,oBAAoB,CAAC;AAE5B,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3C,eAAO,MAAM,kBAAkB,8CAQ7B,CAAC;AAQH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AACH,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC;IACvC,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB,CAkbA,CAAC"}

package/dist/core/AutoCoreTagContext.js

@@ -0,0 +1 @@
+import{jsx as _jsx}from"react/jsx-runtime";import React,{useRef,createContext,useCallback,useContext,useEffect,useMemo,useState}from"react";import{EventEmitterContext}from"./EventEmitterContext";export const AutoCoreTagContext=createContext({values:{},rawValues:{},isLoading:!0,write:async()=>{},tap:async()=>{},scales:{},updateScale:async()=>{}});const sleep=e=>new Promise(t=>setTimeout(t,e));export const AutoCoreTagProvider=({children:e,tags:t,scales:a={},eagerRead:s=!0})=>{const o=useRef(!1),{invoke:n,isConnected:r,subscribe:c,unsubscribe:l}=useContext(EventEmitterContext),[u,i]=useState(()=>{const e={};for(const a of t)void 0!==a.initialValue&&(e[a.tagName]=a.initialValue);return e}),[m,f]=useState({}),[y,b]=useState(a),p=useRef(y),v=useRef(u);useEffect(()=>{p.current=y},[y]),useEffect(()=>{v.current=u},[u]);const[g,d]=useState(!0),N=useCallback((e,t)=>{const{valueType:a,scale:s,codec:o}=e;if("number"===a&&"number"==typeof t&&s){const e=p.current[s];return t*(e?.scale??1)}if("json"===a&&o?.fromServer)try{return o.fromServer(t)}catch{}return t},[]),C=useCallback((e,t)=>{const{valueType:a,scale:s,codec:o}=e;if("json"===a&&o?.toServer)try{t=o.toServer(t)}catch{}if("number"===a&&"number"==typeof t&&s){const e=p.current[s];return t/(e?.scale??1)}return t},[]),w=useCallback(e=>{const a=t.filter(t=>t.scale===e);a.length&&f(e=>{const t={...e};for(const e of a){const a=v.current[e.tagName];if("number"!=typeof a)continue;const s=N(e,a);t[e.tagName]!==s&&(t[e.tagName]=s)}return t})},[t,N]),h=useCallback((e,t)=>{i(a=>a[e.tagName]===t?a:{...a,[e.tagName]:t});const a=N(e,t);f(t=>t[e.tagName]===a?t:{...t,[e.tagName]:a})},[N]),x=useCallback(async(e,t,a)=>{const s=a?.concurrency??4,o=a?.minDelayMs??20,r=a?.jitterMs??40;let c=0;const l=Array.from({length:s},()=>(async()=>{for(;;){const a=c++;if(a>=t.length)return;const s=t[a];try{let t=!1;try{await n(e,"refresh",{topic:s.symbolName}),t=!0}catch{}if(!t){const t="GNV"===e.toUpperCase()?{group:"ux",key:s.symbolName}:{key:s.symbolName};s.options&&(t.options=s.options);try{const a=await n(e,"read_value",t);a?.success&&a?.valid&&h(s,a.data)}catch(e){}}}catch(e){}finally{const e=Math.floor(Math.random()*r);await sleep(o+e)}}})());await Promise.all(l)},[n,h]),k=useCallback(async()=>{for(const[e,t]of Object.entries(a)){if(!t.serverTag)continue;const{domain:a,symbolName:s}=t.serverTag;try{const t=await n(a,"read_value",{group:"ux",key:s});if(t.data&&(t.success??1)&&(t.valid??1)){const a=JSON.parse(t.data);if(a&&"number"==typeof a.scale){const{scale:t,label:s}=a;b(a=>({...a,[e]:{...a[e],scale:t,label:s??a[e]?.label??"---"}})),w(e)}}}catch{}}},[n,a,w]);useEffect(()=>{let e=!0;const a=[],u=async()=>{if(e&&!o.current){o.current=!0;try{await(async()=>{const o=new Map;for(const e of t){const t=o.get(e.domain);t?t.push(e):o.set(e.domain,[e])}try{await k();for(const[t,r]of o.entries()){if("ADS"===t.toUpperCase())for(const e of r)try{const t=e.options?{symbol_name:e.symbolName,options:e.options}:{symbol_name:e.symbolName};await n("ADS","register_symbol",t)}catch(e){}for(const s of r){const o=c(`${t}/${s.symbolName}`,t=>{e&&h(s,t?.value)});a.push(o)}s&&"ADS"!==t.toUpperCase()&&await x(t,r,{concurrency:4,minDelayMs:20,jitterMs:40})}s&&await n("ADS","refresh",{})}finally{e&&setTimeout(()=>e&&d(!1),100)}})()}finally{e&&setTimeout(()=>e&&d(!1),100)}}};if(r())u();else{const e=c("HUB/connected",()=>{l(e),u()});a.push(e)}return()=>{e=!1,a.forEach(l),o.current=!1}},[c,l,r,n,s,t,k,x,h]);const S=useMemo(()=>Object.entries(a).filter(([,e])=>e.serverTag).map(([e,t])=>({scaleName:e,domain:t.serverTag.domain,symbolName:t.serverTag.symbolName})),[a]);useEffect(()=>{let e=!0;const t=[];for(const{scaleName:a,domain:s,symbolName:o}of S){const n=c(`${s}/${o}`,t=>{if(!e)return;const s=t?.value;if(s&&"object"==typeof s&&"number"==typeof s.scale){const{scale:e,label:t}=s;b(s=>({...s,[a]:{...s[a],scale:e,label:t??s[a]?.label??"---"}})),w(a)}});t.push(n)}return()=>{e=!1,t.forEach(l)}},[c,l,S,w]);const T=useCallback(async(e,a)=>{const s=t.find(t=>t.tagName===e);if(!s)return;const o=C(s,a);let r;const c=s.domain.toUpperCase();r="ADS"===c?{symbol_name:s.symbolName,value:o}:"GNV"===c?{group:"ux",key:s.symbolName,value:o}:{key:s.symbolName,value:o},await n(s.domain,"write_value",r)},[t,n,C]),E=useCallback(async e=>{const a=t.find(t=>t.tagName===e);if(!a)return;if("boolean"!==a.valueType)return;const s=a.domain.toUpperCase(),o=e=>"ADS"===s?{symbol_name:a.symbolName,value:e}:"GNV"===s?{group:"ux",key:a.symbolName,value:e}:{key:a.symbolName,value:e};await n(a.domain,"write_value",o(!0)),await sleep(300),await n(a.domain,"write_value",o(!1))},[t,n]),_=useCallback(async(e,t,a)=>{const s=y[e];s&&(s.serverTag&&await n(s.serverTag.domain,"write_value",{group:"ux",key:s.serverTag.symbolName,value:{name:e,scale:t,label:a}}),b(s=>({...s,[e]:{...s[e],scale:t,label:a}})),w(e))},[y,n,w]);useEffect(()=>{f(e=>{const a={...e};for(const e of t){const t=v.current[e.tagName];if(void 0===t)continue;const s=N(e,t);a[e.tagName]!==s&&(a[e.tagName]=s)}return a})},[t,N,y]);const j=useMemo(()=>({values:m,rawValues:u,isLoading:g,write:T,tap:E,scales:y,updateScale:_}),[m,u,g,T,E,y,_]);return _jsx(AutoCoreTagContext.Provider,{value:j,children:e})};

package/dist/core/AutoCoreTagTypes.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @module core/AutoCoreTagTypes
+ *
+ * Core type system for AutoCore's tag layer:
+ * - Strongly-typed tag values (boolean/number/string/json)
+ * - Optional **scales** for numeric unit conversion (e.g., mm ⇄ in)
+ * - Optional **codecs** to present richer client-side types (Date/Map) while
+ *   keeping pure JSON across the wire (serde_json::Value on the server)
+ */
+export type PrimitiveKind = "boolean" | "number" | "string" | "json";
+/** Strict JSON value (mirrors serde_json::Value) */
+type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | {
+    [key: string]: JsonValue;
+} | JsonValue[];
+/**
+ * Extended client-side value you *may* choose to present in the UI.
+ * Use codecs to round-trip these as pure JSON to the server.
+ */
+export type ExtendedJsonValue = JsonValue | Date | Map<string, JsonValue>;
+/**
+ * Map a tag's declared primitive kind to the app-visible type.
+ * - "json" becomes ExtendedJsonValue so UIs can work with Date/Map when desired.
+ */
+export type TagValueOf<K extends PrimitiveKind> = K extends "boolean" ? boolean : K extends "number" ? number : K extends "string" ? string : ExtendedJsonValue;
+/**
+ * Runtime binding for a single tag, as returned by hooks like `useAutoCoreTag`.
+ * - `value` is app-visible (already scaled/decoded)
+ * - `rawValue` is the last **unscaled, un-decoded** controller value received (server JSON)
+ * - `write` expects app-visible value (provider will inverse-scale/encode)
+ * - `tap` is typically for boolean momentaries (provider may pulse true→false)
+ */
+export type TagBinding<T> = Readonly<{
+    /** App-visible value (scaled/decoded). */
+    value: T | undefined;
+    /** Last raw value from the server (pre-scale, pre-codec). */
+    rawValue: unknown | undefined;
+    /** Write a new app-visible value (provider will inverse-scale/encode). */
+    write: (displayValue: T) => Promise<void>;
+    /** Momentary action; typically boolean true→false pulse. */
+    tap: () => Promise<void>;
+    /** True while initial read/bootstrapping is in progress. */
+    isLoading: boolean;
+}>;
+/**
+ * Configuration for a named scale group.
+ * Apply by setting `scale: "<name>"` on numeric tags.
+ */
+export interface ScaleConfig {
+    /** Unique name for this scale group (e.g., "position", "load") */
+    name: string;
+    /** Current scale factor — incoming values ×= scale; outgoing values /= scale */
+    scale: number;
+    /** Units/label for display (e.g., "mm", "in", "lbs") */
+    label: string;
+    /** Optional description for debugging/documentation */
+    description?: string;
+    /**
+     * Optional server tag that provides the scale dynamically.
+     * (If used, your provider should subscribe and update `scale` when it changes.)
+     */
+    serverTag?: {
+        domain: string;
+        symbolName: string;
+    };
+}
+/**
+ * A codec lets a tag expose a richer client-side type while staying JSON on the wire.
+ * Common examples:
+ * - Date values: ISO string ⇄ Date
+ * - Map-like blobs: object ⇄ Map<string, JsonValue>
+ */
+export type TagCodec<TIn = unknown, TOut extends JsonValue = JsonValue> = {
+    /** raw JSON (from server) → app-visible value */
+    fromServer?: (raw: unknown) => TIn;
+    /** app-visible value → pure JSON (to server) */
+    toServer?: (value: TIn) => TOut;
+};
+/**
+ * Tag configuration descriptor used to build a typed spec.
+ *
+ * @typeParam K - Literal tag name (use `as const` on your spec array)
+ * @typeParam T - Primitive kind for type mapping (boolean/number/string/json)
+ */
+export type TagConfig<K extends string = string, T extends PrimitiveKind = PrimitiveKind> = {
+    /** Local key used by UI/consumers (unique within your spec) */
+    tagName: K;
+    /** Domain for the symbol (e.g., "ADS", "MEMORYSTORE") */
+    domain: string;
+    /** Server symbol/topic name (as used by your backend invoke API) */
+    symbolName: string;
+    /** Declared primitive kind for typing and DevPanel rendering */
+    valueType: T;
+    /** Optional initial **raw** value before first server update */
+    initialValue?: TagValueOf<T>;
+    /** Optional per-tag hook/config options (e.g., cycle time, debounce) */
+    options?: Record<string, unknown>;
+    /**
+     * Optional scale group for numeric tags.
+     * If present, provider will:
+     * - Multiply incoming numbers by the group's `scale`
+     * - Divide outgoing numbers by the group's `scale`
+     */
+    scale?: string;
+    /**
+     * Optional codec to present richer UI types while keeping JSON on the wire.
+     * Only commonly used with `valueType: "json"`.
+     */
+    codec?: TagCodec;
+};
+/** Extract the tag config for a particular tag name `K` from a `Spec` */
+export type ExtractByTag<Spec extends readonly TagConfig[], K> = Extract<Spec[number], {
+    tagName: K;
+}>;
+/**
+ * Build a strongly-typed map of tagName → app-visible value type.
+ * Use with `as const` specs to preserve literal tag names.
+ */
+export type TagValueMap<Spec extends readonly TagConfig[]> = {
+    [K in Spec[number]["tagName"]]: TagValueOf<ExtractByTag<Spec, K>["valueType"]>;
+};
+/**
+ * Helper: binding type for a specific tag name from a spec.
+ */
+export type BindingOf<Spec extends readonly TagConfig[], K extends Spec[number]["tagName"]> = TagBinding<TagValueMap<Spec>[K]>;
+/**
+ * Enhanced context value with scale management.
+ * Providers should:
+ * - Buffer **raw** values in `rawValues` (pre-scale, pre-codec)
+ * - Populate `values` from `rawValues` using current scales/codecs
+ * - Inverse-scale/encode on write(t) before invoking backend
+ */
+export interface BaseContextValue<VMap extends Record<string, any>> {
+    /** Current app-visible tag values (already scaled/decoded). */
+    values: Partial<VMap>;
+    /** Last raw (controller) values, as received (pre-scale, pre-codec). */
+    rawValues: Record<string, unknown>;
+    /** Whether initial reads are pending. */
+    isLoading: boolean;
+    /**
+     * Write a single tag value (app-visible → provider will inverse-scale/encode).
+     * Strongly typed by tag name when used with a typed Context.
+     */
+    write: <K extends keyof VMap & string>(tagName: K, value: VMap[K]) => Promise<void>;
+    /**
+     * Trigger a momentary/toggle action for a tag.
+     * Typically used for boolean "request" bits.
+     */
+    tap: <K extends keyof VMap & string>(tagName: K) => Promise<void>;
+    /** Current scale configurations by name. */
+    scales: Record<string, ScaleConfig>;
+    /**
+     * Update a scale group (factor and label). Providers should recompute affected tags from **raw**.
+     *
+     * @param scaleName - Name of the scale group (e.g., "position")
+     * @param newScale  - New scale factor (display = raw * newScale)
+     * @param newLabel  - New units label (e.g., "inches")
+     */
+    updateScale: (scaleName: string, newScale: number, newLabel: string) => Promise<void>;
+}
+export {};
+//# sourceMappingURL=AutoCoreTagTypes.d.ts.map

package/dist/core/AutoCoreTagTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutoCoreTagTypes.d.ts","sourceRoot":"","sources":["../../src/core/AutoCoreTagTypes.ts"],"names":[],"mappings":"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"}

package/dist/core/AutoCoreTagTypes.js

@@ -0,0 +1 @@
+export{};