@adcops/autocore-react 3.3.123 → 3.5.3

package/src/components/tis/TisProvider.tsx

@@ -391,7 +391,7 @@ export interface TisProviderProps {
 }
 
 export const TisProvider: React.FC<TisProviderProps> = ({ children, defaultMethodId: initialDefault }) => {
-    const { invoke, subscribe, unsubscribe } = useContext(EventEmitterContext);
+    const { invoke, read, subscribe, unsubscribe, isConnected } = useContext(EventEmitterContext);
 
     const [schemas, setSchemas] = useState<SchemaRegistry>({});
     const [projectAssetRefs, setProjectAssetRefs] = useState<TisProjectAssetRef[]>([]);
@@ -506,8 +506,51 @@ export const TisProvider: React.FC<TisProviderProps> = ({ children, defaultMetho
             subscribe('tis.active_run_id',       (v: any) => dispatch({ kind: 'active_run_id',       value: String(v ?? '') })),
             subscribe('tis.last_start_error',    (v: any) => dispatch({ kind: 'last_start_error',    value: String(v ?? '') })),
         ];
-        return () => { subs.forEach(unsubscribe); };
-    }, [subscribe, unsubscribe]);
+        // SEED from the current values. Subscriptions only deliver CHANGES, so
+        // on a page refresh mid-test every scalar below would sit empty until
+        // the run's state happened to move — which is why <TestDataView> came
+        // back saying "No test selected" while a test was plainly open, with no
+        // way to select it (an active run clears the History pins).
+        //
+        // Read the GM SCALARS, not the `tis.*` broadcast topics: `tis.active_run_id`
+        // is what the TIS module *publishes*, and it is not a readable endpoint.
+        // The backing variable `gm.tis_active_run_id` is.
+        //
+        // Failures are ignored: a machine without TIS has nothing to seed.
+        const SEED: { fqdn: string; kind: StateAction["kind"]; bool?: boolean }[] = [
+            { fqdn: 'gm.tis_staged',            kind: 'staged',            bool: true },
+            { fqdn: 'gm.tis_staged_project_id', kind: 'staged_project_id' },
+            { fqdn: 'gm.tis_staged_method_id',  kind: 'staged_method_id' },
+            { fqdn: 'gm.tis_staged_sample_id',  kind: 'staged_sample_id' },
+            { fqdn: 'gm.tis_active',            kind: 'active',            bool: true },
+            { fqdn: 'gm.tis_active_project_id', kind: 'active_project_id' },
+            { fqdn: 'gm.tis_active_method_id',  kind: 'active_method_id' },
+            { fqdn: 'gm.tis_active_sample_id',  kind: 'active_sample_id' },
+            { fqdn: 'gm.tis_active_run_id',     kind: 'active_run_id' },
+        ];
+        let cancelled = false;
+        // Only worth attempting once the hub is up — on a cold page load this
+        // effect can run before the socket connects, and a read that fails then
+        // would leave the state empty exactly as before. `isConnected` is in the
+        // deps, so the seed runs again the moment the connection lands.
+        void (async () => {
+            if (!isConnected) return;
+            for (const { fqdn, kind, bool } of SEED) {
+                try {
+                    const resp: any = await read(fqdn);
+                    if (cancelled) return;
+                    if (resp && resp.success === false) continue;
+                    const v = resp?.data;
+                    if (v === undefined || v === null) continue;
+                    dispatch({ kind, value: bool ? !!v : String(v) } as StateAction);
+                } catch {
+                    /* scalar absent on this machine — nothing to seed */
+                }
+            }
+        })();
+
+        return () => { cancelled = true; subs.forEach(unsubscribe); };
+    }, [subscribe, unsubscribe, read, isConnected]);
 
     // -----------------------------------------------------------------
     // Run cache — broadcasts of cycles/results land here so detail

package/src/components/tis-editor/editor/ChartViewDialog.tsx

@@ -3,9 +3,16 @@ import { Dialog } from 'primereact/dialog';
 import { Button } from 'primereact/button';
 import { InputText } from 'primereact/inputtext';
 import { Dropdown } from 'primereact/dropdown';
