@reekon-tools/boldr-utils 1.10.2 → 1.11.0

package/dist/calculator/chips.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedField } from './runtime.js';
+export declare const CALC_COLORS: {
+    /** Ink on the white/light-grey chips. */
+    readonly text: "#181A1C";
+    readonly chipBg: "#E8EAED";
+    readonly chipBorder: "#BCBEC2";
+    readonly letterBg: "#E8EAED";
+    readonly focusRing: "#FFAD00";
+    readonly focusFill: "#FFF8DB";
+    /** A value the user (or a tool) typed. */
+    readonly entered: "#0066FF";
+    readonly enteredLetter: "#50A6FF";
+    /** A value the equation solved for. */
+    readonly computed: "#BD30A8";
+    readonly computedLetter: "#6C155F";
+    /**
+     * A value that disagrees with its equation. RED, not a fourth blue: blue
+     * means entered and purple means calculated, so a navy chip read as a third
+     * kind of VALUE rather than as a problem — and its number stayed legible
+     * enough to cut against. Red is the app's warning colour everywhere else.
+     */
+    readonly conflict: "#E83D2F";
+    readonly conflictLetter: "#DA1100";
+    readonly conflictClear: "#E83D2F";
+};
+export type ChipState = 'empty' | 'entered' | 'computed' | 'conflict' | 'default';
+export declare const chipStateOf: (resolved: ResolvedField) => ChipState;
+export declare const CHIP_STYLE: Record<ChipState, {
+    background: string;
+    letterBackground: string;
+    text: string;
+}>;

package/dist/calculator/chips.js

@@ -0,0 +1,79 @@
+// The value-state palette every calculator surface paints with: mobile's table
+// rows and diagram cards, and the web viewer's read-only cards. It lives here
+// (not in either app) because the COLOR IS THE MEANING — blue says a human
+// typed it, purple says the calculator worked it out, red says the two
+// disagree. A surface that re-derives that mapping locally is one refactor away
+// from telling a crew a computed number was measured.
+//
+// The runtime is a light paper island on both platforms — frame `5287:108428`
+// samples a `#2B2C2E` header over an `#E8EAED` canvas with `#FFFFFF` field
+// cards. That is the exact opposite of the BASIC calculator (`5365:17187`),
+// which is fully dark. Do not "fix" one to match the other.
+import { FormColors, FormulaColors, GeneralColors, RedColors, TileColors, YellowColors, } from '../theme/colors.js';
+export const CALC_COLORS = {
+    /** Ink on the white/light-grey chips. */
+    text: GeneralColors.darkGrey,
+    chipBg: FormColors.lightGrey2,
+    chipBorder: FormColors.lightGrey1,
+    letterBg: FormColors.lightGrey2,
+    focusRing: YellowColors.mainYellow,
+    // A pale cream wash for "focused and empty, waiting for the keypad". It only
+    // exists on the light canvas and has no palette equivalent — mainYellow at
+    // low alpha goes muddy over lightGrey2.
+    focusFill: '#FFF8DB',
+    /** A value the user (or a tool) typed. */
+    entered: TileColors.activeBlue,
+    enteredLetter: TileColors.lightBlue1,
+    /** A value the equation solved for. */
+    computed: FormulaColors.purple,
+    computedLetter: FormulaColors.darkPurple,
+    /**
+     * A value that disagrees with its equation. RED, not a fourth blue: blue
+     * means entered and purple means calculated, so a navy chip read as a third
+     * kind of VALUE rather than as a problem — and its number stayed legible
+     * enough to cut against. Red is the app's warning colour everywhere else.
+     */
+    conflict: RedColors.red,
+    conflictLetter: RedColors.warningRed,
+    conflictClear: RedColors.red,
+};
+export const chipStateOf = (resolved) => {
+    if (resolved.conflict)
+        return 'conflict';
+    if (resolved.origin === 'user' || resolved.origin === 'tool')
+        return 'entered';
+    if (resolved.origin === 'computed' || resolved.origin === 'solved')
+        return 'computed';
+    if (resolved.origin === 'default')
+        return 'default';
+    return 'empty';
+};
+export const CHIP_STYLE = {
+    empty: {
+        background: GeneralColors.white,
+        letterBackground: CALC_COLORS.letterBg,
+        text: CALC_COLORS.text,
+    },
+    default: {
+        background: GeneralColors.white,
+        letterBackground: CALC_COLORS.letterBg,
+        text: CALC_COLORS.text,
+    },
+    entered: {
+        background: CALC_COLORS.entered,
+        letterBackground: CALC_COLORS.enteredLetter,
+        text: GeneralColors.white,
+    },
+    computed: {
+        background: CALC_COLORS.computed,
+        letterBackground: CALC_COLORS.computedLetter,
+        text: GeneralColors.white,
+    },
+    conflict: {
+        background: CALC_COLORS.conflict,
+        letterBackground: CALC_COLORS.conflictLetter,
+        // Full white: the chip shows a dash, and a dash has to be legible. The old
+        // 55% wash existed to de-emphasise a number that is no longer drawn.
+        text: GeneralColors.white,
+    },
+};

