@adcops/autocore-react 3.3.124 → 3.5.5

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/TestFieldDialog.tsx

@@ -8,6 +8,10 @@ import { Checkbox } from 'primereact/checkbox';
 import { InputNumber } from 'primereact/inputnumber';
 import { FormRow } from '../../forms/FormRow';
 import type { TestField, AggFn, AggFrom, AggScope, AggregateSpec } from '../types';
+// One home for bound parsing/formatting — shared with the operator-facing
+// form so the editor and the runtime can never disagree on what a bound is.
+import { boundText, parseBound, boundInvalid } from '../../tis/TestFieldRow';
+
 
 const FIELD_TYPES: { label: string; value: string }[] = [
     { label: 'string', value: 'string' },
@@ -116,6 +120,13 @@ export const TestFieldDialog: React.FC<TestFieldDialogProps> = ({
         if (typeof f.min === 'number' && typeof f.max === 'number' && f.min > f.max) {
             return `Min (${f.min}) cannot be greater than Max (${f.max}).`;
         }
+        // A bound that is neither a number nor a well-formed token resolves to
+        // NO bound at run time — silently unlimited. Refuse the save instead.
+        for (const which of ['min', 'max'] as const) {
+            if (boundInvalid(f[which])) {
+                return `${which === 'min' ? 'Min' : 'Max'} must be a number or an FQDN token like \${gm.some_var} — "${f[which]}" is neither.`;
+            }
+        }
         if (f.aggregate && f.aggregate.fn !== 'count' && !f.aggregate.of?.trim()) {
             return `Aggregate "${f.aggregate.fn}" needs a target field (the field to ${f.aggregate.fn} across tests).`;
         }
@@ -241,26 +252,26 @@ export const TestFieldDialog: React.FC<TestFieldDialogProps> = ({
                     maxFractionDigits={9}
                 />
             </FormRow>
-            <FormRow label="Min" hint="Optional lower bound the operator can enter (display units). Blank = no minimum.">
-                <InputNumber
-                    value={draft.min ?? null}
-                    onValueChange={(e) =>
-                        setDraft({ ...draft, min: typeof e.value === 'number' ? e.value : undefined })
-                    }
-                    mode="decimal"
-                    minFractionDigits={0}
-                    maxFractionDigits={9}
+            <FormRow
+                label="Min"
+                hint="Optional lower bound the operator can enter (display units). Blank = no minimum. Or bind it to the machine with an FQDN token like ${gm.press_force_min_n} — for a bound that moves, e.g. a load-cell force ceiling."
+            >
+                <InputText
+                    value={boundText(draft.min)}
+                    onChange={(e) => setDraft({ ...draft, min: parseBound(e.target.value) })}
+                    className={boundInvalid(draft.min) ? 'p-invalid' : ''}
+                    placeholder="number or ${gm.…}"
                 />
             </FormRow>
-            <FormRow label="Max" hint="Optional upper bound the operator can enter (display units). Blank = no maximum.">
-                <InputNumber
-                    value={draft.max ?? null}
-                    onValueChange={(e) =>
-                        setDraft({ ...draft, max: typeof e.value === 'number' ? e.value : undefined })
-                    }
-                    mode="decimal"
-                    minFractionDigits={0}
-                    maxFractionDigits={9}
+            <FormRow
+                label="Max"
+                hint="Optional upper bound the operator can enter (display units). Blank = no maximum. Or bind it to the machine with an FQDN token like ${gm.press_force_max_n}."
+            >
+                <InputText
+                    value={boundText(draft.max)}
+                    onChange={(e) => setDraft({ ...draft, max: parseBound(e.target.value) })}
+                    className={boundInvalid(draft.max) ? 'p-invalid' : ''}
+                    placeholder="number or ${gm.…}"
                 />
             </FormRow>
             <FormRow label="Default" hint="Applied every time the method loads (operator can override). A literal (display units) like 5, or an FQDN token like ${gm.safe_speed} that snapshots that value on load.">

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

@@ -25,8 +25,12 @@ export interface TestField {
     /** Optional inclusive bounds for the operator's numeric value, authored
      *  in display units (same convention as `default`/`scale`). The form's
      *  numeric input rejects values outside `[min, max]`. */
-    min?: number;
-    max?: number;
+    /** Inclusive bounds. A number is in display units; a string is an FQDN
+     *  token `"${gm.<var>}"` resolved live from the machine — see
+     *  `TestFieldRow.resolveBound`. The editor must preserve a token it does
+     *  not understand rather than coercing it to a number. */
+    min?: number | string;
+    max?: number | string;
     /** results_fields only: a cross-test rollup derived server-side over the
      *  non-excluded runs sharing this test's sample_id. When set, the field
      *  is NOT supplied by the analysis script — the server computes it. */

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;
+}