+import { InputNumber } from 'primereact/inputnumber';
 import { FormRow } from '../../forms/FormRow';
+import { DEFAULT_X_DECIMALS } from '../../tis/TestDataView';
 import type { ChartAxis, ChartSeries, ChartView } from '../types';
 
+/** Upper bound on the editor's X-decimals spinner. Past ~6 the tick labels
+ *  are wider than the gap between them, which is the problem this setting
+ *  exists to solve. */
+const MAX_X_DECIMALS = 8;
+
 const VIEW_TYPES = [
     { label: 'Cycle scatter', value: 'cycle_scatter' },
     { label: 'Raw trace',     value: 'raw_trace' },
@@ -115,6 +122,26 @@ export const ChartViewDialog: React.FC<ChartViewDialogProps> = ({
                     onChange={(e) => setAxis({ label: e.target.value })}
                 />
             </FormRow>
+            <FormRow
+                label="X decimals"
+                hint={`Decimal places on X-axis tick labels. Blank uses the default (${DEFAULT_X_DECIMALS}). Display only — stored data keeps full precision.`}
+            >
+                <InputNumber
+                    value={draft.x_decimals ?? null}
+                    onValueChange={(e) => {
+                        // Blank clears the override so the view falls back to
+                        // the default, rather than pinning it to 0 decimals.
+                        const next = { ...draft };
+                        if (e.value == null) delete next.x_decimals;
+                        else next.x_decimals = e.value;
+                        setDraft(next);
+                    }}
+                    min={0}
+                    max={MAX_X_DECIMALS}
+                    placeholder={String(DEFAULT_X_DECIMALS)}
+                    showButtons
+                />
+            </FormRow>
 
             <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', margin: '1rem 0 0.5rem' }}>
                 <strong>Y series</strong>

package/src/components/tis-editor/types.ts

@@ -89,6 +89,12 @@ export interface ChartView {
     type: ChartViewType | string;
     x: ChartAxis;
     y: ChartSeries[];
+    /**
+     * Max decimal places on X-axis tick labels (display only; default 2).
+     * See `ChartView.x_decimals` in TestDataView for why an uncapped axis
+     * prints 17-digit ticks.
+     */
+    x_decimals?: number;
 }
 
 export type RawColumnSource = 'time' | 'derived' | string; // also `ni.<daq>.channels.<name>`

package/src/core/AutoCoreTagContext.tsx

@@ -72,10 +72,13 @@ import { EventEmitterContext } from "./EventEmitterContext";
 import type {
     BaseContextValue,
     TagConfig,
-    ScaleConfig
+    ScaleConfig,
+    UnitsTable,
+    UnitSystemScale
 } from "./AutoCoreTagTypes";
 
 import { MessageType } from "../hub/CommandMessage";
+import { formatScaled } from "./formatScaled";
 
 /**
  * Runtime type for the values map - allows any tag name to map to any value type.
@@ -227,19 +230,87 @@ export const AutoCoreTagProvider: React.FC<{
 
     const [isLoading, setIsLoading] = useState(true);
 
+    // ── units.json ──────────────────────────────────────────────────────────
+    //
+    // The machine's single definition of units, fetched from `system.get_units`
+    // and resolved against the active system into the `scaleValues` map the
+    // rescale machinery below already understands. Switching systems is
+    // therefore a re-derive + rescale-from-raw — no reload, no restart, and no
+    // stored value is ever touched. See autocore-server/UNITS_PLAN.md §6.3.
+    const [units, setUnits] = useState<UnitsTable | null>(null);
+    const [activeSystem, setActiveSystem] = useState<string | null>(null);
+    const activeSystemRef = useRef<string | null>(null);
+    const unitsRef = useRef<UnitsTable | null>(null);
+    useEffect(() => { activeSystemRef.current = activeSystem; }, [activeSystem]);
+    useEffect(() => { unitsRef.current = units; }, [units]);
+
+    /**
+     * Resolve a units table + system into the provider's scale map.
+     *
+     * Keyed by quantity name, which is what a tag's `quantity` references — so
+     * every existing rescale path keeps working unchanged.
+     */
+    const resolveScales = useCallback(
+        (table: UnitsTable, system: string): Record<string, ScaleConfig> => {
+            const out: Record<string, ScaleConfig> = {};
+            for (const [quantity, row] of Object.entries(table.scales ?? {})) {
+                const entry = (row as any)?.[system] as UnitSystemScale | undefined;
+                if (!entry || typeof entry.scalar !== "number") continue;
+                out[quantity] = {
+                    name: quantity,
+                    scale: entry.scalar,
+                    label: entry.label ?? "",
+                    // Only an `absolute` quantity takes the offset. A temperature
+                    // DELTA must not: a 10 °C rise is 18 °F, not 50 °F.
+                    offset: (row as any)?.kind === "absolute" ? (entry.offset ?? 0) : 0,
+                    precision: entry.precision,
+                    precisionMode: entry.precision_mode,
+                };
+            }
+            return out;
+        },
+        [],
+    );
+
+    /** Re-derive every scale and recompute all displayed values from raw. */
+    const applyUnitSystem = useCallback(
+        (table: UnitsTable, system: string) => {
+            setUnits(table);
+            setActiveSystem(system);
+            const resolved = resolveScales(table, system);
+            scaleRef.current = resolved; // so the rescale below sees the new factors
+            setScaleValues(resolved);
+            setValues(prev => {
+                const next = { ...prev };
+                for (const tag of tags) {
+                    const q = tag.quantity ?? tag.scale;
+                    if (!q || !resolved[q]) continue;
+                    const raw = rawRef.current[tag.tagName];
+                    if (typeof raw !== "number") continue;
+                    const s = resolved[q];
+                    next[tag.tagName] = raw * s.scale + (s.offset ?? 0);
+                }
+                return next;
+            });
+        },
+        [resolveScales, tags],
+    );
+
     /**
      * Converts a raw controller value to a display value.
      *
      * Pipeline: Raw -> [Codec Decode] -> [Scale Multiply] -> Display
      */
     const toDisplay = useCallback((tag: TagConfig, raw: unknown): unknown => {
-        const { valueType, scale, codec } = tag;
+        const { valueType, codec } = tag;
+        const quantity = tag.quantity ?? tag.scale;
 
-        // 1) numeric scaling: multiply raw by scale factor
-        if (valueType === "number" && typeof raw === "number" && scale) {
-            const s = scaleRef.current[scale];
+        // 1) numeric scaling: backend -> display for the active unit system.
+        //    `offset` is non-zero only for an absolute quantity (temperature).
+        if (valueType === "number" && typeof raw === "number" && quantity) {
+            const s = scaleRef.current[quantity];
             const factor = s?.scale ?? 1;
-            return raw * factor;
+            return raw * factor + (s?.offset ?? 0);
         }
 
         // 2) codec for json (optional): decode server representation
@@ -257,18 +328,20 @@ export const AutoCoreTagProvider: React.FC<{
      * Pipeline: Display -> [Scale Divide] -> [Codec Encode] -> Raw
      */
     const toServer = useCallback((tag: TagConfig, display: unknown): unknown => {
-        const { valueType, scale, codec } = tag;
+        const { valueType, codec } = tag;
+        const quantity = tag.quantity ?? tag.scale;
 
         // 1) invert codec first (json): encode for server
         if (valueType === "json" && codec?.toServer) {
             try { display = codec.toServer(display as any); } catch { /* fall through */ }
         }
 
-        // 2) inverse numeric scaling: divide by scale factor
-        if (valueType === "number" && typeof display === "number" && scale) {
-            const s = scaleRef.current[scale];
+        // 2) inverse numeric scaling: display -> backend. Operator entry is the
+        //    only place this runs; stored values are never converted.
+        if (valueType === "number" && typeof display === "number" && quantity) {
+            const s = scaleRef.current[quantity];
             const factor = s?.scale ?? 1;
-            return display / factor;
+            return (display - (s?.offset ?? 0)) / factor;
         }
 
         return display;
@@ -282,7 +355,7 @@ export const AutoCoreTagProvider: React.FC<{
      * This prevents floating point error accumulation from repeated scaling.
      */
     const rescaleFromRaw = useCallback((scaleName: string) => {
-        const affected = tags.filter(t => t.scale === scaleName);
+        const affected = tags.filter(t => (t.quantity ?? t.scale) === scaleName);
         if (!affected.length) return;
 
         setValues(prev => {
@@ -452,8 +525,64 @@ export const AutoCoreTagProvider: React.FC<{
     );
 
     /**
-     * Reads scale configurations from the server (if configured).
-     * Ensures display units match the server's persisted configuration.
+     * Fetch `units.json` from the server and resolve it against the machine's
+     * active system.
+     *
+     * This replaces the hand-authored `acScales` map: units are now defined once
+     * per machine, in a file the operator edits, and every consumer reads the
+     * same table. Failure is non-fatal — a machine with no units sidecar renders
+     * raw backend values rather than a blank screen (UNITS_PLAN.md §3.1).
+     */
+    const pullUnits = useCallback(async () => {
+        try {
+            const resp: any = await invoke("system.get_units", MessageType.Request, {});
+            const payload = resp?.data ?? resp;
+            const table = payload?.units as UnitsTable | undefined | null;
+            if (!table || !table.scales) {
+                console.warn("[units] no units.json on this machine — showing backend values");
+                return;
+            }
+            const system =
+                (payload?.active_system as string | undefined) ?? table.default_system;
+            applyUnitSystem(table, system);
+        } catch (e) {
+            console.warn("[units] system.get_units failed; showing backend values", e);
+        }
+    }, [invoke, applyUnitSystem]);
+
+    /**
+     * Switch the machine's display system. Persisted server-side (GNV) so it
+     * survives a restart and so CSV export follows it; every connected HMI
+     * switches on the broadcast, with no reload.
+     */
+    const setUnitSystem = useCallback(async (system: string) => {
+        await invoke("system.set_unit_system", MessageType.Request, { system });
+        // Optimistic local switch so the operator sees it immediately; the
+        // broadcast below confirms it for every other client.
+        const table = units;
+        if (table) applyUnitSystem(table, system);
+    }, [invoke, units, applyUnitSystem]);
+
+    /**
+     * Live switch: the server broadcasts when the active system changes.
+     * Re-derives every scale and recomputes displays from raw — no reload, and
+     * nothing stored is touched.
+     */
+    useEffect(() => {
+        if (!isConnected) return;
+        const id = subscribe("system.unit_system_changed", (data: any) => {
+            const next = (data?.value?.system ?? data?.system) as string | undefined;
+            if (!next) return;
+            const table = unitsRef.current;
+            if (table && next !== activeSystemRef.current) applyUnitSystem(table, next);
+        });
+        return () => { unsubscribe(id); };
+    }, [isConnected, subscribe, unsubscribe, applyUnitSystem]);
+
+    /**
+     * Legacy per-scale server pull (pre-4.0 `acScales` + `serverTag`).
+     * Retained only for a project that has not been migrated to `units.json`;
+     * it is a no-op once `scales` is omitted from the provider.
      */
     const pullServerScales = useCallback(async () => {
         // Use actualScales to ensure we iterate over a stable object
@@ -499,7 +628,9 @@ export const AutoCoreTagProvider: React.FC<{
 
         const registerAndSubscribe = async () => {
             try {
-                // 1. Load scales first so initial values are correct
+                // 1. Load units first so initial values are already in the
+                //    operator's system rather than flashing backend values.
+                await pullUnits();
                 await pullServerScales();
 
                 // 2. Subscribe to all tags
@@ -752,6 +883,19 @@ export const AutoCoreTagProvider: React.FC<{
         [tagsByFqdn],
     );
 
+    /**
+     * Render a BACKEND value in the active system at that quantity's precision.
+     * Single formatter so a table, a chart tick and a readout never disagree.
+     */
+    const formatQuantity = useCallback(
+        (quantity: string, backendValue: number): string => {
+            const s = scaleValues[quantity];
+            if (!s || !Number.isFinite(backendValue)) return String(backendValue);
+            return formatScaled(backendValue * s.scale + (s.offset ?? 0), s);
+        },
+        [scaleValues],
+    );
+
     /**
      * Construct context value. Memoized to prevent consumers from re-rendering
      * unless actual data changes.
@@ -768,7 +912,12 @@ export const AutoCoreTagProvider: React.FC<{
             scales: scaleValues,
             updateScale,
             findTagByFqdn,
-            }), [values, rawValues, isLoading, write, tap, press, release, scaleValues, updateScale, findTagByFqdn]);
+            units,
+            activeSystem,
+            setUnitSystem,
+            formatQuantity,
+            }), [values, rawValues, isLoading, write, tap, press, release, scaleValues,
+                 updateScale, findTagByFqdn, units, activeSystem, setUnitSystem, formatQuantity]);
 
 
     return (

package/src/core/AutoCoreTagTypes.ts

@@ -174,17 +174,67 @@ export interface SubscriptionOptions {
     args?: Record<string, unknown>;
 }
 
+/** How a resolved scale's `precision` is interpreted. */
+export type PrecisionMode = "decimals" | "significant";
+
+/**
+ * One system's display treatment of one quantity, as it appears in `units.json`.
+ * Mirrors `mechutil::units::SystemScale`.
+ */
+export interface UnitSystemScale {
+    /** Display label ("mm", "lbf", "°C"). */
+    label: string;
+    /** `display = backend * scalar (+ offset)`. */
+    scalar: number;
+    /** Additive term — absolute quantities (temperature) only. */
+    offset?: number;
+    /** Digits, interpreted per `precision_mode`. */
+    precision?: number;
+    precision_mode?: PrecisionMode;
+}
+
+/** One quantity row of `units.json`. Mirrors `mechutil::units::Scale`. */
+export interface UnitScale {
+    /** The unit GM/GNV actually holds on this machine. */
+    backend: string;
+    /** `"absolute"` takes the offset; `"delta"` (default) does not. */
+    kind?: "delta" | "absolute";
+    /** system name → display treatment. Flattened in the JSON. */
+    [system: string]: unknown;
+}
+
 /**
- * Configuration for a named scale group.
- * Apply by setting `scale: "<name>"` on numeric tags.
+ * The whole `units.json` document — the single definition of units for a
+ * machine. Fetched from `system.get_units`; see `autocore-server/UNITS_PLAN.md`.
+ */
+export interface UnitsTable {
+    /** Named systems, in display order. Any names, not a fixed pair. */
+    systems: string[];
+    default_system: string;
+    /** quantity name → row. Quantities are DATA, not a fixed enum. */
+    scales: Record<string, UnitScale>;
+}
+
+/**
+ * A quantity resolved against the active system — what the UI actually renders
+ * with. Produced by the provider from `UnitsTable` + active system.
+ *
+ * `scale`/`label` keep their historical names so the provider's existing
+ * rescale-from-raw machinery is unchanged; `precision` is new and is what makes
+ * "too many decimals" configurable rather than hard-coded.
  */
 export interface ScaleConfig {
-    /** Unique name for this scale group (e.g., "position", "load") */
+    /** Quantity name this resolves (e.g., "position", "force") */
     name: string;
     /** Current scale factor — incoming values ×= scale; outgoing values /= scale */
     scale: number;
     /** Units/label for display (e.g., "mm", "in", "lbs") */
     label: string;
+    /** Additive term for absolute quantities (temperature). Default 0. */
+    offset?: number;
+    /** Display digits. */
+    precision?: number;
+    precisionMode?: PrecisionMode;
     /** Optional description for debugging/documentation */
     description?: string;
     /**
@@ -237,10 +287,22 @@ export type TagConfig<
     
 
     /**
-     * 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`
+     * The QUANTITY this tag measures — a row name in `units.json`
+     * ("position", "force", "torque", …). If present, the provider will:
+     * - Multiply incoming numbers by the active system's `scalar` (+ offset)
+     * - Divide outgoing numbers back to backend units
+     * - Render them at the active system's `precision`
+     *
+     * Quantities are data, not an enum: a machine with a channel nobody
+     * anticipated just gets a new row in `units.json`.
+     */
+    quantity?: string;
+
+    /**
+     * @deprecated Renamed to {@link quantity} in 4.0, when hand-authored
+     * `acScales` was replaced by the server's `units.json`. Still read as a
+     * fallback so a project can be migrated without its HMI going dark, but it
+     * will be removed — regenerate with `acctl codegen-tags`.
      */
     scale?: string;
 
@@ -306,6 +368,28 @@ export interface BaseContextValue<VMap extends Record<string, any>> {
     /** Current app-visible tag values (already scaled/decoded). */
     values: Partial<VMap>;
 
+    /**
+     * The machine's units table (`units.json`), or `null` when the machine has
+     * none — in which case values render in backend units.
+     */
+    units?: UnitsTable | null;
+
+    /** The display system currently in effect (e.g. "Metric"). */
+    activeSystem?: string | null;
+
+    /**
+     * Switch the machine's display system. Persisted server-side and broadcast,
+     * so every connected client switches live with no reload.
+     */
+    setUnitSystem?: (system: string) => Promise<void>;
+
+    /**
+     * Format a BACKEND value for display in the active system, honouring that
+     * quantity's label precision. Rounding is a rendering step only — this never
+     * changes a stored value.
+     */
+    formatQuantity?: (quantity: string, backendValue: number) => string;
+
     /** Last raw (controller) values, as received (pre-scale, pre-codec). */
     rawValues: Record<string, unknown>;
 

package/src/core/formatScaled.ts

@@ -0,0 +1,72 @@
+/*
+ * Copyright (C) 2026 Automated Design Corp. All Rights Reserved.
+ *
+ * Number formatting for a resolved unit scale — the single place display
+ * precision is applied, so a table cell, a chart tick and a live readout can
+ * never disagree about how many digits a value has.
+ *
+ * Deliberately mirrors `mechutil::units::format_value` (Rust) so a value
+ * rendered in the HMI and the same value rendered into a server-side CSV export
+ * look identical. If you change one, change the other.
+ *
+ * Rounding here is a RENDERING step. It is never applied on the way into GM,
+ * GNV or any stored file — see autocore-server/UNITS_PLAN.md §6.1.
+ */
+
+import type { PrecisionMode, ScaleConfig } from "./AutoCoreTagTypes";
+
+/** Digits used when a scale declares no precision. */
+export const DEFAULT_PRECISION = 3;
+
+/**
+ * Format an already-converted (display-unit) value.
+ *
+ * Precision is a **cap, not padding**: a clean 0/1/2 axis stays "0", "1", "2"
+ * rather than becoming "0.000", which is what made fixed `toFixed` unusable for
+ * chart ticks.
+ */
+export function formatValue(
+    value: number,
+    precision: number = DEFAULT_PRECISION,
+    mode: PrecisionMode = "decimals",
+): string {
+    if (!Number.isFinite(value)) return String(value);
+
+    let s: string;
+    if (mode === "significant") {
+        const digits = Math.max(1, precision);
+        if (value === 0) {
+            s = "0";
+        } else {
+            // Track magnitude so a channel spanning 0.001–5000 reads sensibly at
+            // both ends, which fixed decimals cannot do.
+            const exp = Math.floor(Math.log10(Math.abs(value)));
+            const decimals = Math.max(0, digits - 1 - exp);
+            s = value.toFixed(Math.min(decimals, 100));
+        }
+    } else {
+        s = value.toFixed(Math.max(0, Math.min(precision, 100)));
+    }
+
+    if (s.includes(".")) {
+        s = s.replace(/0+$/, "").replace(/\.$/, "");
+        if (s === "" || s === "-") s = "0";
+    }
+    return s;
+}
+
+/** Format a display-unit value using a resolved scale's precision settings. */
+export function formatScaled(displayValue: number, scale?: ScaleConfig): string {
+    return formatValue(
+        displayValue,
+        scale?.precision ?? DEFAULT_PRECISION,
+        scale?.precisionMode ?? "decimals",
+    );
+}
+
+/** `"12.5 mm"` — value plus the active system's label, when there is one. */
+export function formatScaledWithLabel(displayValue: number, scale?: ScaleConfig): string {
+    const text = formatScaled(displayValue, scale);
+    const label = scale?.label?.trim();
+    return label ? `${text} ${label}` : text;
+}

package/src/hooks/useAutoCoreTag.ts

@@ -14,7 +14,7 @@
  */
 
 import { useCallback, useContext, useMemo } from "react";
-import type { BaseContextValue, TagConfig, TagValueMap } from "../core/AutoCoreTagTypes";
+import type { BaseContextValue, ScaleConfig, TagConfig, TagValueMap } from "../core/AutoCoreTagTypes";
 
 export function makeAutoCoreTagHooks<Spec extends readonly TagConfig[]>(
     Context: React.Context<BaseContextValue<TagValueMap<Spec>>>,
@@ -96,12 +96,60 @@ export function makeAutoCoreTagHooks<Spec extends readonly TagConfig[]>(
 
     /**
      * Access scale configurations and update functions.
+     *
+     * `getScale` NEVER returns undefined. Callers destructure it directly
+     * (`const { label } = getScale("load")`), so handing back undefined for an
+     * unknown group throws inside render and white-screens the whole HMI — on a
+     * machine, that is the operator losing the screen over a missing unit label.
+     * An unknown group yields an identity scale instead: no conversion, empty
+     * label, which is the same thing the provider did before units.json existed.
      */
     const useScales = () => {
         const { scales, updateScale } = useContext(Context);
-        const getScale = useCallback((scaleName: string) => scales[scaleName], [scales]);
+        const getScale = useCallback(
+            (scaleName: string): ScaleConfig =>
+                scales[scaleName] ?? { name: scaleName, scale: 1, label: "" },
+            [scales],
+        );
         return { scales, updateScale, getScale } as const;
     };
 
-    return { useAutoCoreTag, useAutoCoreTags, useAutoCoreSelect, useScales } as const;
+    /**
+     * Access the machine's units table, the active display system, the live
+     * switch, and the shared formatter.
+     *
+     * `format(quantity, backendValue)` is the one place display precision is
+     * applied — use it rather than `toFixed` so a readout, a table cell and a
+     * chart tick can never disagree. It takes a BACKEND value; conversion to the
+     * active system happens inside.
+     */
+    const useUnits = () => {
+        const { units, activeSystem, setUnitSystem, formatQuantity, scales } =
+            useContext(Context);
+        const label = useCallback(
+            (quantity: string) => scales[quantity]?.label ?? "",
+            [scales],
+        );
+        const format = useCallback(
+            (quantity: string, backendValue: number) =>
+                formatQuantity ? formatQuantity(quantity, backendValue) : String(backendValue),
+            [formatQuantity],
+        );
+        return {
+            units: units ?? null,
+            activeSystem: activeSystem ?? null,
+            systems: units?.systems ?? [],
+            setUnitSystem,
+            label,
+            format,
+        } as const;
+    };
+
+    return {
+        useAutoCoreTag,
+        useAutoCoreTags,
+        useAutoCoreSelect,
+        useScales,
+        useUnits,
+    } as const;
 }

package/todo.md

@@ -1,5 +1,11 @@
 # TODO
 
+## 3.5.0 — Units & scales
+<!-- NOT 4.0: that is a separate in-progress branch. -->
+- [ ] Replace `ScaleConfig` / `acScales` with quantity-based derivation from the
+      project `units` block + GNV `active_unit_system`. Design plan:
+      **`autocore-server/UNITS_PLAN.md`** (§5.3 is the autocore-react section).
+
 ## Integration
 - [x] Hub class to route to and from the back end
 - -[x] The Hub should also be the dispatcher. I can't think of a reason they should be separate.