package/dist/calculator/display.d.ts

@@ -0,0 +1,78 @@
+import { type CalculatorUnit } from './units.js';
+import type { CalculatorDefinition, CalculatorField } from './schema.js';
+import type { ResolvedField } from './runtime.js';
+export type UnitSystem = 'imperial' | 'metric';
+export type DisplayUnitOverrides = Readonly<Record<string, CalculatorUnit>>;
+/** The unit a field currently displays in (session override > field default). */
+export declare const displayUnitFor: (field: CalculatorField, overrides?: DisplayUnitOverrides) => CalculatorUnit | null;
+/** Units the picker offers for a field; empty for unit-less kinds. */
+export declare const allowedDisplayUnits: (field: CalculatorField) => CalculatorUnit[];
+/**
+ * Parse raw keypad text (in the given display unit) into a canonical value.
+ * Fractions and mixed numbers are accepted for measurements and angles
+ * (mirrors the web editor's EditEquation semantics). Returns null when the
+ * draft isn't parseable yet — callers keep the last good value.
+ */
+export declare const parseFieldInput: (field: CalculatorField, unit: CalculatorUnit | null, raw: string) => number | null;
+/** Format a canonical value for display in the given unit. */
+export declare const formatFieldValue: (field: CalculatorField, unit: CalculatorUnit | null, canonical: number) => {
+    value: string;
+    unit: string;
+};
+/**
+ * What a conflicting field shows INSTEAD of its number. A value the runtime
+ * knows disagrees with its equation must not be readable as a measurement —
+ * someone cuts to what's on the screen — so the number is withheld rather than
+ * dimmed, and the detail sheet is where the entered value is recoverable.
+ * Same em dash the empty-output placeholder uses.
+ */
+export declare const CONFLICT_DASH = "\u2014";
+/**
+ * The text every value surface shows for a resolved field — table row, diagram
+ * stamp, and the detail sheet's card all route through here so the conflict
+ * dash can't ship in one of them and not the others. Null means "nothing to
+ * show": the caller draws its own empty placeholder.
+ */
+export declare const resolvedValueText: (field: CalculatorField, unit: CalculatorUnit | null, resolved: ResolvedField) => string | null;
+/**
+ * The letter chip a field wears in both the diagram badges and the table
+ * rows: sequential A, B, C… over the definition's fields (Instructions
+ * excluded — they carry no value).
+ */
+export declare const letterLabelFor: (definition: Pick<CalculatorDefinition, "fields">, fieldId: string) => string;
+/**
+ * Whether a user-entered value and a freshly computed one count as the same
+ * number: they format identically in the field's DEFAULT unit at its
+ * configured tolerance (i.e. the user couldn't tell them apart), with a tiny
+ * absolute/relative epsilon as a float-noise backstop. Deliberately ignores
+ * session unit overrides so conflict-ness doesn't change with the unit
+ * toggle.
+ */
+export declare const valuesAgree: (field: CalculatorField, entered: number, computed: number) => boolean;
+/** The structured draft the fraction keypad edits. All parts are digit text. */
+export interface KeypadParts {
+    negative: boolean;
+    /** Feet, in feet-inches mode only. */
+    feet: string;
+    /** Whole number (or decimal text in decimal mode). */
+    whole: string;
+    numerator: string;
+    denominator: string;
+}
+export declare const emptyKeypadParts: () => KeypadParts;
+export type KeypadMode = 'decimal' | 'fractional' | 'feetFractional';
+/** Which keypad layout a display unit gets. */
+export declare const keypadModeForUnit: (unit: CalculatorUnit | null) => KeypadMode;
+/**
+ * Convert a keypad draft into a canonical value for the field. Returns null
+ * when the draft is empty/incomplete (callers keep the previous value).
+ * Feet-inches composes feet + fractional inches directly, since a single
+ * "F W N/D" string has no parseable representation in a feet unit.
+ */
+export declare const keypadPartsToCanonical: (field: CalculatorField, unit: CalculatorUnit | null, parts: KeypadParts) => number | null;
+/**
+ * Overrides implementing the English/Metric toggle: every measurement field
+ * flips to its dimension's preferred unit (constrained to allowedUnits).
+ * Fields whose pick equals their default get no override. Angles stay put.
+ */
+export declare const mapUnitSystem: (definition: Pick<CalculatorDefinition, "fields">, system: UnitSystem) => Record<string, CalculatorUnit>;

package/dist/calculator/display.js

