@reekon-tools/boldr-utils 1.10.0 → 1.10.2

package/dist/calculator/evaluate.js

@@ -1,8 +1,9 @@
 import { create, all } from 'mathjs';
 import { ColumnType } from '../types/firestore.js';
-import { equationForField, findField } from './schema.js';
+import { bindingUnitForBase, equationForField, fieldDimension, findField, } from './schema.js';
 import { conversionCellNumber, findConversionRow } from './conversionTable.js';
-import { fromCanonical, toCanonical } from './units.js';
+import { deriveResultUnitForBase } from './expressionUnits.js';
+import { fromCanonical, isEquationBase, toCanonical, } from './units.js';
 // Trig in calculator equations works in DEGREES: angle fields are stored in
 // degrees canonically, and construction authors write `H = W * tan(A)`
 // expecting A in degrees. mathjs has no `angle` config option (evaluateFormula
@@ -107,6 +108,46 @@ export const numericFieldValue = (field, value, columnId) => {
             return null;
     }
 };
+// ---------------------------------------------------------------------------
+// Scope units.
+//
+// A base-anchored equation derives every unit from its base rather than
+// reading `variableUnits` / `resultUnit` off the document. Those fields are
+// still written (older app builds evaluate from them), but they are a cache of
+// this derivation — and trusting a cache over its source is exactly how a
+// stale entry silently rescales a live answer. So the evaluator recomputes.
+//
+// Equations with no base keep the legacy reading, byte for byte: saved
+// calculator instances freeze their definition, so pre-base equations must go
+// on evaluating exactly as they did the day they were saved.
+// ---------------------------------------------------------------------------
+/** The unit one variable's canonical value is re-expressed in before scoping. */
+const scopeUnitFor = (definition, equation, variable, fieldId) => {
+    if (!isEquationBase(equation.base)) {
+        return equation.variableUnits?.[variable] ?? null;
+    }
+    const field = findField(definition, fieldId);
+    if (!field)
+        return null;
+    return bindingUnitForBase(equation.base, field, equation.variableColumnIds?.[variable]);
+};
+/** The unit the expression's raw result carries, or null when it needs none. */
+const resultUnitFor = (definition, equation) => {
+    if (!isEquationBase(equation.base))
+        return equation.resultUnit ?? null;
+    const target = findField(definition, equation.targetFieldId);
+    // A number target takes the raw value — the whole point of evaluating in
+    // display units is that `area_in_ft² / 33` yields squares, not µm².
+    if (!target || fieldDimension(target) === 'none')
+        return null;
+    const derived = deriveResultUnitForBase(equation.base, definition.fields, equation);
+    if (derived.kind === 'unit')
+        return derived.unit;
+    if (derived.kind === 'none')
+        return null;
+    // Inference declined; the author's stored unit is the only information left.
+    return equation.resultUnit ?? null;
+};
 const evaluateEquationInContext = (equation, ctx) => {
     const cached = ctx.cache.get(equation.id);
     if (cached)
@@ -131,9 +172,9 @@ const evaluateEquationInContext = (equation, ctx) => {
                 }
                 return resolved;
             }
