@tmlmt/cooklang-parser 3.0.0-alpha.8 → 3.0.0-elpha.22

package/dist/index.js

@@ -63,7 +63,7 @@ var CategoryConfig = class {
   }
 };
 
-// src/classes/product_catalog.ts
+// src/classes/pantry.ts
 import TOML from "smol-toml";
 
 // node_modules/.pnpm/human-regex@2.2.0/node_modules/human-regex/dist/human-regex.esm.js
@@ -265,14 +265,19 @@ var i = (() => {
 })();
 
 // src/regex.ts
+var metadataKeyRegex = /^([^:\n]+?):/gm;
+var numericValueRegex = /^-?\d+(\.\d+)?$/;
+var nestedMetaVarRegex = (varName) => new RegExp(
+  `^${varName}:\\s*\\r?\\n((?:[ ]+.+(?:\\r?\\n|$))+)`,
+  "m"
+);
 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 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 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().startGroup().literal("/").startNamedGroup("gIngredientSubgroupKey").notAnyOf(nonWordCharStrict).oneOrMore().endGroup().endGroup().optional().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().startGroup().literal("[").startNamedGroup("gIngredientNote").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 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();
@@ -287,12 +292,58 @@ var tokensRegex = new RegExp(
   ].map((r2) => r2.source).join("|"),
   "gu"
 );
+var yieldPrefixPart = d().startAnchor().literal("yield").literal(":").anyOf("	 ").zeroOrMore().startNamedGroup("servingsPrefix").nonWhitespace().startGroup().anyCharacter().zeroOrMore().lazy().nonWhitespace().endGroup().optional().endGroup().optional().anyOf("	 ").zeroOrMore().toRegExp();
+var yieldSuffixPart = d().anyOf("	 ").zeroOrMore().startNamedGroup("servingsSuffix").nonWhitespace().startGroup().anyCharacter().zeroOrMore().nonWhitespace().endGroup().optional().endGroup().optional().anyOf("	 ").zeroOrMore().endAnchor().toRegExp();
+var yieldMetaValueWithUnitRegex = new RegExp(
+  yieldPrefixPart.source + arbitraryScalableRegex.source + yieldSuffixPart.source,
+  "m"
+);
+var yieldMetaValueAsQuantityRegex = d().startAnchor().literal("yield:").anyOf("	 ").zeroOrMore().startNamedGroup("quantity").notAnyOf("{}|%\\n\\r").oneOrMore().endGroup().optional().startGroup().literal("%").startNamedGroup("unit").notAnyOf("\\n\\r|}").oneOrMore().endGroup().endGroup().optional().anyOf("	 ").zeroOrMore().endAnchor().toRegExp();
+var yieldMetaValueRegex = new RegExp(
+  [
+    yieldMetaValueWithUnitRegex.source,
+    yieldMetaValueAsQuantityRegex.source
+  ].join("|"),
+  "m"
+);
 var commentRegex = d().literal("--").anyCharacter().zeroOrMore().global().toRegExp();
 var blockCommentRegex = d().literal("[-").anyCharacter().zeroOrMore().lazy().literal("-]").whitespace().zeroOrMore().global().toRegExp();
 var shoppingListRegex = d().literal("[").startNamedGroup("name").anyCharacter().oneOrMore().endGroup().literal("]").newline().startNamedGroup("items").anyCharacter().zeroOrMore().lazy().endGroup().startGroup().newline().newline().or().endAnchor().endGroup().global().toRegExp();
 var rangeRegex = d().startAnchor().digit().oneOrMore().startGroup().anyOf(".,/").exactly(1).digit().oneOrMore().endGroup().optional().literal("-").digit().oneOrMore().startGroup().anyOf(".,/").exactly(1).digit().oneOrMore().endGroup().optional().endAnchor().toRegExp();
 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();
+var variantTagRegex = d().startAnchor().literal("[").startNamedGroup("variantOptionalPrefix").literal("?").endGroup().optional().startNamedGroup("variantNames").notAnyOf("\\]").oneOrMore().endGroup().optional().literal("]").whitespace().zeroOrMore().toRegExp();
+var mdEscaped = d().literal("\\").startCaptureGroup().anyOf("*_`").endGroup();
+var mdInlineCode = d().literal("`").startCaptureGroup().notAnyOf("`").oneOrMore().lazy().endGroup().literal("`");
+var mdLink = d().literal("[").startCaptureGroup().notAnyOf("\\]").oneOrMore().lazy().endGroup().literal("](").startCaptureGroup().notAnyOf(")").oneOrMore().lazy().endGroup().literal(")");
+var mdTripleAsterisk = d().literal("***").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("***");
+var mdTripleUnderscore = d().literal("___").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("___");
+var mdBoldAstItalicUnd = d().literal("**_").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("_**");
+var mdBoldUndItalicAst = d().literal("__*").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("*__");
+var mdItalicAstBoldUnd = d().literal("*__").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("__*");
+var mdItalicUndBoldAst = d().literal("_**").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("**_");
+var mdBoldAsterisk = d().literal("**").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("**");
+var mdBoldUnderscore = d().wordBoundary().literal("__").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("__").wordBoundary();
+var mdItalicAsterisk = d().literal("*").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("*");
+var mdItalicUnderscore = d().wordBoundary().literal("_").startCaptureGroup().anyCharacter().oneOrMore().lazy().endGroup().literal("_").wordBoundary();
+var markdownRegex = new RegExp(
+  [
+    mdEscaped,
+    mdInlineCode,
+    mdLink,
+    mdTripleAsterisk,
+    mdTripleUnderscore,
+    mdBoldAstItalicUnd,
+    mdBoldUndItalicAst,
+    mdItalicAstBoldUnd,
+    mdItalicUndBoldAst,
+    mdBoldAsterisk,
+    mdBoldUnderscore,
+    mdItalicAsterisk,
+    mdItalicUnderscore
+  ].map((r2) => r2.toRegExp().source).join("|"),
+  "g"
+);
 
 // src/units/definitions.ts
 var units = [
@@ -302,7 +353,8 @@ var units = [
     type: "mass",
     system: "metric",
     aliases: ["gram", "grams", "grammes"],
-    toBase: 1
+    toBase: 1,
+    maxValue: 999
   },
   {
     name: "kg",
@@ -311,20 +363,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)
   {
@@ -332,21 +392,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",
@@ -355,55 +420,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)
   {
@@ -411,7 +523,8 @@ var units = [
     type: "count",
     system: "metric",
     aliases: ["pieces", "pc"],
-    toBase: 1
+    toBase: 1,
+    maxValue: 999
   }
 ];
 var unitMap = /* @__PURE__ */ new Map();
@@ -435,8 +548,14 @@ function isNoUnit(unit) {
   return resolveUnit(unit.name).name === NO_UNIT;
 }
 
+// src/units/conversion.ts
+import Big2 from "big.js";
+
 // src/quantities/numeric.ts
 import Big from "big.js";
+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);
 }
@@ -457,6 +576,41 @@ function simplifyFraction(num, den) {
     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;
@@ -505,9 +659,35 @@ function addNumericValues(val1, val2) {
     };
   }
 }