@@ -0,0 +1,223 @@
+// Display-unit edge of the calculator runtime: parsing keypad input into
+// canonical values, formatting canonical values back out, per-field unit
+// choices, and the letter labels shared by diagram badges and table rows.
+// Pure functions only, shared by every consuming runtime (mobile's run screen,
+// the web read-only viewer) so a value can't render two ways.
+import { ColumnType, Units } from '../types/firestore.js';
+import { formatCanonical, parseToCanonical, unitsForDimension, } from './units.js';
+/** The unit a field currently displays in (session override > field default). */
+export const displayUnitFor = (field, overrides = {}) => {
+    switch (field.kind) {
+        case ColumnType.Measurement:
+            return overrides[field.id] ?? field.unit.defaultUnit;
+        case ColumnType.Angle:
+            return overrides[field.id] ?? field.angleUnit ?? 'deg';
+        default:
+            return null;
+    }
+};
+/** Units the picker offers for a field; empty for unit-less kinds. */
+export const allowedDisplayUnits = (field) => {
+    switch (field.kind) {
+        case ColumnType.Measurement: {
+            const allowed = field.unit.allowedUnits?.length
+                ? field.unit.allowedUnits
+                : unitsForDimension(field.unit.dimension);
+            return allowed.includes(field.unit.defaultUnit)
+                ? allowed
+                : [field.unit.defaultUnit, ...allowed];
+        }
+        case ColumnType.Angle:
+            return ['deg', 'rad'];
+        default:
+            return [];
+    }
+};
+/**
+ * Parse raw keypad text (in the given display unit) into a canonical value.
+ * Fractions and mixed numbers are accepted for measurements and angles
+ * (mirrors the web editor's EditEquation semantics). Returns null when the
+ * draft isn't parseable yet — callers keep the last good value.
+ */
+export const parseFieldInput = (field, unit, raw) => {
+    switch (field.kind) {
+        case ColumnType.Measurement:
+        case ColumnType.Angle:
+            return unit ? parseToCanonical(raw, unit) : null;
+        case ColumnType.Number: {
+            const trimmed = raw.trim();
+            if (trimmed === '')
+                return null;
+            const parsed = Number(trimmed);
+            return Number.isFinite(parsed) ? parsed : null;
+        }
+        default:
+            return null;
+    }
+};
+// Matches the web editor's unit-less number formatting (6 significant
+// figures, no trailing zeros).
+const trimNumber = (value) => Number.isFinite(value) ? Number(value.toPrecision(6)).toString() : 'NaN';
+/** Format a canonical value for display in the given unit. */
+export const formatFieldValue = (field, unit, canonical) => {
+    if (!unit)
+        return { value: trimNumber(canonical), unit: '' };
+    return formatCanonical(canonical, unit, field.kind === ColumnType.Measurement
+        ? {
+            fractionalTolerance: field.unit.fractionalTolerance,
+            decimalTolerance: field.unit.decimalTolerance,
+        }
+        : undefined);
+};
+/**
+ * What a conflicting field shows INSTEAD of its number. A value the runtime
+ * knows disagrees with its equation must not be readable as a measurement —
+ * someone cuts to what's on the screen — so the number is withheld rather than
+ * dimmed, and the detail sheet is where the entered value is recoverable.
+ * Same em dash the empty-output placeholder uses.
+ */
+export const CONFLICT_DASH = '—';
+/**
+ * The text every value surface shows for a resolved field — table row, diagram
+ * stamp, and the detail sheet's card all route through here so the conflict
+ * dash can't ship in one of them and not the others. Null means "nothing to
+ * show": the caller draws its own empty placeholder.
+ */
+export const resolvedValueText = (field, unit, resolved) => {
+    if (resolved.conflict)
+        return CONFLICT_DASH;
+    if (resolved.value == null)
+        return null;
+    if (typeof resolved.value === 'number') {
+        return formatFieldValue(field, unit, resolved.value).value;
+    }
+    return Array.isArray(resolved.value)
+        ? resolved.value.join(', ')
+        : String(resolved.value);
+};
+// 0 -> A, 25 -> Z, 26 -> AA ...
+const indexToLetters = (index) => {
+    let label = '';
+    let i = index;
+    do {
+        label = String.fromCharCode(65 + (i % 26)) + label;
+        i = Math.floor(i / 26) - 1;
+    } while (i >= 0);
+    return label;
+};
+/**
+ * The letter chip a field wears in both the diagram badges and the table
+ * rows: sequential A, B, C… over the definition's fields (Instructions
+ * excluded — they carry no value).
+ */
+export const letterLabelFor = (definition, fieldId) => {
+    let index = 0;
+    for (const field of definition.fields) {
+        if (field.kind === ColumnType.Instructions)
+            continue;
+        if (field.id === fieldId)
+            return indexToLetters(index);
+        index++;
+    }
+    return '';
+};
+/**
+ * Whether a user-entered value and a freshly computed one count as the same
+ * number: they format identically in the field's DEFAULT unit at its
+ * configured tolerance (i.e. the user couldn't tell them apart), with a tiny
+ * absolute/relative epsilon as a float-noise backstop. Deliberately ignores
+ * session unit overrides so conflict-ness doesn't change with the unit
+ * toggle.
+ */
+export const valuesAgree = (field, entered, computed) => {
+    const unit = displayUnitFor(field, {});
+    const enteredText = formatFieldValue(field, unit, entered).value;
+    const computedText = formatFieldValue(field, unit, computed).value;
+    if (enteredText === computedText)
+        return true;
+    const epsilon = Math.max(1e-6, 1e-9 * Math.abs(computed));
+    return Math.abs(entered - computed) <= epsilon;
+};
+// Preferred display units per dimension for the header's unit-system toggle,
+// best-first. The pick is constrained to each field's allowedUnits.
+const SYSTEM_PREFERENCES = {
+    imperial: {
+        length: [
+            Units.FractionalInches,
+            Units.FeetInchesFractional,
+            Units.Inches,
+            Units.Feet,
+            Units.FeetInchesDecimal,
+        ],
+        area: ['sq_ft', 'sq_in', 'sq_yd'],
+        volume: ['cu_ft', 'cu_in', 'cu_yd', 'gallon'],
+    },
+    metric: {
+        length: [Units.Millimeters, Units.Centimeters, Units.Meters],
+        area: ['sq_m', 'sq_cm', 'sq_mm'],
+        volume: ['cu_m', 'liter', 'cu_cm', 'cu_mm'],
+    },
+};
+export const emptyKeypadParts = () => ({
+    negative: false,
+    feet: '',
+    whole: '',
+    numerator: '',
+    denominator: '',
+});
+/** Which keypad layout a display unit gets. */
+export const keypadModeForUnit = (unit) => {
+    if (unit === Units.FractionalInches)
+        return 'fractional';
+    if (unit === Units.FeetInchesFractional)
+        return 'feetFractional';
+    return 'decimal';
+};
+const fractionText = (parts) => {
+    const { whole, numerator, denominator } = parts;
+    const hasFraction = numerator !== '' && denominator !== '' && denominator !== '0';
+    const body = hasFraction
+        ? `${whole || '0'} ${numerator}/${denominator}`
+        : whole;
+    return body;
+};
+/**
+ * Convert a keypad draft into a canonical value for the field. Returns null
+ * when the draft is empty/incomplete (callers keep the previous value).
+ * Feet-inches composes feet + fractional inches directly, since a single
+ * "F W N/D" string has no parseable representation in a feet unit.
+ */
+export const keypadPartsToCanonical = (field, unit, parts) => {
+    const sign = parts.negative ? -1 : 1;
+    if (keypadModeForUnit(unit) === 'feetFractional') {
+        if (parts.feet === '' && fractionText(parts) === '')
+            return null;
+        const feetUm = parseToCanonical(parts.feet || '0', Units.Feet);
+        const inchesUm = parseToCanonical(fractionText(parts) || '0', Units.Inches);
+        if (feetUm == null || inchesUm == null)
+            return null;
+        return sign * (feetUm + inchesUm);
+    }
+    const text = fractionText(parts);
+    if (text === '')
+        return null;
+    const parsed = parseFieldInput(field, unit, text);
+    return parsed == null ? null : sign * parsed;
+};
+/**
+ * Overrides implementing the English/Metric toggle: every measurement field
+ * flips to its dimension's preferred unit (constrained to allowedUnits).
+ * Fields whose pick equals their default get no override. Angles stay put.
+ */
+export const mapUnitSystem = (definition, system) => {
+    const overrides = {};
+    for (const field of definition.fields) {
+        if (field.kind !== ColumnType.Measurement)
+            continue;
+        const allowed = allowedDisplayUnits(field);
+        const pick = SYSTEM_PREFERENCES[system][field.unit.dimension].find((unit) => allowed.includes(unit));
+        if (pick && pick !== field.unit.defaultUnit)
+            overrides[field.id] = pick;
+    }
+    return overrides;
+};

