formlab-mcp 0.6.49 → 0.6.51

package/vendor/cost.js

@@ -0,0 +1,2619 @@
+// ============================================================
+// COST — per-ingredient pricing, currency conversion, formulation
+// cost rollup. The shape of ing.cost is:
+//   { value: number, currency: 'USD', unit: 'kg', source: 'manual'
+//     | 'csv' | 'erp', updatedAt: ISO8601 }
+// ============================================================
+
+const COST_CURRENCIES = [
+  { code: 'USD', symbol: '$',  label: 'US Dollar'         },
+  { code: 'EUR', symbol: '€',  label: 'Euro'              },
+  { code: 'GBP', symbol: '£',  label: 'British Pound'     },
+  { code: 'JPY', symbol: '¥',  label: 'Japanese Yen'      },
+  { code: 'CNY', symbol: '¥',  label: 'Chinese Yuan'      },
+  { code: 'CAD', symbol: 'C$', label: 'Canadian Dollar'   },
+  { code: 'AUD', symbol: 'A$', label: 'Australian Dollar' },
+  { code: 'CHF', symbol: 'Fr', label: 'Swiss Franc'       },
+  { code: 'INR', symbol: '₹',  label: 'Indian Rupee'      },
+  { code: 'BRL', symbol: 'R$', label: 'Brazilian Real'    },
+  // Asia-Pacific + Mexico (2026-09-09): all four are ECB reference currencies,
+  // so Frankfurter serves live rates for them like the rest.
+  { code: 'SGD', symbol: 'S$', label: 'Singapore Dollar'  },
+  { code: 'HKD', symbol: 'HK$', label: 'Hong Kong Dollar' },
+  { code: 'KRW', symbol: '₩',  label: 'South Korean Won'  },
+  { code: 'MXN', symbol: 'MX$', label: 'Mexican Peso'     },
+  // PKR is NOT an ECB reference currency, so Frankfurter (our primary FX
+  // source) doesn't price it. It's live-rated via the secondary source in
+  // _backfillMissingFxRates; see the note there. Added 2026-10-02 for a
+  // Pakistan-based compounder.
+  { code: 'PKR', symbol: '₨',  label: 'Pakistani Rupee'   },
+];
+// Picker order: USD / EUR / GBP pinned on top, the rest alphabetical by code —
+// so a new currency slots into place instead of landing at the end of the list.
+(function () {
+  const pinned = ['USD', 'EUR', 'GBP'];
+  COST_CURRENCIES.sort((a, b) => {
+    const pa = pinned.indexOf(a.code), pb = pinned.indexOf(b.code);
+    if (pa !== -1 || pb !== -1) return (pa === -1 ? 99 : pa) - (pb === -1 ? 99 : pb);
+    return a.code < b.code ? -1 : a.code > b.code ? 1 : 0;
+  });
+})();
+
+// Built-in mass units → kg
+const MASS_TO_KG = {
+  µg: 1e-9, ug: 1e-9, mcg: 1e-9,
+  mg: 1e-6, cg: 1e-5, dg: 1e-4, g: 0.001,
+  hg: 0.1, kg: 1,
+  t: 1000, ton: 1000, tonne: 1000,
+  lb: 0.45359237, oz: 0.0283495, grain: 6.479891e-5, stone: 6.35029,
+};
+// Built-in volume units → L
+const VOL_TO_L = {
+  µL: 1e-6, uL: 1e-6,
+  mL: 0.001, cL: 0.01, dL: 0.1, L: 1,
+  m3: 1000, 'm³': 1000,
+  cm3: 0.001, 'cm³': 0.001,
+  dm3: 1, 'dm³': 1,
+  gal: 3.78541, 'gal_uk': 4.54609, pt: 0.473176, qt: 0.946353,
+  tsp: 0.00492892, tbsp: 0.0147868, cup: 0.24,
+  fl_oz: 0.0295735, 'fl oz': 0.0295735,
+  drum: 208.198, bbl: 158.987,
+};
+// Built-in length units → m
+const LENGTH_TO_M = {
+  µm: 1e-6, um: 1e-6,
+  mm: 0.001, cm: 0.01, m: 1, km: 1000,
+  in: 0.0254, ft: 0.3048, yd: 0.9144, mi: 1609.34,
+};
+
+// === Custom-unit overlay ===
+// Reads db.customUnits and merges with built-ins. Format:
+//   db.customUnits = {
+//     'bag-50kg': { dimension: 'mass',   factorToBase: 50 },
+//     'pail-5gal':{ dimension: 'volume', factorToBase: 18.927 },
+//     'each':     { dimension: 'count' }                       // no conversion
+//   }
+function _customMassUnits() {
+  const out = {};
+  const cu = (typeof db !== 'undefined' && db?.customUnits) || {};
+  for (const [k, v] of Object.entries(cu)) {
+    if (v?.dimension === 'mass'   && isFinite(v.factorToBase) && v.factorToBase > 0) out[k] = v.factorToBase;
+  }
+  return out;
+}
+function _customVolUnits() {
+  const out = {};
+  const cu = (typeof db !== 'undefined' && db?.customUnits) || {};
+  for (const [k, v] of Object.entries(cu)) {
+    if (v?.dimension === 'volume' && isFinite(v.factorToBase) && v.factorToBase > 0) out[k] = v.factorToBase;
+  }
+  return out;
+}
+function _customLengthUnits() {
+  const out = {};
+  const cu = (typeof db !== 'undefined' && db?.customUnits) || {};
+  for (const [k, v] of Object.entries(cu)) {
+    if (v?.dimension === 'length' && isFinite(v.factorToBase) && v.factorToBase > 0) out[k] = v.factorToBase;
+  }
+  return out;
+}
+function getMassUnits()   { return { ...MASS_TO_KG,   ..._customMassUnits()   }; }
+function getVolUnits()    { return { ...VOL_TO_L,     ..._customVolUnits()    }; }
+function getLengthUnits() { return { ...LENGTH_TO_M,  ..._customLengthUnits() }; }
+function isMassUnit(u)    { return u != null && (u in MASS_TO_KG   || u in _customMassUnits()); }
+function isVolUnit(u)     { return u != null && (u in VOL_TO_L     || u in _customVolUnits()); }
+function isLengthUnit(u)  { return u != null && (u in LENGTH_TO_M  || u in _customLengthUnits()); }
+function massToKg(u)      { return MASS_TO_KG[u]  ?? _customMassUnits()[u]   ?? null; }
+function volToL(u)        { return VOL_TO_L[u]    ?? _customVolUnits()[u]    ?? null; }
+function lengthToM(u)     { return LENGTH_TO_M[u] ?? _customLengthUnits()[u] ?? null; }
+
+function getCostUnits() {
+  const customCount = Object.entries((typeof db !== 'undefined' && db?.customUnits) || {})
+    .filter(([_, v]) => v?.dimension === 'count').map(([k]) => k);
+  return [
+    ...Object.keys(getMassUnits()),
+    ...Object.keys(getVolUnits()),
+    ...Object.keys(getLengthUnits()),
+    'each',
+    ...customCount,
+  ];
+}
+
+// ============================================================
+// SHARED UNIT DATALISTS — make every unit field type-to-filter
+// ------------------------------------------------------------
+// A native <select> of ~30 units means scrolling to find one. Instead,
+// unit inputs are <input list="fl-units-…"> referencing one of these
+// shared <datalist>s: the user can just type ("ml", "lb") to filter,
+// or open it to browse. Common units are listed first. Rebuilt on
+// load and whenever a custom unit is added.
+function getAllUnits() {
+  const builtin = [
+    'wt%', 'vol%',
+    ...Object.keys(getMassUnits()),
+    ...Object.keys(getVolUnits()),
+    ...Object.keys(getLengthUnits()),
+    'ppm', 'ppb', 'eq', 'mol', 'each',
+  ];
+  const custom = Object.keys((typeof db !== 'undefined' && db?.customUnits) || {});
+  return [...new Set([...builtin, ...custom])];
+}
+function ensureUnitDatalists() {
+  if (typeof document === 'undefined' || !document.body) return;
+  const q = (s) => String(s).replace(/"/g, '&quot;');
+  const make = (id, units) => {
+    let dl = document.getElementById(id);
+    if (!dl) { dl = document.createElement('datalist'); dl.id = id; document.body.appendChild(dl); }
+    dl.innerHTML = units.map((u) => `<option value="${q(u)}"></option>`).join('');
+  };
+  make('fl-units-all', getAllUnits());   // composition / batch quantity
+  make('fl-units-cost', getCostUnits());  // ingredient set-price (mass/vol/length/each)
+  make('fl-units-qty', getQuantityUnits()); // physical quantity made (mass/vol/count, no fractions)
+}
+
+// Units for a physical quantity made (sample / batch yield): mass, volume,
+// count — NOT fractions (wt%/ppm), which only make sense in a recipe ratio.
+// Mirrors the curated set the old <select> used (`_quantityUnitOptions`).
+function getQuantityUnits() {
+  const mass  = ['mg', 'g', 'kg', 'ton', 'lb', 'oz'];
+  const vol   = ['µL', 'mL', 'L', 'tsp', 'tbsp', 'cup', 'fl_oz', 'pt', 'qt', 'gal', 'drum'];
+  const count = ['units', 'each'];
+  const custom = Object.keys((typeof db !== 'undefined' && db?.customUnits) || {});
+  return [...new Set([...mass, ...vol, ...count, ...custom])];
+}
+
+// ============================================================
+// Unit combobox — replaces the native <datalist> popup.
+// ------------------------------------------------------------
+// The native datalist dropdown mis-anchors to the top-left of the window when
+// its <input> lives inside a position:fixed modal (a long-standing Chromium
+// bug) — it showed up as a stray "floating fill box". So unit inputs now carry
+// `class="fl-unit-combo" data-unit-list="<datalist id>"` (NOT `list=`), and we
+// render our own correctly-positioned, type-to-filter suggestion list off the
+// same datalist options. Free typing still works (custom units are allowed);
+// the list is just suggestions. Delegated listeners cover inputs created later
+// (modals, dynamic ingredient rows) with no per-field wiring.
+(function initUnitCombo() {
+  if (typeof document === 'undefined') return;
+  var POP_ID = 'fl-unit-combo-pop';
+  var activeInput = null, activeIdx = -1;
+  // Show the in-popup search box once a list has more than this many units.
+  var SEARCH_THRESHOLD = 8;
+
+  function escA(s) { return String(s).replace(/"/g, '&quot;'); }
+  function escH(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+  function isCombo(el) { return !!(el && el.classList && el.classList.contains('fl-unit-combo')); }
+  function popEl() {
+    var p = document.getElementById(POP_ID);
+    if (!p) { p = document.createElement('div'); p.id = POP_ID; p.className = 'fl-unit-combo-pop'; p.style.display = 'none'; document.body.appendChild(p); }
+    return p;
+  }
+  function isOpen() { var p = document.getElementById(POP_ID); return !!(p && p.style.display !== 'none'); }
+  function optionsFor(input) {
+    var dl = document.getElementById(input.getAttribute('data-unit-list') || '');
+    return dl ? Array.prototype.map.call(dl.children, function (o) { return o.value; }) : [];
+  }
+  function listEl() { var p = document.getElementById(POP_ID); return p ? p.querySelector('.fl-unit-combo-list') : null; }
+  function items() { var l = listEl(); return l ? Array.prototype.slice.call(l.querySelectorAll('.fl-unit-combo-item')) : []; }
+
+  // Classify a unit into a display group. Mirrors the formula picker's grouping
+  // (Mass / Volume / Length …) and uses the same isMassUnit/isVolUnit helpers
+  // so custom units land in the right bucket too.
+  function classify(u) {
+    if (['wt%', 'vol%', '%', 'ppm', 'ppb'].indexOf(u) !== -1) return 'frac';
+    if (typeof isMassUnit === 'function' && isMassUnit(u)) return 'mass';
+    if (typeof isVolUnit === 'function' && isVolUnit(u)) return 'vol';
+    if (typeof isLengthUnit === 'function' && isLengthUnit(u)) return 'len';
+    if (['mol', 'eq', 'each', 'pcs', 'unit', 'units'].indexOf(u) !== -1) return 'amt';
+    return 'other';
+  }
+  var GROUP_ORDER = [['frac', 'Fraction'], ['mass', 'Mass'], ['vol', 'Volume'], ['len', 'Length'], ['amt', 'Amount / count'], ['other', 'Other']];
+  function groupUnits(units) {
+    var by = {};
+    units.forEach(function (u) { var k = classify(u); (by[k] = by[k] || []).push(u); });
+    return GROUP_ORDER.map(function (p) { return { label: p[1], units: by[p[0]] || [] }; }).filter(function (g) { return g.units.length; });
+  }
+
+  function position(input) {
+    var p = popEl(), r = input.getBoundingClientRect();
+    p.style.position = 'fixed';
+    p.style.minWidth = r.width + 'px';
+    p.style.top = (r.bottom + 2) + 'px';
+    p.style.left = r.left + 'px';
+    var h = p.offsetHeight;
+    if (r.bottom + 2 + h > window.innerHeight - 8) p.style.top = Math.max(8, r.top - h - 2) + 'px';
+    var w = p.offsetWidth, left = r.left;
+    if (left + w > window.innerWidth - 8) left = Math.max(8, window.innerWidth - w - 8);
+    p.style.left = left + 'px';
+  }
+
+  // Re-render ONLY the grouped list for a filter query (keeps the search box —
+  // and its focus/caret — intact across keystrokes).
+  function renderList(input, query) {
+    var l = listEl(); if (!l) return;
+    var q = String(query || '').trim();
+    var ql = q.toLowerCase();
+    var all = optionsFor(input);
+    var cur = String(input.value || '').trim().toLowerCase();
+    var matches = all.filter(function (u) { return !ql || u.toLowerCase().indexOf(ql) !== -1; });
+    var html = groupUnits(matches).map(function (g) {
+      return '<div class="fl-unit-combo-group">' + escH(g.label) + '</div>' +
+        g.units.map(function (u) {
+          return '<div class="fl-unit-combo-item' + (u.toLowerCase() === cur ? ' current' : '') + '" data-val="' + escA(u) + '">' + escH(u) + '</div>';
+        }).join('');
+    }).join('');
+    // Free-typed custom unit: offer to use it verbatim when it isn't an option.
+    var exact = all.some(function (u) { return u.toLowerCase() === ql; });
+    if (q && !exact) html += '<div class="fl-unit-combo-item fl-unit-combo-custom" data-val="' + escA(q) + '">Use “' + escH(q) + '”</div>';
+    if (!html) html = '<div class="fl-unit-combo-empty">No matching units</div>';
+    l.innerHTML = html;
+    activeIdx = -1;
+    position(input);
+  }
+
+  function open(input) {
+    activeInput = input;
+    var p = popEl();
+    var showSearch = optionsFor(input).length > SEARCH_THRESHOLD;
+    p.innerHTML =
+      (showSearch ? '<div class="fl-unit-combo-searchwrap"><input type="text" class="fl-unit-combo-search" placeholder="Search units…" autocomplete="off" spellcheck="false"></div>' : '') +
+      '<div class="fl-unit-combo-list"></div>';
+    p.style.display = 'block';
+    if (showSearch) {
+      var sb = p.querySelector('.fl-unit-combo-search');
+      sb.addEventListener('input', function () { renderList(input, sb.value); });
+      sb.addEventListener('keydown', navKeydown);
+      sb.addEventListener('blur', function () {
+        setTimeout(function () {
+          var pp = document.getElementById(POP_ID);
+          if (pp && !pp.contains(document.activeElement) && document.activeElement !== input) hide();
+        }, 120);
+      });
+    }
+    renderList(input, '');
+    position(input);
+    // Move focus into the search box so the user can type to filter (matches
+    // the ingredient picker). The field keeps the chosen value.
+    if (showSearch) setTimeout(function () { var sb2 = p.querySelector('.fl-unit-combo-search'); if (sb2) sb2.focus(); }, 0);
+  }
+  function hide() { var p = document.getElementById(POP_ID); if (p) p.style.display = 'none'; activeIdx = -1; }
+  function choose(val) {
+    var inp = activeInput; if (!inp) return;
+    inp.value = val;
+    inp.dispatchEvent(new Event('input', { bubbles: true }));
+    inp.dispatchEvent(new Event('change', { bubbles: true }));
+    hide();
+    try { inp.focus(); } catch (_) {}
+  }
+  function highlight(i) {
+    var its = items(); if (!its.length) { activeIdx = -1; return; }
+    activeIdx = (i + its.length) % its.length;
+    its.forEach(function (el, idx) { el.classList.toggle('active', idx === activeIdx); });
+    var c = its[activeIdx]; if (c && c.scrollIntoView) c.scrollIntoView({ block: 'nearest' });
+  }
+  // Shared arrow/Enter/Esc handling for both the field and the search box.
+  function navKeydown(e) {
+    if (!isOpen()) { if (e.key === 'ArrowDown' && activeInput) { open(activeInput); e.preventDefault(); } return; }
+    if (e.key === 'ArrowDown') { highlight(activeIdx + 1); e.preventDefault(); }
+    else if (e.key === 'ArrowUp') { highlight(activeIdx - 1); e.preventDefault(); }
+    else if (e.key === 'Enter') {
+      var its = items();
+      var pick = activeIdx >= 0 ? its[activeIdx] : (its.length === 1 ? its[0] : null);
+      if (pick) { choose(pick.getAttribute('data-val')); e.preventDefault(); }
+    } else if (e.key === 'Escape') { hide(); if (activeInput) try { activeInput.focus(); } catch (_) {} }
+  }
+
+  document.addEventListener('focusin', function (e) { if (isCombo(e.target)) open(e.target); });
+  // Typing directly in the field filters too (only matters when there's no
+  // search box — i.e. short lists; otherwise focus is in the search box).
+  document.addEventListener('input', function (e) {
+    if (isCombo(e.target) && isOpen() && !(document.getElementById(POP_ID) || {}).querySelector('.fl-unit-combo-search')) {
+      renderList(e.target, e.target.value);
+    }
+  });
+  document.addEventListener('keydown', function (e) { if (isCombo(e.target)) navKeydown(e); });
+  // mousedown (capture) so a click on a suggestion wins over the input's blur.
+  document.addEventListener('mousedown', function (e) {
+    if (!isOpen()) return;
+    var item = e.target.closest && e.target.closest('.fl-unit-combo-item');
+    if (item) { e.preventDefault(); choose(item.getAttribute('data-val')); return; }
+    var p = document.getElementById(POP_ID);
+    if (e.target !== activeInput && !(p && p.contains(e.target))) hide();
+  }, true);
+  document.addEventListener('focusout', function (e) {
+    if (!isCombo(e.target)) return;
+    setTimeout(function () {
+      var p = document.getElementById(POP_ID);
+      if (p && p.contains(document.activeElement)) return;   // focus moved into the popup (search box)
+      if (isCombo(document.activeElement)) return;
+      hide();
+    }, 120);
+  });
+  window.addEventListener('scroll', function () { if (activeInput && isOpen()) position(activeInput); }, true);
+  window.addEventListener('resize', hide);
+})();
+
+// Backwards-compat alias — older code paths reference COST_UNITS directly.
+// We can't make it a live getter without breaking destructuring, so anyone
+// hitting it gets the snapshot taken when cost.js loaded. New code should
+// call getCostUnits() instead.
+const COST_UNITS = [
+  ...Object.keys(MASS_TO_KG),
+  ...Object.keys(VOL_TO_L),
+  'each',
+];
+
+// ============================================================
+// COST ESTIMATES — rough market prices for common ingredients,
+// used by the "⚲ Lookup" button in the Ingredient Edit modal as
+// a best-effort default. Values are approximate spot/bulk prices
+// in USD and meant as a starting point — the user should verify
+// against their actual vendor.
+// ============================================================
+const COST_ESTIMATES = {
+  // Food / commodity
+  'water':              { value: 0.002, unit: 'L'  },
+  'wheat flour':        { value: 1.20,  unit: 'kg' },
+  'flour':              { value: 1.20,  unit: 'kg' },
+  'rye flour':          { value: 1.80,  unit: 'kg' },
+  'rice flour':         { value: 2.40,  unit: 'kg' },
+  'salt':               { value: 0.85,  unit: 'kg' },
+  'sodium chloride':    { value: 0.85,  unit: 'kg' },
+  'sugar':              { value: 0.90,  unit: 'kg' },
+  'sucrose':            { value: 0.90,  unit: 'kg' },
+  'yeast':              { value: 18.50, unit: 'kg' },
+  'active dry yeast':   { value: 18.50, unit: 'kg' },
+  'olive oil':          { value: 7.50,  unit: 'L'  },
+  'sunflower oil':      { value: 2.20,  unit: 'L'  },
+  'butter':             { value: 8.50,  unit: 'kg' },
+  // Solvents / chemicals
+  'ethanol':            { value: 0.85,  unit: 'L'  },
+  'methanol':           { value: 0.55,  unit: 'L'  },
+  'isopropanol':        { value: 1.50,  unit: 'L'  },
+  'glycerin':           { value: 1.50,  unit: 'kg' },
+  'glycerol':           { value: 1.50,  unit: 'kg' },
+  'propylene glycol':   { value: 1.80,  unit: 'kg' },
+  'ethylene glycol':    { value: 1.20,  unit: 'kg' },
+  'acetone':            { value: 1.10,  unit: 'L'  },
+  // Industrial / formulation
+  'titanium dioxide':   { value: 3.40,  unit: 'kg' },
+  'calcium carbonate':  { value: 0.30,  unit: 'kg' },
+  'silica':             { value: 1.20,  unit: 'kg' },
+  'sodium hydroxide':   { value: 0.80,  unit: 'kg' },
+  'citric acid':        { value: 1.40,  unit: 'kg' },
+  'stearic acid':       { value: 2.00,  unit: 'kg' },
+  'lauric acid':        { value: 2.50,  unit: 'kg' },
+  'methylcellulose':    { value: 7.50,  unit: 'kg' },
+  'methyl cellulose':   { value: 7.50,  unit: 'kg' },
+  'acrylic latex':      { value: 2.10,  unit: 'kg' },
+  'acrylic latex emulsion': { value: 2.10, unit: 'kg' },
+  // Personal-care
+  'cetyl alcohol':      { value: 3.50,  unit: 'kg' },
+  'beeswax':            { value: 25.00, unit: 'kg' },
+  'lanolin':            { value: 18.00, unit: 'kg' },
+  'shea butter':        { value: 12.00, unit: 'kg' },
+  // Surfactants / detergents
+  'sodium lauryl sulfate':          { value: 2.00,  unit: 'kg' },
+  'sls':                            { value: 2.00,  unit: 'kg' },
+  'sodium laureth sulfate':         { value: 1.80,  unit: 'kg' },
+  'sles':                           { value: 1.80,  unit: 'kg' },
+  'cocamidopropyl betaine':         { value: 2.60,  unit: 'kg' },
+  'linear alkylbenzene sulfonate':  { value: 1.60,  unit: 'kg' },
+  'alcohol ethoxylate':             { value: 2.20,  unit: 'kg' },
+  'nonionic surfactant':            { value: 2.20,  unit: 'kg' },
+  'decyl glucoside':                { value: 4.00,  unit: 'kg' },
+  // Thickeners / rheology / fillers
+  'hydroxyethyl cellulose':         { value: 7.50,  unit: 'kg' },
+  'sodium polyacrylate':            { value: 2.50,  unit: 'kg' },
+  'carbomer':                       { value: 16.00, unit: 'kg' },
+  'xanthan gum':                    { value: 6.00,  unit: 'kg' },
+  'guar gum':                       { value: 3.50,  unit: 'kg' },
+  'carrageenan':                    { value: 12.00, unit: 'kg' },
+  'bentonite':                      { value: 0.60,  unit: 'kg' },
+  'kaolin':                         { value: 0.50,  unit: 'kg' },
+  'talc':                           { value: 0.55,  unit: 'kg' },
+  // Preservatives / chelants
+  'phenoxyethanol':                 { value: 4.00,  unit: 'kg' },
+  'benzyl alcohol':                 { value: 2.50,  unit: 'kg' },
+  'potassium sorbate':              { value: 4.00,  unit: 'kg' },
+  'sodium benzoate':                { value: 1.80,  unit: 'kg' },
+  'benzisothiazolinone':            { value: 8.00,  unit: 'kg' },
+  'in-can preservative':            { value: 5.00,  unit: 'kg' },
+  'methylparaben':                  { value: 5.50,  unit: 'kg' },
+  'disodium edta':                  { value: 3.00,  unit: 'kg' },
+  'edta':                           { value: 3.00,  unit: 'kg' },
+  // Humectants / emollients / silicones
+  'pentylene glycol':               { value: 8.00,  unit: 'kg' },
+  'butylene glycol':                { value: 4.00,  unit: 'kg' },
+  'dipropylene glycol':             { value: 2.50,  unit: 'kg' },
+  'sorbitol':                       { value: 1.50,  unit: 'kg' },
+  'caprylic/capric triglyceride':   { value: 4.00,  unit: 'kg' },
+  'dimethicone':                    { value: 6.00,  unit: 'kg' },
+  'isopropyl myristate':            { value: 3.50,  unit: 'kg' },
+  'mineral oil':                    { value: 1.50,  unit: 'L'  },
+  'petrolatum':                     { value: 2.00,  unit: 'kg' },
+  // Cosmetic actives
+  'niacinamide':                    { value: 15.00, unit: 'kg' },
+  'sodium hyaluronate':             { value: 250.00, unit: 'kg' },
+  'hyaluronic acid':                { value: 250.00, unit: 'kg' },
+  'salicylic acid':                 { value: 6.00,  unit: 'kg' },
+  'ascorbic acid':                  { value: 8.00,  unit: 'kg' },
+  'panthenol':                      { value: 15.00, unit: 'kg' },
+  'allantoin':                      { value: 12.00, unit: 'kg' },
+  'caffeine':                       { value: 15.00, unit: 'kg' },
+  'zinc oxide':                     { value: 3.00,  unit: 'kg' },
+  // Paints / coatings
+  'styrene acrylic':                { value: 2.00,  unit: 'kg' },
+  'coalescent':                     { value: 3.50,  unit: 'kg' },
+  'texanol':                        { value: 3.50,  unit: 'kg' },
+  'defoamer':                       { value: 4.00,  unit: 'kg' },
+  'iron oxide':                     { value: 2.50,  unit: 'kg' },
+  'carbon black':                   { value: 2.00,  unit: 'kg' },
+  // Solvents (industrial)
+  'toluene':                        { value: 1.20,  unit: 'L'  },
+  'xylene':                         { value: 1.30,  unit: 'L'  },
+  'mineral spirits':                { value: 1.50,  unit: 'L'  },
+  'butyl acetate':                  { value: 2.00,  unit: 'L'  },
+  'ethyl acetate':                  { value: 1.50,  unit: 'L'  },
+  'methyl ethyl ketone':            { value: 2.00,  unit: 'L'  },
+  'butanol':                        { value: 1.60,  unit: 'L'  },
+  // Acids / bases / salts
+  'potassium hydroxide':            { value: 1.20,  unit: 'kg' },
+  'hydrochloric acid':              { value: 0.40,  unit: 'L'  },
+  'sulfuric acid':                  { value: 0.30,  unit: 'kg' },
+  'acetic acid':                    { value: 0.90,  unit: 'L'  },
+  'lactic acid':                    { value: 2.00,  unit: 'kg' },
+  'phosphoric acid':                { value: 1.20,  unit: 'kg' },
+  'ammonia':                        { value: 0.50,  unit: 'L'  },
+  'sodium carbonate':               { value: 0.40,  unit: 'kg' },
+  'soda ash':                       { value: 0.40,  unit: 'kg' },
+  'sodium bicarbonate':             { value: 0.50,  unit: 'kg' },
+  'sodium citrate':                 { value: 2.00,  unit: 'kg' },
+  'potassium chloride':             { value: 1.00,  unit: 'kg' },
+  'magnesium sulfate':              { value: 0.50,  unit: 'kg' },
+  // Food / beverage
+  'fructose':                       { value: 1.20,  unit: 'kg' },
+  'dextrose':                       { value: 1.00,  unit: 'kg' },
+  'glucose':                        { value: 1.00,  unit: 'kg' },
+  'corn syrup':                     { value: 0.80,  unit: 'kg' },
+  'malic acid':                     { value: 2.50,  unit: 'kg' },
+  'monosodium glutamate':           { value: 1.50,  unit: 'kg' },
+  'aqua':                           { value: 0.002, unit: 'L'  },
+  // Waxes / fats / fatty alcohols
+  'carnauba wax':                   { value: 10.00, unit: 'kg' },
+  'paraffin wax':                   { value: 1.50,  unit: 'kg' },
+  'microcrystalline wax':           { value: 2.50,  unit: 'kg' },
+  'coconut oil':                    { value: 2.50,  unit: 'L'  },
+  'castor oil':                     { value: 2.50,  unit: 'kg' },
+  'palm oil':                       { value: 1.20,  unit: 'kg' },
+  'cocoa butter':                   { value: 9.00,  unit: 'kg' },
+  'stearyl alcohol':                { value: 3.50,  unit: 'kg' },
+  'cetearyl alcohol':               { value: 3.50,  unit: 'kg' },
+};
+
+// Returns { value, currency, unit, source, matchedKey } or null.
+// Currency is always USD for now. Match is case-insensitive and tries
+// the full name first, then any whole-word substring match.
+function lookupIngredientCost(name) {
+  if (!name) return null;
+  const key = String(name).toLowerCase().trim();
+  if (key in COST_ESTIMATES) {
+    return { ...COST_ESTIMATES[key], currency: 'USD', source: 'estimate', matchedKey: key };
+  }
+  // Substring fallback — longest match wins so "wheat flour" beats "flour"
+  let best = null;
+  for (const [k, v] of Object.entries(COST_ESTIMATES)) {
+    if (key.includes(k) && (!best || k.length > best.key.length)) {
+      best = { key: k, ...v };
+    }
+  }
+  if (best) return { value: best.value, unit: best.unit, currency: 'USD', source: 'estimate', matchedKey: best.key };
+  return null;
+}
+
+// Add a user-defined unit, immediately available to the cost engine.
+function addCustomUnit(name, dimension, factorToBase) {
+  // sync-exempt: custom units aren't a per-record entity — they sync via the
+  // workspace_settings blob through window.__pro.onSettingsChanged() below.
+  if (typeof db === 'undefined') return false;
+  if (!name || !dimension) return false;
+  db.customUnits = db.customUnits || {};
+  if (dimension === 'count' || dimension === 'other') {
+    db.customUnits[name] = { dimension };
+  } else if (
+    (dimension === 'mass' || dimension === 'volume' || dimension === 'length') &&
+    isFinite(parseFloat(factorToBase)) && parseFloat(factorToBase) > 0
+  ) {
+    db.customUnits[name] = { dimension, factorToBase: parseFloat(factorToBase) };
+  } else {
+    return false;
+  }
+  if (typeof saveDB === 'function') saveDB();
+  registerCustomUnits();
+  ensureUnitDatalists();   // refresh the shared unit pickers with the new unit
+  try { if (typeof window !== 'undefined' && window.__pro && typeof window.__pro.onSettingsChanged === 'function') window.__pro.onSettingsChanged(); } catch (_) {}
+  return true;
+}
+
+// Remove a user-defined unit. Also strips it from the live conversion maps that
+// registerCustomUnits() populates (that fn only ADDS), so the unit vanishes from
+// pickers/conversions without a reload. Records still carrying the label keep it
+// (they just won't convert until it's re-added). Syncs via the workspace_settings
+// blob through onSettingsChanged() — so a removal now propagates across devices.
+function deleteCustomUnit(name) {
+  // sync-exempt: custom units aren't a per-record entity — see addCustomUnit.
+  if (typeof db === 'undefined' || !db || !db.customUnits || !(name in db.customUnits)) return false;
+  const def = db.customUnits[name];
+  delete db.customUnits[name];
+  if (def) {
+    if (def.dimension === 'mass')   delete MASS_TO_KG[name];
+    if (def.dimension === 'volume') delete VOL_TO_L[name];
+    if (def.dimension === 'length') delete LENGTH_TO_M[name];
+  }
+  if (typeof saveDB === 'function') saveDB();
+  registerCustomUnits();
+  if (typeof ensureUnitDatalists === 'function') ensureUnitDatalists();
+  try { if (typeof window !== 'undefined' && window.__pro && typeof window.__pro.onSettingsChanged === 'function') window.__pro.onSettingsChanged(); } catch (_) {}
+  return true;
+}
+
+// How many records still reference a unit string (for the delete warning).
+// Scans the common unit-bearing fields across the library.
+function customUnitUsageCount(name) {
+  if (typeof db === 'undefined' || !db || !name) return 0;
+  let n = 0;
+  const eq = (u) => u === name;
+  (db.ingredients || []).forEach(i => { if (i && eq(i.cost && i.cost.unit)) n++; if (i && eq(i.densityUnit)) n++; });
+  (db.formulations || []).forEach(f => (f && f.composition || []).forEach(c => { if (eq(c && c.unit)) n++; }));
+  (db.batches || []).forEach(b => { if (b && eq(b.unit)) n++; (b && b.actualComposition || []).forEach(c => { if (eq(c && c.unit)) n++; }); });
+  (db.samples || []).forEach(s => { if (s && eq(s.unit)) n++; });
+  (db.lots || []).forEach(l => { if (l && eq(l.unit)) n++; });
+  return n;
+}
+
+// Mutate MASS_TO_KG / VOL_TO_L to include user-defined units, so existing
+// `unit in MASS_TO_KG` checks throughout the cost engine pick them up with
+// no extra refactor. Idempotent — safe to call multiple times.
+function registerCustomUnits() {
+  if (typeof db === 'undefined' || !db?.customUnits) return;
+  for (const [name, def] of Object.entries(db.customUnits)) {
+    if (!def) continue;
+    const factor = parseFloat(def.factorToBase);
+    if (def.dimension === 'mass'   && isFinite(factor) && factor > 0) MASS_TO_KG[name]   = factor;
+    if (def.dimension === 'volume' && isFinite(factor) && factor > 0) VOL_TO_L[name]     = factor;
+    if (def.dimension === 'length' && isFinite(factor) && factor > 0) LENGTH_TO_M[name]  = factor;
+  }
+}
+
+// Returns the unit category by looking at both built-ins and custom units.
+//   'mass-frac' | 'vol-frac' | 'mass-abs' | 'vol-abs' | 'count' | 'unknown'
+function detectUnitDimension(unit) {
+  if (unit == null) return 'unknown';
+  const s = String(unit).trim();
+  const lower = s.toLowerCase();
+  if (lower.startsWith('wt') || s === '%') return 'mass-frac';
+  if (lower.startsWith('vol'))             return 'vol-frac';
+  if (s in MASS_TO_KG  || s in _customMassUnits())   return 'mass-abs';
+  if (s in VOL_TO_L    || s in _customVolUnits())    return 'vol-abs';
+  if (s in LENGTH_TO_M || s in _customLengthUnits()) return 'length-abs';
+  // Case-insensitive fallback for typo-tolerance
+  for (const k of Object.keys(MASS_TO_KG))   if (k.toLowerCase() === lower) return 'mass-abs';
+  for (const k of Object.keys(VOL_TO_L))     if (k.toLowerCase() === lower) return 'vol-abs';
+  for (const k of Object.keys(LENGTH_TO_M))  if (k.toLowerCase() === lower) return 'length-abs';
+  const custom = (typeof db !== 'undefined' && db?.customUnits) || {};
+  if (custom[s]?.dimension === 'count' || custom[s]?.dimension === 'other') return 'count';
+  return 'unknown';
+}
+
+function costUnitDimension(u) {
+  if (u in MASS_TO_KG) return 'mass';
+  if (u in VOL_TO_L)   return 'volume';
+  return 'other';
+}
+
+// ---- Amount "view in other units" conversion (composition table) ----
+// Curated common units shown in the click-to-convert popover. We don't
+// list every mass/volume unit the engine knows — just the ones a
+// formulator typically reaches for, so the popover stays scannable.
+const _AMT_VIEW_MASS = ['mg', 'g', 'kg', 'oz', 'lb', 'ton'];
+const _AMT_VIEW_VOL  = ['mL', 'L', 'tsp', 'tbsp', 'fl_oz', 'cup', 'gal'];
+
+function _massFactorCI(unit) {
+  if (unit in MASS_TO_KG) return MASS_TO_KG[unit];
+  const l = String(unit).toLowerCase();
+  for (const k in MASS_TO_KG) if (k.toLowerCase() === l) return MASS_TO_KG[k];
+  return null;
+}
+function _volFactorCI(unit) {
+  if (unit in VOL_TO_L) return VOL_TO_L[unit];
+  const l = String(unit).toLowerCase();
+  for (const k in VOL_TO_L) if (k.toLowerCase() === l) return VOL_TO_L[k];
+  return null;
+}
+
+// Convert `amount` (in `unit`) into the other common units of the same
+// dimension, plus a cross-dimension block (mass↔volume) when the
+// ingredient's density is known. For relative-fraction units (wt% /
+// vol%) or count/unknown units, returns a `note` instead of rows —
+// those have no absolute conversion without a batch basis.
+//
+// Returns: { dim, source:{value,unit}, same:[{unit,value}],
+//            cross:{label, rows:[{unit,value}]}|null, note:'' }  | null
+function amountConversions(amount, unit, ingredient, opts) {
+  const amt = parseFloat(amount);
+  if (!isFinite(amt)) return null;
+  const dim = (typeof detectUnitDimension === 'function') ? detectUnitDimension(unit) : 'unknown';
+  const res = { dim, source: { value: amt, unit: unit || '' }, same: [], cross: null, note: '' };
+
+  if (dim === 'mass-abs') {
+    const f = _massFactorCI(unit);
+    if (f == null) { res.note = 'Unrecognized mass unit.'; return res; }
+    const kg = amt * f;
+    res.same = _AMT_VIEW_MASS.filter(u => u !== unit).map(u => ({ unit: u, value: kg / MASS_TO_KG[u] }));
+    const d = ingredient ? _densityToKgPerL(ingredient.density, ingredient.densityUnit) : null; // kg/L
+    if (d) {
+      const L = kg / d;
+      res.cross = { label: `via density (${(+d.toFixed(3))} g/mL)`, rows: [
+        { unit: 'mL', value: L / VOL_TO_L.mL },
+        { unit: 'L',  value: L },
+      ] };
+    }
+  } else if (dim === 'vol-abs') {
+    const f = _volFactorCI(unit);
+    if (f == null) { res.note = 'Unrecognized volume unit.'; return res; }
+    const L = amt * f;
+    res.same = _AMT_VIEW_VOL.filter(u => u !== unit).map(u => ({ unit: u, value: L / VOL_TO_L[u] }));
+    const d = ingredient ? _densityToKgPerL(ingredient.density, ingredient.densityUnit) : null;
+    if (d) {
+      const kg = L * d;
+      res.cross = { label: `via density (${(+d.toFixed(3))} g/mL)`, rows: [
+        { unit: 'g',  value: kg / MASS_TO_KG.g },
+        { unit: 'kg', value: kg },
+      ] };
+    }
+  } else if (dim === 'mass-frac' || dim === 'vol-frac') {
+    // When a batch size is provided (opts.batchAmount + opts.batchUnit),
+    // materialize the fraction into an absolute amount so the click
+    // popover stops being a dead end on wt%/vol% rows. The caller passes
+    // the live Scale-to-batch state; without it we fall back to the
+    // legacy "depends on batch size" note.
+    const batchAmt  = opts && parseFloat(opts.batchAmount);
+    const batchUnit = opts && opts.batchUnit;
+    const batchKg = (isFinite(batchAmt) && batchUnit in MASS_TO_KG) ? batchAmt * MASS_TO_KG[batchUnit] : null;
+    const batchL  = (isFinite(batchAmt) && batchUnit in VOL_TO_L  ) ? batchAmt * VOL_TO_L[batchUnit]   : null;
+    const dens    = ingredient ? _densityToKgPerL(ingredient.density, ingredient.densityUnit) : null;
+    // Match the fraction dimension to the batch dimension when possible.
+    // Cross-dimension (mass-frac × volume-batch, or vol-frac × mass-batch)
+    // requires the row's density — handled below when available.
+    let absKg = null, absL = null;
+    if (dim === 'mass-frac') {
+      if (batchKg != null) absKg = (amt / 100) * batchKg;
+      else if (batchL != null && dens != null) absKg = (amt / 100) * (batchL * dens);
+    } else { // vol-frac
+      if (batchL != null) absL = (amt / 100) * batchL;
+      else if (batchKg != null && dens != null) absL = (amt / 100) * (batchKg / dens);
+    }
+    if (absKg != null) {
+      res.same = [{ unit: 'kg', value: absKg }].concat(
+        _AMT_VIEW_MASS.filter(u => u !== 'kg').map(u => ({ unit: u, value: absKg / MASS_TO_KG[u] }))
+      );
+      if (dens != null) {
+        const L = absKg / dens;
+        res.cross = { label: `via density (${(+dens.toFixed(3))} g/mL)`, rows: [
+          { unit: 'mL', value: L / VOL_TO_L.mL },
+          { unit: 'L',  value: L },
+        ] };
+      }
+      res.note = `Computed at ${batchAmt} ${batchUnit} batch.`;
+    } else if (absL != null) {
+      res.same = [{ unit: 'L', value: absL }].concat(
+        _AMT_VIEW_VOL.filter(u => u !== 'L').map(u => ({ unit: u, value: absL / VOL_TO_L[u] }))
+      );
+      if (dens != null) {
+        const kg = absL * dens;
+        res.cross = { label: `via density (${(+dens.toFixed(3))} g/mL)`, rows: [
+          { unit: 'g',  value: kg / MASS_TO_KG.g },
+          { unit: 'kg', value: kg },
+        ] };
+      }
+      res.note = `Computed at ${batchAmt} ${batchUnit} batch.`;
+    } else {
+      res.note = `"${unit}" is a relative fraction — its absolute mass/volume depends on the batch size. Set a "Scale to batch" amount above to materialize.`;
+    }
+  } else {
+    res.note = 'No unit conversions available for this unit.';
+  }
+  return res;
+}
+
+// Normalize whatever density unit the user picked into kg/L (= g/mL).
+function _densityToKgPerL(value, unit) {
+  const v = parseFloat(value);
+  if (!isFinite(v) || v <= 0) return null;
+  switch (unit) {
+    case 'g/mL': case 'kg/L': case 'g/cm³': case 'kg/dm³': return v;
+    case 'g/L': case 'mg/mL':                              return v / 1000;
+    case 'kg/m³': case 't/m³':                             return v / 1000;
+    case 'mg/L': case 'µg/mL':                             return v / 1e6;
+    default: return v;  // assume g/mL
+  }
+}
+
+// Convert an ing.cost to $/kg in the cost's own currency.
+// Returns null if conversion isn't possible (no density for vol→mass).
+function costPerKgInOwnCurrency(cost, density, densityUnit) {
+  if (!cost || cost.value == null || cost.value === '') return null;
+  const v = parseFloat(cost.value);
+  if (!isFinite(v)) return null;
+  const u = cost.unit || 'kg';
+
+  if (u in MASS_TO_KG) return v / MASS_TO_KG[u];
+
+  if (u in VOL_TO_L) {
+    const d = _densityToKgPerL(density, densityUnit);
+    if (!d) return null;
+    // $/u → $/L → $/kg
+    return (v / VOL_TO_L[u]) / d;
+  }
+  return null;
+}
+
+// ============================================================
+// CURRENCY RATES — live via Frankfurter (free, no key), cached
+// daily in localStorage. Falls back to static rates if offline.
+// ============================================================
+const FX_LS_KEY = 'formlab_fx_v1';
+const FX_FALLBACK = {
+  // Approximate rates per 1 USD as of mid-2026. Used only when the
+  // live fetch fails (offline). Don't rely on these for finance.
+  base: 'USD',
+  rates: {
+    USD: 1, EUR: 0.92, GBP: 0.79, JPY: 156, CNY: 7.23,
+    CAD: 1.37, AUD: 1.52, CHF: 0.89, INR: 83.5, BRL: 5.1,
+    SGD: 1.26, HKD: 7.84, KRW: 1336, MXN: 16.9,   // Frankfurter 2026-09-09
+    PKR: 278,                                      // not on Frankfurter; see _backfillMissingFxRates
+  },
+};
+let _fxCache = null;
+
+async function ensureFxRates() {
+  if (_fxCache) return _fxCache;
+  try {
+    const raw = localStorage.getItem(FX_LS_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      const today = flTodayIso();
+      if (parsed && parsed.date === today && parsed.base === 'USD') {
+        _fxCache = parsed;
+        return _fxCache;
+      }
+    }
+  } catch {}
+
+  try {
+    // Frankfurter migrated api.frankfurter.app → api.frankfurter.dev (the old
+    // host now 301-redirects, and a browser fetch can't follow that cross-origin
+    // redirect under CORS — the request failed with "No Access-Control-Allow-
+    // Origin"). Hit the new /v1 endpoint directly; it sends `access-control-
+    // allow-origin: *` and returns the same { base, date, rates } shape.
+    const res = await fetch('https://api.frankfurter.dev/v1/latest?base=USD');
+    if (!res.ok) throw new Error('Frankfurter returned ' + res.status);
+    const data = await res.json();
+    const rates = { USD: 1, ...data.rates };
+    // Frankfurter is ECB-only (~30 currencies). Any currency we list that it
+    // doesn't price (PKR today) gets a live rate from a broader secondary
+    // source, so the picker never offers a currency whose conversions are null.
+    await _backfillMissingFxRates(rates);
+    const date = flTodayIso();
+    _fxCache = { date, base: 'USD', rates };
+    try { localStorage.setItem(FX_LS_KEY, JSON.stringify(_fxCache)); } catch {}
+    return _fxCache;
+  } catch {
+    _fxCache = FX_FALLBACK;
+    return _fxCache;
+  }
+}
+
+// Backfill live rates for listed currencies the primary (ECB/Frankfurter)
+// source doesn't cover — e.g. PKR, which isn't an ECB reference currency.
+// Mutates `rates` in place. Best-effort: on any failure the currency simply
+// stays missing from the live cache and convertCurrencySync falls back to the
+// FX_FALLBACK approximate for it. Source: exchangerate-api's free open endpoint
+// (no key, CORS '*', ~160 currencies, daily refresh).
+async function _backfillMissingFxRates(rates) {
+  const missing = COST_CURRENCIES.map(c => c.code).filter(code => rates[code] == null);
+  if (!missing.length) return;
+  try {
+    const res = await fetch('https://open.er-api.com/v6/latest/USD');
+    if (!res.ok) return;
+    const data = await res.json();
+    const supp = data && data.rates;
+    if (!supp) return;
+    for (const code of missing) {
+      if (typeof supp[code] === 'number' && isFinite(supp[code])) rates[code] = supp[code];
+    }
+  } catch { /* leave missing; the per-code FX_FALLBACK in convertCurrencySync covers it */ }
+}
+
+function convertCurrencySync(amount, from, to) {
+  if (amount == null || !isFinite(amount)) return null;
+  if (from === to) return amount;
+  const cache = _fxCache || FX_FALLBACK;
+  const r = cache.rates;
+  // Per-code fallback: if the live cache is missing a rate (e.g. the PKR
+  // backfill fetch failed this session), use the approximate FX_FALLBACK for
+  // that code rather than returning null and blanking the whole cost panel.
+  const rateOf = code => (r[code] != null ? r[code] : FX_FALLBACK.rates[code]);
+  const rFrom = rateOf(from), rTo = rateOf(to);
+  if (rFrom == null || rTo == null) return null;
+  // Cache is USD-based; convert from→USD→to
+  const usd = amount / rFrom;
+  return usd * rTo;
+}
+
+// ============================================================
+// DISPLAY CURRENCY — user's preferred currency for totals/UI
+// ============================================================
+const DISPLAY_CCY_LS_KEY = 'formlab_display_currency';
+
+function getDisplayCurrency() {
+  return localStorage.getItem(DISPLAY_CCY_LS_KEY) || 'USD';
+}
+function setDisplayCurrency(code) {
+  if (!COST_CURRENCIES.some(c => c.code === code)) return;
+  localStorage.setItem(DISPLAY_CCY_LS_KEY, code);
+  // Per-user preference: write-through to the cloud (Pro). localStorage stays the
+  // offline/Free store; the hook persists it on the user's profile. Best-effort.
+  try { (typeof window !== 'undefined' ? window.__pro : null)?.onDisplayCurrency?.(code); } catch (_) {}
+}
+// Apply a cloud-loaded currency without echoing back to the cloud (used by the
+// Pro layer after it reads the signed-in user's profile on boot).
+function applyDisplayCurrencyFromCloud(code) {
+  if (!code || !COST_CURRENCIES.some(c => c.code === code)) return;
+  if (localStorage.getItem(DISPLAY_CCY_LS_KEY) === code) return;
+  localStorage.setItem(DISPLAY_CCY_LS_KEY, code);
+  if (typeof reRender === 'function') { try { reRender(); } catch (_) {} }
+}
+
+// Live-FX provenance for cost panels: the date the cached rates were fetched,
+// or a clear "offline / approximate" note when the live fetch hasn't landed.
+function fxAsOfHint() {
+  if (_fxCache && _fxCache !== FX_FALLBACK && _fxCache.date) return 'FX ' + _fxCache.date;
+  return 'approx FX';
+}
+
+// Reusable global display-currency switcher for any cost panel. All cost figures
+// share the one global pref (getDisplayCurrency), so changing it here re-renders
+// the whole app in that currency. `reRenderJs` is a JS expression run right after
+// the change to repaint the current view (e.g. "renderBatchDetail('b1')").
+// `betweenHtml` (optional) is slotted between the select and the FX hint — the
+// ingredient Cost tab puts its display-unit switcher there so currency, unit
+// and FX date read as one row.
+function displayCurrencyControlHtml(reRenderJs, betweenHtml) {
+  const cur = getDisplayCurrency();
+  const opts = COST_CURRENCIES
+    .map(c => `<option value="${c.code}"${c.code === cur ? ' selected' : ''}>${c.code} ${c.symbol}</option>`)
+    .join('');
+  const after = String(reRenderJs || '');
+  return `<select class="cost-ccy-select" onclick="event.stopPropagation()" `
+    + `title="Display currency for all cost figures, live FX" `
+    + `onchange="setDisplayCurrency(this.value);${after}" `
+    + `style="padding:3px 6px;border:1px solid var(--border);border-radius:5px;font-size:12px;font-family:inherit;background:#fff">${opts}</select>`
+    + (betweenHtml || '')
+    + `<span class="cost-ccy-fxhint" style="font-size:10.5px;color:var(--text-muted);margin-left:6px;white-space:nowrap">${fxAsOfHint()}</span>`;
+}
+
+// ============================================================
+// DISPLAY COST UNIT — per-user "show prices per …" for the ingredient Cost
+// tab. Mirrors the display currency: the ENTERED price stays the source of
+// truth, this only picks the unit of the read-only "≈ …" conversion line.
+// '' = show in the unit the price was entered in. Synced per user via
+// VIEW_PREF_KEYS (list-shell.js) like the other view prefs.
+// ============================================================
+const DISPLAY_COST_UNIT_LS_KEY = 'formlab_cost_display_unit';
+function getDisplayCostUnit() {
+  try { return localStorage.getItem(DISPLAY_COST_UNIT_LS_KEY) || ''; } catch (_) { return ''; }
+}
+function setDisplayCostUnit(u) {
+  u = u || '';
+  if (u && !(u in MASS_TO_KG) && !(u in VOL_TO_L)) return;
+  if (typeof saveViewPref === 'function') saveViewPref(DISPLAY_COST_UNIT_LS_KEY, u);
+  else { try { localStorage.setItem(DISPLAY_COST_UNIT_LS_KEY, u); } catch (_) {} }
+}
+
+// Convert an ing.cost to price-per-`unit` in the cost's OWN currency.
+// mass↔mass and vol↔vol are exact; mass↔vol needs the ingredient's density.
+// Returns null when the conversion isn't possible (no density, unknown unit).
+function costPerUnitInOwnCurrency(cost, unit, density, densityUnit) {
+  if (!cost || cost.value == null || cost.value === '' || !unit) return null;
+  const v = parseFloat(cost.value);
+  if (!isFinite(v)) return null;
+  const from = cost.unit || 'kg';
+  if (from === unit) return v;
+  const kgPerL = _densityToKgPerL(density, densityUnit);
+  return convertPricePerBasis(v, from, unit, kgPerL || null);
+}
+
+// Unit switcher paired with displayCurrencyControlHtml on the Cost tab. Options
+// are the common basis units plus the entered unit; the cross-family choices
+// (volume for a mass price, or vice versa) are disabled until the ingredient
+// has a density, with the reason in the option's tooltip.
+function displayCostUnitControlHtml(cost, density, densityUnit, reRenderJs) {
+  const entered = (cost && cost.unit) || 'kg';
+  const cur = getDisplayCostUnit() || entered;
+  const hasDensity = !!_densityToKgPerL(density, densityUnit);
+  const fromMass = entered in MASS_TO_KG;
+  const list = COST_BASIS_UNITS.slice();
+  if (list.indexOf(entered) === -1) list.unshift(entered);
+  if (cur !== entered && list.indexOf(cur) === -1) list.push(cur);
+  const opts = list.map(u => {
+    const sameFamily = (u in MASS_TO_KG) === fromMass;
+    const off = !sameFamily && !hasDensity;
+    const t = off ? ' title="Set a density on the Identification tab to convert between mass and volume"' : '';
+    return `<option value="${u}"${u === cur ? ' selected' : ''}${off ? ' disabled' : ''}${t}>/ ${u}</option>`;
+  }).join('');
+  const after = String(reRenderJs || '');
+  return `<select class="cost-ccy-select cost-unit-select" onclick="event.stopPropagation()" `
+    + `title="Show the price per this unit (the entered price is unchanged)" `
+    + `onchange="setDisplayCostUnit(this.value);${after}" `
+    + `style="padding:3px 6px;border:1px solid var(--border);border-radius:5px;font-size:12px;font-family:inherit;background:#fff">${opts}</select>`;
+}
+
+// ============================================================
+// FORMATTING
+// ============================================================
+function formatMoney(amount, currency) {
+  if (amount == null || !isFinite(amount)) return '—';
+  // Under one cent (a per-kg price of water, say), 2 decimals read "$0.00";
+  // show 3 significant digits instead ("$0.002"). Everything else unchanged
+  // (build 33g).
+  const tiny = amount !== 0 && Math.abs(amount) < 0.01;
+  try {
+    return new Intl.NumberFormat(undefined, tiny
+      ? { style: 'currency', currency, maximumSignificantDigits: 3 }
+      : { style: 'currency', currency, maximumFractionDigits: 2 }).format(amount);
+  } catch {
+    const sym = COST_CURRENCIES.find(c => c.code === currency)?.symbol || '';
+    return sym + (tiny ? String(+amount.toPrecision(3)) : amount.toFixed(2));
+  }
+}
+
+function formatCostPerUnit(cost) {
+  if (!cost || cost.value == null || cost.value === '') return '—';
+  const v = parseFloat(cost.value);
+  if (!isFinite(v)) return '—';
+  return `${formatMoney(v, cost.currency || 'USD')} / ${cost.unit || 'kg'}`;
+}
+
+// ============================================================
+// FORMULATION COST ROLLUP
+// Returns { perKg, currency, breakdown, missing, basis }.
+// Handles three cases:
+//   - all rows in wt%:  cost-per-kg directly from $/kg × wt fraction
+//   - all rows in vol%: derive formulation density from per-row
+//                       (vol fraction × ing density), then $/kg
+//   - mixed:            best-effort wt% with vol rows in `missing`
+// Volume rows need each ingredient's density to be priced.
+// ============================================================
+function computeFormulationCost(formulation, displayCcy, basisUnit, _seen) {
+  const comp = formulation.composition || [];
+  // Currency precedence: explicit arg → viewer's display preference → formulation's saved currency → USD.
+  // formulation.costCurrency is the currency the owner used when entering costs, but in a shared
+  // workspace each viewer should always see costs in their own preferred currency.
+  displayCcy = displayCcy || getDisplayCurrency() || formulation.costCurrency || 'USD';
+  basisUnit  = basisUnit  || formulation.costBasisUnit || 'kg';
+  const overrides = formulation.costOverrides || {};
+  const breakdown = [];
+  const missing   = [];
+
+  // Recursion guard for nested formulations. _seen is the chain of
+  // formulation ids currently being priced; if the same id shows up
+  // again, that's a cycle (should have been caught at add time, but be
+  // defensive) and we skip the offending sub-row.
+  _seen = _seen || new Set();
+  if (formulation && formulation.id) _seen = new Set([..._seen, formulation.id]);
+
+  // Resolve each sub-formula row to a "synthetic ingredient" with a
+  // recursively-computed $/kg and a rolled-up density. The main loop
+  // below then treats sub-formula rows just like ingredient rows.
+  const subResolve = new Map();
+  for (const c of comp) {
+    if (!c.formulationId) continue;
+    // By id through the draw's index (12a): a scan per row, per formula, was
+    // most of the Inventory roll-up's cost at 20k records.
+    const subF = (typeof flFindById === 'function') ? flFindById('formulations', c.formulationId) : db.formulations.find(g => g.id === c.formulationId);
+    if (!subF) { missing.push({ reason: 'sub-formula deleted', row: c }); continue; }
+    if (_seen.has(subF.id)) { missing.push({ reason: 'cycle detected', row: c }); continue; }
+    const subRes = computeFormulationCost(subF, displayCcy, 'kg', _seen);
+    const subDensity = (typeof _rolledUpDensity === 'function') ? _rolledUpDensity(subF) : null;
+    subResolve.set(c, {
+      subFormula: subF,
+      perKgDisplay: subRes.perKg,           // $/kg in displayCcy
+      perKgOwn:     subRes.perKg,           // already converted
+      density:      subDensity,             // kg/L, may be null
+      missing:      subRes.missing || [],
+      basisOk:      subRes.basisOk,
+    });
+  }
+
+  // Classify each row's unit into one of five buckets:
+  //   wt-frac   "wt%" / "%"
+  //   vol-frac  "vol%"
+  //   mass-abs  g / kg / mg / lb / oz / ton / ...
+  //   vol-abs   mL / L / gal / drum / ...
+  //   unknown   anything else (each, count, etc.)
+  // NOTE: MASS_TO_KG / VOL_TO_L keys are case-sensitive ('L' for litre,
+  // 'mL' for millilitre — distinct from 'l' / 'ml' which aren't keys).
+  // We check the raw unit first; if that misses, fall back to a
+  // case-normalized form so users typing "ML" or "kG" still resolve.
+  const classifyUnit = u => {
+    const raw = String(u || 'wt%').trim();
+    const lower = raw.toLowerCase();
+    if (lower.startsWith('wt') || raw === '%') return 'wt-frac';
+    if (lower.startsWith('vol')) return 'vol-frac';
+    if (raw in MASS_TO_KG)   return 'mass-abs';
+    if (raw in VOL_TO_L)     return 'vol-abs';
+    if (raw in LENGTH_TO_M)  return 'length-abs';
+    // Case-insensitive fallback
+    for (const k of Object.keys(MASS_TO_KG))  if (k.toLowerCase() === lower) return 'mass-abs';
+    for (const k of Object.keys(VOL_TO_L))    if (k.toLowerCase() === lower) return 'vol-abs';
+    for (const k of Object.keys(LENGTH_TO_M)) if (k.toLowerCase() === lower) return 'length-abs';
+    return 'unknown';
+  };
+  // Map any user-typed unit back to the canonical key.
+  const canonUnit = u => {
+    const raw = String(u || '').trim();
+    if (raw in MASS_TO_KG || raw in VOL_TO_L || raw in LENGTH_TO_M) return raw;
+    const lower = raw.toLowerCase();
+    for (const k of Object.keys(MASS_TO_KG))  if (k.toLowerCase() === lower) return k;
+    for (const k of Object.keys(VOL_TO_L))    if (k.toLowerCase() === lower) return k;
+    for (const k of Object.keys(LENGTH_TO_M)) if (k.toLowerCase() === lower) return k;
+    return raw;
+  };
+
+  const kinds = comp.map(c => classifyUnit(c.unit));
+  const allWt   = comp.length && kinds.every(k => k === 'wt-frac');
+  const allVol  = comp.length && kinds.every(k => k === 'vol-frac');
+  const allAbs  = comp.length && kinds.every(k => k === 'mass-abs' || k === 'vol-abs');
+  const basis   = allVol ? 'vol' : (allAbs ? 'abs' : 'wt');
+
+  // === Vol-% recipe: derive formulation density from per-row densities ===
+  // Sub-formula rows use their rolled-up density (computed above).
+  let formulationKgPerL = null;
+  if (allVol) {
+    let sumKg = 0, ok = true;
+    for (const c of comp) {
+      let d = null;
+      if (c.formulationId) {
+        d = subResolve.get(c)?.density || null;
+      } else {
+        const ing = db.ingredients.find(i => i.id === c.ingredientId);
+        d = ing ? _densityToKgPerL(ing.density, ing.densityUnit) : null;
+      }
+      const amt = parseFloat(c.amount);
+      if (!d || !isFinite(amt)) { ok = false; break; }
+      sumKg += (amt / 100) * d;
+    }
+    formulationKgPerL = ok ? sumKg : null;
+  }
+
+  // === Absolute recipe: convert every row to kg (using density for volume
+  // rows), sum to total mass, then use per-row mass fractions. Also track
+  // total volume so we can derive the formulation density for basis-unit
+  // conversion if all rows have densities. ===
+  const massKgPerRow = new Map();   // c <span class="fl-ar fl-ar-e"></span> row mass in kg
+  const volLPerRow   = new Map();   // c <span class="fl-ar fl-ar-e"></span> row volume in L (when known)
+  let totalMassKg = 0;
+  let totalVolL   = 0;
+  let allAbsHaveDensity = true;
+  if (allAbs) {
+    for (const c of comp) {
+      const u = canonUnit(c.unit || '');
+      const amt = parseFloat(c.amount);
+      let d = null;
+      if (c.formulationId) {
+        if (!subResolve.has(c)) continue;
+        d = subResolve.get(c).density;
+      } else {
+        const ing = db.ingredients.find(i => i.id === c.ingredientId);
+        if (!ing) continue;
+        d = _densityToKgPerL(ing.density, ing.densityUnit);
+      }
+      if (!isFinite(amt)) continue;
+      if (u in MASS_TO_KG) {
+        const m = amt * MASS_TO_KG[u];
+        massKgPerRow.set(c, m);
+        totalMassKg += m;
+        if (d) { const v = m / d; volLPerRow.set(c, v); totalVolL += v; }
+        else allAbsHaveDensity = false;
+      } else if (u in VOL_TO_L) {
+        const v = amt * VOL_TO_L[u];
+        if (d) {
+          const m = v * d;
+          massKgPerRow.set(c, m);
+          volLPerRow.set(c, v);
+          totalMassKg += m;
+          totalVolL   += v;
+        } else {
+          allAbsHaveDensity = false;
+        }
+      }
+    }
+    if (allAbsHaveDensity && totalMassKg > 0 && totalVolL > 0) {
+      formulationKgPerL = totalMassKg / totalVolL;
+    }
+  }
+
+  let totalPerKg  = 0;
+  let totalPct    = 0;
+
+  const tryAutoPrice = (ing, c, unit, amount, kind) => {
+    if (!ing.cost || ing.cost.value == null || ing.cost.value === '') return { ok: false, reason: 'no cost on file' };
+    const perKgOwn = costPerKgInOwnCurrency(ing.cost, ing.density, ing.densityUnit);
+    if (perKgOwn == null) return { ok: false, reason: 'could not convert price unit (needs density?)' };
+    const perKgDisplay = convertCurrencySync(perKgOwn, ing.cost.currency || 'USD', displayCcy);
+    if (perKgDisplay == null) return { ok: false, reason: 'unknown currency rate' };
+
+    if (kind === 'wt-frac') {
+      return { ok: true, perKgOwn, perKgDisplay, contribution: (amount / 100) * perKgDisplay };
+    }
+    if (kind === 'vol-frac') {
+      const d = _densityToKgPerL(ing.density, ing.densityUnit);
+      if (!allVol || !formulationKgPerL || !d) return { ok: false, reason: 'vol-% needs density for every row and a vol-only recipe' };
+      const massFraction = ((amount / 100) * d) / formulationKgPerL;
+      return { ok: true, perKgOwn, perKgDisplay, contribution: massFraction * perKgDisplay };
+    }
+    if (kind === 'mass-abs' || kind === 'vol-abs') {
+      if (!allAbs) return { ok: false, reason: 'absolute amounts cannot be mixed with wt%/vol% in the same recipe' };
+      const m = massKgPerRow.get(c);
+      if (m == null || totalMassKg <= 0) {
+        return { ok: false, reason: kind === 'vol-abs' ? 'volume amount needs ingredient density' : 'cannot determine row mass' };
+      }
+      const massFraction = m / totalMassKg;
+      return { ok: true, perKgOwn, perKgDisplay, contribution: massFraction * perKgDisplay };
+    }
+    if (kind === 'length-abs') {
+      return { ok: false, reason: 'length-based recipes are not auto-priced yet — set a per-row override' };
+    }
+    return { ok: false, reason: `unsupported composition unit "${c.unit}"` };
+  };
+
+  for (const c of comp) {
+    // ---- Sub-formula row: treat as a synthetic ingredient priced
+    //      via the recursive computeFormulationCost above. ----
+    if (c.formulationId) {
+      const sub = subResolve.get(c);
+      if (!sub) continue;   // 'sub-formula deleted' / 'cycle detected' already in missing[]
+      const amount = parseFloat(c.amount);
+      if (!isFinite(amount)) { missing.push({ reason: 'no amount', subFormula: sub.subFormula }); continue; }
+      const kind = classifyUnit((c.unit || 'wt%').toLowerCase());
+      if (kind === 'unknown') { missing.push({ reason: `unsupported composition unit "${c.unit}"`, subFormula: sub.subFormula }); continue; }
+      const perKgDisplay = sub.perKgDisplay;
+      let contribution = null;
+      if (kind === 'wt-frac') {
+        contribution = (amount / 100) * perKgDisplay;
+      } else if (kind === 'vol-frac') {
+        if (!allVol || !formulationKgPerL || !sub.density) {
+          missing.push({ reason: 'vol-% needs density for every row and a vol-only recipe', subFormula: sub.subFormula });
+          continue;
+        }
+        const massFraction = ((amount / 100) * sub.density) / formulationKgPerL;
+        contribution = massFraction * perKgDisplay;
+      } else if (kind === 'mass-abs' || kind === 'vol-abs') {
+        if (!allAbs) { missing.push({ reason: 'absolute amounts cannot be mixed with wt%/vol%', subFormula: sub.subFormula }); continue; }
+        const m = massKgPerRow.get(c);
+        if (m == null || totalMassKg <= 0) {
+          missing.push({ reason: kind === 'vol-abs' ? 'volume amount needs sub-formula density' : 'cannot determine row mass', subFormula: sub.subFormula });
+          continue;
+        }
+        const massFraction = m / totalMassKg;
+        contribution = massFraction * perKgDisplay;
+      } else {
+        missing.push({ reason: `unsupported composition unit "${c.unit}"`, subFormula: sub.subFormula });
+        continue;
+      }
+      totalPerKg += contribution;
+      totalPct   += amount;
+      breakdown.push({
+        subFormula: sub.subFormula, ingredient: null,
+        amount, unit: c.unit || 'wt%',
+        perKgOwn: sub.perKgOwn, perKgDisplay,
+        contribution, overridden: false,
+        density: sub.density,
+      });
+      // Surface any deep-pricing gaps inside the sub-formula so the parent's
+      // "X rows unpriced" warning still reflects reality. Preserve the
+      // original ingredient (or subFormula) reference so the unpriced
+      // tooltip can render the actual name — the earlier shape dropped
+      // m.ingredient and the display fell back to "?" for anything at
+      // depth >= 2 (Parent → SubB → ingredient inside SubB → all surfaced
+      // as "?: (in SubB) no cost on file" instead of "PigmentX: …").
+      for (const m of (sub.missing || [])) {
+        missing.push({
+          reason: `(in ${sub.subFormula.name || 'sub-formula'}) ${m.reason}`,
+          ingredient: m.ingredient || null,
+          subFormula: m.subFormula || sub.subFormula,
+        });
+      }
+      continue;
+    }
+
+    const ing = (typeof flFindById === 'function') ? flFindById('ingredients', c.ingredientId) : db.ingredients.find(i => i.id === c.ingredientId);
+    if (!ing) { missing.push({ reason: 'ingredient deleted', row: c }); continue; }
+    const unit = (c.unit || 'wt%').toLowerCase();
+    const amount = parseFloat(c.amount);
+    if (!isFinite(amount)) { missing.push({ reason: 'no amount', ingredient: ing }); continue; }
+
+    const kind = classifyUnit(unit);
+    if (kind === 'unknown') {
+      missing.push({ reason: `unsupported composition unit "${c.unit}"`, ingredient: ing });
+      continue;
+    }
+
+    const auto = tryAutoPrice(ing, c, unit, amount, kind);
+    if (auto.ok) {
+      totalPerKg += auto.contribution;
+      totalPct   += amount;
+      breakdown.push({
+        ingredient: ing, amount, unit: c.unit || 'wt%',
+        perKgOwn: auto.perKgOwn, perKgDisplay: auto.perKgDisplay,
+        contribution: auto.contribution,
+        overridden: false,
+      });
+      continue;
+    }
+
+    // Auto-pricing failed. Check for a manual override.
+    const ov = overrides[ing.id];
+    if (ov && ov.value != null && isFinite(parseFloat(ov.value))) {
+      const ovValueOwn = parseFloat(ov.value);
+      const ovUnit     = ov.basisUnit || 'kg';
+      const ovCcy      = ov.currency  || 'USD';
+      // Currency conversion: override was stored in ovCcy; rollup is in displayCcy.
+      const ovValue = ovCcy === displayCcy ? ovValueOwn : convertCurrencySync(ovValueOwn, ovCcy, displayCcy);
+      // Unit conversion (override is in "$ per basisUnit of formulation").
+      let perBasisContribution = null;
+      if (ovValue != null) {
+        if (ovUnit === basisUnit) {
+          perBasisContribution = ovValue;
+        } else if (ovUnit in MASS_TO_KG && basisUnit in MASS_TO_KG) {
+          const inKg = ovValue / MASS_TO_KG[ovUnit];
+          perBasisContribution = inKg * MASS_TO_KG[basisUnit];
+        }
+      }
+      const stale = perBasisContribution == null;
+      breakdown.push({
+        ingredient: ing, amount, unit: c.unit || 'wt%',
+        perKgOwn: null, perKgDisplay: null,
+        contribution: stale ? 0 : perBasisContribution,
+        overridden: true,
+        overrideValue: ovValueOwn,
+        overrideUnit:  ovUnit,
+        overrideCurrency: ovCcy,
+        overrideStale: stale,
+        contributionIsAlreadyInBasis: true,
+      });
+      continue;
+    }
+
+    missing.push({ reason: auto.reason, ingredient: ing });
+  }
+
+  // === Convert $/kg of formulation → $/basisUnit of formulation ===
+  // For per-row priced contributions, totalPerKg is the running sum in $/kg.
+  // Compute scaling so we can also expose perBasisUnit and perBasisRow.
+  let basisOk = true;
+  let basisScale = 1;            // multiplier from $/kg of formulation to $/basisUnit of formulation
+  if (basisUnit in MASS_TO_KG) {
+    basisScale = MASS_TO_KG[basisUnit];
+  } else if (basisUnit in VOL_TO_L) {
+    // Need a formulation density (kg/L) to do mass→volume conversion
+    let formKgPerL = formulationKgPerL;
+    if (!formKgPerL) {
+      // Estimate from composition: weight-average density (only works if all densities present).
+      // Sub-formula rows use their rolled-up density.
+      let sumA = 0, sumW = 0;
+      for (const c of comp) {
+        let d = null;
+        if (c.formulationId) {
+          d = subResolve.get(c)?.density || null;
+        } else {
+          const ing = db.ingredients.find(i => i.id === c.ingredientId);
+          d = ing ? _densityToKgPerL(ing.density, ing.densityUnit) : null;
+        }
+        const a = parseFloat(c.amount);
+        if (d && isFinite(a)) { sumA += a * d; sumW += a; }
+      }
+      formKgPerL = sumW ? sumA / sumW : null;
+    }
+    if (formKgPerL) {
+      basisScale = formKgPerL * VOL_TO_L[basisUnit];
+    } else {
+      basisOk = false;
+    }
+  } else if (basisUnit !== 'kg') {
+    basisOk = false;
+  }
+
+  // Apply scale to per-row priced contributions (overridden rows already
+  // carry their contribution in basis terms).
+  let totalPerBasis = 0;
+  for (const b of breakdown) {
+    if (b.contributionIsAlreadyInBasis) {
+      totalPerBasis += b.contribution;
+      b.perBasis = b.contribution;
+    } else if (basisOk) {
+      b.perBasis = b.contribution * basisScale;
+      totalPerBasis += b.perBasis;
+    } else {
+      b.perBasis = null;
+    }
+    // Per-kg of the ingredient → also expose per-basisUnit of the ingredient
+    if (b.perKgDisplay != null && basisOk && !(basisUnit in VOL_TO_L)) {
+      // Ingredient per-basisUnit: only meaningful for mass conversions
+      b.perBasisRate = b.perKgDisplay * MASS_TO_KG[basisUnit];
+    } else if (b.perKgDisplay != null && basisOk) {
+      // Volume basis: use ingredient density (or sub-formula rolled-up density)
+      let d = null;
+      if (b.ingredient) {
+        d = _densityToKgPerL(b.ingredient.density, b.ingredient.densityUnit);
+      } else if (b.subFormula) {
+        d = b.density || (typeof _rolledUpDensity === 'function' ? _rolledUpDensity(b.subFormula) : null);
+      }
+      b.perBasisRate = d ? b.perKgDisplay * d * VOL_TO_L[basisUnit] : null;
+    }
+  }
+
+  return {
+    perKg: totalPerKg,
+    perBasis: basisOk ? totalPerBasis : null,
+    basisUnit,
+    basisOk,
+    coveragePct: totalPct,
+    currency: displayCcy,
+    breakdown,
+    missing,
+    basis,                       // 'wt' or 'vol' (recipe basis, not display basis)
+    formulationKgPerL,           // only meaningful when basis === 'vol'
+  };
+}
+
+// Common basis units the user can pick in the composition cost column.
+const COST_BASIS_UNITS = ['kg', 'g', 'lb', 'oz', 'ton', 'L', 'mL', 'gal'];
+
+// Convert a money-per-basis value from one basis to another. Mass↔mass and
+// volume↔volume are direct; mass↔volume needs formulationKgPerL (derived
+// by computeFormulationCost when possible). Returns null if a needed
+// density is missing.
+function convertPricePerBasis(price, fromBasis, toBasis, formulationKgPerL) {
+  if (price == null || !isFinite(price)) return null;
+  if (fromBasis === toBasis) return price;
+  const scaleFromKg = u => {
+    if (u === 'kg') return 1;
+    if (u in MASS_TO_KG) return MASS_TO_KG[u];
+    if (u in VOL_TO_L) {
+      if (!formulationKgPerL) return null;
+      return formulationKgPerL * VOL_TO_L[u];
+    }
+    return null;
+  };
+  const sFrom = scaleFromKg(fromBasis);
+  const sTo   = scaleFromKg(toBasis);
+  if (sFrom == null || sTo == null) return null;
+  // price_per_kg = price_per_fromBasis / sFrom
+  // price_per_toBasis = price_per_kg × sTo
+  return price * (sTo / sFrom);
+}
+
+// ============================================================
+// COMPOSITION FRACTIONS — per-row mass/volume fractions of the
+// formulation, computed regardless of whether rows use wt%, vol%,
+// or absolute mass/volume amounts. Used by the "% of Total"
+// column when the user wants "by weight" / "by volume" instead of
+// raw-amount percentages.
+// ============================================================
+function computeCompositionFractions(formulation) {
+  const comp = formulation.composition || [];
+
+  const canonUnit = u => {
+    const raw = String(u || '').trim();
+    if (raw in MASS_TO_KG || raw in VOL_TO_L || raw in LENGTH_TO_M) return raw;
+    const lower = raw.toLowerCase();
+    for (const k of Object.keys(MASS_TO_KG))  if (k.toLowerCase() === lower) return k;
+    for (const k of Object.keys(VOL_TO_L))    if (k.toLowerCase() === lower) return k;
+    for (const k of Object.keys(LENGTH_TO_M)) if (k.toLowerCase() === lower) return k;
+    return raw;
+  };
+
+  // Pass 1: classify each row, compute absolute mass, volume, length when possible.
+  // Sub-formula rows resolve to a "synthetic ingredient" with the sub-formula's
+  // rolled-up density so the same mass/volume math applies.
+  const rows = comp.map(c => {
+    const rawU = (c.unit || 'wt%').trim();
+    const u    = rawU.toLowerCase();
+    const amount = parseFloat(c.amount);
+    let ing = null, subFormula = null, d = null;
+    if (c.formulationId) {
+      subFormula = db.formulations.find(g => g.id === c.formulationId) || null;
+      d = subFormula && typeof _rolledUpDensity === 'function' ? _rolledUpDensity(subFormula) : null;
+    } else {
+      ing = db.ingredients.find(i => i.id === c.ingredientId);
+      d = ing ? _densityToKgPerL(ing.density, ing.densityUnit) : null;
+    }
+    const out = { composition: c, ingredient: ing, subFormula, amount, unit: rawU, density: d };
+    const resolved = !!(ing || subFormula);
+    if (!isFinite(amount) || !resolved) { out.kind = 'invalid'; return out; }
+    if (u.startsWith('wt') || u === '%') { out.kind = 'wt-frac'; return out; }
+    if (u.startsWith('vol'))             { out.kind = 'vol-frac'; return out; }
+    const cu = canonUnit(rawU);
+    if (cu in MASS_TO_KG) {
+      out.kind = 'mass-abs';
+      out.massKg = amount * MASS_TO_KG[cu];
+      out.volL   = d ? out.massKg / d : null;
+      return out;
+    }
+    if (cu in VOL_TO_L) {
+      out.kind = 'vol-abs';
+      out.volL   = amount * VOL_TO_L[cu];
+      out.massKg = d ? out.volL * d : null;
+      return out;
+    }
+    if (cu in LENGTH_TO_M) {
+      out.kind = 'length-abs';
+      out.lengthM = amount * LENGTH_TO_M[cu];
+      return out;
+    }
+    out.kind = 'unknown';
+    return out;
+  });
+
+  // Sums + same-kind detection
+  let totalMassKg = 0, totalVolL = 0, totalLengthM = 0;
+  rows.forEach(r => {
+    if (r.massKg  != null) totalMassKg  += r.massKg;
+    if (r.volL    != null) totalVolL    += r.volL;
+    if (r.lengthM != null) totalLengthM += r.lengthM;
+  });
+  const allWt  = rows.length && rows.every(r => r.kind === 'wt-frac');
+  const allVol = rows.length && rows.every(r => r.kind === 'vol-frac');
+  const allLen = rows.length && rows.every(r => r.kind === 'length-abs');
+
+  // For pure wt% / vol% recipes, derive formulation density from densities
+  // so we can also compute the *other* fraction (vol for wt%, mass for vol%).
+  let wtFormKgPerL = null;
+  let volFormKgPerL = null;
+  if (allWt && rows.every(r => r.density)) {
+    let invSum = 0;  // sum over rows of (wt_frac / density)
+    rows.forEach(r => { invSum += (r.amount / 100) / r.density; });
+    if (invSum > 0) wtFormKgPerL = 1 / invSum;
+  }
+  if (allVol && rows.every(r => r.density)) {
+    let sum = 0;
+    rows.forEach(r => { sum += (r.amount / 100) * r.density; });
+    if (sum > 0) volFormKgPerL = sum;
+  }
+
+  // Mixed-basis guard. A composition that combines PERCENTAGE rows (wt%/vol%)
+  // with ABSOLUTE mass/volume rows (g, lb, mL, …) is under-determined: the
+  // percentage rows carry no absolute mass, and the absolute rows carry no
+  // percentage basis, so there is no shared 100% to normalize against. Without
+  // this guard each group self-normalizes to ~100% and the two stack — e.g.
+  // 25/25/50 wt% + one 5 lb row reports 200%. When we detect the mix we refuse
+  // to fabricate a fraction (null it out) and flag `mixedBasis` so the UI can
+  // explain and prompt for a single basis. (Length is a separate dimension and
+  // is left alone.)
+  const hasFracRow    = rows.some(r => r.kind === 'wt-frac'  || r.kind === 'vol-frac');
+  const hasAbsMassVol = rows.some(r => r.kind === 'mass-abs' || r.kind === 'vol-abs');
+  const mixedBasis    = hasFracRow && hasAbsMassVol;
+
+  // Pass 2: fill in massFraction / volFraction per row
+  rows.forEach(r => {
+    if (mixedBasis && (r.kind === 'wt-frac' || r.kind === 'vol-frac' ||
+                       r.kind === 'mass-abs' || r.kind === 'vol-abs')) {
+      // Ill-posed mix — no coherent fraction. Surface "—", not a fake number.
+      r.massFraction = null;
+      r.volFraction  = null;
+      return;
+    }
+    if (r.kind === 'wt-frac') {
+      r.massFraction = r.amount / 100;
+      r.volFraction  = (wtFormKgPerL && r.density)
+        ? ((r.amount / 100) / r.density) * wtFormKgPerL
+        : null;
+    } else if (r.kind === 'vol-frac') {
+      r.volFraction  = r.amount / 100;
+      r.massFraction = (volFormKgPerL && r.density)
+        ? ((r.amount / 100) * r.density) / volFormKgPerL
+        : null;
+    } else if (r.kind === 'mass-abs' || r.kind === 'vol-abs') {
+      r.massFraction = (r.massKg != null && totalMassKg > 0) ? r.massKg / totalMassKg : null;
+      r.volFraction  = (r.volL   != null && totalVolL   > 0) ? r.volL   / totalVolL   : null;
+    } else if (r.kind === 'length-abs') {
+      r.lengthFraction = (r.lengthM != null && totalLengthM > 0) ? r.lengthM / totalLengthM : null;
+      r.massFraction = null;
+      r.volFraction  = null;
+    } else {
+      r.massFraction = null;
+      r.volFraction  = null;
+    }
+  });
+
+  return { rows, totalMassKg, totalVolL, totalLengthM, allWt, allVol, allLen, mixedBasis };
+}
+
+// Scale-to-batch: given a target batch (amount + unit), return the
+// absolute amount of each composition row in that unit. The math is
+// simply fraction × batchAmount, using mass fractions when the batch
+// unit is a mass and volume fractions when it's a volume — so it
+// works for %-recipes, absolute recipes, and mixed alike (the
+// fraction computation already normalizes them).
+//
+// Rows whose fraction can't be resolved in the chosen dimension
+// (e.g. a volume batch but the row lacks density) come back null so
+// the UI can show "—". Returns:
+//   { unit, dim:'mass'|'volume', byRow: Map<compRowObj, number|null> } | null
+// Metric "ladders" for auto-scaling a value to the most readable unit
+// in its dimension. factor = base units (kg or L) per 1 of this unit.
+const _MASS_LADDER = [
+  { unit: 'µg', factor: 1e-9 }, { unit: 'mg', factor: 1e-6 },
+  { unit: 'g',  factor: 1e-3 }, { unit: 'kg', factor: 1 }, { unit: 'ton', factor: 1000 },
+];
+const _VOL_LADDER = [
+  { unit: 'µL', factor: 1e-6 }, { unit: 'mL', factor: 1e-3 }, { unit: 'L', factor: 1 },
+];
+
+// Re-express `value` (in `unit`) using the most readable unit of the
+// same dimension — the largest unit that keeps the magnitude >= 1.
+// Turns "0.00912 kg" into "9.12 g", "1500 kg" into "1.5 ton", etc.
+// Leaves the value untouched for non mass/volume units. Returns
+// { value, unit }.
+function smartScaleAmount(value, unit) {
+  if (!isFinite(value)) return { value, unit };
+  let ladder, base;
+  if (unit in MASS_TO_KG)      { ladder = _MASS_LADDER; base = value * MASS_TO_KG[unit]; }
+  else if (unit in VOL_TO_L)   { ladder = _VOL_LADDER;  base = value * VOL_TO_L[unit]; }
+  else return { value, unit };
+  if (base === 0) return { value: 0, unit };
+  const a = Math.abs(base);
+  let chosen = ladder[0];
+  for (const l of ladder) { if (a / l.factor >= 1) chosen = l; else break; }
+  return { value: base / chosen.factor, unit: chosen.unit };
+}
+
+// → { unit, dim, byRow: Map<compRow, amount-in-batchUnit|null>, anyNull,
+//     density?: { kgPerL, source: 'finished'|'ideal', how, batchId, temp },
+//     totalMassKg?, partsSum? }
+//
+// A VOLUME target on a recipe is under-determined until you know the density
+// of the FINISHED mix: 250 mL of syrup weighs 250 × ρ_mix, and ρ_mix is not
+// the sum of parts (solutions contract or expand on mixing). So:
+//   • finished density declared on the formula (measured on a batch / spec)
+//     → total mass = V × ρ_mix; each row = its mass fraction of that; shown
+//       in the batch unit via the ROW's own density (the volume you would
+//       measure out of the pure ingredient). Row volumes therefore do NOT sum
+//       to the target — `partsSum` says what they do sum to.
+//   • no finished density → ideal-mix estimate, exactly as before: row volume
+//     fractions × target (parts add up, which is the assumption).
+// Mass targets are unaffected either way.
+function scaleCompositionToBatch(formulation, batchAmount, batchUnit) {
+  const amt = parseFloat(batchAmount);
+  if (!isFinite(amt) || amt <= 0) return null;
+  const dim = (batchUnit in MASS_TO_KG) ? 'mass'
+            : (batchUnit in VOL_TO_L)   ? 'volume'
+            : null;
+  if (!dim) return null;
+  const fr = computeCompositionFractions(formulation);
+  const comp = formulation.composition || [];
+  const byRow = new Map();
+  let anyNull = false;
+  const pd = (typeof formulaPlanningDensity === 'function') ? formulaPlanningDensity(formulation) : null;
+  const useFinished = dim === 'volume' && pd && pd.source === 'finished';
+  if (useFinished) {
+    const totalMassKg = amt * VOL_TO_L[batchUnit] * pd.kgPerL;
+    let partsSum = 0;
+    fr.rows.forEach((r, i) => {
+      const mf = r.massFraction;
+      const rowD = (r.density != null && isFinite(r.density) && r.density > 0) ? r.density : null;   // kg/L
+      const ok = (mf != null && isFinite(mf) && rowD != null);
+      if (!ok) anyNull = true;
+      const vol = ok ? ((mf * totalMassKg) / rowD) / VOL_TO_L[batchUnit] : null;
+      if (ok) partsSum += vol;
+      byRow.set(comp[i], vol);
+    });
+    return { unit: batchUnit, dim, byRow, anyNull, density: pd, totalMassKg, partsSum };
+  }
+  fr.rows.forEach((r, i) => {
+    const frac = dim === 'mass' ? r.massFraction : r.volFraction;
+    const ok = (frac != null && isFinite(frac));
+    if (!ok) anyNull = true;
+    byRow.set(comp[i], ok ? frac * amt : null);
+  });
+  const out = { unit: batchUnit, dim, byRow, anyNull };
+  if (dim === 'volume' && pd) { out.density = pd; out.totalMassKg = amt * VOL_TO_L[batchUnit] * pd.kgPerL; out.partsSum = amt; }
+  return out;
+}
+
+// Effective on-hand amount of a batch for budget math (Tier 3). Once a batch
+// is Completed and has a logged actual yield, the budget reconciles against
+// that actual; otherwise it reserves against the planned target quantity.
+// Returns { amount, isActual } in the batch's own unit (actualYield shares
+// the target-quantity unit).
+function effectiveBatchAmount(batch) {
+  if (!batch) return { amount: null, isActual: false };
+  const ay = parseFloat(batch.actualYield);
+  if (batch.status === 'Completed' && batch.actualYield != null && batch.actualYield !== '' && isFinite(ay) && ay >= 0) {
+    return { amount: ay, isActual: true };
+  }
+  const tq = parseFloat(batch.targetQuantity);
+  return { amount: isFinite(tq) ? tq : null, isActual: false };
+}
+
+// Shared "Δ vs plan" severity tiers — one source of truth for the
+// planned-vs-actual deviation colors used in the DOE Matrix column and the
+// Compare chip, so the color key means the same thing everywhere.
+//   <2 wt-% → on-target (green) · 2–10 → drift (amber) · ≥10 → off (red)
+function deviationTier(pct) {
+  const p = Math.abs(parseFloat(pct));
+  if (!isFinite(p))  return { tier: 'none',  color: '#94a3b8', bg: 'transparent', label: '—' };
+  if (p < 2)         return { tier: 'on',     color: '#15803d', bg: '#f0fdf4', label: 'on-target' };
+  if (p < 10)        return { tier: 'drift',  color: '#b45309', bg: '#fffbeb', label: 'drift' };
+  return             { tier: 'off',    color: '#b91c1c', bg: '#fef2f2', label: 'off-target' };
+}
+
+// Plain-text tooltip + inline color legend for the deviation tiers.
+const DEVIATION_TIP = 'Δ vs plan = worst-case wt-% drift of the as-prepared composition from the proposal. Colors: under 2% on-target (green), 2–10% drift (amber), 10%+ off-target (red).';
+function deviationLegendHtml() {
+  const dot = c => `<span style="display:inline-block;width:8px;height:8px;border-radius:50%;background:${c};vertical-align:middle;margin-right:3px"></span>`;
+  return `<span title="${DEVIATION_TIP}" style="font-size:10.5px;color:#64748b;white-space:nowrap">Δ vs plan: ${dot('#15803d')}&lt;2% ${dot('#b45309')}2–10% ${dot('#b91c1c')}≥10%</span>`;
+}
+
+// Effective % active for grossing up a weigh-out amount of a technical
+// (impure) ingredient. Precedence:
+//   1. the ingredient's nominal `purity` (the stable spec / override), else
+//   2. the purity of the active lot we'd draw next (soonest expiry, then
+//      oldest received) — so lot data entered on the CoA is used even with no
+//      nominal set, else
+//   3. null → treat as 100% (no correction).
+// A nominal (or lot) value of ≥100 means "pure" → returns null (no correction).
+// Used by the batch AND sample weigh-outs so both correct identically. This is
+// a bench/weigh-out concept only — composition, cost, and property math keep
+// using the as-declared amounts.
+function effectivePurity(ing) {
+  if (!ing) return null;
+  const nom = parseFloat(ing.purity);
+  if (isFinite(nom) && nom > 0) return nom < 100 ? nom : null;
+  // No usable nominal → fall back to a representative active lot with purity.
+  const lots = (typeof db !== 'undefined' && Array.isArray(db.lots))
+    ? db.lots.filter(l => l.ingredientId === ing.id
+        && (parseFloat(l.qtyRemaining) || 0) > 0
+        && (!l.status || l.status === 'active')
+        && l.purity != null && isFinite(parseFloat(l.purity)) && parseFloat(l.purity) > 0)
+    : [];
+  if (!lots.length) return null;
+  lots.sort((a, b) => {
+    const ax = a.expiryDate || '9999-12-31', bx = b.expiryDate || '9999-12-31';
+    if (ax !== bx) return ax < bx ? -1 : 1;
+    return (a.receivedDate || '').localeCompare(b.receivedDate || '');
+  });
+  const p = parseFloat(lots[0].purity);
+  return (isFinite(p) && p > 0 && p < 100) ? p : null;
+}
+
+// Lot-assay deviation warning. The weigh-out is grossed up on the ingredient's
+// NOMINAL purity (the design basis — see effectivePurity); a delivered lot may
+// assay differently. When the lot this row will draw from (the batch's consumed
+// lots, else the FIFO front lot) deviates from the nominal by ≥ PURITY_DEVIATION_WARN
+// absolute points, return the facts + the weigh amount that would deliver the
+// spec active at the lot's assay. Null when there's nothing to warn about.
+const PURITY_DEVIATION_WARN = 1;   // absolute % points
+function lotPurityDeviation(ing, opts) {
+  opts = opts || {};
+  if (!ing || typeof db === 'undefined' || !Array.isArray(db.lots)) return null;
+  const nominal = parseFloat(ing.purity);
+  if (!(isFinite(nominal) && nominal > 0 && nominal < 100)) return null;
+  let lots = [];
+  if (opts.batchId && typeof lotsUsedInBatch === 'function') {
+    lots = lotsUsedInBatch(db.stockMovements || [], opts.batchId)
+      .map(u => db.lots.find(l => l && l.id === u.lotId)).filter(l => l && l.ingredientId === ing.id);
+  }
+  const consumed = lots.length > 0;
+  if (!lots.length) {
+    lots = db.lots.filter(l => l && l.ingredientId === ing.id && (parseFloat(l.qtyRemaining) || 0) > 0 && (!l.status || l.status === 'active'))
+      .sort((a, b) => { const ax = a.expiryDate || '9999-12-31', bx = b.expiryDate || '9999-12-31'; return ax !== bx ? (ax < bx ? -1 : 1) : (a.receivedDate || '').localeCompare(b.receivedDate || ''); });
+  }
+  const lot = lots.find(l => l.purity != null && isFinite(parseFloat(l.purity)) && parseFloat(l.purity) > 0);
+  if (!lot) return null;
+  const p = parseFloat(lot.purity);
+  const dev = p - nominal;
+  if (Math.abs(dev) < PURITY_DEVIATION_WARN) return null;
+  const amount = (opts.amount != null && isFinite(opts.amount)) ? opts.amount : null;
+  return { lot, lotNumber: lot.lotNumber || lot.uid || '', lotPurity: p, nominal, deviation: +dev.toFixed(2), consumed,
+    correctedAmount: amount != null ? amount * (nominal / p) : null };
+}
+
+// Gross up a single weigh-out amount for the row's ingredient purity (drift
+// model — other rows are NOT rebalanced). Returns the amount technicians
+// weigh, the purity used, and the active amount it delivers. Sub-formula rows
+// and rows with no purity data pass through unchanged.
+function correctAmountForPurity(comp, amt) {
+  const passthrough = { amount: amt, purity: null, activeAmount: amt };
+  if (!comp || !comp.ingredientId || amt == null || !isFinite(amt)) return passthrough;
+  const ing = (typeof db !== 'undefined' && Array.isArray(db.ingredients))
+    ? db.ingredients.find(i => i.id === comp.ingredientId) : null;
+  const p = effectivePurity(ing);
+  if (p == null || !(p > 0) || p >= 100) return passthrough;
+  return { amount: amt / (p / 100), purity: p, activeAmount: amt };
+}
+
+// A composition row carrying this role is the "balance / q.s." ingredient:
+// at weigh-out it's set to whatever amount holds the batch at its target size
+// (absorbing the purity gross-up), so concentrations stay on-spec. Kept in
+// sync with the role option lists in js/views/formulations.js.
+const QS_ROLE = 'Balance (q.s.)';
+
+// Actual MASS of a set of as-prepared rows, in kg, from each row's OWN unit:
+// mass units directly; volume units × that ingredient's (or sub-formula's)
+// density — never the formula density, and never a sum of volumes. This is the
+// make-up-to-volume truth: weigh the solids, fill the solvent to the mark, log
+// what went in, and Σ row masses ÷ the mark volume is the finished density.
+// Returns { kg, n } or null when no row resolves / any comparable row can't.
+function sumActualRowsMassKg(rows, formula) {
+  if (!Array.isArray(rows)) return null;
+  let kg = 0, n = 0;
+  for (const c of rows) {
+    if (!c || !(c.ingredientId || c.formulationId)) continue;
+    const amt = parseFloat(c.amount);
+    if (!isFinite(amt)) continue;
+    const u = (c.unit || '').trim();
+    if (u in MASS_TO_KG) { kg += amt * MASS_TO_KG[u]; n++; continue; }
+    if (u in VOL_TO_L) {
+      let d = null;
+      if (c.ingredientId) {
+        const ing = (typeof db !== 'undefined' ? (db.ingredients || []) : []).find(i => i.id === c.ingredientId);
+        d = ing ? _densityToKgPerL(ing.density, ing.densityUnit) : null;
+      } else if (typeof _rolledUpDensity === 'function') {
+        const sub = (typeof db !== 'undefined' ? (db.formulations || []) : []).find(g => g.id === c.formulationId);
+        d = sub ? _rolledUpDensity(sub) : null;
+      }
+      if (d == null || !isFinite(d) || d <= 0) return null;
+      kg += amt * VOL_TO_L[u] * d; n++;
+    }
+    // % rows aren't absolute amounts — skipped, as everywhere else.
+  }
+  return n ? { kg, n } : null;
+}
+
+// Post-process weigh-out rows: if one row is the q.s. balance ingredient, set
+// its amount to targetQty − (sum of all other rows) so the total lands exactly
+// on target. Mutates rows in place. Returns { qsApplied, qsShort } — qsShort is
+// true when the other rows already exceed target (can't balance; balance
+// clamped to 0). Runs whenever a balance row exists, purity-corrected or not.
+function applyQsBalance(rows, targetQty) {
+  const out = { qsApplied: false, qsShort: false };
+  if (!Array.isArray(rows) || !isFinite(targetQty) || targetQty <= 0) return out;
+  const bi = rows.findIndex(r => r && r.comp && r.comp.role === QS_ROLE);
+  if (bi < 0) return out;
+  let others = 0;
+  rows.forEach((r, i) => { if (i !== bi && r.amount != null && isFinite(r.amount)) others += r.amount; });
+  let bal = targetQty - others;
+  out.qsApplied = true;
+  out.qsShort = bal < -1e-9;
+  if (out.qsShort) bal = 0;
+  rows[bi].amount = bal;
+  rows[bi].qs = true;          // panel shows a q.s. tag
+  rows[bi].purity = null;      // the balance row isn't purity-corrected
+  rows[bi].activeAmount = bal;
+  return out;
+}
+
+// Shared weigh-out panel (Tier 1/2). Renders planned per-ingredient amounts
+// and — once as-prepared actuals exist — Planned / Actual / Δ columns, all in
+// absolute amounts (the "more than percentages" bench view). Used by both
+// the batch detail and the sample modal.
+//   w           – result of _*PlannedWeighout(): { available, unit, qty, rows:[{key,name,amount,comp}], total, anyNull, reason, formula }
+//   actuals     – as-prepared composition rows ([{ ingredientId|formulationId, amount, unit }])
+//   formula     – linked formula (for density-aware unit conversion)
+//   copyOnclick – onclick string for the "Copy into As-prepared" button
+//   noun        – 'batch' | 'sample' (hint wording)
+// Volume-target explainer under the weigh-out subtitle: which density turned
+// the target volume into a mass, where it came from, and (finished density)
+// that the per-row volumes are pure-ingredient volumes that do not add up to
+// the target because mixing isn't additive. Empty for mass targets.
+function _weighoutDensityLineHtml(w) {
+  if (!w || !w.density || w.totalMassKg == null || !isFinite(w.totalMassKg)) return '';
+  const d = w.density;
+  const g = w.totalMassKg * 1000;
+  const mass = g >= 1000 ? `${+(g / 1000).toFixed(3)} kg` : `${+g.toFixed(1)} g`;
+  const rho = `${+d.kgPerL.toFixed(4)} g/mL`;
+  const temp = (d.temp != null && d.temp !== '') ? ` @ ${esc(String(d.temp))} °C` : '';
+  const qty = `${w.qty} ${esc(w.unit)}`;
+  if (d.source === 'finished') {
+    let src = d.how === 'measured' ? 'measured' : (d.how === 'spec' ? 'from spec' : 'entered');
+    if (d.batchId && typeof db !== 'undefined') {
+      const b = (db.batches || []).find(x => x.id === d.batchId);
+      if (b) src += ` on <a href="#" onclick="navigate('batch-detail','${esc(b.id)}');return false" style="color:#2563eb">${esc(b.uid)}</a>`;
+    }
+    const parts = (w.partsSum != null && isFinite(w.partsSum) && Math.abs(w.partsSum - w.qty) > 1e-6)
+      ? ` Pure-ingredient volumes sum to ${+w.partsSum.toFixed(2)} ${esc(w.unit)} — volumes aren't additive on mixing; the masses are what to weigh.` : '';
+    return `<div style="margin-top:4px;font-size:11.5px;color:#0f172a"><strong>${qty} ≙ ${mass}</strong> at finished density <strong>${rho}</strong>${temp} <span style="color:#64748b">(${src})</span>.${parts}</div>`;
+  }
+  return `<div style="margin-top:4px;font-size:11.5px;color:#92400e"><strong>${qty} ≙ ${mass}</strong> at <strong>${rho}</strong> — an <strong>ideal-mix estimate</strong> from the ingredient densities (assumes volumes add up; real mixes contract or expand). Record a measured density on a batch and adopt it as the formula's finished density to make this exact.</div>`;
+}
+
+function renderWeighoutPanel(w, actuals, formula, copyOnclick, noun) {
+  const fmt = n => (n == null || !isFinite(n)) ? '—' : parseFloat(n.toFixed(4)).toString();
+  const sgn = n => (n == null || !isFinite(n)) ? '—' : (n > 0 ? '+' : '') + parseFloat(n.toFixed(4)).toString();
+  if (!w || !w.available) {
+    if (w && w.reason === 'bad-unit')
+      return `<div style="padding:8px 11px;margin-bottom:12px;background:#fffbeb;border:1px solid #fde68a;border-radius:6px;color:#92400e;font-size:12px"><span class="fl-warn" aria-hidden="true"></span> Set the ${noun} quantity in a <strong>mass or volume unit</strong> (g, kg, mL, L…) to get a weigh-out sheet — currently <strong>${esc(w.unit || '—')}</strong>.</div>`;
+    if (w && w.reason === 'no-qty')
+      return `<div style="padding:8px 11px;margin-bottom:12px;background:#eff6ff;border:1px solid #bfdbfe;border-radius:6px;color:#1e40af;font-size:12px">Set a <strong>${noun} quantity</strong> to compute the per-ingredient weigh-out amounts technicians need.</div>`;
+    return '';
+  }
+  // Map as-prepared actuals by ingredient / sub-formula key. Only absolute
+  // (mass/volume) rows are comparable to the planned weigh-out — a row left in
+  // % is a concentration figure, handled by the proposal-vs-actual %-diff, not
+  // here, so it's skipped (the panel stays planned-only in that case).
+  const actMap = new Map();
+  (Array.isArray(actuals) ? actuals : []).forEach(c => {
+    const key = c.formulationId ? ('f:' + c.formulationId) : (c.ingredientId ? ('i:' + c.ingredientId) : '');
+    const amt = parseFloat(c.amount);
+    const u = c.unit || '';
+    const comparable = (typeof isMassUnit === 'function' && isMassUnit(u)) || (typeof isVolUnit === 'function' && isVolUnit(u));
+    if (key && comparable && isFinite(amt)) actMap.set(key, { amount: amt, unit: u });
+  });
+  const hasActuals = actMap.size > 0;
+  // ---- Display unit: show the whole sheet in any unit of the SAME dimension as
+  // the batch's target unit (a per-device preference), converting every amount
+  // through convertQuantity. Defaults to the batch unit; keeps one consistent
+  // unit per sheet (never mixed per row).
+  const _woDim = (typeof isMassUnit === 'function' && isMassUnit(w.unit)) ? 'mass'
+    : (typeof isVolUnit === 'function' && isVolUnit(w.unit)) ? 'volume' : null;
+  let displayUnit = w.unit;
+  if (_woDim) {
+    let pref = null; try { pref = localStorage.getItem('formlab_weighout_unit_' + _woDim); } catch (_) {}
+    if (pref && pref !== w.unit && typeof convertQuantity === 'function') {
+      const t = convertQuantity(1, w.unit, pref, formula);
+      if (t != null && isFinite(t)) displayUnit = pref;
+    }
+  }
+  const conv = amt => {
+    if (amt == null || !isFinite(amt)) return null;
+    if (displayUnit === w.unit) return amt;
+    const v = (typeof convertQuantity === 'function') ? convertQuantity(amt, w.unit, displayUnit, formula) : null;
+    return (v == null || !isFinite(v)) ? null : v;
+  };
+  const cv  = amt => fmt(conv(amt));    // convert + format
+  const cvs = amt => sgn(conv(amt));    // convert + signed format
+  // Offer EVERY supported unit of the batch's dimension, deduped by conversion
+  // factor (so µg/ug/mcg or t/ton/tonne collapse to one canonical spelling),
+  // plus the batch's own unit and any custom units — sorted smallest-first.
+  let _woUnits = [];
+  if (_woDim) {
+    const src = _woDim === 'mass' ? MASS_TO_KG : VOL_TO_L;
+    const customs = _woDim === 'mass' ? (typeof _customMassUnits === 'function' ? _customMassUnits() : {}) : (typeof _customVolUnits === 'function' ? _customVolUnits() : {});
+    const byFactor = new Map();
+    Object.keys(src).forEach(u => { const f = src[u]; if (!byFactor.has(f)) byFactor.set(f, u); });
+    const set = new Set([w.unit, ...byFactor.values()]);
+    Object.keys(customs || {}).forEach(u => set.add(u));
+    const factorOf = u => { const f = (u in src) ? src[u] : (customs && customs[u]); return (typeof f === 'number') ? f : 1; };
+    _woUnits = [...set].sort((a, b) => factorOf(a) - factorOf(b));
+  }
+  const _woResetBtn = (_woDim && displayUnit !== w.unit)
+    ? `<button type="button" onclick="_weighoutResetDisplayUnit('${_woDim}')" title="Reset to the batch's target unit (${esc(w.unit)})" style="font-size:11px;padding:2px 7px;border:1px solid var(--border);border-radius:5px;background:#fff;color:#64748b;cursor:pointer;white-space:nowrap">↺ ${esc(w.unit)}</button>`
+    : '';
+  const unitDropdown = (_woDim && _woUnits.length > 1)
+    ? `<span style="display:inline-flex;align-items:center;gap:6px;white-space:nowrap;margin-left:16px">
+        <label style="font-size:11px;color:#64748b;display:inline-flex;align-items:center;gap:4px;white-space:nowrap">show in
+          <select onchange="_weighoutSetDisplayUnit('${_woDim}', this.value)" title="Display the weigh-out amounts in this unit; the sheet stays in one consistent unit" style="padding:2px 6px;border:1px solid var(--border);border-radius:5px;font-size:11px;background:#fff">
+            ${_woUnits.map(u => `<option value="${esc(u)}" ${u === displayUnit ? 'selected' : ''}>${esc(u)}</option>`).join('')}
+          </select></label>
+        ${_woResetBtn}
+      </span>`
+    : '';
+  // A logged actual in another unit converts to the sheet's unit through THAT
+  // ROW's density (ingredient / sub-formula) — never the formula's. Cross-
+  // dimension with no row density → null (shown raw, not fabricated).
+  const toUnit = (amt, from, key) => {
+    if (amt == null || !isFinite(amt)) return null;
+    if (!from || from === w.unit) return amt;
+    if (typeof convertQuantityAtDensity !== 'function') return null;
+    const v = convertQuantityAtDensity(amt, from, w.unit, rowDensityKgPerL(key));
+    return (v == null || !isFinite(v)) ? null : v;
+  };
+  let actualTotal = 0;
+  const rows = w.rows.map(r => {
+    const a = actMap.get(r.key);
+    const planned = (r.amount != null && isFinite(r.amount)) ? r.amount : null;
+    let actInUnit = null;
+    if (a) { actInUnit = toUnit(a.amount, a.unit, r.key); if (actInUnit != null) actualTotal += actInUnit; }
+    const delta = (hasActuals && planned != null && actInUnit != null) ? (actInUnit - planned) : null;
+    const rel = (delta != null && planned > 0) ? Math.abs(delta) / planned : (delta != null && actInUnit > 0 ? 1 : null);
+    return { key: r.key, name: r.name, planned, actInUnit, actRaw: a, delta, rel, purity: r.purity, activeAmount: r.activeAmount, qs: r.qs, lotDev: r.lotDev || null };
+  });
+  // Union in ingredients that were ADDED to the As-prepared table but aren't in
+  // the recipe (a spike / colorant / q.s. carrier). Without this the weigh-out
+  // silently drops them from the comparison AND from the Actual total, so the
+  // total under-reports. They show with no Planned, their Actual amount, and a
+  // full deviation (they're all "extra").
+  if (hasActuals) {
+    const plannedKeys = new Set(w.rows.map(r => r.key));
+    actMap.forEach((a, key) => {
+      if (plannedKeys.has(key)) return;
+      const actInUnit = toUnit(a.amount, a.unit, key);
+      if (actInUnit != null) actualTotal += actInUnit;
+      let name = '(added)';
+      if (key.slice(0, 2) === 'i:') { const ing = (typeof db !== 'undefined' && db.ingredients || []).find(i => i.id === key.slice(2)); name = ing ? ing.name : '(added ingredient)'; }
+      else if (key.slice(0, 2) === 'f:') { const ff = (typeof db !== 'undefined' && db.formulations || []).find(x => x.id === key.slice(2)); name = ff ? '▸ ' + ff.name : '(added sub-formula)'; }
+      rows.push({ key, name, planned: null, actInUnit, actRaw: a, delta: actInUnit, rel: (actInUnit > 0 ? 1 : null), purity: null, activeAmount: null, qs: false, _added: true });
+    });
+  }
+  const _rNumFmt = v => (typeof _fmpNum === 'function') ? _fmpNum(v) : (Math.abs(v) >= 100 ? (+v).toFixed(1) : (+v).toFixed(3)).replace(/\.?0+$/, '');
+  const _purityTagBase = r => (r.purity == null) ? '' :
+    ` <span style="font-size:9.5px;color:#6d28d9;font-weight:600;background:#f5f3ff;border:1px solid #ddd6fe;border-radius:4px;padding:0 3px;vertical-align:middle;white-space:nowrap" title="Grossed up for ${esc(String(+r.purity))}% purity, delivers ${cv(r.activeAmount)} ${esc(displayUnit)} of active">↑${esc(String(+r.purity))}%</span>`;
+  // Lot-assay deviation: the lot this row draws from assays away from the nominal.
+  const purityTag = r => _purityTagBase(r) + (!r.lotDev ? '' :
+    ` <span style="font-size:9.5px;color:#b45309;font-weight:600;background:#fffbeb;border:1px solid #fde68a;border-radius:4px;padding:0 3px;vertical-align:middle;white-space:nowrap" title="Lot ${esc(String(r.lotDev.lotNumber))} assays ${esc(String(+r.lotDev.lotPurity))}% but the weigh-out is grossed up on the nominal ${esc(String(+r.lotDev.nominal))}%. ${r.lotDev.consumed ? 'This batch drew from that lot.' : 'FIFO will draw from that lot next.'} To deliver the spec active at the lot's assay, weigh ${r.lotDev.correctedAmount != null ? esc(_rNumFmt(r.lotDev.correctedAmount)) + ' ' + esc(String(displayUnit || w.unit || '')) : 'the corrected amount'} instead.">⚠ lot ${esc(String(+r.lotDev.lotPurity))}% vs ${esc(String(+r.lotDev.nominal))}%${r.lotDev.correctedAmount != null ? ' → ' + esc(_rNumFmt(r.lotDev.correctedAmount)) : ''}</span>`);
+  const _woVolTarget = (typeof isVolUnit === 'function') && isVolUnit(w.unit);
+  const qsTag = r => (!r.qs) ? '' :
+    ` <span style="font-size:9.5px;color:#0369a1;font-weight:600;background:#eff6ff;border:1px solid #bfdbfe;border-radius:4px;padding:0 3px;vertical-align:middle;white-space:nowrap" title="${_woVolTarget ? `Balance ingredient — add it up to the ${w.qty} ${esc(w.unit)} mark rather than to this number, then log what actually went in` : 'Balance ingredient, set to hold the batch at its target size'}">${_woVolTarget ? `q.s. to ${w.qty} ${esc(w.unit)}` : 'q.s.'}</span>`;
+  const dColor = rel => rel == null ? '#94a3b8' : (rel < 0.02 ? '#15803d' : rel < 0.10 ? '#b45309' : '#b91c1c');
+  // Tint a whole row when it deviates, so off-plan ingredients pop at a glance
+  // (matches the composition-% table's row tinting). On-target rows stay white.
+  const dRowBg = rel => (rel == null || rel < 0.02) ? '' : (rel < 0.10 ? 'background:#fffbeb' : 'background:#fef2f2');
+  // ---- Secondary reference column: each row shown in the OTHER dimension,
+  // derived per-row from that ingredient's OWN density (sub-formulas use their
+  // rolled-up density). The prepared unit stays the single basis; this is a
+  // read-only convenience for batches that mix weighed and measured rows.
+  // A row with no density shows — (never guessed from the formula aggregate),
+  // and there's no total (the derived dimension isn't additive across rows).
+  const _altDim = _woDim === 'mass' ? 'volume' : (_woDim === 'volume' ? 'mass' : null);
+  const _ALT_SIBLING = { kg: 'L', g: 'mL', mg: 'µL', L: 'kg', mL: 'g', 'µL': 'mg' };
+  // Units offered for the ≈ column — every supported unit of the ALT dimension,
+  // deduped by conversion factor + any customs, smallest-first (mirrors the
+  // show-in list). The column unit is a per-device preference; with none set it
+  // auto-tracks the display unit's scale (g→mL, kg→L) via _ALT_SIBLING.
+  let _altUnits = [];
+  if (_altDim) {
+    const src = _altDim === 'mass' ? MASS_TO_KG : VOL_TO_L;
+    const customs = _altDim === 'mass' ? (typeof _customMassUnits === 'function' ? _customMassUnits() : {}) : (typeof _customVolUnits === 'function' ? _customVolUnits() : {});
+    const byFactor = new Map();
+    Object.keys(src).forEach(u => { const f = src[u]; if (!byFactor.has(f)) byFactor.set(f, u); });
+    const set = new Set([...byFactor.values()]);
+    Object.keys(customs || {}).forEach(u => set.add(u));
+    const factorOf = u => { const f = (u in src) ? src[u] : (customs && customs[u]); return (typeof f === 'number') ? f : 1; };
+    _altUnits = [...set].sort((a, b) => factorOf(a) - factorOf(b));
+  }
+  let _altPref = null; try { _altPref = _altDim ? localStorage.getItem('formlab_weighout_altunit_' + _altDim) : null; } catch (_) {}
+  const altUnit = _altDim
+    ? ((_altPref && _altUnits.indexOf(_altPref) !== -1) ? _altPref : (_ALT_SIBLING[displayUnit] || (_altDim === 'volume' ? 'mL' : 'g')))
+    : null;
+  const rowDensity = r => {
+    const key = (r && r.key) || '';
+    if (key.slice(0, 2) === 'f:') { const sf = db.formulations.find(g => g.id === key.slice(2)); return (sf && typeof _rolledUpDensity === 'function') ? _rolledUpDensity(sf) : null; }
+    if (key.slice(0, 2) === 'i:') { const ing = db.ingredients.find(i => i.id === key.slice(2)); return (ing && typeof _densityToKgPerL === 'function') ? _densityToKgPerL(ing.density, ing.densityUnit) : null; }
+    return null;
+  };
+  const altConv = (amt, d) => {
+    if (amt == null || !isFinite(amt) || d == null || !isFinite(d) || d <= 0 || !altUnit) return null;
+    if (_woDim === 'mass')   { const kg = amt * massToKg(w.unit); const b = volToL(altUnit);  return (b != null) ? (kg / d) / b : null; }
+    if (_woDim === 'volume') { const L  = amt * volToL(w.unit);  const b = massToKg(altUnit); return (b != null) ? (L * d) / b : null; }
+    return null;
+  };
+  // ≈ column shows the row's PRIMARY amount in the other dimension — planned for
+  // recipe rows, but the ACTUAL amount for an added ("not in recipe") row, which
+  // has no planned. Otherwise a density-bearing add (e.g. TiO2) shows a blank ≈.
+  const _altAmt = r => (r.planned != null) ? r.planned : r.actInUnit;
+  const altCell = r => {
+    const v = altConv(_altAmt(r), rowDensity(r));
+    if (v == null) return `<span style="color:#cbd5e1" title="No density set for this ingredient — add one to show its ${esc(_altDim || '')} equivalent">—</span>`;
+    return `≈ ${fmt(v)} <span translate="no" style="color:#94a3b8;font-size:10px">${esc(altUnit)}</span>`;
+  };
+  const _altAny = !!_altDim && rows.some(r => altConv(_altAmt(r), rowDensity(r)) != null);
+  // Unit picker for the ≈ column (mirrors the show-in dropdown). Only when the
+  // column is actually showing and there's more than one unit to choose.
+  const altDropdown = (_altAny && _altDim && _altUnits.length > 1)
+    ? `<span style="display:inline-flex;align-items:center;gap:6px;white-space:nowrap;margin-left:10px">
+        <label style="font-size:11px;color:#64748b;display:inline-flex;align-items:center;gap:4px;white-space:nowrap">≈ in
+          <select onchange="_weighoutSetAltUnit('${_altDim}', this.value)" title="Unit for the ≈ reference column — the other dimension, derived per-ingredient from its density" style="padding:2px 6px;border:1px solid var(--border);border-radius:5px;font-size:11px;background:#fff">
+            ${_altUnits.map(u => `<option value="${esc(u)}" ${u === altUnit ? 'selected' : ''}>${esc(u)}</option>`).join('')}
+          </select></label>
+      </span>`
+    : '';
+  const th = (txt, extra = '') => `<th style="padding:5px 8px;color:#475569;font-weight:400;${extra}">${txt}</th>`;
+  const head = `<tr style="background:#eff6ff">
+    ${th('#', 'text-align:left;width:28px')}
+    ${th('Ingredient / Sub-formula', 'text-align:left')}
+    ${th('Planned', 'text-align:right')}
+    ${hasActuals ? th('Actual', 'text-align:right') + th('Δ', 'text-align:right') : ''}
+    ${th('Unit', 'text-align:left')}
+    ${_altAny ? `<th style="padding:5px 8px;color:#475569;font-weight:400;text-align:right" title="Approx. ${esc(_altDim || '')} equivalent, derived per-ingredient from its own density. Reference only — not additive, so no total.">≈ ${esc(altUnit)}</th>` : ''}
+  </tr>`;
+  const body = rows.map((r, i) => `<tr data-wo-key="${esc(r.key)}" style="${hasActuals ? dRowBg(r.rel) : ''}">
+    <td style="padding:4px 8px;color:#94a3b8">${i + 1}</td>
+    <td style="padding:4px 8px">${esc(r.name)}${r._added ? ` <span style="font-size:9.5px;color:#b91c1c;font-weight:600;background:#fef2f2;border:1px solid #fecaca;border-radius:4px;padding:0 4px;vertical-align:middle;white-space:nowrap" title="Added to the as-prepared batch — not part of the linked recipe">+ not in recipe</span>` : ''}</td>
+    <td style="padding:4px 8px;text-align:right;font-variant-numeric:tabular-nums;font-weight:600;color:#0f172a">${r.planned != null ? `${cv(r.planned)}${purityTag(r)}${qsTag(r)}` : '<span style="color:#cbd5e1">—</span>'}</td>
+    ${hasActuals ? `<td style="padding:4px 8px;text-align:right;font-variant-numeric:tabular-nums">${
+      r.actInUnit != null ? cv(r.actInUnit)
+        : (r.actRaw ? `${fmt(r.actRaw.amount)} <span translate="no" style="color:#94a3b8;font-size:10px">${esc(r.actRaw.unit)}</span>` : '<span style="color:#cbd5e1">—</span>')
+    }</td>
+    <td style="padding:4px 8px;text-align:right;font-variant-numeric:tabular-nums;color:${dColor(r.rel)};font-weight:${r.delta ? 600 : 400}">${r.delta != null ? cvs(r.delta) : '—'}</td>` : ''}
+    <td style="padding:4px 8px;color:#64748b">${esc(displayUnit)}</td>
+    ${_altAny ? `<td style="padding:4px 8px;text-align:right;font-variant-numeric:tabular-nums;color:#64748b">${altCell(r)}</td>` : ''}
+  </tr>`).join('');
+  const totalDelta = hasActuals ? (actualTotal - w.total) : null;
+  // Volume target: the Planned column's sum is the sum of PURE-ingredient
+  // volumes — not a lab quantity (the finished batch is w.qty, and mixing isn't
+  // additive). Say so on the row, and put the number that IS real — the total
+  // mass to weigh, V × ρ — in the ≈ mass column instead of a dash.
+  const _volTarget = _woVolTarget && w.totalMassKg != null && isFinite(w.totalMassKg);
+  const _totalMassCell = (() => {
+    if (!_volTarget || !_altAny || _altDim !== 'mass') return null;
+    const g = w.totalMassKg * 1000;
+    const inAlt = (typeof convertQuantity === 'function') ? convertQuantity(g, 'g', altUnit, formula) : null;
+    return (inAlt != null && isFinite(inAlt)) ? `<strong>${fmt(inAlt)}</strong> <span translate="no" style="color:#94a3b8;font-size:10px">${esc(altUnit)}</span>` : null;
+  })();
+  const tfoot = `<tr style="border-top:1px solid #dbeafe">
+    <td></td><td style="padding:5px 8px;font-weight:600">Total${_volTarget ? ` <span style="font-weight:400;color:#94a3b8;font-size:10.5px" title="Sum of the pure-ingredient volumes in the Planned column. Not a lab quantity — the finished batch is ${w.qty} ${esc(w.unit)}; the mass in the ≈ column is what the batch weighs.">(pure-ingredient volumes)</span>` : ''}</td>
+    <td style="padding:5px 8px;text-align:right;font-variant-numeric:tabular-nums;font-weight:${_volTarget ? 400 : 700};color:${_volTarget ? '#94a3b8' : 'inherit'}" title="${_volTarget ? `Volumes aren't additive on mixing — this sum has no bench meaning. Finished batch: ${w.qty} ${esc(w.unit)}.` : ''}">${cv(w.total)}</td>
+    ${hasActuals ? `<td style="padding:5px 8px;text-align:right;font-variant-numeric:tabular-nums;font-weight:700">${cv(actualTotal)}</td>
+      <td style="padding:5px 8px;text-align:right;font-variant-numeric:tabular-nums;color:#64748b">${cvs(totalDelta)}</td>` : ''}
+    <td style="padding:5px 8px;color:#64748b">${esc(displayUnit)}</td>
+    ${_altAny ? (_totalMassCell
+      ? `<td style="padding:5px 8px;text-align:right;font-variant-numeric:tabular-nums" title="Total mass of the finished ${w.qty} ${esc(w.unit)} = volume × finished density. This is what the batch weighs — the number to reconcile the balance against.">${_totalMassCell}</td>`
+      : `<td style="padding:5px 8px;text-align:right;color:#cbd5e1" title="No total — the ${esc(_altDim || '')} equivalent isn't additive across ingredients">—</td>`) : ''}
+  </tr>`;
+  const densityNote = w.anyNull
+    ? `<div style="margin-top:7px;font-size:11.5px;color:#92400e"><span class="fl-warn" aria-hidden="true"></span> Some rows can't be scaled to ${esc(displayUnit)} — set the formula / ingredient <strong>density</strong> to convert % across mass↔volume.</div>`
+    : '';
+  // Purity / q.s. footer. Three cases: q.s. balanced (on target), q.s. short
+  // (actives exceed target), or drift (corrected, no balance ingredient).
+  let purityNote = '';
+  if (w.qsApplied && w.qsShort) {
+    purityNote = `<div style="margin-top:7px;font-size:11.5px;color:#b91c1c"><span class="fl-warn" aria-hidden="true"></span> Purity-corrected amounts already <strong>exceed the ${cv(w.qty)} ${esc(displayUnit)} target</strong> — the q.s. ingredient can't balance it (clamped to 0). Increase the batch size or reduce the actives.</div>`;
+  } else if (w.qsApplied && w.correctedAny) {
+    purityNote = `<div style="margin-top:7px;font-size:11.5px;color:#0369a1">↑ Actives <strong>grossed up for purity</strong>; the <strong>q.s. ingredient</strong> was shrunk to hold the batch at <strong>${cv(w.total)} ${esc(displayUnit)}</strong> — on target, concentrations on-spec.</div>`;
+  } else if (w.correctedAny && w.nominalTotal != null && isFinite(w.nominalTotal)) {
+    purityNote = `<div style="margin-top:7px;font-size:11.5px;color:#5b21b6">↑ Amounts <strong>grossed up for purity</strong> so each delivers its target active. Total <strong>${cv(w.total)} ${esc(displayUnit)}</strong> vs ${cv(w.nominalTotal)} nominal (+${cv(w.total - w.nominalTotal)}). Other rows are unchanged, so the batch runs a little over target — mark a diluent's role <strong>“${esc(QS_ROLE)}”</strong> to auto-balance back to ${cv(w.qty)} ${esc(displayUnit)}.</div>`;
+  }
+  // Make-up-to-volume instruction: a VOLUME target with a balance row is best
+  // made the pharmacist's way — weigh everything else, fill the balance
+  // ingredient to the mark, log what went in. Nobody has to predict the
+  // contraction; the logged masses ÷ the mark give the finished density, which
+  // the batch page then offers to adopt on the formula.
+  let makeUpNote = '';
+  const _qsRow = w.rows.find(r => r.qs);
+  if (_woVolTarget && w.qsApplied && _qsRow && !hasActuals) {
+    const bal = (_qsRow.amount != null && isFinite(_qsRow.amount)) ? _qsRow.amount : null;
+    const balMass = (bal != null && typeof convertQuantity === 'function' && _qsRow.comp && _qsRow.comp.ingredientId)
+      ? (() => { const ing = (db.ingredients || []).find(i => i.id === _qsRow.comp.ingredientId); const d = ing ? _densityToKgPerL(ing.density, ing.densityUnit) : null; return (d && VOL_TO_L[w.unit]) ? bal * VOL_TO_L[w.unit] * d * 1000 : null; })() : null;
+    makeUpNote = `<div style="margin-top:7px;padding:7px 10px;background:#f0f9ff;border:1px solid #bae6fd;border-radius:6px;font-size:11.5px;color:#0c4a6e;line-height:1.45"><strong>Make up to volume.</strong> Weigh the other rows as planned, then add <strong>${esc(_qsRow.name)}</strong> up to the <strong>${w.qty} ${esc(w.unit)}</strong> mark and log the amount that actually went in${balMass != null ? ` (planned ≈ ${+balMass.toFixed(1)} g)` : ''}. Volumes aren't additive, so the mark — not the planned number — decides the balance. Once logged, the batch page derives the finished density from the total mass ÷ ${w.qty} ${esc(w.unit)} and offers to save it on the formula for next time.</div>`;
+  }
+  const title = hasActuals ? '⚖ Weigh-out — planned vs actual amounts' : '⚖ Weigh-out — target amounts';
+  // One-line explainer so this table's job (concrete amounts) is unmistakable
+  // and distinct from the composition-% table below it on the batch page.
+  const subtitle = (hasActuals
+    ? `How much of each ingredient to weigh, in <strong>${esc(displayUnit)}</strong>. <strong>Planned</strong> = the recipe scaled to ${cv(w.qty)} ${esc(displayUnit)}; <strong>Actual</strong> = what you logged as prepared.`
+    : `How much of each ingredient to weigh for a ${cv(w.qty)} ${esc(displayUnit)} ${esc(noun)}, in <strong>${esc(displayUnit)}</strong>.`)
+    + _weighoutDensityLineHtml(w);
+  // Yield headline: the as-prepared input total vs the batch target, up front —
+  // so a proportional over/under-make reads as a yield note, not as a mystery
+  // (this is the "why is it +0.2 kg but composition matches" answer, surfaced).
+  let yieldBanner = '';
+  if (hasActuals && isFinite(actualTotal) && actualTotal > 0 && isFinite(w.qty) && w.qty > 0) {
+    const d = actualTotal - w.qty;
+    const pct = (d / w.qty) * 100;
+    const near = Math.abs(pct) < 0.5;
+    const mag = Math.abs(pct);
+    const c  = near ? '#15803d' : (mag < 5 ? '#b45309' : '#b91c1c');
+    const bg = near ? '#f0fdf4' : (mag < 5 ? '#fffbeb' : '#fef2f2');
+    const bd = near ? '#bbf7d0' : (mag < 5 ? '#fde68a' : '#fecaca');
+    yieldBanner = `<div style="display:flex;align-items:baseline;gap:8px;flex-wrap:wrap;margin:0 0 10px;padding:8px 12px;background:${bg};border:1px solid ${bd};border-radius:7px;font-size:13px">
+      <span style="font-weight:700;color:${c}">As-prepared total ${cv(actualTotal)} ${esc(displayUnit)}</span>
+      ${near
+        ? `<span style="color:#15803d;font-weight:600">✓ on the ${cv(w.qty)} ${esc(displayUnit)} target</span>`
+        : `<span style="color:${c};font-weight:600">${cvs(d)} ${esc(displayUnit)} (${d > 0 ? '+' : ''}${pct.toFixed(1)}%) ${d > 0 ? 'over' : 'under'} the ${cv(w.qty)} ${esc(displayUnit)} target</span>`}
+    </div>`;
+  }
+  const copyLabel = hasActuals ? '<span class="fl-import" aria-hidden="true"></span> Reset to planned' : '<span class="fl-import" aria-hidden="true"></span> Copy into As-prepared';
+  return `
+  <div style="border:1px solid #dbeafe;border-radius:8px;padding:12px 14px;margin-bottom:12px;background:#f8fbff">
+    <div style="display:flex;align-items:center;gap:8px;margin-bottom:2px;flex-wrap:wrap">
+      <span style="font-size:13px;font-weight:600;color:#0f172a">${title}</span>
+      <span style="font-size:11.5px;color:#64748b">scaled to ${cv(w.qty)} ${esc(displayUnit)}</span>
+      ${unitDropdown}
+      ${altDropdown}
+      <button type="button" class="btn btn-secondary btn-sm" style="margin-left:auto" onclick="${copyOnclick}" title="Seed / reset the as-prepared amounts to the planned weigh-out, then edit each to what you actually weighed.">${copyLabel}</button>
+    </div>
+    <div style="font-size:11px;color:#64748b;line-height:1.5;margin:0 0 9px">${subtitle}</div>
+    ${yieldBanner}
+    <table style="width:100%;border-collapse:collapse;font-size:12px">
+      <thead>${head}</thead>
+      <tbody>${body}</tbody>
+      <tfoot>${tfoot}</tfoot>
+    </table>
+    ${densityNote}
+    ${purityNote}${makeUpNote}
+  </div>`;
+}
+
+// Re-render every weigh-out panel on screen (batch + sample) AND the
+// Proposal-vs-As-prepared diff card (its Δ column shares the same unit), in place.
+function _weighoutRerenderPanels() {
+  try {
+    document.querySelectorAll('[id^="batch-weighout-"]').forEach(el => {
+      const b = (typeof getBatch === 'function') ? getBatch(el.id.slice('batch-weighout-'.length)) : null;
+      if (b && typeof _batchWeighoutPanelHtml === 'function') el.innerHTML = _batchWeighoutPanelHtml(b);
+    });
+    document.querySelectorAll('[id^="sm-weighout-"]').forEach(el => {
+      const s = (typeof getSample === 'function') ? getSample(el.id.slice('sm-weighout-'.length)) : null;
+      if (s && typeof _sampleWeighoutPanelHtml === 'function') el.innerHTML = _sampleWeighoutPanelHtml(s);
+    });
+    document.querySelectorAll('[id^="batch-actual-diff-"]').forEach(el => {
+      const id = el.id.slice('batch-actual-diff-'.length);
+      if (typeof renderBatchActualDiff === 'function') el.innerHTML = renderBatchActualDiff(id);
+    });
+  } catch (_) {}
+}
+// Persist a per-dimension weigh-out display unit (per-device preference) + re-render.
+function _weighoutSetDisplayUnit(dim, unit) {
+  try { localStorage.setItem('formlab_weighout_unit_' + dim, unit); } catch (_) {}
+  _weighoutRerenderPanels();
+}
+// Reset the weigh-out display unit back to each sheet's own target unit.
+function _weighoutResetDisplayUnit(dim) {
+  try { localStorage.removeItem('formlab_weighout_unit_' + dim); } catch (_) {}
+  _weighoutRerenderPanels();
+}
+// Persist the ≈ reference column's unit (per alt-dimension, per-device) + re-render.
+function _weighoutSetAltUnit(dim, unit) {
+  try { localStorage.setItem('formlab_weighout_altunit_' + dim, unit); } catch (_) {}
+  _weighoutRerenderPanels();
+}
+
+// Heuristic: pick a default for the "% of Total" basis based on which
+// unit dimension the highest-cost-contributing row uses. Falls back to
+// mass when nothing is priced yet.
+function defaultPercentBasis(formulation, costSummary) {
+  const isVolUnit = u => {
+    const s = String(u || '').toLowerCase().trim();
+    if (s.startsWith('vol')) return true;
+    const canon = (() => {
+      if (s in VOL_TO_L) return true;
+      for (const k of Object.keys(VOL_TO_L)) if (k.toLowerCase() === s) return true;
+      return false;
+    })();
+    return canon;
+  };
+  if (costSummary?.breakdown?.length) {
+    const top = costSummary.breakdown.reduce(
+      (best, b) => (b.contribution > (best?.contribution ?? -Infinity) ? b : best),
+      null
+    );
+    if (top) return isVolUnit(top.unit) ? 'volume' : 'mass';
+  }
+  // Fallback: scan composition units alone
+  const comp = formulation?.composition || [];
+  const volRows  = comp.filter(c => isVolUnit(c.unit)).length;
+  const massRows = comp.length - volRows;
+  return volRows > massRows ? 'volume' : 'mass';
+}
+
+// ============================================================
+// BATCH + PROJECT COST ROLLUP
+// ============================================================
+// Approximate kg conversion for batch.targetQuantity.unit. If
+// volume, falls back to *assume kg* unless density is known.
+function computeBatchCost(batch, displayCcy = getDisplayCurrency()) {
+  const f = db.formulations.find(x => x.id === batch.formulationId);
+  if (!f) return null;
+  const perKg = computeFormulationCost(f, displayCcy);
+  // Batch size in kg via the shared quantityToKg (mass units convert directly;
+  // volume units use the formula's rolled-up density). This is the SAME path the
+  // sample/detail-field "Cost" cell uses, so the card and that field always agree.
+  // (It replaced a private _batchSizeInKg that lowercased the unit before a
+  // case-sensitive VOL_TO_L lookup — so "L" became "l", missed the table, and
+  // every volume-unit batch silently reported no total.)
+  const _umk = (typeof _batchUnitMassKg === 'function') ? _batchUnitMassKg(batch) : null;
+  const sizeKg = quantityToKg(batch.targetQuantity, batch.unit, f, _umk);
+  return {
+    formulation: f,
+    perKg: perKg.perKg,
+    sizeKg,
+    total: sizeKg != null ? perKg.perKg * sizeKg : null,
+    currency: displayCcy,
+    missing: perKg.missing,
+  };
+}
+
+// Finished-goods best-by: a formulation's shelf life (months) applied to a
+// prepared date → the expiry Date (or ISO string). Null when there's no shelf
+// life on the formula or the prepared date is missing/unparseable. Shared by the
+// inventory roll-up, batch detail/list and sample detail/list so they agree.
+function shelfLifeExpiry(formulation, preparedDate) {
+  const m = formulation && formulation.shelfLifeMonths;
+  if (m == null || m === '' || !isFinite(+m) || +m <= 0) return null;
+  const pm = Date.parse(preparedDate);
+  if (!isFinite(pm)) return null;
+  // UTC arithmetic: a date-only prepared date parses as UTC midnight, and adding
+  // months in LOCAL time then reading the UTC day back landed a day early for
+  // US users whenever the span crossed a DST change (build 33w). A day past the
+  // target month's end clamps to its last day (Jan 31 + 1 month = Feb 28/29).
+  const d = new Date(pm);
+  const day = d.getUTCDate();
+  d.setUTCDate(1);
+  d.setUTCMonth(d.getUTCMonth() + (+m));
+  const last = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate();
+  d.setUTCDate(Math.min(day, last));
+  return d;
+}
+function shelfLifeExpiryISO(formulation, preparedDate) {
+  const d = shelfLifeExpiry(formulation, preparedDate);
+  return d ? d.toISOString().slice(0, 10) : null;
+}
+// A small coloured badge for a best-by date (red if past, amber if ≤30d).
+function shelfLifeBadgeHtml(iso) {
+  if (!iso) return '—';
+  const d = Math.floor((Date.parse(iso) - Date.now()) / 86400000);
+  let style = 'color:var(--text)', note = '';
+  if (d < 0) { style = 'background:#fee2e2;color:#991b1b;padding:1px 7px;border-radius:10px;font-weight:600'; note = ' · expired'; }
+  else if (d <= 30) { style = 'background:#fef3c7;color:#b45309;padding:1px 7px;border-radius:10px;font-weight:600'; note = ` · ${d}d`; }
+  else if (d <= 90) { style = 'color:#b45309'; note = ` · ${d}d`; }
+  return `<span style="${style}">${(typeof esc === 'function' ? esc(iso) : iso)}${note}</span>`;
+}
+
+function computeProjectCost(projectId, displayCcy = getDisplayCurrency()) {
+  const project = db.projects.find(p => p.id === projectId);
+  if (!project) return null;
+  const formulations = db.formulations.filter(f => f.projectId === projectId);
+  const batches = db.batches.filter(b => formulations.some(f => f.id === b.formulationId));
+  const batchSummaries = batches.map(b => ({ batch: b, summary: computeBatchCost(b, displayCcy) }))
+    .filter(x => x.summary);
+  const total = batchSummaries.reduce((s, x) => s + (x.summary.total || 0), 0);
+  const counted = batchSummaries.filter(x => x.summary.total != null).length;
+  return {
+    project,
+    currency: displayCcy,
+    batchCount: batches.length,
+    pricedBatchCount: counted,
+    total,
+    batchSummaries,
+  };
+}
+
+// ============================================================
+// PRICE CHANGE / ALERTS — uses ing.cost.history (set on save).
+// Compares the current cost to the OLDEST history entry by default;
+// returns percent change in the cost's own currency, normalized to
+// $/kg so different units don't distort the comparison.
+// ============================================================
+function ingredientCostChangePct(ing) {
+  if (!ing?.cost?.history?.length) return null;
+  const cur = costPerKgInOwnCurrency(ing.cost, ing.density, ing.densityUnit);
+  // Walk back to oldest entry that has a comparable per-kg value
+  for (let i = 0; i < ing.cost.history.length; i++) {
+    const old = ing.cost.history[i];
+    const oldPerKg = costPerKgInOwnCurrency(old, ing.density, ing.densityUnit);
+    // Convert to same currency for fair comparison
+    const oldInCurCcy = convertCurrencySync(oldPerKg, old.currency || 'USD', ing.cost.currency || 'USD');
+    if (cur != null && oldInCurCcy && oldInCurCcy > 0) {
+      return { pct: (cur - oldInCurCcy) / oldInCurCcy * 100, baseline: oldInCurCcy, current: cur, since: old.updatedAt };
+    }
+  }
+  return null;
+}
+
+function getPriceAlerts(thresholdPct = 10) {
+  const alerts = [];
+  for (const ing of db.ingredients) {
+    const change = ingredientCostChangePct(ing);
+    if (change && Math.abs(change.pct) >= thresholdPct) {
+      alerts.push({ ingredient: ing, ...change });
+    }
+  }
+  alerts.sort((a, b) => Math.abs(b.pct) - Math.abs(a.pct));
+  return alerts;
+}
+
+// ============================================================
+// PHYSICAL-QUANTITY COST (samples / batches)
+// A sample (quantity) or batch (targetQuantity) is a physical amount of
+// a formula, so its cost = formula $/kg × quantity-in-kg. Mass units
+// convert directly; volume units need the formula's rolled-up density.
+// ============================================================
+// Convert a quantity between units for budget bookkeeping. Mass↔mass and
+// volume↔volume convert directly; mass↔volume needs the formula's rolled-up
+// density (kg/L). Returns the value in `toUnit`, or null when not possible
+// (count/"each" units, or cross-dimension with no known density).
+function convertQuantity(value, fromUnit, toUnit, formula) {
+  const dens = (typeof _rolledUpDensity === 'function') ? _rolledUpDensity(formula) : null; // kg/L
+  return convertQuantityAtDensity(value, fromUnit, toUnit, dens);
+}
+
+// Same conversion with an EXPLICIT density (kg/L === g/mL). Use this for a
+// single ingredient row — 41.86 g of sucrose is 26.3 mL at sucrose's 1.59,
+// not 40 mL at the formula's 1.0465. Mass↔volume without a density → null.
+function convertQuantityAtDensity(value, fromUnit, toUnit, dens) {
+  const v = parseFloat(value);
+  if (!isFinite(v)) return null;
+  const from = (fromUnit || '').trim(), to = (toUnit || '').trim();
+  if (!to) return null;
+  if (from === to) return v;
+  const fM = (typeof isMassUnit === 'function') && isMassUnit(from);
+  const tM = (typeof isMassUnit === 'function') && isMassUnit(to);
+  const fV = (typeof isVolUnit === 'function') && isVolUnit(from);
+  const tV = (typeof isVolUnit === 'function') && isVolUnit(to);
+  if (fM && tM) { const a = massToKg(from), b = massToKg(to); return (a != null && b != null) ? v * a / b : null; }
+  if (fV && tV) { const a = volToL(from),  b = volToL(to);  return (a != null && b != null) ? v * a / b : null; }
+  if (dens == null || !isFinite(dens) || dens <= 0) return null;
+  if (fM && tV) { const kg = v * massToKg(from); const L = kg / dens; const b = volToL(to);  return (b != null) ? L / b : null; }
+  if (fV && tM) { const L  = v * volToL(from);  const kg = L * dens;  const b = massToKg(to); return (b != null) ? kg / b : null; }
+  return null;
+}
+
+// Density (kg/L) of ONE composition row: an ingredient's own density, or a
+// sub-formula's planning density. Keyed 'i:<id>' / 'f:<id>' like the
+// weigh-out rows, or pass a composition row object. null when unknown.
+function rowDensityKgPerL(keyOrRow) {
+  let ingId = null, subId = null;
+  if (typeof keyOrRow === 'string') {
+    if (keyOrRow.slice(0, 2) === 'i:') ingId = keyOrRow.slice(2);
+    else if (keyOrRow.slice(0, 2) === 'f:') subId = keyOrRow.slice(2);
+  } else if (keyOrRow) { ingId = keyOrRow.ingredientId || null; subId = keyOrRow.formulationId || null; }
+  const D = (typeof db !== 'undefined') ? db : { ingredients: [], formulations: [] };
+  if (ingId) { const ing = (D.ingredients || []).find(i => i.id === ingId); return ing ? _densityToKgPerL(ing.density, ing.densityUnit) : null; }
+  if (subId) { const sf = (D.formulations || []).find(g => g.id === subId); return (sf && typeof _rolledUpDensity === 'function') ? _rolledUpDensity(sf) : null; }
+  return null;
+}
+
+// Classify whether `fromUnit` can be expressed as `toUnit`:
+//   'same'         — identical units
+//   'ok'           — same dimension, or cross-dimension with a known density
+//   'needs-density'— mass↔volume but the formula has no density (FIXABLE)
+//   'incompatible' — count/unknown units that no density can bridge
+// Lets callers show a light, actionable warning instead of a silent "—".
+function unitConvertibility(fromUnit, toUnit, formula) {
+  const from = (fromUnit || '').trim(), to = (toUnit || '').trim();
+  if (!from || !to || from === to) return 'same';
+  const fM = (typeof isMassUnit === 'function') && isMassUnit(from);
+  const tM = (typeof isMassUnit === 'function') && isMassUnit(to);
+  const fV = (typeof isVolUnit === 'function') && isVolUnit(from);
+  const tV = (typeof isVolUnit === 'function') && isVolUnit(to);
+  if ((fM && tM) || (fV && tV)) return 'ok';
+  if ((fM && tV) || (fV && tM)) {
+    const dens = (typeof _rolledUpDensity === 'function') ? _rolledUpDensity(formula) : null;
+    return (dens != null && isFinite(dens) && dens > 0) ? 'ok' : 'needs-density';
+  }
+  return 'incompatible';
+}
+
+function quantityToKg(qty, unit, formula, unitMassKg) {
+  const q = parseFloat(qty);
+  if (!isFinite(q) || q <= 0) return null;
+  const u = unit || '';
+  if (typeof isMassUnit === 'function' && isMassUnit(u)) {
+    const f = massToKg(u); return (f != null) ? q * f : null;
+  }
+  if (typeof isVolUnit === 'function' && isVolUnit(u)) {
+    const litres = volToL(u); if (litres == null) return null;
+    const dens = (typeof _rolledUpDensity === 'function') ? _rolledUpDensity(formula) : null; // kg/L
+    if (dens == null || !isFinite(dens)) return null;
+    return q * litres * dens;
+  }
+  // Count unit (tablet / capsule / unit / piece …) with a known per-unit mass:
+  // total mass = count × mass-per-unit. Lets dose-form batches have a cost/yield.
+  if (unitMassKg != null && isFinite(unitMassKg) && unitMassKg > 0) return q * unitMassKg;
+  return null;
+}
+
+// Returns { perKg, kg, computed, ccy, convertible } in the display currency.
+function quantityCost(qty, unit, formula, displayCcy) {
+  const ccy = displayCcy ||
+    (typeof getDisplayCurrency === 'function' ? getDisplayCurrency() : null) ||
+    (formula && formula.costCurrency) || 'USD';
+  let perKg = null;
+  try {
+    const c = formula && typeof computeFormulationCost === 'function' ? computeFormulationCost(formula, ccy) : null;
+    if (c && isFinite(c.perKg)) perKg = c.perKg;
+  } catch (_) { perKg = null; }
+  const kg = quantityToKg(qty, unit, formula);
+  const computed = (perKg != null && kg != null) ? perKg * kg : null;
+  return { perKg, kg, computed, ccy, convertible: kg != null };
+}
+
+// Open the global Display-currency setting — Settings modal → Preferences tab
+// (where the selector actually lives) — and scroll it into view with a brief
+// highlight. The old link went to navigate('data') (Import / Export), which has
+// NO currency selector, so the link went nowhere useful.
+function goToDisplayCurrencySetting() {
+  if (typeof openSettingsModal === 'function') openSettingsModal('prefs');
+  else if (typeof navigate === 'function') navigate('data');   // fallback if the modal helper is unavailable
+  const focus = () => {
+    const el = document.getElementById('display-currency-card');
+    if (!el) return;
+    el.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    el.style.transition = 'box-shadow .35s ease';
+    el.style.boxShadow = '0 0 0 3px rgba(37,99,235,0.35)';
+    setTimeout(() => { el.style.boxShadow = ''; }, 1400);
+  };
+  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(focus);
+  else setTimeout(focus, 50);
+}
+
+// Effective cost for a batch/sample: the manual override when set, else the
+// live computed cost — plus the drift between them. Mirrors entityCostValueHtml's
+// override resolution (same currency conversion) so the list Cost column and the
+// detail Cost field always agree. Returns:
+//   { total, computed, currency, overridden, note, driftPct }
+// total is null only when there's neither an override nor a computable cost.
+function entityEffectiveCost(qty, unit, formula, override, overrideCcy, note) {
+  const { computed, ccy } = quantityCost(qty, unit, formula);
+  const ovRaw = (override != null && override !== '' && isFinite(parseFloat(override))) ? parseFloat(override) : null;
+  const ovCcy = overrideCcy || ccy;
+  let ov = ovRaw;
+  if (ovRaw != null && ovCcy !== ccy && typeof convertCurrencySync === 'function') {
+    const conv = convertCurrencySync(ovRaw, ovCcy, ccy);
+    if (isFinite(conv)) ov = conv;
+  }
+  const overridden = ov != null;
+  return {
+    total: overridden ? ov : computed,
+    computed,
+    currency: ccy,
+    overridden,
+    note: (note != null && String(note).trim() !== '') ? String(note).trim() : '',
+    driftPct: (overridden && computed != null && computed > 0) ? (ov - computed) / computed * 100 : null,
+  };
+}
+
+// Amber-flag threshold: a manual override this far (%) from the live computed
+// cost is surfaced as "stale" in the compact list cell.
+const COST_DRIFT_PCT = 10;
+
+// Compact Cost-cell HTML for LIST views (batch/sample tables + cards). Plain
+// formatted total for a computed cost; a superscript "ᴹ" marker when it's a
+// manual override — amber when the override has drifted >= COST_DRIFT_PCT from
+// computed — with the computed value + drift + note in the tooltip. "—" when
+// unpriceable. `label` names the value in the non-override tooltip.
+function entityCostCellHtml(summary, label) {
+  const lbl = label || 'Cost';
+  if (!summary || summary.total == null) {
+    return `<span title="${esc(lbl)}, not priced (no ingredient prices, or a volume amount with no density)" style="color:#94a3b8">—</span>`;
+  }
+  const money = v => (typeof formatMoney === 'function') ? formatMoney(v, summary.currency) : (summary.currency + ' ' + (+v).toFixed(2));
+  const amt = money(summary.total);
+  if (!summary.overridden) return `<span title="${esc(lbl)} (live ingredient prices)">${amt}</span>`;
+  const drift = summary.driftPct;
+  const drifted = drift != null && Math.abs(drift) >= COST_DRIFT_PCT;
+  const compStr = summary.computed != null ? money(summary.computed) : null;
+  const dStr = (drift != null) ? ` (${drift > 0 ? '+' : ''}${drift.toFixed(0)}%)` : '';
+  const tip = 'Manual override'
+    + (compStr ? ` · computed ${compStr}${dStr}` : '')
+    + (drifted ? ' · drifted from live cost' : '')
+    + (summary.note ? ` · “${summary.note}”` : '');
+  const mark = drifted
+    ? ` <span style="color:#b45309;font-size:11px" aria-hidden="true">⚠</span>`
+    : `<sup style="color:#2563eb;font-size:9px;font-weight:700;margin-left:1px" aria-hidden="true">M</sup>`;
+  return `<span title="${esc(tip)}">${amt}${mark}</span>`;
+}
+
+// Value-cell HTML for a sample/batch "Cost" detail field. Shows the
+// computed total cost (with breakdown), or — if a manual override is
+// set — the override + a divergence warning vs the live computed value.
+// o = { kind:'sample'|'batch', id, qty, unit, formula, override }.
+function entityCostValueHtml(o) {
+  const { perKg, computed, ccy, convertible } = quantityCost(o.qty, o.unit, o.formula);
+  const money = v => (typeof formatMoney === 'function') ? formatMoney(v, ccy) : (ccy + ' ' + (+v).toFixed(2));
+  const ovRaw = (o.override != null && o.override !== '' && isFinite(parseFloat(o.override))) ? parseFloat(o.override) : null;
+  // The override was entered in o.overrideCcy (legacy values w/o a stamp are
+  // assumed to be in the current display currency). Convert it INTO the
+  // display currency so both the shown value and the divergence vs computed
+  // are apples-to-apples regardless of the active display currency.
+  const ovCcy = o.overrideCcy || ccy;
+  const ov = (ovRaw != null && ovCcy !== ccy && typeof convertCurrencySync === 'function')
+    ? convertCurrencySync(ovRaw, ovCcy, ccy) : ovRaw;
+  const note = (o.note != null && String(o.note).trim() !== '') ? String(o.note).trim() : '';
+  const editBtn = `<a onclick="openCostOverrideModal('${o.kind}','${o.id}')" style="color:var(--primary);cursor:pointer;font-size:11px;margin-left:8px">${ov != null ? 'Edit' : 'Override'}</a>`;
+  let chipTitle = note ? 'Reason: ' + note : 'Manually overridden cost';
+  if (ovRaw != null && ovCcy !== ccy) chipTitle += ` · entered as ${formatMoney(ovRaw, ovCcy)}`;
+  const manualChip = `<span title="${esc(chipTitle)}" style="font-size:10.5px;background:#eff6ff;border:1px solid #bfdbfe;color:#1e40af;padding:1px 6px;border-radius:999px;margin-left:6px">manual</span>`;
+
+  // Currency source hint: viewer's own display preference always wins.
+  // Only fall back to "from formula" if the user has no display preference set.
+  const fromFormula = !!(o.formula && o.formula.costCurrency && !getDisplayCurrency());
+  const ccyLine = `<div style="font-size:10.5px;color:#94a3b8;margin-top:2px">${esc(ccy)} · <a onclick="event.stopPropagation();${fromFormula ? `navigate('formulation-detail','${o.formula.id}')` : `goToDisplayCurrencySetting()`}" title="${fromFormula ? esc('Currency inherited from the formula; click to change it there') : esc('Global display currency; click to change in Settings → Preferences')}" style="color:var(--primary);cursor:pointer">${fromFormula ? 'from formula' : 'display currency'}</a></div>`;
+
+  if (ov != null) {
+    let ref = '';
+    if (computed != null) {
+      if (computed > 0) {
+        const pct = (ov - computed) / computed * 100;
+        if (Math.abs(pct) >= 1) {
+          ref = `<span title="Manual override differs from the live computed cost; recheck if the recipe or ingredient prices changed" style="margin-left:8px;font-size:10.5px;background:#fef3c7;border:1px solid #fcd34d;color:#92400e;padding:1px 6px;border-radius:999px"><span class="fl-warn" aria-hidden="true"></span> computed ${money(computed)} (Δ ${pct > 0 ? '+' : ''}${pct.toFixed(0)}%)</span>`;
+        }
+      }
+      if (!ref) ref = `<span style="font-size:11px;color:var(--text-muted);margin-left:8px">computed ${money(computed)}</span>`;
+    }
+    const noteLine = note ? `<div style="font-size:11px;color:var(--text-muted);font-style:italic;margin-top:3px">“${esc(note)}”</div>` : '';
+    return `<strong>${money(ov)}</strong>${manualChip}${ref}${editBtn}${ccyLine}${noteLine}`;
+  }
+  if (perKg == null) {
+    // No formula is not "no ingredient prices" (35m): say whether it's in Trash.
+    if (!o.formula) {
+      const rec = ((typeof db !== 'undefined' && db && db[o.kind === 'batch' ? 'batches' : 'samples']) || []).find(x => x && x.id === o.id);
+      const fid = rec && rec.formulationId;
+      const why = !fid ? 'no formula' : (typeof flTrashEntryFor === 'function' && flTrashEntryFor('formulation', fid)) ? 'formula is in Trash' : 'formula deleted';
+      return `<span style="color:var(--text-muted)">—</span> <span style="font-size:11px;color:var(--text-muted)">${why}</span>${editBtn}`;
+    }
+    return `<span style="color:var(--text-muted)">—</span> <span style="font-size:11px;color:var(--text-muted)">no ingredient prices</span>${editBtn}`;
+  }
+  if (!convertible) {
+    // Light, actionable warning: mass↔volume just needs a density (fixable);
+    // count/"each" units genuinely can't be priced by mass.
+    const why = (typeof unitConvertibility === 'function') ? unitConvertibility(o.unit, 'kg', o.formula) : 'incompatible';
+    const msg = (why === 'needs-density')
+      ? `⚠ add a density to the formula to price ${esc(o.unit || 'this unit')} by mass`
+      : `can't convert ${esc(o.unit || 'this unit')} to mass`;
+    const col = (why === 'needs-density') ? '#b45309' : 'var(--text-muted)';
+    return `<span style="color:var(--text-muted)">—</span> <span style="font-size:11px;color:${col}">${msg}</span>${editBtn}`;
+  }
+  const breakdown = `<span style="font-size:11px;color:var(--text-muted);margin-left:6px">${esc(String(o.qty))} ${esc(o.unit || '')} × ${money(perKg)}/kg</span>`;
+  return `<strong>${money(computed)}</strong>${breakdown}${editBtn}${ccyLine}`;
+}
+
+function openCostOverrideModal(kind, id) {
+  const ent = (kind === 'sample' ? db.samples : db.batches).find(x => x.id === id);
+  if (!ent) return;
+  const qty = (kind === 'sample') ? ent.quantity : ent.targetQuantity;
+  const formula = db.formulations.find(f => f.id === ent.formulationId);
+  const { computed, ccy } = quantityCost(qty, ent.unit, formula);
+  // Prefill the input in the CURRENT display currency, converting a value
+  // that was stored in a different currency, so editing is always in `ccy`.
+  let cur = '';
+  if (ent.costOverride != null && ent.costOverride !== '' && isFinite(parseFloat(ent.costOverride))) {
+    const stored = parseFloat(ent.costOverride);
+    const sCcy = ent.costOverrideCcy || ccy;
+    cur = (sCcy !== ccy && typeof convertCurrencySync === 'function')
+      ? +convertCurrencySync(stored, sCcy, ccy).toPrecision(6) : stored;
+  }
+  const curNote = (ent.costOverrideNote != null) ? ent.costOverrideNote : '';
+  const compStr = (computed != null) ? formatMoney(computed, ccy) : '—';
+  const body = `
+    <p style="font-size:13px;color:var(--text-muted);margin-bottom:12px;line-height:1.5">
+      Computed cost is <strong>${compStr}</strong>. Enter a manual override to record the actual cost — it'll be flagged on the detail page whenever it diverges from the live computed value.
+    </p>
+    <label style="font-size:12px;font-weight:600;display:block;margin-bottom:4px">Override (${esc(ccy)})</label>
+    <input id="cost-ov-input" type="number" step="any" value="${esc(String(cur))}" placeholder="${computed != null ? (+computed).toPrecision(4) : ''}" style="width:100%;padding:7px 9px;border:1px solid var(--border);border-radius:6px;font-size:14px" autofocus />
+    <label style="font-size:12px;font-weight:600;display:block;margin:12px 0 4px">Reason <span style="font-weight:400;color:var(--text-muted)">(optional)</span></label>
+    <input id="cost-ov-note" type="text" value="${esc(String(curNote))}" placeholder="e.g. actual lot price incl. freight &amp; MOQ" style="width:100%;padding:7px 9px;border:1px solid var(--border);border-radius:6px;font-size:13px" />
+    <p style="font-size:11.5px;color:var(--text-muted);margin-top:8px">Leave the override blank and save to clear it (and its reason) and fall back to the computed cost.</p>`;
+  showModal(`${kind === 'sample' ? 'Sample' : 'Batch'} cost override`, body, () => _saveCostOverride(kind, id));
+}
+
+function _saveCostOverride(kind, id) {
+  const ent = (kind === 'sample' ? db.samples : db.batches).find(x => x.id === id);
+  if (!ent) return;
+  const el = document.getElementById('cost-ov-input');
+  const noteEl = document.getElementById('cost-ov-note');
+  const raw = el ? String(el.value).trim() : '';
+  const note = noteEl ? String(noteEl.value).trim() : '';
+  // The modal entered the value in the current display currency — stamp it so
+  // the override survives a later display-currency change.
+  const qty = (kind === 'sample') ? ent.quantity : ent.targetQuantity;
+  const formula = db.formulations.find(f => f.id === ent.formulationId);
+  const ccy = quantityCost(qty, ent.unit, formula).ccy;
+  if (raw === '' || !isFinite(parseFloat(raw))) {
+    delete ent.costOverride;
+    delete ent.costOverrideNote;   // clearing the override clears its reason
+    delete ent.costOverrideCcy;
+  } else {
+    ent.costOverride = parseFloat(raw);
+    ent.costOverrideCcy = ccy;
+    if (note) ent.costOverrideNote = note; else delete ent.costOverrideNote;
+  }
+  ent.updatedAt = (typeof now === 'function') ? now() : new Date().toISOString();
+  saveDB();
+  if (typeof _proHook === 'function') _proHook(kind, 'update', ent);   // kind = 'sample' | 'batch'
+  if (kind === 'sample' && typeof renderSampleDetail === 'function') renderSampleDetail(id);
+  else if (kind === 'batch' && typeof renderBatchDetail === 'function') renderBatchDetail(id);
+}