-var toRoundedDecimal = (v) => {
+var toRoundedDecimal = (v, precision = 3) => {
   const value = v.type === "decimal" ? v.decimal : v.num / v.den;
-  return { type: "decimal", decimal: Math.round(value * 1e3) / 1e3 };
+  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") {
@@ -541,6 +721,143 @@ function getAverageValue(q) {
   }
 }
 
+// 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 Big2(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) {
@@ -571,7 +888,7 @@ 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",
+      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`
@@ -610,20 +927,37 @@ var InvalidQuantityFormat = class extends Error {
     this.name = "InvalidQuantityFormat";
   }
 };
+var NoTabAsIndentError = class extends Error {
+  constructor() {
+    super(
+      `Tabs are not allowed for indentation in metadata blocks. Please use spaces only.`
+    );
+    this.name = "NoTabAsIndentError";
+  }
+};
+var BadIndentationError = class extends Error {
+  constructor() {
+    super(`Bad identation of a nested block. Please use spaces only.`);
+    this.name = "BadIndentationError";
+  }
+};
 
 // src/utils/type_guards.ts
 function isGroup(x) {
-  return x && "type" in x;
+  return "and" in x || "or" in x;
 }
 function isOrGroup(x) {
-  return isGroup(x) && x.type === "or";
+  return isGroup(x) && "or" in x;
 }
 function isAndGroup(x) {
-  return isGroup(x) && x.type === "and";
+  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;
@@ -635,37 +969,32 @@ function isValueIntegerLike(q) {
   }
   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 (isGroup(q)) {
-    return { ...q, entries: q.entries.map(extendAllUnits) };
-  } else {
-    const newQ = {
-      quantity: q.quantity
-    };
-    if (q.unit) {
-      newQ.unit = { name: q.unit };
-    }
-    return newQ;
-  }
-}
 function normalizeAllUnits(q) {
-  if (isGroup(q)) {
-    return { ...q, entries: q.entries.map(normalizeAllUnits) };
+  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;
   }
 }
-var convertQuantityValue = (value, def, targetDef) => {
-  if (def.name === targetDef.name) return value;
-  const factor = def.toBase / targetDef.toBase;
-  return multiplyQuantityValue(value, factor);
-};
 function getDefaultQuantityValue() {
   return { type: "fixed", value: { type: "decimal", decimal: 0 } };
 }
@@ -692,7 +1021,7 @@ function addQuantityValues(v1, v2) {
   );
   return { type: "range", min: newMin, max: newMax };
 }
-function addQuantities(q1, q2) {
+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") {
@@ -710,55 +1039,149 @@ function addQuantities(q1, q2) {
   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.name.toLowerCase() === q2.unit.name.toLowerCase()) {
+  if (!q1.unit && !q2.unit) {
+    return addQuantityValuesAndSetUnit(v1, v2, q1.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
+      ]);
+    }
     return addQuantityValuesAndSetUnit(v1, v2, q1.unit);
   }
   if (unit1Def && unit2Def) {
-    if (unit1Def.type !== unit2Def.type) {
+    if (!areUnitsConvertible(unit1Def, unit2Def)) {
       throw new IncompatibleUnitsError(
         `${unit1Def.type} (${q1.unit?.name})`,
         `${unit2Def.type} (${q2.unit?.name})`
       );
     }
-    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;
+    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 {
+          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";
+        }
+      }
     }
-    const convertedV1 = convertQuantityValue(v1, unit1Def, targetUnitDef);
-    const convertedV2 = convertQuantityValue(v2, unit2Def, targetUnitDef);
-    const targetUnit = { name: targetUnitDef.name };
-    return addQuantityValuesAndSetUnit(convertedV1, convertedV2, targetUnit);
+    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 {
+      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 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 {
+  else if (isOrGroup(quantity)) {
+    return {
+      or: quantity.or.map(toPlainUnit)
+    };
+  } else {
     return {
-      ...quantity,
-      entries: quantity.entries.map(toPlainUnit)
+      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 {
-      ...q,
-      entries: q.entries.map(
-        (entry) => isQuantity(entry) ? toExtendedUnit(entry) : toExtendedUnit(entry)
-      )
-    };
+    return { and: q.and.map(toExtendedUnit) };
   }
 }
 function deNormalizeQuantity(q) {
@@ -772,26 +1195,24 @@ function deNormalizeQuantity(q) {
 }
 var flattenPlainUnitGroup = (summed) => {
   if (isOrGroup(summed)) {
-    const entries = summed.entries;
+    const entries = summed.or;
     const andGroupEntry = entries.find(
-      (e2) => isGroup(e2) && e2.type === "and"
+      (e2) => isAndGroup(e2)
     );
     if (andGroupEntry) {
       const andEntries = [];
-      for (const entry of andGroupEntry.entries) {
-        if (isQuantity(entry)) {
-          andEntries.push({
-            quantity: entry.quantity,
-            unit: entry.unit
-          });
-        }
+      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 [
           {
-            type: "and",
-            entries: andEntries,
+            and: andEntries,
             equivalents: equivalentsList
           }
         ];
@@ -815,41 +1236,128 @@ var flattenPlainUnitGroup = (summed) => {
       const first = entries[0];
       return [{ quantity: first.quantity, unit: first.unit }];
     }
-  } else if (isGroup(summed)) {
+  } else if (isAndGroup(summed)) {
     const andEntries = [];
+    const standaloneEntries = [];
     const equivalentsList = [];
-    for (const entry of summed.entries) {
+    for (const entry of summed.and) {
       if (isOrGroup(entry)) {
-        const orEntries = entry.entries.filter(
-          (e2) => isQuantity(e2)
-        );
-        if (orEntries.length > 0) {
+        const orEntries = entry.or;
+        const firstEntry = orEntries[0];
+        if (isAndGroup(firstEntry)) {
+          for (const nestedEntry of firstEntry.and) {
+            andEntries.push({
+              quantity: nestedEntry.quantity,
+              ...nestedEntry.unit && { unit: nestedEntry.unit }
+            });
+          }
+        } else {
+          const primary = firstEntry;
           andEntries.push({
-            quantity: orEntries[0].quantity,
-            unit: orEntries[0].unit
+            quantity: primary.quantity,
+            ...primary.unit && { unit: primary.unit }
           });
-          equivalentsList.push(...orEntries.slice(1));
         }
-      } else if (isQuantity(entry)) {
-        andEntries.push({
-          quantity: entry.quantity,
-          unit: entry.unit
+        const equivEntries = orEntries.slice(1).filter((e2) => isQuantity(e2));
+        equivalentsList.push(
+          ...equivEntries.map((e2) => ({
+            quantity: e2.quantity,
+            ...e2.unit && { unit: e2.unit }
+          }))
+        );
+      } else {
+        const simpleQuantityEntry = entry;
+        standaloneEntries.push({
+          quantity: simpleQuantityEntry.quantity,
+          ...simpleQuantityEntry.unit && { unit: simpleQuantityEntry.unit }
         });
       }
     }
     if (equivalentsList.length === 0) {
-      return andEntries;
+      return [...andEntries, ...standaloneEntries];
     }
-    const result = {
-      type: "and",
-      entries: andEntries,
+    const result = [];
+    result.push({
+      and: andEntries,
       equivalents: equivalentsList
-    };
-    return [result];
+    });
+    result.push(...standaloneEntries);
+    return result;
   } else {
-    return [{ quantity: summed.quantity, unit: summed.unit }];
+    return [
+      { quantity: summed.quantity, ...summed.unit && { unit: summed.unit } }
+    ];
   }
 };
+function applyBestUnit(q, system) {
+  const extended = { quantity: q.quantity };
+  if (q.unit) {
+    extended.unit = typeof q.unit === "string" ? { name: q.unit } : q.unit;
+  }
+  if (!extended.unit?.name) {
+    return q;
+  }
+  const unitDef = resolveUnit(extended.unit.name);
+  if (unitDef.type === "other") {
+    return q;
+  }
+  if (extended.quantity.type === "fixed" && extended.quantity.value.type === "text") {
+    return q;
+  }
+  const avgValue = getAverageValue(extended.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(extended.unit.name)?.name;
+  if (bestUnit.name === originalCanonicalName) {
+    return q;
+  }
+  const formattedValue = formatOutputValue(bestValue, bestUnit);
+  if (extended.quantity.type === "range") {
+    const bestToBase = getToBase(bestUnit, effectiveSystem);
+    const minValue = getNumericValue(extended.quantity.min) * toBase / bestToBase;
+    const maxValue = getNumericValue(extended.quantity.max) * toBase / bestToBase;
+    return {
+      quantity: {
+        type: "range",
+        min: formatOutputValue(minValue, bestUnit),
+        max: formatOutputValue(maxValue, bestUnit)
+      },
+      unit: typeof q.unit === "string" ? bestUnit.name : { name: bestUnit.name }
+    };
+  }
+  return {
+    quantity: {
+      type: "fixed",
+      value: formattedValue
+    },
+    unit: typeof q.unit === "string" ? bestUnit.name : { name: bestUnit.name }
+  };
+}
+function subtractQuantities(q1, q2, options = {}) {
+  const { clampToZero = true, system } = options;
+  const negatedQ2 = {
+    ...q2,
+    quantity: multiplyQuantityValue(q2.quantity, -1)
+  };
+  const result = addQuantities(q1, negatedQ2, system);
+  if (clampToZero) {
+    const avg = getAverageValue(result.quantity);
+    if (typeof avg === "number" && avg < 0) {
+      return {
+        quantity: { type: "fixed", value: { type: "decimal", decimal: 0 } },
+        unit: result.unit
+      };
+    }
+  }
+  return result;
+}
 
 // src/utils/parser_helpers.ts
 function flushPendingNote(section, noteItems) {
@@ -859,9 +1367,12 @@ function flushPendingNote(section, noteItems) {
   }
   return noteItems;
 }
-function flushPendingItems(section, items) {
+function flushPendingItems(section, items, stepVariants, stepOptional) {
   if (items.length > 0) {
-    section.content.push({ type: "step", items: [...items] });
+    const step = { type: "step", items: [...items] };
+    if (stepVariants) step.variants = stepVariants;
+    if (stepOptional) step.optional = true;
+    section.content.push(step);
     items.length = 0;
     return true;
   }
@@ -980,7 +1491,7 @@ function stringifyFixedValue(quantity) {
     return String(quantity.value.decimal);
   else return quantity.value.text;
 }
-function parseQuantityInput(input_str) {
+function parseQuantityValue(input_str) {
   const clean_str = String(input_str).trim();
   if (rangeRegex.test(clean_str)) {
     const range_parts = clean_str.split("-");
@@ -990,19 +1501,253 @@ function parseQuantityInput(input_str) {
   }
   return { type: "fixed", value: parseFixedValue(clean_str) };
 }
+function parseQuantityWithUnit(input) {
+  const trimmed = input.trim();
+  const separatorIndex = trimmed.indexOf("%");
+  if (separatorIndex === -1) {
+    return { value: parseQuantityValue(trimmed) };
+  }
+  const valuePart = trimmed.slice(0, separatorIndex).trim();
+  const unitPart = trimmed.slice(separatorIndex + 1).trim();
+  return {
+    value: parseQuantityValue(valuePart),
+    unit: unitPart || void 0
+  };
+}
+function parseDateFromFormat(input, format) {
+  const delimiterMatch = format.match(/[^A-Za-z]/);
+  if (!delimiterMatch) {
+    throw new Error(`Invalid date format: ${format}. No delimiter found.`);
+  }
+  const delimiter = delimiterMatch[0];
+  const formatParts = format.split(delimiter);
+  const inputParts = input.trim().split(delimiter);
+  if (formatParts.length !== 3 || inputParts.length !== 3) {
+    throw new Error(
+      `Invalid date input "${input}" for format "${format}". Expected 3 parts.`
+    );
+  }
+  let day = 0, month = 0, year = 0;
+  for (let i2 = 0; i2 < 3; i2++) {
+    const token = formatParts[i2].toUpperCase();
+    const value = parseInt(inputParts[i2], 10);
+    if (isNaN(value)) {
+      throw new Error(
+        `Invalid date input "${input}": non-numeric part "${inputParts[i2]}".`
+      );
+    }
+    if (token === "DD") day = value;
+    else if (token === "MM") month = value;
+    else if (token === "YYYY") year = value;
+    else
+      throw new Error(
+        `Unknown token "${formatParts[i2]}" in format "${format}"`
+      );
+  }
+  const date = new Date(year, month - 1, day);
+  if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) {
+    throw new Error(`Invalid date: "${input}" does not form a valid date.`);
+  }
+  return date;
+}
+function disambiguateDayMonth(first, second, year) {
+  if (second > 12 && first <= 12) {
+    return [second, first, year];
+  }
+  return [first, second, year];
+}
+function parseFuzzyDate(input) {
+  const trimmed = input.trim();
+  const delimiterMatch = trimmed.match(/[./-]/);
+  if (!delimiterMatch) {
+    throw new Error(`Cannot parse date "${input}": no delimiter found.`);
+  }
+  const delimiter = delimiterMatch[0];
+  const parts = trimmed.split(delimiter);
+  if (parts.length !== 3) {
+    throw new Error(
+      `Cannot parse date "${input}": expected 3 parts, got ${parts.length}.`
+    );
+  }
+  const nums = parts.map((p) => parseInt(p, 10));
+  if (nums.some((n2) => isNaN(n2))) {
+    throw new Error(`Cannot parse date "${input}": non-numeric parts found.`);
+  }
+  let day, month, year;
+  if (nums[0] >= 1e3) {
+    year = nums[0];
+    month = nums[1];
+    day = nums[2];
+  } else if (nums[2] >= 1e3) {
+    [day, month, year] = disambiguateDayMonth(nums[0], nums[1], nums[2]);
+  } else {
+    if (nums[2] >= 100)
+      throw new Error(`Invalid date: "${input}" does not form a valid date.`);
+    [day, month] = disambiguateDayMonth(nums[0], nums[1], 0);
+    year = 2e3 + nums[2];
+  }
+  const date = new Date(year, month - 1, day);
+  if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) {
+    throw new Error(`Invalid date: "${input}" does not form a valid date.`);
+  }
+  return date;
+}
+function parseMarkdownSegments(text) {
+  const items = [];
+  let cursor = 0;
+  for (const match of text.matchAll(markdownRegex)) {
+    const idx = match.index;
+    if (idx > cursor) {
+      items.push({ type: "text", value: text.slice(cursor, idx) });
+    }
+    const [
+      ,
+      escaped,
+      // group 1: escaped character
+      code,
+      // group 2: inline code
+      linkText,
+      // group 3: link text
+      linkUrl,
+      // group 4: link url
+      tripleAst,
+      // group 5: ***bold+italic***
+      tripleUnd,
+      // group 6: ___bold+italic___
+      astUnd,
+      // group 7: **_bold+italic_**
+      undAst,
+      // group 8: __*bold+italic*__
+      astUndUnd,
+      // group 9: *__bold+italic__*
+      undAstAst,
+      // group 10: _**bold+italic**_
+      boldAst,
+      // group 11: **bold**
+      boldUnd,
+      // group 12: __bold__
+      italicAst,
+      // group 13: *italic*
+      italicUnd
+      // group 14: _italic_
+    ] = match;
+    let value;
+    let attribute;
+    let href;
+    if (escaped !== void 0) {
+      items.push({ type: "text", value: escaped });
+      cursor = idx + match[0].length;
+      continue;
+    } else if (code !== void 0) {
+      value = code;
+      attribute = "code";
+    } else if (linkText !== void 0) {
+      value = linkText;
+      attribute = "link";
+      href = linkUrl;
+    } else if (tripleAst !== void 0 || tripleUnd !== void 0 || astUnd !== void 0 || undAst !== void 0 || astUndUnd !== void 0 || undAstAst !== void 0) {
+      value = tripleAst ?? tripleUnd ?? astUnd ?? undAst ?? astUndUnd ?? undAstAst;
+      attribute = "bold+italic";
+    } else if (boldAst !== void 0 || boldUnd !== void 0) {
+      value = boldAst ?? boldUnd;
+      attribute = "bold";
+    } else {
+      value = italicAst ?? italicUnd;
+      attribute = "italic";
+    }
+    const item = { type: "text", value };
+    if (attribute) item.attribute = attribute;
+    if (href) item.href = href;
+    items.push(item);
+    cursor = idx + match[0].length;
+  }
+  if (cursor < text.length) {
+    items.push({ type: "text", value: text.slice(cursor) });
+  }
+  return items;
+}
 function parseSimpleMetaVar(content, varName) {
   const varMatch = content.match(
     new RegExp(`^${varName}:\\s*(.*(?:\\r?\\n\\s+.*)*)+`, "m")
   );
   return varMatch ? varMatch[1]?.trim().replace(/\s*\r?\n\s+/g, " ") : void 0;
 }
-function parseScalingMetaVar(content, varName) {
-  const varMatch = content.match(scalingMetaValueRegex(varName));
-  if (!varMatch) return void 0;
-  if (isNaN(Number(varMatch[2]?.trim()))) {
-    throw new Error("Scaling variables should be numbers");
+function parseBlockScalarMetaVar(content, varName) {
+  const match = content.match(
+    new RegExp(
+      `^${varName}:\\s*([|>])\\s*\\r?\\n((?:(?:[ ]+.*|\\s*)(?:\\r?\\n|$))+)`,
+      "m"
+    )
+  );
+  if (!match) return void 0;
+  const style = match[1];
+  const rawBlock = match[2];
+  const lines = rawBlock.split(/\r?\n/);
+  const firstNonEmpty = lines.find((l) => l.trim() !== "");
+  if (!firstNonEmpty) return void 0;
+  const baseIndent = firstNonEmpty.match(/^([ ]*)/)[1].length;
+  const stripped = lines.map((line) => line.trim() === "" ? "" : line.slice(baseIndent)).join("\n").replace(/\n+$/, "");
+  if (style === "|") {
+    return stripped;
+  }
+  return stripped.replace(/\n\n/g, "\0").replace(/\n/g, " ").replace(/\0/g, "\n");
+}
+function parseArbitraryQuantity(raw) {
+  const quantityMatch = raw.trim().match(quantityAlternativeRegex);
+  if (!quantityMatch?.groups) {
+    throw new InvalidQuantityFormat(
+      raw,
+      "Arbitrary quantities must have a numerical value"
+    );
+  }
+  const value = parseQuantityValue(quantityMatch.groups.quantity);
+  const unit = quantityMatch.groups.unit;
+  if (!value || value.type === "fixed" && value.value.type === "text") {
+    throw new InvalidQuantityFormat(
+      raw,
+      "Arbitrary quantities must have a numerical value"
+    );
+  }
+  const arbitrary = {
+    quantity: value
+  };
+  if (unit) arbitrary.unit = unit;
+  return arbitrary;
+}
+function parseServingsMetaVar(content, varName) {
+  const raw = parseSimpleMetaVar(content, varName);
+  if (raw === void 0) return void 0;
+  const num = Number(raw);
+  if (isNaN(num)) {
+    return { numericValue: 1, rawValue: raw };
+  }
+  return { numericValue: num, rawValue: num };
+}
+function parseYieldMetaVar(content) {
+  const match = content.match(yieldMetaValueRegex);
+  if (!match) return void 0;
+  if (match.groups?.arbitraryQuantity) {
+    const parsed = parseArbitraryQuantity(match.groups.arbitraryQuantity);
+    const result = {
+      quantity: parsed.quantity
+    };
+    if (parsed.unit) result.unit = parsed.unit;
+    if (match.groups.servingsPrefix) {
+      result.textBefore = match.groups.servingsPrefix;
+    }
+    if (match.groups.servingsSuffix) {
+      result.textAfter = match.groups.servingsSuffix;
+    }
+    return result;
+  }
+  if (match.groups?.quantity) {
+    const result = {
+      quantity: parseQuantityValue(match.groups.quantity)
+    };
+    if (match.groups.unit) result.unit = match.groups.unit;
+    return result;
   }
-  return [Number(varMatch[2]?.trim()), varMatch[1].trim()];
+  return void 0;
 }
 function parseListMetaVar(content, varName) {
   const listMatch = content.match(
@@ -1018,6 +1763,115 @@ function parseListMetaVar(content, varName) {
     return listMatch[2].split("\n").filter((line) => line.trim() !== "").map((line) => line.replace(/^\s*-\s*/, "").trim());
   }
 }
+function extractAllMetadataKeys(content) {
+  const keys = [];
+  for (const match of content.matchAll(metadataKeyRegex)) {
+    keys.push(match[1].trim());
+  }
+  return [...new Set(keys)];
+}
+function parseNestedMetaVar(content, varName) {
+  const match = content.match(nestedMetaVarRegex(varName));
+  if (!match) return void 0;
+  const nestedContent = match[1];
+  return parseNestedBlock(nestedContent);
+}
+function parseNestedBlock(content) {
+  const lines = content.split(/\r?\n/).filter((line) => line.trim() !== "");
+  if (lines.length === 0) return void 0;
+  const baseIndentMatch = lines[0].match(/^(\s*)/);
+  if (baseIndentMatch?.[0]?.includes("	")) {
+    throw new NoTabAsIndentError();
+  }
+  const baseIndent = baseIndentMatch?.[1]?.length;
+  if (lines[0].trim().startsWith("- ")) return void 0;
+  const result = {};
+  let i2 = 0;
+  while (i2 < lines.length) {
+    const line = lines[i2];
+    const leadingWhitespace = line.match(/^(\s*)/)?.[1];
+    if (leadingWhitespace && leadingWhitespace.includes("	")) {
+      throw new NoTabAsIndentError();
+    }
+    const currentIndent = leadingWhitespace.length;
+    if (currentIndent < baseIndent) {
+      break;
+    }
+    if (currentIndent !== baseIndent) {
+      throw new BadIndentationError();
+    }
+    const keyValueMatch = line.match(/^[ ]*([^:\n]+?):\s*(.*)$/);
+    if (!keyValueMatch) {
+      i2++;
+      continue;
+    }
+    const key = keyValueMatch[1].trim();
+    const rawValue = keyValueMatch[2].trim();
+    if (rawValue === "") {
+      const childLines = [];
+      let j = i2 + 1;
+      while (j < lines.length) {
+        const childLine = lines[j];
+        const childIndent = childLine.match(/^([ ]*)/)?.[1]?.length;
+        if (childIndent && childIndent > baseIndent) {
+          childLines.push(childLine);
+          j++;
+        } else {
+          break;
+        }
+      }
+      if (childLines.length > 0) {
+        const firstChildTrimmed = childLines[0].trim();
+        if (firstChildTrimmed.startsWith("- ")) {
+          const reconstructedContent = `${key}:
+${childLines.join("\n")}`;
+          const listResult = parseListMetaVar(reconstructedContent, key);
+          if (listResult) {
+            result[key] = listResult.map(
+              (item) => parseMetadataValue(item)
+            );
+          }
+        } else {
+          const childContent = childLines.join("\n");
+          const nested = parseNestedBlock(childContent);
+          if (nested) {
+            result[key] = nested;
+          }
+        }
+      }
+      i2 = j;
+    } else {
+      result[key] = parseMetadataValue(rawValue);
+      i2++;
+    }
+  }
+  return result;
+}
+function parseMetadataValue(rawValue) {
+  if (rawValue.startsWith("[") && rawValue.endsWith("]")) {
+    return rawValue.slice(1, -1).split(",").map((item) => item.trim());
+  }
+  if (numericValueRegex.test(rawValue)) {
+    return Number(rawValue);
+  }
+  return rawValue;
+}
+function parseAnyMetaVar(content, varName) {
+  const nested = parseNestedMetaVar(content, varName);
+  if (nested) return nested;
+  const list = parseListMetaVar(content, varName);
+  if (list) return list;
+  const simple = parseSimpleMetaVar(content, varName);
+  if (simple) return parseMetadataValue(simple);
+  return void 0;
+}
+function getNumericValueFromYield(v) {
+  if (v.quantity.type === "fixed" && v.quantity.value.type !== "text") {
+    return getNumericValue(v.quantity.value);
+  }
+  if (v.quantity.type === "range") return getNumericValue(v.quantity.min);
+  return 1;
+}
 function extractMetadata(content) {
   const metadata = {};
   let servings = void 0;
@@ -1025,13 +1879,24 @@ function extractMetadata(content) {
   if (!metadataContent) {
     return { metadata };
   }
-  for (const metaVar of [
+  const handledKeys = /* @__PURE__ */ new Set([
+    // Simple string fields
     "title",
+    "author",
+    "locale",
+    "introduction",
+    "description",
+    "course",
+    "category",
+    "diet",
+    "cuisine",
+    "difficulty",
+    // Source fields
     "source",
     "source.name",
     "source.url",
-    "author",
     "source.author",
+    // Time fields
     "prep time",
     "time.prep",
     "cook time",
@@ -1039,6 +1904,24 @@ function extractMetadata(content) {
     "time required",
     "time",
     "duration",
+    // Image fields
+    "image",
+    "picture",
+    "images",
+    "pictures",
+    // Unit system
+    "unit system",
+    // Scaling fields
+    "servings",
+    "yield",
+    "serves",
+    // List fields
+    "tags",
+    "variants"
+  ]);
+  for (const metaVar of [
+    "title",
+    "author",
     "locale",
     "introduction",
     "description",
@@ -1046,25 +1929,97 @@ function extractMetadata(content) {
     "category",
     "diet",
     "cuisine",
-    "difficulty",
-    "image",
-    "picture"
+    "difficulty"
   ]) {
+    if (metaVar === "description" || metaVar === "introduction") {
+      const blockValue = parseBlockScalarMetaVar(metadataContent, metaVar);
+      if (blockValue) {
+        metadata[metaVar] = blockValue;
+        continue;
+      }
+    }
     const stringMetaValue = parseSimpleMetaVar(metadataContent, metaVar);
     if (stringMetaValue) metadata[metaVar] = stringMetaValue;
   }
-  for (const metaVar of ["serves", "yield", "servings"]) {
-    const scalingMetaValue = parseScalingMetaVar(metadataContent, metaVar);
-    if (scalingMetaValue && scalingMetaValue[1]) {
-      metadata[metaVar] = scalingMetaValue[1];
-      servings = scalingMetaValue[0];
+  const sourceNested = parseNestedMetaVar(metadataContent, "source");
+  const sourceTxt = parseSimpleMetaVar(metadataContent, "source");
+  const sourceName = parseSimpleMetaVar(metadataContent, "source.name");
+  const sourceUrl = parseSimpleMetaVar(metadataContent, "source.url");
+  const sourceAuthor = parseSimpleMetaVar(metadataContent, "source.author");
+  if (sourceNested) {
+    const source = {};
+    if (typeof sourceNested.name === "string") source.name = sourceNested.name;
+    if (typeof sourceNested.url === "string") source.url = sourceNested.url;
+    if (typeof sourceNested.author === "string")
+      source.author = sourceNested.author;
+    if (Object.keys(source).length > 0) metadata.source = source;
+  } else if (sourceName || sourceAuthor || sourceUrl) {
+    const source = {};
+    if (sourceName) source.name = sourceName;
+    if (sourceUrl) source.url = sourceUrl;
+    if (sourceAuthor) source.author = sourceAuthor;
+    metadata.source = source;
+  } else if (sourceTxt) {
+    metadata.source = sourceTxt;
+  }
+  const timeNested = parseNestedMetaVar(metadataContent, "time");
+  const prepTime = parseSimpleMetaVar(metadataContent, "prep time") ?? parseSimpleMetaVar(metadataContent, "time.prep");
+  const cookTime = parseSimpleMetaVar(metadataContent, "cook time") ?? parseSimpleMetaVar(metadataContent, "time.cook");
+  const totalTime = parseSimpleMetaVar(metadataContent, "time required") ?? parseSimpleMetaVar(metadataContent, "time") ?? parseSimpleMetaVar(metadataContent, "duration");
+  if (timeNested) {
+    const time = {};
+    if (typeof timeNested.prep === "string") time.prep = timeNested.prep;
+    if (typeof timeNested.cook === "string") time.cook = timeNested.cook;
+    if (typeof timeNested.total === "string") time.total = timeNested.total;
+    if (Object.keys(time).length > 0) metadata.time = time;
+  } else if (prepTime || cookTime || totalTime) {
+    const time = {};
+    if (prepTime) time.prep = prepTime;
+    if (cookTime) time.cook = cookTime;
+    if (totalTime) time.total = totalTime;
+    metadata.time = time;
+  }
+  const image = parseSimpleMetaVar(metadataContent, "image") ?? parseSimpleMetaVar(metadataContent, "picture");
+  if (image) metadata.image = image;
+  const images = parseListMetaVar(metadataContent, "images") ?? parseListMetaVar(metadataContent, "pictures");
+  if (images) metadata.images = images;
+  let unitSystem;
+  const unitSystemRaw = parseSimpleMetaVar(metadataContent, "unit system");
+  if (unitSystemRaw) {
+    metadata.unitSystem = unitSystemRaw;
+    const unitSystemMap = {
+      metric: "metric",
+      us: "US",
+      uk: "UK",
+      jp: "JP"
+    };
+    unitSystem = unitSystemMap[unitSystemRaw.toLowerCase()];
+  }
+  const yieldValue = parseYieldMetaVar(metadataContent);
+  if (yieldValue) {
+    metadata.yield = yieldValue;
+    servings = getNumericValueFromYield(yieldValue);
+  }
+  for (const metaVar of ["serves", "servings"]) {
+    const result = parseServingsMetaVar(metadataContent, metaVar);
+    if (result !== void 0) {
+      metadata[metaVar] = result.rawValue;
+      servings = result.numericValue;
     }
   }
-  for (const metaVar of ["tags", "images", "pictures"]) {
-    const listMetaValue = parseListMetaVar(metadataContent, metaVar);
-    if (listMetaValue) metadata[metaVar] = listMetaValue;
+  const tags = parseListMetaVar(metadataContent, "tags");
+  if (tags) metadata.tags = tags;
+  const variants = parseListMetaVar(metadataContent, "variants");
+  if (variants) metadata.variants = variants;
+  const allKeys = extractAllMetadataKeys(metadataContent);
+  for (const key of allKeys) {
+    if (handledKeys.has(key)) continue;
+    const value = parseAnyMetaVar(metadataContent, key);
+    if (value !== void 0) {
+      metadata[key] = value;
+    }
   }
-  return { metadata, servings };
+  return { metadata, servings, unitSystem };
 }
 function isPositiveIntegerString(str) {
   return /^\d+$/.test(str);
@@ -1078,10 +2033,230 @@ function unionOfSets(s1, s2) {
 }
 function getAlternativeSignature(alternatives) {
   if (!alternatives || alternatives.length === 0) return null;
-  return alternatives.map((a2) => a2.index).sort((a2, b) => a2 - b).join(",");
+  return alternatives.flat().map((a2) => a2.index).sort((a2, b) => a2 - b).join(",");
 }
 
+// src/classes/pantry.ts
+var Pantry = class {
+  /**
+   * Creates a new Pantry instance.
+   * @param tomlContent - Optional TOML content to parse.
+   * @param options - Optional configuration options.
+   */
+  constructor(tomlContent, options = {}) {
+    /**
+     * The parsed pantry items.
+     */
+    __publicField(this, "items", []);
+    /**
+     * Options for date parsing and other configuration.
+     */
+    __publicField(this, "options");
+    /**
+     * Optional category configuration for alias-based lookups.
+     */
+    __publicField(this, "categoryConfig");
+    this.options = options;
+    if (tomlContent) {
+      this.parse(tomlContent);
+    }
+  }
+  /**
+   * Parses a TOML string into pantry items.
+   * @param tomlContent - The TOML string to parse.
+   * @returns The parsed list of pantry items.
+   */
+  parse(tomlContent) {
+    const raw = TOML.parse(tomlContent);
+    this.items = [];
+    for (const [location, locationData] of Object.entries(raw)) {
+      const locationTable = locationData;
+      for (const [itemName, itemData] of Object.entries(locationTable)) {
+        const item = this.parseItem(
+          itemName,
+          location,
+          itemData
+        );
+        this.items.push(item);
+      }
+    }
+    return this.items;
+  }
+  /**
+   * Parses a single pantry item from its TOML representation.
+   */
+  parseItem(name, location, data) {
+    const item = { name, location };
+    if (typeof data === "string") {
+      const parsed = parseQuantityWithUnit(data);
+      item.quantity = parsed.value;
+      if (parsed.unit) item.unit = parsed.unit;
+    } else {
+      if (data.quantity) {
+        const parsed = parseQuantityWithUnit(data.quantity);
+        item.quantity = parsed.value;
+        if (parsed.unit) item.unit = parsed.unit;
+      }
+      if (data.low) {
+        const parsed = parseQuantityWithUnit(data.low);
+        item.low = parsed.value;
+        if (parsed.unit) item.lowUnit = parsed.unit;
+      }
+      if (data.bought) {
+        item.bought = this.parseDate(data.bought);
+      }
+      if (data.expire) {
+        item.expire = this.parseDate(data.expire);
+      }
+    }
+    return item;
+  }
+  /**
+   * Parses a date string using the configured format or fuzzy detection.
+   */
+  parseDate(input) {
+    if (this.options.dateFormat) {
+      return parseDateFromFormat(input, this.options.dateFormat);
+    }
+    return parseFuzzyDate(input);
+  }
+  /**
+   * Sets a category configuration for alias-based item lookups.
+   * @param config - The category configuration to use.
+   */
+  setCategoryConfig(config) {
+    this.categoryConfig = config;
+  }
+  /**
+   * Finds a pantry item by name, using exact match first, then alias lookup
+   * via the stored CategoryConfig.
+   * @param name - The name to search for.
+   * @returns The matching pantry item, or undefined if not found.
+   */
+  findItem(name) {
+    const lowerName = name.toLowerCase();
+    const exact = this.items.find(
+      (item) => item.name.toLowerCase() === lowerName
+    );
+    if (exact) return exact;
+    if (this.categoryConfig) {
+      for (const category of this.categoryConfig.categories) {
+        for (const catIngredient of category.ingredients) {
+          if (catIngredient.aliases.some(
+            (alias) => alias.toLowerCase() === lowerName
+          )) {
+            const canonicalName = catIngredient.name.toLowerCase();
+            const byCanonical = this.items.find(
+              (item) => item.name.toLowerCase() === canonicalName
+            );
+            if (byCanonical) return byCanonical;
+            for (const alias of catIngredient.aliases) {
+              const byAlias = this.items.find(
+                (item) => item.name.toLowerCase() === alias.toLowerCase()
+              );
+              if (byAlias) return byAlias;
+            }
+          }
+        }
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Gets the numeric value of a pantry item's quantity, optionally converted to base units.
+   * Returns undefined if the quantity has a text value or is not set.
+   */
+  getItemNumericValue(quantity, unit) {
+    if (!quantity) return void 0;
+    let numericValue;
+    if (quantity.type === "fixed") {
+      if (quantity.value.type === "text") return void 0;
+      numericValue = getNumericValue(quantity.value);
+    } else {
+      numericValue = (getNumericValue(quantity.min) + getNumericValue(quantity.max)) / 2;
+    }
+    if (unit) {
+      const unitDef = normalizeUnit(unit);
+      if (unitDef) {
+        const toBase = getToBase(unitDef);
+        numericValue *= toBase;
+      }
+    }
+    return numericValue;
+  }
+  /**
+   * Returns all items that are depleted (quantity = 0) or below their low threshold.
+   * @returns An array of depleted pantry items.
+   */
+  getDepletedItems() {
+    return this.items.filter((item) => this.isItemLow(item));
+  }
+  /**
+   * Returns all items whose expiration date is within `nbDays` days from today
+   * (or already passed).
+   * @param nbDays - Number of days ahead to check. Defaults to 0 (already expired).
+   * @returns An array of expired pantry items.
+   */
+  getExpiredItems(nbDays = 0) {
+    return this.items.filter((item) => this.isItemExpired(item, nbDays));
+  }
+  /**
+   * Checks if a specific item is low (quantity = 0 or below `low` threshold).
+   * @param itemName - The name of the item to check (supports aliases if CategoryConfig is set).
+   * @returns true if the item is low, false otherwise. Returns false if item not found.
+   */
+  isLow(itemName) {
+    const item = this.findItem(itemName);
+    if (!item) return false;
+    return this.isItemLow(item);
+  }
+  /**
+   * Checks if a specific item is expired or expires within `nbDays` days.
+   * @param itemName - The name of the item to check (supports aliases if CategoryConfig is set).
+   * @param nbDays - Number of days ahead to check. Defaults to 0.
+   * @returns true if the item is expired, false otherwise. Returns false if item not found.
+   */
+  isExpired(itemName, nbDays = 0) {
+    const item = this.findItem(itemName);
+    if (!item) return false;
+    return this.isItemExpired(item, nbDays);
+  }
+  /**
+   * Internal: checks if a pantry item is low.
+   */
+  isItemLow(item) {
+    if (!item.quantity) return false;
+    const qtyValue = this.getItemNumericValue(item.quantity, item.unit);
+    if (qtyValue === void 0) return false;
+    if (qtyValue === 0) return true;
+    if (item.low) {
+      const lowValue = this.getItemNumericValue(item.low, item.lowUnit);
+      if (lowValue !== void 0 && qtyValue <= lowValue) return true;
+    }
+    return false;
+  }
+  /**
+   * Internal: checks if a pantry item is expired.
+   */
+  isItemExpired(item, nbDays) {
+    if (!item.expire) return false;
+    const now = /* @__PURE__ */ new Date();
+    const cutoff = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate() + nbDays
+    );
+    const expireDay = new Date(
+      item.expire.getFullYear(),
+      item.expire.getMonth(),
+      item.expire.getDate()
+    );
+    return expireDay <= cutoff;
+  }
+};
+
 // src/classes/product_catalog.ts
+import TOML2 from "smol-toml";
 var ProductCatalog = class {
   constructor(tomlContent) {
     __publicField(this, "products", []);
@@ -1093,7 +2268,7 @@ var ProductCatalog = class {
    * @returns A parsed list of `ProductOption`.
    */
   parse(tomlContent) {
-    const catalogRaw = TOML.parse(tomlContent);
+    const catalogRaw = TOML2.parse(tomlContent);
     this.products = [];
     if (!this.isValidTomlContent(catalogRaw)) {
       throw new InvalidProductCatalogFormat();
@@ -1110,7 +2285,7 @@ var ProductCatalog = class {
         const sizeStrings = Array.isArray(size) ? size : [size];
         const sizes = sizeStrings.map((sizeStr) => {
           const sizeAndUnitRaw = sizeStr.split("%");
-          const sizeParsed = parseQuantityInput(
+          const sizeParsed = parseQuantityValue(
             sizeAndUnitRaw[0]
           );
           const productSize = { size: sizeParsed };
@@ -1166,7 +2341,7 @@ var ProductCatalog = class {
         size: sizeStrings.length === 1 ? sizeStrings[0] : sizeStrings
       };
     }
-    return TOML.stringify(grouped);
+    return TOML2.stringify(grouped);
   }
   /**
    * Adds a product to the catalog.
@@ -1223,8 +2398,10 @@ var Section = class {
   /**
    * Creates an instance of Section.
    * @param name - The name of the section. Defaults to an empty string.
+   * @param variants - Optional variant names for this section.
+   * @param optional - Whether the section is optional.
    */
-  constructor(name = "") {
+  constructor(name = "", variants, optional) {
     /**
      * The name of the section. Can be an empty string for the default (first) section.
      * @defaultValue `""`
@@ -1232,7 +2409,13 @@ var Section = class {
     __publicField(this, "name");
     /** An array of steps and notes that make up the content of the section. */
     __publicField(this, "content", []);
+    /** Optional list of variant names this section belongs to. */
+    __publicField(this, "variants");
+    /** Whether the section has been marked as optional ([?]) */
+    __publicField(this, "optional");
     this.name = name;
+    if (variants) this.variants = variants;
+    if (optional) this.optional = true;
   }
   /**
    * Checks if the section is blank (has no name and no content).
@@ -1245,46 +2428,16 @@ var Section = class {
 };
 
 // src/quantities/alternatives.ts
-import Big3 from "big.js";
-
-// src/units/conversion.ts
-import Big2 from "big.js";
-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 Big2(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;
-  }
-}
+import Big4 from "big.js";
 
 // src/units/lookup.ts
-function areUnitsCompatible(u1, u2) {
-  if (u1.name === u2.name) {
-    return true;
-  }
-  if (u1.type !== "other" && u1.type === u2.type && u1.system === u2.system) {
-    return true;
-  }
-  return false;
-}
 function findListWithCompatibleQuantity(list, quantity) {
   const quantityWithUnitDef = {
     ...quantity,
     unit: resolveUnit(quantity.unit?.name)
   };
   return list.find(
-    (l) => l.some((lq) => areUnitsCompatible(lq.unit, quantityWithUnitDef.unit))
+    (l) => l.some((lq) => areUnitsGroupable(lq.unit, quantityWithUnitDef.unit))
   );
 }
 function findCompatibleQuantityWithinList(list, quantity) {
@@ -1298,10 +2451,14 @@ function findCompatibleQuantityWithinList(list, quantity) {
 }
 
 // src/utils/general.ts
+import Big3 from "big.js";
 var legacyDeepClone = (v) => {
   if (v === null || typeof v !== "object") {
     return v;
   }
+  if (v instanceof Big3) {
+    return new Big3(v);
+  }
   if (v instanceof Map) {
     return new Map(
       Array.from(v.entries()).map(([k, val]) => [
@@ -1311,7 +2468,9 @@ var legacyDeepClone = (v) => {
     );
   }
   if (v instanceof Set) {
-    return new Set(Array.from(v).map((val) => legacyDeepClone(val)));
+    return new Set(
+      Array.from(v).map((val) => legacyDeepClone(val))
+    );
   }
   if (v instanceof Date) {
     return new Date(v.getTime());
@@ -1325,27 +2484,24 @@ var legacyDeepClone = (v) => {
   }
   return cloned;
 };
-var deepClone = (v) => typeof structuredClone === "function" ? structuredClone(v) : legacyDeepClone(v);
+var deepClone = (v) => legacyDeepClone(v);
 
 // src/quantities/alternatives.ts
 function getEquivalentUnitsLists(...quantities) {
   const quantitiesCopy = deepClone(quantities);
-  const OrGroups = quantitiesCopy.filter(isOrGroup).filter((q) => q.entries.length > 1);
+  const OrGroups = quantitiesCopy.filter(isOrGroup).filter((q) => q.or.length > 1);
   const unitLists = [];
   const normalizeOrGroup = (og) => ({
-    ...og,
-    entries: og.entries.map((q) => ({
+    or: og.or.map((q) => ({
       ...q,
       unit: resolveUnit(q.unit?.name, q.unit?.integerProtected)
     }))
   });
   function findLinkIndexForUnits(lists, unitsToCheck) {
     return lists.findIndex((l) => {
-      const listItem = l.map((q) => resolveUnit(q.unit?.name));
+      const listItems = l.map((q) => resolveUnit(q.unit?.name));
       return unitsToCheck.some(
-        (u) => listItem.some(
-          (lu) => lu.name === u?.name || lu.system === u?.system && lu.type === u?.type && lu.type !== "other"
-        )
+        (u) => u && listItems.some((lu) => areUnitsGroupable(lu, u))
       );
     });
   }
@@ -1356,17 +2512,19 @@ function getEquivalentUnitsLists(...quantities) {
         ...v,
         unit: resolveUnit(v.unit?.name, v.unit?.integerProtected)
       };
-      const commonQuantity = og.entries.find(
-        (q) => isQuantity(q) && areUnitsCompatible(q.unit, normalizedV.unit)
+      const commonQuantity = og.or.find(
+        (q) => isQuantity(q) && areUnitsGroupable(q.unit, normalizedV.unit)
       );
       if (commonQuantity) {
         acc.push(normalizedV);
-        unitRatio = getUnitRatio(normalizedV, commonQuantity);
+        if (!unitRatio) {
+          unitRatio = getUnitRatio(normalizedV, commonQuantity);
+        }
       }
       return acc;
     }, []);
-    for (const newQ of og.entries) {
-      if (commonUnitList.some((q) => areUnitsCompatible(q.unit, newQ.unit))) {
+    for (const newQ of og.or) {
+      if (commonUnitList.some((q) => areUnitsGroupable(q.unit, newQ.unit))) {
         continue;
       } else {
         const scaledQuantity = multiplyQuantityValue(newQ.quantity, unitRatio);
@@ -1376,10 +2534,10 @@ function getEquivalentUnitsLists(...quantities) {
   }
   for (const orGroup of OrGroups) {
     const orGroupModified = normalizeOrGroup(orGroup);
-    const units2 = orGroupModified.entries.map((q) => q.unit);
+    const units2 = orGroupModified.or.map((q) => q.unit);
     const linkIndex = findLinkIndexForUnits(unitLists, units2);
     if (linkIndex === -1) {
-      unitLists.push(orGroupModified.entries);
+      unitLists.push(orGroupModified.or);
     } else {
       mergeOrGroupIntoList(unitLists, linkIndex, orGroupModified);
     }
@@ -1475,7 +2633,7 @@ function reduceOrsToFirstEquivalent(unitList, quantities) {
   return quantities.map((q) => {
     if (isQuantity(q)) return reduceToQuantity(q);
     const qListModified = sortUnitList(
-      q.entries.map((qq) => ({
+      q.or.map((qq) => ({
         ...qq,
         unit: resolveUnit(qq.unit?.name, qq.unit?.integerProtected)
       }))
@@ -1483,7 +2641,7 @@ function reduceOrsToFirstEquivalent(unitList, quantities) {
     return reduceToQuantity(qListModified[0]);
   });
 }
-function addQuantitiesOrGroups(...quantities) {
+function addQuantitiesOrGroups(quantities, system) {
   if (quantities.length === 0)
     return {
       sum: {
@@ -1513,7 +2671,7 @@ function addQuantitiesOrGroups(...quantities) {
         unit: resolveUnit(nextQ.unit?.name)
       });
     } else {
-      const sumQ = addQuantities(existingQ, nextQ);
+      const sumQ = addQuantities(existingQ, nextQ, system);
       existingQ.quantity = sumQ.quantity;
       existingQ.unit = resolveUnit(sumQ.unit?.name);
     }
@@ -1521,10 +2679,10 @@ function addQuantitiesOrGroups(...quantities) {
   if (sum.length === 1) {
     return { sum: sum[0], unitsLists };
   }
-  return { sum: { type: "and", entries: sum }, unitsLists };
+  return { sum: { and: sum }, unitsLists };
 }
-function regroupQuantitiesAndExpandEquivalents(sum, unitsLists) {
-  const sumQuantities = isGroup(sum) ? sum.entries : [sum];
+function regroupQuantitiesAndExpandEquivalents(sum, unitsLists, system) {
+  const sumQuantities = isAndGroup(sum) ? sum.and : [sum];
   const result = [];
   const processedQuantities = /* @__PURE__ */ new Set();
   for (const list of unitsLists) {
@@ -1551,10 +2709,20 @@ function regroupQuantitiesAndExpandEquivalents(sum, unitsLists) {
       }
       return main.reduce((acc, v) => {
         const mainInList = findCompatibleQuantityWithinList(list, v);
+        const conversionRatio = getBaseUnitRatio(v, mainInList);
+        const valueInOriginalUnit = Big4(getAverageValue(v.quantity)).times(
+          conversionRatio
+        );
         const newValue = {
           quantity: multiplyQuantityValue(
-            v.quantity,
-            Big3(getAverageValue(equiv.quantity)).div(
+            {
+              type: "fixed",
+              value: {
+                type: "decimal",
+                decimal: valueInOriginalUnit.toNumber()
+              }
+            },
+            Big4(getAverageValue(equiv.quantity)).div(
               getAverageValue(mainInList.quantity)
             )
           )
@@ -1562,17 +2730,15 @@ function regroupQuantitiesAndExpandEquivalents(sum, unitsLists) {
         if (equiv.unit && !isNoUnit(equiv.unit)) {
           newValue.unit = { name: equiv.unit.name };
         }
-        return addQuantities(acc, newValue);
+        return addQuantities(acc, newValue, system);
       }, initialValue);
     });
     if (main.length + equivalents.length > 1) {
       const resultMain = main.length > 1 ? {
-        type: "and",
-        entries: main.map(deNormalizeQuantity)
+        and: main.map(deNormalizeQuantity)
       } : deNormalizeQuantity(main[0]);
       result.push({
-        type: "or",
-        entries: [resultMain, ...equivalents]
+        or: [resultMain, ...equivalents]
       });
     } else {
       result.push(deNormalizeQuantity(main[0]));
@@ -1581,21 +2747,66 @@ function regroupQuantitiesAndExpandEquivalents(sum, unitsLists) {
   sumQuantities.filter((q) => !processedQuantities.has(q)).forEach((q) => result.push(deNormalizeQuantity(q)));
   return result;
 }
-function addEquivalentsAndSimplify(...quantities) {
+function addEquivalentsAndSimplify(quantities, system) {
   if (quantities.length === 1) {
     return toPlainUnit(quantities[0]);
   }
-  const { sum, unitsLists } = addQuantitiesOrGroups(...quantities);
-  const regrouped = regroupQuantitiesAndExpandEquivalents(sum, unitsLists);
+  const { sum, unitsLists } = addQuantitiesOrGroups(quantities, system);
+  const regrouped = regroupQuantitiesAndExpandEquivalents(
+    sum,
+    unitsLists,
+    system
+  );
   if (regrouped.length === 1) {
     return toPlainUnit(regrouped[0]);
   } else {
-    return { type: "and", entries: regrouped.map(toPlainUnit) };
+    return { and: regrouped.map(toPlainUnit) };
+  }
+}
+function buildEquivalenceRatioMap(unitsLists) {
+  const ratioMap = {};
+  for (const list of unitsLists) {
+    for (const equiv of list) {
+      const equivValue = getAverageValue(equiv.quantity);
+      for (const primary of list) {
+        if (primary === equiv) continue;
+        const primaryValue = getAverageValue(primary.quantity);
+        const equivUnit = normalizeUnit(equiv.unit.name)?.name ?? equiv.unit.name;
+        const primaryUnit = normalizeUnit(primary.unit.name)?.name ?? primary.unit.name;
+        ratioMap[equivUnit] ?? (ratioMap[equivUnit] = {});
+        ratioMap[equivUnit][primaryUnit] = equivValue / primaryValue;
+      }
+    }
+  }
+  return ratioMap;
+}
+function recomputeEquivalents(primaries, ratioMap, equivUnits) {
+  const equivalents = [];
+  for (const equivUnit of equivUnits) {
+    const ratios = ratioMap[normalizeUnit(equivUnit)?.name ?? equivUnit];
+    let total = 0;
+    for (const primary of primaries) {
+      const pUnit = normalizeUnit(primary.unit ?? NO_UNIT)?.name ?? primary.unit ?? NO_UNIT;
+      const ratio = ratios[pUnit];
+      if (ratio === void 0) continue;
+      const pValue = getAverageValue(primary.quantity);
+      total += pValue * ratio;
+    }
+    if (total > 0) {
+      equivalents.push({
+        quantity: {
+          type: "fixed",
+          value: { type: "decimal", decimal: total }
+        },
+        ...equivUnit !== "" && { unit: equivUnit }
+      });
+    }
   }
+  return equivalents.length > 0 ? equivalents : void 0;
 }
 
 // src/classes/recipe.ts
-import Big4 from "big.js";
+import Big5 from "big.js";
 var _Recipe = class _Recipe {
   /**
    * Creates a new Recipe instance.
@@ -1607,12 +2818,12 @@ var _Recipe = class _Recipe {
      */
     __publicField(this, "metadata", {});
     /**
-     * The default or manual choice of alternative ingredients.
-     * Contains the full context including alternatives list and active selection index.
+     * The possible choices of alternative ingredients for this recipe.
      */
     __publicField(this, "choices", {
       ingredientItems: /* @__PURE__ */ new Map(),
-      ingredientGroups: /* @__PURE__ */ new Map()
+      ingredientGroups: /* @__PURE__ */ new Map(),
+      variants: []
     });
     /**
      * The parsed recipe ingredients.
@@ -1643,10 +2854,20 @@ var _Recipe = class _Recipe {
      */
     __publicField(this, "servings");
     _Recipe.itemCounts.set(this, 0);
+    _Recipe.subgroupIndices.set(this, /* @__PURE__ */ new Map());
     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.
    */
@@ -1669,27 +2890,17 @@ var _Recipe = class _Recipe {
    */
   _parseArbitraryScalable(regexMatchGroups, intoArray) {
     if (!regexMatchGroups || !regexMatchGroups.arbitraryQuantity) return;
-    const quantityMatch = regexMatchGroups.arbitraryQuantity?.trim().match(quantityAlternativeRegex);
-    if (quantityMatch?.groups) {
-      const value = quantityMatch.groups.quantity ? parseQuantityInput(quantityMatch.groups.quantity) : void 0;
-      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
-      });
-    }
+    const parsed = parseArbitraryQuantity(regexMatchGroups.arbitraryQuantity);
+    const name = regexMatchGroups.arbitraryName || void 0;
+    const arbitrary = {
+      quantity: parsed.quantity
+    };
+    if (name) arbitrary.name = name;
+    if (parsed.unit) arbitrary.unit = parsed.unit;
+    intoArray.push({
+      type: "arbitrary",
+      index: this.arbitraries.push(arbitrary) - 1
+    });
   }
   /**
    * Parses text for arbitrary scalables and returns NoteItem array.
@@ -1703,13 +2914,13 @@ var _Recipe = class _Recipe {
     for (const match of text.matchAll(globalRegex)) {
       const idx = match.index;
       if (idx > cursor) {
-        noteItems.push({ type: "text", value: text.slice(cursor, idx) });
+        noteItems.push(...parseMarkdownSegments(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) });
+      noteItems.push(...parseMarkdownSegments(text.slice(cursor)));
     }
     return noteItems;
   }
@@ -1717,7 +2928,7 @@ var _Recipe = class _Recipe {
     let quantityMatch = quantityRaw.match(quantityAlternativeRegex);
     const quantities = [];
     while (quantityMatch?.groups) {
-      const value = quantityMatch.groups.quantity ? parseQuantityInput(quantityMatch.groups.quantity) : void 0;
+      const value = quantityMatch.groups.quantity ? parseQuantityValue(quantityMatch.groups.quantity) : void 0;
       const unit = quantityMatch.groups.unit;
       if (value) {
         const newQuantity = { quantity: value };
@@ -1818,7 +3029,7 @@ var _Recipe = class _Recipe {
         alternative.note = note;
       }
       if (itemQuantity) {
-        alternative.itemQuantity = itemQuantity;
+        Object.assign(alternative, itemQuantity);
       }
       alternatives.push(alternative);
       testString = groups.ingredientAlternative || "";
@@ -1861,6 +3072,7 @@ var _Recipe = class _Recipe {
     if (!match?.groups) return;
     const groups = match.groups;
     const groupKey = groups.gIngredientGroupKey;
+    const subgroupKey = groups.gIngredientSubgroupKey;
     let name = groups.gmIngredientName || groups.gsIngredientName;
     const preparation = groups.gIngredientPreparation;
     const modifiers = groups.gIngredientModifiers;
@@ -1926,9 +3138,14 @@ var _Recipe = class _Recipe {
       displayName
     };
     if (itemQuantity) {
-      alternative.itemQuantity = itemQuantity;
+      Object.assign(alternative, itemQuantity);
     }
-    const existingAlternatives = this.choices.ingredientGroups.get(groupKey);
+    const note = groups.gIngredientNote?.trim();
+    if (note) {
+      alternative.note = note;
+    }
+    const existingSubgroups = this.choices.ingredientGroups.get(groupKey);
+    const existingAlternativesFlat = existingSubgroups?.flat();
     function upsertAlternativeToIngredient(ingredients, ingredientIdx, newAlternativeIdx) {
       const ingredient = ingredients[ingredientIdx];
       if (ingredient) {
@@ -1939,8 +3156,8 @@ var _Recipe = class _Recipe {
         }
       }
     }
-    if (existingAlternatives) {
-      for (const alt of existingAlternatives) {
+    if (existingAlternativesFlat) {
+      for (const alt of existingAlternativesFlat) {
         upsertAlternativeToIngredient(this.ingredients, alt.index, idxInList);
         upsertAlternativeToIngredient(this.ingredients, idxInList, alt.index);
       }
@@ -1952,14 +3169,35 @@ var _Recipe = class _Recipe {
       group: groupKey,
       alternatives: [alternative]
     };
+    if (subgroupKey !== void 0) {
+      newItem.subgroup = subgroupKey;
+    }
     items.push(newItem);
     const choiceAlternative = deepClone(alternative);
     choiceAlternative.itemId = id;
     const existingChoice = this.choices.ingredientGroups.get(groupKey);
+    const sgMap = _Recipe.subgroupIndices.get(this);
     if (!existingChoice) {
-      this.choices.ingredientGroups.set(groupKey, [choiceAlternative]);
+      this.choices.ingredientGroups.set(groupKey, [[choiceAlternative]]);
+      if (subgroupKey !== void 0) {
+        sgMap.set(groupKey, /* @__PURE__ */ new Map([[subgroupKey, 0]]));
+      }
+    } else if (subgroupKey !== void 0) {
+      const groupSgMap = sgMap.get(groupKey);
+      const existingIdx = groupSgMap?.get(subgroupKey);
+      if (existingIdx !== void 0) {
+        existingChoice[existingIdx].push(choiceAlternative);
+      } else {
+        const newIdx = existingChoice.length;
+        existingChoice.push([choiceAlternative]);
+        if (!groupSgMap) {
+          sgMap.set(groupKey, /* @__PURE__ */ new Map([[subgroupKey, newIdx]]));
+        } else {
+          groupSgMap.set(subgroupKey, newIdx);
+        }
+      }
     } else {
-      existingChoice.push(choiceAlternative);
+      existingChoice.push([choiceAlternative]);
     }
   }
   /**
@@ -1973,142 +3211,230 @@ var _Recipe = class _Recipe {
    * Quantities are grouped by their alternative signature and summed using addEquivalentsAndSimplify.
    * @internal
    */
-  _populate_ingredient_quantities() {
-    this.ingredients = this.ingredients.map((ing) => {
-      if (ing.quantities) {
-        delete ing.quantities;
+  _populateIngredientQuantities() {
+    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 (ing.usedAsPrimary) {
-        delete ing.usedAsPrimary;
+      if (computed.usedAsPrimary) {
+        ing.usedAsPrimary = true;
       }
-      return ing;
-    });
-    const seenGroups = /* @__PURE__ */ new Set();
+    }
+  }
+  // Type for accumulated quantities (used internally by collectQuantityGroups)
+  // Defined as a static type alias for the private method's return type
+  /** @internal */
+  collectQuantityGroups(options) {
+    const { section, step, choices } = options || {};
+    const activeVariant = choices?.variant;
+    const isDefaultVariant = activeVariant === void 0 || activeVariant === "*";
+    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();
-    for (const section of this.sections) {
-      for (const step of section.content.filter(
+    const selectedIndices = /* @__PURE__ */ new Set();
+    const referencedIndices = /* @__PURE__ */ new Set();
+    const dynamicOptionalIndices = /* @__PURE__ */ new Set();
+    for (const currentSection of sectionsToProcess) {
+      if (currentSection.variants) {
+        if (isDefaultVariant) {
+          if (!currentSection.variants.includes("*")) continue;
+        } else {
+          if (!currentSection.variants.includes(activeVariant)) continue;
+        }
+      }
+      const allSteps = currentSection.content.filter(
         (item) => item.type === "step"
-      )) {
-        for (const item of step.items.filter(
+      );
+      const isOptionalSection = currentSection.optional === true;
+      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) {
+        if (currentStep.variants) {
+          if (isDefaultVariant) {
+            if (!currentStep.variants.includes("*")) continue;
+          } else {
+            if (!currentStep.variants.includes(activeVariant)) continue;
+          }
+        }
+        const isOptionalStep = currentStep.optional === true || isOptionalSection;
+        for (const item of currentStep.items.filter(
           (item2) => item2.type === "ingredient"
         )) {
-          const isGroupedItem = "group" in item && item.group !== void 0;
-          const isFirstInGroup = isGroupedItem && !seenGroups.has(item.group);
-          if (isGroupedItem) {
-            seenGroups.add(item.group);
-          }
-          const isPrimary = !isGroupedItem || isFirstInGroup;
-          const alternative = item.alternatives[0];
-          if (isPrimary) {
-            const primaryIngredient = this.ingredients[alternative.index];
-            if (primaryIngredient) {
-              primaryIngredient.usedAsPrimary = true;
+          const isGrouped = "group" in item && item.group !== void 0;
+          const groupSubgroups = isGrouped ? this.choices.ingredientGroups.get(item.group) : void 0;
+          let selectedAltIndex = 0;
+          let isSelected;
+          let hasExplicitChoice;
+          if (isGrouped) {
+            const groupChoice = choices?.ingredientGroups?.get(item.group);
+            hasExplicitChoice = groupChoice !== void 0;
+            if (!hasExplicitChoice && !isDefaultVariant) {
+              const matchingSubgroupIdx = groupSubgroups?.findIndex(
+                (sg) => sg.some(
+                  (alt) => alt.note && alt.note.toLowerCase().includes(activeVariant.toLowerCase())
+                )
+              );
+              if (matchingSubgroupIdx !== void 0 && matchingSubgroupIdx >= 0) {
+                const matchedSubgroup = groupSubgroups[matchingSubgroupIdx];
+                isSelected = matchedSubgroup.some(
+                  (alt) => alt.itemId === item.id
+                );
+                hasExplicitChoice = true;
+                selectedAltIndex = 0;
+              } else {
+                const targetSubgroupIndex = 0;
+                const selectedSubgroup = groupSubgroups?.[targetSubgroupIndex];
+                isSelected = selectedSubgroup.some(
+                  (alt) => alt.itemId === item.id
+                );
+              }
+            } else {
+              const targetSubgroupIndex = groupChoice ?? 0;
+              const selectedSubgroup = groupSubgroups?.[targetSubgroupIndex];
+              isSelected = selectedSubgroup?.some((alt) => alt.itemId === item.id) ?? false;
             }
-          }
-          if (!isPrimary || !alternative.itemQuantity) continue;
-          const allQuantities = [
-            {
-              quantity: alternative.itemQuantity.quantity,
-              unit: alternative.itemQuantity.unit
+          } else {
+            const itemChoice = choices?.ingredientItems?.get(item.id);
+            hasExplicitChoice = itemChoice !== void 0;
+            if (!hasExplicitChoice && !isDefaultVariant) {
+              const matchingIndices = item.alternatives.map((alt, idx) => ({ alt, idx })).filter(
+                ({ alt }) => alt.note && alt.note.toLowerCase().includes(activeVariant.toLowerCase())
+              ).map(({ idx }) => idx);
+              if (matchingIndices.length > 0) {
+                selectedAltIndex = matchingIndices[0];
+                hasExplicitChoice = true;
+              } else {
+                selectedAltIndex = itemChoice ?? 0;
+              }
+            } else {
+              selectedAltIndex = itemChoice ?? 0;
             }
-          ];
-          if (alternative.itemQuantity.equivalents) {
-            allQuantities.push(...alternative.itemQuantity.equivalents);
+            isSelected = true;
+          }
+          const alternative = item.alternatives[selectedAltIndex];
+          if (!alternative || !isSelected) continue;
+          selectedIndices.add(alternative.index);
+          if (isOptionalStep) {
+            dynamicOptionalIndices.add(alternative.index);
           }
-          const quantityEntry = allQuantities.length === 1 ? allQuantities[0] : { type: "or", entries: allQuantities };
-          const hasInlineAlternatives = item.alternatives.length > 1;
-          const hasGroupedAlternatives = isGroupedItem && this.choices.ingredientGroups.has(item.group);
+          const allAltsFlat = isGrouped ? groupSubgroups.flat() : item.alternatives;
+          for (const alt of allAltsFlat) {
+            referencedIndices.add(alt.index);
+          }
+          if (!alternative.quantity) continue;
+          const baseQty = {
+            quantity: alternative.quantity,
+            ...alternative.unit && {
+              unit: alternative.unit
+            }
+          };
+          const quantityEntry = alternative.equivalents?.length ? { or: [baseQty, ...alternative.equivalents] } : baseQty;
           let alternativeRefs;
-          if (hasInlineAlternatives) {
-            alternativeRefs = [];
-            for (let j = 1; j < item.alternatives.length; j++) {
-              const otherAlt = item.alternatives[j];
-              const newRef = {
-                index: otherAlt.index
-              };
-              if (otherAlt.itemQuantity) {
-                const altQty = {
-                  quantity: otherAlt.itemQuantity.quantity
+          if (!hasExplicitChoice && groupSubgroups && groupSubgroups.length > 1) {
+            const currentSubgroupIdx = groupSubgroups.findIndex(
+              (sg) => sg.some((alt) => alt.itemId === item.id)
+            );
+            alternativeRefs = groupSubgroups.filter((_, idx) => idx !== currentSubgroupIdx).map(
+              (subgroup) => subgroup.map((otherAlt) => {
+                const ref = {
+                  index: otherAlt.index
                 };
-                if (otherAlt.itemQuantity.unit) {
-                  altQty.unit = otherAlt.itemQuantity.unit.name;
-                }
-                if (otherAlt.itemQuantity.equivalents) {
-                  altQty.equivalents = otherAlt.itemQuantity.equivalents.map(
-                    (eq) => toPlainUnit(eq)
-                  );
+                if (otherAlt.quantity) {
+                  const altQty = {
+                    quantity: otherAlt.quantity,
+                    ...otherAlt.unit && {
+                      unit: otherAlt.unit.name
+                    },
+                    ...otherAlt.equivalents && {
+                      equivalents: otherAlt.equivalents.map(
+                        (eq) => toPlainUnit(eq)
+                      )
+                    }
+                  };
+                  ref.quantities = [altQty];
                 }
-                newRef.quantities = [altQty];
-              }
-              alternativeRefs.push(newRef);
-            }
-          } else if (hasGroupedAlternatives) {
-            const groupAlternatives = this.choices.ingredientGroups.get(
-              item.group
+                return ref;
+              })
             );
-            alternativeRefs = [];
-            for (let j = 1; j < groupAlternatives.length; j++) {
-              const otherAlt = groupAlternatives[j];
-              if (otherAlt.itemQuantity) {
+          } else if (!hasExplicitChoice && !isGrouped && allAltsFlat.length > 1) {
+            alternativeRefs = allAltsFlat.filter((alt) => alt.index !== alternative.index).map((otherAlt) => {
+              const ref = { index: otherAlt.index };
+              if (otherAlt.quantity) {
                 const altQty = {
-                  quantity: otherAlt.itemQuantity.quantity
+                  quantity: otherAlt.quantity,
+                  ...otherAlt.unit && {
+                    unit: otherAlt.unit.name
+                  },
+                  ...otherAlt.equivalents && {
+                    equivalents: otherAlt.equivalents.map(
+                      (eq) => toPlainUnit(eq)
+                    )
+                  }
                 };
-                if (otherAlt.itemQuantity.unit) {
-                  altQty.unit = otherAlt.itemQuantity.unit.name;
-                }
-                if (otherAlt.itemQuantity.equivalents) {
-                  altQty.equivalents = otherAlt.itemQuantity.equivalents.map(
-                    (eq) => toPlainUnit(eq)
-                  );
-                }
-                alternativeRefs.push({
-                  index: otherAlt.index,
-                  quantities: [altQty]
-                });
+                ref.quantities = [altQty];
               }
-            }
-            if (alternativeRefs.length === 0) {
-              alternativeRefs = void 0;
-            }
+              return [ref];
+            });
+          }
+          const altIndices = getAlternativeSignature(alternativeRefs) ?? "";
+          let signature;
+          if (isGrouped) {
+            const resolvedUnit = resolveUnit(alternative.unit?.name);
+            signature = `group:${item.group}|${altIndices}|${resolvedUnit.type}`;
+          } else if (altIndices) {
+            const resolvedUnit = resolveUnit(alternative.unit?.name);
+            signature = `${altIndices}|${resolvedUnit.type}}`;
+          } else {
+            signature = null;
           }
           if (!ingredientGroups.has(alternative.index)) {
             ingredientGroups.set(alternative.index, /* @__PURE__ */ new Map());
           }
-          const groupsForIngredient = ingredientGroups.get(alternative.index);
-          const baseSignature = getAlternativeSignature(alternativeRefs);
-          const signature = isGroupedItem ? `group:${item.group}|${baseSignature ?? ""}` : baseSignature;
-          if (!groupsForIngredient.has(signature)) {
-            groupsForIngredient.set(signature, {
+          const groupsForIng = ingredientGroups.get(alternative.index);
+          if (!groupsForIng.has(signature)) {
+            groupsForIng.set(signature, {
+              quantities: [],
               alternativeQuantities: /* @__PURE__ */ new Map(),
-              quantities: []
+              alternativeSubgroups: []
             });
           }
-          const group = groupsForIngredient.get(signature);
+          const group = groupsForIng.get(signature);
           group.quantities.push(quantityEntry);
-          if (alternativeRefs) {
-            for (const ref of alternativeRefs) {
+          if (alternativeRefs && alternativeRefs.length > 0 && group.alternativeSubgroups.length === 0) {
+            group.alternativeSubgroups = alternativeRefs.map(
+              (subgroup) => subgroup.map((ref) => ref.index)
+            );
+          }
+          for (const subgroup of alternativeRefs ?? []) {
+            for (const ref of subgroup) {
               if (!group.alternativeQuantities.has(ref.index)) {
                 group.alternativeQuantities.set(ref.index, []);
               }
-              if (ref.quantities && ref.quantities.length > 0) {
-                for (const altQty of ref.quantities) {
-                  if (altQty.equivalents && altQty.equivalents.length > 0) {
-                    const entries = [
-                      toExtendedUnit({
-                        quantity: altQty.quantity,
-                        unit: altQty.unit
-                      }),
-                      ...altQty.equivalents.map((eq) => toExtendedUnit(eq))
-                    ];
-                    group.alternativeQuantities.get(ref.index).push({ type: "or", entries });
-                  } else {
-                    group.alternativeQuantities.get(ref.index).push(
-                      toExtendedUnit({
-                        quantity: altQty.quantity,
-                        unit: altQty.unit
-                      })
-                    );
-                  }
+              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);
                 }
               }
             }
@@ -2116,144 +3442,219 @@ var _Recipe = class _Recipe {
         }
       }
     }
-    for (const [index, groupsForIngredient] of ingredientGroups) {
-      const ingredient = this.ingredients[index];
-      const quantityGroups = [];
-      for (const [, group] of groupsForIngredient) {
-        const summedGroupQuantity = addEquivalentsAndSimplify(
-          ...group.quantities
-        );
-        const groupQuantities = flattenPlainUnitGroup(summedGroupQuantity);
-        let alternatives;
-        if (group.alternativeQuantities.size > 0) {
-          alternatives = [];
-          for (const [altIndex, altQuantities] of group.alternativeQuantities) {
-            const ref = { index: altIndex };
-            if (altQuantities.length > 0) {
-              const summedAltQuantity = addEquivalentsAndSimplify(
-                ...altQuantities
-              );
-              const flattenedAlt = flattenPlainUnitGroup(summedAltQuantity);
-              ref.quantities = flattenedAlt.flatMap((item) => {
-                if ("quantity" in item) {
-                  return [item];
-                } else {
-                  return item.entries;
-                }
-              });
-            }
-            alternatives.push(ref);
-          }
-        }
-        for (const gq of groupQuantities) {
-          if ("type" in gq && gq.type === "and") {
-            const andGroup = {
-              type: "and",
-              entries: gq.entries
-            };
-            if (gq.equivalents && gq.equivalents.length > 0) {
-              andGroup.equivalents = gq.equivalents;
-            }
-            if (alternatives && alternatives.length > 0) {
-              andGroup.alternatives = alternatives;
-            }
-            quantityGroups.push(andGroup);
-          } else {
-            const quantityGroup = gq;
-            if (alternatives && alternatives.length > 0) {
-              quantityGroup.alternatives = alternatives;
-            }
-            quantityGroups.push(quantityGroup);
+    return {
+      ingredientGroups,
+      selectedIndices,
+      referencedIndices,
+      dynamicOptionalIndices
+    };
+  }
+  /**
+   * Gets the raw (unprocessed) quantity groups for each ingredient, before
+   * any summation or equivalents simplification. This is useful for cross-recipe
+   * aggregation (e.g., in {@link ShoppingList}), where quantities from multiple
+   * recipes should be combined before processing.
+   *
+   * @param options - Options for filtering and choice selection (same as {@link getIngredientQuantities}).
+   * @returns Array of {@link RawQuantityGroup} objects, one per ingredient with quantities.
+   *
+   * @example
+   * ```typescript
+   * const rawGroups = recipe.getRawQuantityGroups();
+   * // Each group has: name, usedAsPrimary, flags, quantities[]
+   * // quantities are the raw QuantityWithExtendedUnit or FlatOrGroup entries
+   * ```
+   */
+  getRawQuantityGroups(options) {
+    const {
+      ingredientGroups,
+      selectedIndices,
+      referencedIndices,
+      dynamicOptionalIndices
+    } = this.collectQuantityGroups(options);
+    const result = [];
+    for (let index = 0; index < this.ingredients.length; index++) {
+      if (!referencedIndices.has(index)) continue;
+      const orig = this.ingredients[index];
+      const usedAsPrimary = selectedIndices.has(index);
+      let flags = orig.flags;
+      if (dynamicOptionalIndices.has(index) && !flags?.includes("optional")) {
+        flags = [...flags ?? [], "optional"];
+      }
+      const quantities = [];
+      if (usedAsPrimary) {
+        const groupsForIng = ingredientGroups.get(index);
+        if (groupsForIng) {
+          for (const [, group] of groupsForIng) {
+            quantities.push(...group.quantities);
           }
         }
       }
-      if (quantityGroups.length > 0) {
-        ingredient.quantities = quantityGroups;
-      }
+      result.push({
+        name: orig.name,
+        ...usedAsPrimary && { usedAsPrimary: true },
+        ...flags && { flags },
+        quantities
+      });
     }
+    return result;
   }
   /**
-   * Calculates ingredient quantities based on the provided choices.
-   * Returns a list of computed ingredients with their total quantities.
+   * 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();
    *
-   * @param choices - The recipe choices to apply when computing quantities.
-   *   If not provided, uses the default choices (first alternative for each item).
-   * @returns An array of ComputedIngredient with quantityTotal calculated based on choices.
+   * // 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]]) }
+   * });
+   * ```
    */