package/dist/calculator/index.d.ts

@@ -6,4 +6,7 @@ export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';
 export * from './instance.js';
+export * from './runtime.js';
+export * from './display.js';
+export * from './chips.js';
 export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, type IssueSeverity, type ValidationIssue, type ValidationResult, } from './validate.js';

package/dist/calculator/index.js

@@ -1,7 +1,9 @@
 // Construction Calculator shared module: the calculator-definition schema,
-// per-field unit system, forward evaluator, two-way numeric solver, and
-// definition validation. Pure logic (mathjs + zod only — no Skia/React), safe
-// on web, native, and Node.
+// per-field unit system, forward evaluator, two-way numeric solver, definition
+// validation, and the consumption-time runtime (derive pass + display
+// formatting + value-state palette) that turns a saved instance into what a
+// screen shows. Pure logic (mathjs + zod only — no Skia/React), safe on web,
+// native, and Node.
 export * from './schema.js';
 export * from './categories.js';
 export * from './units.js';
@@ -10,4 +12,7 @@ export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';
 export * from './instance.js';
+export * from './runtime.js';
+export * from './display.js';
+export * from './chips.js';
 export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, } from './validate.js';

package/dist/calculator/runtime.d.ts

@@ -0,0 +1,61 @@
+import { type CalculatorDefinition, type CalculatorFieldValue } from './schema.js';
+import type { CalculatorEntryAttribution, CalculatorFieldEntry } from './instance.js';
+export type ResolvedOrigin = 'user' | 'tool' | 'computed' | 'solved' | 'default' | 'empty';
+export interface ResolvedField {
+    /** Canonical value to display; null when empty/blocked. */
+    value: CalculatorFieldValue | null;
+    origin: ResolvedOrigin;
+    /**
+     * Over-constrained: this entry sits on an equation target whose freshly
+     * computed value disagrees beyond the field's display tolerance. Reachable
+     * only when the displacement pass below can't move anything — EVERY entry
+     * deciding it is locked, or nothing left is invertible. UI: RED chip
+     * with the value withheld behind a dash — clearing the entry, or unlocking a
+     * participant, resolves it.
+     */
+    conflict: {
+        computedValue: number;
+    } | null;
+    /** Eval/solve error attributable to this field's equation. */
+    error: string | null;
+    /** When its equation is blocked: the field ids still needed. */
+    missingFieldIds: string[];
+    /** Which equation computed/solved this value. */
+    viaEquationId: string | null;
+    locked: boolean;
+    /**
+     * Populating this field can only end in a conflict, so entry is refused
+     * outright (Asana 1217172568173859). True when the row is showing a
+     * CALCULATED value and every other field on its governing equation is
+     * entered AND locked: the displacement pass then has nothing left to
+     * yield, so a typed value would land as the red conflict chip instead of
+     * steering the calculation. Unlocking any one of them clears it.
+     */
+    populationBlocked: boolean;
+    attribution: CalculatorEntryAttribution | null;
+}
+export interface EquationStatus {
+    equationId: string;
+    targetFieldId: string;
+    /** Variables ∪ target — drives the link badges on participating rows. */
+    participantFieldIds: string[];
+    state: 'computed' | 'solved-a-field' | 'blocked' | 'error';
+    /** The field this equation was inverted for (wears the '=' badge). */
+    solvedFieldId: string | null;
+}
+export interface DerivedRuntime {
+    resolved: Record<string, ResolvedField>;
+    equations: EquationStatus[];
+    /** fieldId -> equation ids it participates in (focus highlighting). */
+    equationsByField: Record<string, string[]>;
+}
+export declare const EMPTY_DERIVED: DerivedRuntime;
+export declare const deriveRuntime: (definition: Pick<CalculatorDefinition, "fields" | "equations">, entries: Readonly<Record<string, CalculatorFieldEntry>>, options?: {
+    solveEnabled?: boolean;
+}) => DerivedRuntime;
+/**
+ * `populationBlocked` for a single field — the one rule the reducer's guards
+ * and the UI's entry affordances share, so a refused "+" and a refused tape
+ * reading can never disagree about which fields are enterable.
+ */
+export declare const isPopulationBlocked: (definition: Pick<CalculatorDefinition, "fields" | "equations">, entries: Readonly<Record<string, CalculatorFieldEntry>>, fieldId: string) => boolean;

