@reekon-tools/boldr-utils 1.8.5 → 1.9.0

package/dist/calculator/expressionUnits.d.ts

@@ -0,0 +1,84 @@
+import { type MathNode } from 'mathjs';
+import type { CalculatorEquation, CalculatorField } from './schema.js';
+import { type CalculatorUnit, type FieldDimension } from './units.js';
+/** Constants mathjs resolves without a scope entry. */
+export declare const MATHJS_CONSTANTS: Set<string>;
+export type ParseResult = {
+    ok: true;
+    node: MathNode;
+} | {
+    ok: false;
+    error: string;
+};
+/** Shared mathjs parse — the one place expression text becomes a tree. */
+export declare const parseExpression: (expression: string) => ParseResult;
+/**
+ * Bases whose values are ALREADY canonical, so an equation in them needs no
+ * `resultUnit` at all (the pre-unit-annotation form: a canonical scope in
+ * µm / µm² / µm³ / degrees).
+ */
+export declare const CANONICAL_BASES: Set<string>;
+export type InferenceFailureReason = 
+/** The expression does not parse. */
+'unparseable'
+/** A symbol is neither a mapped variable nor a mathjs constant. */
+ | 'unknown-symbol'
+/** A function or operator whose unit behaviour we don't model. */
+ | 'unsupported-operation'
+/** Dimensioned terms added or compared against a different dimension. */
+ | 'inconsistent-terms'
+/** A real exponent, but one this unit vocabulary can't name (µm⁴, 1/ft). */
+ | 'unnameable-dimension';
+export interface InferredExpressionUnit {
+    /** The dimension of the expression's raw value. */
+    dimension: FieldDimension;
+    /**
+     * The unit the raw value carries, or null when no single unit names it
+     * (mixed bases, or a canonical/yard/liter base with no entry).
+     */
+    unit: CalculatorUnit | null;
+    /** Distinct base units among the variables carrying that dimension. */
+    bases: string[];
+}
+export type ExpressionUnitInference = ({
+    ok: true;
+} & InferredExpressionUnit) | {
+    ok: false;
+    reason: InferenceFailureReason;
+};
+/**
+ * The dimension and unit of an equation's raw expression value — what the
+ * number means BEFORE `resultUnit` is applied.
+ */
+export declare const inferExpressionUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableUnits">) => ExpressionUnitInference;
+/**
+ * True when an expression's raw value is already canonical, so omitting
+ * `resultUnit` is correct rather than a 25400× mistake. Only the
+ * no-variable-units form (and dimensionless results) qualifies.
+ */
+export declare const producesCanonicalValue: (inferred: InferredExpressionUnit) => boolean;
+/** Same physical unit, ignoring display form: `in` ≡ `in_frac`, `ft` ≡ `ft_in_frac`. */
+export declare const isEquivalentUnit: (a: CalculatorUnit, b: CalculatorUnit) => boolean;
+/**
+ * How far off a value is when it carries `actual` but was declared as
+ * `declared` — 144 for in² labelled ft². Used to make validation messages
+ * say what the author will actually see.
+ */
+export declare const unitScaleRatio: (declared: CalculatorUnit, actual: CalculatorUnit) => number;
+/**
+ * The `resultUnit` an equation should carry, or null when it should be omitted
+ * (dimensionless or already-canonical result) or cannot be derived. An
+ * existing equivalent unit is preserved so `in_frac` isn't churned to `in`.
+ */
+export declare const deriveResultUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableUnits" | "resultUnit">) => CalculatorUnit | null;
+/**
+ * Bring an equation's unit annotations back in line with the fields it
+ * references. Field edits (a dimension switch, a kind change, a deletion) are
+ * written independently of equations, so a stale `variableUnits` entry or
+ * `resultUnit` would otherwise keep converting against a unit the field no
+ * longer uses — the failure mode this whole module exists to prevent.
+ */
+export declare const reconcileEquationUnits: (fields: readonly CalculatorField[], equations: readonly CalculatorEquation[]) => {
+    equations: CalculatorEquation[];
+    changed: boolean;
+};

package/dist/calculator/expressionUnits.js

