@tmlmt/cooklang-parser 2.1.8 → 3.0.0-alpha.11

package/dist/index.cjs

@@ -33,9 +33,27 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 var index_exports = {};
 __export(index_exports, {
   CategoryConfig: () => CategoryConfig,
+  NoProductCatalogForCartError: () => NoProductCatalogForCartError,
+  NoShoppingListForCartError: () => NoShoppingListForCartError,
+  ProductCatalog: () => ProductCatalog,
   Recipe: () => Recipe,
   Section: () => Section,
-  ShoppingList: () => ShoppingList
+  ShoppingCart: () => ShoppingCart,
+  ShoppingList: () => ShoppingList,
+  convertQuantityToSystem: () => convertQuantityToSystem,
+  formatExtendedQuantity: () => formatExtendedQuantity,
+  formatItemQuantity: () => formatItemQuantity,
+  formatNumericValue: () => formatNumericValue,
+  formatQuantity: () => formatQuantity,
+  formatQuantityWithUnit: () => formatQuantityWithUnit,
+  formatSingleValue: () => formatSingleValue,
+  formatUnit: () => formatUnit,
+  hasAlternatives: () => hasAlternatives,
+  isAlternativeSelected: () => isAlternativeSelected,
+  isAndGroup: () => isAndGroup,
+  isGroupedItem: () => isGroupedItem,
+  isSimpleGroup: () => isSimpleGroup,
+  renderFractionAsVulgar: () => renderFractionAsVulgar
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -100,33 +118,10 @@ var CategoryConfig = class {
   }
 };
 
-// src/classes/section.ts
-var Section = class {
-  /**
-   * Creates an instance of Section.
-   * @param name - The name of the section. Defaults to an empty string.
-   */
-  constructor(name = "") {
-    /**
-     * The name of the section. Can be an empty string for the default (first) section.
-     * @defaultValue `""`
-     */
-    __publicField(this, "name");
-    /** An array of steps and notes that make up the content of the section. */
-    __publicField(this, "content", []);
-    this.name = name;
-  }
-  /**
-   * Checks if the section is blank (has no name and no content).
-   * Used during recipe parsing
-   * @returns `true` if the section is blank, otherwise `false`.
-   */
-  isBlank() {
-    return this.name === "" && this.content.length === 0;
-  }
-};
+// src/classes/product_catalog.ts
+var import_smol_toml = __toESM(require("smol-toml"), 1);
 
-// node_modules/.pnpm/human-regex@2.1.5_patch_hash=6d6bd9e233f99785a7c2187fd464edc114b76d47001dbb4eb6b5d72168de7460/node_modules/human-regex/dist/human-regex.esm.js
+// node_modules/.pnpm/human-regex@2.2.0/node_modules/human-regex/dist/human-regex.esm.js
 var t = /* @__PURE__ */ new Map();
 var r = { GLOBAL: "g", NON_SENSITIVE: "i", MULTILINE: "m", DOT_ALL: "s", UNICODE: "u", STICKY: "y" };
 var e = Object.freeze({ digit: "0-9", lowercaseLetter: "a-z", uppercaseLetter: "A-Z", letter: "a-zA-Z", alphanumeric: "a-zA-Z0-9", anyCharacter: "." });
@@ -187,7 +182,7 @@ var a = class {
     return this.add(".");
   }
   newline() {
-    return this.add("(?:\\r\\n|\\r|\\n)");
+    return this.add("(\\r\\n|\\r|\\n)");
   }
   negativeLookahead(t2) {
     return this.add(`(?!${t2})`);
@@ -328,19 +323,22 @@ var i = (() => {
 var metadataRegex = d().literal("---").newline().startCaptureGroup().anyCharacter().zeroOrMore().optional().endGroup().newline().literal("---").dotAll().toRegExp();
 var scalingMetaValueRegex = (varName) => d().startAnchor().literal(varName).literal(":").anyOf("\\t ").zeroOrMore().startCaptureGroup().startCaptureGroup().notAnyOf(",\\n").oneOrMore().endGroup().startGroup().literal(",").whitespace().zeroOrMore().startCaptureGroup().anyCharacter().oneOrMore().endGroup().endGroup().optional().endGroup().endAnchor().multiline().toRegExp();
 var nonWordChar = "\\s@#~\\[\\]{(,;:!?";
-var multiwordIngredient = d().literal("@").startNamedGroup("mIngredientModifiers").anyOf("@\\-&?").zeroOrMore().endGroup().optional().startNamedGroup("mIngredientRecipeAnchor").literal("./").endGroup().optional().startNamedGroup("mIngredientName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().notAnyOf("\\." + nonWordChar).endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\}|\\([^)]*\\))").startGroup().literal("{").startNamedGroup("mIngredientQuantityModifier").literal("=").exactly(1).endGroup().optional().startNamedGroup("mIngredientQuantity").notAnyOf("}%").oneOrMore().endGroup().optional().startGroup().literal("%").startNamedGroup("mIngredientUnit").notAnyOf("}").oneOrMore().lazy().endGroup().endGroup().optional().literal("}").endGroup().optional().startGroup().literal("(").startNamedGroup("mIngredientPreparation").notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().toRegExp();
-var singleWordIngredient = d().literal("@").startNamedGroup("sIngredientModifiers").anyOf("@\\-&?").zeroOrMore().endGroup().optional().startNamedGroup("sIngredientRecipeAnchor").literal("./").endGroup().optional().startNamedGroup("sIngredientName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().startGroup().literal("{").startNamedGroup("sIngredientQuantityModifier").literal("=").exactly(1).endGroup().optional().startNamedGroup("sIngredientQuantity").notAnyOf("}%").oneOrMore().endGroup().optional().startGroup().literal("%").startNamedGroup("sIngredientUnit").notAnyOf("}").oneOrMore().lazy().endGroup().endGroup().optional().literal("}").endGroup().optional().startGroup().literal("(").startNamedGroup("sIngredientPreparation").notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().toRegExp();
+var nonWordCharStrict = "\\s@#~\\[\\]{(,;:!?|";
+var ingredientWithAlternativeRegex = d().literal("@").startNamedGroup("ingredientModifiers").anyOf("@\\-&?").zeroOrMore().endGroup().optional().startNamedGroup("ingredientRecipeAnchor").literal("./").endGroup().optional().startGroup().startGroup().startNamedGroup("mIngredientName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\}|\\([^)]*\\))").endGroup().or().startNamedGroup("sIngredientName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().endGroup().startGroup().literal("{").startNamedGroup("ingredientQuantityModifier").literal("=").exactly(1).endGroup().optional().startNamedGroup("ingredientQuantity").startGroup().notAnyOf("}|%").oneOrMore().endGroup().optional().startGroup().literal("%").notAnyOf("|}").oneOrMore().lazy().endGroup().optional().startGroup().literal("|").notAnyOf("}").oneOrMore().lazy().endGroup().zeroOrMore().endGroup().literal("}").endGroup().optional().startGroup().literal("(").startNamedGroup("ingredientPreparation").notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().startGroup().literal("[").startNamedGroup("ingredientNote").notAnyOf("\\]").oneOrMore().lazy().endGroup().literal("]").endGroup().optional().startNamedGroup("ingredientAlternative").startGroup().literal("|").startGroup().anyOf("@\\-&?").zeroOrMore().endGroup().optional().startGroup().literal("./").endGroup().optional().startGroup().startGroup().startGroup().notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\}|\\([^)]*\\))").endGroup().or().startGroup().notAnyOf(nonWordChar).oneOrMore().endGroup().endGroup().startGroup().literal("{").startGroup().literal("=").exactly(1).endGroup().optional().startGroup().notAnyOf("}%").oneOrMore().endGroup().optional().startGroup().literal("%").startGroup().notAnyOf("}").oneOrMore().lazy().endGroup().endGroup().optional().literal("}").endGroup().optional().startGroup().literal("(").startGroup().notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().startGroup().literal("[").startGroup().notAnyOf("\\]").oneOrMore().lazy().endGroup().literal("]").endGroup().optional().endGroup().zeroOrMore().endGroup().toRegExp();
+var inlineIngredientAlternativesRegex = new RegExp("\\|" + ingredientWithAlternativeRegex.source.slice(1));
+var quantityAlternativeRegex = d().startNamedGroup("quantity").notAnyOf("}|%").oneOrMore().endGroup().optional().startGroup().literal("%").startNamedGroup("unit").notAnyOf("|}").oneOrMore().endGroup().endGroup().optional().startGroup().literal("|").startNamedGroup("alternative").startGroup().notAnyOf("}").oneOrMore().endGroup().zeroOrMore().endGroup().endGroup().optional().toRegExp();
+var ingredientWithGroupKeyRegex = d().literal("@|").startNamedGroup("gIngredientGroupKey").notAnyOf(nonWordCharStrict).oneOrMore().endGroup().literal("|").startNamedGroup("gIngredientModifiers").anyOf("@\\-&?").zeroOrMore().endGroup().optional().startNamedGroup("gIngredientRecipeAnchor").literal("./").endGroup().optional().startGroup().startGroup().startNamedGroup("gmIngredientName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\}|\\([^)]*\\))").endGroup().or().startNamedGroup("gsIngredientName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().endGroup().startGroup().literal("{").startNamedGroup("gIngredientQuantityModifier").literal("=").exactly(1).endGroup().optional().startNamedGroup("gIngredientQuantity").startGroup().notAnyOf("}|%").oneOrMore().endGroup().optional().startGroup().literal("%").notAnyOf("|}").oneOrMore().lazy().endGroup().optional().startGroup().literal("|").notAnyOf("}").oneOrMore().lazy().endGroup().zeroOrMore().endGroup().literal("}").endGroup().optional().startGroup().literal("(").startNamedGroup("gIngredientPreparation").notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().toRegExp();
 var ingredientAliasRegex = d().startAnchor().startNamedGroup("ingredientListName").notAnyOf("|").oneOrMore().endGroup().literal("|").startNamedGroup("ingredientDisplayName").notAnyOf("|").oneOrMore().endGroup().endAnchor().toRegExp();
-var multiwordCookware = d().literal("#").startNamedGroup("mCookwareModifiers").anyOf("\\-&?").zeroOrMore().endGroup().startNamedGroup("mCookwareName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().notAnyOf("\\." + nonWordChar).endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\})").literal("{").startNamedGroup("mCookwareQuantity").anyCharacter().zeroOrMore().lazy().endGroup().literal("}").toRegExp();
-var singleWordCookware = d().literal("#").startNamedGroup("sCookwareModifiers").anyOf("\\-&?").zeroOrMore().endGroup().startNamedGroup("sCookwareName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().startGroup().literal("{").startNamedGroup("sCookwareQuantity").anyCharacter().zeroOrMore().lazy().endGroup().literal("}").endGroup().optional().toRegExp();
-var timer = d().literal("~").startNamedGroup("timerName").anyCharacter().zeroOrMore().lazy().endGroup().literal("{").startNamedGroup("timerQuantity").anyCharacter().oneOrMore().lazy().endGroup().startGroup().literal("%").startNamedGroup("timerUnit").anyCharacter().oneOrMore().lazy().endGroup().endGroup().optional().literal("}").toRegExp();
+var cookwareRegex = d().literal("#").startNamedGroup("cookwareModifiers").anyOf("\\-&?").zeroOrMore().endGroup().startGroup().startGroup().startNamedGroup("mCookwareName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\})").endGroup().or().startNamedGroup("sCookwareName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().endGroup().startGroup().literal("{").startNamedGroup("cookwareQuantity").anyCharacter().zeroOrMore().lazy().endGroup().literal("}").endGroup().optional().toRegExp();
+var timerRegex = d().literal("~").startNamedGroup("timerName").anyCharacter().zeroOrMore().lazy().endGroup().literal("{").startNamedGroup("timerQuantity").anyCharacter().oneOrMore().lazy().endGroup().startGroup().literal("%").startNamedGroup("timerUnit").anyCharacter().oneOrMore().lazy().endGroup().endGroup().optional().literal("}").toRegExp();
+var arbitraryScalableRegex = d().literal("{{").startGroup().startNamedGroup("arbitraryName").notAnyOf("}:%").oneOrMore().endGroup().literal(":").endGroup().optional().startNamedGroup("arbitraryQuantity").startGroup().notAnyOf("}|%").oneOrMore().endGroup().optional().startGroup().literal("%").notAnyOf("|}").oneOrMore().lazy().endGroup().optional().startGroup().literal("|").notAnyOf("}").oneOrMore().lazy().endGroup().zeroOrMore().endGroup().literal("}}").toRegExp();
 var tokensRegex = new RegExp(
   [
-    multiwordIngredient,
-    singleWordIngredient,
-    multiwordCookware,
-    singleWordCookware,
-    timer
+    ingredientWithGroupKeyRegex,
+    ingredientWithAlternativeRegex,
+    cookwareRegex,
+    timerRegex,
+    arbitraryScalableRegex
   ].map((r2) => r2.source).join("|"),
   "gu"
 );
@@ -351,8 +349,7 @@ var rangeRegex = d().startAnchor().digit().oneOrMore().startGroup().anyOf(".,/")
 var numberLikeRegex = d().startAnchor().digit().oneOrMore().startGroup().anyOf(".,/").exactly(1).digit().oneOrMore().endGroup().optional().endAnchor().toRegExp();
 var floatRegex = d().startAnchor().digit().oneOrMore().startGroup().anyOf(".").exactly(1).digit().oneOrMore().endGroup().optional().endAnchor().toRegExp();
 
-// src/units.ts
-var import_big = __toESM(require("big.js"), 1);
+// src/units/definitions.ts
 var units = [
   // Mass (Metric)
   {
@@ -360,7 +357,8 @@ var units = [
     type: "mass",
     system: "metric",
     aliases: ["gram", "grams", "grammes"],
-    toBase: 1
+    toBase: 1,
+    maxValue: 999
   },
   {
     name: "kg",
@@ -369,20 +367,28 @@ var units = [
     aliases: ["kilogram", "kilograms", "kilogrammes", "kilos", "kilo"],
     toBase: 1e3
   },
-  // Mass (Imperial)
+  // Mass (US/UK - identical in both systems)
   {
     name: "oz",
     type: "mass",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["ounce", "ounces"],
-    toBase: 28.3495
+    toBase: 28.3495,
+    // default: US (same as UK)
+    toBaseBySystem: { US: 28.3495, UK: 28.3495 },
+    maxValue: 31,
+    // 16 oz = 1 lb, allow a bit more
+    fractions: { enabled: true, denominators: [2] }
   },
   {
     name: "lb",
     type: "mass",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["pound", "pounds"],
-    toBase: 453.592
+    toBase: 453.592,
+    // default: US (same as UK)
+    toBaseBySystem: { US: 453.592, UK: 453.592 },
+    fractions: { enabled: true, denominators: [2, 4] }
   },
   // Volume (Metric)
   {
@@ -390,21 +396,26 @@ var units = [
     type: "volume",
     system: "metric",
     aliases: ["milliliter", "milliliters", "millilitre", "millilitres", "cc"],
-    toBase: 1
+    toBase: 1,
+    maxValue: 999
   },
   {
     name: "cl",
     type: "volume",
     system: "metric",
     aliases: ["centiliter", "centiliters", "centilitre", "centilitres"],
-    toBase: 10
+    toBase: 10,
+    isBestUnit: false
+    // exists but not a "best" candidate
   },
   {
     name: "dl",
     type: "volume",
     system: "metric",
     aliases: ["deciliter", "deciliters", "decilitre", "decilitres"],
-    toBase: 100
+    toBase: 100,
+    isBestUnit: false
+    // exists but not a "best" candidate
   },
   {
     name: "l",
@@ -413,55 +424,102 @@ var units = [
     aliases: ["liter", "liters", "litre", "litres"],
     toBase: 1e3
   },
+  // Volume (JP)
+  {
+    name: "go",
+    type: "volume",
+    system: "JP",
+    aliases: ["gou", "goo", "\u5408", "rice cup"],
+    toBase: 180,
+    maxValue: 10
+  },
+  // Volume (Ambiguous: metric/US/UK)
   {
     name: "tsp",
     type: "volume",
-    system: "metric",
+    system: "ambiguous",
     aliases: ["teaspoon", "teaspoons"],
-    toBase: 5
+    toBase: 5,
+    // default: metric
+    toBaseBySystem: { metric: 5, US: 4.929, UK: 5.919, JP: 5 },
+    maxValue: 5,
+    // 3 tsp = 1 tbsp (but allow a bit more)
+    fractions: { enabled: true, denominators: [2, 3, 4, 8] }
   },
   {
     name: "tbsp",
     type: "volume",
-    system: "metric",
+    system: "ambiguous",
     aliases: ["tablespoon", "tablespoons"],
-    toBase: 15
+    toBase: 15,
+    // default: metric
+    toBaseBySystem: { metric: 15, US: 14.787, UK: 17.758, JP: 15 },
+    maxValue: 4,
+    // ~16 tbsp = 1 cup
+    fractions: { enabled: true }
   },
-  // Volume (Imperial)
+  // Volume (Ambiguous: US/UK only)
   {
     name: "fl-oz",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["fluid ounce", "fluid ounces"],
-    toBase: 29.5735
+    toBase: 29.5735,
+    // default: US
+    toBaseBySystem: { US: 29.5735, UK: 28.4131 },
+    maxValue: 15,
+    // 8 fl-oz ~ 1 cup, allow more
+    fractions: { enabled: true, denominators: [2] }
   },
   {
     name: "cup",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["cups"],
-    toBase: 236.588
+    toBase: 236.588,
+    // default: US
+    toBaseBySystem: { US: 236.588, UK: 284.131 },
+    maxValue: 15,
+    // upgrade to gallons above 15 cups
+    fractions: { enabled: true }
   },
   {
     name: "pint",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["pints"],
-    toBase: 473.176
+    toBase: 473.176,
+    // default: US
+    toBaseBySystem: { US: 473.176, UK: 568.261 },
+    maxValue: 3,
+    // 2 pints = 1 quart
+    fractions: { enabled: true, denominators: [2] },
+    isBestUnit: false
+    // exists but not a "best" candidate
   },
   {
     name: "quart",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["quarts"],
-    toBase: 946.353
+    toBase: 946.353,
+    // default: US
+    toBaseBySystem: { US: 946.353, UK: 1136.52 },
+    maxValue: 3,
+    // 4 quarts = 1 gallon
+    fractions: { enabled: true, denominators: [2] },
+    isBestUnit: false
+    // exists but not a "best" candidate
   },
   {
     name: "gallon",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["gallons"],
-    toBase: 3785.41
+    toBase: 3785.41,
+    // default: US
+    toBaseBySystem: { US: 3785.41, UK: 4546.09 },
+    fractions: { enabled: true, denominators: [2] }
   },
   // Count units (no conversion, but recognized as a type)
   {
@@ -469,7 +527,8 @@ var units = [
     type: "count",
     system: "metric",
     aliases: ["pieces", "pc"],
-    toBase: 1
+    toBase: 1,
+    maxValue: 999
   }
 ];
 var unitMap = /* @__PURE__ */ new Map();
@@ -482,20 +541,25 @@ for (const unit of units) {
 function normalizeUnit(unit = "") {
   return unitMap.get(unit.toLowerCase().trim());
 }
-var CannotAddTextValueError = class extends Error {
-  constructor() {
-    super("Cannot add a quantity with a text value.");
-    this.name = "CannotAddTextValueError";
-  }
-};
-var IncompatibleUnitsError = class extends Error {
-  constructor(unit1, unit2) {
-    super(
-      `Cannot add quantities with incompatible or unknown units: ${unit1} and ${unit2}`
-    );
-    this.name = "IncompatibleUnitsError";
-  }
-};
+var NO_UNIT = "__no-unit__";
+function resolveUnit(name = NO_UNIT, integerProtected = false) {
+  const normalizedUnit = normalizeUnit(name);
+  const resolvedUnit = normalizedUnit ? { ...normalizedUnit, name } : { name, type: "other", system: "none" };
+  return integerProtected ? { ...resolvedUnit, integerProtected: true } : resolvedUnit;
+}
+function isNoUnit(unit) {
+  if (!unit) return true;
+  return resolveUnit(unit.name).name === NO_UNIT;
+}
+
+// src/units/conversion.ts
+var import_big2 = __toESM(require("big.js"), 1);
+
+// src/quantities/numeric.ts
+var import_big = __toESM(require("big.js"), 1);
+var DEFAULT_DENOMINATORS = [2, 3, 4];
+var DEFAULT_FRACTION_ACCURACY = 0.05;
+var DEFAULT_MAX_WHOLE = 4;
 function gcd(a2, b) {
   return b === 0 ? a2 : gcd(b, a2 % b);
 }
@@ -511,14 +575,58 @@ function simplifyFraction(num, den) {
     simplifiedDen = -simplifiedDen;
   }
   if (simplifiedDen === 1) {
-    return { type: "decimal", value: simplifiedNum };
+    return { type: "decimal", decimal: simplifiedNum };
   } else {
     return { type: "fraction", num: simplifiedNum, den: simplifiedDen };
   }
 }
+function approximateFraction(value, denominators = DEFAULT_DENOMINATORS, accuracy = DEFAULT_FRACTION_ACCURACY, maxWhole = DEFAULT_MAX_WHOLE) {
+  if (value <= 0 || !Number.isFinite(value)) {
+    return null;
+  }
+  const wholePart = Math.floor(value);
+  if (wholePart > maxWhole) {
+    return null;
+  }
+  const fractionalPart = value - wholePart;
+  if (fractionalPart < 1e-4) {
+    return null;
+  }
+  let bestFraction = null;
+  for (const den of denominators) {
+    const exactNum = value * den;
+    const roundedNum = Math.round(exactNum);
+    if (roundedNum === 0) continue;
+    const approximatedValue = roundedNum / den;
+    const relativeError = Math.abs(approximatedValue - value) / value;
+    if (relativeError <= accuracy) {
+      if (!bestFraction || relativeError < bestFraction.error) {
+        bestFraction = { num: roundedNum, den, error: relativeError };
+      }
+    }
+  }
+  if (!bestFraction) {
+    return null;
+  }
+  const commonDivisor = gcd(bestFraction.num, bestFraction.den);
+  return {
+    type: "fraction",
+    num: bestFraction.num / commonDivisor,
+    den: bestFraction.den / commonDivisor
+  };
+}
+function getNumericValue(v) {
+  if (v.type === "decimal") {
+    return v.decimal;
+  }
+  return v.num / v.den;
+}
 function multiplyNumericValue(v, factor) {
   if (v.type === "decimal") {
-    return { type: "decimal", value: (0, import_big.default)(v.value).times(factor).toNumber() };
+    return {
+      type: "decimal",
+      decimal: (0, import_big.default)(v.decimal).times(factor).toNumber()
+    };
   }
   return simplifyFraction((0, import_big.default)(v.num).times(factor).toNumber(), v.den);
 }
@@ -528,36 +636,62 @@ function addNumericValues(val1, val2) {
   let num2;
   let den2;
   if (val1.type === "decimal") {
-    num1 = val1.value;
+    num1 = val1.decimal;
     den1 = 1;
   } else {
     num1 = val1.num;
     den1 = val1.den;
   }
   if (val2.type === "decimal") {
-    num2 = val2.value;
+    num2 = val2.decimal;
     den2 = 1;
   } else {
     num2 = val2.num;
     den2 = val2.den;
   }
   if (num1 === 0 && num2 === 0) {
-    return { type: "decimal", value: 0 };
+    return { type: "decimal", decimal: 0 };
   }
-  if (val1.type === "fraction" && val2.type === "fraction" || val1.type === "fraction" && val2.type === "decimal" && val2.value === 0 || val2.type === "fraction" && val1.type === "decimal" && val1.value === 0) {
+  if (val1.type === "fraction" && val2.type === "fraction" || val1.type === "fraction" && val2.type === "decimal" && val2.decimal === 0 || val2.type === "fraction" && val1.type === "decimal" && val1.decimal === 0) {
     const commonDen = den1 * den2;
     const sumNum = num1 * den2 + num2 * den1;
     return simplifyFraction(sumNum, commonDen);
   } else {
     return {
       type: "decimal",
-      value: (0, import_big.default)(num1).div(den1).add((0, import_big.default)(num2).div(den2)).toNumber()
+      decimal: (0, import_big.default)(num1).div(den1).add((0, import_big.default)(num2).div(den2)).toNumber()
     };
   }
 }
-var toRoundedDecimal = (v) => {
-  const value = v.type === "decimal" ? v.value : v.num / v.den;
-  return { type: "decimal", value: Math.floor(value * 100) / 100 };
+var toRoundedDecimal = (v, precision = 3) => {
+  const value = v.type === "decimal" ? v.decimal : v.num / v.den;
+  if (value === 0) {
+    return { type: "decimal", decimal: 0 };
+  }
+  const absValue = Math.abs(value);
+  if (absValue >= 1e3) {
+    return { type: "decimal", decimal: Math.round(value) };
+  }
+  const magnitude = Math.floor(Math.log10(absValue));
+  const scale = Math.pow(10, precision - 1 - magnitude);
+  const rounded = Math.round(value * scale) / scale;
+  return { type: "decimal", decimal: rounded };
+};
+var formatOutputValue = (value, unitDef, precision = 3) => {
+  if (unitDef.fractions?.enabled) {
+    const denominators = unitDef.fractions.denominators ?? DEFAULT_DENOMINATORS;
+    const maxWhole = unitDef.fractions.maxWhole ?? DEFAULT_MAX_WHOLE;
+    const fraction = approximateFraction(
+      value,
+      denominators,
+      DEFAULT_FRACTION_ACCURACY,
+      maxWhole
+    );
+    if (fraction) {
+      return fraction;
+    }
+  }
+  return toRoundedDecimal({ type: "decimal", decimal: value }, precision);
 };
 function multiplyQuantityValue(value, factor) {
   if (value.type === "fixed") {
@@ -565,8 +699,8 @@ function multiplyQuantityValue(value, factor) {
       value.value,
       (0, import_big.default)(factor)
     );
-    if (factor === parseInt(factor.toString()) || // e.g. 2 === int
-    (0, import_big.default)(1).div(factor).toNumber() === parseInt((0, import_big.default)(1).div(factor).toString())) {
+    if (newValue.type === "fraction" && ((0, import_big.default)(factor).toNumber() === parseInt((0, import_big.default)(factor).toString()) || // e.g. 2 === int
+    (0, import_big.default)(1).div(factor).toNumber() === parseInt((0, import_big.default)(1).div(factor).toString()))) {
       return {
         type: "fixed",
         value: newValue
@@ -583,13 +717,291 @@ function multiplyQuantityValue(value, factor) {
     max: multiplyNumericValue(value.max, factor)
   };
 }
-var convertQuantityValue = (value, def, targetDef) => {
-  if (def.name === targetDef.name) return value;
-  const factor = def.toBase / targetDef.toBase;
-  return multiplyQuantityValue(value, factor);
+function getAverageValue(q) {
+  if (q.type === "fixed") {
+    return q.value.type === "text" ? q.value.text : getNumericValue(q.value);
+  } else {
+    return (getNumericValue(q.min) + getNumericValue(q.max)) / 2;
+  }
+}
+
+// src/units/compatibility.ts
+function areUnitsGroupable(u1, u2) {
+  if (u1.name === u2.name) {
+    return true;
+  }
+  if (u1.type === "other" || u2.type === "other") {
+    return false;
+  }
+  if (u1.type === u2.type && u1.system === u2.system) {
+    return true;
+  }
+  if (u1.type === u2.type) {
+    if (u1.system === "ambiguous" && u2.system === "metric" && u1.toBaseBySystem?.metric !== void 0) {
+      return true;
+    }
+    if (u2.system === "ambiguous" && u1.system === "metric" && u2.toBaseBySystem?.metric !== void 0) {
+      return true;
+    }
+  }
+  return false;
+}
+function areUnitsConvertible(u1, u2) {
+  if (u1.name === u2.name) return true;
+  if (u1.type === "other" || u2.type === "other") return false;
+  return u1.type === u2.type;
+}
+function isUnitCompatibleWithSystem(unit, system) {
+  if (unit.system === system) return true;
+  if (unit.system === "ambiguous") {
+    if (unit.toBaseBySystem) {
+      return system in unit.toBaseBySystem;
+    }
+    if (system === "metric") return true;
+  }
+  if (unit.system === "metric" && system === "JP") {
+    return true;
+  }
+  return false;
+}
+
+// src/units/conversion.ts
+var EPSILON = 0.01;
+var DEFAULT_MAX_VALUE = 999;
+function isCloseToInteger(value) {
+  return Math.abs(value - Math.round(value)) < EPSILON;
+}
+function getMaxValue(unit) {
+  return unit.maxValue ?? DEFAULT_MAX_VALUE;
+}
+function isValueInRange(value, unit) {
+  const maxValue = getMaxValue(unit);
+  if (value >= 1 && value <= maxValue) {
+    return true;
+  }
+  if (value > 0 && value < 1 && unit.fractions?.enabled) {
+    const denominators = unit.fractions.denominators ?? DEFAULT_DENOMINATORS;
+    const maxWhole = unit.fractions.maxWhole ?? DEFAULT_MAX_WHOLE;
+    const fraction = approximateFraction(
+      value,
+      denominators,
+      DEFAULT_FRACTION_ACCURACY,
+      maxWhole
+    );
+    return fraction !== null;
+  }
+  return false;
+}
+function findBestUnit(valueInBase, unitType, system, inputUnits) {
+  const inputUnitNames = new Set(inputUnits.map((u) => u.name));
+  const candidates = units.filter(
+    (u) => u.type === unitType && isUnitCompatibleWithSystem(u, system) && (u.isBestUnit !== false || inputUnitNames.has(u.name))
+  );
+  if (candidates.length === 0) {
+    const fallbackUnit = inputUnits[0];
+    return {
+      unit: fallbackUnit,
+      value: valueInBase / getToBase(fallbackUnit, system)
+    };
+  }
+  const candidatesWithValues = candidates.map((unit) => ({
+    unit,
+    value: valueInBase / getToBase(unit, system)
+  }));
+  const inRange = candidatesWithValues.filter(
+    (c) => isValueInRange(c.value, c.unit)
+  );
+  if (inRange.length > 0) {
+    const integersInInputFamily = inRange.filter(
+      (c) => isCloseToInteger(c.value) && inputUnitNames.has(c.unit.name)
+    );
+    if (integersInInputFamily.length > 0) {
+      return integersInInputFamily.sort((a2, b) => a2.value - b.value)[0];
+    }
+    const integersAny = inRange.filter((c) => isCloseToInteger(c.value));
+    if (integersAny.length > 0) {
+      return integersAny.sort((a2, b) => a2.value - b.value)[0];
+    }
+    return inRange.sort((a2, b) => {
+      const aInFamily = inputUnitNames.has(a2.unit.name) ? 0 : 1;
+      const bInFamily = inputUnitNames.has(b.unit.name) ? 0 : 1;
+      if (aInFamily !== bInFamily) return aInFamily - bInFamily;
+      return a2.value - b.value;
+    })[0];
+  }
+  return candidatesWithValues.sort((a2, b) => {
+    const aMaxValue = getMaxValue(a2.unit);
+    const bMaxValue = getMaxValue(b.unit);
+    const aDistance = a2.value < 1 ? 1 - a2.value : a2.value - aMaxValue;
+    const bDistance = b.value < 1 ? 1 - b.value : b.value - bMaxValue;
+    return aDistance - bDistance;
+  })[0];
+}
+function getUnitRatio(q1, q2) {
+  const q1Value = getAverageValue(q1.quantity);
+  const q2Value = getAverageValue(q2.quantity);
+  const factor = "toBase" in q1.unit && "toBase" in q2.unit ? q1.unit.toBase / q2.unit.toBase : 1;
+  if (typeof q1Value !== "number" || typeof q2Value !== "number") {
+    throw Error(
+      "One of both values is not a number, so a ratio cannot be computed"
+    );
+  }
+  return (0, import_big2.default)(q1Value).times(factor).div(q2Value);
+}
+function getBaseUnitRatio(q, qRef) {
+  if ("toBase" in q.unit && "toBase" in qRef.unit) {
+    return q.unit.toBase / qRef.unit.toBase;
+  } else {
+    return 1;
+  }
+}
+function getToBase(unit, system) {
+  if (unit.system === "ambiguous" && system && unit.toBaseBySystem) {
+    return unit.toBaseBySystem[system] ?? unit.toBase;
+  }
+  return unit.toBase;
+}
+
+// src/errors.ts
+var ReferencedItemCannotBeRedefinedError = class extends Error {
+  constructor(item_type, item_name, new_modifier) {
+    super(
+      `The referenced ${item_type} "${item_name}" cannot be redefined as ${new_modifier}.
+You can either remove the reference to create a new ${item_type} defined as ${new_modifier} or add the ${new_modifier} flag to the original definition of the ${item_type}`
+    );
+    this.name = "ReferencedItemCannotBeRedefinedError";
+  }
+};
+var NoProductCatalogForCartError = class extends Error {
+  constructor() {
+    super(
+      `Cannot build a cart without a product catalog. Please set one using setProductCatalog()`
+    );
+    this.name = "NoProductCatalogForCartError";
+  }
+};
+var NoShoppingListForCartError = class extends Error {
+  constructor() {
+    super(
+      `Cannot build a cart without a shopping list. Please set one using setShoppingList()`
+    );
+    this.name = "NoShoppingListForCartError";
+  }
+};
+var NoProductMatchError = class extends Error {
+  constructor(item_name, code) {
+    const messageMap = {
+      incompatibleUnits: `The units of the products in the catalogue are incompatible with ingredient ${item_name} in the shopping list.`,
+      noProduct: "No product was found linked to ingredient name ${item_name} in the shopping list",
+      textValue: `Ingredient ${item_name} has a text value as quantity and can therefore not be matched with any product in the catalogue.`,
+      noQuantity: `Ingredient ${item_name} has no quantity and can therefore not be matched with any product in the catalogue.`,
+      textValue_incompatibleUnits: `Multiple alternative quantities were provided for ingredient ${item_name} in the shopping list but they were either text values or no product in catalog were found to have compatible units`
+    };
+    super(messageMap[code]);
+    __publicField(this, "code");
+    this.code = code;
+    this.name = "NoProductMatchError";
+  }
+};
+var InvalidProductCatalogFormat = class extends Error {
+  constructor() {
+    super("Invalid product catalog format.");
+    this.name = "InvalidProductCatalogFormat";
+  }
+};
+var CannotAddTextValueError = class extends Error {
+  constructor() {
+    super("Cannot add a quantity with a text value.");
+    this.name = "CannotAddTextValueError";
+  }
+};
+var IncompatibleUnitsError = class extends Error {
+  constructor(unit1, unit2) {
+    super(
+      `Cannot add quantities with incompatible or unknown units: ${unit1} and ${unit2}`
+    );
+    this.name = "IncompatibleUnitsError";
+  }
+};
+var InvalidQuantityFormat = class extends Error {
+  constructor(value, extra) {
+    super(
+      `Invalid quantity format found in: ${value}${extra ? ` (${extra})` : ""}`
+    );
+    this.name = "InvalidQuantityFormat";
+  }
 };
+
+// src/utils/type_guards.ts
+function isGroup(x) {
+  return "and" in x || "or" in x;
+}
+function isOrGroup(x) {
+  return isGroup(x) && "or" in x;
+}
+function isAndGroup(x) {
+  return "and" in x;
+}
+function isQuantity(x) {
+  return x && typeof x === "object" && "quantity" in x;
+}
+function isSimpleGroup(entry) {
+  return "quantity" in entry;
+}
+function isNumericValueIntegerLike(v) {
+  if (v.type === "decimal") return Number.isInteger(v.decimal);
+  return v.num % v.den === 0;
+}
+function isValueIntegerLike(q) {
+  if (q.type === "fixed") {
+    if (q.value.type === "text") return false;
+    return isNumericValueIntegerLike(q.value);
+  }
+  return isNumericValueIntegerLike(q.min) && isNumericValueIntegerLike(q.max);
+}
+function hasAlternatives(entry) {
+  return "alternatives" in entry && Array.isArray(entry.alternatives) && entry.alternatives.length > 0;
+}
+
+// src/quantities/mutations.ts
+function extendAllUnits(q) {
+  if (isAndGroup(q)) {
+    return { and: q.and.map(extendAllUnits) };
+  } else if (isOrGroup(q)) {
+    return { or: q.or.map(extendAllUnits) };
+  } else {
+    const newQ = {
+      quantity: q.quantity
+    };
+    if (q.unit) {
+      newQ.unit = { name: q.unit };
+    }
+    return newQ;
+  }
+}
+function normalizeAllUnits(q) {
+  if (isAndGroup(q)) {
+    return { and: q.and.map(normalizeAllUnits) };
+  } else if (isOrGroup(q)) {
+    return { or: q.or.map(normalizeAllUnits) };
+  } else {
+    const newQ = {
+      quantity: q.quantity,
+      unit: resolveUnit(q.unit)
+    };
+    if (q.equivalents && q.equivalents.length > 0) {
+      const equivalentsNormalized = q.equivalents.map(
+        (eq) => normalizeAllUnits(eq)
+      );
+      return {
+        or: [newQ, ...equivalentsNormalized]
+      };
+    }
+    return newQ;
+  }
+}
 function getDefaultQuantityValue() {
-  return { type: "fixed", value: { type: "decimal", value: 0 } };
+  return { type: "fixed", value: { type: "decimal", decimal: 0 } };
 }
 function addQuantityValues(v1, v2) {
   if (v1.type === "fixed" && v1.value.type === "text" || v2.type === "fixed" && v2.value.type === "text") {
@@ -614,201 +1026,406 @@ function addQuantityValues(v1, v2) {
   );
   return { type: "range", min: newMin, max: newMax };
 }
-function addQuantities(q1, q2) {
-  const v1 = q1.value;
-  const v2 = q2.value;
+function addQuantities(q1, q2, system) {
+  const v1 = q1.quantity;
+  const v2 = q2.quantity;
   if (v1.type === "fixed" && v1.value.type === "text" || v2.type === "fixed" && v2.value.type === "text") {
     throw new CannotAddTextValueError();
   }
-  const unit1Def = normalizeUnit(q1.unit);
-  const unit2Def = normalizeUnit(q2.unit);
-  const addQuantityValuesAndSetUnit = (val1, val2, unit) => ({ value: addQuantityValues(val1, val2), unit });
-  if ((q1.unit === "" || q1.unit === void 0) && q2.unit !== void 0) {
+  const unit1Def = normalizeUnit(q1.unit?.name);
+  const unit2Def = normalizeUnit(q2.unit?.name);
+  const addQuantityValuesAndSetUnit = (val1, val2, unit) => ({
+    quantity: addQuantityValues(val1, val2),
+    unit
+  });
+  if ((q1.unit?.name === "" || q1.unit === void 0) && q2.unit !== void 0) {
     return addQuantityValuesAndSetUnit(v1, v2, q2.unit);
   }
-  if ((q2.unit === "" || q2.unit === void 0) && q1.unit !== void 0) {
+  if ((q2.unit?.name === "" || q2.unit === void 0) && q1.unit !== void 0) {
     return addQuantityValuesAndSetUnit(v1, v2, q1.unit);
   }
-  if (!q1.unit && !q2.unit || q1.unit && q2.unit && q1.unit.toLowerCase() === q2.unit.toLowerCase()) {
+  if (!q1.unit && !q2.unit) {
     return addQuantityValuesAndSetUnit(v1, v2, q1.unit);
   }
-  if (unit1Def && unit2Def) {
-    if (unit1Def.type !== unit2Def.type) {
-      throw new IncompatibleUnitsError(
-        `${unit1Def.type} (${q1.unit})`,
-        `${unit2Def.type} (${q2.unit})`
-      );
+  if (q1.unit && q2.unit && q1.unit.name.toLowerCase() === q2.unit.name.toLowerCase()) {
+    if (unit1Def) {
+      const effectiveSystem = system ?? (["metric", "JP"].includes(unit1Def.system) ? unit1Def.system : "US");
+      return addAndFindBestUnit(v1, v2, unit1Def, unit1Def, effectiveSystem, [
+        unit1Def
+      ]);
     }
-    let targetUnitDef;
-    if (unit1Def.system !== unit2Def.system) {
-      const metricUnitDef = unit1Def.system === "metric" ? unit1Def : unit2Def;
-      targetUnitDef = units.filter((u) => u.type === metricUnitDef.type && u.system === "metric").reduce(
-        (prev, current) => prev.toBase > current.toBase ? prev : current
-      );
-    } else {
-      targetUnitDef = unit1Def.toBase >= unit2Def.toBase ? unit1Def : unit2Def;
-    }
-    const convertedV1 = convertQuantityValue(v1, unit1Def, targetUnitDef);
-    const convertedV2 = convertQuantityValue(v2, unit2Def, targetUnitDef);
-    return addQuantityValuesAndSetUnit(
-      convertedV1,
-      convertedV2,
-      targetUnitDef.name
-    );
-  }
-  throw new IncompatibleUnitsError(q1.unit, q2.unit);
-}
-
-// src/errors.ts
-var ReferencedItemCannotBeRedefinedError = class extends Error {
-  constructor(item_type, item_name, new_modifier) {
-    super(
-      `The referenced ${item_type} "${item_name}" cannot be redefined as ${new_modifier}.
-You can either remove the reference to create a new ${item_type} defined as ${new_modifier} or add the ${new_modifier} flag to the original definition of the ${item_type}`
-    );
-    this.name = "ReferencedItemCannotBeRedefinedError";
-  }
-};
-
-// src/parser_helpers.ts
-function flushPendingNote(section, note) {
-  if (note.length > 0) {
-    section.content.push({ type: "note", note });
-    return "";
-  }
-  return note;
-}
-function flushPendingItems(section, items) {
-  if (items.length > 0) {
-    section.content.push({ type: "step", items: [...items] });
-    items.length = 0;
-    return true;
+    return addQuantityValuesAndSetUnit(v1, v2, q1.unit);
   }
-  return false;
-}
-function findAndUpsertIngredient(ingredients, newIngredient, isReference) {
-  const { name, quantity, unit } = newIngredient;
-  if (isReference) {
-    const indexFind = ingredients.findIndex(
-      (i2) => i2.name.toLowerCase() === name.toLowerCase()
-    );
-    if (indexFind === -1) {
-      throw new Error(
-        `Referenced ingredient "${name}" not found. A referenced ingredient must be declared before being referenced with '&'.`
+  if (unit1Def && unit2Def) {
+    if (!areUnitsConvertible(unit1Def, unit2Def)) {
+      throw new IncompatibleUnitsError(
+        `${unit1Def.type} (${q1.unit?.name})`,
+        `${unit2Def.type} (${q2.unit?.name})`
       );
     }
-    const existingIngredient = ingredients[indexFind];
-    for (const flag of newIngredient.flags) {
-      if (!existingIngredient.flags.includes(flag)) {
-        throw new ReferencedItemCannotBeRedefinedError(
-          "ingredient",
-          existingIngredient.name,
-          flag
-        );
-      }
-    }
-    let quantityPartIndex = void 0;
-    if (quantity !== void 0) {
-      const currentQuantity = {
-        value: existingIngredient.quantity ?? getDefaultQuantityValue(),
-        unit: existingIngredient.unit ?? ""
-      };
-      const newQuantity = { value: quantity, unit: unit ?? "" };
-      try {
-        const total = addQuantities(currentQuantity, newQuantity);
-        existingIngredient.quantity = total.value;
-        existingIngredient.unit = total.unit || void 0;
-        if (existingIngredient.quantityParts) {
-          existingIngredient.quantityParts.push(
-            ...newIngredient.quantityParts
-          );
+    let effectiveSystem = system;
+    if (!effectiveSystem) {
+      if (unit1Def.system === "metric" || unit2Def.system === "metric") {
+        effectiveSystem = "metric";
+      } else {
+        if (unit1Def.system === "JP" && unit2Def.system === "JP") {
+          effectiveSystem = "JP";
         } else {
-          existingIngredient.quantityParts = newIngredient.quantityParts;
-        }
-        quantityPartIndex = existingIngredient.quantityParts.length - 1;
-      } catch (e2) {
-        if (e2 instanceof IncompatibleUnitsError || e2 instanceof CannotAddTextValueError) {
-          return {
-            ingredientIndex: ingredients.push(newIngredient) - 1,
-            quantityPartIndex: 0
-          };
+          const unit1SupportsUS = unit1Def.system === "US" || unit1Def.system === "ambiguous" && unit1Def.toBaseBySystem && "US" in unit1Def.toBaseBySystem;
+          const unit2SupportsUS = unit2Def.system === "US" || unit2Def.system === "ambiguous" && unit2Def.toBaseBySystem && "US" in unit2Def.toBaseBySystem;
+          effectiveSystem = unit1SupportsUS && unit2SupportsUS ? "US" : "metric";
         }
       }
     }
+    return addAndFindBestUnit(v1, v2, unit1Def, unit2Def, effectiveSystem, [
+      unit1Def,
+      unit2Def
+    ]);
+  }
+  throw new IncompatibleUnitsError(
+    q1.unit?.name,
+    q2.unit?.name
+  );
+}
+function addAndFindBestUnit(v1, v2, unit1Def, unit2Def, system, inputUnits) {
+  const toBase1 = getToBase(unit1Def, system);
+  const toBase2 = getToBase(unit2Def, system);
+  let sumInBase;
+  if (v1.type === "fixed" && v2.type === "fixed") {
+    const val1 = getNumericValue(v1.value);
+    const val2 = getNumericValue(v2.value);
+    sumInBase = val1 * toBase1 + val2 * toBase2;
+  } else {
+    const avg1 = getAverageValue(v1);
+    const avg2 = getAverageValue(v2);
+    sumInBase = avg1 * toBase1 + avg2 * toBase2;
+  }
+  const { unit: bestUnit, value: bestValue } = findBestUnit(
+    sumInBase,
+    unit1Def.type,
+    system,
+    inputUnits
+  );
+  const formattedValue = formatOutputValue(bestValue, bestUnit);
+  if (v1.type === "range" || v2.type === "range") {
+    const r1 = v1.type === "range" ? v1 : { type: "range", min: v1.value, max: v1.value };
+    const r2 = v2.type === "range" ? v2 : { type: "range", min: v2.value, max: v2.value };
+    const minInBase = getNumericValue(r1.min) * toBase1 + getNumericValue(r2.min) * toBase2;
+    const maxInBase = getNumericValue(r1.max) * toBase1 + getNumericValue(r2.max) * toBase2;
+    const bestToBase = getToBase(bestUnit, system);
+    const minValue = minInBase / bestToBase;
+    const maxValue = maxInBase / bestToBase;
     return {
-      ingredientIndex: indexFind,
-      quantityPartIndex
+      quantity: {
+        type: "range",
+        min: formatOutputValue(minValue, bestUnit),
+        max: formatOutputValue(maxValue, bestUnit)
+      },
+      unit: { name: bestUnit.name }
     };
   }
   return {
-    ingredientIndex: ingredients.push(newIngredient) - 1,
-    quantityPartIndex: newIngredient.quantity ? 0 : void 0
+    quantity: { type: "fixed", value: formattedValue },
+    unit: { name: bestUnit.name }
   };
 }
-function findAndUpsertCookware(cookware, newCookware, isReference) {
-  const { name, quantity } = newCookware;
-  if (isReference) {
-    const index = cookware.findIndex(
-      (i2) => i2.name.toLowerCase() === name.toLowerCase()
-    );
-    if (index === -1) {
-      throw new Error(
-        `Referenced cookware "${name}" not found. A referenced cookware must be declared before being referenced with '&'.`
-      );
-    }
-    const existingCookware = cookware[index];
-    for (const flag of newCookware.flags) {
-      if (!existingCookware.flags.includes(flag)) {
-        throw new ReferencedItemCannotBeRedefinedError(
+function convertQuantityToSystem(quantity, system) {
+  const unitDef = resolveUnit(
+    typeof quantity.unit === "string" ? quantity.unit : quantity.unit?.name
+  );
+  if (unitDef.type === "other" || !("toBase" in unitDef)) {
+    return void 0;
+  }
+  const avgValue = getAverageValue(quantity.quantity);
+  if (typeof avgValue !== "number") {
+    return void 0;
+  }
+  const toBase = getToBase(unitDef, system);
+  const valueInBase = avgValue * toBase;
+  const { unit: bestUnit, value: bestValue } = findBestUnit(
+    valueInBase,
+    unitDef.type,
+    system,
+    [unitDef]
+  );
+  const formattedValue = formatOutputValue(bestValue, bestUnit);
+  if (quantity.quantity.type === "range") {
+    const bestToBase = getToBase(bestUnit, system);
+    const minValue = getNumericValue(quantity.quantity.min) * toBase / bestToBase;
+    const maxValue = getNumericValue(quantity.quantity.max) * toBase / bestToBase;
+    return {
+      quantity: {
+        type: "range",
+        min: formatOutputValue(minValue, bestUnit),
+        max: formatOutputValue(maxValue, bestUnit)
+      },
+      unit: { name: bestUnit.name }
+    };
+  }
+  return {
+    quantity: { type: "fixed", value: formattedValue },
+    unit: { name: bestUnit.name }
+  };
+}
+function toPlainUnit(quantity) {
+  if (isQuantity(quantity))
+    return quantity.unit ? { ...quantity, unit: quantity.unit.name } : quantity;
+  else if (isOrGroup(quantity)) {
+    return {
+      or: quantity.or.map(toPlainUnit)
+    };
+  } else {
+    return {
+      and: quantity.and.map(toPlainUnit)
+    };
+  }
+}
+function toExtendedUnit(q) {
+  if (isQuantity(q)) {
+    return q.unit ? { ...q, unit: { name: q.unit } } : q;
+  } else if (isOrGroup(q)) {
+    return { or: q.or.map(toExtendedUnit) };
+  } else {
+    return { and: q.and.map(toExtendedUnit) };
+  }
+}
+function deNormalizeQuantity(q) {
+  const result = {
+    quantity: q.quantity
+  };
+  if (!isNoUnit(q.unit)) {
+    result.unit = { name: q.unit.name };
+  }
+  return result;
+}
+var flattenPlainUnitGroup = (summed) => {
+  if (isOrGroup(summed)) {
+    const entries = summed.or;
+    const andGroupEntry = entries.find(
+      (e2) => isAndGroup(e2)
+    );
+    if (andGroupEntry) {
+      const andEntries = [];
+      const addGroupEntryContent = andGroupEntry.and;
+      for (const entry of addGroupEntryContent) {
+        andEntries.push({
+          quantity: entry.quantity,
+          ...entry.unit && { unit: entry.unit }
+        });
+      }
+      const equivalentsList = entries.filter((e2) => isQuantity(e2)).map((e2) => ({ quantity: e2.quantity, unit: e2.unit }));
+      if (equivalentsList.length > 0) {
+        return [
+          {
+            and: andEntries,
+            equivalents: equivalentsList
+          }
+        ];
+      } else {
+        return andEntries;
+      }
+    }
+    const simpleEntries = entries.filter(
+      (e2) => isQuantity(e2)
+    );
+    if (simpleEntries.length > 0) {
+      const result = {
+        quantity: simpleEntries[0].quantity,
+        unit: simpleEntries[0].unit
+      };
+      if (simpleEntries.length > 1) {
+        result.equivalents = simpleEntries.slice(1);
+      }
+      return [result];
+    } else {
+      const first = entries[0];
+      return [{ quantity: first.quantity, unit: first.unit }];
+    }
+  } else if (isAndGroup(summed)) {
+    const andEntries = [];
+    const equivalentsList = [];
+    for (const entry of summed.and) {
+      if (isOrGroup(entry)) {
+        const orEntries = entry.or;
+        andEntries.push({
+          quantity: orEntries[0].quantity,
+          ...orEntries[0].unit && { unit: orEntries[0].unit }
+        });
+        equivalentsList.push(...orEntries.slice(1));
+      } else if (isQuantity(entry)) {
+        andEntries.push({
+          quantity: entry.quantity,
+          ...entry.unit && { unit: entry.unit }
+        });
+      }
+    }
+    if (equivalentsList.length === 0) {
+      return andEntries;
+    }
+    const result = {
+      and: andEntries,
+      equivalents: equivalentsList
+    };
+    return [result];
+  } else {
+    return [
+      { quantity: summed.quantity, ...summed.unit && { unit: summed.unit } }
+    ];
+  }
+};
+function applyBestUnit(q, system) {
+  if (!q.unit?.name) {
+    return q;
+  }
+  const unitDef = resolveUnit(q.unit.name);
+  if (unitDef.type === "other") {
+    return q;
+  }
+  if (q.quantity.type === "fixed" && q.quantity.value.type === "text") {
+    return q;
+  }
+  const avgValue = getAverageValue(q.quantity);
+  const effectiveSystem = system ?? (["metric", "JP"].includes(unitDef.system) ? unitDef.system : "US");
+  const toBase = getToBase(unitDef, effectiveSystem);
+  const valueInBase = avgValue * toBase;
+  const { unit: bestUnit, value: bestValue } = findBestUnit(
+    valueInBase,
+    unitDef.type,
+    effectiveSystem,
+    [unitDef]
+  );
+  const originalCanonicalName = normalizeUnit(q.unit.name)?.name;
+  if (bestUnit.name === originalCanonicalName) {
+    return q;
+  }
+  const formattedValue = formatOutputValue(bestValue, bestUnit);
+  if (q.quantity.type === "range") {
+    const bestToBase = getToBase(bestUnit, effectiveSystem);
+    const minValue = getNumericValue(q.quantity.min) * toBase / bestToBase;
+    const maxValue = getNumericValue(q.quantity.max) * toBase / bestToBase;
+    return {
+      quantity: {
+        type: "range",
+        min: formatOutputValue(minValue, bestUnit),
+        max: formatOutputValue(maxValue, bestUnit)
+      },
+      unit: { name: bestUnit.name }
+    };
+  }
+  return {
+    quantity: {
+      type: "fixed",
+      value: formattedValue
+    },
+    unit: { name: bestUnit.name }
+  };
+}
+
+// src/utils/parser_helpers.ts
+function flushPendingNote(section, noteItems) {
+  if (noteItems.length > 0) {
+    section.content.push({ type: "note", items: [...noteItems] });
+    return [];
+  }
+  return noteItems;
+}
+function flushPendingItems(section, items) {
+  if (items.length > 0) {
+    section.content.push({ type: "step", items: [...items] });
+    items.length = 0;
+    return true;
+  }
+  return false;
+}
+function findAndUpsertIngredient(ingredients, newIngredient, isReference) {
+  const { name } = newIngredient;
+  if (isReference) {
+    const indexFind = ingredients.findIndex(
+      (i2) => i2.name.toLowerCase() === name.toLowerCase()
+    );
+    if (indexFind === -1) {
+      throw new Error(
+        `Referenced ingredient "${name}" not found. A referenced ingredient must be declared before being referenced with '&'.`
+      );
+    }
+    const existingIngredient = ingredients[indexFind];
+    if (!newIngredient.flags) {
+      if (Array.isArray(existingIngredient.flags) && existingIngredient.flags.length > 0) {
+        throw new ReferencedItemCannotBeRedefinedError(
+          "ingredient",
+          existingIngredient.name,
+          existingIngredient.flags[0]
+        );
+      }
+    } else {
+      for (const flag of newIngredient.flags) {
+        if (existingIngredient.flags === void 0 || !existingIngredient.flags.includes(flag)) {
+          throw new ReferencedItemCannotBeRedefinedError(
+            "ingredient",
+            existingIngredient.name,
+            flag
+          );
+        }
+      }
+    }
+    return indexFind;
+  }
+  return ingredients.push(newIngredient) - 1;
+}
+function findAndUpsertCookware(cookware, newCookware, isReference) {
+  const { name, quantity } = newCookware;
+  if (isReference) {
+    const index = cookware.findIndex(
+      (i2) => i2.name.toLowerCase() === name.toLowerCase()
+    );
+    if (index === -1) {
+      throw new Error(
+        `Referenced cookware "${name}" not found. A referenced cookware must be declared before being referenced with '&'.`
+      );
+    }
+    const existingCookware = cookware[index];
+    if (!newCookware.flags) {
+      if (Array.isArray(existingCookware.flags) && existingCookware.flags.length > 0) {
+        throw new ReferencedItemCannotBeRedefinedError(
           "cookware",
           existingCookware.name,
-          flag
+          existingCookware.flags[0]
         );
       }
+    } else {
+      for (const flag of newCookware.flags) {
+        if (existingCookware.flags === void 0 || !existingCookware.flags.includes(flag)) {
+          throw new ReferencedItemCannotBeRedefinedError(
+            "cookware",
+            existingCookware.name,
+            flag
+          );
+        }
+      }
     }
-    let quantityPartIndex = void 0;
     if (quantity !== void 0) {
       if (!existingCookware.quantity) {
         existingCookware.quantity = quantity;
-        existingCookware.quantityParts = newCookware.quantityParts;
-        quantityPartIndex = 0;
       } else {
         try {
           existingCookware.quantity = addQuantityValues(
             existingCookware.quantity,
             quantity
           );
-          if (!existingCookware.quantityParts) {
-            existingCookware.quantityParts = newCookware.quantityParts;
-            quantityPartIndex = 0;
-          } else {
-            quantityPartIndex = existingCookware.quantityParts.push(
-              ...newCookware.quantityParts
-            ) - 1;
-          }
         } catch (e2) {
           if (e2 instanceof CannotAddTextValueError) {
-            return {
-              cookwareIndex: cookware.push(newCookware) - 1,
-              quantityPartIndex: 0
-            };
+            return cookware.push(newCookware) - 1;
           }
         }
       }
     }
-    return {
-      cookwareIndex: index,
-      quantityPartIndex
-    };
+    return index;
   }
-  return {
-    cookwareIndex: cookware.push(newCookware) - 1,
-    quantityPartIndex: quantity ? 0 : void 0
-  };
+  return cookware.push(newCookware) - 1;
 }
 var parseFixedValue = (input_str) => {
   if (!numberLikeRegex.test(input_str)) {
-    return { type: "text", value: input_str };
+    return { type: "text", text: input_str };
   }
   const s = input_str.trim().replace(",", ".");
   if (s.includes("/")) {
@@ -817,8 +1434,22 @@ var parseFixedValue = (input_str) => {
     const den = Number(parts[1]);
     return { type: "fraction", num, den };
   }
-  return { type: "decimal", value: Number(s) };
+  return { type: "decimal", decimal: Number(s) };
 };
+function stringifyQuantityValue(quantity) {
+  if (quantity.type === "fixed") {
+    return stringifyFixedValue(quantity);
+  } else {
+    return `${stringifyFixedValue({ type: "fixed", value: quantity.min })}-${stringifyFixedValue({ type: "fixed", value: quantity.max })}`;
+  }
+}
+function stringifyFixedValue(quantity) {
+  if (quantity.value.type === "fraction")
+    return `${quantity.value.num}/${quantity.value.den}`;
+  else if (quantity.value.type === "decimal")
+    return String(quantity.value.decimal);
+  else return quantity.value.text;
+}
 function parseQuantityInput(input_str) {
   const clean_str = String(input_str).trim();
   if (rangeRegex.test(clean_str)) {
@@ -860,7 +1491,7 @@ function parseListMetaVar(content, varName) {
 function extractMetadata(content) {
   const metadata = {};
   let servings = void 0;
-  const metadataContent = content.match(metadataRegex)?.[1];
+  const metadataContent = content.match(metadataRegex)?.[2];
   if (!metadataContent) {
     return { metadata };
   }
@@ -892,6 +1523,18 @@ function extractMetadata(content) {
     const stringMetaValue = parseSimpleMetaVar(metadataContent, metaVar);
     if (stringMetaValue) metadata[metaVar] = stringMetaValue;
   }
+  let unitSystem;
+  const unitSystemRaw = parseSimpleMetaVar(metadataContent, "unit system");
+  if (unitSystemRaw) {
+    metadata["unit system"] = unitSystemRaw;
+    const unitSystemMap = {
+      metric: "metric",
+      us: "US",
+      uk: "UK",
+      jp: "JP"
+    };
+    unitSystem = unitSystemMap[unitSystemRaw.toLowerCase()];
+  }
   for (const metaVar of ["serves", "yield", "servings"]) {
     const scalingMetaValue = parseScalingMetaVar(metadataContent, metaVar);
     if (scalingMetaValue && scalingMetaValue[1]) {
@@ -903,12 +1546,521 @@ function extractMetadata(content) {
     const listMetaValue = parseListMetaVar(metadataContent, metaVar);
     if (listMetaValue) metadata[metaVar] = listMetaValue;
   }
-  return { metadata, servings };
+  return { metadata, servings, unitSystem };
+}
+function isPositiveIntegerString(str) {
+  return /^\d+$/.test(str);
+}
+function unionOfSets(s1, s2) {
+  const result = new Set(s1);
+  for (const item of s2) {
+    result.add(item);
+  }
+  return result;
+}
+function getAlternativeSignature(alternatives) {
+  if (!alternatives || alternatives.length === 0) return null;
+  return alternatives.map((a2) => a2.index).sort((a2, b) => a2 - b).join(",");
+}
+
+// src/classes/product_catalog.ts
+var ProductCatalog = class {
+  constructor(tomlContent) {
+    __publicField(this, "products", []);
+    if (tomlContent) this.parse(tomlContent);
+  }
+  /**
+   * Parses a TOML string into a list of product options.
+   * @param tomlContent - The TOML string to parse.
+   * @returns A parsed list of `ProductOption`.
+   */
+  parse(tomlContent) {
+    const catalogRaw = import_smol_toml.default.parse(tomlContent);
+    this.products = [];
+    if (!this.isValidTomlContent(catalogRaw)) {
+      throw new InvalidProductCatalogFormat();
+    }
+    for (const [ingredientName, ingredientData] of Object.entries(catalogRaw)) {
+      const ingredientTable = ingredientData;
+      const aliases = ingredientTable.aliases;
+      for (const [key, productData] of Object.entries(ingredientTable)) {
+        if (key === "aliases") {
+          continue;
+        }
+        const productId = key;
+        const { name, size, price, ...rest } = productData;
+        const sizeStrings = Array.isArray(size) ? size : [size];
+        const sizes = sizeStrings.map((sizeStr) => {
+          const sizeAndUnitRaw = sizeStr.split("%");
+          const sizeParsed = parseQuantityInput(
+            sizeAndUnitRaw[0]
+          );
+          const productSize = { size: sizeParsed };
+          if (sizeAndUnitRaw.length > 1) {
+            productSize.unit = sizeAndUnitRaw[1];
+          }
+          return productSize;
+        });
+        const productOption = {
+          id: productId,
+          productName: name,
+          ingredientName,
+          price,
+          sizes,
+          ...rest
+        };
+        if (aliases) {
+          productOption.ingredientAliases = aliases;
+        }
+        this.products.push(productOption);
+      }
+    }
+    return this.products;
+  }
+  /**
+   * Stringifies the catalog to a TOML string.
+   * @returns The TOML string representation of the catalog.
+   */
+  stringify() {
+    const grouped = {};
+    for (const product of this.products) {
+      const {
+        id,
+        ingredientName,
+        ingredientAliases,
+        sizes,
+        productName,
+        ...rest
+      } = product;
+      if (!grouped[ingredientName]) {
+        grouped[ingredientName] = {};
+      }
+      if (ingredientAliases && !grouped[ingredientName].aliases) {
+        grouped[ingredientName].aliases = ingredientAliases;
+      }
+      const sizeStrings = sizes.map(
+        (s) => s.unit ? `${stringifyQuantityValue(s.size)}%${s.unit}` : stringifyQuantityValue(s.size)
+      );
+      grouped[ingredientName][id] = {
+        ...rest,
+        name: productName,
+        // Use array if multiple sizes, otherwise single string
+        size: sizeStrings.length === 1 ? sizeStrings[0] : sizeStrings
+      };
+    }
+    return import_smol_toml.default.stringify(grouped);
+  }
+  /**
+   * Adds a product to the catalog.
+   * @param productOption - The product to add.
+   */
+  add(productOption) {
+    this.products.push(productOption);
+  }
+  /**
+   * Removes a product from the catalog by its ID.
+   * @param productId - The ID of the product to remove.
+   */
+  remove(productId) {
+    this.products = this.products.filter((product) => product.id !== productId);
+  }
+  isValidTomlContent(catalog) {
+    for (const productsRaw of Object.values(catalog)) {
+      if (typeof productsRaw !== "object" || productsRaw === null) {
+        return false;
+      }
+      for (const [id, obj] of Object.entries(productsRaw)) {
+        if (id === "aliases") {
+          if (!Array.isArray(obj)) {
+            return false;
+          }
+        } else {
+          if (!isPositiveIntegerString(id)) {
+            return false;
+          }
+          if (typeof obj !== "object" || obj === null) {
+            return false;
+          }
+          const record = obj;
+          const keys = Object.keys(record);
+          const mandatoryKeys = ["name", "size", "price"];
+          if (mandatoryKeys.some((key) => !keys.includes(key))) {
+            return false;
+          }
+          const hasProductName = typeof record.name === "string";
+          const hasSize = typeof record.size === "string" || Array.isArray(record.size) && record.size.every((s) => typeof s === "string");
+          const hasPrice = typeof record.price === "number";
+          if (!(hasProductName && hasSize && hasPrice)) {
+            return false;
+          }
+        }
+      }
+    }
+    return true;
+  }
+};
+
+// src/classes/section.ts
+var Section = class {
+  /**
+   * Creates an instance of Section.
+   * @param name - The name of the section. Defaults to an empty string.
+   */
+  constructor(name = "") {
+    /**
+     * The name of the section. Can be an empty string for the default (first) section.
+     * @defaultValue `""`
+     */
+    __publicField(this, "name");
+    /** An array of steps and notes that make up the content of the section. */
+    __publicField(this, "content", []);
+    this.name = name;
+  }
+  /**
+   * Checks if the section is blank (has no name and no content).
+   * Used during recipe parsing
+   * @returns `true` if the section is blank, otherwise `false`.
+   */
+  isBlank() {
+    return this.name === "" && this.content.length === 0;
+  }
+};
+
+// src/quantities/alternatives.ts
+var import_big3 = __toESM(require("big.js"), 1);
+
+// src/units/lookup.ts
+function findListWithCompatibleQuantity(list, quantity) {
+  const quantityWithUnitDef = {
+    ...quantity,
+    unit: resolveUnit(quantity.unit?.name)
+  };
+  return list.find(
+    (l) => l.some((lq) => areUnitsGroupable(lq.unit, quantityWithUnitDef.unit))
+  );
+}
+function findCompatibleQuantityWithinList(list, quantity) {
+  const quantityWithUnitDef = {
+    ...quantity,
+    unit: resolveUnit(quantity.unit?.name)
+  };
+  return list.find(
+    (q) => q.unit.name === quantityWithUnitDef.unit.name || q.unit.type === quantityWithUnitDef.unit.type && q.unit.type !== "other"
+  );
+}
+
+// src/utils/general.ts
+var legacyDeepClone = (v) => {
+  if (v === null || typeof v !== "object") {
+    return v;
+  }
+  if (v instanceof Map) {
+    return new Map(
+      Array.from(v.entries()).map(([k, val]) => [
+        legacyDeepClone(k),
+        legacyDeepClone(val)
+      ])
+    );
+  }
+  if (v instanceof Set) {
+    return new Set(Array.from(v).map((val) => legacyDeepClone(val)));
+  }
+  if (v instanceof Date) {
+    return new Date(v.getTime());
+  }
+  if (Array.isArray(v)) {
+    return v.map((item) => legacyDeepClone(item));
+  }
+  const cloned = {};
+  for (const key of Object.keys(v)) {
+    cloned[key] = legacyDeepClone(v[key]);
+  }
+  return cloned;
+};
+var deepClone = (v) => typeof structuredClone === "function" ? structuredClone(v) : legacyDeepClone(v);
+
+// src/quantities/alternatives.ts
+function getEquivalentUnitsLists(...quantities) {
+  const quantitiesCopy = deepClone(quantities);
+  const OrGroups = quantitiesCopy.filter(isOrGroup).filter((q) => q.or.length > 1);
+  const unitLists = [];
+  const normalizeOrGroup = (og) => ({
+    ...og,
+    or: og.or.map((q) => ({
+      ...q,
+      unit: resolveUnit(q.unit?.name, q.unit?.integerProtected)
+    }))
+  });
+  function findLinkIndexForUnits(lists, unitsToCheck) {
+    return lists.findIndex((l) => {
+      const listItems = l.map((q) => resolveUnit(q.unit?.name));
+      return unitsToCheck.some(
+        (u) => u && listItems.some((lu) => areUnitsGroupable(lu, u))
+      );
+    });
+  }
+  function mergeOrGroupIntoList(lists, idx, og) {
+    let unitRatio;
+    const commonUnitList = lists[idx].reduce((acc, v) => {
+      const normalizedV = {
+        ...v,
+        unit: resolveUnit(v.unit?.name, v.unit?.integerProtected)
+      };
+      const commonQuantity = og.or.find(
+        (q) => isQuantity(q) && areUnitsGroupable(q.unit, normalizedV.unit)
+      );
+      if (commonQuantity) {
+        acc.push(normalizedV);
+        if (!unitRatio) {
+          unitRatio = getUnitRatio(normalizedV, commonQuantity);
+        }
+      }
+      return acc;
+    }, []);
+    for (const newQ of og.or) {
+      if (commonUnitList.some((q) => areUnitsGroupable(q.unit, newQ.unit))) {
+        continue;
+      } else {
+        const scaledQuantity = multiplyQuantityValue(newQ.quantity, unitRatio);
+        lists[idx].push({ ...newQ, quantity: scaledQuantity });
+      }
+    }
+  }
+  for (const orGroup of OrGroups) {
+    const orGroupModified = normalizeOrGroup(orGroup);
+    const units2 = orGroupModified.or.map((q) => q.unit);
+    const linkIndex = findLinkIndexForUnits(unitLists, units2);
+    if (linkIndex === -1) {
+      unitLists.push(orGroupModified.or);
+    } else {
+      mergeOrGroupIntoList(unitLists, linkIndex, orGroupModified);
+    }
+  }
+  return unitLists;
+}
+function sortUnitList(list) {
+  if (!list || list.length <= 1) return list;
+  const priorityList = [];
+  const nonPriorityList = [];
+  for (const q of list) {
+    if (q.unit.integerProtected || q.unit.system === "none") {
+      priorityList.push(q);
+    } else {
+      nonPriorityList.push(q);
+    }
+  }
+  return priorityList.sort((a2, b) => {
+    const prefixA = a2.unit.integerProtected ? "___" : "";
+    const prefixB = b.unit.integerProtected ? "___" : "";
+    return (prefixA + a2.unit.name).localeCompare(prefixB + b.unit.name, "en");
+  }).concat(nonPriorityList);
+}
+function reduceOrsToFirstEquivalent(unitList, quantities) {
+  function reduceToQuantity(firstQuantity) {
+    const equivalentList = sortUnitList(
+      findListWithCompatibleQuantity(unitList, firstQuantity)
+    );
+    if (!equivalentList) return firstQuantity;
+    const firstQuantityInList = findCompatibleQuantityWithinList(
+      equivalentList,
+      firstQuantity
+    );
+    const normalizedFirstQuantity = {
+      ...firstQuantity,
+      unit: resolveUnit(firstQuantity.unit?.name)
+    };
+    if (firstQuantityInList.unit.integerProtected) {
+      const resultQuantity = {
+        quantity: firstQuantity.quantity
+      };
+      if (!isNoUnit(normalizedFirstQuantity.unit)) {
+        resultQuantity.unit = { name: normalizedFirstQuantity.unit.name };
+      }
+      return resultQuantity;
+    } else {
+      let nextProtected;
+      const equivalentListTemp = [...equivalentList];
+      while (nextProtected !== -1) {
+        nextProtected = equivalentListTemp.findIndex(
+          (eq) => eq.unit?.integerProtected
+        );
+        if (nextProtected !== -1) {
+          const unitRatio2 = getUnitRatio(
+            equivalentListTemp[nextProtected],
+            firstQuantityInList
+          );
+          const nextProtectedQuantityValue = multiplyQuantityValue(
+            firstQuantity.quantity,
+            unitRatio2
+          );
+          if (isValueIntegerLike(nextProtectedQuantityValue)) {
+            const nextProtectedQuantity = {
+              quantity: nextProtectedQuantityValue
+            };
+            if (!isNoUnit(equivalentListTemp[nextProtected].unit)) {
+              nextProtectedQuantity.unit = {
+                name: equivalentListTemp[nextProtected].unit.name
+              };
+            }
+            return nextProtectedQuantity;
+          } else {
+            equivalentListTemp.splice(nextProtected, 1);
+          }
+        }
+      }
+      const firstNonIntegerProtected = equivalentListTemp.filter(
+        (q) => !q.unit.integerProtected
+      )[0];
+      const unitRatio = getUnitRatio(
+        firstNonIntegerProtected,
+        firstQuantityInList
+      ).times(getBaseUnitRatio(normalizedFirstQuantity, firstQuantityInList));
+      const firstEqQuantity = {
+        quantity: firstNonIntegerProtected.unit.name === firstQuantity.unit.name ? firstQuantity.quantity : multiplyQuantityValue(firstQuantity.quantity, unitRatio)
+      };
+      if (!isNoUnit(firstNonIntegerProtected.unit)) {
+        firstEqQuantity.unit = { name: firstNonIntegerProtected.unit.name };
+      }
+      return firstEqQuantity;
+    }
+  }
+  return quantities.map((q) => {
+    if (isQuantity(q)) return reduceToQuantity(q);
+    const qListModified = sortUnitList(
+      q.or.map((qq) => ({
+        ...qq,
+        unit: resolveUnit(qq.unit?.name, qq.unit?.integerProtected)
+      }))
+    );
+    return reduceToQuantity(qListModified[0]);
+  });
+}
+function addQuantitiesOrGroups(quantities, system) {
+  if (quantities.length === 0)
+    return {
+      sum: {
+        quantity: getDefaultQuantityValue(),
+        unit: resolveUnit()
+      },
+      unitsLists: []
+    };
+  if (quantities.length === 1) {
+    if (isQuantity(quantities[0]))
+      return {
+        sum: {
+          ...quantities[0],
+          unit: resolveUnit(quantities[0].unit?.name)
+        },
+        unitsLists: []
+      };
+  }
+  const unitsLists = getEquivalentUnitsLists(...quantities);
+  const reducedQuantities = reduceOrsToFirstEquivalent(unitsLists, quantities);
+  const sum = [];
+  for (const nextQ of reducedQuantities) {
+    const existingQ = findCompatibleQuantityWithinList(sum, nextQ);
+    if (existingQ === void 0) {
+      sum.push({
+        ...nextQ,
+        unit: resolveUnit(nextQ.unit?.name)
+      });
+    } else {
+      const sumQ = addQuantities(existingQ, nextQ, system);
+      existingQ.quantity = sumQ.quantity;
+      existingQ.unit = resolveUnit(sumQ.unit?.name);
+    }
+  }
+  if (sum.length === 1) {
+    return { sum: sum[0], unitsLists };
+  }
+  return { sum: { and: sum }, unitsLists };
+}
+function regroupQuantitiesAndExpandEquivalents(sum, unitsLists, system) {
+  const sumQuantities = isAndGroup(sum) ? sum.and : [sum];
+  const result = [];
+  const processedQuantities = /* @__PURE__ */ new Set();
+  for (const list of unitsLists) {
+    const listCopy = deepClone(list);
+    const main = [];
+    const mainCandidates = sumQuantities.filter(
+      (q) => !processedQuantities.has(q)
+    );
+    if (mainCandidates.length === 0) continue;
+    mainCandidates.forEach((q) => {
+      const mainInList = findCompatibleQuantityWithinList(listCopy, q);
+      if (mainInList !== void 0) {
+        processedQuantities.add(q);
+        main.push(q);
+        listCopy.splice(listCopy.indexOf(mainInList), 1);
+      }
+    });
+    const equivalents = sortUnitList(listCopy).map((equiv) => {
+      const initialValue = {
+        quantity: getDefaultQuantityValue()
+      };
+      if (equiv.unit) {
+        initialValue.unit = { name: equiv.unit.name };
+      }
+      return main.reduce((acc, v) => {
+        const mainInList = findCompatibleQuantityWithinList(list, v);
+        const conversionRatio = getBaseUnitRatio(v, mainInList);
+        const valueInOriginalUnit = (0, import_big3.default)(getAverageValue(v.quantity)).times(
+          conversionRatio
+        );
+        const newValue = {
+          quantity: multiplyQuantityValue(
+            {
+              type: "fixed",
+              value: {
+                type: "decimal",
+                decimal: valueInOriginalUnit.toNumber()
+              }
+            },
+            (0, import_big3.default)(getAverageValue(equiv.quantity)).div(
+              getAverageValue(mainInList.quantity)
+            )
+          )
+        };
+        if (equiv.unit && !isNoUnit(equiv.unit)) {
+          newValue.unit = { name: equiv.unit.name };
+        }
+        return addQuantities(acc, newValue, system);
+      }, initialValue);
+    });
+    if (main.length + equivalents.length > 1) {
+      const resultMain = main.length > 1 ? {
+        and: main.map(deNormalizeQuantity)
+      } : deNormalizeQuantity(main[0]);
+      result.push({
+        or: [resultMain, ...equivalents]
+      });
+    } else {
+      result.push(deNormalizeQuantity(main[0]));
+    }
+  }
+  sumQuantities.filter((q) => !processedQuantities.has(q)).forEach((q) => result.push(deNormalizeQuantity(q)));
+  return result;
+}
+function addEquivalentsAndSimplify(quantities, system) {
+  if (quantities.length === 1) {
+    return toPlainUnit(quantities[0]);
+  }
+  const { sum, unitsLists } = addQuantitiesOrGroups(quantities, system);
+  const regrouped = regroupQuantitiesAndExpandEquivalents(
+    sum,
+    unitsLists,
+    system
+  );
+  if (regrouped.length === 1) {
+    return toPlainUnit(regrouped[0]);
+  } else {
+    return { and: regrouped.map(toPlainUnit) };
+  }
 }
 
 // src/classes/recipe.ts
-var import_big2 = __toESM(require("big.js"), 1);
-var Recipe = class _Recipe {
+var import_big4 = __toESM(require("big.js"), 1);
+var _Recipe = class _Recipe {
   /**
    * Creates a new Recipe instance.
    * @param content - The recipe content to parse.
@@ -918,6 +2070,13 @@ var Recipe = class _Recipe {
      * The parsed recipe metadata.
      */
     __publicField(this, "metadata", {});
+    /**
+     * The possible choices of alternative ingredients for this recipe.
+     */
+    __publicField(this, "choices", {
+      ingredientItems: /* @__PURE__ */ new Map(),
+      ingredientGroups: /* @__PURE__ */ new Map()
+    });
     /**
      * The parsed recipe ingredients.
      */
@@ -934,6 +2093,10 @@ var Recipe = class _Recipe {
      * The parsed recipe timers.
      */
     __publicField(this, "timers", []);
+    /**
+     * The parsed arbitrary quantities.
+     */
+    __publicField(this, "arbitraries", []);
     /**
      * The parsed recipe servings. Used for scaling. Parsed from one of
      * {@link Metadata.servings}, {@link Metadata.yield} or {@link Metadata.serves}
@@ -942,35 +2105,608 @@ var Recipe = class _Recipe {
      * @see {@link Recipe.scaleBy | scaleBy()} and {@link Recipe.scaleTo | scaleTo()} methods
      */
     __publicField(this, "servings");
+    _Recipe.itemCounts.set(this, 0);
     if (content) {
       this.parse(content);
     }
   }
+  /**
+   * Gets the unit system specified in the recipe metadata.
+   * Used for resolving ambiguous units like tsp, tbsp, cup, etc.
+   *
+   * @returns The unit system if specified, or undefined to use defaults
+   */
+  get unitSystem() {
+    return _Recipe.unitSystems.get(this);
+  }
+  /**
+   * Gets the current item count for this recipe.
+   */
+  getItemCount() {
+    return _Recipe.itemCounts.get(this);
+  }
+  /**
+   * Gets the current item count and increments it.
+   */
+  getAndIncrementItemCount() {
+    const current = this.getItemCount();
+    _Recipe.itemCounts.set(this, current + 1);
+    return current;
+  }
+  /**
+   * Parses a matched arbitrary scalable quantity and adds it to the given array.
+   * @private
+   * @param regexMatchGroups - The regex match groups from arbitrary scalable regex.
+   * @param intoArray - The array to push the parsed arbitrary scalable item into.
+   */
+  _parseArbitraryScalable(regexMatchGroups, intoArray) {
+    if (!regexMatchGroups || !regexMatchGroups.arbitraryQuantity) return;
+    const quantityMatch = regexMatchGroups.arbitraryQuantity?.trim().match(quantityAlternativeRegex);
+    if (quantityMatch?.groups) {
+      const value = parseQuantityInput(quantityMatch.groups.quantity);
+      const unit = quantityMatch.groups.unit;
+      const name = regexMatchGroups.arbitraryName || void 0;
+      if (!value || value.type === "fixed" && value.value.type === "text") {
+        throw new InvalidQuantityFormat(
+          regexMatchGroups.arbitraryQuantity?.trim(),
+          "Arbitrary quantities must have a numerical value"
+        );
+      }
+      const arbitrary = {
+        quantity: value
+      };
+      if (name) arbitrary.name = name;
+      if (unit) arbitrary.unit = unit;
+      intoArray.push({
+        type: "arbitrary",
+        index: this.arbitraries.push(arbitrary) - 1
+      });
+    }
+  }
+  /**
+   * Parses text for arbitrary scalables and returns NoteItem array.
+   * @param text - The text to parse for arbitrary scalables.
+   * @returns Array of NoteItem (text and arbitrary scalable items).
+   */
+  _parseNoteText(text) {
+    const noteItems = [];
+    let cursor = 0;
+    const globalRegex = new RegExp(arbitraryScalableRegex.source, "g");
+    for (const match of text.matchAll(globalRegex)) {
+      const idx = match.index;
+      if (idx > cursor) {
+        noteItems.push({ type: "text", value: text.slice(cursor, idx) });
+      }
+      this._parseArbitraryScalable(match.groups, noteItems);
+      cursor = idx + match[0].length;
+    }
+    if (cursor < text.length) {
+      noteItems.push({ type: "text", value: text.slice(cursor) });
+    }
+    return noteItems;
+  }
+  _parseQuantityRecursive(quantityRaw) {
+    let quantityMatch = quantityRaw.match(quantityAlternativeRegex);
+    const quantities = [];
+    while (quantityMatch?.groups) {
+      const value = quantityMatch.groups.quantity ? parseQuantityInput(quantityMatch.groups.quantity) : void 0;
+      const unit = quantityMatch.groups.unit;
+      if (value) {
+        const newQuantity = { quantity: value };
+        if (unit) {
+          if (unit.startsWith("=")) {
+            newQuantity.unit = {
+              name: unit.substring(1),
+              integerProtected: true
+            };
+          } else {
+            newQuantity.unit = { name: unit };
+          }
+        }
+        quantities.push(newQuantity);
+      } else {
+        throw new InvalidQuantityFormat(quantityRaw);
+      }
+      quantityMatch = quantityMatch.groups.alternative ? quantityMatch.groups.alternative.match(quantityAlternativeRegex) : null;
+    }
+    return quantities;
+  }
+  _parseIngredientWithAlternativeRecursive(ingredientMatchString, items) {
+    const alternatives = [];
+    let testString = ingredientMatchString;
+    while (true) {
+      const match = testString.match(
+        alternatives.length > 0 ? inlineIngredientAlternativesRegex : ingredientWithAlternativeRegex
+      );
+      if (!match?.groups) break;
+      const groups = match.groups;
+      let name = groups.mIngredientName || groups.sIngredientName;
+      const preparation = groups.ingredientPreparation;
+      const modifiers = groups.ingredientModifiers;
+      const reference = modifiers !== void 0 && modifiers.includes("&");
+      const flags = [];
+      if (modifiers !== void 0 && modifiers.includes("?")) {
+        flags.push("optional");
+      }
+      if (modifiers !== void 0 && modifiers.includes("-")) {
+        flags.push("hidden");
+      }
+      if (modifiers !== void 0 && modifiers.includes("@") || groups.ingredientRecipeAnchor) {
+        flags.push("recipe");
+      }
+      let extras = void 0;
+      if (flags.includes("recipe")) {
+        extras = { path: `${name}.cook` };
+        name = name.substring(name.lastIndexOf("/") + 1);
+      }
+      const aliasMatch = name.match(ingredientAliasRegex);
+      let listName, displayName;
+      if (aliasMatch && aliasMatch.groups.ingredientListName.trim().length > 0 && aliasMatch.groups.ingredientDisplayName.trim().length > 0) {
+        listName = aliasMatch.groups.ingredientListName.trim();
+        displayName = aliasMatch.groups.ingredientDisplayName.trim();
+      } else {
+        listName = name;
+        displayName = name;
+      }
+      const newIngredient = {
+        name: listName
+      };
+      if (preparation) {
+        newIngredient.preparation = preparation;
+      }
+      if (flags.length > 0) {
+        newIngredient.flags = flags;
+      }
+      if (extras) {
+        newIngredient.extras = extras;
+      }
+      const idxInList = findAndUpsertIngredient(
+        this.ingredients,
+        newIngredient,
+        reference
+      );
+      let itemQuantity = void 0;
+      if (groups.ingredientQuantity) {
+        const parsedQuantities = this._parseQuantityRecursive(
+          groups.ingredientQuantity
+        );
+        const [primary, ...rest] = parsedQuantities;
+        if (primary) {
+          itemQuantity = {
+            ...primary,
+            scalable: groups.ingredientQuantityModifier !== "="
+          };
+          if (rest.length > 0) {
+            itemQuantity.equivalents = rest;
+          }
+        }
+      }
+      const alternative = {
+        index: idxInList,
+        displayName
+      };
+      const note = groups.ingredientNote?.trim();
+      if (note) {
+        alternative.note = note;
+      }
+      if (itemQuantity) {
+        alternative.itemQuantity = itemQuantity;
+      }
+      alternatives.push(alternative);
+      testString = groups.ingredientAlternative || "";
+    }
+    if (alternatives.length > 1) {
+      const alternativesIndexes = alternatives.map((alt) => alt.index);
+      for (const ingredientIndex of alternativesIndexes) {
+        const ingredient = this.ingredients[ingredientIndex];
+        if (ingredient) {
+          if (!ingredient.alternatives) {
+            ingredient.alternatives = new Set(
+              alternativesIndexes.filter((index) => index !== ingredientIndex)
+            );
+          } else {
+            ingredient.alternatives = unionOfSets(
+              ingredient.alternatives,
+              new Set(
+                alternativesIndexes.filter(
+                  (index) => index !== ingredientIndex
+                )
+              )
+            );
+          }
+        }
+      }
+    }
+    const id = `ingredient-item-${this.getAndIncrementItemCount()}`;
+    const newItem = {
+      type: "ingredient",
+      id,
+      alternatives
+    };
+    items.push(newItem);
+    if (alternatives.length > 1) {
+      this.choices.ingredientItems.set(id, alternatives);
+    }
+  }
+  _parseIngredientWithGroupKey(ingredientMatchString, items) {
+    const match = ingredientMatchString.match(ingredientWithGroupKeyRegex);
+    if (!match?.groups) return;
+    const groups = match.groups;
+    const groupKey = groups.gIngredientGroupKey;
+    let name = groups.gmIngredientName || groups.gsIngredientName;
+    const preparation = groups.gIngredientPreparation;
+    const modifiers = groups.gIngredientModifiers;
+    const reference = modifiers !== void 0 && modifiers.includes("&");
+    const flags = [];
+    if (modifiers !== void 0 && modifiers.includes("?")) {
+      flags.push("optional");
+    }
+    if (modifiers !== void 0 && modifiers.includes("-")) {
+      flags.push("hidden");
+    }
+    if (modifiers !== void 0 && modifiers.includes("@") || groups.gIngredientRecipeAnchor) {
+      flags.push("recipe");
+    }
+    let extras = void 0;
+    if (flags.includes("recipe")) {
+      extras = { path: `${name}.cook` };
+      name = name.substring(name.lastIndexOf("/") + 1);
+    }
+    const aliasMatch = name.match(ingredientAliasRegex);
+    let listName, displayName;
+    if (aliasMatch && aliasMatch.groups.ingredientListName.trim().length > 0 && aliasMatch.groups.ingredientDisplayName.trim().length > 0) {
+      listName = aliasMatch.groups.ingredientListName.trim();
+      displayName = aliasMatch.groups.ingredientDisplayName.trim();
+    } else {
+      listName = name;
+      displayName = name;
+    }
+    const newIngredient = {
+      name: listName
+    };
+    if (preparation) {
+      newIngredient.preparation = preparation;
+    }
+    if (flags.length > 0) {
+      newIngredient.flags = flags;
+    }
+    if (extras) {
+      newIngredient.extras = extras;
+    }
+    const idxInList = findAndUpsertIngredient(
+      this.ingredients,
+      newIngredient,
+      reference
+    );
+    let itemQuantity = void 0;
+    if (groups.gIngredientQuantity) {
+      const parsedQuantities = this._parseQuantityRecursive(
+        groups.gIngredientQuantity
+      );
+      const [primary, ...rest] = parsedQuantities;
+      itemQuantity = {
+        ...primary,
+        // there's necessarily a primary quantity as the match group was detected
+        scalable: groups.gIngredientQuantityModifier !== "="
+      };
+      if (rest.length > 0) {
+        itemQuantity.equivalents = rest;
+      }
+    }
+    const alternative = {
+      index: idxInList,
+      displayName
+    };
+    if (itemQuantity) {
+      alternative.itemQuantity = itemQuantity;
+    }
+    const existingAlternatives = this.choices.ingredientGroups.get(groupKey);
+    function upsertAlternativeToIngredient(ingredients, ingredientIdx, newAlternativeIdx) {
+      const ingredient = ingredients[ingredientIdx];
+      if (ingredient) {
+        if (ingredient.alternatives === void 0) {
+          ingredient.alternatives = /* @__PURE__ */ new Set([newAlternativeIdx]);
+        } else {
+          ingredient.alternatives.add(newAlternativeIdx);
+        }
+      }
+    }
+    if (existingAlternatives) {
+      for (const alt of existingAlternatives) {
+        upsertAlternativeToIngredient(this.ingredients, alt.index, idxInList);
+        upsertAlternativeToIngredient(this.ingredients, idxInList, alt.index);
+      }
+    }
+    const id = `ingredient-item-${this.getAndIncrementItemCount()}`;
+    const newItem = {
+      type: "ingredient",
+      id,
+      group: groupKey,
+      alternatives: [alternative]
+    };
+    items.push(newItem);
+    const choiceAlternative = deepClone(alternative);
+    choiceAlternative.itemId = id;
+    const existingChoice = this.choices.ingredientGroups.get(groupKey);
+    if (!existingChoice) {
+      this.choices.ingredientGroups.set(groupKey, [choiceAlternative]);
+    } else {
+      existingChoice.push(choiceAlternative);
+    }
+  }
+  /**
+   * Populates the `quantities` property for each ingredient based on
+   * how they appear in the recipe preparation. Only primary ingredients
+   * get quantities populated. Primary ingredients get `usedAsPrimary: true` flag.
+   *
+   * For inline alternatives (e.g. `\@a|b|c`), the first alternative is primary.
+   * For grouped alternatives (e.g. `\@|group|a`, `\@|group|b`), the first item in the group is primary.
+   *
+   * Quantities are grouped by their alternative signature and summed using addEquivalentsAndSimplify.
+   * @internal
+   */
+  _populate_ingredient_quantities() {
+    for (const ing of this.ingredients) {
+      delete ing.quantities;
+      delete ing.usedAsPrimary;
+    }
+    const ingredientsWithQuantities = this.getIngredientQuantities();
+    const matchedIndices = /* @__PURE__ */ new Set();
+    for (const computed of ingredientsWithQuantities) {
+      const idx = this.ingredients.findIndex(
+        (ing2, i2) => ing2.name === computed.name && !matchedIndices.has(i2)
+      );
+      matchedIndices.add(idx);
+      const ing = this.ingredients[idx];
+      if (computed.quantities) {
+        ing.quantities = computed.quantities;
+      }
+      if (computed.usedAsPrimary) {
+        ing.usedAsPrimary = true;
+      }
+    }
+  }
+  /**
+   * Gets ingredients with their quantities populated, optionally filtered by section/step
+   * and respecting user choices for alternatives.
+   *
+   * When no options are provided, returns all recipe ingredients with quantities
+   * calculated using primary alternatives (same as after parsing).
+   *
+   * @param options - Options for filtering and choice selection:
+   *   - `section`: Filter to a specific section (Section object or 0-based index)
+   *   - `step`: Filter to a specific step (Step object or 0-based index)
+   *   - `choices`: Choices for alternative ingredients (defaults to primary)
+   * @returns Array of Ingredient objects with quantities populated
+   *
+   * @example
+   * ```typescript
+   * // Get all ingredients with primary alternatives
+   * const ingredients = recipe.getIngredientQuantities();
+   *
+   * // Get ingredients for a specific section
+   * const sectionIngredients = recipe.getIngredientQuantities({ section: 0 });
+   *
+   * // Get ingredients with specific choices applied
+   * const withChoices = recipe.getIngredientQuantities({
+   *   choices: { ingredientItems: new Map([['ingredient-item-2', 1]]) }
+   * });
+   * ```
+   */
+  getIngredientQuantities(options) {
+    const { section, step, choices } = options || {};
+    const sectionsToProcess = section !== void 0 ? (() => {
+      const idx = typeof section === "number" ? section : this.sections.indexOf(section);
+      return idx >= 0 && idx < this.sections.length ? [this.sections[idx]] : [];
+    })() : this.sections;
+    const ingredientGroups = /* @__PURE__ */ new Map();
+    const selectedIndices = /* @__PURE__ */ new Set();
+    const referencedIndices = /* @__PURE__ */ new Set();
+    for (const currentSection of sectionsToProcess) {
+      const allSteps = currentSection.content.filter(
+        (item) => item.type === "step"
+      );
+      const stepsToProcess = step === void 0 ? allSteps : typeof step === "number" ? step >= 0 && step < allSteps.length ? [allSteps[step]] : [] : allSteps.includes(step) ? [step] : [];
+      for (const currentStep of stepsToProcess) {
+        for (const item of currentStep.items.filter(
+          (item2) => item2.type === "ingredient"
+        )) {
+          const isGrouped = "group" in item && item.group !== void 0;
+          const groupAlternatives = isGrouped ? this.choices.ingredientGroups.get(item.group) : void 0;
+          let selectedAltIndex = 0;
+          let isSelected = false;
+          let hasExplicitChoice = false;
+          if (isGrouped) {
+            const groupChoice = choices?.ingredientGroups?.get(item.group);
+            hasExplicitChoice = groupChoice !== void 0;
+            const targetIndex = groupChoice ?? 0;
+            isSelected = groupAlternatives?.[targetIndex]?.itemId === item.id;
+          } else {
+            const itemChoice = choices?.ingredientItems?.get(item.id);
+            hasExplicitChoice = itemChoice !== void 0;
+            selectedAltIndex = itemChoice ?? 0;
+            isSelected = true;
+          }
+          const alternative = item.alternatives[selectedAltIndex];
+          if (!alternative || !isSelected) continue;
+          selectedIndices.add(alternative.index);
+          const allAlts = isGrouped ? groupAlternatives : item.alternatives;
+          for (const alt of allAlts) {
+            referencedIndices.add(alt.index);
+          }
+          if (!alternative.itemQuantity) continue;
+          const baseQty = {
+            quantity: alternative.itemQuantity.quantity,
+            ...alternative.itemQuantity.unit && {
+              unit: alternative.itemQuantity.unit
+            }
+          };
+          const quantityEntry = alternative.itemQuantity.equivalents?.length ? { or: [baseQty, ...alternative.itemQuantity.equivalents] } : baseQty;
+          let alternativeRefs;
+          if (!hasExplicitChoice && allAlts.length > 1) {
+            alternativeRefs = allAlts.filter(
+              (alt) => isGrouped ? alt.itemId !== item.id : alt.index !== alternative.index
+            ).map((otherAlt) => {
+              const ref = { index: otherAlt.index };
+              if (otherAlt.itemQuantity) {
+                const altQty = {
+                  quantity: otherAlt.itemQuantity.quantity,
+                  ...otherAlt.itemQuantity.unit && {
+                    unit: otherAlt.itemQuantity.unit.name
+                  },
+                  ...otherAlt.itemQuantity.equivalents && {
+                    equivalents: otherAlt.itemQuantity.equivalents.map(
+                      (eq) => toPlainUnit(eq)
+                    )
+                  }
+                };
+                ref.quantities = [altQty];
+              }
+              return ref;
+            });
+          }
+          const altIndices = getAlternativeSignature(alternativeRefs) ?? "";
+          let signature;
+          if (isGrouped) {
+            const resolvedUnit = resolveUnit(
+              alternative.itemQuantity.unit?.name
+            );
+            signature = `group:${item.group}|${altIndices}|${resolvedUnit.type}`;
+          } else if (altIndices) {
+            const resolvedUnit = resolveUnit(
+              alternative.itemQuantity.unit?.name
+            );
+            signature = `${altIndices}|${resolvedUnit.type}}`;
+          } else {
+            signature = null;
+          }
+          if (!ingredientGroups.has(alternative.index)) {
+            ingredientGroups.set(alternative.index, /* @__PURE__ */ new Map());
+          }
+          const groupsForIng = ingredientGroups.get(alternative.index);
+          if (!groupsForIng.has(signature)) {
+            groupsForIng.set(signature, {
+              quantities: [],
+              alternativeQuantities: /* @__PURE__ */ new Map()
+            });
+          }
+          const group = groupsForIng.get(signature);
+          group.quantities.push(quantityEntry);
+          for (const ref of alternativeRefs ?? []) {
+            if (!group.alternativeQuantities.has(ref.index)) {
+              group.alternativeQuantities.set(ref.index, []);
+            }
+            for (const altQty of ref.quantities ?? []) {
+              const extended = toExtendedUnit({
+                quantity: altQty.quantity,
+                unit: altQty.unit
+              });
+              if (altQty.equivalents?.length) {
+                const eqEntries = [
+                  extended,
+                  ...altQty.equivalents.map((eq) => toExtendedUnit(eq))
+                ];
+                group.alternativeQuantities.get(ref.index).push({ or: eqEntries });
+              } else {
+                group.alternativeQuantities.get(ref.index).push(extended);
+              }
+            }
+          }
+        }
+      }
+    }
+    const result = [];
+    for (let index = 0; index < this.ingredients.length; index++) {
+      if (!referencedIndices.has(index)) continue;
+      const orig = this.ingredients[index];
+      const ing = {
+        name: orig.name,
+        ...orig.preparation && { preparation: orig.preparation },
+        ...orig.flags && { flags: orig.flags },
+        ...orig.extras && { extras: orig.extras }
+      };
+      if (selectedIndices.has(index)) {
+        ing.usedAsPrimary = true;
+        const groupsForIng = ingredientGroups.get(index);
+        if (groupsForIng) {
+          const quantityGroups = [];
+          for (const [, group] of groupsForIng) {
+            const summed = addEquivalentsAndSimplify(
+              group.quantities,
+              this.unitSystem
+            );
+            const flattened = flattenPlainUnitGroup(summed);
+            const alternatives = group.alternativeQuantities.size > 0 ? [...group.alternativeQuantities].map(([altIdx, altQtys]) => ({
+              index: altIdx,
+              ...altQtys.length > 0 && {
+                quantities: flattenPlainUnitGroup(
+                  addEquivalentsAndSimplify(altQtys, this.unitSystem)
+                ).flatMap(
+                  /* v8 ignore next -- item.and branch requires complex nested AND-with-equivalents structure */
+                  (item) => "quantity" in item ? [item] : item.and
+                )
+              }
+            })) : void 0;
+            for (const gq of flattened) {
+              if ("and" in gq) {
+                quantityGroups.push({
+                  and: gq.and,
+                  ...gq.equivalents?.length && {
+                    equivalents: gq.equivalents
+                  },
+                  ...alternatives?.length && { alternatives }
+                });
+              } else {
+                quantityGroups.push({
+                  ...gq,
+                  ...alternatives?.length && { alternatives }
+                });
+              }
+            }
+          }
+          if (quantityGroups.length > 0) {
+            ing.quantities = quantityGroups;
+          }
+        }
+      }
+      result.push(ing);
+    }
+    return result;
+  }
   /**
    * Parses a recipe from a string.
    * @param content - The recipe content to parse.
    */
   parse(content) {
     const cleanContent = content.replace(metadataRegex, "").replace(commentRegex, "").replace(blockCommentRegex, "").trim().split(/\r\n?|\n/);
-    const { metadata, servings } = extractMetadata(content);
+    const { metadata, servings, unitSystem } = extractMetadata(content);
     this.metadata = metadata;
     this.servings = servings;
+    if (unitSystem) _Recipe.unitSystems.set(this, unitSystem);
     let blankLineBefore = true;
     let section = new Section();
     const items = [];
-    let note = "";
+    let noteText = "";
     let inNote = false;
     for (const line of cleanContent) {
       if (line.trim().length === 0) {
         flushPendingItems(section, items);
-        note = flushPendingNote(section, note);
+        flushPendingNote(
+          section,
+          noteText ? this._parseNoteText(noteText) : []
+        );
+        noteText = "";
         blankLineBefore = true;
         inNote = false;
         continue;
       }
       if (line.startsWith("=")) {
         flushPendingItems(section, items);
-        note = flushPendingNote(section, note);
+        flushPendingNote(
+          section,
+          noteText ? this._parseNoteText(noteText) : []
+        );
+        noteText = "";
         if (this.sections.length === 0 && section.isBlank()) {
           section.name = line.replace(/^=+|=+$/g, "").trim();
         } else {
@@ -985,22 +2721,20 @@ var Recipe = class _Recipe {
       }
       if (blankLineBefore && line.startsWith(">")) {
         flushPendingItems(section, items);
-        note = flushPendingNote(section, note);
-        note += line.substring(1).trim();
+        noteText = line.substring(1).trim();
         inNote = true;
         blankLineBefore = false;
         continue;
       }
       if (inNote) {
         if (line.startsWith(">")) {
-          note += " " + line.substring(1).trim();
+          noteText += " " + line.substring(1).trim();
         } else {
-          note += " " + line.trim();
+          noteText += " " + line.trim();
         }
         blankLineBefore = false;
         continue;
       }
-      note = flushPendingNote(section, note);
       let cursor = 0;
       for (const match of line.matchAll(tokensRegex)) {
         const idx = match.index;
@@ -1009,12 +2743,13 @@ var Recipe = class _Recipe {
         }
         const groups = match.groups;
         if (groups.mIngredientName || groups.sIngredientName) {
-          let name = groups.mIngredientName || groups.sIngredientName;
-          const scalableQuantity = (groups.mIngredientQuantityModifier || groups.sIngredientQuantityModifier) !== "=";
-          const quantityRaw = groups.mIngredientQuantity || groups.sIngredientQuantity;
-          const unit = groups.mIngredientUnit || groups.sIngredientUnit;
-          const preparation = groups.mIngredientPreparation || groups.sIngredientPreparation;
-          const modifiers = groups.mIngredientModifiers || groups.sIngredientModifiers;
+          this._parseIngredientWithAlternativeRecursive(match[0], items);
+        } else if (groups.gmIngredientName || groups.gsIngredientName) {
+          this._parseIngredientWithGroupKey(match[0], items);
+        } else if (groups.mCookwareName || groups.sCookwareName) {
+          const name = groups.mCookwareName || groups.sCookwareName;
+          const modifiers = groups.cookwareModifiers;
+          const quantityRaw = groups.cookwareQuantity;
           const reference = modifiers !== void 0 && modifiers.includes("&");
           const flags = [];
           if (modifiers !== void 0 && modifiers.includes("?")) {
@@ -1023,83 +2758,31 @@ var Recipe = class _Recipe {
           if (modifiers !== void 0 && modifiers.includes("-")) {
             flags.push("hidden");
           }
-          if (modifiers !== void 0 && modifiers.includes("@") || groups.mIngredientRecipeAnchor || groups.sIngredientRecipeAnchor) {
-            flags.push("recipe");
-          }
-          let extras = void 0;
-          if (flags.includes("recipe")) {
-            extras = { path: `${name}.cook` };
-            name = name.substring(name.lastIndexOf("/") + 1);
-          }
           const quantity = quantityRaw ? parseQuantityInput(quantityRaw) : void 0;
-          const aliasMatch = name.match(ingredientAliasRegex);
-          let listName, displayName;
-          if (aliasMatch && aliasMatch.groups.ingredientListName.trim().length > 0 && aliasMatch.groups.ingredientDisplayName.trim().length > 0) {
-            listName = aliasMatch.groups.ingredientListName.trim();
-            displayName = aliasMatch.groups.ingredientDisplayName.trim();
-          } else {
-            listName = name;
-            displayName = name;
-          }
-          const newIngredient = {
-            name: listName,
-            quantity,
-            quantityParts: quantity ? [
-              {
-                value: quantity,
-                unit,
-                scalable: scalableQuantity
-              }
-            ] : void 0,
-            unit,
-            preparation,
-            flags
+          const newCookware = {
+            name
           };
-          if (extras) {
-            newIngredient.extras = extras;
+          if (quantity) {
+            newCookware.quantity = quantity;
+          }
+          if (flags.length > 0) {
+            newCookware.flags = flags;
           }
-          const idxsInList = findAndUpsertIngredient(
-            this.ingredients,
-            newIngredient,
+          const idxInList = findAndUpsertCookware(
+            this.cookware,
+            newCookware,
             reference
           );
           const newItem = {
-            type: "ingredient",
-            index: idxsInList.ingredientIndex,
-            displayName
+            type: "cookware",
+            index: idxInList
           };
-          if (idxsInList.quantityPartIndex !== void 0) {
-            newItem.quantityPartIndex = idxsInList.quantityPartIndex;
+          if (quantity) {
+            newItem.quantity = quantity;
           }
           items.push(newItem);
-        } else if (groups.mCookwareName || groups.sCookwareName) {
-          const name = groups.mCookwareName || groups.sCookwareName;
-          const modifiers = groups.mCookwareModifiers || groups.sCookwareModifiers;
-          const quantityRaw = groups.mCookwareQuantity || groups.sCookwareQuantity;
-          const reference = modifiers !== void 0 && modifiers.includes("&");
-          const flags = [];
-          if (modifiers !== void 0 && modifiers.includes("?")) {
-            flags.push("optional");
-          }
-          if (modifiers !== void 0 && modifiers.includes("-")) {
-            flags.push("hidden");
-          }
-          const quantity = quantityRaw ? parseQuantityInput(quantityRaw) : void 0;
-          const idxsInList = findAndUpsertCookware(
-            this.cookware,
-            {
-              name,
-              quantity,
-              quantityParts: quantity ? [quantity] : void 0,
-              flags
-            },
-            reference
-          );
-          items.push({
-            type: "cookware",
-            index: idxsInList.cookwareIndex,
-            quantityPartIndex: idxsInList.quantityPartIndex
-          });
+        } else if (groups.arbitraryQuantity) {
+          this._parseArbitraryScalable(groups, items);
         } else {
           const durationStr = groups.timerQuantity.trim();
           const unit = (groups.timerUnit || "").trim();
@@ -1123,10 +2806,11 @@ var Recipe = class _Recipe {
       blankLineBefore = false;
     }
     flushPendingItems(section, items);
-    note = flushPendingNote(section, note);
+    flushPendingNote(section, noteText ? this._parseNoteText(noteText) : []);
     if (!section.isBlank()) {
       this.sections.push(section);
     }
+    this._populate_ingredient_quantities();
   }
   /**
    * Scales the recipe to a new number of servings. In practice, it calls
@@ -1141,7 +2825,7 @@ var Recipe = class _Recipe {
     if (originalServings === void 0 || originalServings === 0) {
       originalServings = 1;
     }
-    const factor = (0, import_big2.default)(newServings).div(originalServings);
+    const factor = (0, import_big4.default)(newServings).div(originalServings);
     return this.scaleBy(factor);
   }
   /**
@@ -1156,44 +2840,83 @@ var Recipe = class _Recipe {
     if (originalServings === void 0 || originalServings === 0) {
       originalServings = 1;
     }
-    newRecipe.ingredients = newRecipe.ingredients.map((ingredient) => {
-      if (ingredient.quantityParts) {
-        ingredient.quantityParts = ingredient.quantityParts.map(
-          (quantityPart) => {
-            if (quantityPart.value.type === "fixed" && quantityPart.value.value.type === "text") {
-              return quantityPart;
-            }
-            return {
-              ...quantityPart,
-              value: multiplyQuantityValue(
-                quantityPart.value,
-                quantityPart.scalable ? (0, import_big2.default)(factor) : 1
-              )
-            };
+    const unitSystem = this.unitSystem;
+    function scaleAlternativesBy(alternatives, factor2) {
+      for (const alternative of alternatives) {
+        if (alternative.itemQuantity) {
+          const scaleFactor = alternative.itemQuantity.scalable ? (0, import_big4.default)(factor2) : 1;
+          if (alternative.itemQuantity.quantity.type !== "fixed" || alternative.itemQuantity.quantity.value.type !== "text") {
+            alternative.itemQuantity.quantity = multiplyQuantityValue(
+              alternative.itemQuantity.quantity,
+              scaleFactor
+            );
           }
-        );
-        if (ingredient.quantityParts.length === 1) {
-          ingredient.quantity = ingredient.quantityParts[0].value;
-          ingredient.unit = ingredient.quantityParts[0].unit;
-        } else {
-          const totalQuantity = ingredient.quantityParts.reduce(
-            (acc, val) => addQuantities(acc, { value: val.value, unit: val.unit }),
-            { value: getDefaultQuantityValue() }
+          if (alternative.itemQuantity.equivalents) {
+            alternative.itemQuantity.equivalents = alternative.itemQuantity.equivalents.map(
+              (altQuantity) => {
+                if (altQuantity.quantity.type === "fixed" && altQuantity.quantity.value.type === "text") {
+                  return altQuantity;
+                } else {
+                  return {
+                    ...altQuantity,
+                    quantity: multiplyQuantityValue(
+                      altQuantity.quantity,
+                      scaleFactor
+                    )
+                  };
+                }
+              }
+            );
+          }
+          const optimizedPrimary = applyBestUnit(
+            {
+              quantity: alternative.itemQuantity.quantity,
+              unit: alternative.itemQuantity.unit
+            },
+            unitSystem
           );
-          ingredient.quantity = totalQuantity.value;
-          ingredient.unit = totalQuantity.unit;
+          alternative.itemQuantity.quantity = optimizedPrimary.quantity;
+          alternative.itemQuantity.unit = optimizedPrimary.unit;
+          if (alternative.itemQuantity.equivalents) {
+            alternative.itemQuantity.equivalents = alternative.itemQuantity.equivalents.map(
+              (eq) => applyBestUnit(eq, unitSystem)
+            );
+          }
         }
       }
-      return ingredient;
-    }).filter((ingredient) => ingredient.quantity !== null);
-    newRecipe.servings = (0, import_big2.default)(originalServings).times(factor).toNumber();
+    }
+    for (const section of newRecipe.sections) {
+      for (const step of section.content.filter(
+        (item) => item.type === "step"
+      )) {
+        for (const item of step.items.filter(
+          (item2) => item2.type === "ingredient"
+        )) {
+          scaleAlternativesBy(item.alternatives, factor);
+        }
+      }
+    }
+    for (const alternatives of newRecipe.choices.ingredientGroups.values()) {
+      scaleAlternativesBy(alternatives, factor);
+    }
+    for (const alternatives of newRecipe.choices.ingredientItems.values()) {
+      scaleAlternativesBy(alternatives, factor);
+    }
+    for (const arbitrary of newRecipe.arbitraries) {
+      arbitrary.quantity = multiplyQuantityValue(
+        arbitrary.quantity,
+        factor
+      );
+    }
+    newRecipe._populate_ingredient_quantities();
+    newRecipe.servings = (0, import_big4.default)(originalServings).times(factor).toNumber();
     if (newRecipe.metadata.servings && this.metadata.servings) {
       if (floatRegex.test(String(this.metadata.servings).replace(",", ".").trim())) {
         const servingsValue = parseFloat(
           String(this.metadata.servings).replace(",", ".")
         );
         newRecipe.metadata.servings = String(
-          (0, import_big2.default)(servingsValue).times(factor).toNumber()
+          (0, import_big4.default)(servingsValue).times(factor).toNumber()
         );
       }
     }
@@ -1203,7 +2926,7 @@ var Recipe = class _Recipe {
           String(this.metadata.yield).replace(",", ".")
         );
         newRecipe.metadata.yield = String(
-          (0, import_big2.default)(yieldValue).times(factor).toNumber()
+          (0, import_big4.default)(yieldValue).times(factor).toNumber()
         );
       }
     }
@@ -1213,10 +2936,143 @@ var Recipe = class _Recipe {
           String(this.metadata.serves).replace(",", ".")
         );
         newRecipe.metadata.serves = String(
-          (0, import_big2.default)(servesValue).times(factor).toNumber()
+          (0, import_big4.default)(servesValue).times(factor).toNumber()
+        );
+      }
+    }
+    return newRecipe;
+  }
+  /**
+   * Converts all ingredient quantities in the recipe to a target unit system.
+   *
+   * @param system - The target unit system to convert to (metric, US, UK, JP)
+   * @param method - How to handle existing quantities:
+   *   - "keep": Keep all existing equivalents (swap if needed, or add converted)
+   *   - "replace": Replace primary with target system quantity, discard equivalent used for conversion
+   *   - "remove": Only keep target system quantity, delete all equivalents
+   * @returns A new Recipe instance with converted quantities
+   *
+   * @example
+   * ```typescript
+   * // Convert a recipe to metric, keeping original units as equivalents
+   * const metricRecipe = recipe.convertTo("metric", "keep");
+   *
+   * // Convert to US units, removing all other equivalents
+   * const usRecipe = recipe.convertTo("US", "remove");
+   * ```
+   */
+  convertTo(system, method) {
+    const newRecipe = this.clone();
+    function buildNewPrimary(convertedQty, oldPrimary, remainingEquivalents, scalable, integerProtected, source) {
+      const newUnit = integerProtected && convertedQty.unit ? { name: convertedQty.unit.name, integerProtected: true } : convertedQty.unit;
+      const newPrimary = {
+        quantity: convertedQty.quantity,
+        unit: newUnit,
+        scalable
+      };
+      if (method === "remove") {
+        return newPrimary;
+      } else if (method === "replace") {
+        if (remainingEquivalents.length > 0) {
+          newPrimary.equivalents = remainingEquivalents;
+          if (source === "converted") newPrimary.equivalents.push(oldPrimary);
+        }
+      } else {
+        newPrimary.equivalents = [oldPrimary, ...remainingEquivalents];
+      }
+      return newPrimary;
+    }
+    function convertItemQuantity(itemQuantity) {
+      const primaryUnit = resolveUnit(itemQuantity.unit?.name);
+      const equivalents = itemQuantity.equivalents ?? [];
+      const oldPrimary = {
+        quantity: itemQuantity.quantity,
+        unit: itemQuantity.unit
+      };
+      if (primaryUnit.type !== "other" && isUnitCompatibleWithSystem(primaryUnit, system)) {
+        if (method === "remove") {
+          return { ...itemQuantity, equivalents: void 0 };
+        }
+        return itemQuantity;
+      }
+      const targetEquivIndex = equivalents.findIndex((eq) => {
+        const eqUnit = resolveUnit(eq.unit?.name);
+        return eqUnit.type !== "other" && isUnitCompatibleWithSystem(eqUnit, system);
+      });
+      if (targetEquivIndex !== -1) {
+        const targetEquiv = equivalents[targetEquivIndex];
+        const remainingEquivalents = equivalents.filter(
+          (_, i2) => i2 !== targetEquivIndex
         );
+        return buildNewPrimary(
+          targetEquiv,
+          oldPrimary,
+          remainingEquivalents,
+          itemQuantity.scalable,
+          targetEquiv.unit?.integerProtected,
+          "swapped"
+        );
+      }
+      const converted = convertQuantityToSystem(oldPrimary, system);
+      if (converted && converted.unit) {
+        return buildNewPrimary(
+          converted,
+          oldPrimary,
+          equivalents,
+          itemQuantity.scalable,
+          itemQuantity.unit?.integerProtected,
+          "swapped"
+        );
+      }
+      for (let i2 = 0; i2 < equivalents.length; i2++) {
+        const equiv = equivalents[i2];
+        const convertedEquiv = convertQuantityToSystem(equiv, system);
+        if (convertedEquiv && convertedEquiv.unit) {
+          const remainingEquivalents = method === "keep" ? equivalents : equivalents.filter((_, idx) => idx !== i2);
+          return buildNewPrimary(
+            convertedEquiv,
+            oldPrimary,
+            remainingEquivalents,
+            itemQuantity.scalable,
+            equiv.unit?.integerProtected,
+            "converted"
+          );
+        }
+      }
+      if (method === "remove") {
+        return { ...itemQuantity, equivalents: void 0 };
+      } else {
+        return itemQuantity;
+      }
+    }
+    function convertAlternatives(alternatives) {
+      for (const alternative of alternatives) {
+        if (alternative.itemQuantity) {
+          alternative.itemQuantity = convertItemQuantity(
+            alternative.itemQuantity
+          );
+        }
       }
     }
+    for (const section of newRecipe.sections) {
+      for (const step of section.content.filter(
+        (item) => item.type === "step"
+      )) {
+        for (const item of step.items.filter(
+          (item2) => item2.type === "ingredient"
+        )) {
+          convertAlternatives(item.alternatives);
+        }
+      }
+    }
+    for (const alternatives of newRecipe.choices.ingredientGroups.values()) {
+      convertAlternatives(alternatives);
+    }
+    for (const alternatives of newRecipe.choices.ingredientItems.values()) {
+      convertAlternatives(alternatives);
+    }
+    newRecipe._populate_ingredient_quantities();
+    if (method !== "keep") _Recipe.unitSystems.set(newRecipe, system);
     return newRecipe;
   }
   /**
@@ -1236,19 +3092,33 @@ var Recipe = class _Recipe {
    */
   clone() {
     const newRecipe = new _Recipe();
-    newRecipe.metadata = JSON.parse(JSON.stringify(this.metadata));
-    newRecipe.ingredients = JSON.parse(
-      JSON.stringify(this.ingredients)
-    );
-    newRecipe.sections = JSON.parse(JSON.stringify(this.sections));
-    newRecipe.cookware = JSON.parse(
-      JSON.stringify(this.cookware)
-    );
-    newRecipe.timers = JSON.parse(JSON.stringify(this.timers));
+    newRecipe.choices = deepClone(this.choices);
+    _Recipe.itemCounts.set(newRecipe, this.getItemCount());
+    newRecipe.metadata = deepClone(this.metadata);
+    newRecipe.ingredients = deepClone(this.ingredients);
+    newRecipe.sections = this.sections.map((section) => {
+      const newSection = new Section(section.name);
+      newSection.content = deepClone(section.content);
+      return newSection;
+    });
+    newRecipe.cookware = deepClone(this.cookware);
+    newRecipe.timers = deepClone(this.timers);
+    newRecipe.arbitraries = deepClone(this.arbitraries);
     newRecipe.servings = this.servings;
     return newRecipe;
   }
 };
+/**
+ * External storage for unit system (not a property on instances).
+ * Used for resolving ambiguous units during quantity addition.
+ */
+__publicField(_Recipe, "unitSystems", /* @__PURE__ */ new WeakMap());
+/**
+ * External storage for item count (not a property on instances).
+ * Used for giving ID numbers to items during parsing.
+ */
+__publicField(_Recipe, "itemCounts", /* @__PURE__ */ new WeakMap());
+var Recipe = _Recipe;
 
 // src/classes/shopping_list.ts
 var ShoppingList = class {
@@ -1257,6 +3127,7 @@ var ShoppingList = class {
    * @param category_config_str - The category configuration to parse.
    */
   constructor(category_config_str) {
+    // TODO: backport type change
     /**
      * The ingredients in the shopping list.
      */
@@ -1279,6 +3150,33 @@ var ShoppingList = class {
   }
   calculate_ingredients() {
     this.ingredients = [];
+    const addIngredientQuantity = (name, quantityTotal) => {
+      const quantityTotalExtended = extendAllUnits(quantityTotal);
+      const newQuantities = isAndGroup(quantityTotalExtended) ? quantityTotalExtended.and : [quantityTotalExtended];
+      const existing = this.ingredients.find((i2) => i2.name === name);
+      if (existing) {
+        if (!existing.quantityTotal) {
+          existing.quantityTotal = quantityTotal;
+          return;
+        }
+        try {
+          const existingQuantityTotalExtended = extendAllUnits(
+            existing.quantityTotal
+          );
+          const existingQuantities = isAndGroup(existingQuantityTotalExtended) ? existingQuantityTotalExtended.and : [existingQuantityTotalExtended];
+          existing.quantityTotal = addEquivalentsAndSimplify([
+            ...existingQuantities,
+            ...newQuantities
+          ]);
+          return;
+        } catch {
+        }
+      }
+      this.ingredients.push({
+        name,
+        quantityTotal
+      });
+    };
     for (const addedRecipe of this.recipes) {
       let scaledRecipe;
       if ("factor" in addedRecipe) {
@@ -1287,67 +3185,123 @@ var ShoppingList = class {
       } else {
         scaledRecipe = addedRecipe.recipe.scaleTo(addedRecipe.servings);
       }
-      for (const ingredient of scaledRecipe.ingredients) {
+      const ingredients = scaledRecipe.getIngredientQuantities({
+        choices: addedRecipe.choices
+      });
+      for (const ingredient of ingredients) {
         if (ingredient.flags && ingredient.flags.includes("hidden")) {
           continue;
         }
-        const existingIngredient = this.ingredients.find(
-          (i2) => i2.name === ingredient.name
-        );
-        let addSeparate = false;
-        try {
-          if (existingIngredient && ingredient.quantity) {
-            if (existingIngredient.quantity) {
-              const newQuantity = addQuantities(
-                {
-                  value: existingIngredient.quantity,
-                  unit: existingIngredient.unit ?? ""
-                },
-                {
-                  value: ingredient.quantity,
-                  unit: ingredient.unit ?? ""
-                }
-              );
-              existingIngredient.quantity = newQuantity.value;
-              if (newQuantity.unit) {
-                existingIngredient.unit = newQuantity.unit;
+        if (!ingredient.usedAsPrimary) {
+          continue;
+        }
+        if (ingredient.quantities && ingredient.quantities.length > 0) {
+          const allQuantities = [];
+          for (const qGroup of ingredient.quantities) {
+            if ("and" in qGroup) {
+              for (const qty of qGroup.and) {
+                allQuantities.push(qty);
               }
             } else {
-              existingIngredient.quantity = ingredient.quantity;
-              if (ingredient.unit) {
-                existingIngredient.unit = ingredient.unit;
-              }
+              const plainQty = {
+                quantity: qGroup.quantity
+              };
+              if (qGroup.unit) plainQty.unit = qGroup.unit;
+              if (qGroup.equivalents) plainQty.equivalents = qGroup.equivalents;
+              allQuantities.push(plainQty);
             }
           }
-        } catch {
-          addSeparate = true;
-        }
-        if (!existingIngredient || addSeparate) {
-          const newIngredient = { name: ingredient.name };
-          if (ingredient.quantity) {
-            newIngredient.quantity = ingredient.quantity;
-          }
-          if (ingredient.unit) {
-            newIngredient.unit = ingredient.unit;
+          if (allQuantities.length === 1) {
+            addIngredientQuantity(ingredient.name, allQuantities[0]);
+          } else {
+            const extendedQuantities = allQuantities.map(
+              (q) => extendAllUnits(q)
+            );
+            const totalQuantity = addEquivalentsAndSimplify(
+              extendedQuantities
+            );
+            addIngredientQuantity(ingredient.name, totalQuantity);
           }
-          this.ingredients.push(newIngredient);
+        } else if (!this.ingredients.some((i2) => i2.name === ingredient.name)) {
+          this.ingredients.push({ name: ingredient.name });
         }
       }
     }
   }
-  add_recipe(recipe, scaling) {
-    if (typeof scaling === "number" || scaling === void 0) {
-      this.recipes.push({ recipe, factor: scaling ?? 1 });
+  /**
+   * Adds a recipe to the shopping list, then automatically
+   * recalculates the quantities and recategorize the ingredients.
+   * @param recipe - The recipe to add.
+   * @param options - Options for adding the recipe.
+   * @throws Error if the recipe has alternatives without corresponding choices.
+   */
+  add_recipe(recipe, options = {}) {
+    const errorMessage = this.getUnresolvedAlternativesError(
+      recipe,
+      options.choices
+    );
+    if (errorMessage) {
+      throw new Error(errorMessage);
+    }
+    if (!options.scaling) {
+      this.recipes.push({
+        recipe,
+        factor: options.scaling ?? 1,
+        choices: options.choices
+      });
     } else {
-      if ("factor" in scaling) {
-        this.recipes.push({ recipe, factor: scaling.factor });
+      if ("factor" in options.scaling) {
+        this.recipes.push({
+          recipe,
+          factor: options.scaling.factor,
+          choices: options.choices
+        });
       } else {
-        this.recipes.push({ recipe, servings: scaling.servings });
+        this.recipes.push({
+          recipe,
+          servings: options.scaling.servings,
+          choices: options.choices
+        });
       }
     }
     this.calculate_ingredients();
     this.categorize();
   }
+  /**
+   * Checks if a recipe has unresolved alternatives (alternatives without provided choices).
+   * @param recipe - The recipe to check.
+   * @param choices - The choices provided for the recipe.
+   * @returns An error message if there are unresolved alternatives, undefined otherwise.
+   */
+  getUnresolvedAlternativesError(recipe, choices) {
+    const missingItems = [];
+    const missingGroups = [];
+    for (const itemId of recipe.choices.ingredientItems.keys()) {
+      if (!choices?.ingredientItems?.has(itemId)) {
+        missingItems.push(itemId);
+      }
+    }
+    for (const groupId of recipe.choices.ingredientGroups.keys()) {
+      if (!choices?.ingredientGroups?.has(groupId)) {
+        missingGroups.push(groupId);
+      }
+    }
+    if (missingItems.length === 0 && missingGroups.length === 0) {
+      return void 0;
+    }
+    const parts = [];
+    if (missingItems.length > 0) {
+      parts.push(
+        `ingredientItems: [${missingItems.map((i2) => `'${i2}'`).join(", ")}]`
+      );
+    }
+    if (missingGroups.length > 0) {
+      parts.push(
+        `ingredientGroups: [${missingGroups.map((g) => `'${g}'`).join(", ")}]`
+      );
+    }
+    return `Recipe has unresolved alternatives. Missing choices for: ${parts.join(", ")}`;
+  }
   /**
    * Removes a recipe from the shopping list, then automatically
    * recalculates the quantities and recategorize the ingredients.s
@@ -1407,15 +3361,384 @@ var ShoppingList = class {
     this.categories = categories;
   }
 };
+
+// src/classes/shopping_cart.ts
+var import_yalps = require("yalps");
+var ShoppingCart = class {
+  /**
+   * Creates a new ShoppingCart instance
+   * @param options - {@link ShoppingCartOptions | Options} for the constructor
+   */
+  constructor(options) {
+    /**
+     * The product catalog to use for matching products
+     */
+    __publicField(this, "productCatalog");
+    /**
+     * The shopping list to build the cart from
+     */
+    __publicField(this, "shoppingList");
+    /**
+     * The content of the cart
+     */
+    __publicField(this, "cart", []);
+    /**
+     * The ingredients that were successfully matched with products
+     */
+    __publicField(this, "match", []);
+    /**
+     * The ingredients that could not be matched with products
+     */
+    __publicField(this, "misMatch", []);
+    /**
+     * Key information about the shopping cart
+     */
+    __publicField(this, "summary");
+    if (options?.catalog) this.productCatalog = options.catalog;
+    if (options?.list) this.shoppingList = options.list;
+    this.summary = { totalPrice: 0, totalItems: 0 };
+  }
+  /**
+   * Sets the product catalog to use for matching products
+   * To use if a catalog was not provided at the creation of the instance
+   * @param catalog - The {@link ProductCatalog} to set
+   */
+  setProductCatalog(catalog) {
+    this.productCatalog = catalog;
+  }
+  // TODO: harmonize recipe name to use underscores
+  /**
+   * Sets the shopping list to build the cart from.
+   * To use if a shopping list was not provided at the creation of the instance
+   * @param list - The {@link ShoppingList} to set
+   */
+  setShoppingList(list) {
+    this.shoppingList = list;
+  }
+  /**
+   * Builds the cart from the shopping list and product catalog
+   * @remarks
+   * - If a combination of product(s) is successfully found for a given ingredient, the latter will be listed in the {@link ShoppingCart.match | match} array
+   * in addition to that combination being added to the {@link ShoppingCart.cart | cart}.
+   * - Otherwise, the latter will be listed in the {@link ShoppingCart.misMatch | misMatch} array. Possible causes can be:
+   *   - No product is listed in the catalog for that ingredient
+   *   - The ingredient has no quantity, a text quantity
+   *   - The ingredient's quantity unit is incompatible with the units of the candidate products listed in the catalog
+   * @throws {@link NoProductCatalogForCartError} if no product catalog is set
+   * @throws {@link NoShoppingListForCartError} if no shopping list is set
+   * @returns `true` if all ingredients in the shopping list have been matched to products in the catalog, or `false` otherwise
+   */
+  buildCart() {
+    this.resetCart();
+    if (this.productCatalog === void 0) {
+      throw new NoProductCatalogForCartError();
+    } else if (this.shoppingList === void 0) {
+      throw new NoShoppingListForCartError();
+    }
+    for (const ingredient of this.shoppingList.ingredients) {
+      const productOptions = this.getProductOptions(ingredient);
+      try {
+        const optimumMatch = this.getOptimumMatch(ingredient, productOptions);
+        this.cart.push(...optimumMatch);
+        this.match.push({ ingredient, selection: optimumMatch });
+      } catch (error) {
+        if (error instanceof NoProductMatchError) {
+          this.misMatch.push({ ingredient, reason: error.code });
+        }
+      }
+    }
+    this.summarize();
+    return this.misMatch.length > 0;
+  }
+  /**
+   * Gets the product options for a given ingredient
+   * @param ingredient - The ingredient to get the product options for
+   * @returns An array of {@link ProductOption}
+   */
+  getProductOptions(ingredient) {
+    return this.productCatalog.products.filter(
+      (product) => product.ingredientName === ingredient.name || product.ingredientAliases?.includes(ingredient.name)
+    );
+  }
+  /**
+   * Gets the optimum match for a given ingredient and product option
+   * @param ingredient - The ingredient to match
+   * @param options - The product options to choose from
+   * @returns An array of {@link ProductSelection}
+   * @throws {@link NoProductMatchError} if no match can be found
+   */
+  getOptimumMatch(ingredient, options) {
+    if (options.length === 0)
+      throw new NoProductMatchError(ingredient.name, "noProduct");
+    if (!ingredient.quantityTotal)
+      throw new NoProductMatchError(ingredient.name, "noQuantity");
+    const normalizedOptions = options.map(
+      (option) => ({
+        ...option,
+        sizes: option.sizes.map((s) => {
+          const resolvedUnit = resolveUnit(s.unit);
+          return {
+            size: resolvedUnit && "toBase" in resolvedUnit ? multiplyQuantityValue(
+              s.size,
+              resolvedUnit.toBase
+            ) : s.size,
+            unit: resolvedUnit
+          };
+        })
+      })
+    );
+    const normalizedQuantityTotal = normalizeAllUnits(ingredient.quantityTotal);
+    function getOptimumMatchForQuantityParts(normalizedQuantities, normalizedOptions2, selection = []) {
+      if (isAndGroup(normalizedQuantities)) {
+        for (const q of normalizedQuantities.and) {
+          const result = getOptimumMatchForQuantityParts(
+            q,
+            normalizedOptions2,
+            selection
+          );
+          selection.push(...result);
+        }
+      } else {
+        const alternativeUnitsOfQuantity = isOrGroup(normalizedQuantities) ? normalizedQuantities.or : [normalizedQuantities];
+        const solutions = [];
+        const errors = /* @__PURE__ */ new Set();
+        for (const alternative of alternativeUnitsOfQuantity) {
+          if (alternative.quantity.type === "fixed" && alternative.quantity.value.type === "text") {
+            errors.add("textValue");
+            continue;
+          }
+          const scaledQuantity = multiplyQuantityValue(
+            alternative.quantity,
+            "toBase" in alternative.unit ? alternative.unit.toBase : 1
+          );
+          alternative.quantity = scaledQuantity;
+          const matchOptions = normalizedOptions2.filter(
+            (option) => option.sizes.some(
+              (s) => areUnitsGroupable(alternative.unit, s.unit)
+            )
+          );
+          if (matchOptions.length > 0) {
+            const findCompatibleSize = (option) => option.sizes.find(
+              (s) => areUnitsGroupable(alternative.unit, s.unit)
+            );
+            if (matchOptions.length == 1) {
+              const matchedOption = matchOptions[0];
+              const compatibleSize = findCompatibleSize(matchedOption);
+              const product = options.find(
+                (opt) => opt.id === matchedOption.id
+              );
+              const targetQuantity = scaledQuantity.type === "fixed" ? scaledQuantity.value : scaledQuantity.min;
+              const resQuantity = Math.ceil(
+                getNumericValue(targetQuantity) / getNumericValue(compatibleSize.size.value)
+              );
+              solutions.push([
+                {
+                  product,
+                  quantity: resQuantity,
+                  totalPrice: resQuantity * matchedOption.price
+                }
+              ]);
+              continue;
+            }
+            const model = {
+              direction: "minimize",
+              objective: "price",
+              integers: true,
+              constraints: {
+                size: {
+                  min: scaledQuantity.type === "fixed" ? getNumericValue(scaledQuantity.value) : getNumericValue(scaledQuantity.min)
+                }
+              },
+              variables: matchOptions.reduce(
+                (acc, option) => {
+                  const compatibleSize = findCompatibleSize(option);
+                  acc[option.id] = {
+                    price: option.price,
+                    size: getNumericValue(compatibleSize.size.value)
+                  };
+                  return acc;
+                },
+                {}
+              )
+            };
+            const solution = (0, import_yalps.solve)(model);
+            solutions.push(
+              solution.variables.map((variable) => {
+                const resProductSelection = {
+                  product: options.find((option) => option.id === variable[0]),
+                  quantity: variable[1]
+                };
+                return {
+                  ...resProductSelection,
+                  totalPrice: resProductSelection.quantity * resProductSelection.product.price
+                };
+              })
+            );
+          } else {
+            errors.add("incompatibleUnits");
+          }
+        }
+        if (solutions.length === 0) {
+          throw new NoProductMatchError(
+            ingredient.name,
+            errors.size === 1 ? errors.values().next().value : "textValue_incompatibleUnits"
+          );
+        } else {
+          return solutions.sort(
+            (a2, b) => a2.reduce((acc, item) => acc + item.totalPrice, 0) - b.reduce((acc, item) => acc + item.totalPrice, 0)
+          )[0];
+        }
+      }
+      return selection;
+    }
+    return getOptimumMatchForQuantityParts(
+      normalizedQuantityTotal,
+      normalizedOptions
+    );
+  }
+  /**
+   * Reset the cart's properties
+   */
+  resetCart() {
+    this.cart = [];
+    this.match = [];
+    this.misMatch = [];
+    this.summary = { totalPrice: 0, totalItems: 0 };
+  }
+  /**
+   * Calculate the cart's key info and store it in the cart's {@link ShoppingCart.summary | summary} property.
+   * This function is automatically invoked by {@link ShoppingCart.buildCart | buildCart() } method.
+   * @returns the total price and number of items in the cart
+   */
+  summarize() {
+    this.summary.totalPrice = this.cart.reduce(
+      (acc, item) => acc + item.totalPrice,
+      0
+    );
+    this.summary.totalItems = this.cart.length;
+    return this.summary;
+  }
+};
+
+// src/utils/render_helpers.ts
+var VULGAR_FRACTIONS = {
+  "1/2": "\xBD",
+  "1/3": "\u2153",
+  "2/3": "\u2154",
+  "1/4": "\xBC",
+  "3/4": "\xBE",
+  "1/8": "\u215B",
+  "3/8": "\u215C",
+  "5/8": "\u215D",
+  "7/8": "\u215E"
+};
+function renderFractionAsVulgar(num, den) {
+  const wholePart = Math.floor(num / den);
+  const remainder = num % den;
+  if (remainder === 0) {
+    return String(wholePart);
+  }
+  const fractionKey = `${remainder}/${den}`;
+  const vulgar = VULGAR_FRACTIONS[fractionKey];
+  if (wholePart > 0) {
+    return vulgar ? `${wholePart}${vulgar}` : `${wholePart} ${remainder}/${den}`;
+  }
+  return vulgar ?? `${num}/${den}`;
+}
+function formatNumericValue(value, useVulgar = true) {
+  if (value.type === "decimal") {
+    return String(value.decimal);
+  }
+  if (useVulgar) {
+    return renderFractionAsVulgar(value.num, value.den);
+  }
+  return `${value.num}/${value.den}`;
+}
+function formatSingleValue(value) {
+  if (value.type === "text") {
+    return value.text;
+  }
+  return formatNumericValue(value);
+}
+function formatQuantity(quantity) {
+  if (quantity.type === "fixed") {
+    return formatSingleValue(quantity.value);
+  }
+  const minStr = formatNumericValue(quantity.min);
+  const maxStr = formatNumericValue(quantity.max);
+  return `${minStr}-${maxStr}`;
+}
+function formatUnit(unit) {
+  if (!unit) return "";
+  if (typeof unit === "string") return unit;
+  return unit.name;
+}
+function formatQuantityWithUnit(quantity, unit) {
+  if (!quantity) return "";
+  const qty = formatQuantity(quantity);
+  const unitStr = formatUnit(unit);
+  return unitStr ? `${qty} ${unitStr}` : qty;
+}
+function formatExtendedQuantity(item) {
+  return formatQuantityWithUnit(item.quantity, item.unit);
+}
+function formatItemQuantity(itemQuantity, separator = " | ") {
+  const parts = [];
+  parts.push(formatExtendedQuantity(itemQuantity));
+  if (itemQuantity.equivalents) {
+    for (const eq of itemQuantity.equivalents) {
+      parts.push(formatExtendedQuantity(eq));
+    }
+  }
+  return parts.join(separator);
+}
+function isGroupedItem(item) {
+  return item.group !== void 0;
+}
+function isAlternativeSelected(recipe, choices, item, alternativeIndex) {
+  if (item.group) {
+    const selectedIndex2 = choices?.ingredientGroups?.get(item.group);
+    const groupAlternatives = recipe.choices.ingredientGroups.get(item.group);
+    if (groupAlternatives && selectedIndex2 !== void 0 && selectedIndex2 < groupAlternatives.length) {
+      const selectedItemId = groupAlternatives[selectedIndex2]?.itemId;
+      return selectedItemId === item.id;
+    }
+    return false;
+  }
+  const selectedIndex = choices?.ingredientItems?.get(item.id);
+  return alternativeIndex === selectedIndex;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CategoryConfig,
+  NoProductCatalogForCartError,
+  NoShoppingListForCartError,
+  ProductCatalog,
   Recipe,
   Section,
-  ShoppingList
+  ShoppingCart,
+  ShoppingList,
+  convertQuantityToSystem,
+  formatExtendedQuantity,
+  formatItemQuantity,
+  formatNumericValue,
+  formatQuantity,
+  formatQuantityWithUnit,
+  formatSingleValue,
+  formatUnit,
+  hasAlternatives,
+  isAlternativeSelected,
+  isAndGroup,
+  isGroupedItem,
+  isSimpleGroup,
+  renderFractionAsVulgar
 });
 /* v8 ignore else -- @preserve */
-/* v8 ignore else -- expliciting error types -- @preserve */
+/* v8 ignore next -- @preserve: defensive fallback for ambiguous units without toBaseBySystem */
+/* v8 ignore start -- @preserve: defensive fallback that shouldn't happen with valid inputs */
+// v8 ignore else -- @preserve
+// v8 ignore if -- @preserve
 /* v8 ignore else -- expliciting error type -- @preserve */
-/* v8 ignore else -- only set unit if it is given -- @preserve */
+/* v8 ignore if -- @preserve */
+// v8 ignore next -- @preserve
 //# sourceMappingURL=index.cjs.map