package/dist/calculator/runtime.js

@@ -0,0 +1,430 @@
+// The derive pass: everything the calculator UI shows that isn't a raw entry.
+// deriveRuntime(definition, entries) is a pure function — computed outputs,
+// solved fields, conflicts, equation badges all fall out of it, recomputed
+// after every mutation. Nothing here is stored, so it can never go stale.
+//
+// This is the ENGINE both runtimes share: mobile's editable run screen and the
+// web read-only viewer. A saved instance therefore re-derives identically on
+// either platform, which is the whole point — the numbers a crew reads on the
+// desktop preview are the numbers the phone showed when it saved.
+import { ColumnType } from '../types/firestore.js';
+import { equationForField, findField, } from './schema.js';
+import { evaluateOutputs } from './evaluate.js';
+import { solveForField } from './solve.js';
+import { valuesAgree } from './display.js';
+export const EMPTY_DERIVED = {
+    resolved: {},
+    equations: [],
+    equationsByField: {},
+};
+const EMPTY_RESOLVED = {
+    conflict: null,
+    error: null,
+    missingFieldIds: [],
+    viaEquationId: null,
+    locked: false,
+    populationBlocked: false,
+    attribution: null,
+};
+const solveHintsOf = (field) => field.kind === ColumnType.Number ||
+    field.kind === ColumnType.Measurement ||
+    field.kind === ColumnType.Angle
+    ? field.solve
+    : undefined;
+const entryOrigin = (entry) => entry.source === 'tool' ? 'tool' : 'user';
+const isNumericField = (field) => field?.kind === ColumnType.Number ||
+    field?.kind === ColumnType.Measurement ||
+    field?.kind === ColumnType.Angle;
+/** Variables ∪ target — the fields an equation ties together. */
+const participantsOf = (equation) => [
+    ...new Set([
+        ...Object.values(equation.variableToFieldId),
+        equation.targetFieldId,
+    ]),
+];
+/**
+ * The definition as the solver should see it while inverting `equation` for
+ * `fieldId` under the displacement rule below: whether this field may be
+ * calculated is a RUNTIME question there (the user left it unlocked), so the
+ * authored hints contribute their brackets but not their veto.
+ */
+const definitionForDisplacement = (definition, fieldId, equation) => ({
+    equations: definition.equations,
+    fields: definition.fields.map((field) => {
+        if (field.id !== fieldId)
+            return field;
+        if (field.kind !== ColumnType.Number &&
+            field.kind !== ColumnType.Measurement &&
+            field.kind !== ColumnType.Angle) {
+            return field;
+        }
+        return {
+            ...field,
+            solve: {
+                ...field.solve,
+                solvable: true,
+                governingEquationId: equation.id,
+            },
+        };
+    }),
+});
+export const deriveRuntime = (definition, entries, options) => {
+    const solveEnabled = options?.solveEnabled ?? true;
+    // 1. Project entries to canonical values. Defaults are NOT merged here —
+    //    numericFieldValue falls back to field.defaultValue during evaluation
+    //    and solving, so equations see them for free.
+    const values = {};
+    for (const [fieldId, entry] of Object.entries(entries)) {
+        values[fieldId] = entry.value;
+    }
+    const fieldOrder = new Map(definition.fields.map((f, index) => [f.id, index]));
+    /** fieldId -> equation ids it participates in. */
+    const equationsByField = {};
+    for (const equation of definition.equations) {
+        for (const fieldId of participantsOf(equation)) {
+            (equationsByField[fieldId] ?? (equationsByField[fieldId] = [])).push(equation.id);
+        }
+    }
+    const equationById = new Map(definition.equations.map((e) => [e.id, e]));
+    const equationTargeting = (fieldId) => definition.equations.find((e) => e.targetFieldId === fieldId);
+    /**
+     * Entries the displacement rule set aside. Shadowing is PRESENTATION: the
+     * entry stays in state untouched, so clearing whatever over-determined the
+     * equation brings the original number straight back, and a saved instance
+     * re-derives identically on reopen.
+     */
+    const shadowed = new Set();
+    /** A value the user is currently holding — an entry no shadow has set aside. */
+    const isPinned = (shadows, fieldId) => entries[fieldId] != null && !shadows.has(fieldId);
+    /** Entries (minus shadows) ∪ solved — what the runtime knows right now. */
+    const knownValues = (shadows, solved) => {
+        const known = {};
+        for (const [id, value] of Object.entries(values)) {
+            if (!shadows.has(id))
+                known[id] = value;
+        }
+        for (const [id, s] of Object.entries(solved))
+            known[id] = s.value;
+        return known;
+    };
+    // 2. Solve pass. Two halves: PROPAGATION works out everything derivable from
+    //    the values the user is holding, and DISPLACEMENT decides which held
+    //    values have to give way when they can't all hold at once.
+    /**
+     * Every value the runtime can pin down for a given shadow set, to a fixpoint
+     * so each filled-in value cascades into the next equation. Two rules:
+     *
+     *  - a SHADOWED field is taken over by the first equation that can invert for
+     *    it. The lock is the gate the user actually operates, so the authored
+     *    `solvable` hint gets no veto here — it only lends its brackets (see
+     *    definitionForDisplacement). Which equation ends up with the field is not
+     *    fixed: releasing another entry can hand it to a different one, which is
+     *    exactly how the newest entry takes the wheel below.
+     *  - an EMPTY field fills itself in only when its author marked it solvable.
+     *    solveForField enforces the exactly-one-missing rule (missing-target /
+     *    missing-inputs fail silently), so under-determined systems stay empty.
+     *
+     * Pure in `shadows`, so displacement can try a release and throw it away.
+     */
+    const propagate = (shadows) => {
+        const solved = {};
+        let progressed = true;
+        let sweeps = 0;
+        while (progressed && sweeps++ <= definition.fields.length) {
+            progressed = false;
+            for (const field of definition.fields) {
+                if (solved[field.id] || isPinned(shadows, field.id))
+                    continue;
+                if (!shadows.has(field.id)) {
+                    const hints = solveHintsOf(field);
+                    if (!hints?.solvable || !hints.governingEquationId)
+                        continue;
+                    const result = solveForField({
+                        definition,
+                        fieldId: field.id,
+                        values: knownValues(shadows, solved),
+                    });
+                    if (result.ok) {
+                        solved[field.id] = {
+                            value: result.value,
+                            viaEquationId: hints.governingEquationId,
+                        };
+                        progressed = true;
+                    }
+                    continue;
+                }
+                // A displaced equation TARGET needs no inversion — the forward pass
+                // (step 3) recomputes it from everything else.
+                if (equationTargeting(field.id) || !isNumericField(field))
+                    continue;
+                for (const equationId of equationsByField[field.id] ?? []) {
+                    const equation = equationById.get(equationId);
+                    if (!equation)
+                        continue;
+                    const result = solveForField({
+                        definition: definitionForDisplacement(definition, field.id, equation),
+                        fieldId: field.id,
+                        values: knownValues(shadows, solved),
+                    });
+                    if (!result.ok)
+                        continue;
+                    solved[field.id] = { value: result.value, viaEquationId: equationId };
+                    progressed = true;
+                    break;
+                }
+            }
+        }
+        return solved;
+    };
+    const evaluateAll = (shadows, solved) => evaluateOutputs({ definition, values: knownValues(shadows, solved) });
+    /**
+     * Can this equation still be satisfied as things stand? Two ways it can't,
+     * and both are asking the same question — is there anywhere left to put the
+     * answer:
+     *
+     *  (i)  every participant is pinned by an entry, so the equation has no free
+     *       field to calculate (Asana 1217042186684890 — filling in the last
+     *       field should show a result, not demand one be cleared by hand);
+     *  (ii) its target is pinned and disagrees with what the rest of the
+     *       calculator makes of it. That's the red conflict chip, caught one step
+     *       before step 4 draws it — and unlike (i) it fires even when the
+     *       disagreement arrives through a field ANOTHER equation solved.
+     */
+    const isOverConstrained = (equation, shadows, results) => {
+        if (participantsOf(equation).every((id) => isPinned(shadows, id)))
+            return true;
+        if (!isPinned(shadows, equation.targetFieldId))
+            return false;
+        const target = findField(definition, equation.targetFieldId);
+        const result = results[equation.targetFieldId];
+        const entered = entries[equation.targetFieldId].value;
+        return (target != null &&
+            result?.ok === true &&
+            typeof entered === 'number' &&
+            !valuesAgree(target, entered, result.value));
+    };
+    /**
+     * Every field whose entry decides this equation's value: its participants,
+     * plus — transitively — the participants of whatever equation supplied a
+     * participant the user isn't holding.
+     *
+     * The reach matters (Asana 1217332117501004). In the reported cuboid, the
+     * surface-area equation reads a length the VOLUME equation solved, so the
+     * stale volume entry is what has to give way — and it appears nowhere in the
+     * surface-area equation itself. Walking only the participants leaves the
+     * newest entry with nothing it may displace, and it lands as a red chip.
+     */
+    const determinants = (equation, shadows, solved) => {
+        const fields = new Set();
+        const visited = new Set();
+        const queue = [equation.id];
+        while (queue.length > 0) {
+            const equationId = queue.pop();
+            if (visited.has(equationId))
+                continue;
+            visited.add(equationId);
+            for (const fieldId of participantsOf(equationById.get(equationId) ?? equation)) {
+                fields.add(fieldId);
+                // A held value is decided by its own entry and nothing further back.
+                if (isPinned(shadows, fieldId))
+                    continue;
+                const via = solved[fieldId]?.viaEquationId ?? equationTargeting(fieldId)?.id;
+                if (via)
+                    queue.push(via);
+            }
+        }
+        return [...fields];
+    };
+    let solved = solveEnabled ? propagate(shadowed) : {};
+    let results = evaluateAll(shadowed, solved);
+    if (solveEnabled) {
+        // DISPLACEMENT. While some equation can't be satisfied, the OLDEST unlocked
+        // entry deciding it yields to the calculation.
+        //
+        // Every lock the user set is a value they asked to hold, so what's left
+        // unlocked is what the calculation may move; age breaks the tie, oldest
+        // first, because the newer number is the better statement of intent.
+        //
+        // The NEWEST entry is spared: it's what the user just typed, and
+        // calculating over it would swallow the keystroke. The one exception is
+        // when it is the ONLY thing left unlocked — sparing it there just paints
+        // the red chip and makes them clear it by hand. Locking that last free
+        // field is what pins the whole equation and brings the chip back.
+        //
+        // A release only sticks if it lands: the field has to end up calculated AND
+        // the equation actually satisfied. Otherwise it's rolled back and the next
+        // oldest tries, then the next — and when none of them work, the conflict
+        // chip stands, which is the honest answer.
+        for (let round = 0; round <= definition.fields.length; round++) {
+            let released = false;
+            for (const equation of definition.equations) {
+                if (!isOverConstrained(equation, shadowed, results))
+                    continue;
+                const byAge = determinants(equation, shadowed, solved)
+                    .filter((id) => isPinned(shadowed, id) && !entries[id].locked)
+                    .sort((a, b) => (entries[a].enteredAt ?? 0) - (entries[b].enteredAt ?? 0) ||
+                    (fieldOrder.get(a) ?? 0) - (fieldOrder.get(b) ?? 0));
+                const candidates = byAge.length === 1 ? byAge : byAge.slice(0, -1);
+                for (const candidate of candidates) {
+                    const trial = new Set(shadowed).add(candidate);
+                    const trialSolved = propagate(trial);
+                    const trialResults = evaluateAll(trial, trialSolved);
+                    const calculated = trialSolved[candidate] != null ||
+                        trialResults[candidate]?.ok === true;
+                    if (!calculated)
+                        continue;
+                    if (isOverConstrained(equation, trial, trialResults))
+                        continue;
+                    shadowed.add(candidate);
+                    solved = trialSolved;
+                    results = trialResults;
+                    released = true;
+                    break;
+                }
+                // One release re-decides which equation owns which field, so rescan
+                // from the top rather than carrying on with stale statuses.
+                if (released)
+                    break;
+            }
+            if (!released)
+                break;
+        }
+    }
+    // 3. The forward pass over entries ∪ solved (`results`, above) serves both
+    //    output display and conflict detection.
+    // 4. Resolve each field.
+    const resolved = {};
+    for (const field of definition.fields) {
+        // A shadowed entry resolves exactly as if the field were empty — computed
+        // if it's an equation target, solved otherwise — so the row shows the
+        // calculated value, not the number the displacement rule set aside.
+        const entry = shadowed.has(field.id) ? undefined : entries[field.id];
+        const equation = equationForField(definition, field.id);
+        const result = equation ? results[field.id] : undefined;
+        const base = {
+            ...EMPTY_RESOLVED,
+            value: null,
+            origin: 'empty',
+            locked: entry?.locked ?? false,
+            attribution: entry?.attribution ?? null,
+        };
+        if (field.kind === ColumnType.Instructions) {
+            resolved[field.id] = base;
+            continue;
+        }
+        if (equation && result) {
+            if (result.ok) {
+                if (entry && typeof entry.value === 'number') {
+                    resolved[field.id] = {
+                        ...base,
+                        value: entry.value,
+                        origin: entryOrigin(entry),
+                        viaEquationId: equation.id,
+                        conflict: valuesAgree(field, entry.value, result.value)
+                            ? null
+                            : { computedValue: result.value },
+                    };
+                }
+                else {
+                    resolved[field.id] = {
+                        ...base,
+                        value: result.value,
+                        origin: 'computed',
+                        viaEquationId: equation.id,
+                    };
+                }
+            }
+            else if (result.reason === 'missing-inputs') {
+                resolved[field.id] = entry
+                    ? { ...base, value: entry.value, origin: entryOrigin(entry) }
+                    : { ...base, missingFieldIds: result.missingFieldIds };
+            }
+            else {
+                resolved[field.id] = {
+                    ...base,
+                    value: entry?.value ?? null,
+                    origin: entry ? entryOrigin(entry) : 'empty',
+                    error: result.error,
+                };
+            }
+            continue;
+        }
+        if (entry) {
+            resolved[field.id] = {
+                ...base,
+                value: entry.value,
+                origin: entryOrigin(entry),
+            };
+            continue;
+        }
+        const solvedField = solved[field.id];
+        if (solvedField) {
+            resolved[field.id] = {
+                ...base,
+                value: solvedField.value,
+                origin: 'solved',
+                viaEquationId: solvedField.viaEquationId,
+            };
+            continue;
+        }
+        // Instructions were handled above, so every remaining kind may carry one.
+        if (field.defaultValue != null) {
+            resolved[field.id] = {
+                ...base,
+                value: field.defaultValue,
+                origin: 'default',
+            };
+            continue;
+        }
+        resolved[field.id] = base;
+    }
+    // 4b. Which calculated fields refuse entry (see ResolvedField.populationBlocked).
+    //     A separate pass because it reads the resolved origin: only a field the
+    //     runtime is CURRENTLY calculating can be blocked — an empty one is just
+    //     waiting for a value, and one showing its own entry can be retyped or
+    //     cleared.
+    for (const field of definition.fields) {
+        const current = resolved[field.id];
+        if (current.origin !== 'computed' && current.origin !== 'solved')
+            continue;
+        const equation = definition.equations.find((candidate) => candidate.id === current.viaEquationId);
+        if (!equation)
+            continue;
+        const others = participantsOf(equation).filter((id) => id !== field.id);
+        // `every` over the ENTERED test as well: a participant left to a default
+        // (no entry at all) can't be unlocked, so telling the user to unlock
+        // something wouldn't be true — that case keeps the conflict chip.
+        if (others.length > 0 &&
+            others.every((id) => entries[id]?.locked === true)) {
+            resolved[field.id] = { ...current, populationBlocked: true };
+        }
+    }
+    // 5. Equation statuses for the link/'=' badges.
+    const equations = definition.equations.map((equation) => {
+        const participantFieldIds = participantsOf(equation);
+        const solvedFieldId = Object.entries(solved).find(([, s]) => s.viaEquationId === equation.id)?.[0] ?? null;
+        const result = results[equation.targetFieldId];
+        const state = solvedFieldId
+            ? 'solved-a-field'
+            : result?.ok
+                ? 'computed'
+                : result && !result.ok && result.reason === 'missing-inputs'
+                    ? 'blocked'
+                    : 'error';
+        return {
+            equationId: equation.id,
+            targetFieldId: equation.targetFieldId,
+            participantFieldIds,
+            state,
+            solvedFieldId,
+        };
+    });
+    return { resolved, equations, equationsByField };
+};
+/**
+ * `populationBlocked` for a single field — the one rule the reducer's guards
+ * and the UI's entry affordances share, so a refused "+" and a refused tape
+ * reading can never disagree about which fields are enterable.
+ */
+export const isPopulationBlocked = (definition, entries, fieldId) => deriveRuntime(definition, entries).resolved[fieldId]?.populationBlocked ===
+    true;

package/dist/types/firestore.d.ts

@@ -92,6 +92,7 @@ export interface Template extends Timestamps {
     orgId: string;
     orgName: string;
     parentFolderId?: string | null;
+    formulas?: Formula[];
 }
 export interface SelectedTemplate extends FirestoreDoc {
     count: number;

package/package.json

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