@@ -0,0 +1,439 @@
+import { create, all } from 'mathjs';
+import { Units } from '../types/firestore.js';
+import { fieldDefaultUnit, fieldDimension } from './schema.js';
+import { CALCULATOR_UNIT_INFO, toCanonical, unitDimension, } from './units.js';
+const math = create(all);
+// ---------------------------------------------------------------------------
+// Expression unit inference.
+//
+// An equation's `variableUnits` / `resultUnit` (schema.ts) evaluate it in the
+// author's display units: each variable is converted OUT of canonical before
+// entering the scope, and the raw result is converted back FROM `resultUnit`.
+// Nothing in the evaluator checks that `resultUnit` is the unit the expression
+// actually produces — it is an assertion, not a conversion. Assert wrongly and
+// the answer is silently off by a scale factor: three inch-valued variables
+// multiplied yield in³, so declaring the result `cu_ft` overstates it 1728×,
+// with every unit label on screen still reading correctly.
+//
+// This module recovers the missing information by propagating unit exponents
+// through the expression tree. Each variable contributes its dimension's
+// exponent (length 1, area 2, volume 3), `*` adds them, `/` subtracts, `sqrt`
+// halves, and the result's exponent names the dimension. Pair that with the
+// base unit the variables share and the correct `resultUnit` is fully
+// determined — which is why the authoring UI derives it rather than asking,
+// and why validation can flag the scale errors it otherwise cannot see.
+//
+// Inference is deliberately conservative. Anything it cannot reason about —
+// unknown functions, non-integer powers, symbols with no mapping — returns
+// `ok: false` so callers fall back to prior behaviour instead of reporting a
+// false positive on valid math.
+// ---------------------------------------------------------------------------
+/** Constants mathjs resolves without a scope entry. */
+export const MATHJS_CONSTANTS = new Set([
+    'pi',
+    'PI',
+    'e',
+    'E',
+    'tau',
+    'phi',
+    'i',
+    'true',
+    'false',
+    'Infinity',
+    'NaN',
+    'null',
+]);
+/** Shared mathjs parse — the one place expression text becomes a tree. */
+export const parseExpression = (expression) => {
+    try {
+        return { ok: true, node: math.parse(expression) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
+// The math.js base token a unit reduces to: 'sq_ft' -> 'ft', 'in_frac' -> 'in',
+// 'liter' -> 'L'. Two units share a base exactly when they are the same
+// physical unit at different exponents, which is what makes a result unit
+// nameable.
+const baseUnitOf = (unit) => (CALCULATOR_UNIT_INFO[unit]?.mathUnit ?? '').split('^')[0];
+/**
+ * Bases whose values are ALREADY canonical, so an equation in them needs no
+ * `resultUnit` at all (the pre-unit-annotation form: a canonical scope in
+ * µm / µm² / µm³ / degrees).
+ */
+export const CANONICAL_BASES = new Set(['um', 'deg']);
+const CANONICAL_LENGTH_BASE = 'um';
+const CANONICAL_ANGLE_BASE = 'deg';
+// Base + length exponent -> the unit that names it. Yards have no length
+// entry (the Units enum has no yard) and liters/gallons no length base at all,
+// so both simply fail to name a unit rather than guessing.
+const UNIT_BY_BASE = {
+    mm: { 1: Units.Millimeters, 2: 'sq_mm', 3: 'cu_mm' },
+    cm: { 1: Units.Centimeters, 2: 'sq_cm', 3: 'cu_cm' },
+    m: { 1: Units.Meters, 2: 'sq_m', 3: 'cu_m' },
+    in: { 1: Units.Inches, 2: 'sq_in', 3: 'cu_in' },
+    ft: { 1: Units.Feet, 2: 'sq_ft', 3: 'cu_ft' },
+    yd: { 2: 'sq_yd', 3: 'cu_yd' },
+};
+const SCALAR = { len: 0, ang: 0 };
+const isScalar = (e) => e.len === 0 && e.ang === 0;
+const sameExponents = (a, b) => a.len === b.len && a.ang === b.ang;
+const EXPONENTS_BY_DIMENSION = {
+    none: SCALAR,
+    length: { len: 1, ang: 0 },
+    area: { len: 2, ang: 0 },
+    volume: { len: 3, ang: 0 },
+    angle: { len: 0, ang: 1 },
+};
+// Functions that return their arguments' dimension (scalar arguments — a digit
+// count, a clamp bound — are ignored).
+const DIMENSION_PRESERVING_FNS = new Set([
+    'abs',
+    'min',
+    'max',
+    'mean',
+    'median',
+    'sum',
+    'round',
+    'floor',
+    'ceil',
+    'fix',
+    'mod',
+]);
+// Trig works in DEGREES here (evaluate.ts overrides mathjs), so an inverse
+// function's result is an angle in the canonical angle unit.
+const DIRECT_TRIG_FNS = new Set(['sin', 'cos', 'tan', 'sec', 'csc', 'cot']);
+const INVERSE_TRIG_FNS = new Set(['asin', 'acos', 'atan', 'atan2']);
+// Functions that require and return plain numbers.
+const SCALAR_FNS = new Set(['log', 'log10', 'log2', 'exp', 'sign']);
+/**
+ * The dimension and unit of an equation's raw expression value — what the
+ * number means BEFORE `resultUnit` is applied.
+ */
+export const inferExpressionUnit = (fields, equation) => {
+    const parsed = parseExpression(equation.expression);
+    if (!parsed.ok)
+        return { ok: false, reason: 'unparseable' };
+    const fieldById = new Map(fields.map((f) => [f.id, f]));
+    const lengthBases = new Set();
+    const angleBases = new Set();
+    let failure = null;
+    const fail = (reason) => {
+        failure ?? (failure = reason);
+        return null;
+    };
+    const noteBases = (exponents, base) => {
+        if (exponents.len !== 0)
+            lengthBases.add(base);
+        if (exponents.ang !== 0)
+            angleBases.add(base);
+    };
+    const resolveSymbol = (name) => {
+        const unit = equation.variableUnits?.[name];
+        if (unit != null) {
+            const exponents = EXPONENTS_BY_DIMENSION[unitDimension(unit)];
+            noteBases(exponents, baseUnitOf(unit));
+            return exponents;
+        }
+        const fieldId = equation.variableToFieldId[name];
+        const field = fieldId != null ? fieldById.get(fieldId) : undefined;
+        if (field) {
+            // No variable unit: the value enters the scope canonically (units.ts).
+            const dimension = fieldDimension(field);
+            const exponents = EXPONENTS_BY_DIMENSION[dimension];
+            noteBases(exponents, dimension === 'angle' ? CANONICAL_ANGLE_BASE : CANONICAL_LENGTH_BASE);
+            return exponents;
+        }
+        // Unmapped: fine if mathjs resolves it, otherwise validation's
+        // unmapped-symbol check owns the error and we just decline to infer.
+        return MATHJS_CONSTANTS.has(name) ? SCALAR : fail('unknown-symbol');
+    };
+    // Scale a term's exponents by a constant power, e.g. `^2` or `sqrt`. Only
+    // whole-number results are nameable: sqrt of an area is a length, sqrt of a
+    // length is not anything we can express.
+    const scaled = (exponents, factor) => {
+        const len = exponents.len * factor;
+        const ang = exponents.ang * factor;
+        return Number.isInteger(len) && Number.isInteger(ang)
+            ? { len, ang }
+            : fail('unnameable-dimension');
+    };
+    const constantValue = (node) => {
+        if (node.type === 'ParenthesisNode' && node.content) {
+            return constantValue(node.content);
+        }
+        if (node.type === 'ConstantNode' && typeof node.value === 'number') {
+            return node.value;
+        }
+        if (node.type === 'OperatorNode' && node.fn === 'unaryMinus') {
+            const inner = node.args?.[0] ? constantValue(node.args[0]) : null;
+            return inner == null ? null : -inner;
+        }
+        return null;
+    };
+    const walk = (node) => {
+        switch (node.type) {
+            case 'ConstantNode':
+                return SCALAR;
+            case 'ParenthesisNode':
+                return node.content
+                    ? walk(node.content)
+                    : fail('unsupported-operation');
+            case 'SymbolNode':
+                return node.name ? resolveSymbol(node.name) : fail('unknown-symbol');
+            case 'OperatorNode':
+                return walkOperator(node);
+            case 'FunctionNode':
+                return walkFunction(node);
+            default:
+                // ConditionalNode, AssignmentNode, ranges, matrices, ...
+                return fail('unsupported-operation');
+        }
+    };
+    const walkArgs = (node) => {
+        const args = node.args ?? [];
+        const out = [];
+        for (const arg of args) {
+            const exponents = walk(arg);
+            if (!exponents)
+                return null;
+            out.push(exponents);
+        }
+        return out;
+    };
+    const walkOperator = (node) => {
+        const args = walkArgs(node);
+        if (!args)
+            return null;
+        switch (node.fn) {
+            case 'multiply':
+                return args.reduce((acc, e) => ({ len: acc.len + e.len, ang: acc.ang + e.ang }), SCALAR);
+            case 'divide':
+                return args.length === 2
+                    ? {
+                        len: args[0].len - args[1].len,
+                        ang: args[0].ang - args[1].ang,
+                    }
+                    : fail('unsupported-operation');
+            case 'add':
+            case 'subtract': {
+                // A bare literal added to a dimensioned term adopts its unit — that is
+                // the whole point of evaluating in display units ("wall + 2 inches").
+                // Two DIFFERENT dimensions added is an author error.
+                const dimensioned = args.filter((e) => !isScalar(e));
+                if (dimensioned.length === 0)
+                    return SCALAR;
+                return dimensioned.every((e) => sameExponents(e, dimensioned[0]))
+                    ? dimensioned[0]
+                    : fail('inconsistent-terms');
+            }
+            case 'unaryMinus':
+            case 'unaryPlus':
+                return args[0] ?? fail('unsupported-operation');
+            case 'pow': {
+                if (args.length !== 2)
+                    return fail('unsupported-operation');
+                if (isScalar(args[0]))
+                    return SCALAR;
+                const exponent = node.args?.[1] ? constantValue(node.args[1]) : null;
+                return exponent == null
+                    ? fail('unsupported-operation')
+                    : scaled(args[0], exponent);
+            }
+            case 'mod':
+                return args[0] ?? fail('unsupported-operation');
+            default:
+                // Comparisons, logic, bit ops — not meaningful on dimensioned values.
+                return fail('unsupported-operation');
+        }
+    };
+    const walkFunction = (node) => {
+        const args = walkArgs(node);
+        if (!args)
+            return null;
+        const name = typeof node.fn === 'string' ? node.fn : node.fn?.name;
+        if (!name)
+            return fail('unsupported-operation');
+        if (name === 'sqrt')
+            return scaled(args[0] ?? SCALAR, 0.5);
+        if (name === 'cbrt')
+            return scaled(args[0] ?? SCALAR, 1 / 3);
+        if (name === 'nthRoot') {
+            const root = node.args?.[1] ? constantValue(node.args[1]) : 2;
+            return root == null || root === 0
+                ? fail('unsupported-operation')
+                : scaled(args[0] ?? SCALAR, 1 / root);
+        }
+        if (DIMENSION_PRESERVING_FNS.has(name)) {
+            const dimensioned = args.filter((e) => !isScalar(e));
+            if (dimensioned.length === 0)
+                return SCALAR;
+            return dimensioned.every((e) => sameExponents(e, dimensioned[0]))
+                ? dimensioned[0]
+                : fail('inconsistent-terms');
+        }
+        if (DIRECT_TRIG_FNS.has(name)) {
+            // Degrees in, plain ratio out.
+            const arg = args[0] ?? SCALAR;
+            return arg.len === 0 && arg.ang <= 1
+                ? SCALAR
+                : fail('inconsistent-terms');
+        }
+        if (INVERSE_TRIG_FNS.has(name)) {
+            // atan2's two arguments cancel, so they only need to match.
+            if (!args.every((e) => sameExponents(e, args[0] ?? SCALAR))) {
+                return fail('inconsistent-terms');
+            }
+            angleBases.add(CANONICAL_ANGLE_BASE);
+            return { len: 0, ang: 1 };
+        }
+        if (SCALAR_FNS.has(name)) {
+            return args.every(isScalar) ? SCALAR : fail('inconsistent-terms');
+        }
+        return fail('unsupported-operation');
+    };
+    const exponents = walk(parsed.node);
+    if (!exponents) {
+        return { ok: false, reason: failure ?? 'unsupported-operation' };
+    }
+    if (exponents.ang !== 0) {
+        // Angles don't combine with lengths into anything nameable (a length·deg
+        // has no unit here), and neither does deg².
+        if (exponents.len !== 0 || exponents.ang !== 1) {
+            return { ok: false, reason: 'unnameable-dimension' };
+        }
+        const bases = [...angleBases];
+        return {
+            ok: true,
+            dimension: 'angle',
+            unit: bases.length === 1 ? bases[0] : null,
+            bases,
+        };
+    }
+    if (exponents.len === 0) {
+        return { ok: true, dimension: 'none', unit: null, bases: [] };
+    }
+    if (exponents.len < 1 || exponents.len > 3) {
+        return { ok: false, reason: 'unnameable-dimension' };
+    }
+    const dimension = exponents.len === 1 ? 'length' : exponents.len === 2 ? 'area' : 'volume';
+    const bases = [...lengthBases];
+    return {
+        ok: true,
+        dimension,
+        unit: bases.length === 1
+            ? (UNIT_BY_BASE[bases[0]]?.[exponents.len] ?? null)
+            : null,
+        bases,
+    };
+};
+/**
+ * True when an expression's raw value is already canonical, so omitting
+ * `resultUnit` is correct rather than a 25400× mistake. Only the
+ * no-variable-units form (and dimensionless results) qualifies.
+ */
+export const producesCanonicalValue = (inferred) => inferred.dimension === 'none' ||
+    (inferred.bases.length > 0 &&
+        inferred.bases.every((b) => CANONICAL_BASES.has(b)));
+/** Same physical unit, ignoring display form: `in` ≡ `in_frac`, `ft` ≡ `ft_in_frac`. */
+export const isEquivalentUnit = (a, b) => a === b ||
+    (unitDimension(a) === unitDimension(b) && baseUnitOf(a) === baseUnitOf(b));
+/**
+ * How far off a value is when it carries `actual` but was declared as
+ * `declared` — 144 for in² labelled ft². Used to make validation messages
+ * say what the author will actually see.
+ */
+export const unitScaleRatio = (declared, actual) => toCanonical(1, declared) / toCanonical(1, actual);
+/**
+ * The `resultUnit` an equation should carry, or null when it should be omitted
+ * (dimensionless or already-canonical result) or cannot be derived. An
+ * existing equivalent unit is preserved so `in_frac` isn't churned to `in`.
+ */
+export const deriveResultUnit = (fields, equation) => {
+    const inferred = inferExpressionUnit(fields, equation);
+    if (!inferred.ok || inferred.unit == null)
+        return null;
+    if (producesCanonicalValue(inferred))
+        return null;
+    const current = equation.resultUnit;
+    return current != null && isEquivalentUnit(current, inferred.unit)
+        ? current
+        : inferred.unit;
+};
+// Rebuild an equation without a key, since Firestore rejects `undefined`.
+const withoutResultUnit = (equation) => {
+    const { resultUnit: _dropped, ...rest } = equation;
+    return rest;
+};
+/**
+ * Bring an equation's unit annotations back in line with the fields it
+ * references. Field edits (a dimension switch, a kind change, a deletion) are
+ * written independently of equations, so a stale `variableUnits` entry or
+ * `resultUnit` would otherwise keep converting against a unit the field no
+ * longer uses — the failure mode this whole module exists to prevent.
+ */
+export const reconcileEquationUnits = (fields, equations) => {
+    const fieldById = new Map(fields.map((f) => [f.id, f]));
+    let changed = false;
+    const next = equations.map((equation) => {
+        let repaired = equation;
+        // 1. Variable units must match the dimension of the field they annotate.
+        if (equation.variableUnits) {
+            const variableUnits = {};
+            let unitsChanged = false;
+            for (const [variable, unit] of Object.entries(equation.variableUnits)) {
+                const field = fieldById.get(equation.variableToFieldId[variable] ?? '');
+                if (!field) {
+                    unitsChanged = true; // variable or field is gone
+                    continue;
+                }
+                if (unitDimension(unit) === fieldDimension(field)) {
+                    variableUnits[variable] = unit;
+                    continue;
+                }
+                const replacement = fieldDefaultUnit(field);
+                unitsChanged = true;
+                if (replacement)
+                    variableUnits[variable] = replacement;
+            }
+            if (unitsChanged) {
+                repaired =
+                    Object.keys(variableUnits).length > 0
+                        ? { ...repaired, variableUnits }
+                        : (() => {
+                            const { variableUnits: _dropped, ...rest } = repaired;
+                            return rest;
+                        })();
+            }
+        }
+        // 2. The result unit follows from the repaired variable units.
+        const target = fieldById.get(equation.targetFieldId);
+        const targetDimension = target ? fieldDimension(target) : 'none';
+        if (targetDimension === 'none') {
+            if (repaired.resultUnit != null)
+                repaired = withoutResultUnit(repaired);
+        }
+        else {
+            const derived = deriveResultUnit(fields, repaired);
+            if (derived != null) {
+                if (repaired.resultUnit !== derived) {
+                    repaired = { ...repaired, resultUnit: derived };
+                }
+            }
+            else if (repaired.resultUnit != null &&
+                unitDimension(repaired.resultUnit) !== targetDimension) {
+                // Not derivable AND not even the right dimension: drop it rather than
+                // keep converting a length factor into an area field.
+                repaired = withoutResultUnit(repaired);
+            }
+        }
+        if (repaired !== equation)
+            changed = true;
+        return repaired;
+    });
+    return { equations: next, changed };
+};

package/dist/calculator/index.d.ts

@@ -1,6 +1,7 @@
 export * from './schema.js';
 export * from './categories.js';
 export * from './units.js';
+export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';
 export * from './instance.js';

package/dist/calculator/index.js

@@ -5,6 +5,7 @@
 export * from './schema.js';
 export * from './categories.js';
 export * from './units.js';
+export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';
 export * from './instance.js';

package/dist/calculator/schema.d.ts

@@ -171,6 +171,12 @@ export declare const findEquation: (definition: Pick<CalculatorDefinition, "equa
 export declare const equationForField: (definition: Pick<CalculatorDefinition, "equations">, fieldId: string) => CalculatorEquation | undefined;
 /** The dimension a field's numeric value carries. */
 export declare const fieldDimension: (field: CalculatorField) => FieldDimension;
+/**
+ * The unit a field's value is entered and displayed in, or null for fields
+ * that carry no unit. Also the unit an equation referencing the field starts
+ * out annotated with.
+ */
+export declare const fieldDefaultUnit: (field: CalculatorField) => CalculatorUnit | null;
 /** Fields whose value participates in equations as a number. */
 export declare const isNumericFieldKind: (kind: CalculatorFieldKind) => kind is ColumnType.Number | ColumnType.Measurement | ColumnType.Angle | ColumnType.ConversionTable;
 /** Field kinds an equation may target (compute into). */

package/dist/calculator/schema.js

@@ -59,6 +59,21 @@ export const fieldDimension = (field) => {
             return 'none';
     }
 };
+/**
+ * The unit a field's value is entered and displayed in, or null for fields
+ * that carry no unit. Also the unit an equation referencing the field starts
+ * out annotated with.
+ */
+export const fieldDefaultUnit = (field) => {
+    switch (field.kind) {
+        case ColumnType.Measurement:
+            return field.unit.defaultUnit;
+        case ColumnType.Angle:
+            return field.angleUnit ?? 'deg';
+        default:
+            return null;
+    }
+};
 /** Fields whose value participates in equations as a number. */
 export const isNumericFieldKind = (kind) => kind === ColumnType.Number ||
     kind === ColumnType.Measurement ||

package/dist/calculator/validate.d.ts

@@ -184,8 +184,16 @@ export interface ValidationResult {
     ok: boolean;
     issues: ValidationIssue[];
 }
-/** Free variables of an expression (function names and constants excluded). */
-export declare const expressionSymbols: (expression: string) => {
+/**
+ * Free variables of an expression (function names and constants excluded).
+ *
+ * `knownVariables` are treated as variables even when mathjs would resolve
+ * them as constants: the authoring UI names variables A, B, C… and `E` is
+ * Euler's number, so without this a mapped `E` reads as a constant and gets
+ * reported as an unused variable. Evaluation is unaffected — a scope entry
+ * shadows the constant — so this only realigns validation with reality.
+ */
+export declare const expressionSymbols: (expression: string, knownVariables?: Iterable<string>) => {
     ok: true;
     symbols: string[];
 } | {

package/dist/calculator/validate.js

@@ -1,10 +1,9 @@
 import { z } from 'zod';
-import { create, all } from 'mathjs';
 import { ColumnType, DecimalTolerance, FractionalTolerance, } from '../types/firestore.js';
 import { CALCULATOR_SCHEMA_VERSION, equationForField, fieldDimension, isEquationTargetKind, isNumericFieldKind, } from './schema.js';
-import { CALCULATOR_UNIT_INFO, unitDimension } from './units.js';
+import { CALCULATOR_UNIT_INFO, unitDimension, } from './units.js';
+import { MATHJS_CONSTANTS, inferExpressionUnit, isEquivalentUnit, parseExpression, producesCanonicalValue, unitScaleRatio, } from './expressionUnits.js';
 import { isCalculatorCategoryId } from './categories.js';
-const math = create(all);
 // ---------------------------------------------------------------------------
 // Definition validation: zod for structure, plus the cross-field invariants
 // zod can't express (reference resolution, cycles, solve wiring). Callable
@@ -129,45 +128,43 @@ export const calculatorDefinitionSchema = z.object({
     createdAt: z.unknown().optional(),
     updatedAt: z.unknown().optional(),
 });
-// Constants mathjs resolves without a scope entry.
-const KNOWN_SYMBOLS = new Set([
-    'pi',
-    'PI',
-    'e',
-    'E',
-    'tau',
-    'phi',
-    'i',
-    'true',
-    'false',
-    'Infinity',
-    'NaN',
-    'null',
-]);
-/** Free variables of an expression (function names and constants excluded). */
-export const expressionSymbols = (expression) => {
-    try {
-        const node = math.parse(expression);
-        const symbols = new Set();
-        node.traverse((n, path, parent) => {
-            const sym = n;
-            const par = parent;
-            if (sym.isSymbolNode &&
-                sym.name &&
-                !(par?.isFunctionNode && path === 'fn') &&
-                !KNOWN_SYMBOLS.has(sym.name)) {
-                symbols.add(sym.name);
-            }
-        });
-        return { ok: true, symbols: [...symbols] };
-    }
-    catch (err) {
-        return {
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
+/**
+ * Free variables of an expression (function names and constants excluded).
+ *
+ * `knownVariables` are treated as variables even when mathjs would resolve
+ * them as constants: the authoring UI names variables A, B, C… and `E` is
+ * Euler's number, so without this a mapped `E` reads as a constant and gets
+ * reported as an unused variable. Evaluation is unaffected — a scope entry
+ * shadows the constant — so this only realigns validation with reality.
+ */
+export const expressionSymbols = (expression, knownVariables) => {
+    const parsed = parseExpression(expression);
+    if (!parsed.ok)
+        return { ok: false, error: parsed.error };
+    const known = new Set(knownVariables ?? []);
+    const symbols = new Set();
+    parsed.node.traverse((n, path, parent) => {
+        const sym = n;
+        const par = parent;
+        if (sym.isSymbolNode &&
+            sym.name &&
+            !(par?.isFunctionNode && path === 'fn') &&
+            (!MATHJS_CONSTANTS.has(sym.name) || known.has(sym.name))) {
+            symbols.add(sym.name);
+        }
+    });
+    return { ok: true, symbols: [...symbols] };
 };
+const DIMENSION_LABELS = {
+    length: 'a length',
+    area: 'an area',
+    volume: 'a volume',
+    angle: 'an angle',
+    none: 'a plain number',
+};
+const describeDimension = (dimension) => DIMENSION_LABELS[dimension];
+// 1728 stays 1728; 57.29577951308232 becomes 57.3.
+const trimRatio = (ratio) => Number.isInteger(ratio) ? String(ratio) : ratio.toFixed(1);
 // Does `equation` depend on `fieldId`, directly or through the equations of
 // output fields it references? (Chained solving: the unknown may reach the
 // governing equation through intermediate outputs.)
@@ -324,13 +321,47 @@ export const validateCalculatorDefinition = (input) => {
                 push('variable-unit-dimension-mismatch', unitPath, `Unit "${unit}" is not a ${dim} unit (variable ${variable} maps to "${mapped.name}")`);
             }
         }
-        if (eq.resultUnit != null && target) {
+        if (target) {
             const dim = fieldDimension(target);
-            if (dim === 'none') {
-                push('result-unit-on-number-target', `${path}.resultUnit`, `Equation target "${target.name}" is a number field and takes the result as-is; remove the result unit`);
+            if (eq.resultUnit != null) {
+                if (dim === 'none') {
+                    push('result-unit-on-number-target', `${path}.resultUnit`, `Equation target "${target.name}" is a number field and takes the result as-is; remove the result unit`);
+                }
+                else if (unitDimension(eq.resultUnit) !== dim) {
+                    push('result-unit-dimension-mismatch', `${path}.resultUnit`, `Result unit "${eq.resultUnit}" is not a ${dim} unit (target "${target.name}")`);
+                }
+            }
+            // The unit the EXPRESSION produces, which is what `resultUnit` claims to
+            // be. Dimension checks against the target field can't see a same-
+            // dimension scale error: three inch variables multiplied are in³, so
+            // `cu_ft` passes every check above while reporting 1728× the truth.
+            const inferred = inferExpressionUnit(def.fields, eq);
+            if (inferred.ok && dim !== 'none') {
+                if (inferred.dimension !== dim) {
+                    push('expression-dimension-mismatch', `${path}.expression`, `Expression produces ${describeDimension(inferred.dimension)} but "${target.name}" is ${describeDimension(dim)} — check the variable units and the expression`);
+                }
+                else if (eq.resultUnit == null) {
+                    if (!producesCanonicalValue(inferred)) {
+                        push('missing-result-unit', `${path}.resultUnit`, `Expression produces a value in ${inferred.unit ? `"${inferred.unit}"` : inferred.bases.join('/')} but no result unit is set, so it will be stored as a canonical value. Set the result unit${inferred.unit ? ` to "${inferred.unit}"` : ''}.`);
+                    }
+                }
+                else if (inferred.unit != null &&
+                    // A result unit from the wrong dimension is already reported above;
+                    // quoting a scale factor across dimensions would be meaningless.
+                    unitDimension(eq.resultUnit) === inferred.dimension &&
+                    !isEquivalentUnit(eq.resultUnit, inferred.unit)) {
+                    const ratio = unitScaleRatio(eq.resultUnit, inferred.unit);
+                    const off = ratio > 1
+                        ? `${trimRatio(ratio)}× too large`
+                        : `${trimRatio(1 / ratio)}× too small`;
+                    push('result-unit-scale-mismatch', `${path}.resultUnit`, `Expression produces "${inferred.unit}" but the result unit is "${eq.resultUnit}" — computed values will be ${off}. Use "${inferred.unit}", or change the variable units to match.`);
+                }
+            }
+            if (inferred.ok && inferred.bases.length > 1) {
+                push('mixed-base-units', `${path}.variableUnits`, `Variables mix ${inferred.bases.join(' and ')} in one expression, so the result has no single unit. Put them all in the same unit.`, 'warning');
             }
-            else if (unitDimension(eq.resultUnit) !== dim) {
-                push('result-unit-dimension-mismatch', `${path}.resultUnit`, `Result unit "${eq.resultUnit}" is not a ${dim} unit (target "${target.name}")`);
+            if (!inferred.ok && inferred.reason === 'inconsistent-terms') {
+                push('expression-mixed-dimensions', `${path}.expression`, 'Expression adds or compares terms of different dimensions (a length and an area, say) — one of them is probably the wrong field', 'warning');
             }
         }
         // The canonical-leak trap: a number target consuming a unit-carrying
@@ -345,7 +376,7 @@ export const validateCalculatorDefinition = (input) => {
                 }
             }
         }
-        const symbols = expressionSymbols(eq.expression);
+        const symbols = expressionSymbols(eq.expression, Object.keys(eq.variableToFieldId));
         if (!symbols.ok) {
             push('expression-invalid', `${path}.expression`, `Expression does not parse: ${symbols.error}`);
         }

package/dist/theme/index.d.ts

@@ -0,0 +1,3 @@
+export * from './colors.js';
+export * from './semantic.js';
+export * from './preset.js';

package/dist/theme/index.js

@@ -0,0 +1,3 @@
+export * from './colors.js';
+export * from './semantic.js';
+export * from './preset.js';

package/dist/theme/preset.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared Tailwind preset. COLORS ONLY, by design.
+ *
+ * Must never define `content`, `plugins`, `presets`, or `darkMode`:
+ * NativeWind recurses `config.presets[].presets` hunting for its own marker
+ * preset, and a `content` key here would silently narrow the consuming app's
+ * globs.
+ *
+ * Consumed from CJS Tailwind configs, so this is a NAMED export with no
+ * default — that keeps ESM/CJS interop semantics irrelevant:
+ *
+ *   const { boldrPreset } = require('@reekon-tools/boldr-utils/theme/preset');
+ *   module.exports = { presets: [require('nativewind/preset'), boldrPreset] };
+ *
+ * Tailwind loads configs through jiti + sucrase, so requiring this ESM file
+ * from a CJS config works regardless of Node version.
+ *
+ * Note that Tailwind merges `theme.extend` per key with the *app* winning, and
+ * replaces a color key wholesale rather than deep-merging. An app that keeps
+ * its own `colors.background` will silently shadow this preset.
+ */
+export declare const boldrPreset: {
+    theme: {
+        extend: {
+            colors: {
+                background: "#1D1F21";
+                foreground: {
+                    DEFAULT: "#FFFFFF";
+                    disabled: "#626364";
+                };
+                card: {
+                    DEFAULT: "#2B2C2E";
+                    foreground: "#FFFFFF";
+                };
+                popover: {
+                    DEFAULT: "#2B2C2E";
+                    foreground: "#FFFFFF";
+                };
+                muted: {
+                    DEFAULT: "#424345";
+                    foreground: "#9FA0A2";
+                };
+                accent: {
+                    DEFAULT: "#424345";
+                    foreground: "#FFFFFF";
+                };
+                secondary: {
+                    DEFAULT: "#424345";
+                    foreground: "#FFFFFF";
+                };
+                border: {
+                    DEFAULT: "#424345";
+                    strong: "#626364";
+                };
+                input: "#424345";
+                ring: "#FFAD00";
+                primary: {
+                    DEFAULT: "#FFAD00";
+                    foreground: "#1D1F21";
+                };
+                destructive: {
+                    DEFAULT: "#DF6358";
+                    foreground: "#1D1F21";
+                };
+                elevated: {
+                    DEFAULT: "#424345";
+                    foreground: "#FFFFFF";
+                };
+                interactive: {
+                    DEFAULT: "#0066FF";
+                    foreground: "#FFFFFF";
+                };
+                nav: {
+                    DEFAULT: "#2D3843";
+                    foreground: "#FFFFFF";
+                };
+                paper: {
+                    DEFAULT: "#E8EAED";
+                    foreground: "#1D1F21";
+                    field: "#FFFFFF";
+                    line: "#BCBEC2";
+                    muted: "#626364";
+                };
+                tile: {
+                    foreground: "#FFFFFF";
+                    measurement: {
+                        DEFAULT: "#0066FF";
+                        badge: "#50A6FF";
+                    };
+                    formula: {
+                        DEFAULT: "#BD30A8";
+                        badge: "#6C155F";
+                    };
+                    count: {
+                        DEFAULT: "#02274B";
+                        foreground: "#FFFFFF";
+                    };
+                };
+                diagram: {
+                    1: "#2E4C6A";
+                    2: "#4B6074";
+                    3: "#67819A";
+                };
+                tolerance: {
+                    in: {
+                        DEFAULT: "#58A942";
+                        warning: "#00E920";
+                        muted: "#8BB380";
+                    };
+                    out: {
+                        DEFAULT: "#E83D2F";
+                        warning: "#DA1100";
+                        muted: "#DF6358";
+                    };
+                };
+            };
+        };
+    };
+};
+export type BoldrPreset = typeof boldrPreset;

package/dist/theme/preset.js

@@ -0,0 +1,25 @@
+import { boldrColors } from './semantic.js';
+/**
+ * Shared Tailwind preset. COLORS ONLY, by design.
+ *
+ * Must never define `content`, `plugins`, `presets`, or `darkMode`:
+ * NativeWind recurses `config.presets[].presets` hunting for its own marker
+ * preset, and a `content` key here would silently narrow the consuming app's
+ * globs.
+ *
+ * Consumed from CJS Tailwind configs, so this is a NAMED export with no
+ * default — that keeps ESM/CJS interop semantics irrelevant:
+ *
+ *   const { boldrPreset } = require('@reekon-tools/boldr-utils/theme/preset');
+ *   module.exports = { presets: [require('nativewind/preset'), boldrPreset] };
+ *
+ * Tailwind loads configs through jiti + sucrase, so requiring this ESM file
+ * from a CJS config works regardless of Node version.
+ *
+ * Note that Tailwind merges `theme.extend` per key with the *app* winning, and
+ * replaces a color key wholesale rather than deep-merging. An app that keeps
+ * its own `colors.background` will silently shadow this preset.
+ */
+export const boldrPreset = {
+    theme: { extend: { colors: boldrColors } },
+};

package/dist/theme/semantic.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Structural shape of a Tailwind `theme.extend.colors` tree.
+ *
+ * Declared locally on purpose: annotating with tailwindcss's own `Config` type
+ * would put `import type { Config } from 'tailwindcss'` into the emitted .d.ts
+ * and make tailwindcss a hard type dependency of this package.
+ */
+export type ColorTree = {
+    [key: string]: string | ColorTree;
+};
+/**
+ * Semantic design tokens — the layer apps actually consume.
+ *
+ * `colors.ts` is the palette (raw Figma variables, named by value).
+ * This file maps those values onto *roles*, and is the only color surface the
+ * apps should reference. The raw palette is deliberately NOT exposed as Tailwind
+ * classes; naming by value is how both apps accumulated hundreds of arbitrary
+ * hex classes in the first place.
+ *
+ * The shadcn/ui token names (background, card, popover, foreground, muted,
+ * accent, secondary, border, input, ring, primary, destructive) are reused
+ * rather than paralleled, so every shadcn component is re-skinned without any
+ * component edits and `shadcn add` keeps generating markup that lands on these
+ * tokens.
+ *
+ * The design is dark-only. The light calculator / form surfaces are the
+ * explicitly-named `paper.*` tokens, not a light/dark variant pair — on native
+ * NativeWind's `dark:` variant is global, and portal-rendered surfaces
+ * (bottom sheets, dialogs, selects) mount outside any scoped subtree, so a
+ * scoped override would leak dark chrome onto a light page.
+ */
+export declare const boldrColors: {
+    background: "#1D1F21";
+    foreground: {
+        DEFAULT: "#FFFFFF";
+        disabled: "#626364";
+    };
+    card: {
+        DEFAULT: "#2B2C2E";
+        foreground: "#FFFFFF";
+    };
+    popover: {
+        DEFAULT: "#2B2C2E";
+        foreground: "#FFFFFF";
+    };
+    muted: {
+        DEFAULT: "#424345";
+        foreground: "#9FA0A2";
+    };
+    accent: {
+        DEFAULT: "#424345";
+        foreground: "#FFFFFF";
+    };
+    secondary: {
+        DEFAULT: "#424345";
+        foreground: "#FFFFFF";
+    };
+    border: {
+        DEFAULT: "#424345";
+        strong: "#626364";
+    };
+    input: "#424345";
+    ring: "#FFAD00";
+    primary: {
+        DEFAULT: "#FFAD00";
+        foreground: "#1D1F21";
+    };
+    destructive: {
+        DEFAULT: "#DF6358";
+        foreground: "#1D1F21";
+    };
+    /** Chips, inset controls, thumbnail placeholders. */
+    elevated: {
+        DEFAULT: "#424345";
+        foreground: "#FFFFFF";
+    };
+    /**
+     * Steppers and other interactive fills. FILL ONLY — #0066FF as text on
+     * #2B2C2E is 2.89:1. Never `text-interactive`.
+     */
+    interactive: {
+        DEFAULT: "#0066FF";
+        foreground: "#FFFFFF";
+    };
+    /** Nav chrome (the web app's sidebar). */
+    nav: {
+        DEFAULT: "#2D3843";
+        foreground: "#FFFFFF";
+    };
+    paper: {
+        DEFAULT: "#E8EAED";
+        foreground: "#1D1F21";
+        field: "#FFFFFF";
+        line: "#BCBEC2";
+        muted: "#626364";
+    };
+    tile: {
+        /**
+         * Ink for any tile fill — `text-tile-foreground`. Shared across the
+         * measurement and formula variants because both carry white type; keeping it
+         * at the family level avoids two identical `foreground` keys that could
+         * drift apart by accident.
+         */
+        foreground: "#FFFFFF";
+        measurement: {
+            DEFAULT: "#0066FF";
+            badge: "#50A6FF";
+        };
+        formula: {
+            DEFAULT: "#BD30A8";
+            badge: "#6C155F";
+        };
+        count: {
+            DEFAULT: "#02274B";
+            foreground: "#FFFFFF";
+        };
+    };
+    diagram: {
+        1: "#2E4C6A";
+        2: "#4B6074";
+        3: "#67819A";
+    };
+    tolerance: {
+        in: {
+            DEFAULT: "#58A942";
+            warning: "#00E920";
+            muted: "#8BB380";
+        };
+        out: {
+            DEFAULT: "#E83D2F";
+            warning: "#DA1100";
+            muted: "#DF6358";
+        };
+    };
+};
+export type BoldrColors = typeof boldrColors;

package/dist/theme/semantic.js

@@ -0,0 +1,116 @@
+import { GeneralColors, SecondaryColors, FormColors, TileColors, FormulaColors, YellowColors, RedColors, GreenColors, } from './colors.js';
+/**
+ * Semantic design tokens — the layer apps actually consume.
+ *
+ * `colors.ts` is the palette (raw Figma variables, named by value).
+ * This file maps those values onto *roles*, and is the only color surface the
+ * apps should reference. The raw palette is deliberately NOT exposed as Tailwind
+ * classes; naming by value is how both apps accumulated hundreds of arbitrary
+ * hex classes in the first place.
+ *
+ * The shadcn/ui token names (background, card, popover, foreground, muted,
+ * accent, secondary, border, input, ring, primary, destructive) are reused
+ * rather than paralleled, so every shadcn component is re-skinned without any
+ * component edits and `shadcn add` keeps generating markup that lands on these
+ * tokens.
+ *
+ * The design is dark-only. The light calculator / form surfaces are the
+ * explicitly-named `paper.*` tokens, not a light/dark variant pair — on native
+ * NativeWind's `dark:` variant is global, and portal-rendered surfaces
+ * (bottom sheets, dialogs, selects) mount outside any scoped subtree, so a
+ * scoped override would leak dark chrome onto a light page.
+ */
+export const boldrColors = {
+    // ── dark app chrome — shadcn-compatible names, re-pointed ────────────────
+    background: GeneralColors.darkGrey, // screen + header
+    foreground: {
+        DEFAULT: GeneralColors.white,
+        disabled: GeneralColors.grey3, // text-foreground-disabled
+    },
+    card: { DEFAULT: GeneralColors.grey1, foreground: GeneralColors.white },
+    popover: { DEFAULT: GeneralColors.grey1, foreground: GeneralColors.white },
+    // muted / accent / secondary exist so unmodified shadcn components look
+    // right. Prefer `elevated` in new boldr components — it gives future
+    // divergence a seam.
+    muted: { DEFAULT: GeneralColors.grey2, foreground: GeneralColors.grey4 },
+    accent: { DEFAULT: GeneralColors.grey2, foreground: GeneralColors.white },
+    secondary: { DEFAULT: GeneralColors.grey2, foreground: GeneralColors.white },
+    border: { DEFAULT: GeneralColors.grey2, strong: GeneralColors.grey3 },
+    input: GeneralColors.grey2,
+    ring: YellowColors.mainYellow,
+    primary: {
+        DEFAULT: YellowColors.mainYellow,
+        // White on #FFAD00 is 1.87:1. Dark ink is 8.84:1, and matches the mockups.
+        foreground: GeneralColors.darkGrey,
+    },
+    destructive: {
+        DEFAULT: RedColors.mutedRed,
+        // Confirmed against the Settings frame: the Log Out label is dark ink.
+        // White on #DF6358 would be 3.46:1; #1D1F21 is 4.77:1.
+        foreground: GeneralColors.darkGrey,
+    },
+    // ── boldr additions the shadcn vocabulary has no word for ───────────────
+    /** Chips, inset controls, thumbnail placeholders. */
+    elevated: { DEFAULT: GeneralColors.grey2, foreground: GeneralColors.white },
+    /**
+     * Steppers and other interactive fills. FILL ONLY — #0066FF as text on
+     * #2B2C2E is 2.89:1. Never `text-interactive`.
+     */
+    interactive: {
+        DEFAULT: TileColors.activeBlue,
+        foreground: GeneralColors.white,
+    },
+    /** Nav chrome (the web app's sidebar). */
+    nav: {
+        DEFAULT: SecondaryColors.accentBlue1,
+        foreground: GeneralColors.white,
+    },
+    // ── light "paper": the calculator page and form fields ──────────────────
+    paper: {
+        DEFAULT: FormColors.lightGrey2, // bg-paper            page / canvas
+        foreground: GeneralColors.darkGrey, // text-paper-foreground
+        field: GeneralColors.white, // bg-paper-field      inputs, cards on paper
+        line: FormColors.lightGrey1, // border-paper-line   field borders, dividers
+        // grey3, not lightGrey1: #BCBEC2 on #E8EAED is 1.54:1 — invisible.
+        // lightGrey1 is a border color only, which is why it's `paper.line`.
+        muted: GeneralColors.grey3, // text-paper-muted
+    },
+    // ── product tiles ───────────────────────────────────────────────────────
+    tile: {
+        /**
+         * Ink for any tile fill — `text-tile-foreground`. Shared across the
+         * measurement and formula variants because both carry white type; keeping it
+         * at the family level avoids two identical `foreground` keys that could
+         * drift apart by accident.
+         */
+        foreground: GeneralColors.white,
+        measurement: {
+            DEFAULT: TileColors.activeBlue,
+            badge: TileColors.lightBlue1,
+        },
+        // Note the badge is DARKER than the tile here, inverting the old app-local
+        // values. Confirmed in the mockups: a magenta tile with a darker magenta
+        // label bar.
+        formula: { DEFAULT: FormulaColors.purple, badge: FormulaColors.darkPurple },
+        count: { DEFAULT: TileColors.darkBlue, foreground: GeneralColors.white },
+    },
+    // ── 3D / diagram depth ramp (ordered; the steps have no individual meaning) ─
+    diagram: {
+        1: SecondaryColors.accentBlue2,
+        2: SecondaryColors.accentBlue3,
+        3: SecondaryColors.accentBlue4,
+    },
+    // ── measurement tolerance ───────────────────────────────────────────────
+    tolerance: {
+        in: {
+            DEFAULT: GreenColors.green,
+            warning: GreenColors.warningGreen,
+            muted: GreenColors.mutedGreen,
+        },
+        out: {
+            DEFAULT: RedColors.red,
+            warning: RedColors.warningRed,
+            muted: RedColors.mutedRed,
+        },
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.8.5",
+  "version": "1.9.0",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",