-  calc_ingredient_quantities(choices) {
-    const effectiveChoices = choices || {
-      ingredientItems: new Map(
-        Array.from(this.choices.ingredientItems.keys()).map((k) => [k, 0])
-      ),
-      ingredientGroups: new Map(
-        Array.from(this.choices.ingredientGroups.keys()).map((k) => [k, 0])
-      )
-    };
-    const ingredientQuantities = /* @__PURE__ */ new Map();
-    const selectedIngredientIndices = /* @__PURE__ */ new Set();
-    for (const section of this.sections) {
-      for (const step of section.content.filter(
-        (item) => item.type === "step"
-      )) {
-        for (const item of step.items.filter(
-          (item2) => item2.type === "ingredient"
-        )) {
-          for (let i2 = 0; i2 < item.alternatives.length; i2++) {
-            const alternative = item.alternatives[i2];
-            const isAlternativeChoiceItem = effectiveChoices.ingredientItems?.get(item.id) === i2;
-            const alternativeChoiceGroupIdx = item.group ? effectiveChoices.ingredientGroups?.get(item.group) : void 0;
-            const alternativeChoiceGroup = item.group ? this.choices.ingredientGroups.get(item.group) : void 0;
-            const isAlternativeChoiceGroup = alternativeChoiceGroup && alternativeChoiceGroupIdx !== void 0 ? alternativeChoiceGroup[alternativeChoiceGroupIdx]?.itemId === item.id : false;
-            const isSelected = !("group" in item) && (item.alternatives.length === 1 || isAlternativeChoiceItem) || isAlternativeChoiceGroup;
-            if (isSelected) {
-              selectedIngredientIndices.add(alternative.index);
-              if (alternative.itemQuantity) {
-                const allQuantities = [
-                  {
-                    quantity: alternative.itemQuantity.quantity,
-                    unit: alternative.itemQuantity.unit
-                  }
-                ];
-                if (alternative.itemQuantity.equivalents) {
-                  allQuantities.push(...alternative.itemQuantity.equivalents);
-                }
-                const equivalents = allQuantities.length === 1 ? allQuantities[0] : {
-                  type: "or",
-                  entries: allQuantities
-                };
-                ingredientQuantities.set(alternative.index, [
-                  ...ingredientQuantities.get(alternative.index) || [],
-                  equivalents
-                ]);
+  getIngredientQuantities(options) {
+    const {
+      ingredientGroups,
+      selectedIndices,
+      referencedIndices,
+      dynamicOptionalIndices
+    } = this.collectQuantityGroups(options);
+    const result = [];
+    for (let index = 0; index < this.ingredients.length; index++) {
+      if (!referencedIndices.has(index)) continue;
+      const orig = this.ingredients[index];
+      let flags = orig.flags;
+      if (dynamicOptionalIndices.has(index) && !flags?.includes("optional")) {
+        flags = [...flags ?? [], "optional"];
+      }
+      const ing = {
+        name: orig.name,
+        ...orig.preparation && { preparation: orig.preparation },
+        ...flags && { 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);
+            let alternatives;
+            if (group.alternativeSubgroups.length > 0) {
+              alternatives = group.alternativeSubgroups.map(
+                (subgroupIndices) => subgroupIndices.map((altIdx) => {
+                  const altQtys = group.alternativeQuantities.get(altIdx);
+                  return {
+                    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
+                      )
+                    }
+                  };
+                })
+              );
+            }
+            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);
     }
-    const computedIngredients = [];
-    for (let index = 0; index < this.ingredients.length; index++) {
-      if (!selectedIngredientIndices.has(index)) continue;
-      const ing = this.ingredients[index];
-      const computed = {
-        name: ing.name
-      };
-      if (ing.preparation) {
-        computed.preparation = ing.preparation;
-      }
-      if (ing.flags) {
-        computed.flags = ing.flags;
-      }
-      if (ing.extras) {
-        computed.extras = ing.extras;
+    return result;
+  }
+  /**
+   * Returns the list of cookware items that are used in the active variant.
+   * Cookware in steps/sections not matching the active variant are excluded.
+   * Hidden cookware is always excluded.
+   *
+   * @param options - Options for filtering:
+   *   - `choices`: The choices to apply (only `variant` is used)
+   * @returns Array of Cookware objects referenced by active steps
+   *
+   * @example
+   * ```typescript
+   * // Get all cookware for the default variant
+   * const cookware = recipe.getCookwareForVariant();
+   *
+   * // Get cookware for a specific variant
+   * const veganCookware = recipe.getCookwareForVariant({ choices: { variant: 'vegan' } });
+   * ```
+   */
+  getCookwareForVariant(options) {
+    const { choices } = options || {};
+    const activeVariant = choices?.variant;
+    const isDefaultVariant = activeVariant === void 0 || activeVariant === "*";
+    const cookwareIndices = /* @__PURE__ */ new Set();
+    for (const currentSection of this.sections) {
+      if (currentSection.variants) {
+        if (isDefaultVariant) {
+          if (!currentSection.variants.includes("*")) continue;
+        } else {
+          if (!currentSection.variants.includes(activeVariant)) continue;
+        }
       }
-      const quantities = ingredientQuantities.get(index);
-      if (quantities && quantities.length > 0) {
-        computed.quantityTotal = addEquivalentsAndSimplify(...quantities);
+      const allSteps = currentSection.content.filter(
+        (item) => item.type === "step"
+      );
+      for (const currentStep of allSteps) {
+        if (currentStep.variants) {
+          if (isDefaultVariant) {
+            if (!currentStep.variants.includes("*")) continue;
+          } else {
+            if (!currentStep.variants.includes(activeVariant)) continue;
+          }
+        }
+        for (const item of currentStep.items) {
+          if (item.type === "cookware") {
+            cookwareIndices.add(item.index);
+          }
+        }
       }
-      computedIngredients.push(computed);
     }
-    return computedIngredients;
+    return this.cookware.filter(
+      (cw, idx) => cookwareIndices.has(idx) && !cw.flags?.includes("hidden")
+    );
   }
   /**
    * Parses a recipe from a string.
@@ -2261,17 +3662,23 @@ var _Recipe = class _Recipe {
    */
   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 noteText = "";
     let inNote = false;
+    let stepVariants;
+    let stepOptional;
+    const discoveredVariants = /* @__PURE__ */ new Set();
     for (const line of cleanContent) {
       if (line.trim().length === 0) {
-        flushPendingItems(section, items);
+        flushPendingItems(section, items, stepVariants, stepOptional);
+        stepVariants = void 0;
+        stepOptional = void 0;
         flushPendingNote(
           section,
           noteText ? this._parseNoteText(noteText) : []
@@ -2282,30 +3689,42 @@ var _Recipe = class _Recipe {
         continue;
       }
       if (line.startsWith("=")) {
-        flushPendingItems(section, items);
+        flushPendingItems(section, items, stepVariants, stepOptional);
+        stepVariants = void 0;
+        stepOptional = void 0;
         flushPendingNote(
           section,
           noteText ? this._parseNoteText(noteText) : []
         );
         noteText = "";
-        if (this.sections.length === 0 && section.isBlank()) {
-          section.name = line.replace(/^=+|=+$/g, "").trim();
-        } else {
-          if (!section.isBlank()) {
-            this.sections.push(section);
+        let sectionName = line.replace(/^=+|=+$/g, "").trim();
+        let sectionVariants;
+        let sectionOptional;
+        const sectionVarMatch = sectionName.match(variantTagRegex);
+        if (sectionVarMatch?.groups) {
+          const isOptionalPrefix = sectionVarMatch.groups.variantOptionalPrefix === "?";
+          const names = (sectionVarMatch.groups.variantNames ?? "").split(",").map((n2) => n2.trim()).filter((n2) => n2.length > 0);
+          if (names.length > 0) {
+            sectionVariants = names;
+            for (const v of names) discoveredVariants.add(v);
+          }
+          if (isOptionalPrefix) {
+            sectionOptional = true;
           }
-          section = new Section(line.replace(/^=+|=+$/g, "").trim());
+          sectionName = sectionName.slice(sectionVarMatch[0].length).trim();
         }
+        if (!section.isBlank()) {
+          this.sections.push(section);
+        }
+        section = new Section(sectionName, sectionVariants, sectionOptional);
         blankLineBefore = true;
         inNote = false;
         continue;
       }
       if (blankLineBefore && line.startsWith(">")) {
-        flushPendingItems(section, items);
-        flushPendingNote(
-          section,
-          noteText ? this._parseNoteText(noteText) : []
-        );
+        flushPendingItems(section, items, stepVariants, stepOptional);
+        stepVariants = void 0;
+        stepOptional = void 0;
         noteText = line.substring(1).trim();
         inNote = true;
         blankLineBefore = false;
@@ -2320,13 +3739,31 @@ var _Recipe = class _Recipe {
         blankLineBefore = false;
         continue;
       }
-      flushPendingNote(section, noteText ? this._parseNoteText(noteText) : []);
-      noteText = "";
+      let currentLine = line;
+      if (items.length === 0) {
+        const varMatch = currentLine.match(variantTagRegex);
+        if (varMatch?.groups) {
+          const isOptionalPrefix = varMatch.groups.variantOptionalPrefix === "?";
+          const names = (varMatch.groups.variantNames ?? "").split(",").map((n2) => n2.trim()).filter((n2) => n2.length > 0);
+          if (names.length > 0) {
+            stepVariants = names;
+            for (const v of names) discoveredVariants.add(v);
+          }
+          if (isOptionalPrefix) {
+            stepOptional = true;
+          }
+          currentLine = currentLine.slice(varMatch[0].length);
+          if (currentLine.trim().length === 0) {
+            blankLineBefore = false;
+            continue;
+          }
+        }
+      }
       let cursor = 0;
-      for (const match of line.matchAll(tokensRegex)) {
+      for (const match of currentLine.matchAll(tokensRegex)) {
         const idx = match.index;
         if (idx > cursor) {
-          items.push({ type: "text", value: line.slice(cursor, idx) });
+          items.push(...parseMarkdownSegments(currentLine.slice(cursor, idx)));
         }
         const groups = match.groups;
         if (groups.mIngredientName || groups.sIngredientName) {
@@ -2345,7 +3782,7 @@ var _Recipe = class _Recipe {
           if (modifiers !== void 0 && modifiers.includes("-")) {
             flags.push("hidden");
           }
-          const quantity = quantityRaw ? parseQuantityInput(quantityRaw) : void 0;
+          const quantity = quantityRaw ? parseQuantityValue(quantityRaw) : void 0;
           const newCookware = {
             name
           };
@@ -2377,7 +3814,7 @@ var _Recipe = class _Recipe {
             throw new Error("Timer missing unit");
           }
           const name = groups.timerName || void 0;
-          const duration = parseQuantityInput(durationStr);
+          const duration = parseQuantityValue(durationStr);
           const timerObj = {
             name,
             duration,
@@ -2387,17 +3824,22 @@ var _Recipe = class _Recipe {
         }
         cursor = idx + match[0].length;
       }
-      if (cursor < line.length) {
-        items.push({ type: "text", value: line.slice(cursor) });
+      if (cursor < currentLine.length) {
+        items.push(...parseMarkdownSegments(currentLine.slice(cursor)));
       }
       blankLineBefore = false;
     }
-    flushPendingItems(section, items);
+    flushPendingItems(section, items, stepVariants, stepOptional);
     flushPendingNote(section, noteText ? this._parseNoteText(noteText) : []);
     if (!section.isBlank()) {
       this.sections.push(section);
     }
-    this._populate_ingredient_quantities();
+    const metaVariants = this.metadata.variants ?? [];
+    const allVariants = /* @__PURE__ */ new Set([...metaVariants, ...discoveredVariants]);
+    if (allVariants.size > 0) {
+      this.choices.variants = [...allVariants];
+    }
+    this._populateIngredientQuantities();
   }
   /**
    * Scales the recipe to a new number of servings. In practice, it calls
@@ -2412,7 +3854,7 @@ var _Recipe = class _Recipe {
     if (originalServings === void 0 || originalServings === 0) {
       originalServings = 1;
     }
-    const factor = Big4(newServings).div(originalServings);
+    const factor = Big5(newServings).div(originalServings);
     return this.scaleBy(factor);
   }
   /**
@@ -2427,18 +3869,19 @@ var _Recipe = class _Recipe {
     if (originalServings === void 0 || originalServings === 0) {
       originalServings = 1;
     }
+    const unitSystem = this.unitSystem;
     function scaleAlternativesBy(alternatives, factor2) {
       for (const alternative of alternatives) {
-        if (alternative.itemQuantity) {
-          const scaleFactor = alternative.itemQuantity.scalable ? Big4(factor2) : 1;
-          if (alternative.itemQuantity.quantity.type !== "fixed" || alternative.itemQuantity.quantity.value.type !== "text") {
-            alternative.itemQuantity.quantity = multiplyQuantityValue(
-              alternative.itemQuantity.quantity,
+        if (alternative.quantity) {
+          const scaleFactor = alternative.scalable ? Big5(factor2) : 1;
+          if (alternative.quantity.type !== "fixed" || alternative.quantity.value.type !== "text") {
+            alternative.quantity = multiplyQuantityValue(
+              alternative.quantity,
               scaleFactor
             );
           }
-          if (alternative.itemQuantity.equivalents) {
-            alternative.itemQuantity.equivalents = alternative.itemQuantity.equivalents.map(
+          if (alternative.equivalents) {
+            alternative.equivalents = alternative.equivalents.map(
               (altQuantity) => {
                 if (altQuantity.quantity.type === "fixed" && altQuantity.quantity.value.type === "text") {
                   return altQuantity;
@@ -2454,6 +3897,20 @@ var _Recipe = class _Recipe {
               }
             );
           }
+          const optimizedPrimary = applyBestUnit(
+            {
+              quantity: alternative.quantity,
+              unit: alternative.unit
+            },
+            unitSystem
+          );
+          alternative.quantity = optimizedPrimary.quantity;
+          alternative.unit = optimizedPrimary.unit;
+          if (alternative.equivalents) {
+            alternative.equivalents = alternative.equivalents.map(
+              (eq) => applyBestUnit(eq, unitSystem)
+            );
+          }
         }
       }
     }
@@ -2468,8 +3925,10 @@ var _Recipe = class _Recipe {
         }
       }
     }
-    for (const alternatives of newRecipe.choices.ingredientGroups.values()) {
-      scaleAlternativesBy(alternatives, factor);
+    for (const subgroups of newRecipe.choices.ingredientGroups.values()) {
+      for (const subgroup of subgroups) {
+        scaleAlternativesBy(subgroup, factor);
+      }
     }
     for (const alternatives of newRecipe.choices.ingredientItems.values()) {
       scaleAlternativesBy(alternatives, factor);
@@ -2479,39 +3938,198 @@ var _Recipe = class _Recipe {
         arbitrary.quantity,
         factor
       );
+      const optimized = applyBestUnit(
+        { quantity: arbitrary.quantity, unit: arbitrary.unit },
+        unitSystem
+      );
+      arbitrary.quantity = optimized.quantity;
+      arbitrary.unit = optimized.unit;
     }
-    newRecipe._populate_ingredient_quantities();
-    newRecipe.servings = Big4(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(
-          Big4(servingsValue).times(factor).toNumber()
-        );
+    newRecipe._populateIngredientQuantities();
+    newRecipe.servings = Big5(originalServings).times(factor).toNumber();
+    for (const metaVar of ["servings", "serves"]) {
+      if (typeof newRecipe.metadata[metaVar] === "number") {
+        newRecipe.metadata[metaVar] = Big5(newRecipe.metadata[metaVar]).times(factor).toNumber();
       }
     }
     if (newRecipe.metadata.yield && this.metadata.yield) {
-      if (floatRegex.test(String(this.metadata.yield).replace(",", ".").trim())) {
-        const yieldValue = parseFloat(
-          String(this.metadata.yield).replace(",", ".")
+      const original = this.metadata.yield;
+      if (original.quantity.type === "fixed" && original.quantity.value.type === "text") {
+      } else {
+        const scaledQuantity = multiplyQuantityValue(
+          original.quantity,
+          factor
         );
-        newRecipe.metadata.yield = String(
-          Big4(yieldValue).times(factor).toNumber()
+        const optimized = applyBestUnit(
+          { quantity: scaledQuantity, unit: original.unit },
+          unitSystem
         );
+        const scaled = {
+          quantity: optimized.quantity
+        };
+        if (optimized.unit) scaled.unit = optimized.unit;
+        if (original.textBefore) scaled.textBefore = original.textBefore;
+        if (original.textAfter) scaled.textAfter = original.textAfter;
+        newRecipe.metadata.yield = scaled;
+      }
+    }
+    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 (source === "converted") remainingEquivalents.push(oldPrimary);
+        if (remainingEquivalents.length > 0) {
+          newPrimary.equivalents = remainingEquivalents;
+        }
+      } else {
+        newPrimary.equivalents = [oldPrimary, ...remainingEquivalents];
       }
+      return newPrimary;
     }
-    if (newRecipe.metadata.serves && this.metadata.serves) {
-      if (floatRegex.test(String(this.metadata.serves).replace(",", ".").trim())) {
-        const servesValue = parseFloat(
-          String(this.metadata.serves).replace(",", ".")
+    function convertAlternativeQuantity(alternative) {
+      const primaryUnit = resolveUnit(alternative.unit?.name);
+      const equivalents = alternative.equivalents ?? [];
+      const oldPrimary = {
+        quantity: alternative.quantity,
+        unit: alternative.unit
+      };
+      if (primaryUnit.type !== "other" && isUnitCompatibleWithSystem(primaryUnit, system)) {
+        if (method === "remove") {
+          return {
+            quantity: alternative.quantity,
+            unit: alternative.unit,
+            scalable: alternative.scalable
+          };
+        }
+        return {
+          quantity: alternative.quantity,
+          unit: alternative.unit,
+          scalable: alternative.scalable,
+          equivalents
+        };
+      }
+      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
         );
-        newRecipe.metadata.serves = String(
-          Big4(servesValue).times(factor).toNumber()
+        return buildNewPrimary(
+          targetEquiv,
+          oldPrimary,
+          remainingEquivalents,
+          alternative.scalable,
+          targetEquiv.unit?.integerProtected,
+          "swapped"
+        );
+      }
+      const converted = convertQuantityToSystem(oldPrimary, system);
+      if (converted && converted.unit) {
+        return buildNewPrimary(
+          converted,
+          oldPrimary,
+          equivalents,
+          alternative.scalable,
+          alternative.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,
+            alternative.scalable,
+            equiv.unit?.integerProtected,
+            "converted"
+          );
+        }
+      }
+      if (method === "remove") {
+        return {
+          quantity: alternative.quantity,
+          unit: alternative.unit,
+          scalable: alternative.scalable
+        };
+      } else {
+        return {
+          quantity: alternative.quantity,
+          unit: alternative.unit,
+          scalable: alternative.scalable,
+          equivalents
+        };
+      }
+    }
+    function convertAlternatives(alternatives) {
+      for (const alternative of alternatives) {
+        if (alternative.quantity) {
+          const converted = convertAlternativeQuantity(
+            alternative
+          );
+          alternative.quantity = converted.quantity;
+          alternative.unit = converted.unit;
+          alternative.scalable = converted.scalable;
+          alternative.equivalents = converted.equivalents;
+        }
+      }
     }
+    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 subgroups of newRecipe.choices.ingredientGroups.values()) {
+      for (const subgroup of subgroups) {
+        convertAlternatives(subgroup);
+      }
+    }
+    for (const alternatives of newRecipe.choices.ingredientItems.values()) {
+      convertAlternatives(alternatives);
+    }
+    newRecipe._populateIngredientQuantities();
+    if (method !== "keep") _Recipe.unitSystems.set(newRecipe, system);
     return newRecipe;
   }
   /**
@@ -2536,7 +4154,11 @@ var _Recipe = class _Recipe {
     newRecipe.metadata = deepClone(this.metadata);
     newRecipe.ingredients = deepClone(this.ingredients);
     newRecipe.sections = this.sections.map((section) => {
-      const newSection = new Section(section.name);
+      const newSection = new Section(
+        section.name,
+        section.variants,
+        section.optional
+      );
       newSection.content = deepClone(section.content);
       return newSection;
     });
@@ -2547,21 +4169,30 @@ var _Recipe = class _Recipe {
     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());
+/**
+ * External storage for subgroup index tracking during parsing.
+ * Maps groupKey → subgroupKey → index within the subgroups array.
+ */
+__publicField(_Recipe, "subgroupIndices", /* @__PURE__ */ new WeakMap());
 var Recipe = _Recipe;
 
 // src/classes/shopping_list.ts
 var ShoppingList = class {
   /**
    * Creates a new ShoppingList instance
-   * @param category_config_str - The category configuration to parse.
+   * @param categoryConfigStr - The category configuration to parse.
    */
-  constructor(category_config_str) {
-    // TODO: backport type change
+  constructor(categoryConfigStr) {
     /**
      * The ingredients in the shopping list.
      */
@@ -2573,43 +4204,43 @@ var ShoppingList = class {
     /**
      * The category configuration for the shopping list.
      */
-    __publicField(this, "category_config");
+    __publicField(this, "categoryConfig");
     /**
      * The categorized ingredients in the shopping list.
      */
     __publicField(this, "categories");
-    if (category_config_str) {
-      this.set_category_config(category_config_str);
+    /**
+     * The unit system to use for quantity simplification.
+     * When set, overrides per-recipe unit systems.
+     */
+    __publicField(this, "unitSystem");
+    /**
+     * Per-ingredient equivalence ratio maps for recomputing equivalents
+     * after pantry subtraction. Keyed by ingredient name.
+     * @internal
+     */
+    __publicField(this, "equivalenceRatios", /* @__PURE__ */ new Map());
+    /**
+     * The original pantry (never mutated by recipe calculations).
+     */
+    __publicField(this, "pantry");
+    /**
+     * The pantry with quantities updated after subtracting recipe needs.
+     * Recomputed on every {@link ShoppingList.calculateIngredients | calculateIngredients()} call.
+     */
+    __publicField(this, "resultingPantry");
+    if (categoryConfigStr) {
+      this.setCategoryConfig(categoryConfigStr);
     }
   }
-  calculate_ingredients() {
+  calculateIngredients() {
     this.ingredients = [];
-    const addIngredientQuantity = (name, quantityTotal) => {
-      const quantityTotalExtended = extendAllUnits(quantityTotal);
-      const newQuantities = isAndGroup(quantityTotalExtended) ? quantityTotalExtended.entries : [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.entries : [existingQuantityTotalExtended];
-          existing.quantityTotal = addEquivalentsAndSimplify(
-            ...existingQuantities,
-            ...newQuantities
-          );
-          return;
-        } catch {
-        }
+    const rawQuantitiesMap = /* @__PURE__ */ new Map();
+    const nameOrder = [];
+    const trackName = (name) => {
+      if (!nameOrder.includes(name)) {
+        nameOrder.push(name);
       }
-      this.ingredients.push({
-        name,
-        quantityTotal
-      });
     };
     for (const addedRecipe of this.recipes) {
       let scaledRecipe;
@@ -2619,28 +4250,261 @@ var ShoppingList = class {
       } else {
         scaledRecipe = addedRecipe.recipe.scaleTo(addedRecipe.servings);
       }
-      const computedIngredients = scaledRecipe.calc_ingredient_quantities(
-        addedRecipe.choices
-      );
-      for (const ingredient of computedIngredients) {
-        if (ingredient.flags && ingredient.flags.includes("hidden")) {
+      const rawGroups = scaledRecipe.getRawQuantityGroups({
+        choices: addedRecipe.choices
+      });
+      for (const group of rawGroups) {
+        if (group.flags?.includes("hidden") || !group.usedAsPrimary) {
           continue;
         }
-        if (ingredient.quantityTotal) {
-          addIngredientQuantity(ingredient.name, ingredient.quantityTotal);
-        } else if (!this.ingredients.some((i2) => i2.name === ingredient.name)) {
-          this.ingredients.push({ name: ingredient.name });
+        trackName(group.name);
+        if (group.quantities.length > 0) {
+          const existing = rawQuantitiesMap.get(group.name) ?? [];
+          existing.push(...group.quantities);
+          rawQuantitiesMap.set(group.name, existing);
+        }
+      }
+    }
+    this.equivalenceRatios.clear();
+    for (const name of nameOrder) {
+      const rawQuantities = rawQuantitiesMap.get(name);
+      if (!rawQuantities || rawQuantities.length === 0) {
+        this.ingredients.push({ name });
+        continue;
+      }
+      const textEntries = [];
+      const numericEntries = [];
+      for (const q of rawQuantities) {
+        if ("quantity" in q && q.quantity.type === "fixed" && q.quantity.value.type === "text") {
+          textEntries.push(q);
+        } else {
+          numericEntries.push(q);
+        }
+      }
+      if (numericEntries.length > 1) {
+        const ratioMap = buildEquivalenceRatioMap(
+          getEquivalentUnitsLists(...numericEntries)
+        );
+        if (Object.keys(ratioMap).length > 0) {
+          this.equivalenceRatios.set(name, ratioMap);
         }
       }
+      const resultQuantities = [];
+      for (const t2 of textEntries) {
+        resultQuantities.push(toPlainUnit(t2));
+      }
+      if (numericEntries.length > 0) {
+        resultQuantities.push(
+          ...flattenPlainUnitGroup(
+            addEquivalentsAndSimplify(numericEntries, this.unitSystem)
+          )
+        );
+      }
+      this.ingredients.push({
+        name,
+        quantities: resultQuantities
+      });
     }
+    this.applyPantrySubtraction();
+  }
+  /**
+   * Subtracts pantry item quantities from calculated ingredient quantities
+   * and updates the resultingPantry to reflect consumed stock.
+   */
+  applyPantrySubtraction() {
+    if (!this.pantry) {
+      this.resultingPantry = void 0;
+      return;
+    }
+    const clonedPantry = new Pantry();
+    clonedPantry.items = deepClone(this.pantry.items);
+    if (this.categoryConfig) {
+      clonedPantry.setCategoryConfig(this.categoryConfig);
+    }
+    for (const ingredient of this.ingredients) {
+      if (!ingredient.quantities || ingredient.quantities.length === 0)
+        continue;
+      const pantryItem = clonedPantry.findItem(ingredient.name);
+      if (!pantryItem || !pantryItem.quantity) continue;
+      let pantryExtended = {
+        quantity: pantryItem.quantity,
+        ...pantryItem.unit && { unit: { name: pantryItem.unit } }
+      };
+      for (let i2 = 0; i2 < ingredient.quantities.length; i2++) {
+        const entry = ingredient.quantities[i2];
+        const leaves = "and" in entry ? entry.and : [entry];
+        for (const leaf of leaves) {
+          const ingredientExtended = toExtendedUnit(leaf);
+          const leafHasUnit = leaf.unit !== void 0 && leaf.unit !== "";
+          const pantryHasUnit = pantryExtended.unit !== void 0 && pantryExtended.unit.name !== "";
+          const ratioMap = this.equivalenceRatios.get(ingredient.name);
+          const unitMismatch = leafHasUnit !== pantryHasUnit && ratioMap !== void 0;
+          const leafDef = normalizeUnit(leaf.unit);
+          const pantryDef = normalizeUnit(pantryExtended.unit?.name);
+          if (unitMismatch) {
+            const leafUnit = leaf.unit ?? NO_UNIT;
+            const pantryUnit = pantryExtended.unit?.name ?? NO_UNIT;
+            const ratioFromPantry = ratioMap[normalizeUnit(leafUnit)?.name ?? leafUnit]?.[normalizeUnit(pantryUnit)?.name ?? pantryUnit];
+            if (ratioFromPantry !== void 0) {
+              const pantryValue = getAverageValue(pantryExtended.quantity);
+              const leafValue = getAverageValue(ingredientExtended.quantity);
+              if (typeof pantryValue === "number" && typeof leafValue === "number") {
+                const pantryInLeafUnits = pantryValue * ratioFromPantry;
+                const subtracted = Math.min(pantryInLeafUnits, leafValue);
+                const remainingLeafValue = Math.max(
+                  leafValue - pantryInLeafUnits,
+                  0
+                );
+                leaf.quantity = {
+                  type: "fixed",
+                  value: { type: "decimal", decimal: remainingLeafValue }
+                };
+                const consumedInPantryUnits = subtracted / ratioFromPantry;
+                const remainingPantryValue = Math.max(
+                  pantryValue - consumedInPantryUnits,
+                  0
+                );
+                pantryExtended = {
+                  quantity: {
+                    type: "fixed",
+                    value: {
+                      type: "decimal",
+                      decimal: remainingPantryValue
+                    }
+                  },
+                  ...pantryExtended.unit && { unit: pantryExtended.unit }
+                };
+                continue;
+              }
+            } else {
+              continue;
+            }
+          } else if (leafDef && pantryDef && areUnitsConvertible(leafDef, pantryDef) || (leaf.unit ?? "").toLowerCase() === (pantryExtended.unit?.name ?? "").toLowerCase()) {
+            const remaining = subtractQuantities(
+              ingredientExtended,
+              pantryExtended,
+              { clampToZero: true }
+            );
+            const consumed = subtractQuantities(
+              pantryExtended,
+              ingredientExtended,
+              { clampToZero: true }
+            );
+            pantryExtended = consumed;
+            const updated = toPlainUnit(remaining);
+            leaf.quantity = updated.quantity;
+            leaf.unit = updated.unit;
+          } else if (ratioMap) {
+            const canonicalLeaf = normalizeUnit(leaf.unit)?.name ?? leaf.unit;
+            const leafValue = getAverageValue(ingredientExtended.quantity);
+            const pantryValue = getAverageValue(pantryExtended.quantity);
+            if (typeof leafValue === "number" && typeof pantryValue === "number" && pantryDef) {
+              for (const [equivUnit, ratios] of Object.entries(ratioMap)) {
+                const ratio = ratios[canonicalLeaf];
+                if (ratio === void 0) continue;
+                const equivDef = normalizeUnit(equivUnit);
+                if (!equivDef || !areUnitsConvertible(equivDef, pantryDef))
+                  continue;
+                const pantryInEquiv = pantryValue * getToBase(pantryDef) / getToBase(equivDef);
+                const pantryInLeafUnits = pantryInEquiv / ratio;
+                const subtracted = Math.min(pantryInLeafUnits, leafValue);
+                const remainingLeafValue = Math.max(
+                  leafValue - pantryInLeafUnits,
+                  0
+                );
+                leaf.quantity = {
+                  type: "fixed",
+                  value: { type: "decimal", decimal: remainingLeafValue }
+                };
+                const consumedInEquiv = subtracted * ratio;
+                const consumedInPantryUnits = consumedInEquiv * getToBase(equivDef) / getToBase(pantryDef);
+                const remainingPantryValue = Math.max(
+                  pantryValue - consumedInPantryUnits,
+                  0
+                );
+                pantryExtended = {
+                  quantity: {
+                    type: "fixed",
+                    value: {
+                      type: "decimal",
+                      decimal: remainingPantryValue
+                    }
+                  },
+                  ...pantryExtended.unit && { unit: pantryExtended.unit }
+                };
+                break;
+              }
+            }
+          }
+        }
+        if ("and" in entry) {
+          const nonZero = entry.and.filter(
+            (leaf) => leaf.quantity.type !== "fixed" || leaf.quantity.value.type !== "decimal" || leaf.quantity.value.decimal !== 0
+          );
+          entry.and.length = 0;
+          entry.and.push(...nonZero);
+          const ratioMap = this.equivalenceRatios.get(ingredient.name);
+          if (entry.equivalents && ratioMap) {
+            const equivUnits = entry.equivalents.map((e2) => e2.unit);
+            entry.equivalents = recomputeEquivalents(
+              entry.and,
+              ratioMap,
+              equivUnits
+            );
+          }
+          if (entry.and.length === 1) {
+            const single = entry.and[0];
+            ingredient.quantities[i2] = {
+              quantity: single.quantity,
+              ...single.unit && { unit: single.unit },
+              ...entry.equivalents && { equivalents: entry.equivalents }
+            };
+          }
+        } else if ("equivalents" in entry && entry.equivalents) {
+          const ratioMap = this.equivalenceRatios.get(ingredient.name);
+          if (ratioMap) {
+            const equivUnits = entry.equivalents.map(
+              (e2) => e2.unit
+              // equivalents always have units
+            );
+            const recomputed = recomputeEquivalents(
+              [entry],
+              ratioMap,
+              equivUnits
+            );
+            entry.equivalents = recomputed;
+          }
+        }
+      }
+      ingredient.quantities = ingredient.quantities.filter((entry) => {
+        if ("and" in entry) return entry.and.length > 0;
+        return !(entry.quantity.type === "fixed" && entry.quantity.value.type === "decimal" && entry.quantity.value.decimal === 0);
+      });
+      if (ingredient.quantities.length === 0) {
+        ingredient.quantities = void 0;
+      }
+      pantryItem.quantity = pantryExtended.quantity;
+      if (pantryExtended.unit) {
+        pantryItem.unit = pantryExtended.unit.name;
+      }
+    }
+    this.resultingPantry = clonedPantry;
   }
   /**
    * 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 = {}) {
+  addRecipe(recipe, options = {}) {
+    const errorMessage = this.getUnresolvedAlternativesError(
+      recipe,
+      options.choices
+    );
+    if (errorMessage) {
+      throw new Error(errorMessage);
+    }
     if (!options.scaling) {
       this.recipes.push({
         recipe,
@@ -2662,32 +4526,102 @@ var ShoppingList = class {
         });
       }
     }
-    this.calculate_ingredients();
+    this.calculateIngredients();
     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
+   * recalculates the quantities and recategorize the ingredients.
    * @param index - The index of the recipe to remove.
    */
-  remove_recipe(index) {
+  removeRecipe(index) {
     if (index < 0 || index >= this.recipes.length) {
       throw new Error("Index out of bounds");
     }
     this.recipes.splice(index, 1);
-    this.calculate_ingredients();
+    this.calculateIngredients();
     this.categorize();
   }
+  /**
+   * Adds a pantry to the shopping list. On-hand pantry quantities will be
+   * subtracted from recipe ingredient needs on each recalculation.
+   * @param pantry - A Pantry instance or a TOML string to parse.
+   * @param options - Options for pantry parsing (only used when providing a TOML string).
+   */
+  addPantry(pantry, options) {
+    if (typeof pantry === "string") {
+      this.pantry = new Pantry(pantry, options);
+    } else if (pantry instanceof Pantry) {
+      this.pantry = pantry;
+    } else {
+      throw new Error(
+        "Invalid pantry: expected a Pantry instance or TOML string"
+      );
+    }
+    if (this.categoryConfig) {
+      this.pantry.setCategoryConfig(this.categoryConfig);
+    }
+    this.calculateIngredients();
+    this.categorize();
+  }
+  /**
+   * Returns the resulting pantry with quantities updated to reflect
+   * what was consumed by the shopping list's recipes.
+   * Returns undefined if no pantry was added.
+   * @returns The resulting Pantry, or undefined.
+   */
+  getPantry() {
+    return this.resultingPantry;
+  }
   /**
    * Sets the category configuration for the shopping list
    * and automatically categorize current ingredients from the list.
+   * Also propagates the configuration to the pantry if one is set.
    * @param config - The category configuration to parse.
    */
-  set_category_config(config) {
+  setCategoryConfig(config) {
     if (typeof config === "string")
-      this.category_config = new CategoryConfig(config);
-    else if (config instanceof CategoryConfig) this.category_config = config;
+      this.categoryConfig = new CategoryConfig(config);
+    else if (config instanceof CategoryConfig) this.categoryConfig = config;
     else throw new Error("Invalid category configuration");
+    if (this.pantry) {
+      this.pantry.setCategoryConfig(this.categoryConfig);
+    }
     this.categorize();
   }
   /**
@@ -2695,17 +4629,17 @@ var ShoppingList = class {
    * Will use the category config if any, otherwise all ingredients will be placed in the "other" category
    */
   categorize() {
-    if (!this.category_config) {
+    if (!this.categoryConfig) {
       this.categories = { other: this.ingredients };
       return;
     }
     const categories = { other: [] };
-    for (const category of this.category_config.categories) {
+    for (const category of this.categoryConfig.categories) {
       categories[category.name] = [];
     }
     for (const ingredient of this.ingredients) {
       let found = false;
-      for (const category of this.category_config.categories) {
+      for (const category of this.categoryConfig.categories) {
         for (const categoryIngredient of category.ingredients) {
           if (categoryIngredient.aliases.includes(ingredient.name)) {
             categories[category.name].push(ingredient);
@@ -2769,7 +4703,6 @@ var ShoppingCart = class {
   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
@@ -2833,8 +4766,27 @@ var ShoppingCart = class {
   getOptimumMatch(ingredient, options) {
     if (options.length === 0)
       throw new NoProductMatchError(ingredient.name, "noProduct");
-    if (!ingredient.quantityTotal)
+    if (!ingredient.quantities || ingredient.quantities.length === 0)
       throw new NoProductMatchError(ingredient.name, "noQuantity");
+    const allPlainEntries = [];
+    for (const q of ingredient.quantities) {
+      if ("and" in q) {
+        allPlainEntries.push({ and: q.and });
+      } else {
+        const entry = {
+          quantity: q.quantity,
+          ...q.unit && { unit: q.unit },
+          ...q.equivalents && { equivalents: q.equivalents }
+        };
+        allPlainEntries.push(entry);
+      }
+    }
+    let quantityTotal;
+    if (allPlainEntries.length === 1) {
+      quantityTotal = allPlainEntries[0];
+    } else {
+      quantityTotal = { and: allPlainEntries };
+    }
     const normalizedOptions = options.map(
       (option) => ({
         ...option,
@@ -2850,10 +4802,10 @@ var ShoppingCart = class {
         })
       })
     );
-    const normalizedQuantityTotal = normalizeAllUnits(ingredient.quantityTotal);
+    const normalizedQuantityTotal = normalizeAllUnits(quantityTotal);
     function getOptimumMatchForQuantityParts(normalizedQuantities, normalizedOptions2, selection = []) {
       if (isAndGroup(normalizedQuantities)) {
-        for (const q of normalizedQuantities.entries) {
+        for (const q of normalizedQuantities.and) {
           const result = getOptimumMatchForQuantityParts(
             q,
             normalizedOptions2,
@@ -2862,7 +4814,7 @@ var ShoppingCart = class {
           selection.push(...result);
         }
       } else {
-        const alternativeUnitsOfQuantity = isOrGroup(normalizedQuantities) ? normalizedQuantities.entries : [normalizedQuantities];
+        const alternativeUnitsOfQuantity = isOrGroup(normalizedQuantities) ? normalizedQuantities.or : [normalizedQuantities];
         const solutions = [];
         const errors = /* @__PURE__ */ new Set();
         for (const alternative of alternativeUnitsOfQuantity) {
@@ -2877,12 +4829,12 @@ var ShoppingCart = class {
           alternative.quantity = scaledQuantity;
           const matchOptions = normalizedOptions2.filter(
             (option) => option.sizes.some(
-              (s) => areUnitsCompatible(alternative.unit, s.unit)
+              (s) => areUnitsGroupable(alternative.unit, s.unit)
             )
           );
           if (matchOptions.length > 0) {
             const findCompatibleSize = (option) => option.sizes.find(
-              (s) => areUnitsCompatible(alternative.unit, s.unit)
+              (s) => areUnitsGroupable(alternative.unit, s.unit)
             );
             if (matchOptions.length == 1) {
               const matchedOption = matchOptions[0];
@@ -2982,17 +4934,178 @@ var ShoppingCart = class {
     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 groupSubgroups = recipe.choices.ingredientGroups.get(item.group);
+    if (groupSubgroups && selectedIndex2 !== void 0 && selectedIndex2 < groupSubgroups.length) {
+      const selectedSubgroup = groupSubgroups[selectedIndex2];
+      return selectedSubgroup?.some((alt) => alt.itemId === item.id);
+    }
+    return false;
+  }
+  const selectedIndex = choices?.ingredientItems?.get(item.id);
+  return alternativeIndex === selectedIndex;
+}
+function isSectionActive(section, variant) {
+  if (!section.variants) return true;
+  const isDefault = variant === void 0 || variant === "*";
+  if (isDefault) {
+    return section.variants.includes("*");
+  }
+  return section.variants.includes(variant);
+}
+function isStepActive(step, variant) {
+  if (!step.variants) return true;
+  const isDefault = variant === void 0 || variant === "*";
+  if (isDefault) {
+    return step.variants.includes("*");
+  }
+  return step.variants.includes(variant);
+}
+function getEffectiveChoices(recipe, variant) {
+  const choices = { variant };
+  if (variant === void 0 || variant === "*") return choices;
+  const variantLower = variant.toLowerCase();
+  for (const [itemId, alternatives] of recipe.choices.ingredientItems) {
+    const matchIdx = alternatives.findIndex(
+      (alt) => alt.note && alt.note.toLowerCase().includes(variantLower)
+    );
+    if (matchIdx >= 0) {
+      if (!choices.ingredientItems) choices.ingredientItems = /* @__PURE__ */ new Map();
+      choices.ingredientItems.set(itemId, matchIdx);
+    }
+  }
+  for (const [groupId, subgroups] of recipe.choices.ingredientGroups) {
+    const matchIdx = subgroups.findIndex(
+      (sg) => sg.some(
+        (alt) => alt.note && alt.note.toLowerCase().includes(variantLower)
+      )
+    );
+    if (matchIdx >= 0) {
+      if (!choices.ingredientGroups) choices.ingredientGroups = /* @__PURE__ */ new Map();
+      choices.ingredientGroups.set(groupId, matchIdx);
+    }
+  }
+  return choices;
+}
 export {
   CategoryConfig,
   NoProductCatalogForCartError,
   NoShoppingListForCartError,
+  Pantry,
   ProductCatalog,
   Recipe,
   Section,
   ShoppingCart,
-  ShoppingList
+  ShoppingList,
+  convertQuantityToSystem,
+  formatExtendedQuantity,
+  formatItemQuantity,
+  formatNumericValue,
+  formatQuantity,
+  formatQuantityWithUnit,
+  formatSingleValue,
+  formatUnit,
+  getEffectiveChoices,
+  hasAlternatives,
+  isAlternativeSelected,
+  isAndGroup,
+  isGroupedItem,
+  isSectionActive,
+  isSimpleGroup,
+  isStepActive,
+  renderFractionAsVulgar
 };
 /* v8 ignore else -- @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 next 4 -- @preserve: defensive guard; regex always matches */
+// v8 ignore if -- @preserve: defensive type guard
 /* v8 ignore if -- @preserve */
+// v8 ignore next -- @preserve
+// v8 ignore else -- @preserve: text quantities never reach the equivalence path
+// v8 ignore else --@preserve: defensive type guard
+// v8 ignore else -- @preserve: detection if
+/* v8 ignore else -- @preserve: only act when there are matches */
+/* v8 ignore else -- @preserve: initialization pattern */
 //# sourceMappingURL=index.js.map