-            // Field values resolve canonically; a variable unit re-expresses the
-            // value in the author's chosen display unit before it enters the scope.
-            const unit = equation.variableUnits?.[variable];
+            // Field values resolve canonically; the scope unit re-expresses each one
+            // in the equation's own terms before it enters the expression.
+            const unit = scopeUnitFor(ctx.definition, equation, variable, fieldId);
             try {
                 scope[variable] =
                     unit != null ? fromCanonical(resolved.value, unit) : resolved.value;
@@ -163,11 +204,12 @@ const evaluateEquationInContext = (equation, ctx) => {
         else {
             // A result unit means the expression produced a display-unit value;
             // convert back so the returned value is canonical like everything else.
+            const resultUnit = resultUnitFor(ctx.definition, equation);
             try {
                 result = {
                     ok: true,
-                    value: equation.resultUnit != null
-                        ? toCanonical(evaluated.value, equation.resultUnit)
+                    value: resultUnit != null
+                        ? toCanonical(evaluated.value, resultUnit)
                         : evaluated.value,
                 };
             }

package/dist/calculator/expressionUnits.d.ts

@@ -1,6 +1,6 @@
 import { type MathNode } from 'mathjs';
 import type { CalculatorEquation, CalculatorField } from './schema.js';
-import { type CalculatorUnit, type FieldDimension } from './units.js';
+import { type CalculatorUnit, type EquationBase, type FieldDimension } from './units.js';
 /** Constants mathjs resolves without a scope entry. */
 export declare const MATHJS_CONSTANTS: Set<string>;
 export type ParseResult = {
@@ -39,6 +39,20 @@ export interface InferredExpressionUnit {
     unit: CalculatorUnit | null;
     /** Distinct base units among the variables carrying that dimension. */
     bases: string[];
+    /**
+     * Every distinct length-family base the variables contributed, whether or
+     * not the exponents survived to the result.
+     *
+     * Separate from `bases` because `bases` describes the RESULT, and a result
+     * can be dimensionless while its inputs still disagree: `(A_in * B_in) /
+     * C_ft²` cancels to a plain count, so `bases` is empty and `dimension` is
+     * 'none' — and the 144× scale error that ratio carries is invisible there.
+     * Tracked per axis, since a length and an angle in one expression is normal
+     * (trig consumes the angle) while two length bases never is.
+     */
+    lengthBases: string[];
+    /** Every distinct angle base the variables contributed ('deg' / 'rad'). */
+    angleBases: string[];
 }
 export type ExpressionUnitInference = ({
     ok: true;
@@ -71,6 +85,86 @@ export declare const unitScaleRatio: (declared: CalculatorUnit, actual: Calculat
  * 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" | "variableColumnIds" | "variableUnits" | "resultUnit">) => CalculatorUnit | null;
+/** The scope unit for every variable of a base-anchored equation. */
+export declare const deriveVariableUnits: (base: EquationBase, fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "variableToFieldId" | "variableColumnIds">) => Record<string, CalculatorUnit>;
+export type DerivedResultUnit = 
+/** The raw value carries this unit and must be converted back through it. */
+{
+    kind: 'unit';
+    unit: CalculatorUnit;
+}
+/**
+ * Inference succeeded and the raw value needs NO conversion: dimensionless,
+ * or an angle (degrees are already canonical).
+ */
+ | {
+    kind: 'none';
+}
+/**
+ * Inference declined — an unmodelled function, a non-integer power, a
+ * dimension this vocabulary can't name. The base says nothing useful here,
+ * so callers fall back to whatever unit the equation already carried. This
+ * is the escape hatch the authoring UI's manual result-unit picker fills.
+ */
+ | {
+    kind: 'unknown';
+};
+/** The unit a base-anchored expression's raw value carries. */
+export declare const deriveResultUnitForBase: (base: EquationBase, fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableColumnIds">) => DerivedResultUnit;
+/** Where a migrated equation's base came from — reported by the migration. */
+export type EquationBaseSource = 
+/** A bound conversion column's declared unit. */
+'conversion-column'
+/** An existing authored `variableUnits` entry. */
+ | 'variable-unit'
+/** A bound measurement field's display unit. */
+ | 'field-default'
+/** Nothing length-valued to anchor to; the base is inert. */
+ | 'fallback'
+/** A variable is in a unit family no base can express — see `blockedBy`. */
+ | 'unanchorable';
+export interface DerivedEquationBase {
+    /** Null when the equation cannot be anchored without changing its meaning. */
+    base: EquationBase | null;
+    source: EquationBaseSource;
+    /**
+     * Distinct bases seen at the winning tier. More than one means the source
+     * disagreed with itself and `base` is the most common of them — the case a
+     * migration should surface rather than apply silently.
+     */
+    candidates: EquationBase[];
+    /**
+     * Units that blocked anchoring: cubic yards, liters, gallons — real units a
+     * field may hold, but outside the five families a base can name.
+     */
+    blockedBy?: CalculatorUnit[];
+}
+/** Inert default when an equation has no length-valued binding at all. */
+export declare const DEFAULT_EQUATION_BASE: EquationBase;
+/**
+ * The base a pre-`base` equation should adopt, in descending order of what the
+ * source can be trusted to mean:
+ *
+ *   1. A bound conversion COLUMN's unit. A cell reading "5.33" is literal text
+ *      a human typed; its unit is the only thing that says what the number is,
+ *      so it is the one declaration in the equation that cannot be re-expressed
+ *      without reinterpreting authored data.
+ *   2. An existing `variableUnits` entry — the author's own stated intent,
+ *      even if it disagreed with its neighbours.
+ *   3. A bound measurement field's display unit. Values are stored canonically,
+ *      so this only reflects a preference, but it is the author's preference.
+ *   4. Nothing length-valued in the equation, so the base cannot matter.
+ *
+ * Declines entirely (`base: null`) when a variable is ALREADY authored in a
+ * unit no base can name — cubic yards, liters, gallons. Re-expressing those is
+ * numerically lossless but semantically not: a gravel estimator multiplying a
+ * cu_yd volume by a tons-per-cubic-yard constant is correct only while the
+ * volume stays in cubic yards, and that constant is a bare number with nothing
+ * to declare its units. Silently rebasing it to cu_in would make the answer
+ * 46,656× too large. Better to leave such an equation on the pre-base path,
+ * where the mixed-base check still watches it, than to guess.
+ */
+export declare const deriveEquationBase: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "variableToFieldId" | "variableColumnIds" | "variableUnits">) => DerivedEquationBase;
 /**
  * Bring an equation's field-derived annotations — variable column bindings,
  * variable units, result unit — back in line with the fields it references.

package/dist/calculator/expressionUnits.js

@@ -1,8 +1,8 @@
 import { create, all } from 'mathjs';
-import { ColumnType, Units } from '../types/firestore.js';
-import { bindingDefaultUnit, bindingDimension, fieldDimension, } from './schema.js';
+import { ColumnType } from '../types/firestore.js';
+import { bindingDefaultUnit, bindingDimension, bindingUnitForBase, equationBindings, fieldDimension, } from './schema.js';
 import { findConversionColumn } from './conversionTable.js';
-import { CALCULATOR_UNIT_INFO, toCanonical, unitDimension, } from './units.js';
+import { UNIT_BY_BASE, equationBaseOfUnit, isEquationBase, toCanonical, unitBase, unitDimension, unitForBase, } from './units.js';
 const math = create(all);
 // ---------------------------------------------------------------------------
 // Expression unit inference.
@@ -44,23 +44,41 @@ export const MATHJS_CONSTANTS = new Set([
     'NaN',
     'null',
 ]);
+// Parse cache, mirroring evaluate.ts's compile cache and sized to match. Unit
+// inference now runs on the evaluation path (an equation's scope units are
+// derived from its base, not read off the document), so the same handful of
+// expressions get parsed on every keystroke of the editor preview.
+//
+// The cached node is handed to callers directly. Every consumer in this
+// package only reads it — `traverse` in expressionSymbols, the structural walk
+// below — so nothing mutates the shared tree.
+const parseCache = new Map();
+const PARSE_CACHE_MAX = 200;
 /** Shared mathjs parse — the one place expression text becomes a tree. */
 export const parseExpression = (expression) => {
+    const hit = parseCache.get(expression);
+    if (hit)
+        return hit;
+    let result;
     try {
-        return { ok: true, node: math.parse(expression) };
+        result = { ok: true, node: math.parse(expression) };
     }
     catch (err) {
-        return {
+        result = {
             ok: false,
             error: err instanceof Error ? err.message : String(err),
         };
     }
+    if (parseCache.size >= PARSE_CACHE_MAX)
+        parseCache.clear();
+    parseCache.set(expression, result);
+    return result;
 };
 // 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];
+const baseUnitOf = unitBase;
 /**
  * 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
@@ -69,17 +87,6 @@ const baseUnitOf = (unit) => (CALCULATOR_UNIT_INFO[unit]?.mathUnit ?? '').split(
 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;
@@ -301,28 +308,35 @@ export const inferExpressionUnit = (fields, equation) => {
     if (!exponents) {
         return { ok: false, reason: failure ?? 'unsupported-operation' };
     }
+    // Every success path reports both axes; `bases` narrows to whichever axis
+    // the RESULT lives on.
+    const axes = { lengthBases: [...lengthBases], angleBases: [...angleBases] };
     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];
+        const bases = axes.angleBases;
         return {
             ok: true,
             dimension: 'angle',
             unit: bases.length === 1 ? bases[0] : null,
             bases,
+            ...axes,
         };
     }
     if (exponents.len === 0) {
-        return { ok: true, dimension: 'none', unit: null, bases: [] };
+        // Dimensionless. `bases` is empty because the RESULT names no unit — but
+        // the per-axis lists still carry what went in, which is the only record
+        // that a cancelling ratio mixed inches with feet.
+        return { ok: true, dimension: 'none', unit: null, bases: [], ...axes };
     }
     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];
+    const bases = axes.lengthBases;
     return {
         ok: true,
         dimension,
@@ -330,6 +344,7 @@ export const inferExpressionUnit = (fields, equation) => {
             ? (UNIT_BY_BASE[bases[0]]?.[exponents.len] ?? null)
             : null,
         bases,
+        ...axes,
     };
 };
 /**
@@ -365,6 +380,151 @@ export const deriveResultUnit = (fields, equation) => {
         ? current
         : inferred.unit;
 };
+// ---------------------------------------------------------------------------
+// Base-anchored derivation.
+//
+// With `CalculatorEquation.base` set, units stop being authored and become a
+// function of (base, binding dimension). `deriveVariableUnits` answers "what
+// does each variable arrive as", `deriveResultUnitForBase` answers "what does
+// the expression hand back", and `deriveEquationBase` picks a base for an
+// equation that predates the field.
+// ---------------------------------------------------------------------------
+/** The scope unit for every variable of a base-anchored equation. */
+export const deriveVariableUnits = (base, fields, equation) => {
+    const fieldById = new Map(fields.map((f) => [f.id, f]));
+    const units = {};
+    for (const { variable, fieldId, columnId } of equationBindings(equation)) {
+        const field = fieldById.get(fieldId);
+        if (!field)
+            continue;
+        const unit = bindingUnitForBase(base, field, columnId);
+        if (unit != null)
+            units[variable] = unit;
+    }
+    return units;
+};
+/** The unit a base-anchored expression's raw value carries. */
+export const deriveResultUnitForBase = (base, fields, equation) => {
+    const inferred = inferExpressionUnit(fields, {
+        ...equation,
+        variableUnits: deriveVariableUnits(base, fields, equation),
+    });
+    if (!inferred.ok)
+        return { kind: 'unknown' };
+    if (inferred.dimension === 'none' || inferred.dimension === 'angle') {
+        return { kind: 'none' };
+    }
+    const unit = unitForBase(base, inferred.dimension);
+    return unit ? { kind: 'unit', unit } : { kind: 'unknown' };
+};
+/** Inert default when an equation has no length-valued binding at all. */
+export const DEFAULT_EQUATION_BASE = 'in';
+const LENGTH_DIMENSIONS = new Set(['length', 'area', 'volume']);
+// Most frequent base wins; ties break toward the first one seen, so the result
+// is stable across runs (variable order is the document's own key order).
+const mostCommon = (bases) => {
+    if (bases.length === 0)
+        return null;
+    const counts = new Map();
+    for (const b of bases)
+        counts.set(b, (counts.get(b) ?? 0) + 1);
+    let best = bases[0];
+    for (const b of bases) {
+        if ((counts.get(b) ?? 0) > (counts.get(best) ?? 0))
+            best = b;
+    }
+    return best;
+};
+/**
+ * The base a pre-`base` equation should adopt, in descending order of what the
+ * source can be trusted to mean:
+ *
+ *   1. A bound conversion COLUMN's unit. A cell reading "5.33" is literal text
+ *      a human typed; its unit is the only thing that says what the number is,
+ *      so it is the one declaration in the equation that cannot be re-expressed
+ *      without reinterpreting authored data.
+ *   2. An existing `variableUnits` entry — the author's own stated intent,
+ *      even if it disagreed with its neighbours.
+ *   3. A bound measurement field's display unit. Values are stored canonically,
+ *      so this only reflects a preference, but it is the author's preference.
+ *   4. Nothing length-valued in the equation, so the base cannot matter.
+ *
+ * Declines entirely (`base: null`) when a variable is ALREADY authored in a
+ * unit no base can name — cubic yards, liters, gallons. Re-expressing those is
+ * numerically lossless but semantically not: a gravel estimator multiplying a
+ * cu_yd volume by a tons-per-cubic-yard constant is correct only while the
+ * volume stays in cubic yards, and that constant is a bare number with nothing
+ * to declare its units. Silently rebasing it to cu_in would make the answer
+ * 46,656× too large. Better to leave such an equation on the pre-base path,
+ * where the mixed-base check still watches it, than to guess.
+ */
+export const deriveEquationBase = (fields, equation) => {
+    const fieldById = new Map(fields.map((f) => [f.id, f]));
+    const fromColumns = [];
+    const fromVariableUnits = [];
+    const fromFieldDefaults = [];
+    const blockedBy = [];
+    for (const { variable, fieldId, columnId } of equationBindings(equation)) {
+        const field = fieldById.get(fieldId);
+        if (!field)
+            continue;
+        // Only length-family bindings can disagree about scale; angles are their
+        // own axis and dimensionless bindings carry nothing.
+        if (!LENGTH_DIMENSIONS.has(bindingDimension(field, columnId)))
+            continue;
+        // bindingDefaultUnit resolves an absent/unknown column id to the first
+        // column, matching what the evaluator actually reads.
+        const columnUnit = field.kind === ColumnType.ConversionTable
+            ? bindingDefaultUnit(field, columnId)
+            : null;
+        const declared = equation.variableUnits?.[variable];
+        // The unit this variable is evaluating in TODAY. That is what a base has
+        // to be able to reproduce; a field's display default is only a preference.
+        const effective = declared ?? columnUnit;
+        if (effective != null && equationBaseOfUnit(effective) == null) {
+            blockedBy.push(effective);
+            continue;
+        }
+        if (columnUnit) {
+            const base = equationBaseOfUnit(columnUnit);
+            if (base)
+                fromColumns.push(base);
+        }
+        if (declared) {
+            const base = equationBaseOfUnit(declared);
+            if (base)
+                fromVariableUnits.push(base);
+        }
+        if (field.kind === ColumnType.Measurement) {
+            const base = equationBaseOfUnit(field.unit.defaultUnit);
+            if (base)
+                fromFieldDefaults.push(base);
+        }
+    }
+    if (blockedBy.length > 0) {
+        return {
+            base: null,
+            source: 'unanchorable',
+            candidates: [],
+            blockedBy: [...new Set(blockedBy)],
+        };
+    }
+    const tiers = [
+        ['conversion-column', fromColumns],
+        ['variable-unit', fromVariableUnits],
+        ['field-default', fromFieldDefaults],
+    ];
+    for (const [source, candidates] of tiers) {
+        const base = mostCommon(candidates);
+        if (base)
+            return { base, source, candidates: [...new Set(candidates)] };
+    }
+    return {
+        base: DEFAULT_EQUATION_BASE,
+        source: 'fallback',
+        candidates: [],
+    };
+};
 // Rebuild an equation without a key, since Firestore rejects `undefined`.
 const withoutResultUnit = (equation) => {
     const { resultUnit: _dropped, ...rest } = equation;
@@ -375,6 +535,66 @@ const withoutVariableColumnIds = (equation) => {
     const { variableColumnIds: _dropped, ...rest } = equation;
     return rest;
 };
+// Rebuild an equation without a key, since Firestore rejects `undefined`.
+const withoutVariableUnits = (equation) => {
+    const { variableUnits: _dropped, ...rest } = equation;
+    return rest;
+};
+/**
+ * The pre-base repair, kept verbatim for equations that cannot adopt a base.
+ * It only realigns a unit whose DIMENSION no longer matches its binding — it
+ * has no opinion about bases, which is precisely why it is safe here: an
+ * equation holding cubic yards keeps holding cubic yards.
+ */
+const reconcileLegacyUnits = (fields, fieldById, equation) => {
+    let repaired = equation;
+    if (repaired.variableUnits) {
+        const variableUnits = {};
+        let unitsChanged = false;
+        for (const [variable, unit] of Object.entries(repaired.variableUnits)) {
+            const field = fieldById.get(repaired.variableToFieldId[variable] ?? '');
+            if (!field) {
+                unitsChanged = true; // variable or field is gone
+                continue;
+            }
+            const columnId = repaired.variableColumnIds?.[variable];
+            if (unitDimension(unit) === bindingDimension(field, columnId)) {
+                variableUnits[variable] = unit;
+                continue;
+            }
+            const replacement = bindingDefaultUnit(field, columnId);
+            unitsChanged = true;
+            if (replacement)
+                variableUnits[variable] = replacement;
+        }
+        if (unitsChanged) {
+            repaired =
+                Object.keys(variableUnits).length > 0
+                    ? { ...repaired, variableUnits }
+                    : withoutVariableUnits(repaired);
+        }
+    }
+    const target = fieldById.get(repaired.targetFieldId);
+    const targetDimension = target ? fieldDimension(target) : 'none';
+    if (targetDimension === 'none') {
+        if (repaired.resultUnit != null)
+            repaired = withoutResultUnit(repaired);
+        return repaired;
+    }
+    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);
+    }
+    return repaired;
+};
 /**
  * Bring an equation's field-derived annotations — variable column bindings,
  * variable units, result unit — back in line with the fields it references.
@@ -411,59 +631,61 @@ export const reconcileEquationUnits = (fields, equations) => {
                         : withoutVariableColumnIds(repaired);
             }
         }
-        // 2. Variable units must match the dimension of the binding they annotate.
-        //    Read against `repaired`, not `equation`: step 1 may have moved a
-        //    variable back to the first column, whose dimension is what matters now.
-        if (repaired.variableUnits) {
-            const variableUnits = {};
-            let unitsChanged = false;
-            for (const [variable, unit] of Object.entries(repaired.variableUnits)) {
-                const field = fieldById.get(repaired.variableToFieldId[variable] ?? '');
-                if (!field) {
-                    unitsChanged = true; // variable or field is gone
-                    continue;
-                }
-                const columnId = repaired.variableColumnIds?.[variable];
-                if (unitDimension(unit) === bindingDimension(field, columnId)) {
-                    variableUnits[variable] = unit;
-                    continue;
-                }
-                const replacement = bindingDefaultUnit(field, columnId);
-                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. Adopt a base. An equation authored before bases existed gets one
+        //    inferred from what it already says (deriveEquationBase), so opening
+        //    an old calculator and touching a field migrates it in place. An
+        //    unrecognized stored base is treated as absent rather than trusted.
+        //    Read against `repaired`: step 1 may have moved a variable back to the
+        //    first column, whose unit is what the base should follow.
+        //
+        //    An EXPLICIT base always wins — converting a cu_yd column into ft³ is
+        //    well defined, and an author who asked for it meant it. Only the
+        //    inference declines, and only for an equation already sitting in a
+        //    unit family no base can name (see deriveEquationBase).
+        const base = isEquationBase(repaired.base)
+            ? repaired.base
+            : deriveEquationBase(fields, repaired).base;
+        if (base == null) {
+            // Unanchorable: leave it exactly as the pre-base code would have.
+            repaired = reconcileLegacyUnits(fields, fieldById, repaired);
+            if (repaired !== equation)
+                changed = true;
+            return repaired;
+        }
+        if (repaired.base !== base)
+            repaired = { ...repaired, base };
+        // 3. Variable units are fully determined by the base and each binding's
+        //    dimension, so they are not stored at all — the evaluator derives them.
+        //    Anything left over from the pre-base form is dead weight that a reader
+        //    would reasonably mistake for the source of truth.
+        if (repaired.variableUnits != null) {
+            repaired = withoutVariableUnits(repaired);
         }
-        // 3. The result unit follows from the repaired variable units.
+        // 4. The result unit is derived the same way, with ONE exception worth
+        //    persisting: an expression whose units inference cannot model at all
+        //    (an unmodelled function, a dimension this vocabulary can't name). The
+        //    base says nothing useful there, so the author picks, and that choice
+        //    is real authored data rather than a cache.
+        //
+        //    Number targets take the raw value either way — that is what makes
+        //    `area_in_ft² / 33` read as 33 ft², not 33 µm².
         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 &&
+        const derived = targetDimension === 'none'
+            ? { kind: 'none' }
+            : deriveResultUnitForBase(base, fields, repaired);
+        if (derived.kind === 'unknown') {
+            // Keep the author's pick, unless it isn't even the target's dimension —
+            // that would convert a length factor into an area field.
+            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);
             }
         }
+        else if (repaired.resultUnit != null) {
+            // Derivable, so a stored unit is either redundant or wrong. Drop it.
+            repaired = withoutResultUnit(repaired);
+        }
         if (repaired !== equation)
             changed = true;
         return repaired;

package/dist/calculator/schema.d.ts

@@ -1,5 +1,5 @@
 import { ColumnType, type ColumnConfig, type ConversionTableColumnData, type InstructionsColumnData, type SelectColumnData, type DecimalTolerance, type FractionalTolerance } from '../types/firestore.js';
-import type { AngleUnit, CalculatorUnit, FieldDimension, MeasurementDimension } from './units.js';
+import type { AngleUnit, CalculatorUnit, EquationBase, FieldDimension, MeasurementDimension } from './units.js';
 import type { CalculatorCategoryId } from './categories.js';
 /**
  * Version of the definition format itself. Bumped only on breaking schema
@@ -122,15 +122,45 @@ export interface CalculatorEquation {
      */
     variableColumnIds?: Record<string, string>;
     /**
-     * Variable letter -> display unit its value enters the scope in. A mapped
-     * variable without an entry stays canonical (µm-scale) — the pre-1.9
-     * behavior. Unit dimension must match the mapped field's dimension.
+     * The ONE length base this expression evaluates in ('ft', 'in', 'mm', …) —
+     * and, when present, the only unit information the equation stores. Each
+     * variable's scope unit is this base at the variable's own exponent (ft,
+     * ft², ft³); the result unit is this base at the result's exponent. Both are
+     * computed on demand, never written down.
+     *
+     * This exists because per-variable units could disagree. Authoring
+     * `(A_in * B_in) / C_ft²` passed every dimensional check — length·length ÷
+     * area cancels to a valid dimensionless count — while computing 144× the
+     * truth, because nothing reconciled inches against feet. A single base makes
+     * that unrepresentable rather than merely detectable.
+     *
+     * The base is per EQUATION, not per calculator: values are stored
+     * canonically, so two equations may work in different bases and still feed
+     * each other — each converts in and out at its own edge.
+     *
+     * Absent means the pre-base form below. Still read, because saved instances
+     * freeze their definition and older docs migrate lazily, but never written
+     * for new equations.
+     */
+    base?: EquationBase;
+    /**
+     * LEGACY (pre-`base`). Variable letter -> display unit its value enters the
+     * scope in; a mapped variable with no entry stays canonical (µm-scale).
+     *
+     * Ignored entirely when `base` is set, and stripped by
+     * reconcileEquationUnits, since the base determines every one of these — a
+     * stored copy could only go stale and be mistaken for the source of truth.
      */
     variableUnits?: Record<string, CalculatorUnit>;
     /**
      * Display unit the expression's RESULT is expressed in; converted back to
      * canonical before storage/chaining. Only meaningful for measurement/angle
      * targets — number targets take the result raw. Absent = canonical.
+     *
+     * With `base` set this survives in ONE case: an expression whose units
+     * inference cannot model (an unmodelled function, an unnameable dimension).
+     * The base yields no answer there, so the author picks one and it is real
+     * authored data. Everywhere else it is derived and not stored.
      */
     resultUnit?: CalculatorUnit;
 }
@@ -212,13 +242,24 @@ export declare const bindingDimension: (field: CalculatorField, columnId?: strin
  */
 export declare const fieldDefaultUnit: (field: CalculatorField) => CalculatorUnit | null;
 /**
- * The unit a BOUND value is expressed in, or null when it carries none. For a
- * conversion column this is the column's declared unit and is NOT a per-equation
- * choice: the cell text was typed in that unit, so re-expressing the variable in
- * another one would only invite the scale errors expressionUnits.ts exists to
- * catch. The authoring UI shows it read-only for that reason.
+ * The unit a BOUND value is DECLARED in — the conversion column's unit for a
+ * table binding (the unit the cell text was typed in), the field's display
+ * unit otherwise. This is what the value means at rest, not what it means
+ * inside an equation; `bindingUnitForBase` converts it to the latter.
  */
 export declare const bindingDefaultUnit: (field: CalculatorField, columnId?: string) => CalculatorUnit | null;
+/**
+ * The unit a bound value enters a base-anchored equation's scope in — the
+ * base's member at the binding's own exponent, so a length arrives in `ft` and
+ * an area off the same equation in `ft²`.
+ *
+ * Never an author choice, and deliberately independent of how the value is
+ * declared or displayed: a column typed in ft² feeding an inch-based equation
+ * converts to in², which is a lossless re-expression of the same quantity, not
+ * a reinterpretation of the author's cell text. Returns null for dimensionless
+ * bindings, which enter the scope raw.
+ */
+export declare const bindingUnitForBase: (base: EquationBase, field: CalculatorField, columnId?: string) => 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

@@ -1,5 +1,5 @@
 import { ColumnType, Units, } from '../types/firestore.js';
-import { unitsForDimension } from './units.js';
+import { unitForBase, unitsForDimension } from './units.js';
 import { conversionColumnDimension, resolveConversionColumn, } from './conversionTable.js';
 // ---------------------------------------------------------------------------
 // The Construction Calculator definition — the shared artifact the web
@@ -101,15 +101,39 @@ export const fieldDefaultUnit = (field) => {
     }
 };
 /**
- * The unit a BOUND value is expressed in, or null when it carries none. For a
- * conversion column this is the column's declared unit and is NOT a per-equation
- * choice: the cell text was typed in that unit, so re-expressing the variable in
- * another one would only invite the scale errors expressionUnits.ts exists to
- * catch. The authoring UI shows it read-only for that reason.
+ * The unit a BOUND value is DECLARED in — the conversion column's unit for a
+ * table binding (the unit the cell text was typed in), the field's display
+ * unit otherwise. This is what the value means at rest, not what it means
+ * inside an equation; `bindingUnitForBase` converts it to the latter.
  */
 export const bindingDefaultUnit = (field, columnId) => field.kind === ColumnType.ConversionTable
     ? (resolveConversionColumn(field.columnData, columnId).unit ?? null)
     : fieldDefaultUnit(field);
+/**
+ * The unit a bound value enters a base-anchored equation's scope in — the
+ * base's member at the binding's own exponent, so a length arrives in `ft` and
+ * an area off the same equation in `ft²`.
+ *
+ * Never an author choice, and deliberately independent of how the value is
+ * declared or displayed: a column typed in ft² feeding an inch-based equation
+ * converts to in², which is a lossless re-expression of the same quantity, not
+ * a reinterpretation of the author's cell text. Returns null for dimensionless
+ * bindings, which enter the scope raw.
+ */
+export const bindingUnitForBase = (base, field, columnId) => {
+    const dimension = bindingDimension(field, columnId);
+    switch (dimension) {
+        case 'none':
+            return null;
+        // Trig in equations runs in DEGREES (see evaluate.ts), so angles enter the
+        // scope as degrees whatever the base — and degrees are already canonical,
+        // making this conversion a no-op that exists for uniformity.
+        case 'angle':
+            return 'deg';
+        default:
+            return unitForBase(base, dimension);
+    }
+};
 /** Fields whose value participates in equations as a number. */
 export const isNumericFieldKind = (kind) => kind === ColumnType.Number ||
     kind === ColumnType.Measurement ||

package/dist/calculator/units.d.ts

@@ -28,6 +28,33 @@ export declare const CALCULATOR_UNIT_INFO: Record<CalculatorUnit, CalculatorUnit
 /** The math.js token for a dimension's canonical unit. '' for dimensionless. */
 export declare const canonicalMathUnit: (dimension: FieldDimension) => string;
 export declare const unitDimension: (unit: CalculatorUnit) => FieldDimension;
+/** The math.js base token a unit reduces to: 'sq_ft' -> 'ft', 'in_frac' -> 'in'. */
+export declare const unitBase: (unit: CalculatorUnit) => string;
+/**
+ * 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.
+ */
+export declare const UNIT_BY_BASE: Record<string, Partial<Record<number, CalculatorUnit>>>;
+/**
+ * A base an equation may evaluate in. Only bases that name a unit at EVERY
+ * length exponent qualify — an equation in yards could not express a plain
+ * yard length, and liters/gallons aren't a length family at all. Both remain
+ * perfectly usable as field/column units; they just get converted into the
+ * equation's base like anything else.
+ */
+export type EquationBase = 'mm' | 'cm' | 'm' | 'in' | 'ft';
+export declare const EQUATION_BASES: EquationBase[];
+export declare const isEquationBase: (value: unknown) => value is EquationBase;
+/** Length factors per dimension — an area is two lengths, a volume three. */
+export declare const LENGTH_EXPONENT: Record<MeasurementDimension, 1 | 2 | 3>;
+/** The unit naming `base` at a measurement dimension, e.g. ('ft','area') -> 'sq_ft'. */
+export declare const unitForBase: (base: EquationBase, dimension: MeasurementDimension) => CalculatorUnit | null;
+/**
+ * The equation base a unit belongs to, or null for units outside the five
+ * anchorable families (yd², liters, gallons, degrees, radians).
+ */
+export declare const equationBaseOfUnit: (unit: CalculatorUnit) => EquationBase | null;
 export declare const unitsForDimension: (dimension: FieldDimension) => CalculatorUnit[];
 /**
  * A unit's token and its disambiguating qualifier as separate pieces. The

package/dist/calculator/units.js

@@ -68,6 +68,53 @@ export const canonicalMathUnit = (dimension) => {
     }
 };
 export const unitDimension = (unit) => CALCULATOR_UNIT_INFO[unit]?.dimension ?? 'none';
+// ---------------------------------------------------------------------------
+// Equation bases
+//
+// An equation evaluates in ONE length base (see CalculatorEquation.base). The
+// base names a family — `ft` covers ft, ft², ft³ — and each variable's scope
+// unit is that family's member at the variable's own exponent. This is what
+// makes `(A * B) / C` meaningful: A and B arrive in ft, C in ft², and the
+// ratio is a true dimensionless count rather than a number that happens to
+// divide.
+//
+// Angles are a SEPARATE axis and never participate: the evaluator's trig runs
+// in degrees, so angle values always enter the scope as degrees regardless of
+// the base.
+// ---------------------------------------------------------------------------
+/** The math.js base token a unit reduces to: 'sq_ft' -> 'ft', 'in_frac' -> 'in'. */
+export const unitBase = (unit) => (CALCULATOR_UNIT_INFO[unit]?.mathUnit ?? '').split('^')[0];
+/**
+ * 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.
+ */
+export 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' },
+};
+export const EQUATION_BASES = ['mm', 'cm', 'm', 'in', 'ft'];
+export const isEquationBase = (value) => typeof value === 'string' && EQUATION_BASES.includes(value);
+/** Length factors per dimension — an area is two lengths, a volume three. */
+export const LENGTH_EXPONENT = {
+    length: 1,
+    area: 2,
+    volume: 3,
+};
+/** The unit naming `base` at a measurement dimension, e.g. ('ft','area') -> 'sq_ft'. */
+export const unitForBase = (base, dimension) => UNIT_BY_BASE[base]?.[LENGTH_EXPONENT[dimension]] ?? null;
+/**
+ * The equation base a unit belongs to, or null for units outside the five
+ * anchorable families (yd², liters, gallons, degrees, radians).
+ */
+export const equationBaseOfUnit = (unit) => {
+    const base = unitBase(unit);
+    return isEquationBase(base) ? base : null;
+};
 export const unitsForDimension = (dimension) => Object.keys(CALCULATOR_UNIT_INFO).filter((u) => CALCULATOR_UNIT_INFO[u].dimension === dimension);
 /**
  * A unit's token and its disambiguating qualifier as separate pieces. The

package/dist/calculator/validate.d.ts

@@ -164,6 +164,13 @@ export declare const calculatorDefinitionSchema: z.ZodObject<{
         expression: z.ZodString;
         variableToFieldId: z.ZodRecord<z.ZodString, z.ZodString>;
         variableColumnIds: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        base: z.ZodOptional<z.ZodEnum<{
+            in: "in";
+            ft: "ft";
+            m: "m";
+            mm: "mm";
+            cm: "cm";
+        }>>;
         variableUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         resultUnit: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;

package/dist/calculator/validate.js

@@ -2,8 +2,8 @@ import { z } from 'zod';
 import { ColumnType, DecimalTolerance, FractionalTolerance, } from '../types/firestore.js';
 import { CALCULATOR_SCHEMA_VERSION, bindingDimension, equationForField, fieldDimension, isEquationTargetKind, isNumericFieldKind, } from './schema.js';
 import { conversionBindingLabel, conversionCellValue, conversionColumnLabel, conversionColumns, findConversionColumn, hasMultipleConversionColumns, } from './conversionTable.js';
-import { CALCULATOR_UNIT_INFO, unitDimension, } from './units.js';
-import { MATHJS_CONSTANTS, inferExpressionUnit, isEquivalentUnit, parseExpression, producesCanonicalValue, unitScaleRatio, } from './expressionUnits.js';
+import { CALCULATOR_UNIT_INFO, EQUATION_BASES, isEquationBase, unitDimension, } from './units.js';
+import { MATHJS_CONSTANTS, deriveVariableUnits, inferExpressionUnit, isEquivalentUnit, parseExpression, producesCanonicalValue, unitScaleRatio, } from './expressionUnits.js';
 import { isCalculatorCategoryId } from './categories.js';
 // ---------------------------------------------------------------------------
 // Definition validation: zod for structure, plus the cross-field invariants
@@ -106,6 +106,7 @@ const calculatorEquationSchema = z.object({
     expression: z.string().min(1),
     variableToFieldId: z.record(z.string(), z.string()),
     variableColumnIds: z.record(z.string(), z.string()).optional(),
+    base: z.enum(EQUATION_BASES).optional(),
     variableUnits: z.record(z.string(), calculatorUnitSchema).optional(),
     resultUnit: calculatorUnitSchema.optional(),
 });
@@ -402,7 +403,14 @@ export const validateCalculatorDefinition = (input) => {
         // The unit the EXPRESSION produces, which is what `resultUnit` claims to
         // be. Hoisted out of the `target` branch because the number-target check
         // further down needs it too.
-        const inferred = inferExpressionUnit(def.fields, eq);
+        //
+        // Inferred from what the equation will ACTUALLY evaluate with: for a
+        // base-anchored equation that is the derived units, not whatever the
+        // document stores. Otherwise a stale cache would make every check below
+        // reason about units the evaluator is going to ignore.
+        const inferred = inferExpressionUnit(def.fields, isEquationBase(eq.base)
+            ? { ...eq, variableUnits: deriveVariableUnits(eq.base, def.fields, eq) }
+            : eq);
         if (target) {
             const dim = fieldDimension(target);
             if (eq.resultUnit != null) {
@@ -427,6 +435,11 @@ export const validateCalculatorDefinition = (input) => {
                 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 (isEquationBase(eq.base)) {
+                    // Derived from the base at evaluation time, so it can be neither
+                    // missing nor mis-scaled — the two checks below exist only for the
+                    // pre-base form, where the result unit was an unverified assertion.
+                }
                 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}"` : ''}.`);
@@ -444,8 +457,24 @@ export const validateCalculatorDefinition = (input) => {
                     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');
+            // Base-anchored equations cannot mix bases — every unit comes from the
+            // one base — so this only ever fires on the pre-base authored form.
+            //
+            // Checked PER AXIS. A length and an angle in one expression is ordinary
+            // (trig consumes the angle and hands back a ratio); two length bases
+            // never is. And read off `lengthBases`/`angleBases` rather than `bases`,
+            // because `bases` describes the result: `(A_in * B_in) / C_ft²` cancels
+            // to a dimensionless count, leaving `bases` empty and the 144× scale
+            // error it carries completely invisible here.
+            if (inferred.ok && !isEquationBase(eq.base)) {
+                for (const [axis, axisBases] of [
+                    ['length', inferred.lengthBases],
+                    ['angle', inferred.angleBases],
+                ]) {
+                    if (axisBases.length < 2)
+                        continue;
+                    push('mixed-base-units', `${path}.variableUnits`, `Variables mix ${axisBases.join(' and ')} in one expression, so ${axis === 'length' ? 'lengths' : 'angles'} of different scales are being combined as if they were the same — the result is silently off by a fixed factor. Put them all in one unit, or set the equation's base.`);
+                }
             }
             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');
@@ -468,7 +497,13 @@ export const validateCalculatorDefinition = (input) => {
         // authoring where a µm-scale value in a unitless field is intended, and
         // nothing gates on `ok`: mobile only console.warns in __DEV__, and the
         // web editor shows the banner without blocking save.
+        //
+        // Cannot happen once an equation has a base: every dimensioned binding
+        // gets a unit derived from it, so there is no way for a canonical value to
+        // reach the scope. Skipped rather than left to read the absent
+        // `variableUnits` and report every variable as unitless.
         if (target?.kind === ColumnType.Number &&
+            !isEquationBase(eq.base) &&
             (!inferred.ok || inferred.dimension !== 'none')) {
             for (const [variable, fieldId] of Object.entries(eq.variableToFieldId)) {
                 const mapped = fieldById.get(fieldId);

package/dist/utils/micrometersToUnit.js

@@ -24,6 +24,27 @@ export const roundToT1Values = (value, u) => {
             return Math.round(value / 500) * 500;
     }
 };
+/**
+ * Lowest terms. A fraction is read off a tape, so the denominator has to be
+ * the smallest one that names the value: 2/16 is written 1/8, never "6 2/16".
+ * The tolerance sets the PRECISION the value is rounded to, not the
+ * denominator it prints with.
+ */
+const reduceFraction = (numerator, denominator) => {
+    let a = numerator;
+    let b = denominator;
+    while (b !== 0) {
+        [a, b] = [b, a % b];
+    }
+    const divisor = a || 1;
+    return [numerator / divisor, denominator / divisor];
+};
+/**
+ * Re-apply the sign to a composite string built from a magnitude. Guards the
+ * `-0` case: a value that rounds to nothing at the current tolerance reads as
+ * plain zero, not as a negative.
+ */
+const signPrefix = (signed, body) => signed < 0 && /[1-9]/.test(body) ? `-${body}` : body;
 export const convertMicrometers = (micrometers, unit, fractionalTolerance, decimalTolerance) => {
     if (micrometers == null || isNaN(micrometers)) {
         return { value: 'NaN', unit: '' };
@@ -39,18 +60,22 @@ export const convertMicrometers = (micrometers, unit, fractionalTolerance, decim
                 displayUnit = 'in';
                 if (unit === Units.FractionalInches) {
                     const denominator = parseInt(fractionalTolerance, 10);
-                    const whole = Math.floor(inches);
-                    const fractional = inches - whole;
-                    const numerator = Math.round(fractional * denominator);
+                    // Split the MAGNITUDE, then re-apply the sign: Math.floor walks away
+                    // from zero on a negative, so -6 1/8 came out as `-7 7/8`.
+                    const magnitude = Math.abs(inches);
+                    const whole = Math.floor(magnitude);
+                    const numerator = Math.round((magnitude - whole) * denominator);
                     if (numerator === denominator) {
                         value = `${whole + 1}`;
                     }
+                    else if (numerator === 0) {
+                        value = `${whole}`;
+                    }
                     else {
-                        value =
-                            numerator === 0
-                                ? `${whole}`
-                                : `${whole} ${numerator}/${denominator}`;
+                        const [num, den] = reduceFraction(numerator, denominator);
+                        value = `${whole} ${num}/${den}`;
                     }
+                    value = signPrefix(inches, value);
                 }
                 else {
                     value = inches.toFixed(decimalTolerance.length - 2);
@@ -61,28 +86,45 @@ export const convertMicrometers = (micrometers, unit, fractionalTolerance, decim
             case Units.FeetInchesFractional:
             case Units.FeetInchesDecimal: {
                 const feet = converted.toNumber('ft');
-                const wholeFeet = Math.floor(feet);
-                const fractionalFeet = feet - wholeFeet;
+                // Both COMPOSITE feet-inches units split the magnitude and re-apply the
+                // sign (see the fractional-inch branch) — otherwise -5' 6" printed as
+                // `-6' 6"`. Plain decimal feet keeps the signed value: toFixed renders
+                // that correctly on its own.
+                const composite = unit === Units.FeetInchesFractional ||
+                    unit === Units.FeetInchesDecimal;
+                const magnitudeFeet = composite ? Math.abs(feet) : feet;
+                const wholeFeet = Math.floor(magnitudeFeet);
+                const fractionalFeet = magnitudeFeet - wholeFeet;
                 displayUnit = 'ft';
                 if (unit === Units.FeetInchesFractional) {
                     const inches = fractionalFeet * 12;
-                    const wholeInches = Math.floor(inches);
-                    const fractional = inches - wholeInches;
                     const denominator = parseInt(fractionalTolerance, 10);
-                    const numerator = Math.round(fractional * denominator);
+                    let wholeInches = Math.floor(inches);
+                    let numerator = Math.round((inches - wholeInches) * denominator);
+                    // Carry, twice: a fraction that rounds up to a whole inch becomes an
+                    // inch, and a twelfth inch becomes a foot. Without the second carry
+                    // 5.9999 ft printed as `5' 12"`.
                     if (numerator === denominator) {
-                        value = `${wholeFeet}' ${wholeInches + 1}"`;
+                        numerator = 0;
+                        wholeInches += 1;
+                    }
+                    let displayFeet = wholeFeet;
+                    if (wholeInches === 12) {
+                        wholeInches = 0;
+                        displayFeet += 1;
+                    }
+                    if (numerator === 0) {
+                        value = `${displayFeet}' ${wholeInches}"`;
                     }
                     else {
-                        value =
-                            numerator === 0
-                                ? `${wholeFeet}' ${wholeInches}"`
-                                : `${wholeFeet}' ${wholeInches} ${numerator}/${denominator}"`;
+                        const [num, den] = reduceFraction(numerator, denominator);
+                        value = `${displayFeet}' ${wholeInches} ${num}/${den}"`;
                     }
+                    value = signPrefix(feet, value);
                 }
                 else if (unit === Units.FeetInchesDecimal) {
                     const inches = (fractionalFeet * 12).toFixed(decimalTolerance.length - 2);
-                    value = `${wholeFeet}' ${inches}"`;
+                    value = signPrefix(feet, `${wholeFeet}' ${inches}"`);
                 }
                 else {
                     value = feet.toFixed(decimalTolerance.length - 2);

package/package.json

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